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

package/dist/index.js

@@ -1,12 +1,3 @@
-// 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;
@@ -80,16 +71,19 @@ var ConsoleLogSink = class {
 };
 var Logger = class _Logger {
   level;
+  format;
   sink;
   context;
   constructor(options = {}) {
     this.level = options.level ?? "info";
+    this.format = options.format ?? "text";
     this.sink = options.sink ?? new ConsoleLogSink();
     this.context = options.context ?? {};
   }
   child(context) {
     return new _Logger({
       level: this.level,
+      format: this.format,
       sink: this.sink,
       context: { ...this.context, ...context }
     });
@@ -108,8 +102,13 @@ var Logger = class _Logger {
   }
   log(level, message, data) {
     if (LEVEL_ORDER[level] < LEVEL_ORDER[this.level]) return;
-    const parts = [(/* @__PURE__ */ new Date()).toISOString(), level.toUpperCase(), message];
+    const at = (/* @__PURE__ */ new Date()).toISOString();
     const merged = { ...this.context, ...data };
+    if (this.format === "json") {
+      this.sink.write(level, JSON.stringify({ at, level, message, ...merged }));
+      return;
+    }
+    const parts = [at, level.toUpperCase(), message];
     if (Object.keys(merged).length > 0) {
       parts.push(JSON.stringify(merged));
     }
@@ -117,6 +116,10 @@ var Logger = class _Logger {
   }
 };
 var logger = new Logger();
+function configureLogger(options) {
+  if (options.level !== void 0) logger.level = options.level;
+  if (options.format !== void 0) logger.format = options.format;
+}
 
 // src/config/schema.ts
 import { z } from "zod";
@@ -125,6 +128,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()
@@ -140,6 +144,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({
@@ -160,7 +169,9 @@ var pipelineStepConfigSchema = z.object({
   model: z.string().optional(),
   depends_on: z.array(z.string()).optional(),
   retries: z.number().int().min(0).max(10).optional(),
-  condition: z.enum(["always", "on-success", "on-failure"]).optional()
+  condition: z.enum(["always", "on-success", "on-failure"]).optional(),
+  /** Constraints passed to the planner for plan steps (§15). */
+  constraints: z.array(z.string()).optional()
 }).strict();
 var pipelineConfigSchema = z.object({
   id: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, "pipeline id must be kebab-case"),
@@ -184,14 +195,135 @@ 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({
+  /** Active profile; overlays live under `profiles` (§16). */
+  profile: z.string().min(1).optional(),
+  /** Named partial overlays, e.g. development/production/testing. */
+  profiles: z.record(z.unknown()).optional(),
   project: projectConfigSchema,
-  logging: z.object({ level: z.enum(["debug", "info", "warn", "error"]) }).strict().optional()
+  logging: z.object({
+    level: z.enum(["debug", "info", "warn", "error"]),
+    format: z.enum(["text", "json"]).optional()
+  }).strict().optional()
 }).strict();
 
+// src/config/secrets.ts
+var SAFE_KEY_SUFFIXES = ["_env", "_env_var", "_file", "_path", "_ref", "_id", "_url", "_command"];
+var SECRET_KEY = /^\s*([A-Za-z0-9_-]*(?:api[_-]?key|token|password|passwd|secret|credential)[A-Za-z0-9_-]*)\s*:\s*(.*)$/i;
+var SAFE_VALUE = /^\s*(?:\$\{[^}]*\}|\$[A-Z_][A-Z0-9_]*|<[^>]*>|""|''|null|~)\s*$/i;
+function scanForInlineSecrets(source) {
+  const findings = [];
+  source.split("\n").forEach((line, index) => {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#")) return;
+    const match = SECRET_KEY.exec(line);
+    if (!match) return;
+    const key = match[1] ?? "";
+    const rawValue = (match[2] ?? "").trim().replace(/,\s*$/, "");
+    const keyIsReference = SAFE_KEY_SUFFIXES.some((suffix) => key.toLowerCase().endsWith(suffix));
+    if (keyIsReference) return;
+    const value = rawValue.replace(/^["']|["']$/g, "");
+    if (value.length === 0 || SAFE_VALUE.test(rawValue)) return;
+    if (value.length < 8) return;
+    findings.push({
+      line: index + 1,
+      key,
+      excerpt: `${key}: ${value.slice(0, 3)}\u2026 (${value.length} chars, redacted)`
+    });
+  });
+  return findings;
+}
+function describeSecretFindings(file, findings) {
+  const lines = findings.map((f) => `  line ${f.line}: ${f.excerpt}`).join("\n");
+  return `${file} appears to contain ${findings.length} inline secret(s):
+${lines}
+OmniNode never stores credentials in configuration. Replace each value with an environment-variable reference, e.g. api_key_env_var: MY_API_KEY.`;
+}
+
+// src/config/profiles.ts
+import { homedir } from "os";
+import path from "path";
+function userConfigPath(env = process.env) {
+  if (env.OMNINODE_USER_CONFIG) return env.OMNINODE_USER_CONFIG;
+  const home = env.HOME ?? homedir();
+  return path.join(home, ".omninode", "config.yaml");
+}
+function resolveProfile(input, env) {
+  if (env.OMNINODE_PROFILE) return env.OMNINODE_PROFILE;
+  if (typeof input.profile === "string" && input.profile.length > 0) return input.profile;
+  return "default";
+}
+function mergeConfig(base, overlay) {
+  if (!isPlainObject(base) || !isPlainObject(overlay)) {
+    return overlay === void 0 ? base : overlay;
+  }
+  const result = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    const existing = result[key];
+    if (Array.isArray(value)) {
+      result[key] = value;
+    } else if (isPlainObject(value) && isPlainObject(existing)) {
+      result[key] = mergeConfig(existing, value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asObject(value) {
+  return isPlainObject(value) ? value : {};
+}
+function applyEnvOverrides(input, env) {
+  const applied = [];
+  const config = mergeConfig(input, {});
+  if (env.OMNINODE_LOG_LEVEL) {
+    config.logging = { ...asObject(config.logging), level: env.OMNINODE_LOG_LEVEL };
+    applied.push("OMNINODE_LOG_LEVEL");
+  }
+  if (env.OMNINODE_LOG_FORMAT) {
+    config.logging = { ...asObject(config.logging), format: env.OMNINODE_LOG_FORMAT };
+    applied.push("OMNINODE_LOG_FORMAT");
+  }
+  const memoryProvider = env.OMNINODE_MEMORY_PROVIDER;
+  const memoryRequired = env.OMNINODE_MEMORY_REQUIRED;
+  if (memoryProvider || memoryRequired) {
+    const project = asObject(config.project);
+    config.project = {
+      ...project,
+      memory: {
+        ...asObject(project.memory ?? { provider: "local" }),
+        ...memoryProvider ? { provider: memoryProvider } : {},
+        ...memoryRequired ? { required: memoryRequired !== "false" } : {}
+      }
+    };
+    if (memoryProvider) applied.push("OMNINODE_MEMORY_PROVIDER");
+    if (memoryRequired) applied.push("OMNINODE_MEMORY_REQUIRED");
+  }
+  return { config, applied };
+}
+function applyDefaults(input) {
+  const applied = [];
+  const config = mergeConfig(input, {});
+  const logging = asObject(config.logging);
+  if (logging.level === void 0) {
+    config.logging = { ...logging, level: "info" };
+    applied.push("logging.level");
+  }
+  if (logging.format === void 0) {
+    config.logging = { ...asObject(config.logging), format: "text" };
+    applied.push("logging.format");
+  }
+  return { config, applied };
+}
+
 // src/config/loader.ts
 import { existsSync, readFileSync } from "fs";
 import { parse as parseYaml } from "yaml";
@@ -218,34 +350,132 @@ function expandEnvRefs(text, env, source = "config") {
     }
   );
 }
-function loadConfig(options = {}) {
+function loadConfigDetailed(options = {}) {
   const env = options.env ?? process.env;
-  const path = options.path ?? (options.directory ? findConfigFile(options.directory) : findConfigFile());
-  if (!path) {
+  const explicitPath = options.path;
+  let input = {};
+  let projectFile;
+  let userFile;
+  if (!explicitPath) {
+    const candidate = userConfigPath(env);
+    if (existsSync(candidate)) {
+      input = mergeConfig(input, readConfigDocument(candidate, env));
+      userFile = candidate;
+    }
+  }
+  const resolvedProject = explicitPath ?? (options.directory ? findConfigFile(options.directory) : findConfigFile());
+  if (resolvedProject) {
+    input = mergeConfig(input, readConfigDocument(resolvedProject, env));
+    projectFile = resolvedProject;
+  }
+  if (!projectFile && !userFile) {
     throw new ConfigError(
       "CONFIG_NOT_FOUND",
       "No omninode.yaml found. Run `omninode init` to create one, or pass an explicit path."
     );
   }
-  const raw = readFileSync(path, "utf8");
-  const expanded = expandEnvRefs(raw, env, path);
-  let data;
-  try {
-    data = parseYaml(expanded);
-  } catch (error) {
-    throw new ConfigError("CONFIG_INVALID", `Failed to parse ${path}.`, { cause: error });
+  const profile = options.profile ?? resolveProfile(input, env);
+  const overlay = input.profiles?.[profile];
+  if (overlay !== void 0) {
+    const { profiles: _drop, ...base } = input;
+    input = mergeConfig(base, overlay);
+  } else if (profile !== "default" && profile !== "") {
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `Profile "${profile}" is not defined in this configuration (known: ${Object.keys(input.profiles ?? {}).join(", ") || "none"}).`
+    );
   }
-  const parsed = appConfigSchema.safeParse(data);
+  const withEnv = applyEnvOverrides(input, env);
+  const withDefaults = applyDefaults(withEnv.config);
+  const parsed = appConfigSchema.safeParse(withDefaults.config);
   if (!parsed.success) {
     const issues = parsed.error.issues.map((issue) => {
-      const location = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      const location = issue.path.join(".") || "(root)";
       return `${location}: ${issue.message}`;
     });
-    throw new ConfigError("CONFIG_INVALID", `Invalid configuration in ${path}.`, {
-      details: { issues }
-    });
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `Invalid configuration:
+  ${issues.join("\n  ")}`,
+      { details: { issues } }
+    );
   }
-  return toAppConfig(parsed.data);
+  assertUniqueNames(parsed.data);
+  return {
+    config: toAppConfig(parsed.data),
+    sources: {
+      ...projectFile !== void 0 ? { projectFile } : {},
+      ...userFile !== void 0 ? { userFile } : {},
+      profile,
+      envOverrides: withEnv.applied,
+      defaults: withDefaults.applied
+    }
+  };
+}
+function assertUniqueNames(data) {
+  const groups = [
+    ["provider", data.project.providers.map((p) => p.name)],
+    ["agent", data.project.agents.map((a) => a.name)],
+    ["role", data.project.roles.map((r) => r.id)],
+    ["pipeline", data.project.pipelines.map((p) => p.id)]
+  ];
+  for (const [kind, names] of groups) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const name of names) {
+      if (seen.has(name)) {
+        throw new ConfigError(
+          "CONFIG_INVALID",
+          `Duplicate ${kind} name "${name}" \u2014 every ${kind} must have a unique name.`
+        );
+      }
+      seen.add(name);
+    }
+  }
+}
+function readConfigDocument(path2, optionsEnv) {
+  const raw = readFileSync(path2, "utf8");
+  const secretFindings = scanForInlineSecrets(raw);
+  if (secretFindings.length > 0) {
+    throw new ConfigError("CONFIG_INVALID", describeSecretFindings(path2, secretFindings));
+  }
+  const expanded = expandEnvRefs(raw, optionsEnv, path2);
+  try {
+    return parseYaml(expanded);
+  } catch (error) {
+    throw new ConfigError("CONFIG_INVALID", `Failed to parse ${path2}.`, { cause: error });
+  }
+}
+function loadConfig(options = {}) {
+  return loadConfigDetailed(options).config;
+}
+function configDiagnostics(config) {
+  const notes = [];
+  for (const provider of config.project.providers) {
+    if (!provider.apiKeyEnvVar && provider.baseUrl.startsWith("https://")) {
+      notes.push(
+        `Provider "${provider.name}": API key reference is missing \u2014 add api_key_env_var: <ENV_VAR> unless this endpoint is intentionally keyless.`
+      );
+    }
+  }
+  for (const agent of config.project.agents) {
+    if (!agent.command && agent.integration !== "custom") {
+      notes.push(`Agent "${agent.name}": no command configured \u2014 the process adapter needs one.`);
+    }
+    if (agent.allowExternalCwd) {
+      notes.push(`Agent "${agent.name}": may run outside the project root (allow_external_cwd).`);
+    }
+  }
+  for (const pipeline of config.project.pipelines) {
+    const ids = new Set(pipeline.steps.map((s) => s.id));
+    for (const step of pipeline.steps) {
+      for (const dep of step.dependsOn ?? []) {
+        if (!ids.has(dep)) {
+          notes.push(`Pipeline "${pipeline.id}": step "${step.id}" depends on unknown step "${dep}".`);
+        }
+      }
+    }
+  }
+  return notes;
 }
 function toAppConfig(yaml) {
   return {
@@ -266,7 +496,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
         }
       } : {}
     },
@@ -287,7 +518,8 @@ function toPipelineDefinition(raw) {
       model: step.model,
       dependsOn: step.depends_on,
       retries: step.retries,
-      condition: step.condition
+      condition: step.condition,
+      constraints: step.constraints
     }))
   };
 }
@@ -297,6 +529,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
@@ -314,6 +547,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
   };
 }
