claude2codex 0.1.0 → 0.3.1

package/dist/server.js

@@ -3,11 +3,12 @@
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { stat } from "fs/promises";
+import { resolve } from "path";
 import { z } from "zod";
 
 // src/contracts.ts
-import { readFile } from "fs/promises";
-import { join } from "path";
+import { statSync } from "fs";
 var PROTOCOL_INSTRUCTIONS = `## Protocol Instructions
 
 ### Execution Rules
@@ -39,25 +40,29 @@ End every task with exactly these sections:
 
 ### Rework
 For a Delta Contract, fix only its review findings and failed Success Conditions. Do not revisit work that passed review. Repeat the full Self-Verification and Required Handoff.`;
-async function optionalAgentsInstructions(cwd) {
-  try {
-    return await readFile(join(cwd, "AGENTS.md"), "utf8");
-  } catch (error) {
-    if (error?.code === "ENOENT") return void 0;
-    throw error;
-  }
+function renderContextFiles(contextFiles2) {
+  if (!contextFiles2?.length) return [];
+  return [
+    "### Context Files",
+    "Read these files before implementing. They are reference material, not necessarily files to modify.",
+    ...contextFiles2.map((contextFile) => {
+      const directory = statSync(contextFile.path).isDirectory() ? " (directory)" : "";
+      const note = contextFile.note ? ` \u2014 ${contextFile.note}` : "";
+      return `- ${contextFile.path}${directory}${note}`;
+    }),
+    ""
+  ];
 }
-async function renderGoalContract(c, cwd = process.cwd()) {
-  const agents = await optionalAgentsInstructions(cwd);
+function renderGoalContract(c) {
   const lines = [
     PROTOCOL_INSTRUCTIONS,
-    ...agents ? ["", "## Project Instructions", "", agents.trim()] : [],
     "",
     "## Goal Contract",
     "",
     "### Goal",
     c.goal.trim(),
     "",
+    ...renderContextFiles(c.context_files),
     "### Constraints",
     ...c.constraints.map((x) => `- ${x}`),
     "",
@@ -75,6 +80,7 @@ function renderDeltaContract(d) {
     "### Findings",
     ...d.findings.map((x) => `- ${x}`),
     "",
+    ...renderContextFiles(d.context_files),
     "### Failed Success Conditions",
     ...d.failed_conditions.map((x) => `- [ ] ${x}`),
     "",
@@ -84,10 +90,13 @@ function renderDeltaContract(d) {
   ];
   return lines.join("\n");
 }
-function renderObjective(c, maxLen) {
+function renderObjectiveDetails(c, maxLen) {
   const conditions = c.success_conditions.map((x) => `(${x})`).join(" ");
   const text = `Fulfill this Goal Contract: ${c.goal.trim()} The goal is achieved only when every Success Condition is verified: ${conditions} and a structured handoff (Changed Files / Validation / Success Conditions / Risks & Deviations) has been delivered.`;
-  return text.length <= maxLen ? text : text.slice(0, maxLen - 1) + "\u2026";
+  return {
+    objective: text.length <= maxLen ? text : text.slice(0, maxLen - 1) + "\u2026",
+    objectiveChars: text.length
+  };
 }
 var HANDOFF_SECTIONS = [
   "Changed Files",
@@ -126,6 +135,7 @@ var CodexAppServer = class {
   pending = /* @__PURE__ */ new Map();
   opts;
   stderrTail = [];
+  exitError;
   exited = false;
   constructor(opts) {
     this.opts = opts;
@@ -142,24 +152,26 @@ var CodexAppServer = class {
       if (this.stderrTail.length > 50) this.stderrTail.shift();
       opts.onLog?.(line);
     });
-    this.proc.on("exit", (code) => {
-      this.exited = true;
-      for (const [, p] of this.pending) {
-        clearTimeout(p.timer);
-        p.reject(new Error(`codex app-server exited (code ${code}). stderr: ${this.stderrTail.slice(-10).join(" | ")}`));
-      }
-      this.pending.clear();
-      opts.onExit?.(code);
-    });
+    this.proc.on("spawn", () => opts.onSpawn?.(this.proc.pid));
+    this.proc.on("exit", (code) => this.handleExit(code));
     this.proc.on("error", (err) => {
-      this.exited = true;
-      for (const [, p] of this.pending) {
-        clearTimeout(p.timer);
-        p.reject(new Error(`failed to spawn ${opts.bin}: ${err.message}`));
-      }
-      this.pending.clear();
+      this.handleExit(null, new Error(`failed to spawn ${opts.bin}: ${err.message}`));
     });
   }
+  handleExit(code, error) {
+    if (this.exited) return;
+    this.exited = true;
+    const stderr = this.stderrTail.slice(-10).join(" | ");
+    this.exitError = error ?? new Error(
+      `codex app-server exited (code ${code})${stderr ? `. stderr: ${stderr}` : ""}`
+    );
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(this.exitError);
+    }
+    this.pending.clear();
+    this.opts.onExit?.(code, this.exitError);
+  }
   handleLine(line) {
     const trimmed = line.trim();
     if (!trimmed) return;
@@ -192,13 +204,16 @@ var CodexAppServer = class {
     this.proc.stdin.write(JSON.stringify(obj) + "\n");
   }
   request(method, params, timeoutMs = 6e4) {
+    if (this.exited) {
+      return Promise.reject(this.exitError ?? new Error("codex app-server is not running"));
+    }
     const id = this.nextId++;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
         reject(new Error(`request ${method} timed out after ${timeoutMs}ms`));
       }, timeoutMs);
-      this.pending.set(id, { resolve, reject, timer });
+      this.pending.set(id, { resolve: resolve2, reject, timer });
       this.send({ id, method, ...params !== void 0 ? { params } : {} });
     });
   }
@@ -207,7 +222,7 @@ var CodexAppServer = class {
   }
   async initialize() {
     const result = await this.request("initialize", {
-      clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.1.0" },
+      clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.3.1" },
       capabilities: { experimentalApi: true }
     });
     this.notify("initialized", {});
@@ -218,25 +233,178 @@ var CodexAppServer = class {
   }
 };
 
+// src/log.ts
+var priorities = { error: 1, info: 2, debug: 3 };
+function configuredLevel() {
+  const value = process.env.C2C_LOG_LEVEL;
+  return value === "silent" || value === "error" || value === "info" || value === "debug" ? value : "info";
+}
+function writeLog(level, event, fields = {}) {
+  const configured = configuredLevel();
+  if (configured === "silent" || priorities[level] > priorities[configured]) return;
+  process.stderr.write(`${JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), level, event, ...fields })}
+`);
+}
+
+// src/store.ts
+import { accessSync, constants, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var MAX_JOBS = 50;
+var warned = false;
+function warnOnce(error) {
+  if (warned) return;
+  warned = true;
+  writeLog("error", "persistence_degraded", {
+    error: error instanceof Error ? error.message : String(error)
+  });
+}
+function defaultStateDir() {
+  return process.env.C2C_STATE_DIR ?? join(homedir(), ".claude2codex", "jobs");
+}
+function createJobStore(dir = defaultStateDir()) {
+  const records = /* @__PURE__ */ new Map();
+  let enabled = true;
+  try {
+    mkdirSync(dir, { recursive: true });
+    accessSync(dir, constants.R_OK | constants.W_OK);
+    const interrupted = [];
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".json")) continue;
+      try {
+        const job = JSON.parse(readFileSync(join(dir, name), "utf8"));
+        if (!job?.id || !job?.startedAt || !Array.isArray(job.transcript)) continue;
+        if (job.state === "blocked" || job.state === "queued" || job.state === "starting" || job.state === "running") {
+          job.state = "error";
+          job.error = "interrupted by server restart";
+          job.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+          interrupted.push(job);
+        }
+        records.set(job.id, job);
+      } catch {
+      }
+    }
+    for (const job of interrupted) atomicWrite(dir, job);
+    prune(dir, records);
+  } catch (error) {
+    enabled = false;
+    warnOnce(error);
+  }
+  return {
+    getJob: (id) => records.get(id),
+    listJobs: () => [...records.values()],
+    save(job) {
+      const record = { ...job, transcript: job.transcript.slice(-200) };
+      records.set(job.id, record);
+      if (!enabled) return;
+      try {
+        atomicWrite(dir, record);
+        prune(dir, records);
+      } catch (error) {
+        enabled = false;
+        warnOnce(error);
+      }
+    }
+  };
+}
+function atomicWrite(dir, job) {
+  const target = join(dir, `${job.id}.json`);
+  const temp = join(dir, `.${job.id}.${process.pid}.${Date.now()}.tmp`);
+  writeFileSync(temp, JSON.stringify(job), { encoding: "utf8", mode: 384 });
+  renameSync(temp, target);
+}
+function prune(dir, records) {
+  const entries = [...records.values()].sort(
+    (a, b) => Date.parse(b.endedAt ?? b.startedAt) - Date.parse(a.endedAt ?? a.startedAt)
+  );
+  for (const job of entries.slice(MAX_JOBS)) {
+    records.delete(job.id);
+    try {
+      unlinkSync(join(dir, `${job.id}.json`));
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+}
+
 // src/jobs.ts
-var jobs = /* @__PURE__ */ new Map();
+var store = createJobStore();
+var jobs = new Map(store.listJobs().map((job) => [job.id, job]));
 function getJob(id) {
-  return jobs.get(id);
+  return jobs.get(id) ?? store.getJob(id);
+}
+function listJobs() {
+  return [...jobs.values()];
+}
+var queue = [];
+var blocked = /* @__PURE__ */ new Map();
+function getQueuePosition(id) {
+  const index = queue.findIndex((entry) => entry.job.id === id);
+  return index === -1 ? void 0 : index + 1;
+}
+function activeJobCount() {
+  return [...jobs.values()].filter((job) => job.state === "starting" || job.state === "running").length;
+}
+function launch(job, opts) {
+  void runJob(job, opts).catch((err) => {
+    finish(job, "error", void 0, String(err?.message ?? err));
+  });
+}
+function drainQueue() {
+  while (queue.length > 0 && activeJobCount() < queue[0].opts.config.maxConcurrent) {
+    const { job, opts } = queue.shift();
+    job.state = "starting";
+    log(job, "queue", "dequeued; starting job");
+    store.save(job);
+    writeLog("info", "job_dequeued", { job_id: job.id, kind: job.kind });
+    opts.onProgress?.({ jobId: job.id, event: "dequeued", message: "job dequeued; starting" });
+    launch(job, opts);
+  }
 }
 function startJob(opts) {
+  const dependency = opts.dependsOn ? getJob(opts.dependsOn) : void 0;
+  if (opts.dependsOn && !dependency) throw new Error(`unknown depends_on job_id ${opts.dependsOn}`);
+  if (dependency?.state === "error" || dependency?.state === "timeout") {
+    throw new Error(dependencyFailureMessage(dependency));
+  }
+  const isBlocked = dependency !== void 0 && dependency.state !== "done";
+  const queued = !isBlocked && (queue.length > 0 || activeJobCount() >= opts.config.maxConcurrent);
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
   const job = {
     id: randomUUID().slice(0, 8),
     kind: opts.kind,
-    state: "starting",
+    state: isBlocked ? "blocked" : queued ? "queued" : "starting",
     goalSet: false,
+    usage: {},
+    attempts: 1,
     turns: 0,
     transcript: [],
-    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    ...opts.contextFiles ? { contextFiles: opts.contextFiles } : {},
+    ...opts.dependsOn ? { dependsOn: opts.dependsOn } : {},
+    startedAt,
+    lastActivityAt: startedAt
   };
   jobs.set(job.id, job);
-  void runJob(job, opts).catch((err) => {
-    finish(job, "error", void 0, String(err?.message ?? err));
-  });
+  if (isBlocked) {
+    const dependents = blocked.get(opts.dependsOn) ?? [];
+    dependents.push({ job, opts });
+    blocked.set(opts.dependsOn, dependents);
+    log(job, "blocked", `blocked on dependency ${opts.dependsOn}`);
+  } else if (queued) {
+    queue.push({ job, opts });
+    log(job, "queue", `enqueued at position ${queue.length}`);
+  }
+  store.save(job);
+  writeLog("info", "job_created", { job_id: job.id, kind: job.kind, state: job.state });
+  if (isBlocked) {
+    writeLog("info", "job_blocked", { job_id: job.id, kind: job.kind, depends_on: opts.dependsOn });
+    opts.onProgress?.({ jobId: job.id, event: "blocked", message: `blocked on dependency ${opts.dependsOn}` });
+  } else if (queued) {
+    writeLog("info", "job_enqueued", { job_id: job.id, kind: job.kind, queue_position: queue.length });
+    opts.onProgress?.({ jobId: job.id, event: "queued", message: `job queued at position ${queue.length}` });
+  } else {
+    launch(job, opts);
+  }
   return job;
 }
 function log(job, kind, detail) {
@@ -245,11 +413,73 @@ function log(job, kind, detail) {
 }
 function finish(job, state, client, error) {
   if (job.state === "done" || job.state === "error" || job.state === "timeout") return;
+  const previousState = job.state;
   job.state = state;
   job.error = error;
   job.endedAt = (/* @__PURE__ */ new Date()).toISOString();
   if (job.finalMessage) job.handoff = parseHandoff(job.finalMessage);
+  store.save(job);
+  writeLog(state === "error" || state === "timeout" ? "error" : "info", "job_state_changed", {
+    job_id: job.id,
+    from: previousState,
+    to: state,
+    ...error ? { error } : {}
+  });
+  writeLog("info", "job_usage", {
+    job_id: job.id,
+    state,
+    usage: job.usage ?? {}
+  });
   client?.kill();
+  resolveDependents(job);
+  drainQueue();
+}
+function dependencyFailureMessage(dependency) {
+  return `dependency ${dependency.id} failed: ${dependency.error ?? `state ${dependency.state}`}`;
+}
+function resolveDependents(dependency) {
+  const dependents = blocked.get(dependency.id);
+  if (!dependents?.length) return;
+  blocked.delete(dependency.id);
+  for (const { job, opts } of dependents) {
+    if (dependency.state === "done") {
+      log(job, "unblocked", `dependency ${dependency.id} completed; unblocked`);
+      store.save(job);
+      writeLog("info", "job_unblocked", { job_id: job.id, depends_on: dependency.id });
+      opts.onProgress?.({
+        jobId: job.id,
+        event: "unblocked",
+        message: `dependency ${dependency.id} completed; job unblocked`
+      });
+      enqueueOrLaunch(job, opts);
+    } else {
+      const error = dependencyFailureMessage(dependency);
+      log(job, "dependency_failed", error);
+      store.save(job);
+      writeLog("info", "job_dependency_failed", {
+        job_id: job.id,
+        depends_on: dependency.id,
+        error
+      });
+      opts.onProgress?.({ jobId: job.id, event: "dependency_failed", message: error });
+      finish(job, "error", void 0, error);
+    }
+  }
+}
+function enqueueOrLaunch(job, opts) {
+  if (queue.length > 0 || activeJobCount() >= opts.config.maxConcurrent) {
+    job.state = "queued";
+    queue.push({ job, opts });
+    log(job, "queue", `enqueued at position ${queue.length} after dependency completed`);
+    store.save(job);
+    writeLog("info", "job_enqueued", { job_id: job.id, kind: job.kind, queue_position: queue.length });
+    opts.onProgress?.({ jobId: job.id, event: "queued", message: `job queued at position ${queue.length}` });
+    drainQueue();
+    return;
+  }
+  job.state = "starting";
+  store.save(job);
+  launch(job, opts);
 }
 function extractText(item) {
   if (typeof item?.text === "string") return item.text;
@@ -270,23 +500,96 @@ function extractGoal(params) {
     timeUsedSeconds: g.timeUsedSeconds ?? g.time_used_seconds
   };
 }
+var usageAliases = {
+  input_tokens: "inputTokens",
+  input_token_count: "inputTokens",
+  output_tokens: "outputTokens",
+  output_token_count: "outputTokens",
+  total_tokens: "totalTokens",
+  total_token_count: "totalTokens",
+  tokensUsed: "totalTokens",
+  tokens_used: "totalTokens"
+};
+function extractUsage(params) {
+  const source = params?.turn?.usage ?? params?.usage ?? params?.turn?.tokenUsage ?? params?.tokenUsage;
+  if (!source || typeof source !== "object") return void 0;
+  const usage = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (typeof value === "number" && Number.isFinite(value)) usage[usageAliases[key] ?? key] = value;
+  }
+  return Object.keys(usage).length ? usage : void 0;
+}
+function mergeUsage(job, usage, cumulative = false) {
+  if (!usage) return;
+  job.usage ??= {};
+  for (const [key, value] of Object.entries(usage)) {
+    job.usage[key] = cumulative ? value : (job.usage[key] ?? 0) + value;
+  }
+}
+function updateGoal(job, params) {
+  job.goal = extractGoal(params);
+  if (typeof job.goal.tokensUsed === "number") {
+    mergeUsage(job, { totalTokens: job.goal.tokensUsed }, true);
+  }
+  store.save(job);
+}
 var TERMINAL_GOAL_STATUSES = /* @__PURE__ */ new Set(["complete", "budget_limited", "budgetLimited"]);
 async function runJob(job, opts) {
+  const deadline = Date.now() + opts.config.jobTimeoutMs;
+  const maxAttempts = (opts.config.retries ?? 1) + 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    job.attempts = attempt;
+    log(job, "attempt", `attempt ${attempt} started`);
+    store.save(job);
+    writeLog("info", "job_attempt_started", { job_id: job.id, attempt });
+    const result = await runAttempt(job, opts, Math.max(0, deadline - Date.now()));
+    if (!result.error || job.state === "done" || job.state === "error" || job.state === "timeout") return;
+    const retryable = result.processFailure && job.state === "starting" && job.turns === 0;
+    if (!retryable || attempt === maxAttempts) {
+      finish(job, "error", void 0, result.error.message);
+      return;
+    }
+    log(job, "retry", `attempt ${attempt} failed before the first turn; retrying in 500ms`);
+    store.save(job);
+    writeLog("info", "job_retry_scheduled", {
+      job_id: job.id,
+      attempt,
+      next_attempt: attempt + 1,
+      delay_ms: 500,
+      error: result.error.message
+    });
+    await new Promise((resolve2) => setTimeout(resolve2, 500));
+  }
+}
+async function runAttempt(job, opts, timeoutMs) {
   const cfg = opts.config;
   let activeTurn = false;
+  let stalled = false;
+  let processError;
   let quietTimer;
+  let stallTimer;
   let settle;
   const doneSignal = new Promise((res) => settle = res);
   const progress = (event, message) => opts.onProgress?.({ jobId: job.id, event, message });
+  if (!opts.resumeThreadId) job.goalSet = false;
   const client = new CodexAppServer({
     bin: cfg.bin,
     args: cfg.args,
     cwd: cfg.cwd,
     onLog: (line) => log(job, "log", line),
-    onExit: (code) => {
-      if (job.state === "starting" || job.state === "running") {
-        finish(job, "error", void 0, `codex app-server exited early (code ${code})`);
-      }
+    onSpawn: (pid) => writeLog("info", "codex_process_spawn", {
+      job_id: job.id,
+      attempt: job.attempts ?? 1,
+      ...pid === void 0 ? {} : { pid }
+    }),
+    onExit: (code, error) => {
+      writeLog(job.state === "starting" || job.state === "running" ? "error" : "info", "codex_process_exit", {
+        job_id: job.id,
+        attempt: job.attempts ?? 1,
+        code,
+        error: error.message
+      });
+      if (job.state === "starting" || job.state === "running") processError = error;
       settle();
     },
     onNotification: (method, params) => handleNotification(method, params)
@@ -295,18 +598,73 @@ async function runJob(job, opts) {
     clearTimeout(quietTimer);
     quietTimer = setTimeout(() => {
       log(job, "quiet", `no goal continuation within ${cfg.quietMs}ms; treating turn as final`);
-      finish(job, "done", client);
+      finalize("done");
       settle();
     }, cfg.quietMs);
   }
+  function clearStallTimer() {
+    clearTimeout(stallTimer);
+    stallTimer = void 0;
+  }
+  function armStallTimer() {
+    clearStallTimer();
+    if (cfg.stallWarnMs === 0 || !activeTurn || stalled || !job.lastActivityAt) return;
+    const stalledForMs = Math.max(0, Date.now() - Date.parse(job.lastActivityAt));
+    stallTimer = setTimeout(checkForStall, Math.max(0, cfg.stallWarnMs - stalledForMs));
+  }
+  function checkForStall() {
+    stallTimer = void 0;
+    if (!activeTurn || stalled || !job.lastActivityAt) return;
+    const stalledForMs = Math.max(0, Date.now() - Date.parse(job.lastActivityAt));
+    if (stalledForMs < cfg.stallWarnMs) {
+      armStallTimer();
+      return;
+    }
+    stalled = true;
+    log(job, "stalled", `no Codex activity for ${stalledForMs}ms`);
+    store.save(job);
+    writeLog("info", "job_stalled", { job_id: job.id, stalled_for_ms: stalledForMs });
+    progress("stalled", `job stalled for ${stalledForMs}ms`);
+  }
+  function recordActivity() {
+    const now = /* @__PURE__ */ new Date();
+    if (stalled && job.lastActivityAt) {
+      const stalledForMs = Math.max(0, now.getTime() - Date.parse(job.lastActivityAt));
+      stalled = false;
+      log(job, "resumed", `Codex activity resumed after ${stalledForMs}ms`);
+      writeLog("info", "job_resumed", { job_id: job.id, stalled_for_ms: stalledForMs });
+      progress("resumed", `job resumed after ${stalledForMs}ms`);
+    }
+    job.lastActivityAt = now.toISOString();
+    store.save(job);
+    if (activeTurn) armStallTimer();
+  }
+  function finalize(state, error) {
+    clearStallTimer();
+    finish(job, state, client, error);
+  }
   function handleNotification(method, params) {
+    writeLog("debug", "codex_notification", {
+      job_id: job.id,
+      attempt: job.attempts ?? 1,
+      method,
+      params: params ?? null
+    });
+    recordActivity();
     const p = params ?? {};
     switch (method) {
       case "turn/started": {
         activeTurn = true;
+        armStallTimer();
         job.turns += 1;
         clearTimeout(quietTimer);
+        if (job.state === "starting") {
+          job.state = "running";
+          store.save(job);
+          writeLog("info", "job_state_changed", { job_id: job.id, from: "starting", to: "running" });
+        }
         log(job, "turn", `turn ${job.turns} started`);
+        writeLog("info", "turn_started", { job_id: job.id, turn: job.turns });
         progress("turn_started", `turn ${job.turns} started`);
         break;
       }
@@ -328,11 +686,16 @@ async function runJob(job, opts) {
         break;
       }
       case "thread/goal/updated": {
-        job.goal = extractGoal(p);
-        log(job, "goal", `status=${job.goal.status} tokensUsed=${job.goal.tokensUsed ?? "?"}`);
-        progress("goal_updated", `goal status=${job.goal.status ?? "unknown"}`);
-        if (job.goal.status && TERMINAL_GOAL_STATUSES.has(job.goal.status) && !activeTurn) {
-          finish(job, "done", client);
+        updateGoal(job, p);
+        log(job, "goal", `status=${job.goal?.status} tokensUsed=${job.goal?.tokensUsed ?? "?"}`);
+        writeLog("info", "goal_updated", {
+          job_id: job.id,
+          status: job.goal?.status ?? null,
+          tokens_used: job.goal?.tokensUsed ?? null
+        });
+        progress("goal_updated", `goal status=${job.goal?.status ?? "unknown"}`);
+        if (job.goal?.status && TERMINAL_GOAL_STATUSES.has(job.goal.status) && !activeTurn) {
+          finalize("done");
           settle();
         }
         break;
@@ -340,8 +703,12 @@ async function runJob(job, opts) {
       case "turn/completed":
       case "turn/failed": {
         activeTurn = false;
+        clearStallTimer();
+        mergeUsage(job, extractUsage(p));
+        store.save(job);
         const status = p.turn?.status ?? (method === "turn/failed" ? "failed" : "completed");
         log(job, "turn", `turn ended (${status})`);
+        writeLog("info", "turn_ended", { job_id: job.id, turn: job.turns, status });
         progress("turn_ended", `turn ended (${status})`);
         void onTurnEnded();
         break;
@@ -352,21 +719,21 @@ async function runJob(job, opts) {
   }
   async function onTurnEnded() {
     if (!job.goalSet) {
-      finish(job, "done", client);
+      finalize("done");
       settle();
       return;
     }
     if (job.goal?.status && TERMINAL_GOAL_STATUSES.has(job.goal.status)) {
-      finish(job, "done", client);
+      finalize("done");
       settle();
       return;
     }
     try {
       const res = await client.request("thread/goal/get", { threadId: job.threadId }, 15e3);
       if (res?.goal) {
-        job.goal = extractGoal(res);
-        if (job.goal.status && TERMINAL_GOAL_STATUSES.has(job.goal.status)) {
-          finish(job, "done", client);
+        updateGoal(job, res);
+        if (job.goal?.status && TERMINAL_GOAL_STATUSES.has(job.goal.status)) {
+          finalize("done");
           settle();
           return;
         }
@@ -377,9 +744,9 @@ async function runJob(job, opts) {
     if (!activeTurn) armQuietTimer();
   }
   const overallTimer = setTimeout(() => {
-    finish(job, "timeout", client, `job exceeded ${cfg.jobTimeoutMs}ms`);
+    finalize("timeout", `job exceeded ${cfg.jobTimeoutMs}ms`);
     settle();
-  }, cfg.jobTimeoutMs);
+  }, timeoutMs);
   try {
     await client.initialize();
     const threadParams = {
@@ -399,6 +766,7 @@ async function runJob(job, opts) {
       job.threadId = threadRes?.thread?.id ?? threadRes?.id;
     }
     if (!job.threadId) throw new Error(`could not determine thread id from ${JSON.stringify(threadRes).slice(0, 300)}`);
+    store.save(job);
     log(job, "thread", `thread ${job.threadId} ${opts.resumeThreadId ? "resumed" : "started"}`);
     if (opts.objective) {
       try {
@@ -408,24 +776,29 @@ async function runJob(job, opts) {
           ...opts.tokenBudget ? { tokenBudget: opts.tokenBudget } : {}
         });
         job.goalSet = true;
-        job.goal = extractGoal(goalRes);
-        log(job, "goal", `goal set (status=${job.goal.status ?? "active"})`);
-        progress("goal_updated", `goal status=${job.goal.status ?? "active"}`);
+        updateGoal(job, goalRes);
+        log(job, "goal", `goal set (status=${job.goal?.status ?? "active"})`);
+        progress("goal_updated", `goal status=${job.goal?.status ?? "active"}`);
       } catch (err) {
+        if (client.exited) throw err;
         log(job, "goal", `thread/goal/set failed (${err?.message ?? err}); continuing without goal loop`);
         job.goalSet = false;
       }
     }
-    job.state = "running";
     await client.request("turn/start", {
       threadId: job.threadId,
       input: [{ type: "text", text: opts.prompt }],
       ...opts.reasoningEffort ? { effort: opts.reasoningEffort } : {}
     });
     await doneSignal;
+    return processError ? { error: processError, processFailure: true } : { processFailure: false };
+  } catch (error) {
+    const failure = processError ?? (error instanceof Error ? error : new Error(String(error)));
+    return { error: failure, processFailure: client.exited };
   } finally {
     clearTimeout(overallTimer);
     clearTimeout(quietTimer);
+    clearStallTimer();
     client.kill();
   }
 }
@@ -463,10 +836,14 @@ function config(cwd) {
     approvalPolicy: process.env.CODEX_APPROVAL_POLICY ?? "never",
     permissions: process.env.CODEX_PERMISSIONS || void 0,
     jobTimeoutMs: envInt("CODEX_JOB_TIMEOUT_MS", 18e5),
-    quietMs: envInt("CODEX_QUIET_MS", 3e4)
+    quietMs: envInt("CODEX_QUIET_MS", 3e4),
+    stallWarnMs: Math.max(0, envInt("C2C_STALL_WARN_MS", 12e4)),
+    retries: Math.max(0, envInt("C2C_RETRIES", 1)),
+    maxConcurrent: Math.max(1, envInt("C2C_MAX_CONCURRENT", 2))
   };
 }
 var OBJECTIVE_MAX = envInt("GOAL_OBJECTIVE_MAX", 2e3);
+var objectiveBudgetDescription = `The rendered thread-goal objective has a GOAL_OBJECTIVE_MAX budget of ${OBJECTIVE_MAX} characters; over-limit calls are rejected.`;
 function jobSummary(job, transcriptTail = 15) {
   return {
     job_id: job.id,
@@ -474,10 +851,17 @@ function jobSummary(job, transcriptTail = 15) {
     state: job.state,
     thread_id: job.threadId ?? null,
     goal: job.goal ?? null,
+    usage: job.usage ?? {},
+    attempts: job.attempts ?? 1,
     turns: job.turns,
     started_at: job.startedAt,
     ended_at: job.endedAt ?? null,
     error: job.error ?? null,
+    ...!["done", "error", "timeout"].includes(job.state) ? { last_activity_at: job.lastActivityAt ?? null } : {},
+    ...job.state === "running" && job.lastActivityAt ? { seconds_since_activity: Math.max(0, (Date.now() - Date.parse(job.lastActivityAt)) / 1e3) } : {},
+    ...job.contextFiles ? { context_files: job.contextFiles } : {},
+    ...job.dependsOn ? { depends_on: job.dependsOn } : {},
+    ...job.state === "queued" ? { queue_position: getQueuePosition(job.id) ?? null } : {},
     transcript_tail: job.transcript.slice(-transcriptTail)
   };
 }
@@ -487,8 +871,53 @@ function textResult(obj, isError = false) {
     isError
   };
 }
-var server = new McpServer({ name: "c2c-codex", version: "0.1.0" });
+var server = new McpServer({ name: "c2c-codex", version: "0.3.1" });
 var reasoningEffort = z.enum(["low", "medium", "high", "xhigh", "max", "ultra"]);
+var contextFiles = z.array(z.object({
+  path: z.string().min(1),
+  note: z.string().optional()
+}));
+async function resolveContextFiles(files, cwd) {
+  if (!files?.length) return { files: void 0, missing: [] };
+  const resolved = files.map((file) => ({ ...file, path: resolve(cwd, file.path) }));
+  const exists = await Promise.all(resolved.map(async (file) => {
+    try {
+      await stat(file.path);
+      return true;
+    } catch {
+      return false;
+    }
+  }));
+  return {
+    files: resolved,
+    missing: resolved.filter((_, index) => !exists[index]).map((file) => file.path)
+  };
+}
+function missingContextFiles(paths) {
+  return textResult({ error: `context_files not found:
+${paths.map((path) => `- ${path}`).join("\n")}` }, true);
+}
+function implementHistory() {
+  const totals = listJobs().filter((job) => job.kind === "implement" && job.state === "done").map((job) => job.usage?.totalTokens).filter((total) => typeof total === "number" && Number.isFinite(total)).sort((a, b) => a - b);
+  if (!totals.length) return null;
+  const middle = Math.floor(totals.length / 2);
+  const median = totals.length % 2 ? totals[middle] : (totals[middle - 1] + totals[middle]) / 2;
+  return {
+    samples: totals.length,
+    median_total_tokens: Math.round(median),
+    p90_total_tokens: Math.round(totals[Math.ceil(totals.length * 0.9) - 1]),
+    mean_total_tokens: Math.round(totals.reduce((sum, total) => sum + total, 0) / totals.length)
+  };
+}
+function dependencyValidationError(dependsOn) {
+  if (!dependsOn) return void 0;
+  const dependency = getJob(dependsOn);
+  if (!dependency) return `unknown depends_on job_id ${dependsOn}`;
+  if (dependency.state === "error" || dependency.state === "timeout") {
+    return `dependency ${dependency.id} failed: ${dependency.error ?? `state ${dependency.state}`}`;
+  }
+  return void 0;
+}
 function progressReporter() {
   let sequence = 0;
   return (event) => {
@@ -509,26 +938,42 @@ server.registerTool(
     title: "Delegate a Goal Contract to Codex",
     description: "Start a Codex implementation job for a Goal Contract. Sets the contract as a Codex thread goal (the /goal loop keeps Codex iterating until the objective is achieved or the token budget is hit) and sends the full contract as the first turn. Returns a job_id immediately; poll codex_status, then fetch codex_result when done. Language-agnostic: verification commands come from the contract's Success Conditions, not from this server.",
     inputSchema: {
-      goal: z.string().min(1).describe("What the code must do when this task is done."),
+      goal: z.string().min(1).describe(`What the code must do when this task is done. ${objectiveBudgetDescription}`),
       constraints: z.array(z.string()).describe("Technical boundaries: files to touch, patterns to follow, 'Do not modify' lists."),
-      success_conditions: z.array(z.string()).min(1).describe("Checkable criteria proving the goal is met. At least one must be a runnable command/test."),
+      success_conditions: z.array(z.string()).min(1).describe(`Checkable criteria proving the goal is met. At least one must be a runnable command/test. ${objectiveBudgetDescription}`),
       token_budget: z.number().int().positive().optional().describe("Optional token budget for the Codex goal loop (thread/goal/set tokenBudget)."),
       cwd: z.string().optional().describe("Working directory for Codex. Defaults to the project directory."),
+      context_files: contextFiles.optional().describe("Files or directories Codex should read before implementing."),
+      depends_on: z.string().min(1).optional().describe("Job id of a prior job that must succeed before this job starts."),
       reasoning_effort: reasoningEffort.optional().describe("Optional Codex reasoning effort; omitted uses the Codex default.")
     }
   },
   async (input) => {
+    const jobConfig = config(input.cwd);
+    const resolvedContext = await resolveContextFiles(input.context_files, jobConfig.cwd);
+    if (resolvedContext.missing.length) return missingContextFiles(resolvedContext.missing);
     const contract = {
       goal: input.goal,
       constraints: input.constraints,
-      success_conditions: input.success_conditions
+      success_conditions: input.success_conditions,
+      context_files: resolvedContext.files
     };
-    const jobConfig = config(input.cwd);
+    const prompt = renderGoalContract(contract);
+    const dependencyError = dependencyValidationError(input.depends_on);
+    if (dependencyError) return textResult({ error: dependencyError }, true);
+    const renderedObjective = renderObjectiveDetails(contract, OBJECTIVE_MAX);
+    if (renderedObjective.objectiveChars > OBJECTIVE_MAX) {
+      return textResult({
+        error: `Rendered objective is ${renderedObjective.objectiveChars} characters, exceeding the GOAL_OBJECTIVE_MAX limit of ${OBJECTIVE_MAX}. Shorten goal or success_conditions, or raise GOAL_OBJECTIVE_MAX.`
+      }, true);
+    }
     const job = startJob({
       kind: "implement",
-      prompt: await renderGoalContract(contract, jobConfig.cwd),
-      objective: renderObjective(contract, OBJECTIVE_MAX),
+      prompt,
+      objective: renderedObjective.objective,
       tokenBudget: input.token_budget,
+      contextFiles: resolvedContext.files?.map((file) => file.path),
+      dependsOn: input.depends_on,
       config: jobConfig,
       reasoningEffort: input.reasoning_effort,
       onProgress: progressReporter()
@@ -536,7 +981,46 @@ server.registerTool(
     return textResult({
       job_id: job.id,
       state: job.state,
-      note: "Job started. Poll codex_status until state is 'done', then call codex_result."
+      note: job.state === "blocked" ? `Job blocked on dependency ${job.dependsOn}. Poll codex_status for its state.` : job.state === "queued" ? "Job queued. Poll codex_status for its queue position and state." : "Job started. Poll codex_status until state is 'done', then call codex_result."
+    });
+  }
+);
+server.registerTool(
+  "codex_estimate",
+  {
+    title: "Estimate a Goal Contract's token cost",
+    description: "Read-only estimate made before starting a job. Measures the fully rendered Goal Contract prompt and returns approx_prompt_tokens using an approximate characters/4 heuristic, plus local completed-job history.",
+    inputSchema: {
+      goal: z.string().min(1).describe(`What the code must do when this task is done. ${objectiveBudgetDescription}`),
+      constraints: z.array(z.string()).describe("Technical boundaries: files to touch, patterns to follow, 'Do not modify' lists."),
+      success_conditions: z.array(z.string()).min(1).describe(`Checkable criteria proving the goal is met. At least one must be a runnable command/test. ${objectiveBudgetDescription}`),
+      cwd: z.string().optional().describe("Working directory used to resolve relative context_files paths. Defaults to the project directory."),
+      context_files: contextFiles.optional().describe("Files or directories included in the rendered prompt.")
+    },
+    annotations: { readOnlyHint: true }
+  },
+  async (input) => {
+    const jobConfig = config(input.cwd);
+    const resolvedContext = await resolveContextFiles(input.context_files, jobConfig.cwd);
+    if (resolvedContext.missing.length) return missingContextFiles(resolvedContext.missing);
+    const contract = {
+      goal: input.goal,
+      constraints: input.constraints,
+      success_conditions: input.success_conditions,
+      context_files: resolvedContext.files
+    };
+    const prompt = renderGoalContract(contract);
+    const renderedObjective = renderObjectiveDetails(contract, OBJECTIVE_MAX);
+    const history = implementHistory();
+    return textResult({
+      prompt_chars: prompt.length,
+      approx_prompt_tokens: Math.ceil(prompt.length / 4),
+      objective_chars: renderedObjective.objectiveChars,
+      objective_max_chars: OBJECTIVE_MAX,
+      objective_over_limit: renderedObjective.objectiveChars > OBJECTIVE_MAX,
+      history,
+      estimated_total_tokens: history?.median_total_tokens ?? null,
+      note: history ? "Estimated total tokens are based on local history and vary with task complexity." : "No completed implement job history is available; estimates based on local history vary with task complexity."
     });
   }
 );
@@ -552,10 +1036,14 @@ server.registerTool(
       failed_conditions: z.array(z.string()).describe("The specific Success Conditions from the original contract that did not pass."),
       constraints: z.array(z.string()).optional().describe("Additional constraints beyond the originals."),
       cwd: z.string().optional().describe("Working directory for Codex. Defaults to the project directory."),
+      context_files: contextFiles.optional().describe("Files or directories Codex should read before implementing."),
       reasoning_effort: reasoningEffort.optional().describe("Optional Codex reasoning effort; omitted uses the Codex default.")
     }
   },
   async (input) => {
+    const jobConfig = config(input.cwd);
+    const resolvedContext = await resolveContextFiles(input.context_files, jobConfig.cwd);
+    if (resolvedContext.missing.length) return missingContextFiles(resolvedContext.missing);
     let threadId = input.thread_id;
     if (!threadId && input.job_id) {
       const prev = getJob(input.job_id);
@@ -570,10 +1058,12 @@ server.registerTool(
       prompt: renderDeltaContract({
         findings: input.findings,
         failed_conditions: input.failed_conditions,
-        constraints: input.constraints
+        constraints: input.constraints,
+        context_files: resolvedContext.files
       }),
       resumeThreadId: threadId,
-      config: config(input.cwd),
+      contextFiles: resolvedContext.files?.map((file) => file.path),
+      config: jobConfig,
       reasoningEffort: input.reasoning_effort,
       onProgress: progressReporter()
     });
@@ -581,7 +1071,7 @@ server.registerTool(
       job_id: job.id,
       resumed_thread_id: threadId,
       state: job.state,
-      note: "Rework job started. Poll codex_status until state is 'done', then call codex_result."
+      note: job.state === "queued" ? "Rework job queued. Poll codex_status for its queue position and state." : "Rework job started. Poll codex_status until state is 'done', then call codex_result."
     });
   }
 );
@@ -601,7 +1091,7 @@ server.registerTool(
   "codex_status",
   {
     title: "Check a Codex job",
-    description: "Status of a running or finished Codex job: state, thread id, goal state (status/tokens), turn count, and a tail of the activity transcript.",
+    description: "Status of a blocked, queued, running, or finished Codex job: dependency, state, queue position, thread id, goal state (status/tokens), turn count, and a tail of the activity transcript.",
     inputSchema: {
       job_id: z.string().describe("Job id returned by codex_implement or codex_rework.")
     }
@@ -616,7 +1106,7 @@ server.registerTool(
   "codex_result",
   {
     title: "Fetch a finished Codex job's handoff",
-    description: "Final result of a finished job: Codex's final message, the parsed structured handoff (Changed Files / Validation / Success Conditions / Risks & Deviations \u2014 a missing section is itself a review failure), and final goal state. Errors if the job is still running.",
+    description: "Final result of a finished job: Codex's final message, the parsed structured handoff (Changed Files / Validation / Success Conditions / Risks & Deviations \u2014 a missing section is itself a review failure), and final goal state. Errors if the job is not finished.",
     inputSchema: {
       job_id: z.string().describe("Job id returned by codex_implement or codex_rework.")
     }
@@ -624,7 +1114,7 @@ server.registerTool(
   async (input) => {
     const job = getJob(input.job_id);
     if (!job) return textResult({ error: `unknown job_id ${input.job_id}` }, true);
-    if (job.state === "starting" || job.state === "running") {
+    if (job.state === "blocked" || job.state === "queued" || job.state === "starting" || job.state === "running") {
       return textResult({ error: `job ${job.id} is still ${job.state}; poll codex_status` }, true);
     }
     return textResult({