@hilbras/omninode 1.0.0 → 2.0.0-alpha.10

package/dist/index.js

@@ -1,3 +1,12 @@
+// src/types/task.ts
+var TERMINAL_TASK_STATUSES = [
+  "completed",
+  "failed",
+  "timed_out",
+  "cancelled",
+  "partially_completed"
+];
+
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
   code;
@@ -116,6 +125,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()
@@ -131,6 +141,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({
@@ -175,7 +190,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({
@@ -257,7 +274,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
         }
       } : {}
     },
@@ -288,6 +306,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
@@ -305,6 +324,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
   };
 }
@@ -375,57 +399,200 @@ 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 };
 }
 
+// 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 isNetworkError(error) {
+  return error instanceof TypeError || typeof error?.cause === "object" && error instanceof Error && !error.code;
+}
+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;
@@ -434,22 +601,44 @@ var OpenAICompatibleProvider = class {
         skipped += 1;
         continue;
       }
-      models.push({
-        provider: this.config.name,
-        id: entry.id,
-        displayName: entry.id,
-        status: "available",
-        metadata: {
-          ...typeof entry.owned_by === "string" ? { ownedBy: entry.owned_by } : {},
-          ...typeof entry.created === "number" ? { createdAt: entry.created } : {}
-        }
-      });
+      models.push(this.toModelInfo(entry));
     }
     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(entry) {
+    const parameters = Array.isArray(entry.supported_parameters) ? entry.supported_parameters.filter((p) => typeof p === "string") : void 0;
+    const contextWindow = typeof entry.context_length === "number" ? entry.context_length : typeof entry.context_window === "number" ? entry.context_window : void 0;
+    const inputTypes = normalizeModalities(entry.input_modalities);
+    const outputTypes = normalizeModalities(entry.output_modalities);
+    return {
+      provider: this.config.name,
+      id: entry.id,
+      displayName: entry.id,
+      ...typeof entry.name === "string" ? { name: entry.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 entry.owned_by === "string" ? { ownedBy: entry.owned_by } : {},
+        ...typeof entry.created === "number" ? { createdAt: entry.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 {
@@ -479,27 +668,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 : [];
@@ -521,6 +718,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(/\/+$/, "");
 }
@@ -535,14 +807,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 }
@@ -555,11 +819,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();
@@ -664,19 +950,431 @@ var ModelRegistry = class {
 
 // 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 buildHello(descriptor) {
+  return envelope("HELLO", descriptor, { agentId: descriptor.name });
+}
+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;
+};
+async function decodeStream(session, chunk) {
+  const decoded = session.decoder.push(chunk);
+  for (const result of decoded) {
+    await session.handle(result);
+  }
+  return session.pendingAnswers.splice(0);
+}
+function requireCompletion(session) {
+  if (session.errorMessage !== void 0) {
+    throw new ProtocolError(session.errorMessage);
+  }
+}
+
+// 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}`];
@@ -697,18 +1395,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;
@@ -737,40 +1436,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") {
@@ -804,7 +1536,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;
@@ -812,7 +1556,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,
@@ -827,14 +1571,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) }
           });
         });
       });
@@ -843,67 +1587,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;
@@ -924,6 +1718,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();
@@ -939,14 +1767,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.`);
@@ -987,40 +1816,54 @@ function buildRoleRegistry(config) {
   return registry;
 }
 
-// src/tasks/store.ts
+// src/persistence/json-file-store.ts
 import { mkdir, readFile, rename, writeFile } from "fs/promises";
 import { dirname } from "path";
-var FileTaskStore = class {
+var JsonFileStore = class {
   filePath;
-  /**
-   * Read-modify-write operations are serialized: parallel pipeline tasks
-   * would otherwise race on the JSON file (last writer wins).
-   */
+  schemaVersion;
+  onCorrupt;
+  log;
   queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/tasks.json`;
