@ryanfw/prompt-orchestration-pipeline 1.3.0 → 1.3.2

package/src/core/orchestrator.ts

@@ -112,7 +112,8 @@ import { buildReexecArgs } from "../cli/self-reexec";
 import { writeJobStatus } from "./status-writer";
 import { initializeStatusFromArtifacts } from "./status-initializer";
 import { materializeNormalizedPipelineDefinition } from "./pipeline-definition";
-import { applyHarnessDiscovery, discoverHarnesses } from "../harness/resolve";
+import { discoverHarnesses } from "../harness/index.ts";
+import { applyHarnessDiscovery } from "../harness/discovery.ts";
 import {
   listQueuedSeeds,
   releaseJobSlot,

package/src/core/pipeline-definition.ts

@@ -1,6 +1,6 @@
 import { dirname } from "node:path";
 import { mkdir } from "node:fs/promises";
-import type { AgentEntryConfig } from "../harness/types";
+import type { AgentEntryConfig } from "./agent-types.ts";
 
 export interface PipelineTaskEntry {
   name: string;

package/src/core/pipeline-runner.ts

@@ -5,7 +5,7 @@ import { unlinkSync } from "node:fs";
 import { getConfig, getPipelineConfig } from "./config";
 import { validatePipelineOrThrow } from "./validation";
 import { loadFreshModule } from "./module-loader";
-import { atomicWrite, writeJobStatus, type GateInfo } from "./status-writer";
+import { atomicWrite, writeJobStatus, flushJobStatus, StatusCorruptError, type GateInfo } from "./status-writer";
 import { decideTransition } from "./lifecycle-policy";
 import { runPipeline } from "./task-runner";
 import type { AuditLogEntry, PipelineResult } from "./task-runner";
@@ -672,8 +672,14 @@ export async function runPipelineJob(jobId: string): Promise<void> {
   while (true) {
     const pipeline = await loadPipeline(config.pipelineJsonPath);
     const pipelineTasks = normalizePipelineTasks(pipeline);
-    const statusText = await Bun.file(config.statusPath).text();
-    const status = JSON.parse(statusText) as { tasks: Record<string, { state?: string }> };
+    let status: { tasks: Record<string, { state?: string }> };
+    try {
+      const statusText = await Bun.file(config.statusPath).text();
+      status = JSON.parse(statusText) as { tasks: Record<string, { state?: string }> };
+    } catch (parseErr: unknown) {
+      if (parseErr instanceof SyntaxError) throw new StatusCorruptError(config.statusPath, { cause: parseErr });
+      throw parseErr;
+    }
 
     let selectedEntry: PipelineTaskEntry | null = null;
     let selectedTaskState: TaskStateValue = TaskState.PENDING;
@@ -1092,6 +1098,49 @@ export async function runPipelineJob(jobId: string): Promise<void> {
   }
   await releaseJobSlotBestEffort(dataDir, jobId);
   } catch (err) {
+    if (err instanceof StatusCorruptError) {
+      console.error(`Status corruption detected for job "${jobId}": ${err.statusPath} — refusing to overwrite`);
+      if (workDir !== undefined) {
+        try {
+          const failureIO = createTaskFileIO({
+            workDir,
+            taskName: "orchestrator",
+            trackTaskFiles: false,
+            getStage: () => "runPipelineJob",
+            statusPath: join(workDir, "tasks-status.json"),
+          });
+          const failureLogName = generateLogName(
+            "orchestrator",
+            "runPipelineJob",
+            LogEvent.FAILURE_DETAILS,
+            LogFileExtension.JSON,
+          );
+          await failureIO.writeLog(
+            failureLogName,
+            JSON.stringify({
+              type: "status_corrupt",
+              jobId,
+              statusPath: err.statusPath,
+              message: err.message,
+            }, null, 2),
+          );
+        } catch {
+          // Do not mask the original error if log-write fails
+        }
+        try {
+          await cleanupPidFile(workDir);
+        } catch {
+          // Do not mask the original failure if PID cleanup fails
+        }
+      }
+      if (dataDir !== undefined) {
+        await releaseJobSlotBestEffort(dataDir, jobId);
+      }
+      process.exitCode = 1;
+      setTimeout(() => process.exit(1), 5000).unref();
+      process.exit(1);
+      return;
+    }
     const normalized = normalizeError(err);
     console.error(normalized.message);
     if (workDir !== undefined) {
@@ -1171,6 +1220,8 @@ export async function completeJob(
   // Create complete/ directory if needed
   await mkdir(config.completeDir, { recursive: true });
 
+  await flushJobStatus(config.workDir);
+
   // Move job directory from current/ to complete/
   await rename(config.workDir, destDir);
 

package/src/core/status-writer.ts

@@ -1,5 +1,5 @@
-import { rename, unlink, mkdir } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { rename, unlink, mkdir, open } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { createJobLogger } from "./logger";
 import type { NormalizedError } from "./pipeline-runner";
 
@@ -71,6 +71,19 @@ export interface UploadArtifact {
   content: string;
 }
 
+export class StatusCorruptError extends Error {
+  readonly statusPath: string;
+  constructor(statusPath: string, options?: { cause?: unknown }) {
+    super(
+      `tasks-status.json is corrupt (unparseable) at ${statusPath}; refusing to overwrite — ` +
+      `repair the file or delete it to let a fresh status be created`,
+      options,
+    );
+    this.name = "StatusCorruptError";
+    this.statusPath = statusPath;
+  }
+}
+
 export const STATUS_FILENAME = "tasks-status.json";
 
 function clearResetTaskMetadata(task: TaskEntry): void {
@@ -150,13 +163,40 @@ export async function atomicWrite(filePath: string, content: string): Promise<vo
   const tmp = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
   try {
     await Bun.write(tmp, content);
+    const fh = await open(tmp, "r+");
+    try { await fh.sync(); } finally { await fh.close(); }
     await rename(tmp, filePath);
+    const dirFh = await open(dirname(filePath), "r");
+    try { await dirFh.sync(); } finally { await dirFh.close(); }
   } catch (err) {
     await unlink(tmp).catch(() => {});
     throw err;
   }
 }
 
+async function readSnapshotForUpdate(statusPath: string, jobDir: string): Promise<unknown> {
+  try {
+    const text = await Bun.file(statusPath).text();
+    return JSON.parse(text);
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return createDefaultStatus(jobDir);
+    if (err instanceof SyntaxError) throw new StatusCorruptError(statusPath, { cause: err });
+    throw err;
+  }
+}
+
+export async function flushJobStatus(jobDir: string): Promise<void> {
+  const pending = writeQueues.get(jobDir);
+  if (pending) {
+    try {
+      await pending;
+    } catch {
+      // drain only
+    }
+  }
+}
+
 const writeQueues = new Map<string, Promise<StatusSnapshot>>();
 
 export async function readJobStatus(jobDir: string): Promise<StatusSnapshot | null> {
@@ -195,18 +235,7 @@ export function updateTaskStatus(jobDir: string, taskId: string, taskUpdateFn: T
   return next;
 
   async function runTaskWrite(): Promise<StatusSnapshot> {
-    let raw: unknown;
-    try {
-      const text = await Bun.file(statusPath).text();
-      raw = JSON.parse(text);
-    } catch (err: unknown) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === "ENOENT" || err instanceof SyntaxError) {
-        raw = createDefaultStatus(jobDir);
-      } else {
-        throw err;
-      }
-    }
+    const raw = await readSnapshotForUpdate(statusPath, jobDir);
 
     const snapshot = validateStatusSnapshot(raw, jobDir);
 
@@ -361,18 +390,7 @@ export function writeJobStatus(jobDir: string, updateFn: StatusUpdateFn): Promis
   return next;
 
   async function runWrite(): Promise<StatusSnapshot> {
-    let raw: unknown;
-    try {
-      const text = await Bun.file(statusPath).text();
-      raw = JSON.parse(text);
-    } catch (err: unknown) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === "ENOENT" || err instanceof SyntaxError) {
-        raw = createDefaultStatus(jobDir);
-      } else {
-        throw err;
-      }
-    }
+    const raw = await readSnapshotForUpdate(statusPath, jobDir);
 
     let snapshot = validateStatusSnapshot(raw, jobDir);
 

package/src/core/task-runner.ts

@@ -14,14 +14,19 @@ import { loadFreshModule } from "./module-loader";
 import { loadEnvironment } from "./environment";
 import { createJobLogger } from "./logger";
 import { createHighLevelLLM, createLLMWithOverride, getLLMEvents } from "../llm/index";
+import { executeAgent } from "./agent-step";
 import { TaskState } from "../config/statuses";
 import { LogEvent, LogFileExtension } from "../config/log-events";
 // LLMClient: src/llm/index.ts exports HighLevelLLM (no LLMClient type exists there).
 import type { HighLevelLLM } from "../providers/types";
+import type { AgentStepResult, TaskAgentOptions, TaskAgentRunner } from "./agent-types";
 
 /** Opaque alias — the LLM client passed into execution contexts. */
 export type LLMClient = HighLevelLLM;
 
+/** The CLI-agent harness runner injected into JavaScript task stages. */
+export type { TaskAgentOptions, TaskAgentRunner } from "./agent-types";
+
 /** Validation result returned by schema validators. */
 export type { SchemaValidationResult } from "../api/validators/json";
 
@@ -55,6 +60,7 @@ export interface StageResult {
 export interface ExecutionContext {
   io: TaskFileIO;
   llm: LLMClient;
+  runAgent: TaskAgentRunner;
   meta: ExecutionMeta;
   data: Record<string, unknown>;
   flags: Record<string, unknown>;
@@ -85,6 +91,7 @@ export interface ModelConfig {
 export interface StageContext {
   io: TaskFileIO;
   llm: LLMClient;
+  runAgent: TaskAgentRunner;
   meta: ExecutionMeta;
   data: Record<string, unknown>;
   flags: Record<string, unknown>;
@@ -171,6 +178,8 @@ export interface InitialContext {
   envLoaded?: boolean;
   llm?: LLMClient;
   llmOverride?: unknown;
+  /** Override the injected `runAgent` helper (used by tests/custom hosts). */
+  runAgent?: TaskAgentRunner;
   seed?: unknown;
   modelConfig?: ModelConfig;
   pipelineTasks?: string[];
@@ -245,6 +254,21 @@ export function deriveModelKeyAndTokens(metric: Record<string, unknown>): TokenU
   return [modelKey, inputTokens, outputTokens, cost];
 }
 
+function deriveAgentUsageTuple(options: TaskAgentOptions, result: AgentStepResult): TokenUsageTuple | null {
+  const costUsd =
+    typeof result.costUsd === "number" && Number.isFinite(result.costUsd)
+      ? result.costUsd
+      : undefined;
+  if (!result.usage && costUsd === undefined) return null;
+
+  return [
+    `${options.harness}:${options.model ?? "default"}`,
+    result.usage?.inputTokens ?? 0,
+    result.usage?.outputTokens ?? 0,
+    costUsd ?? 0,
+  ];
+}
+
 // ─── Safe clone ─────────────────────────────────────────────────────────────
 
 function safeClone<T>(value: T): T {
@@ -516,8 +540,11 @@ export async function runPipeline(
     };
     llmMetrics.push(record);
 
-    // Append token usage to status file, serialized via promise queue
     const tuple = deriveModelKeyAndTokens(metric);
+    enqueueTokenUsage(tuple);
+  };
+
+  const enqueueTokenUsage = (tuple: TokenUsageTuple) => {
     tokenWriteQueue = tokenWriteQueue.then(async () => {
       await writeJobStatus(jobDir, (snapshot: StatusSnapshot) => {
         const tasks = snapshot.tasks;
@@ -557,6 +584,20 @@ export async function runPipeline(
     statusPath,
   });
 
+  // 9b. Build the CLI-agent harness runner injected into stages. It reuses the
+  // task's own `io`, so an agent reads and writes the same artifacts the task
+  // sees. A caller may override it (tests/custom hosts).
+  const runAgentCore: TaskAgentRunner =
+    initialContext.runAgent ??
+    ((options: TaskAgentOptions) =>
+      executeAgent({ io, entry: { ...options, name: taskName } }));
+  const runAgent: TaskAgentRunner = async (options: TaskAgentOptions) => {
+    const result = await runAgentCore(options);
+    const tuple = deriveAgentUsageTuple(options, result);
+    if (tuple) enqueueTokenUsage(tuple);
+    return result;
+  };
+
   // 10. Build execution context
   const pipelineTasks = initialContext.pipelineTasks ?? initialContext.meta?.pipelineTasks;
 
@@ -568,6 +609,7 @@ export async function runPipeline(
   const context: ExecutionContext = {
     io,
     llm,
+    runAgent,
     meta: {
       taskName,
       workDir,
@@ -644,6 +686,7 @@ export async function runPipeline(
       const stageContext: StageContext = {
         io,
         llm,
+        runAgent,
         meta: context.meta,
         data: safeClone(context.data),
         flags: safeClone(context.flags),

package/src/core/validation.ts

@@ -2,7 +2,7 @@ import Ajv from "ajv";
 import addFormats from "ajv-formats";
 import { getConfig } from "./config";
 import { isNonEmptyString, isPlainObject } from "./object-utils";
-import type { HarnessName } from "../harness/types";
+import type { HarnessName } from "../harness/index.ts";
 
 export interface ValidationError {
   message: string;

package/src/harness/__tests__/discovery.test.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { healedPath, popBinEnvVar, adapterBinEnvVar, applyHarnessDiscovery } from "../discovery.ts";
+import type { HarnessName, HarnessStatus } from "../index.ts";
+
+function makeStatus(overrides: Partial<HarnessStatus> & { name: HarnessName }): HarnessStatus {
+  return { installed: false, binPath: null, version: null, authenticated: null, ...overrides };
+}
+
+describe("healedPath", () => {
+  let existingDir: string;
+
+  beforeEach(() => {
+    existingDir = mkdtempSync(join(tmpdir(), "discovery-test-"));
+  });
+  afterEach(() => {
+    rmSync(existingDir, { recursive: true, force: true });
+  });
+
+  it("prepends existing standard dirs and preserves the base PATH suffix", () => {
+    const result = healedPath("/usr/bin:/bin");
+    expect(result.endsWith("/usr/bin:/bin")).toBe(true);
+  });
+
+  it("does not duplicate dirs already on the base PATH", () => {
+    const result = healedPath(`${existingDir}:/usr/bin`, [existingDir]);
+    expect(result.split(":").filter((d) => d === existingDir)).toHaveLength(1);
+  });
+
+  it("defaults to process.env.PATH when basePath is undefined", () => {
+    const original = process.env.PATH;
+    process.env.PATH = "/usr/bin";
+    try {
+      const result = healedPath();
+      expect(result).toContain("/usr/bin");
+    } finally {
+      process.env.PATH = original;
+    }
+  });
+
+  it("handles empty basePath", () => {
+    const result = healedPath("");
+    // Should still include any existing standard dirs
+    expect(typeof result).toBe("string");
+  });
+});
+
+describe("popBinEnvVar", () => {
+  it("maps harness names to POP_<HARNESS>_BIN", () => {
+    expect(popBinEnvVar("opencode")).toBe("POP_OPENCODE_BIN");
+    expect(popBinEnvVar("claude")).toBe("POP_CLAUDE_BIN");
+    expect(popBinEnvVar("codex")).toBe("POP_CODEX_BIN");
+  });
+});
+
+describe("adapterBinEnvVar", () => {
+  it("maps harness names to LLM_ADAPTER_<HARNESS>_BIN", () => {
+    expect(adapterBinEnvVar("opencode")).toBe("LLM_ADAPTER_OPENCODE_BIN");
+    expect(adapterBinEnvVar("claude")).toBe("LLM_ADAPTER_CLAUDE_BIN");
+    expect(adapterBinEnvVar("codex")).toBe("LLM_ADAPTER_CODEX_BIN");
+  });
+});
+
+describe("applyHarnessDiscovery", () => {
+  it("populates both POP_*_BIN and LLM_ADAPTER_*_BIN for discovered binaries", () => {
+    const env: Record<string, string | undefined> = { PATH: "/usr/bin" };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: true, binPath: "/x/opencode", authenticated: true }),
+      claude: makeStatus({ name: "claude", installed: true, binPath: "/y/claude", authenticated: true }),
+      codex: makeStatus({ name: "codex", installed: false }),
+    };
+
+    applyHarnessDiscovery(statuses, env);
+
+    expect(env.POP_OPENCODE_BIN).toBe("/x/opencode");
+    expect(env.LLM_ADAPTER_OPENCODE_BIN).toBe("/x/opencode");
+    expect(env.POP_CLAUDE_BIN).toBe("/y/claude");
+    expect(env.LLM_ADAPTER_CLAUDE_BIN).toBe("/y/claude");
+  });
+
+  it("keeps the original path suffix", () => {
+    const env: Record<string, string | undefined> = { PATH: "/usr/bin:/bin" };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: false }),
+      claude: makeStatus({ name: "claude", installed: false }),
+      codex: makeStatus({ name: "codex", installed: false }),
+    };
+
+    applyHarnessDiscovery(statuses, env);
+
+    expect(env.PATH).toContain("/usr/bin:/bin");
+  });
+
+  it("produces a warning for missing harnesses", () => {
+    const env: Record<string, string | undefined> = { PATH: "/usr/bin" };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: false }),
+      claude: makeStatus({ name: "claude", installed: true, binPath: "/y/claude", authenticated: true }),
+      codex: makeStatus({ name: "codex", installed: true, binPath: "/z/codex", authenticated: true }),
+    };
+
+    const messages = applyHarnessDiscovery(statuses, env);
+    const opencodeMsg = messages.find((m) => m.message.includes('"opencode"'));
+
+    expect(opencodeMsg).toBeDefined();
+    expect(opencodeMsg!.level).toBe("warn");
+    expect(opencodeMsg!.message).toContain("not found");
+  });
+
+  it("produces a warning for unauthenticated harnesses", () => {
+    const env: Record<string, string | undefined> = { PATH: "/usr/bin" };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: true, binPath: "/x/opencode", authenticated: false }),
+      claude: makeStatus({ name: "claude", installed: true, binPath: "/y/claude", authenticated: true }),
+      codex: makeStatus({ name: "codex", installed: true, binPath: "/z/codex", authenticated: true }),
+    };
+
+    const messages = applyHarnessDiscovery(statuses, env);
+    const opencodeMsg = messages.find((m) => m.message.includes('"opencode"'));
+
+    expect(opencodeMsg).toBeDefined();
+    expect(opencodeMsg!.level).toBe("warn");
+    expect(opencodeMsg!.message).toContain("not authenticated");
+  });
+
+  it("produces an info message for authenticated harnesses", () => {
+    const env: Record<string, string | undefined> = { PATH: "/usr/bin" };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: true, binPath: "/x/opencode", authenticated: true }),
+      claude: makeStatus({ name: "claude", installed: true, binPath: "/y/claude", authenticated: true }),
+      codex: makeStatus({ name: "codex", installed: true, binPath: "/z/codex", authenticated: true }),
+    };
+
+    const messages = applyHarnessDiscovery(statuses, env);
+    const opencodeMsg = messages.find((m) => m.message.includes('"opencode"'));
+
+    expect(opencodeMsg).toBeDefined();
+    expect(opencodeMsg!.level).toBe("info");
+    expect(opencodeMsg!.message).toContain("authenticated");
+  });
+
+  it("produces an info message for installed harnesses with unknown auth", () => {
+    const env: Record<string, string | undefined> = { PATH: "/usr/bin" };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: true, binPath: "/x/opencode", authenticated: null }),
+      claude: makeStatus({ name: "claude", installed: true, binPath: "/y/claude", authenticated: true }),
+      codex: makeStatus({ name: "codex", installed: true, binPath: "/z/codex", authenticated: true }),
+    };
+
+    const messages = applyHarnessDiscovery(statuses, env);
+    const opencodeMsg = messages.find((m) => m.message.includes('"opencode"'));
+
+    expect(opencodeMsg).toBeDefined();
+    expect(opencodeMsg!.level).toBe("info");
+    expect(opencodeMsg!.message).toContain("auth status unknown");
+  });
+
+  it("does not set bin env vars for missing harnesses", () => {
+    const env: Record<string, string | undefined> = { PATH: "/usr/bin" };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: false }),
+      claude: makeStatus({ name: "claude", installed: false }),
+      codex: makeStatus({ name: "codex", installed: false }),
+    };
+
+    applyHarnessDiscovery(statuses, env);
+
+    expect(env.POP_OPENCODE_BIN).toBeUndefined();
+    expect(env.LLM_ADAPTER_OPENCODE_BIN).toBeUndefined();
+    expect(env.POP_CLAUDE_BIN).toBeUndefined();
+    expect(env.LLM_ADAPTER_CLAUDE_BIN).toBeUndefined();
+    expect(env.POP_CODEX_BIN).toBeUndefined();
+    expect(env.LLM_ADAPTER_CODEX_BIN).toBeUndefined();
+  });
+
+  it("bridges existing POP_* binary overrides to adapter env vars when discovery misses", () => {
+    const env: Record<string, string | undefined> = {
+      PATH: "/usr/bin",
+      POP_OPENCODE_BIN: "/custom/opencode",
+    };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: false }),
+      claude: makeStatus({ name: "claude", installed: false }),
+      codex: makeStatus({ name: "codex", installed: false }),
+    };
+
+    const messages = applyHarnessDiscovery(statuses, env);
+
+    expect(env.POP_OPENCODE_BIN).toBe("/custom/opencode");
+    expect(env.LLM_ADAPTER_OPENCODE_BIN).toBe("/custom/opencode");
+    expect(messages.find((m) => m.message.includes('"opencode"'))).toMatchObject({
+      level: "info",
+    });
+  });
+
+  it("bridges existing adapter binary overrides back to POP env vars when discovery misses", () => {
+    const env: Record<string, string | undefined> = {
+      PATH: "/usr/bin",
+      LLM_ADAPTER_CODEX_BIN: "/custom/codex",
+    };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: false }),
+      claude: makeStatus({ name: "claude", installed: false }),
+      codex: makeStatus({ name: "codex", installed: false }),
+    };
+
+    applyHarnessDiscovery(statuses, env);
+
+    expect(env.LLM_ADAPTER_CODEX_BIN).toBe("/custom/codex");
+    expect(env.POP_CODEX_BIN).toBe("/custom/codex");
+  });
+
+  it("keeps POP_* binary overrides ahead of discovered PATH binaries", () => {
+    const env: Record<string, string | undefined> = {
+      PATH: "/usr/bin",
+      POP_CODEX_BIN: "/custom/codex",
+    };
+    const statuses: Record<HarnessName, HarnessStatus> = {
+      opencode: makeStatus({ name: "opencode", installed: false }),
+      claude: makeStatus({ name: "claude", installed: false }),
+      codex: makeStatus({ name: "codex", installed: true, binPath: "/path/codex", authenticated: true }),
+    };
+
+    const messages = applyHarnessDiscovery(statuses, env);
+
+    expect(env.POP_CODEX_BIN).toBe("/custom/codex");
+    expect(env.LLM_ADAPTER_CODEX_BIN).toBe("/custom/codex");
+    expect(messages.find((m) => m.message.includes('"codex"'))).toMatchObject({
+      level: "info",
+      message: 'harness "codex": using configured binary override /custom/codex',
+    });
+  });
+});