@@ -384,57 +622,213 @@ 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;
+  audit;
+  constructor(config, log = logger, env = process.env, audit) {
+    this.audit = audit;
     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) {
+        await this.recordProviderError("listModels", error);
+        throw error;
+      }
+      const normalized = providerTransportError({
+        provider: this.config.name,
+        operation: "listModels",
+        cause: error
+      });
+      await this.recordProviderError("listModels", normalized);
+      throw normalized;
     }
+    const { status, body } = response;
     if (status !== 200) {
-      throw unavailable(this.config, `Model discovery returned HTTP ${status}.`, status);
+      const httpError = providerHttpError({
+        provider: this.config.name,
+        operation: "listModels",
+        status,
+        body
+      });
+      await this.recordProviderError("listModels", httpError);
+      throw httpError;
     }
+    return response;
+  }
+  async listModels() {
+    const body = await this.rawModelsResponse();
     const entries = extractModelEntries(body, this.config);
     const models = [];
     let skipped = 0;
@@ -443,22 +837,59 @@ 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);
+  }
+  /** Provider errors are part of the audit trail (§14 correlation, §18 observability). */
+  async recordProviderError(operation, error) {
+    await this.audit?.record({
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      action: "provider.error",
+      id: this.providerId,
+      providerId: this.providerId,
+      detail: {
+        operation,
+        code: error.code,
+        kind: error.details?.kind,
+        message: error.message
+      }
+    });
+  }
   async healthCheck() {
     const lastCheckedAt = (/* @__PURE__ */ new Date()).toISOString();
     try {
@@ -488,27 +919,42 @@ 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 } : {}
+    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) {
+        await this.recordProviderError("chat", error);
+        throw error;
       }
-    });
-    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 } }
-      );
+      const normalized = providerTransportError({ provider: this.config.name, operation: "chat", cause: error });
+      await this.recordProviderError("chat", normalized);
+      throw normalized;
     }
+    const { status, body } = response;
     if (status !== 200) {
-      throw unavailable(this.config, `Chat completion returned HTTP ${status}.`, status);
+      const httpError = providerHttpError({
+        provider: this.config.name,
+        operation: "chat",
+        status,
+        body,
+        ...status === 404 ? {
+          code: "MODEL_NOT_FOUND"
+        } : {}
+      });
+      await this.recordProviderError("chat", httpError);
+      throw httpError;
     }
     const payload = body;
     const choices = Array.isArray(payload.choices) ? payload.choices : [];
@@ -530,6 +976,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(/\/+$/, "");
 }
@@ -544,14 +1065,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 }
@@ -564,11 +1077,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();
@@ -612,13 +1147,32 @@ var OPENAI_COMPATIBLE_TYPES = [
   "local",
   "custom"
 ];
-function createProvider(config) {
+function assertProviderConfig(config) {
+  if (!config.name || config.name.trim().length === 0) {
+    throw new ConfigError("CONFIG_INVALID", "Provider name must not be empty.");
+  }
+  if (!config.baseUrl || config.baseUrl.trim().length === 0) {
+    throw new ConfigError("CONFIG_INVALID", `Provider "${config.name}" needs a baseUrl.`);
+  }
+  try {
+    new URL(config.baseUrl);
+  } catch {
+    throw new ConfigError("CONFIG_INVALID", `Provider "${config.name}" has an invalid baseUrl: ${config.baseUrl}`);
+  }
+}
+function createProvider(config, options = {}) {
+  assertProviderConfig(config);
+  const shared = {
+    ...options.env !== void 0 ? { env: options.env } : {},
+    ...options.audit !== void 0 ? { audit: options.audit } : {}
+  };
   if (config.type === "omnihilbras") {
-    return new OmniHilbrasProvider(config);
+    return new OmniHilbrasProvider(config, void 0, options.env, options.audit);
   }
   if (OPENAI_COMPATIBLE_TYPES.includes(config.type)) {
-    return new OpenAICompatibleProvider(config);
+    return new OpenAICompatibleProvider(config, void 0, options.env, options.audit);
   }
+  void shared;
   throw new OmniNodeError("NOT_IMPLEMENTED", `Provider type "${config.type}" has no adapter yet.`);
 }
 
@@ -672,20 +1226,420 @@ var ModelRegistry = class {
 };
 
 // src/agents/process/index.ts
-import { spawn } from "child_process";
+import { spawn } from "child_process";
+
+// 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;
+};
+
+// 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 ?? {};
+  const policy = resolveEnvPolicy(config);
+  if (policy === "inherit") {
+    return { ...process.env, ...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;
-function buildChildEnv(config) {
-  const configured = config.env ?? {};
-  if (config.inheritEnv !== false) {
-    return { ...process.env, ...configured };
-  }
-  return {
-    PATH: process.env.PATH ?? "",
-    HOME: process.env.HOME ?? "",
-    ...configured
-  };
-}
+var DEFAULT_MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
 function composeTaskText(input) {
   const sections = [`# Objective
 ${input.objective}`];
@@ -706,18 +1660,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;
@@ -746,40 +1701,76 @@ 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);
+        child.stdin?.destroy();
+        child.stdout?.destroy();
+        child.stderr?.destroy();
         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") {
@@ -833,7 +1824,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,
@@ -848,14 +1839,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) }
           });
         });
       });
