@ngockhoale/ukit 3.4.60 → 3.4.62

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.62 - 2026-10-22
+
+**Handoff commands: state what `handoff.maxParallelAgents` counts (wording only).**
+- The cap is child workers of ONE batch or review set, summed across roles (implementers and reviewers together); the main session is outside it; it is not a session-wide limit; it is prompt-level guidance (no hook counts children) and the host's own concurrency limit is separate. Added to `handoff-implement`, `handoff-fullstack` (implement batch + review set) and `handoff-review`.
+- No default, config key, scope or behavior change. Basis: BAGuide field audit (peak 14 concurrent children while the cap text said 2, never refused), see `docs/analysis/CONCURRENCY-CHECKPOINT-2026-10-22.md`.
+
+## 3.4.61 - 2026-10-22
+
+**omp bash: stop sending the call shape the host rejects (`name` + `async`/`timeout`).**
+- Field evidence (BAGuide session log, 2026-10-19..22): 1,771 of 6,541 bash calls failed with "Service mode does not accept async or timeout; use ready.timeout for readiness." Every failing call carried `name` with `async`/`timeout`; calls without `name` never failed and 66 immediate retries that dropped `name` succeeded. `name` was used as a label on finite commands.
+- Host contract (omp 18.12.5 bash `execute`, read from the installed binary): `name` selects SERVICE mode, which rejects `async === true` and any `timeout`; readiness is `ready.timeout`. Without `name`, `async`/`timeout` are valid and `ready` is only ignored with a warning.
+- Change: `omp-bash-call-guard.mjs` (block-only, stateless, never rewrites input or changes a command's meaning) wired into the omp bridge `tool_call` for `bash`; the block reason separates the two intents (finite command: drop `name`/`ready`; service: drop `async`/`timeout`, use `ready.timeout`). Same rule added to the Stall & Wait instructions (STALL-02) for all three engines.
+- Live smoke (omp 18.12.5, isolated temp project with the template bridge, model `unic/unic-lite`, BAGuide and the omp binary untouched): `name`+`timeout` was blocked with the UKit preflight text (not the host's "Service mode..." text), so the `tool_call` hook runs before the host validator; a finite command ran; the corrected retry (name dropped) ran and was not blocked. NOT verified live: a genuine service call (the test model kept adding a top-level `timeout`; one attempt hung with no output and was stopped; no process was left running). The service-allowed path is covered only by the bridge-boundary tests. Guidance, not host enforcement.
+- Flaky test root cause + fix: `withTransientFsRetry` compared `Date.now()` against a deadline while sleeping with `setTimeout`; node timers can fire up to ~2% early at small delays, so after a clamped sleep the clock still showed time remaining and an extra attempt ran. It now measures with `performance.now()` (injectable `now`/`sleep`) and stops after a sleep that exhausted the deadline. Regression: `tests/hooks/transientFsRetry.test.js` (controlled clock incl. early-timer skew, plus one real-timer smoke); 30/30 repeated runs.
+- Review freshness through a real Bash mutation (git fixture, real PostToolUse receipt): review approved -> `sed -i` via Bash -> `changeSeq` advances, review is `review-stale`, verification is `edited-after-verification`; a no-op Bash keeps the approval. No defect reproduced; regression `tests/hooks/playbookReviewBashMutation.test.js`.
+- Regression: `tests/hooks/ompBashCallGuard.test.js` (normal finite command with timeout/async allowed; genuine service with `ready.timeout` allowed; `name`+`timeout` / `name`+`async` blocked repeatably; blank `name` is not service mode; input never mutated).
+
 ## 3.4.60 - 2026-10-22
 
 **Completion Gate: a background completion footer is no longer trusted on its own.**

package/manifests/documentation.yaml

@@ -451,6 +451,17 @@ entries:
     validation: [manual]
     archive_policy: replace-with-snapshot
     notes: Phase A read-only concurrency audit; provisional metrics labelled, pilot not run
+  - id: docs-analysis-concurrency-checkpoint
+    path: docs/analysis/CONCURRENCY-CHECKPOINT-2026-10-22.md
+    class: canonical
+    audience: [owner, maintainer]
+    owner: runtime
+    source_of_truth: docs/analysis/CONCURRENCY-CHECKPOINT-2026-10-22.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: replace-with-snapshot
+    notes: continuity checkpoint for the concurrency audit (R6 corrections, bash guard, prepared unpaid pilot)
   - id: docs-analysis-subagent-cost-audit
     path: docs/analysis/SUBAGENT-COST-AUDIT.md
     class: archive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.60",
+  "version": "3.4.62",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/template_project/.claude/commands/ukit/handoff-fullstack.md

@@ -446,7 +446,7 @@ if it is missing required fields — never merely for sharing a file.
 **Batch each wave — mandatory.** Read `handoff.maxParallelAgents` from
 `.ukit/storage/config.json`. A wave with more tasks than that is split
 into consecutive batches of at most that many; finish one batch completely (including 3c
-copy-back and worktree deletion) before starting the next.
+copy-back and worktree deletion) before starting the next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
 Never spawn a whole wide wave at once. Every background agent carries its own context
 window, and each finished report is injected back into this session — a wave of 20+ is
@@ -659,7 +659,7 @@ Never make fake edits or fake tests to satisfy an empty diff, and never lower ac
 
 ### R2 — Model isolation check (strong model, always first)
 
-**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next.
+**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
 **Claude Code — MANDATORY, do this before anything else in R2–R4:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per task in the batch, not once per wave). Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees.
 

