@olegkoval/agent-skills 1.58.1 → 1.59.0

package/adapters/claude/olko-github-pr/skills/lekker-review/SKILL.md

@@ -141,6 +141,12 @@ returns the number checked as `hardRuleCount`.
 Resolve every `references/...` and script path relative to `SKILL_ROOT`; never
 assume a `~/.claude/skills/` installation path.
 
+Run one simple command per shell call. Do not prefix commands with
+`cd <dir> &&`; use absolute paths, `git -C <dir>`, and `grep -rn <pattern> <dir>`
+instead. Permission checkers cannot vet a compound or `cd`-prefixed command,
+so in an unattended or auto-approved run each one becomes a denial and a
+wasted turn.
+
 ## Host selection
 
 Set `HOST=codex` when native Codex collaboration tools such as `spawn_agent`
@@ -159,6 +165,39 @@ single-agent review is not equivalent to lekker-review.
 
 ## Step 0 - Parse input
 
+### Dependencies (first thing, every run)
+
+```bash
+node ${SKILL_ROOT}/scripts/deps.mjs check   # add --unattended when no human is present
+```
+
+Milliseconds: it only checks presence. The upstream version check needs the
+network, so it runs at most once per `cadenceDays` (default 7) and the ledger
+`~/.local/state/lekker-review/deps.json` records when it last ran. Act on `state`:
+
+- `first-run`: ask ONCE (AskUserQuestion in Claude Code): a multiSelect of the
+  `offer[]` tools (label = tool, description = `usedBy`), plus "keep them
+  updated automatically?" yes/no. Then
+  `deps.mjs init --install <picked> --skip <the rest> --auto-update on|off`.
+  A tool not picked is recorded as skipped and never offered again; the user can
+  still run `deps.mjs install <tool>` later. Unattended: do not ask, do not
+  install; carry on and say `deps not initialised` in the header.
+- `missing-required`: stop and print the `missing` list. The review needs them.
+- `undecided` non-empty (a tool added to the registry since init): ask about
+  those tools only, then `deps.mjs install <tool>` or `deps.mjs skip <tool>`.
+- `outdated` non-empty and `updated` null: one line, e.g.
+  `deps outdated: revmux 0.2.6 -> 0.2.7 (deps.mjs update)`. With auto-update on,
+  `check` already upgraded them when the check was due; report `updated`.
+- `revmuxPromptsInSync: false`: run
+  `bash ${SKILL_ROOT}/scripts/install-revmux-prompts.sh`, which resyncs the
+  lekker profiles into `~/.config/revmux` (`deps.mjs update revmux` does the
+  same after upgrading).
+- An install that returns `manual` (no Homebrew on PATH) prints the command to
+  run by hand; pass it on, do not improvise another installer.
+
+`ENGINE=revmux` additionally needs revmux `present`; when it is missing or
+skipped, fall back to the host's native engine and say why in the header.
+
 ### Pick the mode first
 
 `MODE=branch` when ANY of these hold:
@@ -313,6 +352,25 @@ treat as a full review and leave PREV_SHA unset. Also grep the same file for
 - Step 3.5 reuses that exact URL or local path so the artifact stays a living
 page for this PR.
 
+**Open the run log** once mode, depth and engine are settled (see
+`references/traces.md` for where every trace of a run lives):
+
+Resolve the run-log script path in every shell call. The examples below use
+Claude Code's `CLAUDE_PLUGIN_ROOT`. In Codex, replace the quoted script path in
+each invocation with the absolute path to `scripts/run-log.mjs` beside the
+selected `SKILL.md`. Do not rely on a shell variable set by an earlier call.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/run-log.mjs" start --repo <REPO_SLUG> --target <TARGET_SLUG> --mode <MODE> \
+  --depth <depth> --engine <ENGINE> [--fix]
+```
+
+Keep the returned `runId` as `RUN_ID`. Then run
+`node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/run-log.mjs" mark <RUN_ID> <phase>`
+at each step boundary: `context` (Step 1), `review` (Step 2), `synthesis`
+(Step 3), `fix` (Step 4), `post` (Step 5). A marker is one line of JSON; never
+skip the review because the log failed, just say `run log unavailable`.
+
 ---
 
 ## Depth gate
