@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/core/spawn-tee.js

@@ -11,13 +11,19 @@ const path = require('path');
 // context land in the buffer even if the agent printed a lot before exiting.
 const DEFAULT_MAX_TAIL_BYTES = 64 * 1024;
 
+/** @typedef {Buffer|string} ChunkType */
 class TailBuffer {
+  /** @param {number} maxBytes */
   constructor(maxBytes) {
+    /** @type {number} */
     this.maxBytes = maxBytes;
+    /** @type {ChunkType[]} */
     this.chunks = [];
+    /** @type {number} */
     this.size = 0;
   }
 
+  /** @param {ChunkType} chunk */
   push(chunk) {
     this.chunks.push(chunk);
     this.size += chunk.length;
@@ -28,15 +34,20 @@ class TailBuffer {
         this.chunks.shift();
         this.size -= head.length;
       } else {
-        this.chunks[0] = head.subarray(overflow);
+        if (Buffer.isBuffer(head)) {
+          this.chunks[0] = head.subarray(overflow);
+        } else {
+          this.chunks.shift();
+          this.size -= head.length;
+        }
         this.size -= overflow;
       }
     }
   }
 
   toString() {
-    if (this.chunks.length === 0) return '';
-    return Buffer.concat(this.chunks).toString('utf8');
+    if (this.chunks.length === 0) {return '';}
+    return Buffer.concat(/** @type {Buffer[]} */(this.chunks)).toString('utf8');
   }
 }
 
