@syntax-syllogism/aloop 0.6.2 → 0.8.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
 
+## [0.7.0] - 2026-09-18
+
+### Added
+
+- **Gemini engine.** `gemini` joins `claude`, `codex`, and `agy` as a built-in
+  engine. Any phase can run on the Gemini CLI via `engines.*.name = 'gemini'` or
+  `--engine gemini`. Headless phases run with `--approval-mode` (`plan` when
+  read-only, `yolo` when writing), `--skip-trust` so a fresh worktree is
+  trusted, and `--output-format stream-json` so long phases stay watchable.
+  Gemini has no reasoning-effort flag, so a configured `effort` is ignored for
+  it.
+
 ## [0.6.0] - 2026-09-14
 
 ### Added
@@ -183,6 +195,26 @@ History from before the standalone extraction (changesets format), preserved for
   - Prompts ship with the package and are overridable per phase from
     `.loop/prompts/` in the consuming project.
 
+## [0.8.0] - 2026-09-20
+
+### Added
+
+- Eval harness for running code across multiple models
+- JSDoc type checking for validation
+- Live TUI renderer for interactive aloop runs
+- aloop init command for project initialization
+- Guided resume capability to repair failing gates
+
+### Changed
+
+- TUI renderer now runs even with --yes flag
+
+### Fixed
+
+- JSDoc type contracts bound to production boundaries
+- Fixed TUI rendering performance with diff-stat caching
+- Resume repair and downstream attestation restored
+
 ## [0.6.2] - 2026-09-16
 
 ### Fixed

package/README.md

@@ -28,7 +28,13 @@ Interactive confirmations use the Git Bash/Windows console when available. Use
 
 ## Quick start
 