+  constructor(options) {
+    this.filePath = `${options.directory ?? `${process.cwd()}/.omninode`}/${options.fileName}`;
+    this.schemaVersion = options.schemaVersion ?? 1;
+    this.onCorrupt = options.onCorrupt;
+    this.log = logger.child({ component: "persistence", file: options.fileName });
   }
-  async save(task) {
-    return this.synchronized(async () => {
-      const tasks = await this.load();
-      const index = tasks.findIndex((t) => t.id === task.id);
-      if (index >= 0) tasks[index] = task;
-      else tasks.push(task);
-      await this.write(tasks);
-    });
+  get path() {
+    return this.filePath;
   }
-  async get(id) {
-    return this.synchronized(async () => {
-      const tasks = await this.load();
-      return tasks.find((t) => t.id === id);
-    });
+  /** All items, or [] when missing/corrupt. */
+  async readAll() {
+    let raw;
+    try {
+      raw = await readFile(this.filePath, "utf8");
+    } catch {
+      return [];
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed;
+      if (parsed !== null && typeof parsed === "object" && Array.isArray(parsed.items)) {
+        return parsed.items;
+      }
+      throw new Error("persisted file has an unrecognized shape");
+    } catch (error) {
+      this.log.warn(`Treating ${this.filePath} as empty \u2014 it could not be parsed.`);
+      this.onCorrupt?.(this.filePath, error);
+      return [];
+    }
   }
-  async list(filter = {}) {
-    return this.synchronized(async () => {
-      const tasks = await this.load();
-      return tasks.filter((task) => filter.status ? task.status === filter.status : true).filter((task) => filter.project ? task.project === filter.project : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    });
+  async writeAll(items) {
+    const document = { schemaVersion: this.schemaVersion, items };
+    const tmp = `${this.filePath}.tmp`;
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await writeFile(tmp, `${JSON.stringify(document, null, 2)}
+`, "utf8");
+    await rename(tmp, this.filePath);
   }
+  /** Serializes an async operation against this file. */
   synchronized(operation) {
     const result = this.queue.then(operation, operation);
     this.queue = result.then(
@@ -1029,21 +1872,37 @@ var FileTaskStore = class {
     );
     return result;
   }
-  async load() {
-    try {
-      const raw = await readFile(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
+  /** Read-modify-write helper: applies `mutate` to the current items. */
+  async mutate(mutate) {
+    return this.synchronized(async () => {
+      const items = await this.readAll();
+      const [next, result] = await mutate(items);
+      await this.writeAll(next);
+      return result;
+    });
+  }
+};
+
+// src/tasks/store.ts
+var FileTaskStore = class extends JsonFileStore {
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "tasks.json" });
+  }
+  save(task) {
+    return this.mutate((tasks) => {
+      const index = tasks.findIndex((t) => t.id === task.id);
+      if (index >= 0) tasks[index] = task;
+      else tasks.push(task);
+      return [tasks, void 0];
+    });
   }
-  async write(tasks) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir(dirname(this.filePath), { recursive: true });
-    await writeFile(tmp, `${JSON.stringify(tasks, null, 2)}
-`, "utf8");
-    await rename(tmp, this.filePath);
+  async get(id) {
+    const tasks = await this.readAll();
+    return tasks.find((t) => t.id === id);
+  }
+  async list(filter = {}) {
+    const tasks = await this.readAll();
+    return tasks.filter((task) => filter.status ? task.status === filter.status : true).filter((task) => filter.project ? task.project === filter.project : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
 };
 
@@ -1052,12 +1911,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;
@@ -1089,6 +1954,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 } : {},
@@ -1105,8 +1971,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.`);
@@ -1119,49 +1987,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);
@@ -1174,13 +2082,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;
@@ -1212,10 +2121,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);
@@ -1236,6 +2149,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";
@@ -1260,10 +2186,10 @@ var FileAuditLog = class {
   }
   /** Recent events, oldest first; used by the CLI. */
   async recent(limit = 20) {
-    const { readFile: readFile6 } = await import("fs/promises");
+    const { readFile: readFile2 } = await import("fs/promises");
     let raw;
     try {
-      raw = await readFile6(this.filePath, "utf8");
+      raw = await readFile2(this.filePath, "utf8");
     } catch {
       return [];
     }
@@ -1278,9 +2204,24 @@ 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
-import { mkdir as mkdir3, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname3 } from "path";
 var STOPWORDS = /* @__PURE__ */ new Set([
   "the",
   "and",
@@ -1337,29 +2278,42 @@ function relevanceScore(queryKeywords, entry) {
   }
   return overlap * 2 + tagMatches * 1.5;
 }
-var LocalMemoryProvider = class {
+var LocalMemoryProvider = class extends JsonFileStore {
   name = "local";
-  filePath;
-  queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/memory.json`;
-  }
-  async query(query) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      const filtered = entries.filter((entry) => query.scope ? entry.scope === query.scope : true).filter(
-        (entry) => query.tags && query.tags.length > 0 ? query.tags.every((tag) => (entry.tags ?? []).includes(tag)) : true
-      );
-      if (!query.text || query.text.trim().length === 0) {
-        return filtered.sort((a, b) => (b.updatedAt ?? b.createdAt ?? "").localeCompare(a.updatedAt ?? a.createdAt ?? "")).slice(0, query.limit ?? 10);
-      }
-      const queryKeywords = keywords(query.text);
-      return filtered.map((entry) => ({ entry, score: relevanceScore(queryKeywords, entry) })).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, query.limit ?? 10).map(({ entry }) => entry);
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "memory.json" });
+  }
+  metadata() {
+    return defaultMetadata(this.name, {
+      capabilities: ["retrieve", "store", "search", "categories", "tags"],
+      relevanceRanking: true,
+      backend: { kind: "json-file", deterministicScoring: true }
     });
   }
