@davidvornholt/standards 0.17.1 → 0.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -81,6 +81,7 @@
     "src/poller-acknowledgements.ts",
     "src/poller-claim.ts",
     "src/poller-codex.ts",
+    "src/poller-codex-stderr.ts",
     "src/poller-commands.ts",
     "src/poller-comment-metadata.ts",
     "src/poller-config.ts",

package/src/poller-codex-stderr.ts

@@ -0,0 +1,68 @@
+const STDERR_SNIPPET_LIMIT = 2000;
+const STDERR_RETAINED_LIMIT = STDERR_SNIPPET_LIMIT * 2;
+const CAPTURE_FAILURE_DETAIL_LIMIT = 800;
+const CAPTURE_FAILURE_PREFIX = 'stderr capture failed: ';
+const STDERR_WITH_CAPTURE_FAILURE_LIMIT =
+  STDERR_SNIPPET_LIMIT -
+  CAPTURE_FAILURE_PREFIX.length -
+  CAPTURE_FAILURE_DETAIL_LIMIT -
+  '\n'.length;
+const LOW_SURROGATE_MIN = 0xdc_00;
+const LOW_SURROGATE_MAX = 0xdf_ff;
+
+const unicodeSafeTail = (value: string, limit: number): string => {
+  let start = Math.max(0, value.length - limit);
+  const first = value.charCodeAt(start);
+  if (first >= LOW_SURROGATE_MIN && first <= LOW_SURROGATE_MAX) {
+    start += 1;
+  }
+  return value.slice(start);
+};
+
+export const createStderrCapture = () => {
+  const decoder = new TextDecoder();
+  let retained = '';
+  let pendingWhitespace = '';
+  const appendText = (text: string): void => {
+    const content = text.trimEnd();
+    if (content === '') {
+      pendingWhitespace = unicodeSafeTail(
+        pendingWhitespace + text,
+        STDERR_RETAINED_LIMIT,
+      );
+      return;
+    }
+    retained = unicodeSafeTail(
+      retained + pendingWhitespace + content,
+      STDERR_RETAINED_LIMIT,
+    );
+    pendingWhitespace = unicodeSafeTail(
+      text.slice(content.length),
+      STDERR_RETAINED_LIMIT,
+    );
+  };
+  return {
+    append: (chunk: Buffer): void => {
+      appendText(decoder.decode(chunk, { stream: true }));
+    },
+    finish: (): string => {
+      decoder.decode();
+      return unicodeSafeTail(retained.trim(), STDERR_SNIPPET_LIMIT);
+    },
+  };
+};
+
+export const withCaptureFailure = (
+  stderr: string,
+  captureFailure: string | null,
+): string => {
+  if (captureFailure === null) {
+    return stderr;
+  }
+  const retained = unicodeSafeTail(stderr, STDERR_WITH_CAPTURE_FAILURE_LIMIT);
+  const failure = `${CAPTURE_FAILURE_PREFIX}${unicodeSafeTail(
+    captureFailure,
+    CAPTURE_FAILURE_DETAIL_LIMIT,
+  )}`;
+  return retained === '' ? failure : `${retained}\n${failure}`;
+};

package/src/poller-codex.ts

