Harden runner timeouts and docs

Author: egavrin

README.md

@@ -41,12 +41,24 @@ devagent-runner cancel <run-id>
 devagent-runner inspect <run-id>
 ```
 
+Example:
+
+```bash
+cp ../devagent-sdk/fixtures/request-plan.json /tmp/request-plan.json
+devagent-runner run --request /tmp/request-plan.json
+devagent-runner inspect <run-id>
+```
+
 ## Local Development Wiring
 
 For local MVP work this repo consumes `@devagent-sdk/*` through file dependencies from
 `../devagent-sdk`, and `devagent-hub` consumes this runner through file dependencies from
 `../devagent-runner/packages/*`.
 
+The supported local setup path is the bootstrap flow documented in
+[`devagent-hub/README.md`](../devagent-hub/README.md) and
+[`devagent-hub/BASELINE_VALIDATION.md`](../devagent-hub/BASELINE_VALIDATION.md).
+
 ## Validated Flow
 
 The runner has been validated in the canonical path:
@@ -55,8 +67,16 @@ The runner has been validated in the canonical path:
 devagent-hub -> LocalRunnerClient -> LocalRunner -> DevAgentAdapter -> devagent execute
 ```
 
-Stub smoke tests cover all four adapters, and live Hub validation has exercised the `DevAgentAdapter`
-path against a real GitHub repository.
+Adapter maturity today:
+
+- `DevAgentAdapter`
+  - live-validated and supported for the MVP path
+- `CodexAdapter`
+- `ClaudeAdapter`
+- `OpenCodeAdapter`
+  - adapter-present and smoke-tested, but still experimental
+
+Treat the experimental adapters as development surfaces, not production-equivalent executor paths.
 
 ## Development
 

bun.lock

@@ -367,6 +367,22 @@ test("local runner supports cancellation from a fresh process instance", async (
   assert.equal(result.status, "cancelled");
 });
 
+test("local runner fails a run that exceeds timeoutSec", async () => {
+  const repo = await createRepo();
+  const runner = new LocalRunner({
+    adapters: [new SleepingAdapter()],
+  });
+  const request = createRequest(repo, "task-timeout");
+  request.constraints.timeoutSec = 1;
+
+  const { runId } = await runner.startTask(request);
+  const result = await runner.awaitResult(runId);
+
+  assert.equal(result.status, "failed");
+  assert.equal(result.error?.code, "EXECUTION_FAILED");
+  assert.equal(result.error?.message, "Task exceeded timeoutSec (1)");
+});
+
 test("local runner reads finished runs from persisted metadata", async () => {
   const repo = await createRepo();
   const runner = new LocalRunner({

packages/local-runner/src/index.test.ts

@@ -17,6 +17,7 @@ import type {
   TaskExecutionResult,
   WorkspaceSpec,
 } from "@devagent-sdk/types";
+import { PROTOCOL_VERSION } from "@devagent-sdk/types";
 
 type RunMetadata = {
   runId: string;
@@ -151,6 +152,24 @@ function safeWorkspaceName(workBranch: string): string {
   return normalized || "workspace";
 }
 
+function createTimeoutResult(request: TaskExecutionRequest, startedAt: string): TaskExecutionResult {
+  return {
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: request.taskId,
+    status: "failed",
+    artifacts: [],
+    metrics: {
+      startedAt,
+      finishedAt: new Date().toISOString(),
+      durationMs: Date.now() - new Date(startedAt).getTime(),
+    },
+    error: {
+      code: "EXECUTION_FAILED",
+      message: `Task exceeded timeoutSec (${request.constraints.timeoutSec})`,
+    },
+  };
+}
+
 export class FileSystemWorkspaceManager implements WorkspaceManager {
   async prepare(spec: WorkspaceSpec): Promise<{ workspacePath: string }> {
     const runnerRoot = workspaceRootFor(spec.sourceRepoPath);
@@ -282,9 +301,35 @@ export class LocalRunner implements RunnerClient {
     await writeFile(join(runsDir, `${handle.id}.json`), JSON.stringify(metadata, null, 2));
     this.knownRuns.set(handle.id, metadata);
 
+    const startedAt = new Date().toISOString();
+    const resultPromise = handle.wait();
+    const timedPromise = request.constraints.timeoutSec && request.constraints.timeoutSec > 0
+      ? new Promise<TaskExecutionResult>((resolve) => {
+          const timeoutMs = request.constraints.timeoutSec! * 1000;
+          const timer = setTimeout(async () => {
+            try {
+              await handle.cancel();
+            } catch {
+              // Best-effort cancel.
+            }
+            const timeoutResult = createTimeoutResult(request, startedAt);
+            onEvent({
+              protocolVersion: PROTOCOL_VERSION,
+              type: "completed",
+              at: timeoutResult.metrics.finishedAt,
+              taskId: request.taskId,
+              status: timeoutResult.status,
+            });
+            resolve(timeoutResult);
+          }, timeoutMs);
+
+          void resultPromise.finally(() => clearTimeout(timer));
+        })
+      : null;
+
     const wrappedHandle = new LocalRunHandle(
       handle.id,
-      handle.wait().then(async (result: TaskExecutionResult) => {
+      Promise.race([resultPromise, ...(timedPromise ? [timedPromise] : [])]).then(async (result: TaskExecutionResult) => {
         metadata.status = result.status;
         await writeFile(resultPath, JSON.stringify(result, null, 2));
         await writeFile(join(runsDir, `${handle.id}.json`), JSON.stringify(metadata, null, 2));