@open330/oac 2026.4.3 → 2026.220.2

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to OAC (Open Agent Contribution) are documented here.
+
+## [Unreleased]
+
+_No unreleased changes._
+
+---
+
+## [2026.2.5] — 2026-02-20
+
+> **Note**: Versions `2026.3.x` and `2026.4.x` were published with an incorrect CalVer month.
+> This release corrects the version to `2026.2.5` (year=2026, month=February, patch=5th iteration).
+
+### Config Loader Fix (`fb57557`)
+- **fix**: Config loader now matches `@open330/oac` import (previously only matched `@open330/oac-core`)
+
+### OpenCode Provider Integration (`afdf725`)
+- **feat**: OpenCode adapter (`src/execution/agents/opencode.adapter.ts`)
+- **feat**: Adapter registry replacing hard-coded switch (`src/execution/agents/registry.ts`)
+- **fix**: 7 pre-existing typecheck errors resolved (`doctor.ts`, `explain.ts`, `init.ts`, `task.ts`)
+
+### Security & Quality Fixes (`55780e4`)
+- **security**: Fixed shell injection in dashboard browser opener (replaced `exec` with `open` library)
+- **security**: Sanitized branch names in `sandbox.ts` against path traversal
+- **security**: Replaced `sh -c` shell redirect with `execa` piping in `github-auth.ts`
+- **security**: Added `AbortSignal.timeout` to all GitHub API `fetch` calls
+- **security**: SHA-pinned all CI/CD workflow actions
+- **refactor**: Consolidated `truncate()` and `isRecord()` into `core/utils.ts`
+- **refactor**: Unified error normalization into shared `normalizeError` module
+- **refactor**: Extracted `AsyncEventQueue` into shared module for agent adapters
+- **refactor**: Created scanner factory to eliminate construction duplication
+- **chore**: Annotated all 10 empty catch blocks with `// best-effort` comments
+- **ci**: Added `pnpm audit --prod` to CI pipeline
+
+### Deploy Readiness (`91898c8`)
+- **chore**: Added `LICENSE`, `CHANGELOG.md`, `docs/` to npm `files` array
+- **chore**: Added `prepublishOnly` script (`pnpm build && pnpm test`)
+- **chore**: Restored CI/CD workflows (SHA-pinned actions)
+- **chore**: Lowered Node.js requirement from `>=24` to `>=20`
+- **chore**: Fixed repository URL in `package.json`
+
+### Wave 9 — Final P3/T3 Polish (`f8ff2ae`)
+- **feat**: `oac init --minimal` for quick, non-interactive setup
+- **feat**: `oac explain <task-id>` command — inspect why a task/epic was selected
+- **feat**: Colored diff output in `--dry-run` mode (source files, complexity, scanner)
+- **docs**: Comprehensive troubleshooting section in README
+- **perf**: Streaming file reads in analyzer for large files (>1MB threshold)
+- **perf**: Memory pressure monitoring — PQueue auto-throttles when heap usage exceeds 85%
+
+### Wave 8 — Final UX Polish (`806a170`)
+- **docs**: Auto-generated config reference from Zod schema (`docs/config-reference.md`)
+- **docs**: Added CHANGELOG
+
+### Maintenance
+- **chore**: Temporarily removed CI/CD workflows during dev phase (`cb90214`)
+
+---
+
+## [2026.4.3] — 2026-02-18 _(deprecated — wrong CalVer month)_
+
+### Wave 7 — Quick Wins Bundle (`7c179a0`)
+- **feat**: `oac r` alias for `oac run` (power-user shortcut)
+- **feat**: Distinct exit codes for CI/CD integration:
+  - `0` — all tasks succeeded or dry-run
+  - `1` — unhandled error
+  - `2` — config/validation error
+  - `3` — every task/epic failed
+  - `4` — partial success (some tasks failed)
+- **feat**: Resettable token counters (`claudeCounter.reset()`, `codexCounter.reset()`) for correctness in long-lived processes
+- **feat**: Progress percentages on long operations (file analysis, task estimation, epic execution)
+
+### Wave 6 — Single-Command Pipeline (`156c7d2`)
+- **feat**: `oac run` now performs the full scan → analyze → execute pipeline in one command
+- **ux**: Clarified distinction between `oac scan` (discover tasks) and `oac analyze` (build context)
+
+### Wave 5 — Run Module Decomposition (`aea2760`)
+- **refactor**: Decomposed the 1,692-line `run.ts` monolith into `src/cli/commands/run/` with 8 focused modules:
+  - `index.ts` — command definition and option parsing
+  - `pipeline.ts` — top-level orchestration
+  - `epic.ts` — epic-based execution flow
+  - `task.ts` — single-task execution
+  - `retry.ts` — `--retry-failed` pipeline
+  - `output.ts` — summary rendering and JSON output
+  - `validation.ts` — config and input validation
+  - `types.ts` — shared types, exit codes, `ConfigError`
+
+### Wave 4 — Timeout, Completion, & Retry (`cb1af6c`)
+- **feat**: PR creation timeout (prevents hanging on GitHub API issues)
+- **perf**: Replaced hand-rolled `runWithConcurrency` with `PQueue` for bounded parallelism
+- **feat**: `oac completion` command for shell tab-completion (bash/zsh/fish)
+- **feat**: `--retry-failed` flag to re-run only previously failed tasks
+
+### Wave 3 — UX & CLI Improvements (`9869073`)
+- **ux**: Usage examples in every `--help` screen
+- **feat**: Global `--quiet` flag suppresses spinner/progress output (for CI pipelines)
+- **ux**: Failed task/epic details included in run summary
+- **perf**: Parallelized epic execution pipeline with bounded concurrency
+
+### Wave 2 — Helpers, Parallelism, & Cleanup (`417fc85`)
+- **refactor**: Extracted 11 duplicated helper functions into `src/cli/helpers.ts`
+- **perf**: Parallelized `analyzer.ts` file processing with `PQueue`
+- **perf**: Parallelized `todo-scanner.ts` file processing
+- **chore**: Removed dead `withTimeout` utility
+
+### Wave 1 — Foundation Fixes (`4196c59`)
+- **fix**: `withWorktreeLock` now correctly releases locks on error
+- **perf**: Bounded `Promise.all` with `PQueue` to prevent unbounded parallelism
+- **perf**: Replaced `child_process.spawn` with `execa` for better error handling
+- **feat**: SIGINT handler for graceful shutdown
+- **fix**: Removed simulation fallback that silently skipped real execution
+- **feat**: `defineConfig()` wrapper for type-safe config files
+- **ux**: Getting Started help text for first-time users
+

