@onlooker-community/ecosystem 0.10.0 → 0.15.0

package/plugins/tribunal/skills/tribunal/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: tribunal
+description: Run a task under multi-agent quality gates. Spawns the tribunal-actor subagent, a jury of typed Judges, and a Meta-Judge; aggregates verdicts under a configurable gate policy; retries the Actor with critique on rejection until acceptance or max_iterations. Use when the user explicitly wraps a task with /tribunal, or wants stronger correctness/safety review than a single pass. Emits the full tribunal.* canonical event stream.
+---
+
+# Tribunal: Multi-Agent Execution with Quality Gates
+
+You are orchestrating a **Tribunal** evaluation loop. A user task gets wrapped in: **Actor → Jury → Meta-Judge → Gate**, retrying the Actor with feedback until the gate passes or `max_iterations` is reached.
+
+## Setup
+
+Before the loop, source the plugin's bash helpers and load config. Run this once at the start:
+
+```bash
+set -uo pipefail
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-config.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-rubric.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-jury.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-aggregate.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-gate.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-events.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-verdict.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-project-key.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tribunal-ulid.sh"
+
+tribunal_config_load "$(pwd)"
+tribunal_rubric_load "$(pwd)"
+```
+
+Parse the task description from the user's prompt arguments. If the user passed `--rubric=<id>`, use that; otherwise use `tribunal_rubric_default_id`.
+
+Resolve the active rubric with `tribunal_rubric_get "$rubric_id"`. Validate it with `tribunal_rubric_validate "$rubric"`. If validation fails, abort with `tribunal.session.complete` outcome `aborted` and tell the user why.
+
+## Per-task initialization
+
+Generate identifiers and persist task-level state:
+
+```bash
+task_id=$(tribunal_ulid)
+project_key=$(tribunal_project_key "$(pwd)")
+remote=$(tribunal_project_remote_url "$(pwd)")
+repo_root=$(tribunal_project_repo_root "$(pwd)")
+tribunal_write_project_manifest "$project_key" "$remote" "$repo_root"
+tribunal_write_task_manifest "$project_key" "$task_id" "$task_summary" "$rubric_id" "$rubric"
+```
+
+Emit `tribunal.session.start` with the resolved config (`judge_types`, `gate_policy`, `score_threshold`, `max_iterations`, model IDs).
+
+## The loop
+
+For `iteration_number` from `0` while `iteration_number < max_iterations`:
+
+1. **Iteration start.** Generate `iteration_id=$(tribunal_ulid)`. `trigger` is `"initial"` for n=0, `"gate_blocked"` for retries. Emit `tribunal.iteration.start`.
+
+2. **Actor.** Emit `tribunal.actor.start`. Use the Task tool to spawn `tribunal-actor` with:
+   - The task description.
+   - The rubric criteria (just `name` + `weight` + `min_pass`).
+   - On retries: a digest of the prior iteration's consensus, dissent (if any), and Meta-Judge override.
+
+   Capture the Actor's final output. Persist it: `tribunal_write_actor_output "$project_key" "$task_id" "$iteration_id" "$actor_output"`. Emit `tribunal.actor.complete` with `success: true` and the inferred `artifact_kind` (`file` / `patch` / `message` / `command`).
+
+3. **Empanel the jury.** Resolve the panel from configured types:
+   ```bash
+   types=$(tribunal_config_get_json '.tribunal.session.judge_types')
+   # Rubric may override:
+   rubric_types=$(printf '%s' "$rubric" | jq -c '.judge_types // empty')
+   [[ -n "$rubric_types" && "$rubric_types" != "null" ]] && types="$rubric_types"
+   jury=$(tribunal_jury_empanel "$types")
+   ```
+   Persist the jury (`tribunal_write_iteration_artifact ... jury ...`) and emit `tribunal.jury.empaneled` with the schema-shaped `judges[]` (`tribunal_jury_to_schema_judges "$jury"`).
+
+4. **Run each Judge.** For each entry in the jury panel:
+   - Emit `tribunal.judge.start` with `judge_id`, `judge_type`, `judge_model_id`.
+   - Spawn the judge subagent (`.subagent` field) with the Actor output + rubric.
+   - Parse the JSON object the judge returns. Augment it with `task_id`, `iteration_id`, `judge_id`, `judge_model_id` from the panel entry, and `judge_type` from the panel entry (canonical, overriding what the agent self-reported).
+   - Emit `tribunal.verdict` with that payload.
+   - Persist with `tribunal_write_judge_verdict`.
+
+   Collect the verdicts into a JSON array `verdicts`.
+
+5. **Aggregate + dissent.**
+   ```bash
+   method=$(printf '%s' "$rubric" | jq -r '.aggregation_method // "weighted_mean"')
+   threshold=$(printf '%s' "$rubric" | jq -r '.score_threshold // 0.75')
+   dissent_threshold=$(tribunal_config_get '.tribunal.session.dissent_threshold')
+   [[ -z "$dissent_threshold" ]] && dissent_threshold="0.25"
+
+   aggregated=$(tribunal_aggregate "$method" "$verdicts" "$rubric")
+   dissent=$(tribunal_disagreement "$verdicts")
+   ```
+   Build and emit `tribunal.consensus.reached`. If `dissent > dissent_threshold`, emit `tribunal.dissent.recorded` (set `resolution` to `null` for now — the Meta-Judge may set it on the next step via `override_recommendation`).
+
+6. **Meta-Judge.** Emit `tribunal.meta.start`. Spawn `tribunal-meta-judge` with the verdicts and the Actor output. Parse its JSON; augment with `task_id`, `iteration_id`, `meta_model_id`. Emit `tribunal.meta.complete`. Persist.
+
+7. **Gate.**
+   ```bash
+   policy=$(printf '%s' "$rubric" | jq -r '.gate_policy // "majority"')
+   gate=$(tribunal_gate_decide "$policy" "$verdicts" "$aggregated" "$threshold" "$meta" "$dissent" "$dissent_threshold")
+   ```
+   If `gate.passed == true`, emit `tribunal.gate.passed` with `final_score: aggregated` and break the loop with outcome `accepted`. Otherwise emit `tribunal.gate.blocked` with the `reason`, `will_retry: (iteration_number + 1 < max_iterations)`, and `retry_iteration_number` if retrying. Persist `gate.json` either way.
+
+   If blocking and retrying, build the retry digest (lowest-scoring criteria + meta override + dissent summary) and feed it into the next iteration's Actor prompt.
+
+## Termination
+
+When the loop exits:
+
+- `accepted` — gate passed.
+- `exhausted_iterations` — loop ran `max_iterations` without acceptance.
+- `aborted` — orchestrator caught an unrecoverable error (rubric validation failed, Actor subagent crashed twice, etc.). Set this explicitly when you catch errors; do not silently swallow.
+
+Emit `tribunal.session.complete` with `outcome`, `final_score`, `iterations_used`, `total_duration_ms`. Skip `total_cost_usd` in v0.1 — the runtime does not surface subagent costs to the orchestrator yet.
+
+## Summary to the user
+
+After emitting `session.complete`, render a compact markdown summary to the user:
+
+- Verdict (✓ accepted / ✗ rejected / ⏱ exhausted / ⚠ aborted) with final score.
+- Per-iteration table: iteration | per-judge scores | dissent | gate result.
+- Meta-Judge bias notes if any.
+- Path to the persisted artifacts (`~/.onlooker/tribunal/<key>/<task_id>/`).
+
+Keep the summary terse. The artifacts on disk are the long form.
+
+## Error handling
+
+- If a judge subagent fails to return parseable JSON, treat that judge as `score: 0, passed: false, confidence: 0` and surface the parse error in `feedback_summary`. Do not abort the iteration — let the gate decide.
+- If the Meta-Judge fails, default to `verdict_quality: "questionable", bias_detected: false` so the gate falls back to score-based logic.
+- If event emission fails (schema validation), keep going and write a warning to stderr. The persisted artifacts on disk are still trustworthy.

