fix: enforce hard wall-clock timeout on runTrackedJob

Wrap the runner with Promise.race against a 30-minute default timeout.
On expiry the job transitions to failed/phase:failed so zombie
'running' rows can't accumulate when a runner hangs.

OPENCODE_COMPANION_JOB_TIMEOUT_MS overrides the default.

Closes #41. Port of openai/codex-plugin-cc#184.

Author: JohnnyVicious

plugins/opencode/scripts/lib/tracked-jobs.mjs

@@ -7,6 +7,22 @@ import { generateJobId, upsertJob, jobLogPath, jobDataPath } from "./state.mjs";
 
 const SESSION_ID_ENV = "OPENCODE_COMPANION_SESSION_ID";
 
+// Hard ceiling for any single tracked job. 30 minutes is generous enough for
+// long OpenCode turns but bounded so a hung runner cannot keep the companion
+// process alive forever. Override via OPENCODE_COMPANION_JOB_TIMEOUT_MS.
+const DEFAULT_JOB_TIMEOUT_MS = 30 * 60 * 1000;
+
+function resolveJobTimeoutMs(options = {}) {
+  if (Number.isFinite(options.timeoutMs) && options.timeoutMs > 0) {
+    return options.timeoutMs;
+  }
+  const fromEnv = Number(process.env.OPENCODE_COMPANION_JOB_TIMEOUT_MS);
+  if (Number.isFinite(fromEnv) && fromEnv > 0) {
+    return fromEnv;
+  }
+  return DEFAULT_JOB_TIMEOUT_MS;
+}
+
 /**
  * Get the current Claude session ID from environment.
  * @returns {string|undefined}
@@ -41,9 +57,10 @@ export function createJobRecord(workspacePath, type, meta = {}) {
  * @param {string} workspacePath
  * @param {object} job
  * @param {(ctx: { report: Function, log: Function }) => Promise<object>} runner
+ * @param {{ timeoutMs?: number }} [options]
  * @returns {Promise<object>} the job result
  */
-export async function runTrackedJob(workspacePath, job, runner) {
+export async function runTrackedJob(workspacePath, job, runner, options = {}) {
   // Mark as running
   upsertJob(workspacePath, { id: job.id, status: "running", pid: process.pid });
 
@@ -61,9 +78,35 @@ export async function runTrackedJob(workspacePath, job, runner) {
     appendLine(logFile, `[${new Date().toISOString()}] ${message}`);
   };
 
+  // Race the runner against a hard wall-clock timeout so a hung runner
+  // (dropped SSE stream, wedged post-response handler, unresolved downstream
+  // fetch) cannot leave the job in `running` forever. See issue #41.
+  const timeoutMs = resolveJobTimeoutMs(options);
+  let timeoutHandle = null;
+  const timeoutPromise = new Promise((_resolve, reject) => {
+    timeoutHandle = setTimeout(() => {
+      reject(
+        new Error(
+          `Tracked job ${job.id} exceeded the ${Math.round(timeoutMs / 1000)}s hard timeout. ` +
+            "The runner did not produce a terminal status. " +
+            "Set OPENCODE_COMPANION_JOB_TIMEOUT_MS to adjust."
+        )
+      );
+    }, timeoutMs);
+    timeoutHandle.unref?.();
+  });
+
+  const clearTimer = () => {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+      timeoutHandle = null;
+    }
+  };
+
   try {
     report("starting", `Job ${job.id} started`);
-    const result = await runner({ report, log });
+    const result = await Promise.race([runner({ report, log }), timeoutPromise]);
+    clearTimer();
 
     // Mark as completed
     upsertJob(workspacePath, {
@@ -81,9 +124,11 @@ export async function runTrackedJob(workspacePath, job, runner) {
     report("completed", `Job ${job.id} completed`);
     return result;
   } catch (err) {
+    clearTimer();
     upsertJob(workspacePath, {
       id: job.id,
       status: "failed",
+      phase: "failed",
       completedAt: new Date().toISOString(),
       errorMessage: err.message,
     });

tests/tracked-jobs-timeout.test.mjs

@@ -0,0 +1,80 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runTrackedJob } from "../plugins/opencode/scripts/lib/tracked-jobs.mjs";
+import { loadState } from "../plugins/opencode/scripts/lib/state.mjs";
+
+describe("runTrackedJob timeout", () => {
+  let workspace;
+  let previousPluginData;
+
+  before(() => {
+    workspace = fs.mkdtempSync(path.join(os.tmpdir(), "opencode-timeout-"));
+    previousPluginData = process.env.CLAUDE_PLUGIN_DATA;
+    process.env.CLAUDE_PLUGIN_DATA = fs.mkdtempSync(
+      path.join(os.tmpdir(), "opencode-timeout-data-")
+    );
+  });
+
+  after(() => {
+    if (previousPluginData == null) {
+      delete process.env.CLAUDE_PLUGIN_DATA;
+    } else {
+      process.env.CLAUDE_PLUGIN_DATA = previousPluginData;
+    }
+  });
+
+  it("aborts a runner that never resolves and marks the job failed", async () => {
+    const job = { id: "timeout-never-1" };
+
+    await assert.rejects(
+      runTrackedJob(
+        workspace,
+        job,
+        () => new Promise(() => {}),
+        { timeoutMs: 50 }
+      ),
+      /hard timeout/i
+    );
+
+    const state = loadState(workspace);
+    const stored = state.jobs.find((j) => j.id === job.id);
+    assert.ok(stored);
+    assert.equal(stored.status, "failed");
+    assert.equal(stored.phase, "failed");
+    assert.match(stored.errorMessage, /hard timeout/i);
+  });
+
+  it("does not fire for runners that resolve quickly", async () => {
+    const job = { id: "timeout-quick-1" };
+
+    const result = await runTrackedJob(
+      workspace,
+      job,
+      async () => ({ rendered: "ok" }),
+      { timeoutMs: 60_000 }
+    );
+
+    assert.equal(result.rendered, "ok");
+    const state = loadState(workspace);
+    const stored = state.jobs.find((j) => j.id === job.id);
+    assert.equal(stored.status, "completed");
+  });
+
+  it("honors OPENCODE_COMPANION_JOB_TIMEOUT_MS env override", async () => {
+    const previous = process.env.OPENCODE_COMPANION_JOB_TIMEOUT_MS;
+    process.env.OPENCODE_COMPANION_JOB_TIMEOUT_MS = "40";
+    try {
+      const job = { id: "timeout-env-1" };
+      await assert.rejects(
+        runTrackedJob(workspace, job, () => new Promise(() => {})),
+        /hard timeout/i
+      );
+    } finally {
+      if (previous == null) delete process.env.OPENCODE_COMPANION_JOB_TIMEOUT_MS;
+      else process.env.OPENCODE_COMPANION_JOB_TIMEOUT_MS = previous;
+    }
+  });
+});