package/README.md

@@ -14,7 +14,7 @@
 
 [![npm](https://img.shields.io/npm/v/@open330/oac?label=npm&color=CB3837&logo=npm)](https://www.npmjs.com/package/@open330/oac)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?logo=typescript&logoColor=white)](https://typescriptlang.org/)
 
 [Getting Started](#-getting-started) · [How It Works](#-how-it-works) · [Commands](#commands) · [Configuration](#configuration) · [Architecture](#architecture) · [Contributing](#contributing)
@@ -93,7 +93,7 @@ npx @open330/oac run --repo facebook/react --tokens unlimited
 
 ### Prerequisites
 
-- **Node.js** >= 24 (see `engines` in package.json)
+- **Node.js** >= 20 (see `engines` in package.json)
 - **git** installed
 - At least one AI agent CLI: [Claude Code](https://claude.ai/code), [Codex](https://github.com/openai/codex), or [OpenCode](https://github.com/opencode-ai/opencode)
 

package/dist/{chunk-YWIB3TRI.js → chunk-6A37SKAJ.js}

@@ -38,8 +38,21 @@ function createMemoryMonitor(options) {
   };
 }
 
+// src/core/utils.ts
+function truncate(value, maxLength, ellipsis = "\u2026") {
+  if (value.length <= maxLength) {
+    return value;
+  }
+  return `${value.slice(0, Math.max(0, maxLength - ellipsis.length))}${ellipsis}`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
 export {
   getMemorySnapshot,
-  createMemoryMonitor
+  createMemoryMonitor,
+  truncate,
+  isRecord
 };
-//# sourceMappingURL=chunk-YWIB3TRI.js.map
+//# sourceMappingURL=chunk-6A37SKAJ.js.map

package/dist/chunk-6A37SKAJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/memory.ts","../src/core/utils.ts"],"sourcesContent":["/**\n * Memory pressure monitoring utilities.\n *\n * Provides lightweight heap-usage checks that callers can use to\n * throttle work when the process is approaching memory limits.\n */\n\n/** Default threshold: pause work when heap usage exceeds 85% of the limit. */\nconst DEFAULT_PRESSURE_RATIO = 0.85;\n\nexport interface MemorySnapshot {\n  heapUsedMB: number;\n  heapTotalMB: number;\n  rssUsedMB: number;\n  /** Ratio of heapUsed / heapTotal (0–1). */\n  heapPressure: number;\n  /** True when heapPressure exceeds the configured threshold. */\n  isUnderPressure: boolean;\n}\n\n/**\n * Take a snapshot of current memory usage.\n *\n * @param pressureRatio - Threshold ratio (0–1) above which `isUnderPressure`\n *   is set to `true`. Defaults to 0.85.\n */\nexport function getMemorySnapshot(pressureRatio = DEFAULT_PRESSURE_RATIO): MemorySnapshot {\n  const mem = process.memoryUsage();\n  const heapUsedMB = mem.heapUsed / 1_048_576;\n  const heapTotalMB = mem.heapTotal / 1_048_576;\n  const rssUsedMB = mem.rss / 1_048_576;\n  const heapPressure = mem.heapTotal > 0 ? mem.heapUsed / mem.heapTotal : 0;\n\n  return {\n    heapUsedMB: Math.round(heapUsedMB * 10) / 10,\n    heapTotalMB: Math.round(heapTotalMB * 10) / 10,\n    rssUsedMB: Math.round(rssUsedMB * 10) / 10,\n    heapPressure: Math.round(heapPressure * 1000) / 1000,\n    isUnderPressure: heapPressure >= pressureRatio,\n  };\n}\n\n/**\n * Creates a monitor that periodically checks memory pressure and calls\n * `onPressure` when the threshold is exceeded.  The monitor can be used\n * to pause a PQueue or reduce concurrency under load.\n *\n * Returns a `stop` function to clear the interval.\n */\nexport function createMemoryMonitor(options: {\n  /** Polling interval in milliseconds (default: 5 000). */\n  intervalMs?: number;\n  /** Heap pressure ratio threshold (default: 0.85). */\n  pressureRatio?: number;\n  /** Called when heap pressure exceeds the threshold. */\n  onPressure: (snapshot: MemorySnapshot) => void;\n  /** Called when heap pressure drops back below the threshold. */\n  onRelief?: (snapshot: MemorySnapshot) => void;\n}): { stop: () => void } {\n  const intervalMs = options.intervalMs ?? 5_000;\n  const pressureRatio = options.pressureRatio ?? DEFAULT_PRESSURE_RATIO;\n  let wasPressured = false;\n\n  const timer = setInterval(() => {\n    const snapshot = getMemorySnapshot(pressureRatio);\n\n    if (snapshot.isUnderPressure && !wasPressured) {\n      wasPressured = true;\n      options.onPressure(snapshot);\n    } else if (!snapshot.isUnderPressure && wasPressured) {\n      wasPressured = false;\n      options.onRelief?.(snapshot);\n    }\n  }, intervalMs);\n\n  // Unref so this doesn't keep the process alive\n  if (typeof timer === \"object\" && \"unref\" in timer) {\n    timer.unref();\n  }\n\n  return {\n    stop() {\n      clearInterval(timer);\n    },\n  };\n}\n\n","/**\n * Shared utility functions used across the codebase.\n */\n\n/**\n * Truncate a string to `maxLength`, appending an ellipsis when trimmed.\n * Defaults to the unicode ellipsis `\"…\"` (1 char).  Pass `\"...\"` for the\n * three-dot ASCII variant.\n */\nexport function truncate(\n  value: string,\n  maxLength: number,\n  ellipsis = \"…\",\n): string {\n  if (value.length <= maxLength) {\n    return value;\n  }\n  return `${value.slice(0, Math.max(0, maxLength - ellipsis.length))}${ellipsis}`;\n}\n\n/**\n * Type guard: returns `true` when `value` is a non-null object\n * (i.e.\\ a `Record<string, unknown>`).\n */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\n"],"mappings":";AAQA,IAAM,yBAAyB;AAkBxB,SAAS,kBAAkB,gBAAgB,wBAAwC;AACxF,QAAM,MAAM,QAAQ,YAAY;AAChC,QAAM,aAAa,IAAI,WAAW;AAClC,QAAM,cAAc,IAAI,YAAY;AACpC,QAAM,YAAY,IAAI,MAAM;AAC5B,QAAM,eAAe,IAAI,YAAY,IAAI,IAAI,WAAW,IAAI,YAAY;AAExE,SAAO;AAAA,IACL,YAAY,KAAK,MAAM,aAAa,EAAE,IAAI;AAAA,IAC1C,aAAa,KAAK,MAAM,cAAc,EAAE,IAAI;AAAA,IAC5C,WAAW,KAAK,MAAM,YAAY,EAAE,IAAI;AAAA,IACxC,cAAc,KAAK,MAAM,eAAe,GAAI,IAAI;AAAA,IAChD,iBAAiB,gBAAgB;AAAA,EACnC;AACF;AASO,SAAS,oBAAoB,SASX;AACvB,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,gBAAgB,QAAQ,iBAAiB;AAC/C,MAAI,eAAe;AAEnB,QAAM,QAAQ,YAAY,MAAM;AAC9B,UAAM,WAAW,kBAAkB,aAAa;AAEhD,QAAI,SAAS,mBAAmB,CAAC,cAAc;AAC7C,qBAAe;AACf,cAAQ,WAAW,QAAQ;AAAA,IAC7B,WAAW,CAAC,SAAS,mBAAmB,cAAc;AACpD,qBAAe;AACf,cAAQ,WAAW,QAAQ;AAAA,IAC7B;AAAA,EACF,GAAG,UAAU;AAGb,MAAI,OAAO,UAAU,YAAY,WAAW,OAAO;AACjD,UAAM,MAAM;AAAA,EACd;AAEA,SAAO;AAAA,IACL,OAAO;AACL,oBAAc,KAAK;AAAA,IACrB;AAAA,EACF;AACF;;;AC5EO,SAAS,SACd,OACA,WACA,WAAW,UACH;AACR,MAAI,MAAM,UAAU,WAAW;AAC7B,WAAO;AAAA,EACT;AACA,SAAO,GAAG,MAAM,MAAM,GAAG,KAAK,IAAI,GAAG,YAAY,SAAS,MAAM,CAAC,CAAC,GAAG,QAAQ;AAC/E;AAMO,SAAS,SAAS,OAAkD;AACzE,SAAO,OAAO,UAAU,YAAY,UAAU;AAChD;","names":[]}

package/dist/{chunk-HDMLNOND.js → chunk-6JEFW6B7.js}

@@ -1,6 +1,7 @@
 import {
-  createMemoryMonitor
-} from "./chunk-YWIB3TRI.js";
+  createMemoryMonitor,
+  truncate
+} from "./chunk-6A37SKAJ.js";
 
 // src/discovery/scanners/todo-scanner.ts
 import { spawn } from "child_process";
@@ -289,12 +290,6 @@ function extractTodoKeyword(lineText) {
   }
   return match[1].toUpperCase();
 }
-function truncate(value, maxLength) {
-  if (value.length <= maxLength) {
-    return value;
-  }
-  return `${value.slice(0, maxLength - 1)}\u2026`;
-}
 function createTaskId(source, targetFiles, title, suffix) {
   const base = [source, [...targetFiles].sort().join(","), title, suffix].join("::");
   return createHash("sha256").update(base).digest("hex").slice(0, 16);
@@ -1142,6 +1137,8 @@ import { readFile as readFile4 } from "fs/promises";
 import { resolve as resolve4 } from "path";
 var GITHUB_API_BASE_URL = "https://api.github.com";
 var ISSUES_PER_PAGE = 30;
+var OAC_PR_PAGE_SIZE = 100;
+var OAC_PR_TITLE_PREFIX = "[OAC]";
 var TITLE_LIMIT = 120;
 var DESCRIPTION_LIMIT = 500;
 var ESTIMATED_TOKENS_BY_COMPLEXITY = {
@@ -1165,12 +1162,15 @@ var GitHubIssuesScanner = class {
     if (!repo) {
       return [];
     }
-    const issues = await fetchOpenIssues(repo, token);
+    const [issues, claimedIssueNumbers] = await Promise.all([
+      fetchOpenIssues(repo, token),
+      fetchOacClaimedIssueNumbers(repo, token)
+    ]);
     if (issues.length === 0) {
       return [];
     }
     const discoveredAt = (/* @__PURE__ */ new Date()).toISOString();
-    const tasks = issues.filter((issue) => issue.pull_request === void 0).map((issue) => mapIssueToTask(issue, discoveredAt)).filter((task) => task !== void 0);
+    const tasks = issues.filter((issue) => issue.pull_request === void 0).filter((issue) => !claimedIssueNumbers.has(asNumber3(issue.number) ?? -1)).map((issue) => mapIssueToTask(issue, discoveredAt)).filter((task) => task !== void 0);
     if (typeof options.maxTasks === "number" && options.maxTasks >= 0) {
       return tasks.slice(0, options.maxTasks);
     }
@@ -1194,7 +1194,8 @@ async function fetchOpenIssues(repo, token) {
       headers: {
         Authorization: `Bearer ${token}`,
         Accept: "application/vnd.github.v3+json"
-      }
+      },
+      signal: AbortSignal.timeout(3e4)
     });
     if (!response.ok) {
       return [];
@@ -1208,6 +1209,47 @@ async function fetchOpenIssues(repo, token) {
     return [];
   }
 }
+async function fetchOacClaimedIssueNumbers(repo, token) {
+  const url = `${GITHUB_API_BASE_URL}/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.name)}/pulls?state=open&per_page=${OAC_PR_PAGE_SIZE}&sort=updated&direction=desc`;
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github.v3+json"
+      },
+      signal: AbortSignal.timeout(15e3)
+    });
+    if (!response.ok) {
+      return /* @__PURE__ */ new Set();
+    }
+    const pulls = await response.json();
+    if (!Array.isArray(pulls)) {
+      return /* @__PURE__ */ new Set();
+    }
+    return extractClaimedIssueNumbers(pulls);
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function extractClaimedIssueNumbers(pulls) {
+  const claimed = /* @__PURE__ */ new Set();
+  const issueRefPattern = /(?:Fixes|Closes|Resolves)\s+#(\d+)/gi;
+  for (const pr of pulls) {
+    if (!pr || typeof pr !== "object") continue;
+    const record = pr;
+    const title = typeof record.title === "string" ? record.title : "";
+    if (!title.startsWith(OAC_PR_TITLE_PREFIX)) continue;
+    const body = typeof record.body === "string" ? record.body : "";
+    for (const match of body.matchAll(issueRefPattern)) {
+      const num = Number.parseInt(match[1], 10);
+      if (Number.isFinite(num)) {
+        claimed.add(num);
+      }
+    }
+  }
+  return claimed;
+}
 async function parseRepoFromGitConfig(repoPath) {
   const config = await readGitConfig(repoPath);
   if (!config) {
@@ -1324,8 +1366,8 @@ function mapIssueToTask(issue, discoveredAt) {
   const estimatedTokens = ESTIMATED_TOKENS_BY_COMPLEXITY[complexity];
   const bodyText = asString3(issue.body)?.trim() || "No description provided.";
   const labelSummary = labels.length > 0 ? `Labels: ${labels.join(", ")}` : "Labels: none";
-  const title = truncate2(rawTitle, TITLE_LIMIT);
-  const description = truncate2(`${bodyText}
+  const title = truncate(rawTitle, TITLE_LIMIT);
+  const description = truncate(`${bodyText}
 
 ${labelSummary}`, DESCRIPTION_LIMIT);
   const url = asString3(issue.html_url) ?? "";
@@ -1406,12 +1448,6 @@ function readAuthor(user) {
   }
   return login;
 }
-function truncate2(value, maxLength) {
-  if (value.length <= maxLength) {
-    return value;
-  }
-  return `${value.slice(0, maxLength - 1)}\u2026`;
-}
 function toIssueResponse(value) {
   if (value && typeof value === "object") {
     return value;
@@ -1524,6 +1560,41 @@ function unique(values) {
   return Array.from(new Set(values.filter((value) => value.trim().length > 0)));
 }
 
+// src/discovery/scanner-factory.ts
+function buildScanners(config, hasGitHubAuth) {
+  const names = [];
+  if (config?.discovery.scanners.lint !== false) {
+    names.push("lint");
+  }
+  if (config?.discovery.scanners.todo !== false) {
+    names.push("todo");
+  }
+  if (config?.discovery.scanners.testGap !== false) {
+    names.push("test-gap");
+  }
+  if (hasGitHubAuth) {
+    names.push("github-issues");
+  }
+  if (names.length === 0) {
+    names.push("lint", "todo", "test-gap");
+  }
+  const unique2 = [...new Set(names)];
+  const instances = unique2.map(instantiateScanner);
+  return { names: unique2, instances, composite: new CompositeScanner(instances) };
+}
+function instantiateScanner(name) {
+  switch (name) {
+    case "lint":
+      return new LintScanner();
+    case "todo":
+      return new TodoScanner();
+    case "test-gap":
+      return new TestGapScanner();
+    case "github-issues":
+      return new GitHubIssuesScanner();
+  }
+}
+
 // src/discovery/ranker.ts
 var IMPACT_BY_SOURCE = {
   lint: 22,
@@ -2323,6 +2394,7 @@ export {
   GitHubIssuesScanner,
   CompositeScanner,
   createDefaultCompositeScanner,
+  buildScanners,
   rankTasks,
   analyzeCodebase,
   persistContext,
@@ -2339,4 +2411,4 @@ export {
   updateBacklog,
   getPendingEpics
 };
-//# sourceMappingURL=chunk-HDMLNOND.js.map
+//# sourceMappingURL=chunk-6JEFW6B7.js.map