-  async write(entry) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
+  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(entry) {
+    return this.store(entry);
+  }
+  async retrieve(query) {
+    const entries = await this.readAll();
+    const filtered = entries.filter((entry) => query.scope ? entry.scope === query.scope : true).filter((entry) => query.category ? entry.category === query.category : true).filter(
+      (entry) => query.tags && query.tags.length > 0 ? query.tags.every((tag) => (entry.tags ?? []).includes(tag)) : true
+    );
+    if (!query.text || query.text.trim().length === 0) {
+      return filtered.sort((a, b) => (b.updatedAt ?? b.createdAt ?? "").localeCompare(a.updatedAt ?? a.createdAt ?? "")).slice(0, query.limit ?? 10);
+    }
+    const queryKeywords = keywords(query.text);
+    return filtered.map((entry) => ({ entry, score: relevanceScore(queryKeywords, entry) })).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, query.limit ?? 10).map(({ entry }) => entry);
+  }
+  store(entry) {
+    return this.mutate((entries) => {
       const index = entries.findIndex((e) => e.key === entry.key);
       const stamped = {
         ...entry,
@@ -1368,35 +2322,11 @@ var LocalMemoryProvider = class {
       };
       if (index >= 0) entries[index] = stamped;
       else entries.push(stamped);
-      await this.saveAll(entries);
+      return [entries, void 0];
     });
   }
   async count() {
-    return (await this.load()).length;
-  }
-  synchronized(operation) {
-    const result = this.queue.then(operation, operation);
-    this.queue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
-  }
-  async load() {
-    try {
-      const raw = await readFile2(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
-  }
-  async saveAll(entries) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir3(dirname3(this.filePath), { recursive: true });
-    await writeFile2(tmp, `${JSON.stringify(entries, null, 2)}
-`, "utf8");
-    await rename2(tmp, this.filePath);
+    return (await this.readAll()).length;
   }
 };
 
@@ -1413,11 +2343,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(entry) {
+    return this.store(entry);
+  }
+  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}.`);
@@ -1428,7 +2387,7 @@ var RememberaMemoryProvider = class {
     }
     return entries.map((entry) => this.toEntry(entry)).filter((entry) => entry !== void 0);
   }
-  async write(entry) {
+  async store(entry) {
     const { status } = await this.request(`${this.baseUrl}/api/memory`, entry);
     if (status !== 200 && status !== 201) {
       throw new MemoryError(`Remembera write returned HTTP ${status}.`);
@@ -1463,6 +2422,7 @@ var RememberaMemoryProvider = class {
       content: entry.content,
       scope: scope === "project" || scope === "role" || scope === "task" || scope === "knowledge" ? scope : "knowledge",
       ...Array.isArray(entry.tags) ? { tags: entry.tags.filter((t) => typeof t === "string") } : {},
+      ...typeof entry.category === "string" ? { category: entry.category } : {},
       ...typeof entry.createdAt === "string" ? { createdAt: entry.createdAt } : {},
       ...typeof entry.updatedAt === "string" ? { updatedAt: entry.updatedAt } : {}
     };
@@ -1493,57 +2453,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 entry of entries) {
-        byScope.set(entry.scope, [...byScope.get(entry.scope) ?? [], entry]);
-      }
-      const parts = [];
-      for (const scope of ["project", "task", "role", "knowledge"]) {
-        const scopeEntries = byScope.get(scope) ?? [];
-        if (scopeEntries.length === 0) continue;
-        const lines = scopeEntries.map((entry) => `- ${entry.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}`,
@@ -1554,18 +2511,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 entry of entries) {
+      byScope.set(entry.scope, [...byScope.get(entry.scope) ?? [], entry]);
+    }
+    const parts = [];
+    for (const scope of ["project", "task", "role", "knowledge"]) {
+      const scopeEntries = byScope.get(scope) ?? [];
+      if (scopeEntries.length === 0) continue;
+      const lines = scopeEntries.map((entry) => {
+        const category = entry.category ? `[${entry.category}] ` : "";
+        return `- ${category}${entry.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 };
   }
 };
 