@@ -389,7 +447,14 @@ On completion, read `worktree.json`. Keys emitted:
 `worktreePath`, `repoRoot`, `headSha`, `headShaShort`, `tscTail`,
 `tscChangedTail`, `tscErrorCount`, `eslintTail`, `eslintScope`, `eslintJson`,
 `changedFiles`, `baseRef`, `mergeBase`, `projectRules`, `deltaFile`, `notes`,
-`depsInstall`.
+`depsInstall`, `testRunner`.
+
+`testRunner` is `{runner, dirs, reason}` from `scripts/test-runner.mjs`:
+`runner` is `vitest|jest|mocha|node-test` only when its binary is installed
+in the worktree, `dirs` lists `{dir, runner}` pairs for each usable package
+(including binaries installed in a parent dir within the worktree), and `reason`
+says why `runner` is null. Pass it to the workflow unchanged; Prove skips
+without one instead of paying provers to find the missing `node_modules`.
 
 `notes` containing `changed-files-mismatch:<got>-vs-<expected>` means the
 merge-base still disagrees with the PR. Use the `files` list from `gh pr view`
@@ -602,7 +667,10 @@ First copy the script into the scratchpad. The Workflow tool rejects a
 `scriptPath` outside the working directory or added dirs ("scriptPath must be a
 script path this tool returned, or a file you can already read"), and the skill
 dir is usually neither: `cp ${SKILL_ROOT}/workflow.js <scratchpad>/workflow.js`.
-If it still rejects the path, pass the script inline via `script` instead.
+If `workflow.js` is already in the working directory (an unattended runner may
+stage it there), use that copy and skip the `cp`: some permission checks deny
+reading files out of the skill dir. If the Workflow tool still rejects the
+path, pass the script inline via `script` instead.
 
 Invoke the Workflow tool:
 
@@ -618,7 +686,8 @@ args: {
   contextFile: "<scratchpad>/context.json",
   worktreePath: <null for scan, else from worktree.json>,
   promptDir:   "${SKILL_ROOT}/references/agents",
-  prevSha:     <null unless re-review>
+  prevSha:     <null unless re-review>,
+  testRunner:  <worktree.json testRunner, null for scan>
 }
 ```
 
@@ -663,14 +732,16 @@ The workflow runs three phases:
   thirty-finding PR launches thirty concurrent agents.
 - **Critic (deep only):** completeness critic gets the full deduped finding
   list + DIFF_FILE; its findings go through verifier agents before promotion.
-- **Prove (medium/deep, worktree required):** each non-hard-rule Critical gets
-  one prover agent (`references/agents/prover.md`, sonnet, max 5, run
+- **Prove (medium/deep, worktree and an installed test runner required):**
+  each Critical without a `rule` tag gets one prover agent (`references/agents/prover.md`, sonnet, max 5, run
   `maxConcurrent` at a time) that writes a test asserting the CORRECT behaviour,
   runs it in the worktree, and captures it failing because of the bug. The proof rides on the finding as
   `proof: {attempted, proven, outcome, reason, testCode?, testCommand?, redOutput?}`.
   A proof that comes back GREEN (code behaved correctly) is counter-evidence -
   the workflow automatically downgrades the finding from Critical to Important.
-  Hard-rule findings are never proved (policy violations have no failing test).
+  Rule-tagged findings are never proved (policy violations have no failing
+  test). With `testRunner.runner` null, no prover runs and each candidate
+  carries `proof: {attempted: false, reason: "no runnable test runner: ..."}`.
 
 Findings have schema:
 `{file, line, severity, title, description, badCode, fix, rule?, precedent?, agreedBy?, verificationStatus?, verifierReasoning?, proof?}`
@@ -732,7 +803,8 @@ round; Prove runs through the current host's native engine. Steps:
    adapter's `agents` array has `degraded: true`. State the fallback in the
    review header (`**Note:** revmux unavailable - fell back to workflow
    engine` or `...fell back to codex engine`) and re-run the native path from
-   the top of Step 2.
+   the top of Step 2. Quote the last lines of `<round dir>/revmux.stderr.log`
+   in that note: it is the only record of why the agents failed.
 
 **Trust boundary:** always pass `--config-dir ~/.config/revmux` explicitly.
 Without it revmux also reads the reviewed repo's checked-in `.revmux/`, which
@@ -972,6 +1044,24 @@ Write it against the sha that was actually reviewed. When fix mode later adds
 commits, write a marker for the NEW head sha too - a gate keys on the tip
 that is about to be pushed, and a marker for a superseded sha would be a lie.
 
+**Close the run log** right after the receipt, then print the review:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/run-log.mjs" attach <RUN_ID> <scratchpad>/findings.json <scratchpad>/worktree.json \
+  <scratchpad>/preflight.json <scratchpad>/context.json
+node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/run-log.mjs" finish <RUN_ID> --status ok --verdict lgtm|lgtm-with-changes|needs-work \
+  --review-file "$REVIEW_FILE" [--wf <wf_id of the lekker-review-core run>]
+```
+
+`--wf` is the `runId` the Claude Code Workflow tool returned (omit it on other
+hosts). `finish` copies duration, tokens, agent count, verifier drops and
+prove results out of the harness's own record, which Claude Code deletes with
+old sessions. When fix mode, the artifact or a post follows, call `finish`
+again at the very end using the resolved script path, with every `--wf` id of
+the run (review and fix) and
+`--artifact-url`: the newest row wins. A run that dies part-way still gets
+`node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/run-log.mjs" finish <RUN_ID> --status failed --note <why>`.
+
 Then print the full review as the response.
 
 **Closer goes last.** The run's FINAL message (this one, or the later summary
@@ -1038,8 +1128,9 @@ Read `references/fix-mode.md` and follow it. Shape of the run:
    its severity. Never auto-fix any other Observation or Idiomatic finding, or a
    title/process rule.
 3. Invoke the host's fix workflow. In Claude, copy `fix-workflow.js` to the
-   scratchpad first (same reason as the review workflow; inline `script` if the
-   path is still rejected), then run:
+   scratchpad first (same reason as the review workflow; skip the copy when it
+   is already in the working directory; inline `script` if the path is still
+   rejected), then run:
    ```
    scriptPath: <scratchpad>/fix-workflow.js
    args: { repoSlug, prNumber, targetLabel, worktreePath, diffFile, contextFile,
@@ -1233,6 +1324,11 @@ If `repoRoot` starts with `/tmp/lekker-clone-`, also remove that clone dir.
 Remove the delta file if `deltaFile` was set in worktree.json. Verify with
 `git -C <repoRoot> worktree list` that no `lekker-review` entries remain.
 
+**Measuring changes.** `node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/run-log.mjs" report --days 30`
+prints duration, tokens, findings, verifier drop rate and prove yield per
+engine and depth. Run it before and after a change to `workflow.js` or the
+prompts and quote both. `backfill` imports past runs (idempotent).
+
 ---
 
 ## Failure rules

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/prover.md

@@ -44,9 +44,10 @@ hold:
   network) and the repo has no test infra to fake it cheaply.
 - The buggy logic is not importable/reachable from a test without large
   scaffolding (deep framework wiring, a webhook server bootstrap).