-From a git repository with a `loop.config.mjs` (or with the defaults):
+From a git repository, create the editable configuration and prompt overrides:
+
+```sh
+aloop init
+```
+
+Review the generated `loop.config.mjs`, then start a task:
 
 ```sh
 aloop --task "Add request tracing" --name request-tracing
@@ -67,7 +73,8 @@ complete guide, manifest schema, and verdict contract.
 
 ## Configuration
 
-Create `loop.config.mjs` in the repository being operated on:
+`aloop init` creates a commented `loop.config.mjs` in the repository being
+operated on. Adjust it as needed; for example, a configuration can be:
 
 ```js
 export default {
@@ -85,9 +92,10 @@ export default {
 };
 ```
 
-Supported built-in engines are `claude`, `codex`, and `agy`. The corresponding
-CLI must already be installed and authenticated. Engine descriptors may include
-an engine-specific `model` and `effort`. `--config` selects a configuration
+Supported built-in engines are `claude`, `codex`, `agy`, and `gemini`. The
+corresponding CLI must already be installed and authenticated. Engine
+descriptors may include an engine-specific `model` and `effort` (Gemini has no
+effort tier, so a configured `effort` is ignored for it). `--config` selects a configuration
 file outside the current repository; command-line phase and round options take
 precedence.
 
@@ -124,12 +132,13 @@ placeholder is unresolved.
 For repositories using Markdown work items, install the bundled preset:
 
 ```sh
-mkdir -p .loop/prompts
-cp -r node_modules/@syntax-syllogism/aloop/presets/work-item/prompts/. .loop/prompts/
+aloop init --preset work-item
 ```
 
-The preset includes prompts and a sample configuration. Adapt it to the
-repository's branches and gates before use.
+This creates the preset's sample configuration and prompt overrides. Adapt its
+branches and gates before use. `aloop init` also copies the default prompts, so
+you can edit any `.loop/prompts/<phase>.md` immediately; see
+[`docs/loop.md`](docs/loop.md#getting-started) for overwrite and preset details.
 
 ## Building up to unattended runs
 
@@ -140,6 +149,13 @@ Use this progression:
 3. Exercise the review loop with `--max-rounds 2`.
 4. Add `-y` only for task shapes whose behavior is already understood.
 
+## Evaluation harness
+
+`aloop-eval <spec.mjs>` runs a task corpus across a model/config matrix, each
+cell in its own throwaway repository, and reports completion, escaped
+defects, convergence, and cost per cell and per config. See
+[`docs/eval.md`](docs/eval.md) for the spec file shape and reported fields.
+
 ## Development
 
 ```sh

package/bin/eval.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isMainEntrypoint } from '../src/entrypoint.mjs';
+import { formatEvalSummaryTable, formatEvalTable, runEval, summarizeEval } from '../src/eval.mjs';
+
+export function usage() {
+  return [
+    'Usage: aloop-eval <spec.mjs> [options]',
+    '',
+    'Runs the task corpus and model/config matrix exported by <spec.mjs>',
+    '(a default export, or named `corpus` and `matrix` exports) through the',
+    'loop and reports completion, escaped defects, convergence, cost, and time.',
+    '',
+    'Options:',
+    '      --json    Emit machine-readable JSON instead of tables',
+  ].join('\n');
+}
+
+export async function runEvalCli(argv, { cwd = process.cwd(), output = console } = {}) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: { json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+    allowPositionals: true,
+    strict: true,
+  });
+  if (values.help || !positionals.length) {
+    output.log(usage());
+    return null;
+  }
+  const [specPath] = positionals;
+  const spec = await import(pathToFileURL(resolve(cwd, specPath)).href);
+  const { corpus, matrix } = spec.default ?? spec;
+  if (!Array.isArray(corpus) || !Array.isArray(matrix)) {
+    throw new Error(`${specPath} must export a task \`corpus\` array and a config \`matrix\` array.`);
+  }
+  const results = await runEval({ corpus, matrix });
+  const summaries = summarizeEval(results);
+  if (values.json) {
+    output.log(JSON.stringify({ results, summaries }, null, 2));
+  } else {
+    output.log(formatEvalTable(results));
+    output.log('');
+    output.log(formatEvalSummaryTable(summaries));
+  }
+  return { results, summaries };
+}
+
+if (isMainEntrypoint(import.meta.url)) {
+  try {
+    await runEvalCli(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/bin/loop.mjs

@@ -10,6 +10,7 @@ import {
   doctor,
   getAggregateMetrics,
   getRun,
+  init,
   inspectRun,
   listRuns,
   resolveRunsDir,
@@ -17,7 +18,7 @@ import {
 import { computeRunMetrics } from '../src/metrics.mjs';
 import { runLoop } from '../src/pipeline.mjs';
 
-const commands = new Set(['run', 'list', 'status', 'inspect', 'cancel', 'clean', 'doctor', 'metrics']);
+const commands = new Set(['run', 'list', 'status', 'inspect', 'cancel', 'clean', 'doctor', 'metrics', 'init']);
 
 export function parseLoopArgs(argv) {
   const command = commands.has(argv[0]) ? argv[0] : 'run';
@@ -37,12 +38,17 @@ export function parseLoopArgs(argv) {
       'max-rounds': { type: 'string' },
       from: { type: 'string' },
       resume: { type: 'boolean' },
+      note: { type: 'string' },
+      'note-file': { type: 'string' },
       yes: { type: 'boolean', short: 'y' },
       'no-worktree': { type: 'boolean' },
+      'no-tui': { type: 'boolean' },
       'dry-run': { type: 'boolean' },
       json: { type: 'boolean' },
       metrics: { type: 'boolean' },
       'older-than': { type: 'string' },
+      preset: { type: 'string' },
+      force: { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
     },
     allowPositionals: true,
@@ -79,12 +85,17 @@ export function parseLoopArgs(argv) {
     maxRounds,
     from: values.from,
     resume: values.resume,
+    note: values.note,
+    noteFile: values['note-file'],
     yes: values.yes,
     noWorktree: values['no-worktree'],
+    noTui: values['no-tui'],
     dryRun: values['dry-run'],
     json: values.json,
     metrics: values.metrics,
     olderThanDays,
+    preset: values.preset,
+    force: values.force,
   };
 }
 
@@ -100,6 +111,7 @@ export function usage() {
     '  cancel <name>           Stop a run and release its lock',
     '  clean                   Preview/remove completed runs older than 30 days',
     '  doctor                  Check configuration and local tooling',
+    '  init                    Scaffold loop.config.mjs and .loop/prompts',
     '  run                     Start or resume a run (the default)',
     '',
     'Operational options:',
@@ -109,20 +121,27 @@ export function usage() {
     '  -y, --yes               Confirm destructive clean operations',
     '      --dry-run           Preview clean operations without changing files',
     '',
+    'Init options:',
+    '      --preset <name>     Seed init from a bundled preset (e.g. work-item)',
+    '      --force             Overwrite existing scaffold files',
+    '',
     'Run options:',
     '  -t, --task <text>       Inline task description',
     '  -f, --task-file <path>  Path to a task/plan/spec file',
     '  -n, --name <slug>       Explicit run identity/slug',
     '  -b, --branch <name>     Branch to build on (default: <branchPrefix><name>)',
     '      --base-branch <branch>  Base to branch from and PR against (default: baseBranch config)',
-    '  -e, --engine <name>     Default engine: claude | codex | agy',
+    '  -e, --engine <name>     Default engine: claude | codex | agy | gemini',
     '      --override-engine   With --resume and --engine, replace saved agent executables',
     '      --config <path>     Load loop configuration from this file (also overrides saved config on resume)',
     '      --phases a,b,c      Override the configured phase list',
     '      --max-rounds <n>    Cap on review/repair rounds',
     '      --from <phase>      Start at this phase',
     '      --resume            Skip phases already recorded complete',
+    '      --note <text>       Give the resumed phase an authoritative instruction',
+    '      --note-file <path>  Read the instruction from a file (--note wins)',
     '      --no-worktree       Work in the current checkout instead of a worktree',
+    '      --no-tui            Force plain streaming output (TUI is on by default on a TTY)',
     '  -y, --yes               Run unattended (no per-phase confirmation; required without a terminal)',
     '      --dry-run           Print the plan and rendered prompts, run nothing',
   ].join('\n');
@@ -258,6 +277,16 @@ export async function runOperationalCommand(args, { cwd = process.cwd(), output
     }
     return result;
   }
+  if (args.command === 'init') {
+    const result = await init({ cwd, preset: args.preset, force: args.force });
+    if (args.json) output.log(JSON.stringify(result, null, 2));
+    else {
+      for (const file of result.created) output.log(`  create  ${file}`);
+      for (const file of result.skipped) output.log(`  skip    ${file} (exists)`);
+      output.log(result.preset ? `Initialized aloop with preset "${result.preset}".` : 'Initialized aloop.');
+    }
+    return result;
+  }
   throw new Error(`Unknown command: ${args.command}`);
 }
 
@@ -270,7 +299,7 @@ if (isMainEntrypoint(import.meta.url)) {
       await runLoop({ args });
     } else {
       const result = await runOperationalCommand(args);
-      if (args.command === 'doctor' && !result.ok) process.exitCode = 1;
+      if (args.command === 'doctor' && !(/** @type {any} */ (result)).ok) process.exitCode = 1;
     }
   } catch (error) {
     console.error(error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntax-syllogism/aloop",
-  "version": "0.6.2",
+  "version": "0.8.1",
   "description": "Syntax & Syllogism agentic loop runner.",
   "type": "module",
   "exports": {
@@ -13,7 +13,8 @@
     "node": ">=22"
   },
   "bin": {
-    "aloop": "bin/loop.mjs"
+    "aloop": "bin/loop.mjs",
+    "aloop-eval": "bin/eval.mjs"
   },
   "files": [
     "bin",
@@ -31,6 +32,7 @@
     "claude",
     "codex",
     "antigravity",
+    "gemini",
     "opencode",
     "cli"
   ],
@@ -47,6 +49,11 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^5.9.3"
   }
 }

package/presets/work-item/README.md

@@ -18,14 +18,16 @@ branches, engines, phases, and `npm test` gate. Adjust it for your repository.
 
 ## Installation
 
-Install the package, create `.loop/prompts/`, and copy the preset prompts into
-the project override directory:
+Install the package, then initialize the project with the preset:
 
 ```sh
-mkdir -p .loop/prompts
-cp -r node_modules/@syntax-syllogism/aloop/presets/work-item/prompts/. .loop/prompts/
+aloop init --preset work-item
 ```
 
-The runner loads project prompt overrides before its packaged defaults. Keep the
-sample config as a starting point for `loop.config.mjs` if its settings match
-your repository.
+This writes the sample config and preset prompts into your project, with the
+packaged defaults filling any prompts the preset does not provide. The runner
+loads project prompt overrides before its packaged defaults.
+
+If you prefer to wire it up by hand, create `.loop/prompts/` and copy the
+contents of `node_modules/@syntax-syllogism/aloop/presets/work-item/prompts/`
+there; copy `loop.config.mjs` separately if its settings match your repository.

package/prompts/fix-gate.md

@@ -0,0 +1,17 @@
+{{TASK_CONTEXT}}
+
+The deterministic gate is failing. Work in `{{REPO}}` on branch `{{BRANCH}}`
+and make the gate pass by fixing the underlying implementation.
+
+## Gate status
+
+{{GATE_STATUS}}
+
+## Gate commands
+
+{{GATE_COMMANDS}}
+
+Do not delete, skip, or weaken tests or gate commands to make the gate pass.
+Make only the changes needed to correct the failure, run the relevant tests and
+the gate commands, then commit the repair with a conventional commit message.
+Keep the worktree clean for the re-check.

package/src/adapters.mjs

@@ -1,3 +1,7 @@
+/** @typedef {import('./types.js').Adapter} Adapter */
+/** @typedef {import('./types.js').Config} Config */
+/** @typedef {import('./types.js').Engine} Engine */
+
 /**
  * Engine adapters.
  *
@@ -71,6 +75,24 @@ function summarizeAgyParams(params) {
   return '';
 }
 
+/**
+ * Summarize a Gemini tool call's parameters.
+ *
+ * Gemini's built-in tools use the descriptive keys the shared summarizer already
+ * knows (`command`, `file_path`, `path`, `pattern`, `url`, …); an MCP tool may
+ * use anything, so fall back to the first string value — robust to tools this
+ * list has never seen, the same shape as `summarizeAgyParams`.
+ */
+function summarizeGeminiParams(params) {
+  if (!params || typeof params !== 'object') return '';
+  const known = summarizeToolInput(params);
+  if (known) return known;
+  for (const value of Object.values(params)) {
+    if (typeof value === 'string' && value.trim()) return condense(value);
+  }
+  return '';
+}
+
 function cliVersion(command) {
   return async () => {
     const cwd = await mkdtemp(join(tmpdir(), 'aloop-version-'));
@@ -163,6 +185,63 @@ export function renderAgyEvent(event) {
   return '';
 }
 
+/**
+ * Turn one Gemini stream-json event into the line a watching human wants.
+ *
+ * Gemini tags each event with `type` (like Claude, unlike agy's `event`). The
+ * headless stream emits `init` (session), `message` (user/assistant turns —
+ * assistant text streams as deltas), `tool_use` (a tool the model invoked, with
+ * `tool_name`/`parameters`), `tool_result` (its outcome, `status` success|error
+ * with an `error.message`), `error` (non-fatal warnings and system errors), and
+ * `result` (final status, token counts under `stats`). Tool activity and tool
+ * or system failures are surfaced so a long phase stays watchable; a successful
+ * tool result is not — its full output would bury the log, exactly as the
+ * claude and agy renderers omit theirs. An unrecognized shape renders as nothing
+ * rather than raw JSON, so the enormous init payload and any event a future
+ * release adds stay out of the log.
+ */
+export function renderGeminiEvent(event) {
+  if (event.type === 'init') {
+    const id = String(event.session_id ?? '').slice(0, 8);
+    const model = event.model;
+    return `  · session ${id}${model ? ` model ${model}` : ''}\n`;
+  }
+  if (event.type === 'message') {
+    // Assistant text arrives as deltas; stream them through verbatim. The user
+    // turn is the prompt aloop already wrote, so echoing it back is noise.
+    if (event.role !== 'assistant' || typeof event.content !== 'string') return '';
+    return event.content;
+  }
+  if (event.type === 'tool_use') {
+    const detail = summarizeGeminiParams(event.parameters);
+    return `  → ${event.tool_name ?? 'tool'}${detail ? ` ${detail}` : ''}\n`;
+  }
+  if (event.type === 'tool_result') {
+    // Only failures are worth a line; a successful result's `output` is the
+    // tool's full stdout and belongs in the phase's files, not the run log.
+    if (event.status !== 'error') return '';
+    const message = event.error?.message ?? event.output ?? 'tool call failed';
+    return `  ✗ ${condense(String(message), 160)}\n`;
+  }
+  if (event.type === 'error') {
+    // Non-fatal warnings and system errors — a warning is marked, not dropped,
+    // so a stall or a blocked turn is visible while the phase runs.
+    const mark = event.severity === 'warning' ? '⚠' : '✗';
+    return `  ${mark} ${condense(String(event.message ?? 'error'), 160)}\n`;
+  }
+  if (event.type === 'result') {
+    const stats = event.stats ?? {};
+    const calls = stats.tool_calls ? ` ${stats.tool_calls} tool call${stats.tool_calls === 1 ? '' : 's'}` : '';
+    const seconds = stats.duration_ms ? ` ${Math.round(stats.duration_ms / 1000)}s` : '';
+    if (event.status && event.status !== 'success') {
+      const why = event.error?.message ? `: ${condense(String(event.error.message), 160)}` : '';
+      return `  ✗ ${String(event.status).toLowerCase()}${why}${calls}${seconds}\n`;
+    }
+    return `  ✓ done${calls}${seconds}\n`;
+  }
+  return '';
+}
+
 /**
  * Line-buffer a JSONL stream and render each complete event.
  *
@@ -175,7 +254,9 @@ export function createJsonlRenderer(renderEvent) {
   let usage = null;
   const recordUsage = (event) => {
     if (!event || typeof event !== 'object') return;
-    const source = event.usage ?? event.result?.usage ?? event;
+    // Gemini reports token counts under `stats` rather than `usage`; check it
+    // before falling back to the event itself so its totals are not lost.
+    const source = event.usage ?? event.result?.usage ?? event.stats ?? event.result?.stats ?? event;
     if (!source || typeof source !== 'object') return;
     const tokenValues = [
       source.tokens,
@@ -228,15 +309,17 @@ export function createJsonlRenderer(renderEvent) {
 }
 
 /** A renderer for engines whose stdout is already meant to be read. */
+/** @returns {import('./types.js').Renderer} */
 export function passthroughRenderer() {
   return { write: (text) => text, end: () => '' };
 }
 
+/** @type {Adapter} */
 const claudeAdapter = {
   name: 'claude',
   version: cliVersion('claude'),
   efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
-  command({ prompt, addDirs, permissions, artifactOnly = false, agent = {} }) {
+  command({ prompt, addDirs, permissions, artifactOnly = false, agent = /** @type {import('./types.js').Agent} */ ({}) }) {
     // `auto`, not `acceptEdits`, is used for worktree-writing and
     // artifact-only phases: under acceptEdits a non-interactive `-p` run
     // auto-denies every Bash call, because there is no one to answer the
@@ -257,11 +340,12 @@ const claudeAdapter = {
   createRenderer: () => createJsonlRenderer(renderClaudeEvent),
 };
 
+/** @type {Adapter} */
 const codexAdapter = {
   name: 'codex',
   version: cliVersion('codex'),
   efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
-  command({ prompt, cwd, addDirs, permissions, artifactOnly = false, agent = {} }) {
+  command({ prompt, cwd, addDirs, permissions, artifactOnly = false, agent = /** @type {import('./types.js').Agent} */ ({}) }) {
     const canWrite = permissionLevel(permissions) === PERMISSIONS.WRITE_WORKTREE || artifactOnly;
     const sandbox = canWrite ? 'workspace-write' : 'read-only';
     const args = ['exec', prompt, '--sandbox', sandbox, '--cd', cwd];
@@ -272,11 +356,12 @@ const codexAdapter = {
   },
 };
 
+/** @type {Adapter} */
 const agyAdapter = {
   name: 'agy',
   version: cliVersion('agy'),
   efforts: ['low', 'medium', 'high'],
-  command({ prompt, addDirs, timeoutMs, permissions, artifactOnly = false, agent = {} }) {
+  command({ prompt, addDirs, timeoutMs, permissions, artifactOnly = false, agent = /** @type {import('./types.js').Agent} */ ({}) }) {
     // `--dangerously-skip-permissions`, not bare `accept-edits`: in headless
     // `--print` mode agy cannot prompt for the `command` permission its Bash-
     // style tools need, so it auto-denies the first one and exits 0 having done
@@ -305,7 +390,44 @@ const agyAdapter = {
   createRenderer: () => createJsonlRenderer(renderAgyEvent),
 };
 
-const adapters = { claude: claudeAdapter, codex: codexAdapter, agy: agyAdapter };
+/** @type {Adapter} */
+const geminiAdapter = {
+  name: 'gemini',
+  version: cliVersion('gemini'),
+  // Gemini CLI exposes no reasoning-effort flag, so this adapter declares no
+  // `efforts`: a configured effort is simply not passed through (see docs).
+  command({ prompt, addDirs, permissions, artifactOnly = false, agent = /** @type {import('./types.js').Agent} */ ({}) }) {
+    // `yolo`, not `plan`/`auto_edit`: in headless `--prompt` mode Gemini cannot
+    // interactively approve the shell tools a worktree-writing phase needs to
+    // build, test, and commit. `plan` is read-only and `auto_edit` auto-approves
+    // only edit tools, so either one auto-denies the first shell call and the
+    // phase "completes" instantly with an empty log. `yolo` auto-approves every
+    // tool — Gemini's equivalent of the claude adapter's `--permission-mode
+    // auto` and agy's `--dangerously-skip-permissions`.
+    //
+    // `--skip-trust`: a fresh worktree is an untrusted folder, and Gemini
+    // refuses to run headlessly in one (it prints a trust warning and does
+    // nothing). This trusts the workspace for this one invocation only.
+    //
+    // stream-json, not the default `text`: text output withholds every byte
+    // until the process exits, so a multi-minute phase is indistinguishable from
+    // a hang. stream-json emits an event per step, which `createRenderer` turns
+    // back into readable lines — same reasoning as the claude adapter above.
+    const canWrite = permissionLevel(permissions) === PERMISSIONS.WRITE_WORKTREE || artifactOnly;
+    const args = [
+      '--prompt', prompt,
+      '--approval-mode', canWrite ? 'yolo' : 'plan',
+      '--skip-trust',
+      '--output-format', 'stream-json',
+    ];
+    if (agent.model) args.push('--model', agent.model);
+    for (const dir of addDirs) args.push('--include-directories', dir);
+    return { command: 'gemini', args };
+  },
+  createRenderer: () => createJsonlRenderer(renderGeminiEvent),
+};
+
+const adapters = { claude: claudeAdapter, codex: codexAdapter, agy: agyAdapter, gemini: geminiAdapter };
 
 function validateConfiguredAdapter(name, adapter) {
   if (!adapter || typeof adapter !== 'object' || Array.isArray(adapter) || typeof adapter.command !== 'function') {
@@ -323,6 +445,7 @@ function validateConfiguredAdapter(name, adapter) {
   return adapter;
 }
 
+/** @returns {Adapter} */
 export function adapterFor(engine, customAdapters = {}) {
   const configuredNames = customAdapters && typeof customAdapters === 'object' ? Object.keys(customAdapters) : [];
   const hasConfiguredAdapter = customAdapters && typeof customAdapters === 'object'
@@ -335,6 +458,7 @@ export function adapterFor(engine, customAdapters = {}) {
   return adapter;
 }
 
+/** @param {Engine} agent @returns {Engine} */
 export function validateAgent(agent, customAdapters = {}) {
   const adapter = adapterFor(agent.name, customAdapters);
   if (agent.effort && adapter.efforts && !adapter.efforts.includes(agent.effort)) {
@@ -344,11 +468,13 @@ export function validateAgent(agent, customAdapters = {}) {
 }
 
 /** Resolve an agent descriptor: per-phase override, else the default. */
+/** @param {Config} config @returns {Engine} */
 export function agentForPhase(config, phaseName) {
   return config.engines[phaseName] ?? config.engines.default;
 }
 
 /** Resolve which executable runs a phase. Retained for string-based callers. */
+/** @param {Config} config */
 export function engineForPhase(config, phaseName) {
   return agentForPhase(config, phaseName).name;
 }

package/src/backends/gitlab.mjs

@@ -83,7 +83,8 @@ function errorText(error) {
  * The default GitLab transport. `glab` is intentionally an external runtime
  * requirement, so consumers can replace this transport with REST or MCP code.
  */
-export function glabTransport({ cwd, runner = runCommand, env } = {}) {
+export function glabTransport(options = {}) {
+  const { cwd, runner = runCommand, env } = /** @type {any} */ (options);
   async function run(args) {
     try {
       return await runner('glab', args, { cwd, ...(env ? { env } : {}) });
@@ -153,9 +154,10 @@ export function glabTransport({ cwd, runner = runCommand, env } = {}) {
 /**
  * Adapt GitLab-native merge request data to aloop's verified pull-request port.
  *
- * @param {{ cwd: string, git?: GitFacade, transport?: GitLabTransport, env?: object }} options
+ * @param {any} options
  */
-export function gitlabBackend({ cwd, git = new GitFacade(cwd), transport, env } = {}) {
+export function gitlabBackend(options = {}) {
+  let { cwd, git = new GitFacade(cwd), transport, env } = options;
   transport ??= glabTransport({ cwd, env });
   const repositories = new Map();
 

package/src/command.mjs

@@ -2,11 +2,8 @@ import { spawn } from 'node:child_process';
 import { existsSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
 import { win32 as windowsPath } from 'node:path';
 
-export function signalProcessGroup(pid, signal, {
-  platform = process.platform,
-  spawnImpl = spawn,
-  onFailure,
-} = {}) {
+export function signalProcessGroup(pid, signal, options = {}) {
+  const { platform = process.platform, spawnImpl = spawn, onFailure } = /** @type {any} */ (options);
   if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return false;
   if (platform === 'win32') {
     const handleFailure = onFailure ?? (() => {
@@ -63,10 +60,8 @@ function environmentValue(env, name) {
   return key ? env[key] : undefined;
 }
 
-export function resolveWindowsExecutable(command, env = process.env, {
-  fileExists = existsSync,
-  realPath = realpathSync.native,
-} = {}) {
+export function resolveWindowsExecutable(command, env = process.env, options = {}) {
+  const { fileExists = existsSync, realPath = realpathSync.native } = /** @type {any} */ (options);
   const pathEntries = (environmentValue(env, 'PATH') ?? '').split(';').filter(Boolean);
   const pathExtensions = (environmentValue(env, 'PATHEXT') ?? WINDOWS_EXECUTABLE_EXTENSIONS.join(';'))
     .split(';')
@@ -144,7 +139,7 @@ export async function runCommand(command, args = [], options = {}) {
     platform = process.platform,
     spawnImpl = spawn,
     resolveExecutable = resolveWindowsExecutable,
-  } = options;
+  } = /** @type {any} */ (options);
   return new Promise((resolve, reject) => {
     const spawnSpec = platform === 'win32' ? windowsSpawnSpec(command, args, env, resolveExecutable) : { command, args };
     const child = spawnImpl(spawnSpec.command, spawnSpec.args, {