@@ -1577,7 +2569,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
   });
@@ -1816,9 +2812,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(run) {
+    const current = await this.options.store.get(run.id);
+    await this.options.store.save({
+      ...run,
+      ...current?.cancellationRequested === true ? { cancellationRequested: true, cancellationRequestedAt: current.cancellationRequestedAt } : {}
+    });
+  }
   /** Structural + semantic validation (§27 Phase 5 — pipeline parser). */
   validate(def) {
     const ids = /* @__PURE__ */ new Set();
@@ -1918,18 +2928,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 run = {
       id: `run-${Date.now().toString(36)}-${randomBytes4(3).toString("hex")}`,
       pipelineId: def.id,
+      attempt: 1,
       objective,
       status: "running",
       startedAt: now,
       stepRuns: []
     };
     await this.options.store.save(run);
-    this.log.info(`Running pipeline ${def.id} as ${run.id}.`);
+    const liveTaskIds = /* @__PURE__ */ new Set();
+    this.activeRuns.set(run.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 ${run.id} (attempt ${run.attempt}).`);
     await this.options.audit?.record({
       at: (/* @__PURE__ */ new Date()).toISOString(),
       action: "pipeline.run.started",
@@ -1941,7 +2977,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(run.id);
+      if (persisted?.cancellationRequested === true) {
+        cancelled = true;
+        run.cancellationRequested = true;
+        run.cancellationRequestedAt = persisted.cancellationRequestedAt;
+        await this.activeRuns.get(run.id)?.cancelTasks();
+        for (const step of def.steps.filter((s) => pending.has(s.id))) {
+          const stepRun = { stepId: step.id, status: "cancelled" };
+          run.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))
       );
@@ -1958,7 +3009,8 @@ var PipelineEngine = class {
             ...role ? { role } : {},
             combinedContext: contextParts.join("\n\n"),
             reports: [...allReports],
-            pipelineRunId: run.id
+            pipelineRunId: run.id,
+            runId: run.id
           };
           return this.executeStep(step, ctx);
         })
@@ -1975,7 +3027,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 } : {}
@@ -1984,10 +3038,12 @@ ${contribution}`);
         options.onStep?.(stepRun);
       });
       run.reports = [...allReports];