@@ -51,6 +62,11 @@ class TailBuffer {
  *
  * Pure I/O wrapper: no policy, no retry, no agent knowledge.
  */
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{stdoutSink?: NodeJS.WriteStream, stderrSink?: NodeJS.WriteStream, maxTailBytes?: number, noOutputWatchdog?: {onNoOutput?: Function, initialDelayMs?: number, intervalMs?: number}, cwd?: string, env?: Record<string, string>, [key: string]: any}} [options]
+ */
 function spawnAndTee(command, args, options = {}) {
   const {
     stdoutSink = process.stdout,
@@ -63,8 +79,11 @@ function spawnAndTee(command, args, options = {}) {
   return new Promise((resolve) => {
     const stdoutTail = new TailBuffer(maxTailBytes);
     const stderrTail = new TailBuffer(maxTailBytes);
+    /** @type {boolean} */
     let settled = false;
+    /** @type {boolean} */
     let sawOutput = false;
+    /** @type {ReturnType<typeof setTimeout> | null} */
     let watchdogTimer = null;
     const startTime = Date.now();
     const resolvedCwd = path.resolve(spawnOptions.cwd || process.cwd());
@@ -96,8 +115,9 @@ function spawnAndTee(command, args, options = {}) {
       }
     };
 
+    /** @param {{status: number|null, signal: string|null, stdout: string, stderr: string, error: any, startedAt: string, endedAt: string}} payload */
     const finish = (payload) => {
-      if (settled) return;
+      if (settled) {return;}
       settled = true;
       clearWatchdog();
       payload.startedAt = new Date(startTime).toISOString();
@@ -105,19 +125,22 @@ function spawnAndTee(command, args, options = {}) {
       resolve(payload);
     };
 
+    /** @param {number} delayMs */
     const scheduleWatchdog = (delayMs) => {
-      if (!noOutputWatchdog || typeof noOutputWatchdog.onNoOutput !== 'function') return;
+      if (!noOutputWatchdog || typeof noOutputWatchdog.onNoOutput !== 'function') {return;}
       const delay = Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : 0;
       watchdogTimer = setTimeout(() => {
         watchdogTimer = null;
-        if (settled || sawOutput) return;
-        noOutputWatchdog.onNoOutput({
+        if (settled || sawOutput) {return;}
+        if (typeof noOutputWatchdog.onNoOutput === 'function') {
+          noOutputWatchdog.onNoOutput({
           command,
           args,
           pid: child.pid,
           elapsedMs: Date.now() - startTime
         });
-        scheduleWatchdog(noOutputWatchdog.intervalMs);
+      }
+        scheduleWatchdog(noOutputWatchdog.intervalMs ?? 0);
       }, delay);
       if (typeof watchdogTimer.unref === 'function') {
         watchdogTimer.unref();
@@ -130,7 +153,7 @@ function spawnAndTee(command, args, options = {}) {
     };
 
     if (noOutputWatchdog) {
-      scheduleWatchdog(noOutputWatchdog.initialDelayMs);
+      scheduleWatchdog(noOutputWatchdog.initialDelayMs ?? 0);
     }
 
     child.stdout.on('data', (chunk) => {
@@ -148,23 +171,27 @@ function spawnAndTee(command, args, options = {}) {
       }
     });
 
-    child.on('error', (err) => {
+    child.on('error', (/** @type {Error} */ err) => {
       finish({
         status: null,
         signal: null,
         stdout: stdoutTail.toString(),
         stderr: stderrTail.toString(),
-        error: err
+        error: err,
+        startedAt: new Date(startTime).toISOString(),
+        endedAt: new Date().toISOString()
       });
     });
 
-    child.on('close', (code, signal) => {
+    child.on('close', (/** @type {number|null} */ code, /** @type {string|null} */ signal) => {
       finish({
         status: code,
         signal,
         stdout: stdoutTail.toString(),
         stderr: stderrTail.toString(),
-        error: null
+        error: null,
+        startedAt: new Date(startTime).toISOString(),
+        endedAt: new Date().toISOString()
       });
     });
   });

package/lib/core/state-map.js

@@ -4,25 +4,29 @@ const { loadEffectiveConfig } = require('./product-config');
 
 const SHIPPED_STATE_MAP_PATH = path.join(__dirname, '..', '..', 'config', 'state-map.json');
 
+/** @param {string} rootDir @param {string} repoRelativePath */
 function resolveRepoRelativePath(rootDir, repoRelativePath) {
-  if (!repoRelativePath || typeof repoRelativePath !== 'string') return null;
+  if (!repoRelativePath || typeof repoRelativePath !== 'string') {return null;}
   return path.isAbsolute(repoRelativePath)
     ? repoRelativePath
     : path.join(rootDir, repoRelativePath);
 }
 
+/** @param {{rootDir?: string, config?: any, fallbackPath?: string}|string} [options] */
 function resolveStateMapPath(options = {}) {
-  if (typeof options === 'string') return options;
+  if (typeof options === 'string') {return options;}
 
-  const rootDir = options.rootDir || process.cwd();
-  const config = options.config || loadEffectiveConfig(rootDir);
+  /** @type {{rootDir?: string, config?: any, fallbackPath?: string}} */
+  const opts = options;
+  const rootDir = opts.rootDir || process.cwd();
+  const config = opts.config || loadEffectiveConfig(rootDir);
   const configuredPath = config.adapters?.tasks?.stateMap;
   const repoPath = resolveRepoRelativePath(rootDir, configuredPath);
 
   if (repoPath && fs.existsSync(repoPath)) {
     return repoPath;
   }
-  return options.fallbackPath || SHIPPED_STATE_MAP_PATH;
+  return opts.fallbackPath || SHIPPED_STATE_MAP_PATH;
 }
 
 function loadStateMap(options = {}) {
@@ -34,14 +38,16 @@ function loadStateMap(options = {}) {
   }
 }
 
+/** @param {unknown} value */
 function normalizeState(value) {
-  if (typeof value !== 'string') return value;
+  if (typeof value !== 'string') {return value;}
   return value.trim().toLowerCase();
 }
 
 // Virtual workflow state → actual backlog.md state name.
 // Returns null if the virtual state explicitly maps to null (no backlog.md write).
 // Returns the virtual name unchanged if it has no entry in the map (identity).
+/** @param {Record<string, any> | any} mapOrOptions */
 function resolveMap(mapOrOptions) {
   if (mapOrOptions && typeof mapOrOptions === 'object' && !Array.isArray(mapOrOptions)) {
     if (Object.prototype.hasOwnProperty.call(mapOrOptions, 'rootDir')
@@ -53,33 +59,46 @@ function resolveMap(mapOrOptions) {
   return mapOrOptions || loadStateMap();
 }
 
+/** @param {string} virtualState @param {Record<string, any>} [map] */
 function toActual(virtualState, map = loadStateMap()) {
-  map = resolveMap(map);
-  if (Object.prototype.hasOwnProperty.call(map, virtualState)) {
-    return map[virtualState];
+  /** @type {Record<string, any>} */
+  const m = resolveMap(map) || {};
+  if (Object.prototype.hasOwnProperty.call(m, virtualState)) {
+    return m[virtualState];
   }
   return virtualState;
 }
 
 // Actual backlog.md state name → virtual workflow state name.
 // Returns the actual name unchanged if no reverse mapping exists (identity).
+/** @param {string} actualState @param {Record<string, any>} [map] */
 function toVirtual(actualState, map = loadStateMap()) {
-  map = resolveMap(map);
+  /** @type {Record<string, any>} */
+  const m = resolveMap(map) || {};
   const normalizedActual = normalizeState(actualState);
-  for (const [virtual, actual] of Object.entries(map)) {
-    if (normalizeState(actual) === normalizedActual) return virtual;
+  for (const [virtual, actual] of Object.entries(m)) {
+    if (normalizeState(actual) === normalizedActual) {return virtual;}
   }
   return actualState;
 }
 
 // Wraps a transitionTask call: resolves virtual → actual, then delegates.
 // If the virtual state maps to null, logs an info line and returns true (no-op).
+/**
+ * @param {Function} transitionTaskFn
+ * @param {string} slug
+ * @param {string} virtualState
+ * @param {{log?: Function}} [options]
+ * @param {Record<string, any>} [map]
+ */
 function transitionVirtual(transitionTaskFn, slug, virtualState, options = {}, map = loadStateMap(options)) {
   map = resolveMap(map);
   const actual = toActual(virtualState, map);
   if (actual === null) {
     const fmt = require('./fmt');
-    const log = options.log || fmt.log.plain;
+    /** @type {{log?: Function}} */
+    const opts = options;
+    const log = opts.log || fmt.log.plain;
     log(fmt.status('INFO', `Virtual state '${virtualState}' has no backlog.md mapping for this board; skipping status write.`));
     return true;
   }

package/lib/core/storage.js

@@ -17,18 +17,23 @@ const path = require('path');
  * call with `ensureDir: true`). Read-side callers may omit ensureDir so they
  * fail gracefully when PARALLIX_HOME has never been initialized.
  */
+/**
+ * @param {{ensureDir?: boolean, platform?: string, env?: Record<string,string>, homedir?: Function} | boolean | string} [options]
+ */
 function resolveParallixHome(options = {}) {
   if (typeof options === 'boolean' || typeof options === 'string') {
     // Legacy shim: resolveParallixHome(true) === { ensureDir: true }
-    options = { ensureDir: options };
+    options = { ensureDir: Boolean(options) };
   }
 
+  /** @type {{ensureDir?: boolean, platform?: string, env?: Record<string,string>, homedir?: Function}} */
+  const opts = /** @type {{ensureDir?: boolean, platform?: string, env?: Record<string,string>, homedir?: Function}} */(options);
   const {
     ensureDir = false,
     platform = process.platform,
     env = process.env,
     homedir = os.homedir
-  } = options;
+  } = opts;
 
   let home;
 
@@ -67,8 +72,11 @@ function resolveParallixHome(options = {}) {
  * is true). Callers that pass an explicit `--csv-file` path bypass this
  * resolver entirely — the caller supplies the path before calling here.
  */
+/** @param {{ensureDir?: boolean, warn?: Function}} [options] */
 function resolveStatsPath(options = {}) {
-  const home = resolveParallixHome({ ensureDir: options.ensureDir !== false, warn: options.warn });
+  /** @type {{ensureDir?: boolean, warn?: Function}} */
+  const opts = options;
+  const home = resolveParallixHome({ ensureDir: opts.ensureDir !== false });
   return path.join(home, 'stats.csv');
 }
 
@@ -78,11 +86,14 @@ function resolveStatsPath(options = {}) {
  * Returns `<PARALLIX_HOME>/agents.local.json`.  Callers that pass an
  * explicit `targetPath` bypass this resolver.
  */
+/** @param {{ensureDir?: boolean} | string} [options] */
 function resolveAgentsLocalPath(options = {}) {
   if (typeof options === 'string') {
     return path.resolve(options);
   }
-  const home = resolveParallixHome({ ensureDir: options.ensureDir !== false });
+  /** @type {{ensureDir?: boolean}} */
+  const opts = options;
+  const home = resolveParallixHome({ ensureDir: opts.ensureDir !== false });
   return path.join(home, 'agents.local.json');
 }
 
@@ -94,6 +105,7 @@ function resolveAgentsLocalPath(options = {}) {
  * Malformed JSON returns `{ ok: false, error }` rather than throwing so
  * callers can decide whether this is a hard failure.
  */
+/** @param {string | (() => string)} pathOrResolution */
 function readJson(pathOrResolution) {
   let filePath;
   if (typeof pathOrResolution === 'function') {
@@ -119,6 +131,7 @@ function readJson(pathOrResolution) {
  * Write JSON to a path under PARALLIX_HOME (or an explicit path).
  * Creates parent directories as needed.
  */
+/** @param {string | (() => string)} filePath @param {any} data */
 function writeJson(filePath, data) {
   if (typeof filePath === 'function') {
     filePath = filePath();
@@ -127,6 +140,7 @@ function writeJson(filePath, data) {
   return filePath;
 }
 
+/** @param {string} filePath @param {string} content */
 function writeFileAtomic(filePath, content) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const tempPath = path.join(
@@ -137,7 +151,7 @@ function writeFileAtomic(filePath, content) {
     fs.writeFileSync(tempPath, content, 'utf8');
     fs.renameSync(tempPath, filePath);
   } finally {
-    if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+    if (fs.existsSync(tempPath)) {fs.unlinkSync(tempPath);}
   }
 }
 

package/lib/core/subagent-limit.js

@@ -0,0 +1,28 @@
+const { loadEffectiveConfig } = require('./product-config');
+
+// Build a prompt-injection prefix that instructs the agent to limit
+// concurrent subagent forks. Returns a non-empty advisory string when
+// maxParallel >= 1, or an empty string when the setting is absent, null,
+// zero, or negative (backward-compatible default).
+//
+// Prefix length target: under 200 characters.
+//
+// @param {number | null | undefined} [maxParallel] — explicit value override;
+//   when omitted the function reads from the effective workflow config.
+/** @param {number | null | undefined} [maxParallel] */
+function buildSubagentLimitPrefix(maxParallel) {
+  let value = maxParallel;
+  if (value === undefined || value === null) {
+    const cfg = loadEffectiveConfig();
+    const sub = cfg.adapters?.agents?.subagents;
+    value = sub && typeof sub.maxParallel === 'number' ? sub.maxParallel : null;
+  }
+  if (typeof value !== 'number' || value < 1) {
+    return '';
+  }
+  return `Do not spawn more than ${value} parallel subagents. If you need more, pause and wait.\n`;
+}
+
+module.exports = {
+  buildSubagentLimitPrefix,
+};

package/lib/core/verification.js

@@ -1,4 +1,6 @@
 const { git, run } = require('./git');
+
+/** @typedef {(args: string[], options?: object) => import('child_process').SpawnSyncReturns<string>} GitFn */
 const { loadAdapterConfig } = require('./product-config');
 const fs = require('fs');
 
@@ -23,33 +25,40 @@ function resolveVerificationAdapter(rootDir = process.cwd()) {
   return { command, defaultArea };
 }
 
+/** @param {string} [area] @param {string} [rootDir] */
 function formatVerificationCommand(area, rootDir = process.cwd()) {
   const { command, defaultArea } = resolveVerificationAdapter(rootDir);
   const effectiveArea = area || defaultArea;
   if (!command) {
     return NO_GATE_NOTICE;
   }
-  return command.replaceAll('{{area}}', effectiveArea);
+  return command.replaceAll('{{area}}', effectiveArea || DEFAULT_AREA);
 }
 
+/** @param {string} [area] @param {{rootDir?: string, log?: Function, stdio?: string, runFn?: Function}} [options] */
 function runVerificationGate(area, options = {}) {
-  const rootDir = options.rootDir || process.cwd();
+  /** @type {{rootDir?: string, log?: Function, stdio?: string, runFn?: Function}} */
+  const opts = options;
+  const rootDir = opts.rootDir || process.cwd();
   const { command, defaultArea } = resolveVerificationAdapter(rootDir);
   const effectiveArea = area || defaultArea;
 
   if (!command) {
-    const info = options.log || require('./fmt').log.info;
+    const info = opts.log || require('./fmt').log.info;
     info(`No verification gate configured for area: ${effectiveArea}; default is no validation. `
       + 'Set adapters.verification.command in workflow.config.json to enforce one.');
     return { status: 0 };
   }
 
-  const stdio = options.stdio || 'inherit';
-  const runFn = options.runFn || run;
+  const stdio = opts.stdio || 'inherit';
+  const runFn = opts.runFn || run;
   return runFn('bash', ['-lc', command.replaceAll('{{area}}', effectiveArea)], { cwd: rootDir, stdio });
 }
 
-function readPublishedTreeState(rootDir = process.cwd(), { gitRunner = git } = {}) {
+/** @param {string} rootDir @param {{gitRunner?: GitFn}} [options] */
+function readPublishedTreeState(rootDir, options = {}) {
+  /** @type {GitFn} */
+  const gitRunner = options.gitRunner || git;
   const resolvedRoot = fs.realpathSync(rootDir);
   const commitResult = gitRunner(['-C', resolvedRoot, 'rev-parse', 'HEAD']);
   const treeResult = gitRunner(['-C', resolvedRoot, 'rev-parse', 'HEAD^{tree}']);
@@ -66,6 +75,7 @@ function readPublishedTreeState(rootDir = process.cwd(), { gitRunner = git } = {
   return { ok: true, rootDir: resolvedRoot, commit, tree };
 }
 
+/** @param {string} [area] @param {string} [rootDir] @param {{gitRunner?: GitFn, runFn?: Function, stdio?: string}} [options] */
 function captureVerifiedTreeProof(area, rootDir = process.cwd(), options = {}) {
   const {
     gitRunner = git,
@@ -74,7 +84,7 @@ function captureVerifiedTreeProof(area, rootDir = process.cwd(), options = {}) {
   } = options;
 
   const before = readPublishedTreeState(rootDir, { gitRunner });
-  if (!before.ok) return before;
+  if (!before.ok) {return before;}
 
   const verification = runVerificationGate(area, {
     rootDir: before.rootDir,
@@ -88,8 +98,8 @@ function captureVerifiedTreeProof(area, rootDir = process.cwd(), options = {}) {
     };
   }
 
-  const after = readPublishedTreeState(before.rootDir, { gitRunner });
-  if (!after.ok) return after;
+  const after = readPublishedTreeState(/** @type {string} */(before.rootDir), { gitRunner });
+  if (!after.ok) {return after;}
   if (after.commit !== before.commit || after.tree !== before.tree) {
     return {
       ok: false,
@@ -113,13 +123,17 @@ function captureVerifiedTreeProof(area, rootDir = process.cwd(), options = {}) {
   };
 }
 
-function assertVerifiedTreeProof(proof, rootDir = process.cwd(), { gitRunner = git } = {}) {
+/** @param {{rootDir?: string, commit?: string, tree?: string}} proof @param {string} [rootDir] @param {{gitRunner?: GitFn}} [opts] */
+function assertVerifiedTreeProof(proof, rootDir = process.cwd(), opts = {}) {
   if (!proof || typeof proof !== 'object') {
     return { ok: false, error: 'missing verification proof' };
   }
 
+  /** @type {{gitRunner?: GitFn}} */
+  const o = opts;
+  const gitRunner = o.gitRunner || git;
   const current = readPublishedTreeState(rootDir, { gitRunner });
-  if (!current.ok) return current;
+  if (!current.ok) {return current;}
 
   if (proof.rootDir !== current.rootDir) {
     return { ok: false, error: `verification proof was captured from a different checkout: ${proof.rootDir}` };
@@ -131,8 +145,11 @@ function assertVerifiedTreeProof(proof, rootDir = process.cwd(), { gitRunner = g
   return { ok: true, proof: current };
 }
 
+/** @param {string[]} args @param {{log?: Function}} [options] */
 function runWorkflow(args, options = {}) {
-  const log = options.log || require('./fmt').log.plain;
+  /** @type {{log?: Function}} */
+  const opts = options;
+  const log = opts.log || require('./fmt').log.plain;
   const area = args[0] || process.env.VERIFY_AREA || DEFAULT_AREA;
   log(`Running verification gate for area: ${area}...`);
   return runVerificationGate(area, { stdio: 'inherit' });

package/lib/review/rebase.js

@@ -18,6 +18,10 @@ const SHARED_FILE_REBASE_CONFLICT_RE = /shared file(?:\(s\))? require agent-assi
 /**
  * Auto-commit safe mission artifacts before rebase.
  * Only touches mission-generated files, task files, and stats CSV.
+ * @param {string} slug
+ * @param {string} worktree
+ * @param {{taskFile?: string|null, gitFn?: Function, log?: Function, error?: Function, isMissionArtifactFn?: Function, isWorkflowGeneratedArtifactFn?: Function, resolveStatsRelPathFn?: Function}} [options]
+ * @returns {Promise<{ok: boolean, dirty: boolean, unsafe?: boolean}>}
  */
 async function commitSafeMissionArtifacts(slug, worktree, {
   taskFile = null,
@@ -34,13 +38,14 @@ async function commitSafeMissionArtifacts(slug, worktree, {
     return { ok: true, dirty: false };
   }
 
-  const parsePorcelainZ = (stdout) => {
+  const parsePorcelainZ = (/** @type {string|Buffer} */ stdout) => {
     const entries = String(stdout).split('\0').filter(Boolean);
     const dirty = [];
     for (let i = 0; i < entries.length; i += 1) {
       const entry = entries[i];
       const xy = entry.slice(0, 2);
       const file = entry.slice(3);
+      /** @type {{xy: string, file: string, paths: string[], source?: string}} */
       const record = { xy, file, paths: [file] };
       if ((xy[0] === 'R' || xy[0] === 'C') && i + 1 < entries.length) {
         const source = entries[i + 1];
@@ -63,7 +68,7 @@ async function commitSafeMissionArtifacts(slug, worktree, {
 
   const resolvedTaskFile = taskFile ? path.relative(rootDir, taskFile) : null;
   const statsRelPath = resolveStatsRelPathFn(rootDir);
-  const isSafeToCommit = (file) =>
+  const isSafeToCommit = (/** @type {string} */ file) =>
     isWorkflowGeneratedArtifactFn(file)
     || isMissionArtifactFn(file, slug, rootDir)
     || (resolvedTaskFile && file === resolvedTaskFile)
@@ -71,7 +76,7 @@ async function commitSafeMissionArtifacts(slug, worktree, {
 
   const unsafeFiles = dirtyFiles
     .flatMap(f => f.paths)
-    .filter(file => !isSafeToCommit(file));
+    .filter((/** @type {string} */ file) => !isSafeToCommit(file));
   if (unsafeFiles.length > 0) {
     error(fmt.status('FAIL', `Cannot auto-commit: dirty files include non-mission paths:`));
     unsafeFiles.forEach(file => error(`       - ${file}`));
@@ -100,6 +105,9 @@ async function commitSafeMissionArtifacts(slug, worktree, {
  *
  * Always commits safe worktree state first, then rebases via the workflow CLI.
  * In standalone (provider-disabled) mode, skips the rebase after committing.
+ * @param {string} slug
+ * @param {{runFn?: Function, gitFn?: Function, taskFile?: string|null, worktree?: string, log?: Function, error?: Function, isReviewProviderEnabledFn?: Function|null, legacyIsForgejoReviewEnabledFn?: Function|null, isForgejoReviewEnabledFn?: Function|null}} [options]
+ * @returns {Promise<{ok: boolean, sharedFileConflicts: boolean}>}
  */
 async function rebaseBeforeReviewRound(slug, {
   runFn = require('child_process').spawnSync,