@@ -864,67 +1855,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;
@@ -945,6 +1986,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();
@@ -960,14 +2035,24 @@ 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 assertAgentConfig(config) {
+  if (!config.name || config.name.trim().length === 0) {
+    throw new ConfigError("CONFIG_INVALID", "Agent name must not be empty.");
+  }
+  if (config.integration === "process" && (!config.command || config.command.trim().length === 0)) {
+    throw new ConfigError("CONFIG_INVALID", `Agent "${config.name}" needs a command for the process adapter.`);
   }
+}
+function createAgent(config, adapters = defaultAgentAdapters) {
+  assertAgentConfig(config);
+  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.`);
@@ -1009,51 +2094,127 @@ function buildRoleRegistry(config) {
 }
 
 // src/persistence/json-file-store.ts
-import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { open, mkdir, readFile, rename, stat, writeFile } from "fs/promises";
 import { dirname } from "path";
+var SCHEMA_VERSION = 2;
+async function writeFileAtomic(target, contents, durability = "rename") {
+  const tmp = `${target}.tmp`;
+  await mkdir(dirname(target), { recursive: true });
+  if (durability === "fsync") {
+    const handle = await open(tmp, "w");
+    try {
+      await handle.writeFile(contents, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } else {
+    await writeFile(tmp, contents, "utf8");
+  }
+  await rename(tmp, target);
+  if (durability === "fsync") {
+    try {
+      const dir = await open(dirname(target), "r");
+      try {
+        await dir.sync();
+      } finally {
+        await dir.close();
+      }
+    } catch {
+    }
+  }
+}
+async function inspectDocument(path2) {
+  let raw;
+  try {
+    await stat(path2);
+  } catch {
+    return { status: "missing" };
+  }
+  try {
+    raw = await readFile(path2, "utf8");
+  } catch (error) {
+    return { status: "corrupt", detail: `unreadable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (raw.trim().length === 0) return { status: "empty" };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return { status: "corrupt", detail: error instanceof Error ? error.message : "invalid JSON" };
+  }
+  if (Array.isArray(parsed)) return { status: "v1-legacy" };
+  if (parsed === null || typeof parsed !== "object") return { status: "corrupt", detail: "not an object" };
+  const doc = parsed;
+  if (!Array.isArray(doc.items)) return { status: "corrupt", detail: "missing items array" };
+  const version = typeof doc.schemaVersion === "number" ? doc.schemaVersion : 1;
+  if (version > SCHEMA_VERSION) return { status: "future", schemaVersion: version };
+  if (version < SCHEMA_VERSION) return { status: "v1-legacy" };
+  return { status: "current", schemaVersion: version, count: doc.items.length };
+}
+async function readDocument(path2, onCorrupt, quarantine = true) {
+  const state = await inspectDocument(path2);
+  if (state.status === "missing" || state.status === "empty") return [];
+  if (state.status === "future") {
+    const error = new Error(
+      `${path2} was written by a newer OmniNode (schema v${state.schemaVersion} > v${SCHEMA_VERSION})`
+    );
+    onCorrupt?.(path2, error);
+    return [];
+  }
+  let raw;
+  try {
+    raw = await readFile(path2, "utf8");
+  } catch (error) {
+    onCorrupt?.(path2, error);
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+    return parsed.items ?? [];
+  } catch (error) {
+    if (quarantine) {
+      const quarantinePath = `${path2}.corrupt-${Date.now()}`;
+      try {
+        await rename(path2, quarantinePath);
+        logger.child({ component: "persistence" }).warn(
+          `Quarantined unreadable store file ${path2} \u2192 ${quarantinePath}`
+        );
+      } catch {
+      }
+    }
+    onCorrupt?.(path2, error);
+    return [];
+  }
+}
 var JsonFileStore = class {
   filePath;
   schemaVersion;
+  durability;
   onCorrupt;
+  quarantine;
   log;
   queue = Promise.resolve();
   constructor(options) {
     this.filePath = `${options.directory ?? `${process.cwd()}/.omninode`}/${options.fileName}`;
-    this.schemaVersion = options.schemaVersion ?? 1;
+    this.schemaVersion = options.schemaVersion ?? SCHEMA_VERSION;
+    this.durability = options.durability ?? "rename";
     this.onCorrupt = options.onCorrupt;
+    this.quarantine = options.quarantine ?? true;
     this.log = logger.child({ component: "persistence", file: options.fileName });
   }
   get path() {
     return this.filePath;
   }
-  /** All items, or [] when missing/corrupt. */
+  /** All items, or [] when missing/migrated-from-v1/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 [];
-    }
+    return readDocument(this.filePath, this.onCorrupt, this.quarantine);
   }
   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);
+    await writeFileAtomic(this.filePath, `${JSON.stringify(document, null, 2)}
+`, this.durability);
   }
   /** Serializes an async operation against this file. */
   synchronized(operation) {
@@ -1150,13 +2311,14 @@ var TaskEngine = class {
       createdAt: now,
       updatedAt: now,
       ...input.project !== void 0 ? { project: input.project } : {},
+      ...input.pipelineId !== void 0 ? { pipelineId: input.pipelineId } : {},
       ...input.role !== void 0 ? { role: input.role } : {},
       ...input.agent !== void 0 ? { agent: input.agent } : {},
       ...input.context !== void 0 ? { context: input.context } : {}
     };
     await this.options.store.save(task);
     this.log.info(`Created task ${task.id}.`);
-    await this.audit("task.created", task.id, { objective: task.objective, project: task.project });
+    await this.audit("task.created", task, { objective: task.objective });
     return task;
   }
   async queue(id) {
@@ -1199,12 +2361,24 @@ var TaskEngine = class {
       const executionId = `exec-${Date.now().toString(36)}-${randomBytes(3).toString("hex")}`;
       const startedAt = (/* @__PURE__ */ new Date()).toISOString();
       current = await this.transition(current, "running", { attempt });
+      await this.options.audit?.record({
+        at: startedAt,
+        action: "agent.started",
+        id: current.id,
+        taskId: current.id,
+        ...current.pipelineId !== void 0 ? { pipelineId: current.pipelineId } : {},
+        agentId: task.agent,
+        executionId,
+        detail: { attempt }
+      });
       let output;
       let thrown;
       try {
         output = await agent.run({
           taskId: current.id,
           objective: current.objective,
+          executionId,
+          ...current.pipelineId !== void 0 ? { pipelineId: current.pipelineId } : {},
           ...role ? { role } : {},
           ...background !== void 0 ? { context: background } : {}
         });
@@ -1212,6 +2386,16 @@ var TaskEngine = class {
         thrown = error;
       }
       const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await this.options.audit?.record({
+        at: finishedAt,
+        action: "agent.completed",
+        id: current.id,
+        taskId: current.id,
+        ...current.pipelineId !== void 0 ? { pipelineId: current.pipelineId } : {},
+        agentId: task.agent,
+        executionId,
+        detail: { attempt, outcome: thrown !== void 0 || output === void 0 ? "threw" : "returned" }
+      });
       if (thrown !== void 0 || output === void 0) {
         const outcome = classifyThrown(thrown);
         const message = thrown instanceof Error ? thrown.message : String(thrown);
@@ -1236,9 +2420,15 @@ var TaskEngine = class {
         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 } : {},
+        ...output.protocol !== void 0 ? { protocol: output.protocol } : {},
         // 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 } : {},
@@ -1286,7 +2476,7 @@ var TaskEngine = class {
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     await this.options.store.save(reset);
-    await this.audit("task.retry", id, { from: task.status });
+    await this.audit("task.retry", reset, { from: task.status });
     this.log.info(`Task ${id} reset for retry.`);
     return reset;
   }
@@ -1319,16 +2509,21 @@ var TaskEngine = class {
       ...extra.result !== void 0 ? { result: { ...task.result, ...extra.result } } : {}
     };
     await this.options.store.save(updated);
-    await this.audit(`task.${to === "queued" ? "queued" : to}`, updated.id, {
+    await this.audit(`task.${to === "queued" ? "queued" : to}`, updated, {
       from: task.status
     });
     return updated;
   }
-  async audit(action, id, detail) {
+  async audit(action, task, detail, executionId) {
     await this.options.audit?.record({
       at: (/* @__PURE__ */ new Date()).toISOString(),
       action,
-      id,
+      id: task.id,
+      taskId: task.id,
+      ...task.project !== void 0 ? { project: task.project } : {},
+      ...task.pipelineId !== void 0 ? { pipelineId: task.pipelineId } : {},
+      ...task.agent !== void 0 ? { agentId: task.agent } : {},
+      ...executionId !== void 0 ? { executionId } : {},
       ...detail !== void 0 ? { detail } : {}
     });
   }
@@ -1347,22 +2542,35 @@ function classifyThrown(error) {
   return "failed";
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
 // src/audit/index.ts
-import { appendFile, mkdir as mkdir2 } from "fs/promises";
+import { appendFile, mkdir as mkdir2, readFile as readFile2, rename as rename2, stat as stat2 } from "fs/promises";
 import { dirname as dirname2 } from "path";
+var DEFAULT_AUDIT_MAX_BYTES = 5 * 1024 * 1024;
 var FileAuditLog = class {
   filePath;
+  maxBytes;
   log;
-  constructor(directory = `${process.cwd()}/.omninode`, log = logger) {
+  constructor(directory = `${process.cwd()}/.omninode`, log = logger, maxBytes = DEFAULT_AUDIT_MAX_BYTES) {
     this.filePath = `${directory}/audit.jsonl`;
+    this.maxBytes = maxBytes;
     this.log = log.child({ component: "audit" });
   }
+  /** Rotates the log once it passes the size budget, keeping one backup. */
+  async rotateIfNeeded() {
+    try {
+      const stats = await stat2(this.filePath);
+      if (stats.size <= this.maxBytes) return;
+      await rename2(this.filePath, `${this.filePath}.1`);
+    } catch {
+    }
+  }
   async record(event) {
     try {
       await mkdir2(dirname2(this.filePath), { recursive: true });
+      await this.rotateIfNeeded();
       await appendFile(this.filePath, `${JSON.stringify(event)}
 `, "utf8");
     } catch (error) {
@@ -1373,7 +2581,6 @@ var FileAuditLog = class {
   }
   /** Recent events, oldest first; used by the CLI. */
   async recent(limit = 20) {
-    const { readFile: readFile2 } = await import("fs/promises");
     let raw;
     try {
       raw = await readFile2(this.filePath, "utf8");
@@ -1391,6 +2598,23 @@ var FileAuditLog = class {
   }
 };
 
+// src/memory/base.ts
+function defaultSearch(provider, text, options = {}) {
+  return provider.retrieve({
+    text,
+    ...options.scope !== void 0 ? { scope: options.scope } : {},
+    ...options.limit !== void 0 ? { limit: options.limit } : {}
+  });
+}
+function defaultMetadata(name, options = {}) {
+  return {
+    name,
+    capabilities: options.capabilities ?? ["retrieve", "store", "search"],
+    relevanceRanking: options.relevanceRanking ?? false,
+    ...options.backend !== void 0 ? { backend: options.backend } : {}
+  };
+}
+
 // src/memory/local.ts
 var STOPWORDS = /* @__PURE__ */ new Set([
   "the",
@@ -1453,9 +2677,27 @@ var LocalMemoryProvider = class extends JsonFileStore {
   constructor(directory) {
     super({ ...directory !== void 0 ? { directory } : {}, fileName: "memory.json" });
   }
-  async query(query) {
+  metadata() {
+    return defaultMetadata(this.name, {
+      capabilities: ["retrieve", "store", "search", "categories", "tags"],
+      relevanceRanking: true,
+      backend: { kind: "json-file", deterministicScoring: true }
+    });
+  }
+  search(text, options = {}) {
+    return defaultSearch(this, text, options);
+  }
+  /** @deprecated v1 alias of {@link retrieve}. */
+  query(query) {
+    return this.retrieve(query);
+  }
+  /** @deprecated v1 alias of {@link store}. */
+  write(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(
+    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) {
@@ -1464,7 +2706,7 @@ var LocalMemoryProvider = class extends JsonFileStore {
     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);
   }
-  write(entry) {
+  store(entry) {
     return this.mutate((entries) => {
       const index = entries.findIndex((e) => e.key === entry.key);
       const stamped = {
@@ -1495,11 +2737,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}.`);
@@ -1510,7 +2781,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}.`);
@@ -1545,6 +2816,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 } : {}
     };
@@ -1575,57 +2847,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}`,
@@ -1636,41 +2905,335 @@ 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 };
+  }
+};
+
+// src/tasks/engine-factory.ts
+function createTaskEngine(config, log = logger, directory) {
+  const agents = buildAgentRegistry(config, log);
+  const roles = buildRoleRegistry(config);
+  return new TaskEngine({
+    agents,
+    roles,
+    store: new FileTaskStore(directory),
+    ...config.project.memory !== void 0 ? {
+      memory: new MemoryService(createMemoryProvider(config.project.memory), log, {
+        required: config.project.memory.required
+      })
+    } : {},
+    audit: new FileAuditLog(),
+    log
+  });
+}
+
+// src/pipelines/engine.ts
+import { randomBytes as randomBytes5 } from "crypto";
+
+// src/reports/aggregate.ts
+import { randomBytes as randomBytes2 } from "crypto";
+
+// src/reports/schema.ts
+import { z as z2 } from "zod";
+var evidenceSchema = z2.union([
+  z2.string().transform((excerpt) => ({ kind: "observation", excerpt })),
+  z2.object({
+    kind: z2.enum(["file", "line", "url", "command", "observation", "artifact"]),
+    ref: z2.string().optional(),
+    line: z2.number().int().optional(),
+    excerpt: z2.string().optional(),
+    agent: z2.string().optional()
+  })
+]);
+var findingSchema = z2.object({
+  id: z2.string().min(1),
+  title: z2.string().min(1),
+  detail: z2.string().default(""),
+  description: z2.string().optional(),
+  severity: z2.enum(["info", "low", "medium", "high", "critical"]).optional(),
+  confidence: z2.enum(["low", "medium", "high"]).optional(),
+  severityBySource: z2.record(z2.enum(["info", "low", "medium", "high", "critical"])).optional(),
+  confidenceBySource: z2.record(z2.enum(["low", "medium", "high"])).optional(),
+  recommendations: z2.array(z2.string()).optional(),
+  evidence: z2.array(evidenceSchema).optional(),
+  location: z2.string().optional(),
+  tags: z2.array(z2.string()).optional(),
+  source: z2.object({ agent: z2.string().optional(), reportId: z2.string().optional(), pipelineRunId: z2.string().optional() }).optional(),
+  recommendation: z2.string().optional()
+});
+var artifactSchema = z2.object({
+  kind: z2.enum(["file", "patch", "log", "screenshot", "document", "data"]),
+  ref: z2.string().min(1),
+  description: z2.string().optional(),
+  mediaType: z2.string().optional(),
+  bytes: z2.number().int().optional()
+});
+var reportSchema = z2.object({
+  id: z2.string().min(1),
+  taskId: z2.string().min(1),
+  agent: z2.string().min(1),
+  agentId: z2.string().optional(),
+  pipelineRunId: z2.string().optional(),
+  model: z2.string().optional(),
+  summary: z2.string(),
+  findings: z2.array(findingSchema),
+  recommendations: z2.array(z2.string()),
+  confidence: z2.enum(["low", "medium", "high"]).optional(),
+  evidence: z2.array(evidenceSchema).optional(),
+  artifacts: z2.array(artifactSchema).optional(),
+  createdAt: z2.string().min(1),
+  metadata: z2.record(z2.unknown()).optional()
+});
+function validateReport(value) {
+  const parsed = reportSchema.safeParse(value);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => ({
+      path: issue.path.join(".") || "(root)",
+      message: issue.message
+    }));
+    return {
+      valid: false,
+      issues,
+      reason: `report failed schema validation (${issues.length} issue(s))`
+    };
+  }
+  const report = parsed.data;
+  report.findings = report.findings.map((finding) => ({
+    ...finding,
+    description: finding.description ?? finding.detail,
+    ...finding.source === void 0 ? { source: { agent: report.agent, reportId: report.id, ...report.pipelineRunId !== void 0 ? { pipelineRunId: report.pipelineRunId } : {} } } : {}
+  }));
+  return { valid: true, report };
+}
+function normalizeEvidence(input) {
+  if (input === void 0) return void 0;
+  return input.map(
+    (item) => typeof item === "string" ? { kind: "observation", excerpt: item } : item
+  );
+}
+function normalizeFinding(finding) {
+  return {
+    ...finding,
+    description: finding.description ?? finding.detail,
+    evidence: normalizeEvidence(finding.evidence)
+  };
+}
+
+// src/reports/aggregate.ts
+var SEVERITY_RANK = {
+  info: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4
+};
+var MAX_COMBINED_FINDINGS = 200;
+function aggregateReports(reports, options = {}) {
+  const threshold = options.similarityThreshold ?? 0.7;
+  const findingGroups = [];
+  const recommendationGroups = [];
+  for (const report of reports) {
+    for (const finding of report.findings) {
+      mergeFinding(findingGroups, finding, report, threshold);
+    }
+    for (const text of report.recommendations) {
+      mergeRecommendation(recommendationGroups, text, report, threshold);
+    }
+  }
+  const sources = [...new Set(reports.map((r) => r.agent))].sort();
+  const totalRawFindings = reports.reduce((sum, r) => sum + r.findings.length, 0);
+  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 maxFindings = options.maxFindings ?? MAX_COMBINED_FINDINGS;
+  const orderedFindings = findingGroups.sort((a, b) => rank(b) - rank(a));
+  const retainedFindings = orderedFindings.slice(0, maxFindings);
+  const droppedFindings = orderedFindings.length - retainedFindings.length;
+  const disputed = conflicts.length;
+  const summary = `${reports.length} report(s) from ${sources.length > 0 ? sources.join(", ") : "no agents"}: ${findingGroups.length} unique finding group(s) (${totalRawFindings} raw), ${agreements.length} agreement(s), ${disputed} conflict(s), ${recommendationGroups.length} recommendation group(s).`;
+  return {
+    id: `combined-${Date.now().toString(36)}-${randomBytes2(3).toString("hex")}`,
+    title: options.objective !== void 0 ? truncate(options.objective, 120) : "Combined report",
+    ...options.objective !== void 0 ? { objective: options.objective } : {},
+    ...options.pipelineRunId !== void 0 ? { pipelineRunId: options.pipelineRunId } : {},
+    taskIds: options.taskIds ?? [],
+    summary,
+    findings: retainedFindings,
+    agreements,
+    conflicts,
+    recommendations: recommendationGroups,
+    sources,
+    reportIds: reports.map((r) => r.id),
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    metadata: {
+      agents: sources.length,
+      reports: reports.length,
+      rawFindings: totalRawFindings,
+      findingGroups: findingGroups.length,
+      agreements: agreements.length,
+      conflicts: conflicts.length,
+      findingsTruncated: droppedFindings
+    }
+  };
+}
+function rankConfidence(confidence) {
+  return confidence ? { low: 1, medium: 2, high: 3 }[confidence] : 0;
+}
+function detectConflicts(groups) {
+  const conflicts = [];
+  for (const group of groups) {
+    if (group.sources.length < 2) continue;
+    const severities = new Set(Object.values(group.severityBySource ?? {}));
+    if (severities.size > 1) {
+      conflicts.push({
+        type: "severity",
+        findingTitle: group.title,
+        positions: group.sources.map((source) => position(source, group)),
+        note: `Agents disagree on severity (${[...severities].sort((a, b) => SEVERITY_RANK[a] - SEVERITY_RANK[b]).join(", ")}); the highest severity is shown, every position is preserved.`
+      });
+    }
+    const recommendations = (group.recommendations ?? []).filter((r) => r.length > 0);
+    if (recommendations.length > 1) {
+      conflicts.push({
+        type: "recommendation",
+        findingTitle: group.title,
+        positions: group.sources.map((source) => position(source, group)),
+        note: `Agents proposed ${recommendations.length} different fixes; none was discarded.`
+      });
+    }
+  }
+  return conflicts;
+}
+function position(source, group) {
+  return {
+    agent: source.agent,
+    reportId: source.reportId,
+    ...group.severityBySource?.[source.agent] !== void 0 ? { severity: group.severityBySource[source.agent] } : {},
+    ...group.confidenceBySource?.[source.agent] !== void 0 ? { confidence: group.confidenceBySource[source.agent] } : {},
+    ...group.recommendations?.[0] !== void 0 ? { recommendation: group.recommendations[0] } : {}
+  };
+}
+function rank(finding) {
+  return finding.severity ? SEVERITY_RANK[finding.severity] : -1;
+}
+function mergeFinding(groups, finding, report, threshold) {
+  const source = { agent: report.agent, reportId: report.id };
+  const group = groups.find((g) => similar(g.title, finding.title, threshold));
+  if (group) {
+    group.occurrences += 1;
+    group.details.push(finding.detail);
+    group.sources.push(source);
+    group.evidence.push(...normalizeEvidence(finding.evidence) ?? []);
+    if (finding.severity && (!group.severity || SEVERITY_RANK[finding.severity] > SEVERITY_RANK[group.severity])) {
+      group.severity = finding.severity;
+    }
+    if (finding.confidence && rankConfidence(finding.confidence) > rankConfidence(group.confidence)) {
+      group.confidence = finding.confidence;
+    }
+    if (finding.severity) {
+      group.severityBySource = { ...group.severityBySource, [report.agent]: finding.severity };
+    }
+    if (finding.confidence) {
+      group.confidenceBySource = { ...group.confidenceBySource, [report.agent]: finding.confidence };
+    }
+    if (finding.recommendation && !group.recommendations?.includes(finding.recommendation)) {
+      group.recommendations = [...group.recommendations ?? [], finding.recommendation];
+    }
+    return;
   }
-};
-
-// src/tasks/engine-factory.ts
-function createTaskEngine(config, log = logger, directory) {
-  const agents = buildAgentRegistry(config, log);
-  const roles = buildRoleRegistry(config);
-  return new TaskEngine({
-    agents,
-    roles,
-    store: new FileTaskStore(directory),
-    ...config.project.memory !== void 0 ? { memory: new MemoryService(createMemoryProvider(config.project.memory), log) } : {},
-    audit: new FileAuditLog(),
-    log
+  groups.push({
+    title: finding.title,
+    details: [finding.detail],
+    sources: [source],
+    occurrences: 1,
+    ...finding.severity ? { severity: finding.severity } : {},
+    ...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) ?? []]
   });
 }
-
-// src/pipelines/engine.ts
-import { randomBytes as randomBytes4 } from "crypto";
+function mergeRecommendation(groups, text, report, threshold) {
+  const source = { agent: report.agent, reportId: report.id };
+  const group = groups.find((g) => similar(g.text, text, threshold));
+  if (group) {
+    group.occurrences += 1;
+    group.sources.push(source);
+    return;
+  }
+  groups.push({ text, sources: [source], occurrences: 1 });
+}
+function similar(a, b, threshold) {
+  const left = tokens(a);
+  const right = tokens(b);
+  if (left.size === 0 || right.size === 0) return false;
+  let intersection = 0;
+  for (const token of left) {
+    if (right.has(token)) intersection += 1;
+  }
+  const union = left.size + right.size - intersection;
+  return intersection / union >= threshold;
+}
+function tokens(text) {
+  return new Set(
+    text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((t) => t.length >= 3)
+  );
+}
+function truncate(text, max) {
+  return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
+}
 
 // src/planner/heuristic.ts
-import { randomBytes as randomBytes2 } from "crypto";
-var SEVERITY_RANK = {
+import { randomBytes as randomBytes3 } from "crypto";
+var SEVERITY_RANK2 = {
   info: 0,
   low: 1,
   medium: 2,
@@ -1681,19 +3244,32 @@ var HeuristicPlanner = class {
   name = "heuristic";
   async plan(request) {
     const steps = [];
-    const findings = request.reports.flatMap(
-      (report) => report.findings.map((finding) => ({ finding, agent: report.agent }))
-    );
     const recommendations = dedupe(request.reports.flatMap((r) => r.recommendations));
-    for (const [index, text] of recommendations.entries()) {
+    for (const text of recommendations) {
       steps.push({
         id: `step-${steps.length + 1}`,
-        title: truncate(text, 120),
+        title: truncate2(text, 120),
         order: steps.length + 1,
-        ...index > 0 ? { dependsOn: [`step-${steps.length}`] } : {}
+        ...steps.length > 0 ? { dependsOn: [`step-${steps.length}`] } : {}
       });
     }
-    const significant = findings.filter(({ finding }) => finding.severity ? SEVERITY_RANK[finding.severity] >= SEVERITY_RANK.high : false).sort((a, b) => SEVERITY_RANK[b.finding.severity ?? "info"] - SEVERITY_RANK[a.finding.severity ?? "info"]);
+    const contributed = request.aggregated ? request.aggregated.findings.map((finding) => ({
+      finding: {
+        id: `agg-${slug(finding.title)}`,
+        title: finding.title,
+        detail: finding.details[0] ?? finding.title,
+        ...finding.severity ? { severity: finding.severity } : {},
+        ...finding.recommendations && finding.recommendations.length > 0 ? { recommendation: finding.recommendations[0] } : {}
+      },
+      agent: finding.sources.map((s) => s.agent).join("+")
+    })) : request.reports.flatMap(
+      (report) => report.findings.map((finding) => ({ finding, agent: report.agent }))
+    );
+    const significant = contributed.filter(
+      ({ finding }) => finding.severity ? SEVERITY_RANK2[finding.severity] >= SEVERITY_RANK2.high : false
+    ).sort(
+      (a, b) => SEVERITY_RANK2[b.finding.severity ?? "info"] - SEVERITY_RANK2[a.finding.severity ?? "info"]
+    );
     for (const { finding } of significant) {
       steps.push(remediationStep(finding, steps.length + 1));
     }
@@ -1706,12 +3282,20 @@ var HeuristicPlanner = class {
       });
     }
     const risks = significant.filter(({ finding }) => finding.severity === "critical").map(({ finding }) => `Critical finding unaddressed until its step completes: ${finding.title}`);
+    const conflicts = request.aggregated?.conflicts ?? [];
+    if (conflicts.length > 0) {
+      risks.push(
+        `${conflicts.length} unresolved agent disagreement(s): ${conflicts.map((c) => c.findingTitle).join("; ")}`
+      );
+    }
     return {
-      id: `plan-${Date.now().toString(36)}-${randomBytes2(3).toString("hex")}`,
+      id: `plan-${Date.now().toString(36)}-${randomBytes3(3).toString("hex")}`,
       objective: request.objective,
+      goal: request.aggregated?.title ?? truncate2(request.objective, 120),
       summary: `Derived from ${request.reports.length} report(s): ${recommendations.length} recommendation step(s), ${significant.length} remediation step(s).`,
       steps,
       ...risks.length > 0 ? { risks } : {},
+      ...request.constraints !== void 0 && request.constraints.length > 0 ? { constraints: request.constraints } : {},
       generatedBy: "heuristic",
       ...request.taskId !== void 0 ? { taskId: request.taskId } : {},
       ...request.pipelineRunId !== void 0 ? { pipelineRunId: request.pipelineRunId } : {},
@@ -1722,28 +3306,80 @@ var HeuristicPlanner = class {
 function remediationStep(finding, order) {
   return {
     id: `step-${order}`,
-    title: `Fix: ${truncate(finding.title, 100)}`,
+    title: `Fix: ${truncate2(finding.title, 100)}`,
     description: finding.detail,
     order,
     dependsOn: order > 1 ? [`step-${order - 1}`] : [],
-    sourceFindings: [finding.id]
+    sourceFindings: [finding.id],
+    ...finding.recommendation ? { recommendation: finding.recommendation } : {}
   };
 }
 function dedupe(texts) {
   return [...new Set(texts.map((t) => t.trim()).filter((t) => t.length > 0))];
 }
-function truncate(text, max) {
+function slug(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+}
+function truncate2(text, max) {
   return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
 }
 
 // src/planner/model.ts
-import { randomBytes as randomBytes3 } from "crypto";
-import { z as z2 } from "zod";
+import { randomBytes as randomBytes4 } from "crypto";
+
+// src/planner/schema.ts
+import { z as z3 } from "zod";
+var planStepSchema = z3.object({
+  id: z3.string().min(1).optional(),
+  title: z3.string().min(1),
+  description: z3.string().optional(),
+  order: z3.number().int().optional(),
+  targets: z3.array(z3.string()).optional(),
+  acceptance_criteria: z3.array(z3.string()).optional(),
+  depends_on: z3.array(z3.string()).optional(),
+  source_findings: z3.array(z3.string()).optional()
+});
+var planJsonSchema = z3.object({
+  goal: z3.string().min(1),
+  summary: z3.string().min(1),
+  steps: z3.array(planStepSchema).min(1),
+  risks: z3.array(z3.string()).optional(),
+  notes: z3.array(z3.string()).optional()
+});
+function validatePlan(plan) {
+  const issues = [];
+  const stepIds = /* @__PURE__ */ new Set();
+  for (const [index, step] of plan.steps.entries()) {
+    if (stepIds.has(step.id)) {
+      issues.push({ path: `steps.${index}.id`, message: `duplicate step id "${step.id}"` });
+    }
+    stepIds.add(step.id);
+    if (!step.title || step.title.trim().length === 0) {
+      issues.push({ path: `steps.${index}.title`, message: "title must not be empty" });
+    }
+    for (const dep of step.dependsOn ?? []) {
+      if (!stepIds.has(dep) && !plan.steps.some((s) => s.id === dep)) {
+        issues.push({ path: `steps.${index}.dependsOn`, message: `unknown step dependency "${dep}"` });
+      }
+    }
+  }
+  if (plan.steps.length === 0) {
+    issues.push({ path: "steps", message: "a plan needs at least one step" });
+  }
+  if (!plan.summary || plan.summary.trim().length === 0) {
+    issues.push({ path: "summary", message: "summary must not be empty" });
+  }
+  return issues.length > 0 ? { valid: false, issues, reason: `plan failed validation (${issues.length} issue(s))` } : { valid: true, plan };
+}
 
 // src/planner/context.ts
 function buildPlannerContext(request) {
-  const parts = [`# Objective
+  const parts = [`# Task
 ${request.objective}`];
+  if (request.projectContext) {
+    parts.push(`# Project context
+${request.projectContext}`);
+  }
   if (request.role) {
     const roleLines = [`# Role
 ${request.role.name} (${request.role.id})`];
@@ -1763,7 +3399,7 @@ ${request.role.name} (${request.role.id})`];
       )
     );
     parts.push(
-      `# Findings (${request.reports.length} report(s) by ${agents})
+      `# Agent reports (${request.reports.length} by ${agents})
 ` + (findingLines.length > 0 ? findingLines.join("\n") : "(no findings reported)")
     );
     const recommendationLines = request.reports.flatMap(
@@ -1773,9 +3409,20 @@ ${request.role.name} (${request.role.id})`];
       parts.push(`# Recommendations
 ${recommendationLines.join("\n")}`);
     }
-    const summaryLines = request.reports.map((report) => `- [${report.agent}] ${report.summary}`);
-    parts.push(`# Report summaries
-${summaryLines.join("\n")}`);
+  }
+  if (request.aggregated) {
+    const aggregatedLines = [
+      `- findings: ${request.aggregated.findings.length} (agreements: ${request.aggregated.agreements.length}, conflicts: ${request.aggregated.conflicts.length})`,
+      ...request.aggregated.findings.map(
+        (finding) => `- [${finding.severity ?? "info"}] ${finding.title} (x${finding.occurrences})`
+      ),
+      // Conflicts stay visible to the planner — it must plan around disagreement.
+      ...request.aggregated.conflicts.map(
+        (conflict) => `- CONFLICT (${conflict.type}) on "${conflict.findingTitle}": ${conflict.note}`
+      )
+    ];
+    parts.push(`# Aggregated findings
+${aggregatedLines.join("\n")}`);
   }
   if (request.memory && request.memory.length > 0) {
     parts.push(
@@ -1783,7 +3430,11 @@ ${summaryLines.join("\n")}`);
 ` + request.memory.map((entry) => `- [${entry.scope}] ${entry.content}`).join("\n")
     );
   }
-  if (request.context && request.context.length > 0) {
+  if (request.constraints && request.constraints.length > 0) {
+    parts.push(`# Constraints
+${request.constraints.map((c) => `- ${c}`).join("\n")}`);
+  }
+  if (request.context) {
     parts.push(`# Research context
 ${request.context}`);
   }
@@ -1791,22 +3442,6 @@ ${request.context}`);
 }
 
 // src/planner/model.ts
-var planStepJsonSchema = z2.object({
-  id: z2.string().optional(),
-  title: z2.string().min(1),
-  description: z2.string().optional(),
-  order: z2.number().int().optional(),
-  targets: z2.array(z2.string()).optional(),
-  acceptance_criteria: z2.array(z2.string()).optional(),
-  depends_on: z2.array(z2.string()).optional(),
-  source_findings: z2.array(z2.string()).optional()
-}).strict();
-var planJsonSchema = z2.object({
-  summary: z2.string().min(1),
-  steps: z2.array(planStepJsonSchema).min(1),
-  risks: z2.array(z2.string()).optional(),
-  notes: z2.array(z2.string()).optional()
-}).strict();
 var ModelPlanner = class {
   constructor(options) {
     this.options = options;
@@ -1820,7 +3455,7 @@ var ModelPlanner = class {
     const messages = [
       {
         role: "system",
-        content: 'You are the OmniNode planner. Given the objective and the combined research context, produce a final analysis and a prioritized, actionable implementation plan. Respond with JSON ONLY (no prose, no code fences) matching exactly this shape: {"summary": string, "steps": [{"id": string, "title": string, "description": string, "order": number, "targets": string[], "acceptance_criteria": string[], "source_findings": string[]}], "risks": string[], "notes": string[]}. ' + (this.options.instruction ?? "")
+        content: 'You are the OmniNode planner. Given the objective and the combined research context, produce a final analysis and a prioritized, actionable implementation plan. Respond with JSON ONLY (no prose, no code fences) matching exactly this shape: {"goal": string, "summary": string, "steps": [{"id": string, "title": string, "description": string, "order": number, "targets": string[], "acceptance_criteria": string[], "source_findings": string[]}], "risks": string[], "notes": string[]}. ' + (this.options.instruction ?? "")
       },
       { role: "user", content: context }
     ];
@@ -1831,66 +3466,99 @@ var ModelPlanner = class {
       return this.degrade(request, `planner model call failed: ${describe(error)}`);
     }
     const parsed = parsePlanJson(responseText);
-    if (!parsed) {
-      return this.degrade(request, "planner model output was not valid plan JSON");
+    if (!parsed.ok) {
+      return this.degrade(request, `planner model output rejected: ${parsed.reason}`, parsed.issues);
     }
     const plan = {
-      id: `plan-${Date.now().toString(36)}-${randomBytes3(3).toString("hex")}`,
+      id: `plan-${Date.now().toString(36)}-${randomBytes4(3).toString("hex")}`,
       objective: request.objective,
+      goal: parsed.goal,
       summary: parsed.summary,
       steps: parsed.steps,
       ...parsed.risks !== void 0 ? { risks: parsed.risks } : {},
       ...parsed.notes !== void 0 ? { notes: parsed.notes } : {},
+      ...request.constraints !== void 0 && request.constraints.length > 0 ? { constraints: request.constraints } : {},
       generatedBy: `model:${this.options.model}`,
       model: this.options.model,
       ...request.taskId !== void 0 ? { taskId: request.taskId } : {},
       ...request.pipelineRunId !== void 0 ? { pipelineRunId: request.pipelineRunId } : {},
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    return plan;
+    const validation = validatePlan(plan);
+    if (!validation.valid) {
+      return this.degrade(request, `generated plan rejected: ${validation.reason}`, validation.issues);
+    }
+    return validation.plan;
   }
-  async degrade(request, reason) {
+  async degrade(request, reason, issues = []) {
     if (this.options.fallback) {
       this.log.warn(`${reason} \u2014 using the heuristic fallback planner.`);
       return this.options.fallback.plan(request);
     }
-    throw new PlannerError("PLANNER_FAILED", `Planner failed: ${reason}.`);
+    throw new PlannerError("PLAN_INVALID", `Planner failed: ${reason}.`, {
+      details: { reason, issues }
+    });
   }
 };
 function parsePlanJson(text) {
   const unfenced = text.replace(/```(?:json)?/gi, "");
   const start = unfenced.indexOf("{");
   const end = unfenced.lastIndexOf("}");
-  if (start < 0 || end <= start) return void 0;
+  if (start < 0 || end <= start) {
+    return { ok: false, reason: "planner output contained no JSON object", issues: [] };
+  }
+  let json;
   try {
-    const json = JSON.parse(unfenced.slice(start, end + 1));
-    const parsed = planJsonSchema.safeParse(json);
-    if (!parsed.success) return void 0;
-    const steps = parsed.data.steps.map((step, index) => ({
-      id: step.id ?? `step-${index + 1}`,
-      title: step.title,
-      description: step.description,
-      order: step.order ?? index + 1,
-      targets: step.targets,
-      acceptanceCriteria: step.acceptance_criteria,
-      dependsOn: step.depends_on,
-      sourceFindings: step.source_findings
-    }));
+    json = JSON.parse(unfenced.slice(start, end + 1));
+  } catch (error) {
     return {
-      summary: parsed.data.summary,
-      steps: steps.sort((a, b) => a.order - b.order),
-      risks: parsed.data.risks,
-      notes: parsed.data.notes
+      ok: false,
+      reason: `planner output was not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      issues: []
+    };
+  }
+  const parsed = planJsonSchema.safeParse(json);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      reason: "planner output did not match the plan schema",
+      issues: parsed.error.issues.map((issue) => ({
+        path: issue.path.join(".") || "(root)",
+        message: issue.message
+      }))
     };
-  } catch {
-    return void 0;
   }
+  const steps = parsed.data.steps.map((step, index) => ({
+    id: step.id ?? `step-${index + 1}`,
+    title: step.title,
+    description: step.description,
+    order: step.order ?? index + 1,
+    targets: step.targets,
+    acceptanceCriteria: step.acceptance_criteria,
+    dependsOn: step.depends_on,
+    sourceFindings: step.source_findings
+  })).sort((a, b) => a.order - b.order);
+  return {
+    ok: true,
+    goal: parsed.data.goal,
+    summary: parsed.data.summary,
+    steps,
+    risks: parsed.data.risks,
+    notes: parsed.data.notes
+  };
 }
 function describe(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
 // src/pipelines/engine.ts
+var DEFAULT_MAX_PARALLEL_STEPS = 8;
+var MAX_COMBINED_CONTEXT_CHARS = 2e4;
+function budgetContext(context, maxChars = MAX_COMBINED_CONTEXT_CHARS) {
+  if (context.length <= maxChars) return context;
+  const marker = "\n[earlier context trimmed]\n";
+  return marker + context.slice(context.length - (maxChars - marker.length));
+}
 var PipelineEngine = class {
   constructor(options) {
     this.options = options;
@@ -1898,9 +3566,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();
@@ -2000,22 +3682,49 @@ 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")}`,
+      id: `run-${Date.now().toString(36)}-${randomBytes5(3).toString("hex")}`,
       pipelineId: def.id,
+      attempt: 1,
       objective,
       status: "running",
       startedAt: now,
       stepRuns: []
     };
     await this.options.store.save(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",
       id: run.id,
+      pipelineId: def.id,
       detail: { pipeline: def.id, objective }
     });
     const deps = this.effectiveDependencies(def);
@@ -2023,28 +3732,57 @@ 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))
       );
       if (ready.length === 0) {
         throw new PipelineError("PIPELINE_FAILED", `Pipeline "${def.id}" scheduling stalled.`);
       }
-      const settled = await Promise.all(
-        ready.map(async (step) => {
-          if (!this.shouldRun(step, deps.get(step.id) ?? [], outcomes)) {
-            return { status: "skipped", summary: "", taskIds: [], reports: [] };
-          }
-          const ctx = {
-            objective,
-            ...role ? { role } : {},
-            combinedContext: contextParts.join("\n\n"),
-            reports: [...allReports],
-            pipelineRunId: run.id
-          };
-          return this.executeStep(step, ctx);
-        })
-      );
+      const settled = [];
+      const limit = Math.max(1, this.options.maxParallelSteps ?? DEFAULT_MAX_PARALLEL_STEPS);
+      for (let offset = 0; offset < ready.length; offset += limit) {
+        const batch = ready.slice(offset, offset + limit);
+        settled.push(
+          ...await Promise.all(
+            batch.map(async (step) => {
+              if (!this.shouldRun(step, deps.get(step.id) ?? [], outcomes)) {
+                return { status: "skipped", summary: "", taskIds: [], reports: [] };
+              }
+              const ctx = {
+                maxContextChars: this.options.maxContextChars,
+                objective,
+                ...role ? { role } : {},
+                combinedContext: budgetContext(
+                  contextParts.join("\n\n"),
+                  this.options.maxContextChars ?? MAX_COMBINED_CONTEXT_CHARS
+                ),
+                reports: [...allReports],
+                pipelineRunId: run.id,
+                runId: run.id,
+                pipelineDefId: def.id,
+                taskId: run.id
+              };
+              return this.executeStep(step, ctx);
+            })
+          )
+        );
+      }
       ready.forEach((step, index) => {
         const outcome = settled[index];
         outcomes.set(step.id, outcome);
@@ -2057,6 +3795,8 @@ ${contribution}`);
         }
         const stepRun = {
           stepId: step.id,
+          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 } : {},
@@ -2066,12 +3806,12 @@ ${contribution}`);
         options.onStep?.(stepRun);
       });
       run.reports = [...allReports];
-      await this.options.store.save(run);
+      await this.persist(run);
     }
     const allOutcomes = [...outcomes.values()];
-    const failed = allOutcomes.some((o) => o.status === "failed");
-    const partial = !failed && allOutcomes.some((o) => o.status === "partial");
-    const finalStatus = failed ? "failed" : partial ? "partial" : "completed";
+    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) {
@@ -2099,25 +3839,46 @@ ${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(),
-      action: "pipeline.run.finished",
+      action: cancelled ? "pipeline.run.cancelled" : finalStatus === "failed" ? "pipeline.run.failed" : "pipeline.run.finished",
       id: run.id,
+      pipelineId: def.id,
       detail: { pipeline: def.id, status: finalStatus }
     });
     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);
   }
@@ -2141,9 +3902,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) {
@@ -2170,13 +3938,16 @@ ${contribution}`);
       agentNames.map(
         (name) => this.options.tasks.create({
           objective: ctx.objective,
+          ...ctx.pipelineRunId !== void 0 ? { pipelineId: ctx.pipelineRunId } : {},
           agent: name,
           ...ctx.role ? { role: ctx.role.id } : {},
           ...ctx.combinedContext.length > 0 ? { context: { background: ctx.combinedContext } } : {}
         })
       )
     );
+    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) => {
@@ -2199,15 +3970,23 @@ ${contribution}`);
         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({
       objective: ctx.objective,
+      ...ctx.pipelineRunId !== void 0 ? { pipelineId: ctx.pipelineRunId } : {},
       agent: agentName,
       ...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 {
@@ -2228,11 +4007,16 @@ ${contribution}`);
     };
   }
   async runPlan(step, ctx) {
+    const aggregated = ctx.reports.length > 0 ? aggregateReports(ctx.reports, {
+      ...step.constraints !== void 0 && step.constraints.length > 0 ? { maxFindings: MAX_COMBINED_FINDINGS } : {}
+    }) : void 0;
     const request = {
       objective: ctx.objective,
       reports: ctx.reports,
+      ...aggregated !== void 0 ? { aggregated } : {},
       ...ctx.combinedContext.length > 0 ? { context: ctx.combinedContext } : {},
       ...ctx.role ? { role: ctx.role } : {},
+      ...step.constraints !== void 0 && step.constraints.length > 0 ? { constraints: step.constraints } : {},
       ...ctx.pipelineRunId !== void 0 ? { pipelineRunId: ctx.pipelineRunId } : {}
     };
     let planner;
@@ -2270,7 +4054,13 @@ ${contribution}`);
       at: (/* @__PURE__ */ new Date()).toISOString(),
       action: "plan.generated",
       id: plan.id,
-      detail: { generatedBy: plan.generatedBy, steps: plan.steps.length }
+      ...ctx.pipelineDefId !== void 0 ? { pipelineId: ctx.pipelineDefId } : {},
+      detail: {
+        generatedBy: plan.generatedBy,
+        steps: plan.steps.length,
+        run: ctx.pipelineRunId,
+        taskId: ctx.taskId
+      }
     });
     return {
       status: "completed",
@@ -2304,7 +4094,7 @@ function formatPlan(plan) {
   }
   return lines.join("\n");
 }
-function createDefaultChatFn(providers) {
+function createDefaultChatFn(providers, options = {}) {
   return async (modelRef, messages) => {
     const separator = modelRef.indexOf(":");
     if (separator <= 0 || separator === modelRef.length - 1) {
@@ -2322,7 +4112,10 @@ function createDefaultChatFn(providers) {
         `Provider "${providerName}" (model "${modelRef}") is not configured.`
       );
     }
-    const provider = createProvider(providerConfig);
+    const provider = createProvider(providerConfig, {
+      ...options.audit !== void 0 ? { audit: options.audit } : {},
+      ...options.env !== void 0 ? { env: options.env } : {}
+    });
     const response = await provider.chat({ model: modelId, messages });
     return response.content;
   };
@@ -2391,99 +4184,6 @@ function buildPlanner(plannerConfig, chat, log = logger) {
   });
 }
 
-// src/reports/aggregate.ts
-import { randomBytes as randomBytes5 } from "crypto";
-var SEVERITY_RANK2 = {
-  info: 0,
-  low: 1,
-  medium: 2,
-  high: 3,
-  critical: 4
-};
-function aggregateReports(reports, options = {}) {
-  const threshold = options.similarityThreshold ?? 0.7;
-  const findingGroups = [];
-  const recommendationGroups = [];
-  for (const report of reports) {
-    for (const finding of report.findings) {
-      mergeFinding(findingGroups, finding, report, threshold);
-    }
-    for (const text of report.recommendations) {
-      mergeRecommendation(recommendationGroups, text, report, threshold);
-    }
-  }
-  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).`;
-  return {
-    id: `combined-${Date.now().toString(36)}-${randomBytes5(3).toString("hex")}`,
-    title: options.objective !== void 0 ? truncate2(options.objective, 120) : "Combined report",
-    ...options.objective !== void 0 ? { objective: options.objective } : {},
-    ...options.pipelineRunId !== void 0 ? { pipelineRunId: options.pipelineRunId } : {},
-    taskIds: options.taskIds ?? [],
-    summary,
-    findings: findingGroups.sort((a, b) => rank(b) - rank(a)),
-    recommendations: recommendationGroups,
-    sources,
-    reportIds: reports.map((r) => r.id),
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-}
-function rank(finding) {
-  return finding.severity ? SEVERITY_RANK2[finding.severity] : -1;
-}
-function mergeFinding(groups, finding, report, threshold) {
-  const source = { agent: report.agent, reportId: report.id };
-  const group = groups.find((g) => similar(g.title, finding.title, threshold));
-  if (group) {
-    group.occurrences += 1;
-    group.details.push(finding.detail);
-    group.sources.push(source);
-    group.evidence.push(...finding.evidence ?? []);
-    if (finding.severity && (!group.severity || SEVERITY_RANK2[finding.severity] > SEVERITY_RANK2[group.severity])) {
-      group.severity = finding.severity;
-    }
-    return;
-  }
-  groups.push({
-    title: finding.title,
-    details: [finding.detail],
-    sources: [source],
-    occurrences: 1,
-    ...finding.severity ? { severity: finding.severity } : {},
-    evidence: [...finding.evidence ?? []]
-  });
-}
-function mergeRecommendation(groups, text, report, threshold) {
-  const source = { agent: report.agent, reportId: report.id };
-  const group = groups.find((g) => similar(g.text, text, threshold));
-  if (group) {
-    group.occurrences += 1;
-    group.sources.push(source);
-    return;
-  }
-  groups.push({ text, sources: [source], occurrences: 1 });
-}
-function similar(a, b, threshold) {
-  const left = tokens(a);
-  const right = tokens(b);
-  if (left.size === 0 || right.size === 0) return false;
-  let intersection = 0;
-  for (const token of left) {
-    if (right.has(token)) intersection += 1;
-  }
-  const union = left.size + right.size - intersection;
-  return intersection / union >= threshold;
-}
-function tokens(text) {
-  return new Set(
-    text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((t) => t.length >= 3)
-  );
-}
-function truncate2(text, max) {
-  return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
-}
-
 // src/reports/extract.ts
 var BULLET = /^(?:[-*•]|\d+[.)])\s+(.*)$/;
 function parseSections(raw) {
@@ -2533,6 +4233,7 @@ function extractReportFromText(raw, meta) {
     id: `${meta.taskId}-f-${index + 1}`,
     title: truncate3(text, 120),
     detail: text,
+    description: text,
     severity: guessSeverity(text)
   }));
   return {
@@ -2543,7 +4244,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()
   };
 }
@@ -2552,6 +4254,7 @@ function truncate3(text, max) {
 }
 
 // src/reports/service.ts
+var MAX_REPORT_BYTES = 256 * 1024;
 var ReportService = class {
   constructor(store, log = logger) {
     this.store = store;
@@ -2559,27 +4262,56 @@ 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 size = Buffer.byteLength(JSON.stringify(candidate), "utf8");
+      if (size > MAX_REPORT_BYTES) {
+        rejected.push({
+          key: candidate?.id ?? "(unknown)",
+          reason: `report exceeds the ${MAX_REPORT_BYTES} byte limit (${size} bytes)`,
+          issues: []
+        });
+        this.log.warn(`Rejected oversized report (${size} bytes).`);
+        continue;
+      }
+      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) {
@@ -2640,14 +4372,19 @@ var FileReportStore = class extends JsonFileStore {
 
 // src/pipelines/engine-factory.ts
 function buildPipelineEngine(config, log = logger) {
+  const auditLog = new FileAuditLog();
   const agents = buildAgentRegistry(config, log);
   const roles = buildRoleRegistry(config);
-  const chat = createDefaultChatFn(config.project.providers);
+  const chat = createDefaultChatFn(config.project.providers, { audit: auditLog });
   const tasks = new TaskEngine({
     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
   });
@@ -2683,14 +4420,68 @@ var ProjectStores = class {
     this.audit = new FileAuditLog(directory);
   }
 };
+var STORE_FILES = [
+  "tasks.json",
+  "pipelines.json",
+  "reports.json",
+  "plans.json",
+  "memory.json"
+];
+async function migrateProjectStores(directory = `${process.cwd()}/.omninode`, options = {}) {
+  const reports = [];
+  for (const file of STORE_FILES) {
+    const path2 = `${directory}/${file}`;
+    const state = await inspectDocument(path2);
+    if (state.status === "missing") {
+      reports.push({ file, state: state.status, migrated: false });
+      continue;
+    }
+    if (state.status === "current") {
+      reports.push({ file, state: state.status, before: state.count, after: state.count, migrated: false });
+      continue;
+    }
+    if (state.status === "future") {
+      reports.push({
+        file,
+        state: state.status,
+        migrated: false,
+        note: `written by a newer OmniNode (schema v${state.schemaVersion}); not touched`
+      });
+      continue;
+    }
+    if (state.status === "corrupt") {
+      reports.push({ file, state: state.status, migrated: false, note: state.detail });
+      continue;
+    }
+    const items = await readDocument(path2, void 0, false);
+    if (!options.checkOnly) {
+      await writeFileAtomic(path2, `${JSON.stringify({ schemaVersion: SCHEMA_VERSION, items }, null, 2)}
+`);
+    }
+    const beforeCount = items.length;
+    reports.push({
+      file,
+      state: state.status,
+      before: beforeCount,
+      after: items.length,
+      migrated: !options.checkOnly,
+      ...options.checkOnly ? { note: "would migrate" } : {}
+    });
+  }
+  return reports;
+}
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.2";
+var OMNINODE_VERSION = "2.0.0-alpha.20";
 export {
+  AgentAdapterRegistry,
   AgentError,
   AgentRegistry,
   ConfigError,
   ConsoleLogSink,
+  DEFAULT_AUDIT_MAX_BYTES,
+  DEFAULT_MAX_OUTPUT_BYTES,
+  DEFAULT_MAX_PARALLEL_STEPS,
   FileAuditLog,
   FilePipelineRunStore,
   FilePlanStore,
@@ -2700,6 +4491,11 @@ export {
   JsonFileStore,
   LocalMemoryProvider,
   Logger,
+  MAX_COMBINED_CONTEXT_CHARS,
+  MAX_COMBINED_FINDINGS,
+  MAX_CONTEXT_CHARS,
+  MAX_MESSAGE_BYTES,
+  MAX_REPORT_BYTES,
   MemoryError,
   MemoryService,
   ModelPlanner,
@@ -2709,53 +4505,96 @@ export {
   OmniHilbrasProvider,
   OmniNodeError,
   OpenAICompatibleProvider,
+  PROTOCOL_V2,
   PipelineEngine,
   PipelineError,
   PlannerError,
   ProcessAgent,
+  ProcessAgentAdapter,
   ProjectStores,
+  ProtocolDecoder,
   ProtocolError,
+  ProtocolSession,
   ProviderError,
   RememberaMemoryProvider,
   ReportService,
   RoleRegistry,
-  TERMINAL_TASK_STATUSES,
+  SCHEMA_VERSION,
+  SUPPORTED_PROTOCOL_VERSIONS,
   TaskEngine,
   TaskError,
   agentConfigSchema,
   aggregateReports,
   appConfigSchema,
   authHeaders,
+  budgetContext,
   buildAgentRegistry,
   buildChildEnv,
+  buildHello,
+  buildHelloAck,
   buildPipelineEngine,
   buildPlanner,
   buildPlannerContext,
   buildRoleRegistry,
   composeTaskText,
+  configDiagnostics,
+  configureLogger,
   createAgent,
   createDefaultChatFn,
   createMemoryProvider,
   createProvider,
   createTaskEngine,
+  decodeMessage,
+  defaultAgentAdapters,
   defaultProjectConfigYaml,
+  describeExit,
+  describeSecretFindings,
+  detectConflicts,
+  encodeMessage,
+  envelope,
   expandEnvRefs,
+  extractMessage,
   extractReportFromText,
   findConfigFile,
+  inspectDocument,
+  isNetworkError,
   isOmniNodeError,
-  keywords,
+  isRetryable,
+  isSupportedProtocol,
+  isTimeoutError,
+  killTree,
+  kindFromStatus,
   loadConfig,
+  loadConfigDetailed,
   logger,
+  migrateProjectStores,
+  newMessageId,
+  normalizeEvidence,
+  normalizeFinding,
+  parseHello,
   parsePlanJson,
+  parseRetryAfter,
   pipelineConfigSchema,
   pipelineStepConfigSchema,
+  planJsonSchema,
   plannerConfigSchema,
   projectConfigSchema,
   providerConfigSchema,
+  providerHttpError,
+  providerTransportError,
+  readDocument,
   registryKey,
   requestJson,
   resolveApiKey,
+  resolveEnvPolicy,
   roleConfigSchema,
-  similar
+  sanitizeChunk,
+  scanForInlineSecrets,
+  similar,
+  validateEnvelope,
+  validatePlan,
+  validateReport,
+  validateWorkingDirectory,
+  writeFileAtomic
 };
 //# sourceMappingURL=index.js.map