package/template_project/.claude/commands/ukit/handoff-implement.md

@@ -103,7 +103,7 @@ when it is missing required fields — never merely for sharing a file.
 Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. A wave
 with more tasks than that is split into consecutive batches of at most that many; finish
 one batch completely (including 3c copy-back and worktree deletion) before starting the
-next.
+next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
 Never spawn a whole wide wave at once. Every background agent carries its own context
 window, and each finished report is injected back into this session — a wave of 20+ is

package/template_project/.claude/commands/ukit/handoff-review.md

@@ -53,7 +53,7 @@ Classify by what the diff can show. An empty diff is NOT automatically "implemen
 
 ## Step 2 — Review the diff
 
-**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next.
+**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
 **Spawn the review panel — MANDATORY, do this before anything else:** read `modelRoles['review-panel']` from `.ukit/storage/config.json` → `modelRoles` (default `['smart','code','lite']`; omp tier aliases `@smol`/`@default`/`@slow`). For each `pending_review` task in the batch, call the Agent tool **once per panel entry** (in parallel, bounded by `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per panel entry per task) — each member bound to its panel tier and setting `PANEL_MEMBER: <tier>` in its verdict. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the panel tiers and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
 

package/template_project/.claude/ukit/runtime/async-lock.mjs

@@ -113,7 +113,10 @@ export const TRANSIENT_FS_CODES = new Set(['EAGAIN', 'EBUSY', 'EMFILE', 'ENFILE'
  *   maxDelayMs?: number,
  *   deadlineMs?: number,
  *   signal?: AbortSignal,
- * }} [options]
+ *   now?: () => number,
+ *   sleep?: (ms: number, signal?: AbortSignal) => Promise<boolean>,
+ * }} [options] `now` (monotonic ms) and `sleep` (resolves true when it elapsed fully)
+ *   are injectable so deadline semantics can be tested without wall-clock timing.
  * @returns {Promise<*>} op's resolved value
  */
 export async function withTransientFsRetry(op, {
@@ -122,8 +125,10 @@ export async function withTransientFsRetry(op, {
   maxDelayMs = 150,
   deadlineMs = Infinity,
   signal,
+  now = () => performance.now(),
+  sleep = sleepWithAbort,
 } = {}) {
-  const startedAt = Date.now();
+  const startedAt = now();
   const maxAttempts = Number.isFinite(retries) && retries >= 0 ? Math.floor(retries) + 1 : 1;
   let lastError = null;
   for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
@@ -135,12 +140,18 @@ export async function withTransientFsRetry(op, {
     } catch (error) {
       lastError = error;
       if (!TRANSIENT_FS_CODES.has(error?.code) || attempt + 1 >= maxAttempts) throw error;
-      const remaining = deadlineMs - (Date.now() - startedAt);
+      const remaining = deadlineMs - (now() - startedAt);
       if (remaining <= 0) throw error;
       const backoff = Math.min(baseDelayMs * (2 ** attempt), maxDelayMs);
-      const waitMs = Math.min(backoff * (0.5 + Math.random()), remaining);
-      const sleptFully = await sleepWithAbort(Math.max(0, waitMs), signal);
-      if (!sleptFully || Date.now() - startedAt >= deadlineMs) throw error;
+      const wanted = backoff * (0.5 + Math.random());
+      const waitMs = Math.min(wanted, remaining);
+      // A sleep clamped to `remaining` consumes the whole deadline BY CONSTRUCTION. Re-reading a
+      // clock afterwards is wrong: timers (libuv, ms-truncated) and the clock can disagree by a
+      // millisecond, so a fired 5 ms timer can read as 4 ms elapsed and grant one extra attempt
+      // past the deadline (observed: setTimeout(5) woke with Date.now() +4 ms in ~0.4% of runs).
+      const exhaustsDeadline = wanted >= remaining;
+      const sleptFully = await sleep(Math.max(0, waitMs), signal);
+      if (!sleptFully || exhaustsDeadline || now() - startedAt >= deadlineMs) throw error;
     }
   }
   throw lastError;

package/template_project/.claude/ukit/runtime/omp-bash-call-guard.mjs

@@ -0,0 +1,53 @@
+// omp-bash-call-guard.mjs — block-only preflight for OMP `bash` call shape.
+//
+// Field evidence (BAGuide, 2026-10-19..22): 1,771 of 6,541 bash calls failed with
+// "Service mode does not accept async or timeout; use ready.timeout for readiness."
+// Every failing call carried `name` (the supervised-SERVICE mode) together with `async`
+// or `timeout`; calls without `name` never failed, and 66 immediate retries that dropped
+// `name` succeeded. The agent used `name` as a label on an ordinary finite command.
+//
+// Host contract (omp 18.12.5, bash tool `execute`, read from the binary):
+// - `name` non-empty  => service mode. `async === true` or any `timeout` is rejected;
+//   readiness is `ready.timeout` (seconds) with `ready.log` / `ready.port`.
+// - no `name`         => ordinary command; `async` / `timeout` are valid; `ready` is
+//   ignored with a warning (not an error), so it is not validated here.
+//
+// This guard blocks only the combination the host is known to reject, with guidance that
+// separates the two intents. It never rewrites input and never changes the meaning of a
+// command — choosing finite vs service is the caller's job. The host owns the schema; this
+// is a tolerant, version-pinned mirror of one rule. It can only act where the host runs the
+// tool_call hook before its own validator; where the host validates first, the native
+// error is the only signal and this guard cannot intervene (guidance in RULES.md still applies).
+
+/**
+ * @param {object} args - bash tool input
+ * @returns {{ valid: boolean, violations: Array<{code: string, field: string}> }}
+ */
+export function validateOmpBashArgs(args) {
+  const violations = [];
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return { valid: true, violations };
+  const name = typeof args.name === 'string' ? args.name.trim() : '';
+  if (name === '') return { valid: true, violations };
+  if (args.async === true) violations.push({ code: 'service-with-async', field: 'async' });
+  if (args.timeout !== undefined && args.timeout !== null) {
+    violations.push({ code: 'service-with-timeout', field: 'timeout' });
+  }
+  return { valid: violations.length === 0, violations };
+}
+
+/**
+ * @param {object} args - bash tool input
+ * @returns {{ action: 'allow' } | { action: 'block', violations: object[], guidance: string }}
+ */
+export function preflightOmpBashCall(args) {
+  const { valid, violations } = validateOmpBashArgs(args);
+  if (valid) return { action: 'allow' };
+  const fields = violations.map((v) => `\`${v.field}\``).join(' + ');
+  const guidance = [
+    `omp bash: \`name\` selects SERVICE mode, which rejects ${fields}. Do not resend this invocation unchanged.`,
+    'Pick one intent:',
+    '- Ordinary finite command (tests, build, one-shot script): remove `name` and `ready`; keep `timeout` / `async` as needed. `name` is not a label.',
+    '- Genuine long-running service/watcher: keep `name`, remove `async` and `timeout`, and set readiness with `ready: { log|port, timeout }` (seconds). Inspect it via `read proc://<name>`.',
+  ].join('\n');
+  return { action: 'block', violations, guidance };
+}