-- No test runner exists: check `package.json` for `vitest` or `jest` (in
-  `devDependencies` AND a matching script) and confirm `node_modules` is
-  present. Missing either -> not attemptable.
+- The code under test lives outside every package dir the prompt's
+  `TEST_RUNNER` line lists. The workflow already checked those dirs for an
+  installed runner binary, so do not re-check; a finding in any other package
+  has nothing to run its test.
 
 Deciding "not testable" quickly is a GOOD outcome, not a failure of yours --
 say why in one sentence and stop. Do not burn effort scaffolding around a fake
@@ -56,7 +57,8 @@ IO layer just to force a test into existence.
 
 ## Step 2 -- Write the test
 
-One file at the worktree ROOT named `lekker-proof-<file-slug>-<line>.test.ts`,
+One file at the root of the listed package dir that contains the finding
+(`.` means the worktree root) named `lekker-proof-<file-slug>-<line>.test.ts`,
 where `<file-slug>` is the finding's file path with every `/` and `.` replaced
 by `-` (e.g. finding at `src/sync/orders.ts:142` -> 
 `lekker-proof-src-sync-orders-ts-142.test.ts`). The slug matters: another
@@ -77,10 +79,20 @@ repo's real test directories and trivially findable for cleanup.
 
 ## Step 3 -- Run it
 