-      await this.options.store.save(run);
+      await this.persist(run);
     }
-    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) {
@@ -2015,16 +3071,19 @@ ${contribution}`);
         run.reports = collected;
       }
     }
+    const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.activeRuns.delete(run.id);
     const finished = {
       ...run,
       status: finalStatus,
-      finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      finishedAt,
+      attempts: [...run.attempts ?? [], { attempt: run.attempt, startedAt: run.startedAt ?? finishedAt, finishedAt, status: finalStatus }],
       ...run.reports !== void 0 && run.reports.length > 0 ? { reports: run.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(),
@@ -2034,6 +3093,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 run = await this.options.store.get(runId);
+    if (!run) {
+      throw new PipelineError("PIPELINE_NOT_FOUND", `Pipeline run "${runId}" does not exist.`);
+    }
+    await this.options.store.save({
+      ...run,
+      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);
   }
@@ -2057,9 +3133,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) {
@@ -2092,7 +3175,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";
@@ -2102,16 +3188,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({
@@ -2120,10 +3215,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`,
@@ -2239,114 +3337,44 @@ function createDefaultChatFn(providers) {
 }
 
 // src/pipelines/store.ts
-import { mkdir as mkdir4, readFile as readFile3, rename as rename3, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname4 } from "path";
-var FilePipelineRunStore = class {
-  filePath;
-  queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/pipelines.json`;
+var FilePipelineRunStore = class extends JsonFileStore {
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "pipelines.json" });
   }
-  async save(run) {
-    return this.synchronized(async () => {
-      const runs = await this.load();
+  save(run) {
+    return this.mutate((runs) => {
       const index = runs.findIndex((r) => r.id === run.id);
       if (index >= 0) runs[index] = run;
       else runs.push(run);
-      await this.write(runs);
+      return [runs, void 0];
     });
   }
   async get(id) {
-    return this.synchronized(async () => {
-      const runs = await this.load();
-      return runs.find((r) => r.id === id);
-    });
+    return (await this.readAll()).find((r) => r.id === id);
   }
   async list(filter = {}) {
-    return this.synchronized(async () => {
-      const runs = await this.load();
-      return runs.filter((run) => filter.pipelineId ? run.pipelineId === filter.pipelineId : true).filter((run) => filter.status ? run.status === filter.status : true).sort((a, b) => (a.startedAt ?? "").localeCompare(b.startedAt ?? ""));
-    });
-  }
-  synchronized(operation) {
-    const result = this.queue.then(operation, operation);
-    this.queue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
-  }
-  async load() {
-    try {
-      const raw = await readFile3(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
-  }
-  async write(runs) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir4(dirname4(this.filePath), { recursive: true });
-    await writeFile3(tmp, `${JSON.stringify(runs, null, 2)}
-`, "utf8");
-    await rename3(tmp, this.filePath);
+    return (await this.readAll()).filter((run) => filter.pipelineId ? run.pipelineId === filter.pipelineId : true).filter((run) => filter.status ? run.status === filter.status : true).sort((a, b) => (a.startedAt ?? "").localeCompare(b.startedAt ?? ""));
   }
 };
 
 // src/planner/store.ts
-import { mkdir as mkdir5, readFile as readFile4, rename as rename4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname5 } from "path";
-var FilePlanStore = class {
-  filePath;
-  queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/plans.json`;
+var FilePlanStore = class extends JsonFileStore {
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "plans.json" });
   }
