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

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.1";
+var OMNINODE_VERSION = "2.0.0-alpha.3";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -44,11 +44,6 @@ var PipelineError = class extends OmniNodeError {
     super(code, message, options);
   }
 };
-var ProtocolError = class extends OmniNodeError {
-  constructor(message, options = {}) {
-    super("PROTOCOL_VIOLATION", message, options);
-  }
-};
 var PlannerError = class extends OmniNodeError {
   constructor(code, message, options = {}) {
     super(code, message, options);
@@ -897,6 +892,329 @@ function registerModelsCommand(program) {
 
 // src/agents/process/index.ts
 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 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/process/index.ts
 var DEFAULT_TIMEOUT_MS2 = 6e5;
 var KILL_GRACE_MS = 5e3;
 function buildChildEnv(config) {
@@ -930,18 +1248,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;
@@ -1037,7 +1356,19 @@ var ProcessAgent = class {
               new AgentError(
                 "AGENT_TIMEOUT",
                 `Agent "${this.config.name}" timed out after ${timeoutMs}ms and was killed.`,
-                { details: { taskId: input.taskId, stdout: stdout.slice(0, 4e3), stderr: stderr.slice(0, 2e3) } }
+                {
+                  details: {
+                    operation: "agent.run",
+                    agent: this.config.name,
+                    durationMs: timeoutMs,
+                    // The process was started and may have performed side
+                    // effects before being killed — the outcome is unknown,
+                    // not failed (roadmap §6.3).
+                    dispatched: true,
+                    stdout: stdout.slice(0, 4e3),
+                    stderr: stderr.slice(0, 2e3)
+                  }
+                }
               )
             );
             return;
@@ -1082,62 +1413,75 @@ var ProcessAgent = class {
     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 };
-    }
-  } catch {
-  }
-  return void 0;
-}
 function normalizeReport(payload, taskId, agentName, index) {
   if (payload === null || typeof payload !== "object") return void 0;
   const raw = payload;
@@ -1397,12 +1741,18 @@ import { randomBytes } from "crypto";
 var ALLOWED_TRANSITIONS = {
   created: ["queued", "running", "cancelled"],
   queued: ["running", "cancelled"],
-  running: ["completed", "failed", "cancelled"],
+  running: ["completed", "failed", "timed_out", "unknown", "cancelled", "partially_completed"],
   waiting: ["running", "cancelled"],
   completed: [],
-  failed: [],
-  cancelled: []
+  // failed → running is the only re-entry: bounded automatic retry (§6.4).
+  failed: ["running"],
+  timed_out: [],
+  cancelled: [],
+  unknown: [],
+  partially_completed: []
 };
+var RETRYABLE_ERROR_CODES = ["AGENT_FAILED"];
+var EXECUTION_HISTORY_LIMIT = 10;
 var TaskEngine = class {
   constructor(options) {
     this.options = options;
@@ -1434,6 +1784,7 @@ var TaskEngine = class {
       id: generateTaskId(),
       objective: input.objective.trim(),
       status: "created",
+      attempt: 0,
       createdAt: now,
       updatedAt: now,
       ...input.project !== void 0 ? { project: input.project } : {},
@@ -1450,8 +1801,10 @@ var TaskEngine = class {
     const task = await this.mustGet(id);
     return this.transition(task, "queued");
   }
-  /** Runs the task through its assigned agent and records the result. */
-  async run(id) {
+  /** Runs the task through its assigned agent and records the result.
+   *  `maxAttempts` enables bounded automatic retries of *retryable* errors
+   *  with linear backoff; unknown/timed_out outcomes are never auto-retried. */
+  async run(id, options = {}) {
     const task = await this.mustGet(id);
     if (task.status !== "created" && task.status !== "queued") {
       throw new TaskError("TASK_INVALID", `Task ${id} is "${task.status}" and cannot be run.`);
@@ -1464,49 +1817,84 @@ var TaskEngine = class {
       throw new TaskError("TASK_INVALID", `Agent "${task.agent}" is not registered anymore.`);
     }
     const role = task.role ? this.options.roles.get(task.role) : void 0;
-    const running = await this.transition(task, "running");
     this.log.info(`Running task ${task.id} on agent "${task.agent}".`);
-    let background = running.context?.background;
+    let background = task.context?.background;
     if (this.options.memory) {
       const memoryContext = await this.options.memory.gatherContext({
-        objective: running.objective,
-        ...running.role ? { role: running.role } : {},
-        ...running.project ? { project: running.project } : {}
+        objective: task.objective,
+        ...task.role ? { role: task.role } : {},
+        ...task.project ? { project: task.project } : {}
       });
       if (memoryContext.length > 0) {
         background = [memoryContext, background].filter((part) => part && part.length > 0).join("\n\n");
       }
     }
-    let output;
-    try {
-      output = await agent.run({
-        taskId: running.id,
-        objective: running.objective,
-        ...role ? { role } : {},
-        ...background !== void 0 ? { context: background } : {}
-      });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.log.error(`Task ${task.id} failed: ${message}`);
-      return this.transition(running, "failed", {
-        result: { error: message, finishedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 1);
+    const backoffMs = options.retryBackoffMs ?? 0;
+    let current = task;
+    for (let i = 0; i < maxAttempts; i += 1) {
+      const attempt = current.attempt + 1;
+      const executionId = `exec-${Date.now().toString(36)}-${randomBytes(3).toString("hex")}`;
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      current = await this.transition(current, "running", { attempt });
+      let output;
+      let thrown;
+      try {
+        output = await agent.run({
+          taskId: current.id,
+          objective: current.objective,
+          ...role ? { role } : {},
+          ...background !== void 0 ? { context: background } : {}
+        });
+      } catch (error) {
+        thrown = error;
+      }
+      const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+      if (thrown !== void 0 || output === void 0) {
+        const outcome = classifyThrown(thrown);
+        const message = thrown instanceof Error ? thrown.message : String(thrown);
+        const retryable = outcome === "failed" && RETRYABLE_ERROR_CODES.includes(errorCode(thrown)) && i < maxAttempts - 1;
+        current = await this.transition(current, outcome, {
+          attempt,
+          lastError: message,
+          execution: {
+            executionId,
+            attempt,
+            startedAt,
+            finishedAt,
+            outcome,
+            error: message
+          }
+        });
+        this.log.warn(`Task ${current.id} attempt ${attempt} \u2192 ${outcome}: ${message}`);
+        if (retryable) {
+          if (backoffMs > 0) await sleep(backoffMs * attempt);
+          continue;
+        }
+        if (this.options.memory) await this.options.memory.recordTaskOutcome(current);
+        return current;
+      }
+      const result = {
+        ...output.summary !== void 0 ? { summary: output.summary } : {},
+        ...output.reports !== void 0 && output.reports.length > 0 ? { reports: output.reports } : {},
+        // Keep the verbatim output (bounded) for report extraction and audit.
+        ...output.rawOutput !== void 0 && output.rawOutput.length > 0 ? { rawOutput: output.rawOutput.slice(0, 1e4) } : {},
+        ...output.error !== void 0 ? { error: output.error } : {},
+        finishedAt
+      };
+      const finalStatus = output.status === "completed" ? "completed" : "failed";
+      current = await this.transition(current, finalStatus, {
+        attempt,
+        result,
+        execution: { executionId, attempt, startedAt, finishedAt, outcome: finalStatus }
       });
+      this.log.info(`Task ${current.id} finished: ${finalStatus}.`);
+      break;
     }
-    const result = {
-      ...output.summary !== void 0 ? { summary: output.summary } : {},
-      ...output.reports !== void 0 && output.reports.length > 0 ? { reports: output.reports } : {},
-      // Keep the verbatim output (bounded) for report extraction and audit.
-      ...output.rawOutput !== void 0 && output.rawOutput.length > 0 ? { rawOutput: output.rawOutput.slice(0, 1e4) } : {},
-      ...output.error !== void 0 ? { error: output.error } : {},
-      finishedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    const finalStatus = output.status === "completed" ? "completed" : "failed";
-    const finished = await this.transition(running, finalStatus, { result });
-    this.log.info(`Task ${task.id} finished: ${finalStatus}.`);
     if (this.options.memory) {
-      await this.options.memory.recordTaskOutcome(finished);
+      await this.options.memory.recordTaskOutcome(current);
     }
-    return finished;
+    return current;
   }
   async cancel(id) {
     const task = await this.mustGet(id);
@@ -1519,13 +1907,14 @@ var TaskEngine = class {
     }
     return this.transition(task, "cancelled");
   }
-  /** Error recovery (§27 Phase 9): reset a failed/cancelled task so it can run again. */
+  /** Error recovery: reset a failed/cancelled/unknown/timed_out task so it can run again. */
   async retry(id) {
     const task = await this.mustGet(id);
-    if (task.status !== "failed" && task.status !== "cancelled") {
+    const retryableStates = ["failed", "cancelled", "unknown", "timed_out"];
+    if (!retryableStates.includes(task.status)) {
       throw new TaskError(
         "TASK_INVALID",
-        `Only failed or cancelled tasks can be retried \u2014 task ${id} is "${task.status}".`
+        `Only failed, timed out, unknown or cancelled tasks can be retried \u2014 task ${id} is "${task.status}".`
       );
     }
     const { result: _discarded, ...rest } = task;
@@ -1557,10 +1946,14 @@ var TaskEngine = class {
     if (!allowed.includes(to)) {
       throw new TaskError("TASK_INVALID", `Task ${task.id} cannot move from "${task.status}" to "${to}".`);
     }
+    const executions = extra.execution ? [...task.executions ?? [], extra.execution].slice(-EXECUTION_HISTORY_LIMIT) : task.executions;
     const updated = {
       ...task,
       status: to,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...extra.attempt !== void 0 ? { attempt: extra.attempt } : {},
+      ...extra.lastError !== void 0 ? { lastError: extra.lastError } : {},
+      ...executions !== void 0 ? { executions } : {},
       ...extra.result !== void 0 ? { result: { ...task.result, ...extra.result } } : {}
     };
     await this.options.store.save(updated);
@@ -1581,6 +1974,19 @@ var TaskEngine = class {
 function generateTaskId() {
   return `task-${Date.now().toString(36)}-${randomBytes(3).toString("hex")}`;
 }
+function errorCode(error) {
+  return error?.code ?? "";
+}
+function classifyThrown(error) {
+  if (error instanceof AgentError && error.code === "AGENT_TIMEOUT") {
+    const dispatched = error.details?.dispatched;
+    return dispatched === false ? "timed_out" : "unknown";
+  }
+  return "failed";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 // src/audit/index.ts
 import { appendFile, mkdir as mkdir2 } from "fs/promises";
@@ -1980,7 +2386,7 @@ function registerTaskCommands(program) {
     const cancelled = await engine.cancel(taskId);
     console.log(`Task ${cancelled.id} is now "${cancelled.status}".`);
   });
-  task.command("retry <task-id>").description("Reset a failed/cancelled task to created; combine with --run to execute it again.").option("--run", "Run the task again immediately after resetting it.").action(async (taskId, options) => {
+  task.command("retry <task-id>").description("Reset a failed, timed out, unknown or cancelled task to created; combine with --run to execute it again.").option("--run", "Run the task again immediately after resetting it.").action(async (taskId, options) => {
     const config = loadConfig();
     const engine = createTaskEngine(config);
     const reset = await engine.retry(taskId);
@@ -2003,6 +2409,15 @@ function printOutcome(task, options = {}) {
     if (task.context?.files) console.log(`  files:   ${task.context.files.join(", ")}`);
     console.log(`  objective: ${task.objective}`);
   }
+  if (options.verbose && task.attempt > 0) {
+    console.log(`  attempt: ${task.attempt}`);
+  }
+  if (task.lastError) console.log(`  error:   ${task.lastError}`);
+  if (options.verbose && task.executions && task.executions.length > 0) {
+    console.log(
+      `  executions: ${task.executions.map((e) => `#${e.attempt}:${e.outcome}`).join(", ")}`
+    );
+  }
   const result = task.result;
   if (!result) return;
   if (result.summary) console.log(`  summary: ${result.summary}`);
@@ -2743,7 +3158,7 @@ ${contribution}`);
         }
         const stepRun = {
           stepId: step.id,
-          status: outcome.status === "skipped" ? "cancelled" : outcome.status === "failed" ? "failed" : "completed",
+          status: outcome.status === "skipped" ? "cancelled" : outcome.status === "failed" ? "failed" : outcome.status === "partial" ? "partially_completed" : "completed",
           ...outcome.taskIds.length > 0 ? { taskIds: outcome.taskIds } : {},
           ...outcome.planId !== void 0 ? { planId: outcome.planId } : {},
           ...outcome.error !== void 0 ? { error: outcome.error } : {}
@@ -2754,8 +3169,10 @@ ${contribution}`);
       run2.reports = [...allReports];
       await this.options.store.save(run2);
     }
-    const failed = [...outcomes.values()].some((o) => o.status === "failed");
-    const finalStatus = failed ? "failed" : "completed";
+    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 planId = [...outcomes.values()].find((o) => o.planId !== void 0)?.planId;
     let resultSummary;
     for (let i = def.steps.length - 1; i >= 0; i -= 1) {
@@ -2861,6 +3278,7 @@ ${contribution}`);
       )
     );
     const results = await Promise.all(created.map((task) => this.options.tasks.run(task.id)));
+    const completedTasks = results.filter((r) => r.status === "completed");
     const failedTasks = results.filter((r) => r.status !== "completed");
     const lines = results.map((result, index) => {
       const agentName = agentNames[index] ?? "unknown";
@@ -2870,12 +3288,15 @@ ${contribution}`);
     const reports = results.flatMap((r) => r.result?.reports ?? []);
     const summary = lines.join("\n");
     if (failedTasks.length > 0) {
-      const firstError = failedTasks[0]?.result?.error ?? "unknown error";
+      const firstError = failedTasks[0]?.result?.error ?? failedTasks[0]?.lastError ?? "unknown outcome";
+      const states = failedTasks.map((r) => r.status).join(", ");
       return {
-        status: "failed",
+        // Some agents succeeded → the step produced usable but incomplete
+        // intelligence: partial, not failed (roadmap §9.3).
+        status: completedTasks.length > 0 ? "partial" : "failed",
         summary,
         taskIds: created.map((t) => t.id),
-        error: `${failedTasks.length}/${results.length} task(s) failed \u2014 ${firstError}`,
+        error: `${failedTasks.length}/${results.length} task(s) incomplete (${states}) \u2014 ${firstError}`,
         reports
       };
     }
@@ -2891,7 +3312,9 @@ ${contribution}`);
     const result = await this.options.tasks.run(task.id);
     if (result.status !== "completed") {
       return {
-        status: "failed",
+        // Unknown/timed_out outcomes are not failures — the work may have
+        // happened remotely; the step is incomplete, not broken.
+        status: result.status === "unknown" || result.status === "timed_out" ? "partial" : "failed",
         summary: result.result?.summary ?? "",
         taskIds: [task.id],
         error: result.result?.error ?? `task ${task.id} did not complete`,