-Exactly one run command, scoped to your file only:
+Exactly one run command from that package dir, scoped to your file only, for
+the runner paired with that package dir in the `TEST_RUNNER` mapping
+(use the most specific package dir containing the finding):
 
 - vitest: `npx vitest run lekker-proof-<file-slug>-<line>.test.ts --no-coverage --reporter=verbose`
 - jest: `npx jest lekker-proof-<file-slug>-<line>.test.ts --ci`
+- mocha: `npx mocha lekker-proof-<file-slug>-<line>.test.ts`
+- node-test: `node --test lekker-proof-<file-slug>-<line>.test.ts` (needs a
+  runtime that strips types; if it rejects TypeScript, that is an environment
+  failure, below)
+
+When the package dir is not `.`, prefix the command with
+`cd <package dir> && ` and keep that prefix in `testCommand`: fix mode
+re-runs the proof from the worktree root.
 
 Set the Bash tool's `timeout` parameter to 120000 for this call.
 
@@ -114,7 +126,7 @@ Delete your test file and verify the worktree is exactly as clean as you
 found it:
 
 ```bash
-rm lekker-proof-<file-slug>-<line>.test.ts
+rm <package dir>/lekker-proof-<file-slug>-<line>.test.ts
 git -C <WORKTREE_PATH> status --porcelain
 ```
 

package/adapters/claude/olko-github-pr/skills/lekker-review/references/fix-mode.md

@@ -189,7 +189,8 @@ For each proven finding in a committable group:
 
 1. **Re-materialize the test**: write `proof.testCode` back to its original
    filename (the same `lekker-proof-<file-slug>-<line>.test.ts` name it was captured
-   under) at the worktree root.
+   under) in the package dir `proof.testCommand` starts with `cd` into, or at
+   the worktree root when it has no `cd` prefix.
 2. **Run** exactly `proof.testCommand` (Bash `timeout` 120000).
 3. **Judge**:
    - **PASSES now** -> the fix demonstrably resolves the finding. Record

package/adapters/claude/olko-github-pr/skills/lekker-review/references/github-post.md

@@ -133,9 +133,14 @@ comments.
 ```bash
 gh api "repos/<REPO_SLUG>/pulls/<PR_NUMBER>/reviews" \
   --method POST \
-  --input /tmp/lekker-post-$$.json
+  --input /tmp/lekker-post-$$.json  # pending-ok
 ```
 
+The payload has no `event` field on purpose: the review lands as a PENDING
+draft for the user to submit. Keep the `# pending-ok` comment. Guard hooks
+that block event-less review POSTs (they would otherwise create an invisible
+draft by accident) let a command through when it carries that marker.
+
 ---
 
 ## Step 4 -- Handle 422 errors

package/adapters/claude/olko-github-pr/skills/lekker-review/references/traces.md