-  async save(plan) {
-    return this.synchronized(async () => {
-      const plans = await this.load();
+  save(plan) {
+    return this.mutate((plans) => {
       const index = plans.findIndex((p) => p.id === plan.id);
       if (index >= 0) plans[index] = plan;
       else plans.push(plan);
-      await this.write(plans);
+      return [plans, void 0];
     });
   }
   async get(id) {
-    return this.synchronized(async () => {
-      const plans = await this.load();
-      return plans.find((p) => p.id === id);
-    });
+    return (await this.readAll()).find((p) => p.id === id);
   }
   async list(filter = {}) {
-    return this.synchronized(async () => {
-      const plans = await this.load();
-      return plans.filter((plan) => filter.pipelineRunId ? plan.pipelineRunId === filter.pipelineRunId : true).filter((plan) => filter.taskId ? plan.taskId === filter.taskId : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    });
-  }
-  synchronized(operation) {
-    const result = this.queue.then(operation, operation);
-    this.queue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
-  }
-  async load() {
-    try {
-      const raw = await readFile4(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
-  }
-  async write(plans) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir5(dirname5(this.filePath), { recursive: true });
-    await writeFile4(tmp, `${JSON.stringify(plans, null, 2)}
-`, "utf8");
-    await rename4(tmp, this.filePath);
+    return (await this.readAll()).filter((plan) => filter.pipelineRunId ? plan.pipelineRunId === filter.pipelineRunId : true).filter((plan) => filter.taskId ? plan.taskId === filter.taskId : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
 };
 
@@ -2373,6 +3401,94 @@ function buildPlanner(plannerConfig, chat, log = logger) {
 
 // src/reports/aggregate.ts
 import { randomBytes as randomBytes5 } from "crypto";
+
+// src/reports/schema.ts
+import { z as z3 } from "zod";
+var evidenceSchema = z3.union([
+  z3.string().transform((excerpt) => ({ kind: "observation", excerpt })),
+  z3.object({
+    kind: z3.enum(["file", "line", "url", "command", "observation", "artifact"]),
+    ref: z3.string().optional(),
+    line: z3.number().int().optional(),
+    excerpt: z3.string().optional(),
+    agent: z3.string().optional()
+  })
+]);
+var findingSchema = z3.object({
+  id: z3.string().min(1),
+  title: z3.string().min(1),
+  detail: z3.string().default(""),
+  description: z3.string().optional(),
+  severity: z3.enum(["info", "low", "medium", "high", "critical"]).optional(),
+  confidence: z3.enum(["low", "medium", "high"]).optional(),
+  severityBySource: z3.record(z3.enum(["info", "low", "medium", "high", "critical"])).optional(),
+  confidenceBySource: z3.record(z3.enum(["low", "medium", "high"])).optional(),
+  recommendations: z3.array(z3.string()).optional(),
+  evidence: z3.array(evidenceSchema).optional(),
+  location: z3.string().optional(),
+  tags: z3.array(z3.string()).optional(),
+  source: z3.object({ agent: z3.string().optional(), reportId: z3.string().optional(), pipelineRunId: z3.string().optional() }).optional(),
+  recommendation: z3.string().optional()
+});
+var artifactSchema = z3.object({
+  kind: z3.enum(["file", "patch", "log", "screenshot", "document", "data"]),
+  ref: z3.string().min(1),
+  description: z3.string().optional(),
+  mediaType: z3.string().optional(),
+  bytes: z3.number().int().optional()
+});
+var reportSchema = z3.object({
+  id: z3.string().min(1),
+  taskId: z3.string().min(1),
+  agent: z3.string().min(1),
+  agentId: z3.string().optional(),
+  pipelineRunId: z3.string().optional(),
+  model: z3.string().optional(),
+  summary: z3.string(),
+  findings: z3.array(findingSchema),
+  recommendations: z3.array(z3.string()),
+  confidence: z3.enum(["low", "medium", "high"]).optional(),
+  evidence: z3.array(evidenceSchema).optional(),
+  artifacts: z3.array(artifactSchema).optional(),
+  createdAt: z3.string().min(1),
+  metadata: z3.record(z3.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
+  );
+}
+function normalizeFinding(finding) {
+  return {
+    ...finding,
+    description: finding.description ?? finding.detail,
+    evidence: normalizeEvidence(finding.evidence)
+  };
+}
+
+// src/reports/aggregate.ts
 var SEVERITY_RANK2 = {
   info: 0,
   low: 1,
@@ -2394,7 +3510,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)}-${randomBytes5(3).toString("hex")}`,
     title: options.objective !== void 0 ? truncate2(options.objective, 120) : "Combined report",
@@ -2403,10 +3524,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_RANK2[a] - SEVERITY_RANK2[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) {
@@ -2419,10 +3587,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_RANK2[finding.severity] > SEVERITY_RANK2[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({
@@ -2431,7 +3611,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) {
@@ -2513,6 +3697,7 @@ function extractReportFromText(raw, meta) {
     id: `${meta.taskId}-f-${index + 1}`,
     title: truncate3(text, 120),
     detail: text,
+    description: text,
     severity: guessSeverity(text)
   }));
   return {
@@ -2523,7 +3708,8 @@ function extractReportFromText(raw, meta) {
     summary,
     findings,
     recommendations: recommendationTexts.map((t) => truncate3(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()
   };
 }
@@ -2539,27 +3725,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) {
@@ -2582,84 +3787,39 @@ var ReportService = class {
 };
 
 // src/reports/store.ts
-import { mkdir as mkdir6, readFile as readFile5, rename as rename5, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname6 } from "path";
-var FileReportStore = class {
-  filePath;
-  queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/reports.json`;
+var FileReportStore = class extends JsonFileStore {
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "reports.json" });
   }
   async saveReports(reports) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
+    await this.mutate((entries) => {
       for (const report of reports) {
-        const index = entries.findIndex(
-          (e) => e.kind === "report" && e.report.id === report.id
-        );
+        const index = entries.findIndex((e) => e.kind === "report" && e.report.id === report.id);
         const entry = { kind: "report", report };
         if (index >= 0) entries[index] = entry;
         else entries.push(entry);
       }
-      await this.write(entries);
+      return [entries, void 0];
     });
   }
   async listReports(filter = {}) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      return entries.filter((e) => e.kind === "report").map((e) => e.report).filter((report) => filter.taskId ? report.taskId === filter.taskId : true).filter((report) => filter.agent ? report.agent === filter.agent : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    });
+    return (await this.readAll()).filter((e) => e.kind === "report").map((e) => e.report).filter((report) => filter.taskId ? report.taskId === filter.taskId : true).filter((report) => filter.agent ? report.agent === filter.agent : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
   async saveCombined(combined) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      const index = entries.findIndex(
-        (e) => e.kind === "combined" && e.combined.id === combined.id
-      );
+    await this.mutate((entries) => {
+      const index = entries.findIndex((e) => e.kind === "combined" && e.combined.id === combined.id);
       const entry = { kind: "combined", combined };
       if (index >= 0) entries[index] = entry;
       else entries.push(entry);
-      await this.write(entries);
+      return [entries, void 0];
     });
   }
   async getCombined(id) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      const found = entries.find((e) => e.kind === "combined" && e.combined.id === id);
-      return found?.kind === "combined" ? found.combined : void 0;
-    });
+    const found = (await this.readAll()).find((e) => e.kind === "combined" && e.combined.id === id);
+    return found?.kind === "combined" ? found.combined : void 0;
   }
   async listCombined(filter = {}) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      return entries.filter((e) => e.kind === "combined").map((e) => e.combined).filter(
-        (combined) => filter.pipelineRunId ? combined.pipelineRunId === filter.pipelineRunId : true
-      ).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    });
-  }
-  synchronized(operation) {
-    const result = this.queue.then(operation, operation);
-    this.queue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
-  }
-  async load() {
-    try {
-      const raw = await readFile5(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
-  }
-  async write(entries) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir6(dirname6(this.filePath), { recursive: true });
-    await writeFile5(tmp, `${JSON.stringify(entries, null, 2)}
-`, "utf8");
-    await rename5(tmp, this.filePath);
+    return (await this.readAll()).filter((e) => e.kind === "combined").map((e) => e.combined).filter((combined) => filter.pipelineRunId ? combined.pipelineRunId === filter.pipelineRunId : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
 };
 
@@ -2672,7 +3832,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
   });