package/release-please-config.json

@@ -10,18 +10,72 @@
       "extra-files": [
         {
           "type": "json",
-          "path": "package.json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    "plugins/archivist": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "archivist",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    "plugins/tribunal": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "tribunal",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
           "jsonpath": "$.version"
-        },
+        }
+      ]
+    },
+    "plugins/echo": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "echo",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
         {
           "type": "json",
           "path": ".claude-plugin/plugin.json",
           "jsonpath": "$.version"
-        },
+        }
+      ]
+    },
+    "plugins/cartographer": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-bump-minor-pre-major": false,
+      "component": "cartographer",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
         {
           "type": "json",
-          "path": ".claude-plugin/marketplace.json",
-          "jsonpath": "$.plugins[0].version"
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
         }
       ]
     }

package/scripts/coverage/bash-coverage.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// Bash "tested-functions ratio" heuristic.
+//
+// True bash line coverage (bashcov / kcov) is heavy and flaky in CI, so
+// instead we ask the cheaper question: "for every public function defined
+// in scripts/lib/, does at least one bats test reference it by name?". The
+// result is a per-file ratio plus a flat list of untested public functions.
+//
+// What counts as a "public" function:
+//   * defined with either `name() { ... }` or `function name { ... }`
+//   * name does NOT start with an underscore (those are private helpers and
+//     should be tested indirectly through their callers).
+//
+// What counts as a "reference" in tests:
+//   * the function name appears as a standalone word in any *.bats file
+//     (typical patterns: `run my_func ...`, `my_func "$arg"`, or sourced
+//     and called directly). False positives are possible — that's the cost
+//     of a heuristic — but the score is still useful as a regression gate
+//     and is calibrated against the noise floor.
+//
+// Flags:
+//   --json     emit structured JSON on stdout (default: human-readable)
+//   --root <p> override repo root
+//
+// Exit codes: always 0; this is an informational tool. Use --json to feed
+// into format-comment.mjs.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function findRepoRoot(start) {
+  let cur = resolve(start);
+  while (cur !== '/') {
+    try {
+      statSync(join(cur, '.claude-plugin', 'marketplace.json'));
+      return cur;
+    } catch {}
+    cur = dirname(cur);
+  }
+  throw new Error(`no repo root above ${start}`);
+}
+
+function parseArgs(argv) {
+  const out = { json: false, root: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--json') out.json = true;
+    else if (argv[i] === '--root') out.root = argv[++i];
+  }
+  return out;
+}
+
+function walk(dir, predicate) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    let items;
+    try {
+      items = readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const item of items) {
+      const p = join(cur, item.name);
+      if (item.isDirectory()) {
+        if (item.name === 'node_modules' || item.name === '.git') continue;
+        stack.push(p);
+      } else if (item.isFile() && predicate(p)) {
+        out.push(p);
+      }
+    }
+  }
+  return out.sort();
+}
+
+// Extract `name` from lines like `name() {`, `name () {`, or `function name`.
+// Skips lines indented (those are nested fns / non-top-level callbacks we
+// don't want to attribute to the file's public surface).
+function extractFunctions(content) {
+  const out = [];
+  const lines = content.split(/\r?\n/);
+  const def = /^(?:function\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*\(\s*\)\s*\{?/;
+  for (const line of lines) {
+    // Strict: must start at column 0 (no leading whitespace).
+    if (line.length === 0 || line[0] === ' ' || line[0] === '\t') continue;
+    const m = line.match(def);
+    if (!m) continue;
+    const name = m[1];
+    // Skip private helpers and bash keywords that look like fn names.
+    if (name.startsWith('_')) continue;
+    if (['if', 'while', 'for', 'case', 'then', 'do', 'else', 'fi', 'done'].includes(name)) continue;
+    out.push(name);
+  }
+  return [...new Set(out)];
+}
+
+function isReferenced(name, testsContent) {
+  // Look for the name as a standalone word (preceded/followed by non-word
+  // characters). This catches `run name`, `name "$x"`, `$( name )`, etc.
+  const rx = new RegExp(`(^|[^A-Za-z0-9_])${name}([^A-Za-z0-9_]|$)`);
+  return rx.test(testsContent);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const here = dirname(fileURLToPath(import.meta.url));
+  const root = args.root ? resolve(args.root) : findRepoRoot(here);
+
+  const libDirs = [join(root, 'scripts', 'lib'), join(root, 'plugins', 'archivist', 'scripts', 'lib')];
+  const libFiles = [];
+  for (const d of libDirs) {
+    try {
+      libFiles.push(...walk(d, (p) => p.endsWith('.sh')));
+    } catch {}
+  }
+
+  const testsDir = join(root, 'test', 'bats');
+  const testFiles = walk(testsDir, (p) => p.endsWith('.bats'));
+  const testsContent = testFiles.map((f) => readFileSync(f, 'utf8')).join('\n');
+
+  const perFile = [];
+  let totalFns = 0;
+  let totalTested = 0;
+  const untested = [];
+
+  for (const file of libFiles) {
+    const fns = extractFunctions(readFileSync(file, 'utf8'));
+    const tested = fns.filter((name) => isReferenced(name, testsContent));
+    const fileTotal = fns.length;
+    const fileTested = tested.length;
+    totalFns += fileTotal;
+    totalTested += fileTested;
+    const relpath = relative(root, file);
+    perFile.push({
+      file: relpath,
+      total: fileTotal,
+      tested: fileTested,
+      ratio: fileTotal === 0 ? 1 : fileTested / fileTotal,
+      untested: fns.filter((n) => !tested.includes(n)),
+    });
+    for (const u of fns.filter((n) => !tested.includes(n))) {
+      untested.push({ file: relpath, name: u });
+    }
+  }
+
+  const overallRatio = totalFns === 0 ? 1 : totalTested / totalFns;
+  const report = {
+    overall: { total: totalFns, tested: totalTested, ratio: overallRatio },
+    files: perFile,
+    untested,
+  };
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`bash function coverage: ${totalTested}/${totalFns} (${(overallRatio * 100).toFixed(1)}%)\n\n`);
+  for (const f of perFile) {
+    const pct = (f.ratio * 100).toFixed(0).padStart(3);
+    process.stdout.write(`  ${pct}%  ${f.tested}/${f.total}  ${f.file}\n`);
+    for (const u of f.untested) {
+      process.stdout.write(`         - ${u}\n`);
+    }
+  }
+}
+
+main();

package/scripts/coverage/format-comment.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Combine node coverage + bash function coverage into a single markdown
+// comment suitable for posting on a pull request via `gh pr comment`.
+//
+// Reads each report from a file path (so the caller can capture stdout
+// once and pass the file through). Emits markdown on stdout.
+//
+// Usage:
+//   format-comment.mjs --node coverage-node.json --bash coverage-bash.json
+//
+// Each file should be JSON produced by the matching script's --json mode.
+
+import { readFileSync } from 'node:fs';
+
+function parseArgs(argv) {
+  const out = { node: null, bash: null, sha: process.env.GITHUB_SHA ?? null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--node') out.node = argv[++i];
+    else if (argv[i] === '--bash') out.bash = argv[++i];
+    else if (argv[i] === '--sha') out.sha = argv[++i];
+  }
+  return out;
+}
+
+function pct(n) {
+  if (typeof n !== 'number' || Number.isNaN(n)) return '—';
+  return `${n.toFixed(1)}%`;
+}
+
+function badge(value, kind) {
+  if (typeof value !== 'number') return '⚪';
+  if (kind === 'bash') {
+    if (value >= 70) return '🟢';
+    if (value >= 50) return '🟡';
+    return '🔴';
+  }
+  if (value >= 80) return '🟢';
+  if (value >= 60) return '🟡';
+  return '🔴';
+}
+
+function nodeSection(report) {
+  if (!report?.overall) {
+    return '_No node coverage report._';
+  }
+  const o = report.overall;
+  const lines = [
+    `**Overall:** ${badge(o.line, 'node')} ${pct(o.line)} lines · ${pct(o.branch)} branches · ${pct(o.funcs)} functions`,
+    '',
+    '| file | line | branch | funcs |',
+    '| --- | ---: | ---: | ---: |',
+  ];
+  for (const f of report.files) {
+    lines.push(`| \`${f.file}\` | ${pct(f.line)} | ${pct(f.branch)} | ${pct(f.funcs)} |`);
+  }
+  return lines.join('\n');
+}
+
+function bashSection(report) {
+  if (!report?.overall) {
+    return '_No bash function coverage report._';
+  }
+  const o = report.overall;
+  const overallPct = o.ratio * 100;
+  const lines = [
+    `**Overall:** ${badge(overallPct, 'bash')} ${o.tested}/${o.total} public functions exercised by bats (${pct(overallPct)})`,
+    '',
+    '| file | tested / total | ratio |',
+    '| --- | ---: | ---: |',
+  ];
+  for (const f of report.files) {
+    if (f.total === 0) continue;
+    lines.push(`| \`${f.file}\` | ${f.tested} / ${f.total} | ${pct(f.ratio * 100)} |`);
+  }
+  if (report.untested.length > 0) {
+    lines.push('');
+    lines.push('<details><summary>Untested public functions</summary>');
+    lines.push('');
+    for (const u of report.untested) {
+      lines.push(`- \`${u.file}\` — \`${u.name}\``);
+    }
+    lines.push('');
+    lines.push('</details>');
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  let nodeReport = null;
+  let bashReport = null;
+  if (args.node) nodeReport = JSON.parse(readFileSync(args.node, 'utf8'));
+  if (args.bash) bashReport = JSON.parse(readFileSync(args.bash, 'utf8'));
+
+  const out = [];
+  out.push('<!-- onlooker-coverage-comment -->');
+  out.push('## Coverage');
+  out.push('');
+  if (args.sha) {
+    out.push(`Commit: \`${args.sha.slice(0, 12)}\``);
+    out.push('');
+  }
+  out.push('### Node (.mjs)');
+  out.push('');
+  out.push(nodeSection(nodeReport));
+  out.push('');
+  out.push('### Bash (function-reference heuristic)');
+  out.push('');
+  out.push(bashSection(bashReport));
+  out.push('');
+  out.push('---');
+  out.push('');
+  out.push(
+    'Bash numbers are a heuristic — they count public functions referenced by bats tests, not real line coverage. A red score points to public helpers nobody directly exercises.',
+  );
+
+  process.stdout.write(`${out.join('\n')}\n`);
+}
+
+main();

package/scripts/coverage/run-coverage.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Run the .mjs test suite with node's built-in --experimental-test-coverage,
+// parse the emitted table into structured JSON, and either pretty-print it
+// or hand it off as JSON for downstream tools (format-comment.mjs).
+//
+// The output table is fixed-format text; we parse it line-by-line rather
+// than depending on V8 coverage dumps so we don't need to handle binary
+// formats across node versions.
+//
+// Flags:
+//   --json   emit structured JSON
+//   --root   override repo root
+
+import { spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function findRepoRoot(start) {
+  let cur = resolve(start);
+  while (cur !== '/') {
+    try {
+      statSync(join(cur, '.claude-plugin', 'marketplace.json'));
+      return cur;
+    } catch {}
+    cur = dirname(cur);
+  }
+  throw new Error(`no repo root above ${start}`);
+}
+
+function parseArgs(argv) {
+  const out = { json: false, root: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--json') out.json = true;
+    else if (argv[i] === '--root') out.root = argv[++i];
+  }
+  return out;
+}
+
+// Parse the human-readable coverage report node prints after a --test run.
+// Layout:
+//   ℹ start of coverage report
+//   ℹ ---------- (separator)
+//   ℹ file | line % | branch % | funcs % | uncovered lines
+//   ℹ ---------- (separator)
+//   ℹ <directory>
+//   ℹ  <subdir>
+//   ℹ   <file.mjs>  | 74.20 | 58.27 | 85.00 | 130-131 170 ...
+//   ℹ ---------- (separator)
+//   ℹ all files     | 78.55 | 57.38 | 87.18 |
+//   ℹ ---------- (separator)
+//   ℹ end of coverage report
+function parseCoverageOutput(text) {
+  const lines = text.split(/\r?\n/);
+  const files = [];
+  let overall = null;
+  let inReport = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/^ℹ\s?/, '').replace(/^[\sℹ]+/, '');
+    if (line.startsWith('start of coverage report')) {
+      inReport = true;
+      continue;
+    }
+    if (line.startsWith('end of coverage report')) {
+      inReport = false;
+      continue;
+    }
+    if (!inReport) continue;
+
+    // Skip separators and the header row.
+    if (line.startsWith('-')) continue;
+    if (line.includes('line %') && line.includes('branch %')) continue;
+
+    const cells = line.split('|').map((c) => c.trim());
+    // A real data row has 5 columns: file, line%, branch%, funcs%, uncovered.
+    if (cells.length < 5) continue;
+
+    const [file, linePct, branchPct, funcsPct, uncovered] = cells;
+    if (!file) continue;
+    // Directory rows have all-blank metric columns — skip them so we only
+    // surface per-file numbers + the all-files total.
+    if (!linePct || !branchPct || !funcsPct) continue;
+
+    const num = (s) => Number.parseFloat(s);
+    const entry = {
+      file,
+      line: num(linePct),
+      branch: num(branchPct),
+      funcs: num(funcsPct),
+      uncoveredLines: uncovered || '',
+    };
+    if (file === 'all files') {
+      overall = entry;
+    } else {
+      files.push(entry);
+    }
+  }
+
+  return { files, overall };
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const here = dirname(fileURLToPath(import.meta.url));
+  const root = args.root ? resolve(args.root) : findRepoRoot(here);
+
+  const testGlob = ['test/node'].map((d) => join(root, d, '*.test.mjs'));
+  const r = spawnSync(
+    'node',
+    [
+      '--experimental-test-coverage',
+      '--test-coverage-include=scripts/**/*.mjs',
+      '--test-coverage-exclude=test/**',
+      '--test',
+      ...testGlob,
+    ],
+    { encoding: 'utf8', cwd: root },
+  );
+
+  if (r.status !== 0) {
+    process.stderr.write(`tests failed (exit ${r.status})\n`);
+    process.stderr.write(r.stdout);
+    process.stderr.write(r.stderr);
+    process.exit(r.status ?? 1);
+  }
+
+  const report = parseCoverageOutput(r.stdout);
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (!report.overall) {
+    process.stderr.write('could not parse coverage output\n');
+    process.stderr.write(r.stdout);
+    process.exit(1);
+  }
+
+  process.stdout.write(
+    `node coverage: line ${report.overall.line.toFixed(1)}%  branch ${report.overall.branch.toFixed(1)}%  funcs ${report.overall.funcs.toFixed(1)}%\n\n`,
+  );
+  for (const f of report.files) {
+    process.stdout.write(
+      `  line ${f.line.toFixed(0).padStart(3)}%  branch ${f.branch.toFixed(0).padStart(3)}%  ${f.file}\n`,
+    );
+  }
+}
+
+main();

package/scripts/hooks/agent-spawn-tracker.sh

@@ -64,9 +64,9 @@ BACKGROUND=$(jq -r '.tool_input.background // false' <<<"$INPUT")
 STATE_FILE="$ONLOOKER_DIR/agent-spawn-trackers.json"
 LOCKFILE="$STATE_FILE.lock"
 
-# Use flock for exclusive access
-exec 200>"$LOCKFILE"
-flock -w 5 200 || {
+# Acquire exclusive access via the portable lock helper (mkdir-based mutex,
+# works on macOS without util-linux).
+lock_acquire "$LOCKFILE" 5 || {
 	json_response "deny" "Failed to acquire lock"
 	hook_failure
 	exit 0
@@ -103,7 +103,7 @@ STATE=$(jq --arg sid "$SESSION_ID" '
 echo "$STATE" > "$STATE_FILE" 2>/dev/null || true
 
 # Release lock
-flock -u 200
+lock_release "$LOCKFILE"
 
 # Get current session stats
 SPAWN_COUNT=$(jq -r --arg sid "$SESSION_ID" '.sessions[$sid].spawns' <<<"$STATE")