@@ -0,0 +1,39 @@
+# Where a run leaves traces
+
+One table, so nobody has to rediscover this. The run log is the index: it
+points at, and copies the numbers out of, everything else.
+
+| Trace | Path | Written by | Kept | What it answers |
+|---|---|---|---|---|
+| Run ledger | `~/.local/state/lekker-review/runs.jsonl` | `scripts/run-log.mjs finish`, `backfill` | forever (one line per run) | how long, how many tokens, findings, drops, proofs, verdict, per engine and depth |
+| Run archive | `~/.local/state/lekker-review/runs/<runId>/` | `run-log.mjs start/mark/attach/finish` | 90 days (`prune`) | `run.json` with timeline, plus the run's `findings.json`, `worktree.json`, `preflight.json`, `context.json` |
+| Dependency ledger | `~/.local/state/lekker-review/deps.json` | `scripts/deps.mjs` | forever | which optional tools were installed or skipped, versions, last upstream check |
+| Review report | `~/code-reviews/<date>-<target>-<repo>.md` | Step 3 | forever | the review as printed, including the `Review Cost` block |
+| revmux archive | `~/code-reviews/revmux-tasks/<task>/<NN-run>/` | revmux, plus `revmux.stderr.log` from `scripts/revmux-engine.sh` | forever, never edit | `events.jsonl` (agent start, degraded, retried), `agents/*.jsonl` (per-agent cost and usage), `revmux.stderr.log` (why a round degraded; rounds before 2026-10-20 have none) |
+| Harness workflow record | `~/.claude/projects/*/<session>/workflows/wf_*.json` | Claude Code Workflow tool | until Claude Code cleans the session | the source `finish` copies from: `durationMs`, `totalTokens`, `agentCount`, `result` |
+| Cache | `~/.cache/lekker-review/` | Steps 1, 3, 5 | disposable | `reviewed/<sha>` branch-mode markers, `bot-precision.jsonl`, `repo-map.tsv` |
+| Pattern memory | ICM (`icm recall`) | Step 5 housekeeping | ICM decay | recurring review and false-positive patterns per repo |
+
+`LEKKER_STATE_DIR` moves the state root (tests use it). `LEKKER_CLAUDE_PROJECTS`
+and `LEKKER_REVMUX_TASKS_DIR` point `run-log.mjs` at other harness and revmux
+roots.
+
+## Reading it
+
+```bash
+node ${SKILL_ROOT}/scripts/run-log.mjs report --days 30         # table
+node ${SKILL_ROOT}/scripts/run-log.mjs report --days 90 --json  # for scripts
+jq -c 'select(.verdict=="needs-work")' ~/.local/state/lekker-review/runs.jsonl   # ad hoc
+```
+
+`report` keeps the newest row per `runId`, so a run finished twice (review,
+then fix) counts once. Rows with `source: harness-backfill` or
+`revmux-backfill` were imported from history and have no timeline or verdict.
+
+## Known gaps
+
+- Backfilled harness rows cannot tell which review fell back from revmux to the
+  workflow engine; new runs record the engine at `start`.
+- revmux tokens include cache reads, workflow `totalTokens` does not break them
+  out. Compare cost in dollars or wall time, not raw tokens, across engines.
+- Verdict and severity counts exist only for runs logged with `finish`.

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/deps.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// First-run setup and dependency upkeep for lekker-review.
+//
+// Required tools are only checked, never installed: a review cannot run
+// without them, and installing git or node behind someone's back is not this
+// skill's call. Optional tools are offered once, on the first run, and the
+// answer is remembered. A tool the user skipped is never offered again until
+// `reset`.
+//
+// The upstream version check needs the network, so it runs on a cadence
+// (default 7 days) and not on every review. The ledger records when it last
+// ran and what it found.
+//
+// Usage:
+//   node deps.mjs check [--force] [--unattended]   fast presence check; full version check when due
+//   node deps.mjs init  [--install a,b] [--skip c] [--auto-update on|off] [--cadence-days N]
+//   node deps.mjs install <tool>
+//   node deps.mjs update  [tool]                   upgrade outdated opted-in tools, resync revmux prompts
+//   node deps.mjs skip    <tool>
+//   node deps.mjs reset                            forget every choice; the next check is a first run
+//
+// Ledger: ${LEKKER_STATE_DIR:-~/.local/state/lekker-review}/deps.json
+// Every command prints one JSON object on stdout. Exit 0 unless the command
+// itself failed; a missing required tool is reported as `state`, not an exit.
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
+const STATE_DIR = process.env.LEKKER_STATE_DIR || join(homedir(), '.local', 'state', 'lekker-review');
+const LEDGER = join(STATE_DIR, 'deps.json');
+const DAY_MS = 86400000;
+// A failed upstream lookup is retried, not recorded as "up to date". This keeps
+// a flaky network from re-running the lookup on every single review.
+const RETRY_AFTER_MS = 6 * 3600000;
+
+const REQUIRED = ['git', 'gh', 'node', 'npx', 'jq', 'python3'];
+
+// `usedBy` is shown in the first-run question, so the user knows what each
+// tool buys before agreeing to install it.
+const OPTIONAL = {
+  revmux: {
+    usedBy: '--engine revmux (alternative review engine)',
+    versionCmd: ['revmux', ['--version']],
+    repo: 'umputun/revmux',
+    brew: ['install', '--cask', 'umputun/apps/revmux'],
+    brewUpgrade: ['upgrade', '--cask', 'umputun/apps/revmux'],
+    postInstall: ['bash', [join(SKILL_DIR, 'scripts', 'install-revmux-prompts.sh')]],
+  },
+  icm: {
+    usedBy: 'pattern memory: Track B recall and Step 5 housekeeping',
+    versionCmd: ['icm', ['--version']],
+    repo: 'rtk-ai/icm',
+    brew: ['install', 'rtk-ai/tap/icm'],
+    brewUpgrade: ['upgrade', 'rtk-ai/tap/icm'],
+  },
+};
+
+const argv = process.argv.slice(2);
+const cmd = argv[0] || 'check';
+
+function flag(name, fallback = null) {
+  const i = argv.indexOf('--' + name);
+  return i === -1 ? fallback : argv[i + 1];
+}
+const has = (name) => argv.includes('--' + name);
+
+function run(bin, args, timeout = 15000) {
+  try {
+    return { ok: true, out: execFileSync(bin, args, { encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'] }).trim() };
+  } catch (err) {
+    return { ok: false, out: String(err.stderr || err.message).trim().split('\n').slice(-3).join(' ') };
+  }
+}
+
+const onPath = (bin) => run('/bin/sh', ['-c', `command -v ${bin}`]).ok;
+const semver = (text) => (String(text).match(/(\d+)\.(\d+)\.(\d+)/) || [])[0] || null;
+
+function newer(latest, installed) {
+  if (!latest || !installed) return false;
+  const a = latest.split('.').map(Number);
+  const b = installed.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return false;
+}
+
+// brew is looked up explicitly: the agent's shell PATH often lacks it, and MDM
+// has deleted the /opt/homebrew/bin/brew symlink on this fleet before.
+function findBrew() {
+  for (const p of ['/opt/homebrew/bin/brew', '/usr/local/bin/brew', '/home/linuxbrew/.linuxbrew/bin/brew']) {
+    if (existsSync(p)) return p;
+  }
+  return onPath('brew') ? 'brew' : null;
+}
+
+function loadLedger() {
+  if (!existsSync(LEDGER)) return null;
+  try {
+    return JSON.parse(readFileSync(LEDGER, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveLedger(ledger) {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const tmp = LEDGER + '.tmp';
+  writeFileSync(tmp, JSON.stringify(ledger, null, 2) + '\n');
+  renameSync(tmp, LEDGER);
+}
+
+function blankLedger() {
+  return { schema: 1, initialisedAt: null, cadenceDays: 7, autoUpdate: false, checkedAt: null, lastAttemptAt: null, tools: {} };
+}
+
+function installedVersion(name) {
+  const [bin, args] = OPTIONAL[name].versionCmd;
+  if (!onPath(bin)) return null;
+  const r = run(bin, args);
+  return r.ok ? semver(r.out) : null;
+}
+
+function latestVersion(name) {
+  const r = run('gh', ['release', 'view', '-R', OPTIONAL[name].repo, '--json', 'tagName', '-q', '.tagName']);
+  return r.ok ? semver(r.out) : null;
+}
+
+function requiredMissing() {
+  return REQUIRED.filter((bin) => !onPath(bin));
+}
+
+function presence(ledger) {
+  const out = {};
+  for (const [name, entry] of Object.entries(ledger.tools)) {
+    if (entry.choice !== 'installed' || !Object.hasOwn(OPTIONAL, name)) continue;
+    out[name] = onPath(OPTIONAL[name].versionCmd[0]) ? 'present' : 'missing';
+  }
+  return out;
+}
+
+// The network half of `check`. Updates the ledger in place.
+function fullCheck(ledger, now) {
+  ledger.lastAttemptAt = new Date(now).toISOString();
+  let allResolved = true;
+  for (const [name, entry] of Object.entries(ledger.tools)) {
+    if (entry.choice !== 'installed' || !Object.hasOwn(OPTIONAL, name)) continue;
+    entry.version = installedVersion(name);
+    const latest = latestVersion(name);
+    if (latest) entry.latest = latest;
+    else allResolved = false;
+    entry.outdated = newer(entry.latest, entry.version);
+  }
+  if (allResolved) ledger.checkedAt = ledger.lastAttemptAt;
+  if (existsSync(join(SKILL_DIR, 'scripts', 'install-revmux-prompts.sh')) && ledger.tools.revmux?.choice === 'installed') {
+    const r = run('bash', [join(SKILL_DIR, 'scripts', 'install-revmux-prompts.sh'), '--check']);
+    ledger.tools.revmux.promptsInSync = r.ok;
+  }
+  return allResolved;
+}
+
+function isDue(ledger, now) {
+  const age = (iso) => (iso ? now - Date.parse(iso) : Infinity);
+  return age(ledger.checkedAt) > ledger.cadenceDays * DAY_MS && age(ledger.lastAttemptAt) > RETRY_AFTER_MS;
+}
+
+function brewRun(args) {
+  const brew = findBrew();
+  if (!brew) return { status: 'manual', reason: 'brew not found', command: `brew ${args.join(' ')}` };
+  const r = run(brew, args, 300000);
+  return r.ok ? { status: 'ok' } : { status: 'failed', command: `brew ${args.join(' ')}`, tail: r.out };
+}
+
+function postInstall(name) {
+  const p = OPTIONAL[name].postInstall;
+  if (!p) return null;
+  const r = run(p[0], p[1], 60000);
+  return r.ok ? 'ok' : `failed: ${r.out}`;
+}
+
+function install(ledger, name) {
+  const res = brewRun(OPTIONAL[name].brew);
+  const version = installedVersion(name);
+  // brew can fail with "already installed": the binary on PATH is the truth.
+  if (version) {
+    ledger.tools[name] = { ...ledger.tools[name], choice: 'installed', version, decidedAt: new Date().toISOString() };
+    return { tool: name, status: 'ok', version, postInstall: postInstall(name) };
+  }
+  ledger.tools[name] = { ...ledger.tools[name], choice: 'installed', version: null, decidedAt: new Date().toISOString() };
+  return { tool: name, ...res };
+}
+
+function update(ledger, names) {
+  const results = [];
+  for (const name of names) {
+    const entry = ledger.tools[name];
+    if (!entry || entry.choice !== 'installed') continue;
+    const before = installedVersion(name);
+    const res = before ? brewRun(OPTIONAL[name].brewUpgrade) : brewRun(OPTIONAL[name].brew);
+    const after = installedVersion(name);
+    entry.version = after;
+    entry.outdated = newer(entry.latest, after);
+    // Resync even when brew could not run: the prompts follow the skill, not the binary.
+    const post = after ? postInstall(name) : null;
+    if (name === 'revmux' && post) entry.promptsInSync = post === 'ok';
+    results.push({ tool: name, before, after, ...res, postInstall: post });
+  }
+  return results;
+}
+
+function unknownTool(name) {
+  if (OPTIONAL[name]) return false;
+  console.log(JSON.stringify({ error: `unknown tool "${name}"`, known: Object.keys(OPTIONAL) }));
+  process.exitCode = 2;
+  return true;
+}
+
+const now = Date.now();
+let ledger = loadLedger();
+
+if (cmd === 'check') {
+  const missing = requiredMissing();
+  if (missing.length) {
+    console.log(JSON.stringify({ state: 'missing-required', missing }));
+  } else if (!ledger?.initialisedAt) {
+    const offer = Object.entries(OPTIONAL).map(([name, t]) => ({ tool: name, usedBy: t.usedBy, present: onPath(t.versionCmd[0]) }));
+    console.log(JSON.stringify({ state: 'first-run', offer }));
+  } else {
+    const due = has('force') || isDue(ledger, now);
+    if (due) fullCheck(ledger, now);
+    const outdated = Object.entries(ledger.tools).filter(([, e]) => e.choice === 'installed' && e.outdated).map(([n, e]) => ({ tool: n, version: e.version, latest: e.latest }));
+    let updated = null;
+    // Unattended runs only report: upgrading a binary is a machine change.
+    if (due && outdated.length && ledger.autoUpdate && !has('unattended')) {
+      updated = update(ledger, outdated.map((o) => o.tool));
+    }
+    if (due) saveLedger(ledger);
+    console.log(JSON.stringify({
+      state: due ? 'checked' : 'fresh',
+      checkedAt: ledger.checkedAt,
+      nextCheckAfter: ledger.checkedAt ? new Date(Date.parse(ledger.checkedAt) + ledger.cadenceDays * DAY_MS).toISOString() : null,
+      presence: presence(ledger),
+      outdated,
+      updated,
+      revmuxPromptsInSync: ledger.tools.revmux?.promptsInSync ?? null,
+      skipped: Object.entries(ledger.tools).filter(([, e]) => e.choice === 'skipped').map(([n]) => n),
+      // Tools added to the registry after the first run: offer these once.
+      undecided: Object.keys(OPTIONAL).filter((n) => !ledger.tools[n]).map((n) => ({ tool: n, usedBy: OPTIONAL[n].usedBy })),
+    }));
+  }
+} else if (cmd === 'init') {
+  ledger = ledger || blankLedger();
+  const list = (s) => (s ? s.split(',').map((x) => x.trim()).filter(Boolean) : []);
+  const auto = flag('auto-update');
+  if (auto) ledger.autoUpdate = auto === 'on';
+  const cadence = Number(flag('cadence-days'));
+  if (cadence > 0) ledger.cadenceDays = cadence;
+  const results = [];
+  for (const name of list(flag('skip'))) {
+    if (unknownTool(name)) break;
+    ledger.tools[name] = { choice: 'skipped', decidedAt: new Date().toISOString() };
+    results.push({ tool: name, status: 'skipped' });
+  }
+  for (const name of list(flag('install'))) {
+    if (unknownTool(name)) break;
+    results.push(install(ledger, name));
+  }
+  // Answering the offer covers every tool in it: one not picked counts as
+  // skipped, so the question is never asked twice.
+  for (const name of Object.keys(OPTIONAL)) {
+    if (!ledger.tools[name]) ledger.tools[name] = { choice: 'skipped', decidedAt: new Date().toISOString() };
+  }
+  ledger.initialisedAt = ledger.initialisedAt || new Date(now).toISOString();
+  fullCheck(ledger, now);
+  saveLedger(ledger);
+  console.log(JSON.stringify({ state: 'initialised', ledger: LEDGER, autoUpdate: ledger.autoUpdate, cadenceDays: ledger.cadenceDays, results }));
+} else if (cmd === 'install' || cmd === 'skip') {
+  const name = argv[1];
+  if (!unknownTool(name)) {
+    ledger = ledger || blankLedger();
+    const result = cmd === 'install'
+      ? install(ledger, name)
+      : ((ledger.tools[name] = { choice: 'skipped', decidedAt: new Date().toISOString() }), { tool: name, status: 'skipped' });
+    saveLedger(ledger);
+    console.log(JSON.stringify(result));
+  }
+} else if (cmd === 'update') {
+  if (!ledger) {
+    console.log(JSON.stringify({ state: 'first-run', hint: 'run init first' }));
+  } else {
+    fullCheck(ledger, now);
+    const names = argv[1] ? [argv[1]] : Object.entries(ledger.tools).filter(([, e]) => e.choice === 'installed' && e.outdated).map(([n]) => n);
+    const results = update(ledger, names);
+    saveLedger(ledger);
+    console.log(JSON.stringify({ state: 'updated', results }));
+  }
+} else if (cmd === 'reset') {
+  saveLedger(blankLedger());
+  console.log(JSON.stringify({ state: 'reset', ledger: LEDGER }));
+} else {
+  console.log(JSON.stringify({ error: `unknown command "${cmd}"` }));
+  process.exitCode = 2;
+}

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/revmux-engine.sh

@@ -134,18 +134,23 @@ cp "$WORKTREE_JSON" "$CONTEXT_DIR/worktree.json"
 cp "$PROFILE_FILE" "$PROFILE_INPUT_FILE"
 
 REVMUX_OUT="$OUT"
+# revmux keeps no stderr of its own. Seven rounds between 2026-10-08 and
+# 2026-10-14 had every agent exit -1 within seconds with nothing in the
+# archive to say why, so keep it beside the round (input/scope.md -> round dir).
+STDERR_LOG="$(dirname "$(dirname "$SCOPE_FILE")")/revmux.stderr.log"
 set +e
 revmux --task "$TASK" --run "$RUN" --profile "$PROFILE_NAME" \
     --workdir "$WORKDIR" --tasks-dir "$TASKS_DIR" --config-dir "$CONFIG_DIR" \
     --tools=Read,Grep,Glob,WebFetch,WebSearch \
-    --no-tui > "$REVMUX_OUT"
+    --no-tui > "$REVMUX_OUT" 2> "$STDERR_LOG"
 CODE=$?
 set -e
+cat "$STDERR_LOG" >&2
 
 case "$CODE" in
     0) printf 'revmux exit 0 (no findings)\n' >&2 ;;
     1) printf 'revmux exit 1 (findings reported)\n' >&2 ;;
-    *) printf 'revmux exit %s (tool error)\n' "$CODE" >&2 ;;
+    *) printf 'revmux exit %s (tool error), stderr kept in %s\n' "$CODE" "$STDERR_LOG" >&2 ;;
 esac
 
 exit "$CODE"