@@ -2691,36 +3855,69 @@ function buildPipelineEngine(config, log = logger) {
   });
 }
 
+// src/persistence/index.ts
+var ProjectStores = class {
+  tasks;
+  pipelineRuns;
+  reports;
+  plans;
+  memory;
+  audit;
+  constructor(directory = `${process.cwd()}/.omninode`) {
+    this.tasks = new FileTaskStore(directory);
+    this.pipelineRuns = new FilePipelineRunStore(directory);
+    this.reports = new FileReportStore(directory);
+    this.plans = new FilePlanStore(directory);
+    this.memory = new LocalMemoryProvider(directory);
+    this.audit = new FileAuditLog(directory);
+  }
+};
+
 // src/version.ts
-var OMNINODE_VERSION = "1.0.0";
+var OMNINODE_VERSION = "2.0.0-alpha.10";
 export {
+  AgentAdapterRegistry,
   AgentError,
   AgentRegistry,
   ConfigError,
   ConsoleLogSink,
+  DEFAULT_MAX_OUTPUT_BYTES,
   FileAuditLog,
   FilePipelineRunStore,
+  FilePlanStore,
   FileReportStore,
   FileTaskStore,
+  HeuristicPlanner,
+  JsonFileStore,
   LocalMemoryProvider,
   Logger,
+  MAX_CONTEXT_CHARS,
+  MAX_MESSAGE_BYTES,
   MemoryError,
   MemoryService,
+  ModelPlanner,
   ModelRegistry,
   OMNINODE_VERSION,
   OPENAI_COMPATIBLE_TYPES,
   OmniHilbrasProvider,
   OmniNodeError,
   OpenAICompatibleProvider,
+  PROTOCOL_V2,
   PipelineEngine,
   PipelineError,
   PlannerError,
   ProcessAgent,
+  ProcessAgentAdapter,
+  ProjectStores,
+  ProtocolDecoder,
   ProtocolError,
+  ProtocolSession,
   ProviderError,
   RememberaMemoryProvider,
   ReportService,
   RoleRegistry,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  TERMINAL_TASK_STATUSES,
   TaskEngine,
   TaskError,
   agentConfigSchema,
@@ -2728,7 +3925,12 @@ export {
   appConfigSchema,
   authHeaders,
   buildAgentRegistry,
+  buildChildEnv,
+  buildHello,
+  buildHelloAck,
   buildPipelineEngine,
+  buildPlanner,
+  buildPlannerContext,
   buildRoleRegistry,
   composeTaskText,
   createAgent,
@@ -2736,23 +3938,52 @@ export {
   createMemoryProvider,
   createProvider,
   createTaskEngine,
+  decodeMessage,
+  decodeStream,
+  defaultMetadata,
   defaultProjectConfigYaml,
+  defaultSearch,
+  describeExit,
+  detectConflicts,
+  encodeMessage,
+  envelope,
   expandEnvRefs,
+  extractMessage,
   extractReportFromText,
   findConfigFile,
+  isNetworkError,
   isOmniNodeError,
+  isRetryable,
+  isSupportedProtocol,
+  isTimeoutError,
   keywords,
+  killTree,
+  kindFromStatus,
   loadConfig,
   logger,
+  newMessageId,
+  normalizeEvidence,
+  normalizeFinding,
+  parseHello,
+  parsePlanJson,
+  parseRetryAfter,
   pipelineConfigSchema,
   pipelineStepConfigSchema,
   plannerConfigSchema,
   projectConfigSchema,
   providerConfigSchema,
+  providerHttpError,
+  providerTransportError,
   registryKey,
   requestJson,
+  requireCompletion,
   resolveApiKey,
+  resolveEnvPolicy,
   roleConfigSchema,
-  similar
+  sanitizeChunk,
+  similar,
+  validateEnvelope,
+  validateReport,
+  validateWorkingDirectory
 };
 //# sourceMappingURL=index.js.map