package/src/harness/discovery.ts

@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { HarnessName, HarnessStatus } from "./index.ts";
+
+type EnvLike = Record<string, string | undefined>;
+
+export interface PreflightMessage {
+  level: "info" | "warn";
+  message: string;
+}
+
+/**
+ * Standard user/local bin dirs that interactive shells add (via .zshrc etc.) but
+ * GUI/launchd/cron launches usually miss.
+ */
+function standardBinDirs(): string[] {
+  const home = homedir();
+  return [
+    join(home, ".opencode/bin"),
+    join(home, ".local/bin"),
+    join(home, ".bun/bin"),
+    join(home, ".cargo/bin"),
+    join(home, ".npm-global/bin"),
+    join(home, ".deno/bin"),
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+  ];
+}
+
+/**
+ * Build a PATH with known bin dirs prepended — keeping only dirs that exist
+ * and are not already present.
+ */
+export function healedPath(basePath?: string, candidateDirs = standardBinDirs()): string {
+  const current = (basePath ?? process.env.PATH ?? "").split(":").filter(Boolean);
+  const seen = new Set(current);
+  const prepend: string[] = [];
+  for (const dir of candidateDirs) {
+    if (dir && !seen.has(dir) && existsSync(dir)) {
+      prepend.push(dir);
+      seen.add(dir);
+    }
+  }
+  return [...prepend, ...current].join(":");
+}
+
+/** Env var that pins a harness CLI to an absolute path, e.g. "opencode" → POP_OPENCODE_BIN. */
+export function popBinEnvVar(name: HarnessName): string {
+  return `POP_${name.toUpperCase()}_BIN`;
+}
+
+/** Env var the adapter reads for binary override, e.g. "opencode" → LLM_ADAPTER_OPENCODE_BIN. */
+export function adapterBinEnvVar(name: HarnessName): string {
+  return `LLM_ADAPTER_${name.toUpperCase()}_BIN`;
+}
+
+/**
+ * Apply discovery results to an env object — heal PATH, cache resolved absolute
+ * paths as both POP_*_BIN and LLM_ADAPTER_*_BIN, and return human-readable
+ * status/warning messages.
+ */
+export function applyHarnessDiscovery(
+  statuses: Record<HarnessName, HarnessStatus>,
+  env: EnvLike,
+): PreflightMessage[] {
+  env.PATH = healedPath(env.PATH ?? "");
+
+  const messages: PreflightMessage[] = [];
+  for (const status of Object.values(statuses) as HarnessStatus[]) {
+    const adapterEnv = adapterBinEnvVar(status.name);
+    const popEnv = popBinEnvVar(status.name);
+    const explicitBin = env[popEnv] ?? env[adapterEnv];
+    const configuredBin = explicitBin ?? status.binPath;
+
+    if (configuredBin) {
+      env[adapterEnv] = configuredBin;
+      env[popEnv] = configuredBin;
+    }
+
+    if (explicitBin) {
+      messages.push({
+        level: "info",
+        message: `harness "${status.name}": using configured binary override ${configuredBin}`,
+      });
+    } else if (!status.installed && !configuredBin) {
+      messages.push({
+        level: "warn",
+        message: `harness "${status.name}": CLI not found on PATH or known install dirs; agent steps using it will fail until it is installed`,
+      });
+    } else if (status.authenticated === false) {
+      messages.push({
+        level: "warn",
+        message: `harness "${status.name}": found at ${status.binPath} but not authenticated; runs may fail until you log in`,
+      });
+    } else if (status.authenticated === null) {
+      messages.push({
+        level: "info",
+        message: `harness "${status.name}": ${status.binPath} (auth status unknown)`,
+      });
+    } else {
+      messages.push({
+        level: "info",
+        message: `harness "${status.name}": ${status.binPath} (authenticated)`,
+      });
+    }
+  }
+  return messages;
+}