@@ -1,20 +1,14 @@
-// Codex invocation for poller jobs. The agent runs headless inside the job
-// worktree and hands results back through the outcome file — never stdout,
-// which is unreliable once agent tools are active. The poller then verifies
-// effects (commits, diffs, gates) instead of trusting the narration.
-
-import { execFileSync } from 'node:child_process';
+import { type ChildProcess, spawn } from 'node:child_process';
 import { rmSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
-import { isRecord } from './github-settings-parse';
+import { createStderrCapture, withCaptureFailure } from './poller-codex-stderr';
 import type { PollerConfig } from './poller-config';
 import { OUTCOME_DIR } from './poller-protocol';
 
 const MS_PER_SECOND = 1000;
 const SECONDS_PER_MINUTE = 60;
 const MS_PER_MINUTE = SECONDS_PER_MINUTE * MS_PER_SECOND;
-const STDERR_SNIPPET_LIMIT = 2000;
 
 export type CodexRunResult = {
   readonly succeeded: boolean;
@@ -25,14 +19,14 @@ type CodexExecutor = (
   file: string,
   args: ReadonlyArray<string>,
   options: {
-    readonly encoding: 'utf8';
-    readonly timeout: number;
-    readonly stdio: readonly ['ignore', 'ignore', 'pipe'];
+    readonly detached: true;
+    readonly stdio: ['ignore', 'ignore', 'pipe'];
     readonly env: Record<string, string | undefined>;
   },
-) => unknown;
+) => ChildProcess;
 
-const defaultExecutor: CodexExecutor = execFileSync;
+const defaultExecutor: CodexExecutor = (file, args, options) =>
+  spawn(file, [...args], options);
 
 type CodexRunOptions = {
   readonly workDir: string;
@@ -41,30 +35,113 @@ type CodexRunOptions = {
   readonly config: PollerConfig;
 };
 
-const exitCause = (details: Record<string, unknown>): string => {
-  if (typeof details.status === 'number') {
-    return `exit status ${details.status}`;
+const exitCause = (
+  status: number | null,
+  signal: NodeJS.Signals | null,
+): string => {
+  if (status !== null) {
+    return `exit status ${status}`;
   }
-  if (typeof details.signal === 'string') {
-    return `signal ${details.signal}`;
+  return signal === null ? 'unknown exit cause' : `signal ${signal}`;
+};
+
+const failureResult = (cause: string, stderr = ''): CodexRunResult => ({
+  succeeded: false,
+  failure:
+    stderr === ''
+      ? `codex exec failed: ${cause}`
+      : `codex exec failed (${cause}):\n${stderr}`,
+});
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const timeoutCause = (timeout: number): string => {
+  if (timeout % MS_PER_MINUTE !== 0) {
+    return `timed out after ${timeout} ms`;
   }
-  return 'unknown exit cause';
+  const minutes = timeout / MS_PER_MINUTE;
+  return `timed out after ${minutes} ${minutes === 1 ? 'minute' : 'minutes'}`;
 };
 
-// Codex deliberately inherits the poller's authenticated GitHub environment.
-// The agent uses `gh` for review-fix ledger operations and PR metadata, while
-// the poller still owns verified commit publication, labels, and ready/merge
-// transitions.
-const agentEnv = (): Record<string, string | undefined> => ({ ...process.env });
+const terminateProcessTree = (child: ChildProcess): void => {
+  try {
+    if (process.platform === 'win32' || child.pid === undefined) {
+      child.kill('SIGKILL');
+    } else {
+      process.kill(-child.pid, 'SIGKILL');
+    }
+  } catch {
+    // The process may have exited between the timeout and the kill.
+  }
+};
 
-export const runCodex = (
+const awaitChild = (
+  child: ChildProcess,
+  capture: ReturnType<typeof createStderrCapture>,
+  timeout: number,
+): Promise<CodexRunResult> =>
+  new Promise((resolve) => {
+    let settled = false;
+    let captureFailure: string | null = null;
+    const settle = (result: CodexRunResult): void => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(result);
+      }
+    };
+    const failed = (cause: string): void => {
+      let stderr = '';
+      try {
+        stderr = capture.finish();
+      } catch (error) {
+        captureFailure = errorMessage(error);
+      }
+      settle(failureResult(cause, withCaptureFailure(stderr, captureFailure)));
+    };
+    child.stderr?.on('data', (chunk: Buffer) => {
+      try {
+        capture.append(chunk);
+      } catch (error) {
+        captureFailure = errorMessage(error);
+      }
+    });
+    child.stderr?.on('error', (error) => {
+      captureFailure = errorMessage(error);
+    });
+    child.once('error', (error) => {
+      failed(errorMessage(error));
+    });
+    child.once('close', (status, signal) => {
+      if (status === 0) {
+        settle({ succeeded: true, failure: null });
+        return;
+      }
+      failed(exitCause(status, signal));
+    });
+    const timer = setTimeout(() => {
+      terminateProcessTree(child);
+      child.stderr?.destroy();
+      failed(timeoutCause(timeout));
+    }, timeout);
+  });
+
+export const runCodex = async (
   options: CodexRunOptions,
   execute: CodexExecutor = defaultExecutor,
-): CodexRunResult => {
+): Promise<CodexRunResult> => {
   const { workDir, gitCommonDir, prompt, config } = options;
-  rmSync(join(workDir, OUTCOME_DIR), { recursive: true, force: true });
   try {
-    execute(
+    rmSync(join(workDir, OUTCOME_DIR), { recursive: true, force: true });
+  } catch (error) {
+    return failureResult(
+      `could not prepare the outcome directory: ${errorMessage(error)}`,
+    );
+  }
+  let child: ChildProcess;
+  try {
+    child = execute(
       'codex',
       [
         'exec',
@@ -84,32 +161,21 @@ export const runCodex = (
         prompt,
       ],
       {
-        encoding: 'utf8',
-        timeout: config.runTimeoutMinutes * MS_PER_MINUTE,
+        detached: true,
         stdio: ['ignore', 'ignore', 'pipe'],
-        env: agentEnv(),
+        env: { ...process.env },
       },
     );
-    return { succeeded: true, failure: null };
   } catch (error) {
-    const details: Record<string, unknown> = isRecord(error) ? error : {};
-    const stderr =
-      typeof details.stderr === 'string'
-        ? details.stderr.trim().slice(-STDERR_SNIPPET_LIMIT)
-        : '';
-    const message = error instanceof Error ? error.message : String(error);
-    // Node's "Command failed" message echoes the full command line, and the
-    // prompt embedded in it would push stderr past the failure-comment
-    // snippet limit — report the exit cause instead of the echoed command.
-    const cause = message.startsWith('Command failed')
-      ? exitCause(details)
-      : message;
-    return {
-      succeeded: false,
-      failure:
-        stderr === ''
-          ? `codex exec failed: ${cause}`
-          : `codex exec failed (${cause}):\n${stderr}`,
-    };
+    return failureResult(errorMessage(error));
+  }
+  if (child.stderr === null) {
+    child.kill();
+    return failureResult('stderr capture was not available');
   }
+  return await awaitChild(
+    child,
+    createStderrCapture(),
+    config.runTimeoutMinutes * MS_PER_MINUTE,
+  );
 };

package/src/poller-fix-run.ts

@@ -158,7 +158,7 @@ export const runFixJob = async (
     workspace,
   };
   try {
-    const run = runCodex({
+    const run = await runCodex({
       workDir: workspace.dir,
       gitCommonDir: cacheClone,
       prompt: fixPrompt({

package/src/poller-review-execution.ts

@@ -37,7 +37,7 @@ export const executeReviewJob = async (options: {
     ),
   );
   try {
-    const run = runAgent({
+    const run = await runAgent({
       workDir: workspace.dir,
       gitCommonDir: cacheClone,
       prompt: reviewPrompt({