package/template_project/.omp/hooks/pre/ukit-bridge.js

@@ -30,6 +30,7 @@ import {
 // for Edit|Write is a fail-closed transport failure = every edit blocked).
 import { resolveChainExecTimeoutMs } from '../../../.claude/ukit/runtime/hook-chain-budget.mjs';
 import { preflightOmpTaskDispatch } from '../../../.claude/ukit/runtime/omp-task-dispatch-guard.mjs';
+import { preflightOmpBashCall } from '../../../.claude/ukit/runtime/omp-bash-call-guard.mjs';
 
 // OMP-3 (TASK-002): pi.exec forwards only {cwd, signal, timeout} to its spawn —
 // an environment option is dropped (verified against the bundled omp exec), and the host's
@@ -929,6 +930,15 @@ export async function runToolCall(pi, event, { projectRoot, context: extensionCo
         reason: `UKit OMP task preflight: ${dispatch.guidance}` };
     }
   }
+  // omp bash: `name` = service mode, which the host rejects together with async/timeout.
+  // Block-only (the host return cannot rewrite input); stateless, so a corrected call is allowed.
+  if (String(rawToolName ?? '').trim().toLowerCase() === 'bash') {
+    const bashCall = preflightOmpBashCall(event.input);
+    if (bashCall.action === 'block') {
+      return { block: true, toolName: 'Bash', invoked: [], context: [],
+        reason: `UKit OMP bash preflight: ${bashCall.guidance}` };
+    }
+  }
   const payload = buildHookPayload('PreToolUse', {
     toolName,
     toolInput: normalizeToolInput(toolName, event.input),

package/template_project/AGENTS.md

@@ -29,7 +29,7 @@
 <!-- RULE: STALL-01 -->
 - Announce long waits: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface errors verbatim; suspect network/API — **never blame UKit**.
 <!-- RULE: STALL-02 -->
-- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation.
+- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation. omp `bash`: `name` = supervised SERVICE (rejects `async`/`timeout`; readiness = `ready.timeout`) — finite commands omit `name`/`ready`; after a "Service mode does not accept async or timeout" error drop `name` (finite) or drop `async`/`timeout` (service). UKit's omp bridge blocks that combination where the host runs hooks first; otherwise this is guidance only.
 <!-- RULE: STALL-03 -->
 - **Conditional workaround only:** one tool call per assistant message only when malformed/concatenated tool-input errors are observed or the harness is known-affected — healthy hosts keep parallel calls.
 

package/template_project/CLAUDE.md

@@ -29,7 +29,7 @@
 <!-- RULE: STALL-01 -->
 - Announce long waits: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface errors verbatim; suspect network/API — **never blame UKit**.
 <!-- RULE: STALL-02 -->
-- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation.
+- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation. omp `bash`: `name` = supervised SERVICE (rejects `async`/`timeout`; readiness = `ready.timeout`) — finite commands omit `name`/`ready`; after a "Service mode does not accept async or timeout" error drop `name` (finite) or drop `async`/`timeout` (service). UKit's omp bridge blocks that combination where the host runs hooks first; otherwise this is guidance only.
 <!-- RULE: STALL-03 -->
 - **Conditional workaround only:** one tool call per assistant message only when malformed/concatenated tool-input errors are observed or the harness is known-affected — healthy hosts keep parallel calls.
 

package/template_project/instructions/core.md

@@ -26,7 +26,7 @@
 <!-- RULE: STALL-01 -->
 - Announce long waits: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface errors verbatim; suspect network/API — **never blame UKit**.
 <!-- RULE: STALL-02 -->
-- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation.
+- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation. omp `bash`: `name` = supervised SERVICE (rejects `async`/`timeout`; readiness = `ready.timeout`) — finite commands omit `name`/`ready`; after a "Service mode does not accept async or timeout" error drop `name` (finite) or drop `async`/`timeout` (service). UKit's omp bridge blocks that combination where the host runs hooks first; otherwise this is guidance only.
 <!-- RULE: STALL-03 -->
 - **Conditional workaround only:** one tool call per assistant message only when malformed/concatenated tool-input errors are observed or the harness is known-affected — healthy hosts keep parallel calls.