@ngockhoale/ukit 3.5.18 → 3.5.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,40 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.5.20 - 2026-11-21
6
+
7
+ Field-telemetry fix round 6 (live session + field data since 3.5.19).
8
+
9
+ - **Stop gates honour background waits (R6-1).** When the completion gate releases a Stop because a background job or subagent is still running (WAIT), the mission gate no longer blocks that Stop. The WAIT now travels through the stop coordinator (`outcome: waiting`, `waitingOn`), and the mission gate releases it with a note that it is not completion.
10
+ - **Status questions are not requirements (R6-2).** Progress checks such as "đã xong tới đâu rồi", "vậy là xong chưa", "còn lỗi không", "…rồi sao", "sao vẫn chưa …" and "is it done yet" are classified as questions, so they no longer become mission requirements that need acceptance evidence. Work requests ("sửa lỗi login đi", "thêm nút export CSV") are unchanged, and a status check appended to a work clause ("thêm nút export, chạy test chưa", "sửa login rồi chạy test chưa") keeps the work requirement.
11
+ - **Old pauses no longer release every later stop (R6-7).** The stop coordinator used to scan past newer owner turns that were not control phrases. One "dừng đi" therefore released 83 later stops in one BAGuide session over 17 hours. Now a later owner work request (short or long) supersedes an older pause/cancel. A read-only question asked during a pause ("health check: is everything ok?") keeps the pause, and peer-envelope text is still skipped. Ref: anthropics/claude-code#101528.
12
+ - **Same-command temp cleanup is allowed (R6-4).** A recursive delete of `"$P"` is no longer blocked when `P` was assigned from `mktemp -d` in an earlier segment of the same command, quoted, and never reassigned; the exemption also requires every other segment to start with an allow-listed command that cannot assign shell variables, and no substitution, arithmetic, grouping, `eval` or `printf` anywhere in the command. Every other recursive delete of a variable stays blocked.
13
+ - **Ranked multi-section reports pass through uncompressed (R6-10).** Output compression recognises `N.` rank prefixes and sections whose numbering restarts. The field-telemetry report no longer comes back reordered.
14
+ - **Field audit tools (R6-3, R6-5).** `field-telemetry` normalises job/task/agent ids, so one class no longer splits per id. `--since` accepts `YYYY-MM-DDTHH:MM[:SS][Z]` for post-release windows; `field-replay` uses the same cutoff.
15
+ - R6-6 (batch planner per-file history) was checked against data: after 3.5.19, all 798/798 files have measured durations, so no code change was needed.
16
+
17
+ ## 3.5.19 - 2026-11-21
18
+
19
+ Field-telemetry fix round 5 and faster batched test runs.
20
+
21
+ - **Secret guard false positives (R5-1..R5-4).**
22
+ - `grep -o 'KEY=' .env` (a literal key name, optionally `^`-anchored) is allowed: it can only print that literal. Every grep option is validated, including ones after the pattern (`-e`/`-f`/`-P`).
23
+ - Pipes that try to strip values (`| cut -d= -f1`, `| sed 's/=.*//'`, with or without `-s`/`-n …p`) and regexp classes (`grep -oE '^[A-Z_]*='`) stay blocked. Independent review showed continuation lines of a multi-line value (PEM/base64) carry `=` padding, so these forms can print value text.
24
+ - Inside `$()` nothing new is exempt: digest/metadata verbs (`shasum`, `stat`, `wc`) and `ssh -i KEY` stay blocked on secret files because they echo the filename (`ssh -v … 2>&1`), which an outer `cat $(…)` would read. `wc --files0-from=FILE` is now classified too.
25
+ - Anything that could still print a value stays blocked: an intermediate `tee`, other sed scripts, `cut -f2`, and name producers such as `cat $(echo .env)`.
26
+ - **Loop-breaker (R5-5).** A commit (git HEAD change) now counts as progress. The refused-stop count and its grammar are correct ("1 consecutive time").
27
+ - **Shell watch (R5-8).** Never reports or kills a shell owned by another live Claude Code, Codex or omp session.
28
+ - **Field audit tools (R5-6, R5-7).**
29
+ - `field-telemetry --json` no longer truncates large output on a pipe.
30
+ - `--sample-chars N` controls the sample length for field-telemetry and field-replay.
31
+ - **Release core batches (R5-9).** An empty batch or a missing listed file fails before vitest starts.
32
+ - **Faster full-suite batches.** `test-batches.mjs` gains a `workers` setting (`--workers N` or `.ukit/storage/test-batches.json`). The default of 1 keeps the old serial behaviour, so projects that leave it unset are unaffected.
33
+ - With N>1, each fresh batch process runs up to N files at once (`vitest --maxWorkers`, `jest --maxWorkers`). Batches stay sequential, and every file still runs.
34
+ - Case and file budgets scale per worker, and memory is predicted from the top N peaks.
35
+ - Per-file durations from every report feed longest-first balancing, so one slow file no longer leaves a long tail.
36
+ - Maintainers set `workers` locally (this file is not shipped); the 30.0 → 16.8 min figure used 3 workers.
37
+ - No test was removed or skipped, and the verdict rules are unchanged.
38
+
5
39
  ## 3.5.18 - 2026-11-21
6
40
 
7
41
  - **Auto-compaction fix:** context budget sized to the real ~200k route window (hard cap 185k, host auto-compact 148k; was 250k/235k/188k). The context guard measures from the API-reported usage of the newest assistant turn and ignores transcript-only hook attachments (previously ~3x overcount). The over-cap advisory no longer says "keep working"; it says to stop stacking new work, defer to disk, and add one trailing /compact note.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.5.18",
3
+ "version": "3.5.20",
4
4
  "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -10,7 +10,7 @@
10
10
  * sample commands per class (redacted + truncated; values never printed).
11
11
  *
12
12
  * Usage: node scripts/audit/field-replay.mjs [--projects-dir DIR] [--match SUBSTR]...
13
- * [--since YYYY-MM-DD] [--limit N] [--hook sensitive] [--mode inproc|cli] [--json]
13
+ * [--since YYYY-MM-DD[THH:MM]] [--limit N] [--sample-chars N] [--hook sensitive] [--mode inproc|cli] [--json]
14
14
  *
15
15
  * Hooks are registered in HOOKS below; add block-dangerous / execution-ledger
16
16
  * (PostToolUse) by adding an entry with its own payload builder + verdict parser.
@@ -22,7 +22,7 @@ import path from 'node:path';
22
22
  import readline from 'node:readline';
23
23
  import { spawn } from 'node:child_process';
24
24
  import { fileURLToPath, pathToFileURL } from 'node:url';
25
- import { parseArgs, listTranscripts, normalizeMessage, redact, truncate } from './field-telemetry.mjs';
25
+ import { parseArgs, listTranscripts, normalizeMessage, redact, truncate, beforeSince } from './field-telemetry.mjs';
26
26
 
27
27
  const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
28
28
  const HOOK_DIR = path.join(REPO, 'template_project', '.claude', 'hooks');
@@ -55,7 +55,7 @@ export function extractBashCommands(line, out, { since } = {}) {
55
55
  return;
56
56
  }
57
57
  if (o?.type !== 'assistant' || !Array.isArray(o.message?.content)) return;
58
- if (since && typeof o.timestamp === 'string' && o.timestamp.slice(0, 10) < since) return;
58
+ if (beforeSince(o.timestamp, since)) return;
59
59
  for (const c of o.message.content) {
60
60
  if (c && c.type === 'tool_use' && c.name === 'Bash' && typeof c.input?.command === 'string' && c.input.command.trim()) {
61
61
  out.set(c.input.command, (out.get(c.input.command) || 0) + 1);
@@ -108,7 +108,7 @@ function runCli(hook, payload, projectRoot, tmpDir, idx) {
108
108
  }
109
109
 
110
110
  // --- aggregation -------------------------------------------------------------------
111
- export function classifyResults(results, hook, { samples = 40 } = {}) {
111
+ export function classifyResults(results, hook, { samples = 40, sampleChars = 200 } = {}) {
112
112
  const classes = new Map();
113
113
  let blocked = 0;
114
114
  for (const { command, verdict } of results) {
@@ -120,7 +120,7 @@ export function classifyResults(results, hook, { samples = 40 } = {}) {
120
120
  let c = classes.get(k);
121
121
  if (!c) classes.set(k, (c = { cls: k, count: 0, samples: [] }));
122
122
  c.count += 1;
123
- if (c.samples.length < samples) c.samples.push(truncate(redact(command), 200));
123
+ if (c.samples.length < samples) c.samples.push(truncate(redact(command), sampleChars));
124
124
  }
125
125
  }
126
126
  return { blocked, classes: [...classes.values()].sort((a, b) => b.count - a.count || a.cls.localeCompare(b.cls)) };
@@ -129,7 +129,7 @@ export function classifyResults(results, hook, { samples = 40 } = {}) {
129
129
  export async function main(argv = process.argv.slice(2)) {
130
130
  const opts = parseArgs(argv);
131
131
  if (opts.help) {
132
- process.stdout.write('Usage: field-replay.mjs [--projects-dir DIR] [--match SUBSTR]... [--since YYYY-MM-DD] [--limit N] [--hook sensitive] [--mode inproc|cli] [--json]\n');
132
+ process.stdout.write('Usage: field-replay.mjs [--projects-dir DIR] [--match SUBSTR]... [--since YYYY-MM-DD[THH:MM]] [--limit N] [--sample-chars N] [--hook sensitive] [--mode inproc|cli] [--json]\n');
133
133
  return 0;
134
134
  }
135
135
  const hook = HOOKS[opts.hook];
@@ -161,7 +161,7 @@ export async function main(argv = process.argv.slice(2)) {
161
161
  await fsp.rm(projectRoot, { recursive: true, force: true });
162
162
  await fsp.rm(tmpDir, { recursive: true, force: true });
163
163
  }
164
- const rep = classifyResults(results, hook);
164
+ const rep = classifyResults(results, hook, { sampleChars: opts.sampleChars });
165
165
  const meta = { hook: opts.hook, mode: opts.mode, files, since: opts.since, replayed: commands.length, blocked: rep.blocked, errors, ms: Date.now() - t0 };
166
166
  if (opts.json) {
167
167
  process.stdout.write(`${JSON.stringify({ meta, classes: rep.classes }, null, 2)}\n`);
@@ -185,10 +185,10 @@ const isDirect = (() => {
185
185
  })();
186
186
  if (isDirect) {
187
187
  main().then(
188
- (code) => process.exit(code),
188
+ (code) => { process.exitCode = code; },
189
189
  (err) => {
190
190
  process.stderr.write(`field-replay: ${err && err.message ? err.message : err}\n`);
191
- process.exit(1);
191
+ process.exitCode = 1;
192
192
  },
193
193
  );
194
194
  }
@@ -17,7 +17,7 @@
17
17
  * the assistant tool_use block with the same id.
18
18
  *
19
19
  * Usage: node scripts/audit/field-telemetry.mjs [--projects-dir DIR]
20
- * [--match SUBSTR]... [--since YYYY-MM-DD] [--json]
20
+ * [--match SUBSTR]... [--since YYYY-MM-DD[THH:MM]] [--json]
21
21
  */
22
22
  import fs from 'node:fs';
23
23
  import fsp from 'node:fs/promises';
@@ -33,11 +33,29 @@ const HEX_RE = /\b(?=[0-9a-f]*[0-9])(?=[0-9a-f]*[a-f])[0-9a-f]{7,}\b/gi;
33
33
  const PATH_RE = /(?<![\w.-])(?:~|\$[A-Z_]+|\.{1,2})?(?:\/[^\s"'`:,;()<>\]\[{}]+)+\/?|\b[\w.-]+(?:\/[\w.-]+){2,}\b|\b[\w.-]+(?:\/[\w.-]+)*\/[\w-]+\.[A-Za-z]\w{0,5}\b/g;
34
34
  // ^ relative paths need >=2 slashes or a file extension, so "dotenv/secret" stays readable.
35
35
  const NUM_RE = /\b\d+(?:\.\d+)?(?:ms|s|m|h|d|%|x|MB|KB|GB)?\b/g;
36
+ // Host background job / agent ids (`b0efx3x02`, `tasks/b9t9a0mz3.output`) after a job-ish word: one class, not one per id.
37
+ const JOB_ID_RE = /\b(job|verification|agent|task|tasks\/|task-id>?)(\s*)(?=[a-z0-9]*\d)(?=[a-z0-9]*[a-z])[a-z0-9]{6,20}\b/gi;
38
+
39
+ // `--since` accepts YYYY-MM-DD or an ISO datetime (YYYY-MM-DDTHH:MM[:SS][Z]); a zone-less value is UTC.
40
+ export const SINCE_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?Z?)?$/;
41
+ export function sinceToMs(since) {
42
+ if (!since) return 0;
43
+ const iso = since.length === 10 ? `${since}T00:00:00Z` : (since.endsWith('Z') ? since : `${since}Z`);
44
+ const ms = Date.parse(iso);
45
+ return Number.isFinite(ms) ? ms : 0;
46
+ }
47
+ // True when a transcript timestamp is before the window start (unknown timestamps stay in the window).
48
+ export function beforeSince(ts, since) {
49
+ if (!since || typeof ts !== 'string') return false;
50
+ const ms = Date.parse(ts);
51
+ return Number.isFinite(ms) ? ms < sinceToMs(since) : false;
52
+ }
36
53
 
37
54
  export function normalizeMessage(text, max = 140) {
38
55
  let s = String(text ?? '');
39
56
  s = s.replace(/<\/?system-reminder>/g, ' ');
40
57
  s = s.replace(UUID_RE, '#').replace(TOOLU_RE, '#');
58
+ s = s.replace(JOB_ID_RE, '$1$2#');
41
59
  s = s.replace(PATH_RE, '<p>');
42
60
  s = s.replace(HEX_RE, '#');
43
61
  s = s.replace(NUM_RE, 'N');
@@ -95,12 +113,12 @@ export function parseTranscriptLine(line, acc, { since } = {}) {
95
113
  }
96
114
  if (!o || typeof o !== 'object') return;
97
115
  const ts = o.timestamp;
98
- if (since && typeof ts === 'string' && ts.slice(0, 10) < since) {
116
+ if (beforeSince(ts, since)) {
99
117
  // still learn tool_use ids so later blocks can resolve their command
100
118
  if (o.type !== 'assistant') return;
101
119
  }
102
120
  const day = isoDay(ts);
103
- const inWindow = !since || day === 'unknown' || day >= since;
121
+ const inWindow = !since || day === 'unknown' || !beforeSince(ts, since);
104
122
 
105
123
  // assistant tool_use → remember Bash commands by id
106
124
  if (o.type === 'assistant' && Array.isArray(o.message?.content)) {
@@ -236,7 +254,7 @@ export function aggregate(acc, { top = 15, cmdTop = 20 } = {}) {
236
254
 
237
255
  // --- file discovery ---------------------------------------------------------------
238
256
  export function parseArgs(argv) {
239
- const opts = { projectsDir: path.join(os.homedir(), '.claude', 'projects'), match: [], since: null, json: false, limit: 20000, hook: 'sensitive', mode: 'inproc' };
257
+ const opts = { projectsDir: path.join(os.homedir(), '.claude', 'projects'), match: [], since: null, json: false, limit: 20000, hook: 'sensitive', mode: 'inproc', sampleChars: 200 };
240
258
  for (let i = 0; i < argv.length; i += 1) {
241
259
  const a = argv[i];
242
260
  const next = () => argv[++i];
@@ -245,17 +263,18 @@ export function parseArgs(argv) {
245
263
  else if (a === '--since') opts.since = next();
246
264
  else if (a === '--json') opts.json = true;
247
265
  else if (a === '--limit') opts.limit = Number.parseInt(next(), 10) || opts.limit;
266
+ else if (a === '--sample-chars') opts.sampleChars = Math.max(1, Number.parseInt(next(), 10) || 200);
248
267
  else if (a === '--hook') opts.hook = next();
249
268
  else if (a === '--mode') opts.mode = next();
250
269
  else if (a === '--help' || a === '-h') opts.help = true;
251
270
  }
252
271
  if (!opts.match.length) opts.match = ['KHOA-EXTENAL'];
253
- if (opts.since && !/^\d{4}-\d{2}-\d{2}$/.test(opts.since)) throw new Error(`--since must be YYYY-MM-DD, got ${opts.since}`);
272
+ if (opts.since && (!SINCE_RE.test(opts.since) || !sinceToMs(opts.since))) throw new Error(`--since must be YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS][Z], got ${opts.since}`);
254
273
  return opts;
255
274
  }
256
275
 
257
276
  export async function listTranscripts({ projectsDir, match, since }) {
258
- const sinceMs = since ? Date.parse(`${since}T00:00:00Z`) : 0;
277
+ const sinceMs = sinceToMs(since);
259
278
  const out = [];
260
279
  const walk = async (dir) => {
261
280
  let entries;
@@ -310,7 +329,7 @@ function renderText(rep, meta) {
310
329
  export async function main(argv = process.argv.slice(2)) {
311
330
  const opts = parseArgs(argv);
312
331
  if (opts.help) {
313
- process.stdout.write('Usage: field-telemetry.mjs [--projects-dir DIR] [--match SUBSTR]... [--since YYYY-MM-DD] [--json]\n');
332
+ process.stdout.write('Usage: field-telemetry.mjs [--projects-dir DIR] [--match SUBSTR]... [--since YYYY-MM-DD[THH:MM]] [--json]\n');
314
333
  return 0;
315
334
  }
316
335
  const t0 = Date.now();
@@ -332,10 +351,10 @@ const isDirect = (() => {
332
351
  })();
333
352
  if (isDirect) {
334
353
  main().then(
335
- (code) => process.exit(code),
354
+ (code) => { process.exitCode = code; },
336
355
  (err) => {
337
356
  process.stderr.write(`field-telemetry: ${err && err.message ? err.message : err}\n`);
338
- process.exit(1);
357
+ process.exitCode = 1;
339
358
  },
340
359
  );
341
360
  }
@@ -30,6 +30,15 @@ export function partition(files, count, cwd = process.cwd()) {
30
30
  return batches;
31
31
  }
32
32
 
33
+ // Guard: an empty batch would make `vitest run` receive no file filter and run the WHOLE suite;
34
+ // a listed path missing on disk would match nothing (vitest filters are substrings) and could
35
+ // silently run 0 tests. Both must fail the batch rather than pass or over-run.
36
+ export function assertBatchRunnable(batch, cwd = process.cwd()) {
37
+ if (!Array.isArray(batch) || batch.length === 0) throw new Error('core batch is empty (no file filter would run the entire suite)');
38
+ const missing = batch.filter((f) => { try { return !statSync(path.join(cwd, f)).isFile(); } catch { return true; } });
39
+ if (missing.length) throw new Error(`core batch lists file(s) not found on disk (would run 0 tests): ${missing.join(', ')}`);
40
+ }
41
+
33
42
  if (import.meta.url === `file://${process.argv[1]}`) {
34
43
  const index = Number(process.argv[2]);
35
44
  const count = Number(process.argv[3]);
@@ -40,6 +49,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
40
49
  const files = listCoreFiles();
41
50
  if (files.length === 0) { console.error('[core-batch] no test files listed'); process.exit(1); }
42
51
  const batch = partition(files, count)[index - 1];
52
+ try { assertBatchRunnable(batch); } catch (e) { console.error(`[core-batch] ${e.message}`); process.exit(1); }
43
53
  console.log(`[core-batch] ${index}/${count}: ${batch.length} of ${files.length} files`);
44
54
  const child = spawn('yarn', ['vitest', 'run', ...batch, '--bail', '5'], { stdio: 'inherit' });
45
55
  // Backstop watchdog (same budget as the verifier's per-step deadline; the verifier kills the whole tree first).
@@ -245,7 +245,37 @@ async function evaluate({ command, projectRoot, env, deadlineMs, signal }) {
245
245
  let verdictGeneric = false;
246
246
  let directSeen = false;
247
247
 
248
- for (const rawSegment of scan.split(/[;&|\n]/)) {
248
+ // R6-4: a quoted `"$P"` target is a directory this same command just created with
249
+ // `P=$(mktemp -d …)` — safe to remove. Only when that assignment is the ONLY place the
250
+ // name appears unexpanded. Builtins can assign through COMPUTED names (read/getopts/
251
+ // printf -v/eval/((…))/wait -p …), so enumerating them is unsound: instead EVERY other
252
+ // segment must start with a literal allow-listed command that cannot assign shell
253
+ // variables, and the command may hold no other substitution/arithmetic/grouping syntax.
254
+ const segments = scan.split(/[;&|\n]/);
255
+ const mktempVars = new Map(); // name -> index of the segment that assigned it
256
+ const MKTEMP_ASSIGN = /^\s*([A-Za-z_]\w*)=\$\(\s*mktemp((?:\s+[-\w.\/]+)*)\s*\)\s*$/;
257
+ const SAFE_HEAD = new Set(['cd', 'echo', 'ls', 'cat', 'cp', 'mv', 'mkdir', 'touch', 'git', 'node', 'npm', 'npx', 'yarn', 'pnpm', 'tar', 'unzip', 'grep', 'find', 'true', 'pwd', 'rm', 'sed', 'head', 'tail', 'wc', 'diff', 'cmp']);
258
+ const otherSegmentsSafe = segments.every((seg) => {
259
+ if (!seg.trim() || MKTEMP_ASSIGN.test(seg)) return true;
260
+ const head = seg.trim().split(/\s+/)[0];
261
+ return SAFE_HEAD.has(head);
262
+ });
263
+ const scanWithoutAssigns = scan.split('\n').join(';').split(/(?=[;&|])/).map((s) => s.replace(/^([;&|]+\s*)?[A-Za-z_]\w*=\$\(\s*mktemp[^)]*\)/, '$1')).join('');
264
+ const plainBraces = scanWithoutAssigns.replace(/\$\{[A-Za-z_]\w*\}/g, '$V');
265
+ const exoticSyntax = /\$\(|`|\$'|\$"|\(\(|[(){}]|\beval\b|\bprintf\b/.test(plainBraces);
266
+ if (otherSegmentsSafe && !exoticSyntax) segments.forEach((seg, idx) => {
267
+ const m = MKTEMP_ASSIGN.exec(seg);
268
+ if (!m || !/(^|\s)-[a-zA-Z]*d/.test(m[2]) || /(^|\s)-[a-zA-Z]*u/.test(m[2])) return;
269
+ const bare = scan.match(new RegExp(`(^|[^$\\w{])${m[1]}(?!\\w)`, 'g')) || [];
270
+ if (bare.length === 1 && !mktempVars.has(m[1])) mktempVars.set(m[1], idx);
271
+ });
272
+ const isFreshTempTarget = (target, idx) => {
273
+ const v = /^"\$(?:\{([A-Za-z_]\w*)\}|([A-Za-z_]\w*))"$/.exec(target);
274
+ const name = v && (v[1] || v[2]);
275
+ return Boolean(name) && mktempVars.has(name) && mktempVars.get(name) < idx;
276
+ };
277
+
278
+ for (const [segIdx, rawSegment] of segments.entries()) {
249
279
  const segment = rawSegment;
250
280
  if (!segment) continue;
251
281
  const tokens = segment.trimStart().split(/\s+/).filter(Boolean);
@@ -295,7 +325,9 @@ async function evaluate({ command, projectRoot, env, deadlineMs, signal }) {
295
325
  for (let target of targets) {
296
326
  // Strip ONE trailing slash (never shrink a bare `/` or `~` to '').
297
327
  if (target.length > 1 && target.endsWith('/')) target = target.slice(0, -1);
298
- if (UNSAFE_ONE_TARGET_RE.test(target)) {
328
+ if (isFreshTempTarget(target, segIdx)) {
329
+ // created by this command's own `mktemp -d`: always inside the OS temp area
330
+ } else if (UNSAFE_ONE_TARGET_RE.test(target)) {
299
331
  anyUnsafe = true;
300
332
  allSafe = false;
301
333
  } else if (SAFE_ONE_TARGET_RE.test(target)) {
@@ -702,12 +702,36 @@ async function evaluate({ rawInput, projectRoot, env }) {
702
702
  };
703
703
  // `env | grep -c X` / `printenv | grep -q X`: decided per segment — only an
704
704
  // env/printenv segment whose OWN pipe feeds a count-only grep is exempt.
705
+ const segmentWords = (segments, i) => (i < segments.length
706
+ ? splitShellWords(String(segments[i]).trim()).filter((t) => stripQuotes(t) !== '')
707
+ : []);
708
+ // `grep -o 'KEY=' .env`: with -o the output is only the matched text, and a
709
+ // LITERAL pattern can only ever print itself. No regexp/class form and no
710
+ // downstream "stripper" (`cut -s -d= -f1`, `sed -n 's/=.*//p'`) is exempt:
711
+ // continuation lines of a multi-line value (PEM/base64 body) contain `=` as
712
+ // padding, so any `…=` match or pre-`=` prefix can print value text
713
+ // (independent review of the 3.5.19 candidate, three rounds).
714
+ const isKeyNameOnlyGrep = (tokens, verbIdx) => {
715
+ const words = tokens.slice(verbIdx + 1).map((w) => stripQuotes(w));
716
+ let sawO = false;
717
+ let pattern = null;
718
+ // GNU grep permutes options after operands (`grep -o 'K=' .env -e '.*'`),
719
+ // so EVERY dash word is validated, not only those before the pattern.
720
+ for (const w of words) {
721
+ if (w.startsWith('-')) {
722
+ if (!/^-[oEFirnHhsIw]+$/.test(w)) return false;
723
+ if (w.includes('o')) sawO = true;
724
+ } else if (pattern === null) pattern = w;
725
+ }
726
+ return sawO && pattern !== null && /^\^?[A-Za-z0-9_]+=$/.test(pattern);
727
+ };
705
728
  const envPipedToCountGrep = (segments, seps, si) => {
706
729
  if (seps[si] !== '|' || si + 1 >= segments.length) return false;
707
- const next = splitShellWords(String(segments[si + 1]).trim()).filter((t) => stripQuotes(t) !== '');
730
+ const next = segmentWords(segments, si + 1);
708
731
  if (!next.length) return false;
709
732
  const nextHead = cleanPathToken(next[0]).replace(/^.*\//, '');
710
- return PATTERN_VERBS.has(nextHead) && isCountOnlyGrep(next, 0);
733
+ if (!PATTERN_VERBS.has(nextHead)) return false;
734
+ return isCountOnlyGrep(next, 0);
711
735
  };
712
736
 
713
737
  const scanBashShapes = (command, depth = 0) => {
@@ -737,9 +761,13 @@ async function evaluate({ rawInput, projectRoot, env }) {
737
761
  if (pi !== -1) skip.add(pi);
738
762
  for (const ri of regexpOperandIndexes(segTokens, 0)) skip.add(ri);
739
763
  }
764
+ // No head is exempt here: digest/metadata verbs (shasum/stat/wc) and
765
+ // `ssh -v -i KEY … 2>&1` all echo the filename, which an outer
766
+ // `cat $(…)` or a later `cat $L` then reads (3.5.19 review rounds 4-5).
740
767
  segTokens.forEach((rawTok, ti) => {
741
768
  if (skip.has(ti)) return;
742
- const cleaned = cleanPathToken(rawTok);
769
+ const files0 = /^--files0-from=(.+)$/.exec(stripQuotes(rawTok));
770
+ const cleaned = cleanPathToken(files0 ? files0[1] : rawTok);
743
771
  const kind = classifySecretFile(cleaned);
744
772
  if (!kind || pathAllowed(cleaned)) return;
745
773
  if (segHead === 'jq' && /^\.env\./.test(cleaned)) {
@@ -916,8 +944,12 @@ async function evaluate({ rawInput, projectRoot, env }) {
916
944
  const patternIdx = isPatternVerb ? patternOperandIndex(tokens, headIdx) : -1;
917
945
  const regexpIdx = isPatternVerb ? regexpOperandIndexes(tokens, headIdx) : new Set();
918
946
  const countOnly = isPatternVerb && isCountOnlyGrep(tokens, headIdx);
947
+ // Literal key-name output is exempt for dotenv files only:
948
+ // key/credential files stay blocked regardless.
949
+ const keyNamesOnly = !countOnly && isPatternVerb && isKeyNameOnlyGrep(tokens, headIdx);
919
950
  for (let k = headIdx + 1; k < tokens.length; k += 1) {
920
951
  if (k === patternIdx || regexpIdx.has(k) || countOnly) continue;
952
+ if (keyNamesOnly && classifySecretFile(cleanPathToken(tokens[k])) === 'dotenv/secret env file') continue;
921
953
  const token = tokens[k];
922
954
  // Attached pattern-file operand (`--file=.env`, `-f.env`) reads that
923
955
  // file: classify the value, not the whole flag word.
@@ -16,6 +16,7 @@ import { spawnSync } from 'node:child_process';
16
16
  const toPosix = (p) => String(p).split(path.sep).join('/').replace(/\\/g, '/');
17
17
  const rel = (root, p) => toPosix(path.isAbsolute(p) ? path.relative(root, p) : p);
18
18
  const readText = (f) => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } };
19
+ const workersOf = (ctx) => (Number.isInteger(ctx.workers) && ctx.workers > 1 ? ctx.workers : 1);
19
20
  const tail = (s, n = 1500) => String(s ?? '').slice(-n);
20
21
 
21
22
  function run(cmd, args, { cwd, env, timeoutMs = 10 * 60 * 1000 } = {}) {
@@ -170,9 +171,13 @@ export function parseJestLikeReport(root, files, json) {
170
171
  const fileErrors = [];
171
172
  const map = { passed: 'passed', failed: 'failed', pending: 'skipped', skipped: 'skipped', todo: 'skipped', disabled: 'skipped' };
172
173
  const seenFiles = new Set();
174
+ // Per-file wall time from the report (planning hint only: it balances batches, never decides a verdict).
175
+ const fileMs = {};
173
176
  for (const suite of json?.testResults ?? []) {
174
177
  const file = rel(root, suite.name);
175
178
  seenFiles.add(file);
179
+ const ms = Number(suite.endTime) - Number(suite.startTime);
180
+ if (Number.isFinite(ms) && ms >= 0) fileMs[file] = Math.round(ms);
176
181
  const asserts = suite.assertionResults ?? [];
177
182
  for (const a of asserts) {
178
183
  const id = `${file} > ${[...(a.ancestorTitles ?? []), a.title].join(' > ')}`;
@@ -183,7 +188,7 @@ export function parseJestLikeReport(root, files, json) {
183
188
  }
184
189
  }
185
190
  for (const f of files) if (!seenFiles.has(f)) fileErrors.push({ file: f, message: 'file missing from the framework report' });
186
- return { results, fileErrors };
191
+ return { results, fileErrors, fileMs };
187
192
  }
188
193
 
189
194
  const vitest = {
@@ -208,7 +213,7 @@ const vitest = {
208
213
  },
209
214
  batchCommand(ctx, files, report) {
210
215
  const bin = nodeBin(ctx, 'vitest', 'vitest.mjs');
211
- return { cmd: bin.cmd, args: [...bin.pre, 'run', ...files, '--reporter=json', `--outputFile=${report}`, '--no-file-parallelism', '--passWithNoTests', ...ctx.extra], env: {} };
216
+ return { cmd: bin.cmd, args: [...bin.pre, 'run', ...files, '--reporter=json', `--outputFile=${report}`, ...(workersOf(ctx) > 1 ? [`--maxWorkers=${workersOf(ctx)}`, '--minWorkers=1'] : ['--no-file-parallelism']), '--passWithNoTests', ...ctx.extra], env: {} };
212
217
  },
213
218
  parseReport(ctx, files, report) {
214
219
  const text = readText(report);
@@ -237,7 +242,7 @@ const jest = {
237
242
  },
238
243
  batchCommand(ctx, files, report) {
239
244
  const bin = nodeBin(ctx, 'jest', path.join('bin', 'jest.js'));
240
- return { cmd: bin.cmd, args: [...bin.pre, '--runInBand', '--json', `--outputFile=${report}`, '--passWithNoTests', ...ctx.extra, '--runTestsByPath', ...files], env: {} };
245
+ return { cmd: bin.cmd, args: [...bin.pre, ...(workersOf(ctx) > 1 ? [`--maxWorkers=${workersOf(ctx)}`] : ['--runInBand']), '--json', `--outputFile=${report}`, '--passWithNoTests', ...ctx.extra, '--runTestsByPath', ...files], env: {} };
241
246
  },
242
247
  parseReport: vitest.parseReport,
243
248
  leakCommand(ctx, file, samples) {
@@ -8,7 +8,7 @@
8
8
  //
9
9
  // Contract (never relaxed):
10
10
  // * Every discovered test file runs. Memory/time thresholds only FLAG; they never skip, filter or kill tests.
11
- // * One batch at a time, one fresh OS process per batch, no parallel workers added by this runner.
11
+ // * One batch at a time, one fresh OS process per batch, in-batch workers only via the `workers` setting (default 1 = serial).
12
12
  // * Batches are whole files (native file paths, never name regexes) so module/file fixtures keep their lifecycle.
13
13
  // * Verdict: PASS only when every inventory test is accounted for, no failure/error, every batch completed and no
14
14
  // guarded path changed. Resource warnings never turn a pass into a failure; an incomplete run is never a pass.
@@ -51,7 +51,7 @@ const toPosix = (p) => String(p).split(path.sep).join('/').replace(/\\/g, '/');
51
51
 
52
52
  export function parseArgs(argv) {
53
53
  const out = { mode: 'run', framework: null, root: null, out: null, json: false, guard: [], changed: false,
54
- batchCases: null, batchFiles: null, heavyMb: null, timeoutMs: null, file: null, python: null,
54
+ batchCases: null, batchFiles: null, workers: null, heavyMb: null, timeoutMs: null, file: null, python: null,
55
55
  resourceWarnings: false, criticalFreeMb: null, extra: [], errors: [] };
56
56
  const num = (flag, v) => { const n = Number(v); if (!Number.isFinite(n) || n <= 0) out.errors.push(`${flag} needs a positive number`); return n; };
57
57
  for (let i = 0; i < argv.length; i += 1) {
@@ -68,6 +68,7 @@ export function parseArgs(argv) {
68
68
  case '--changed': out.changed = true; break;
69
69
  case '--batch-size': out.batchCases = num(a, next()); break;
70
70
  case '--batch-files': out.batchFiles = num(a, next()); break;
71
+ case '--workers': out.workers = Math.floor(num(a, next())); break;
71
72
  case '--heavy-mb': out.heavyMb = num(a, next()); break;
72
73
  case '--timeout-ms': out.timeoutMs = num(a, next()); break;
73
74
  case '--critical-free-mb': { const n = Number(next()); if (!Number.isFinite(n) || n < 0) out.errors.push(`${a} needs a number >= 0`); out.criticalFreeMb = n; break; }
@@ -164,26 +165,68 @@ export function buildInventory(discovered) {
164
165
  // History: .ukit/storage/test-batches/history.json → { files: { "<file>": { isolatedPeakMb, ms } } }.
165
166
  // isolatedPeakMb is recorded ONLY from single-file batches or detect-leaks — a multi-file batch peak is
166
167
  // never attributed to its members.
167
- export function planBatches(inventory, { batchFiles = DEFAULTS.batchFiles, batchCases = null, budgets = BUDGETS, config = {}, history = {}, targetBatchMb = DEFAULTS.targetBatchMb } = {}) {
168
+ export function planBatches(inventory, { batchFiles = DEFAULTS.batchFiles, batchCases = null, budgets = BUDGETS, config = {}, history = {}, targetBatchMb = DEFAULTS.targetBatchMb, workers = 1 } = {}) {
169
+ const W = Number.isInteger(workers) && workers > 1 ? workers : 1;
168
170
  const batches = [];
169
- let cur = null;
170
- const close = () => { if (cur && cur.files.length) batches.push(cur); cur = null; };
171
- for (const file of inventory.files) {
171
+ const info = inventory.files.map((file) => {
172
172
  const category = classifyFile(file, config);
173
- const cases = inventory.caseCounts.get(file);
174
- const caseCap = batchCases ?? budgets[category]?.batch ?? BUDGETS.unit.batch;
175
- const knownMb = history.files?.[file]?.isolatedPeakMb ?? null;
176
- // Measured-heavy and e2e files run alone: no other file shares their process.
177
- const solo = category === 'e2e' || (knownMb != null && knownMb >= targetBatchMb / 2);
178
- if (solo) { close(); batches.push({ files: [file], cases, categories: [category], memMb: knownMb, solo: true }); continue; }
179
- const fits = cur && cur.files.length < batchFiles
180
- && (cases == null || cur.cases == null || cur.cases + cases <= caseCap || cur.files.length === 0)
181
- && (knownMb == null || cur.memMb == null || cur.memMb + knownMb <= targetBatchMb);
182
- if (!fits) { close(); cur = { files: [], cases: cases == null ? null : 0, categories: [], memMb: null, solo: false }; }
183
- cur.files.push(file);
184
- if (cur.cases != null && cases != null) cur.cases += cases; else cur.cases = null;
185
- if (!cur.categories.includes(category)) cur.categories.push(category);
186
- if (knownMb != null) cur.memMb = (cur.memMb ?? 0) + knownMb;
173
+ const hist = history.files?.[file];
174
+ return {
175
+ file, category, cases: inventory.caseCounts.get(file),
176
+ // Case budget is per worker: W workers each run a budget-sized share of the batch.
177
+ caseCap: (batchCases ?? budgets[category]?.batch ?? BUDGETS.unit.batch) * W,
178
+ knownMb: hist?.isolatedPeakMb ?? null,
179
+ ms: Number.isFinite(hist?.ms) ? hist.ms : null,
180
+ };
181
+ });
182
+ const isSolo = (f) => f.category === 'e2e' || (f.knownMb != null && f.knownMb >= targetBatchMb / 2);
183
+ const soloBatch = (f) => ({ files: [f.file], cases: f.cases, categories: [f.category], memMb: f.knownMb, solo: true, ...(W > 1 ? { workers: 1 } : {}) });
184
+ const newBatch = (f) => ({ files: [], cases: f.cases == null ? null : 0, categories: [], memMb: null, solo: false, ms: 0, mems: [] });
185
+ // workers=1 keeps the historical rule (sum of every known peak); workers>1 predicts the peak as the sum of the
186
+ // `workers` largest known peaks, because only that many files execute concurrently.
187
+ const predictedMb = (mems) => (W === 1 ? mems.reduce((x, y) => x + y, 0) : [...mems].sort((x, y) => y - x).slice(0, W).reduce((x, y) => x + y, 0));
188
+ const fits = (cur, f, cap) => cur.files.length < cap
189
+ && (f.cases == null || cur.cases == null || cur.cases + f.cases <= f.caseCap || cur.files.length === 0)
190
+ && (f.knownMb == null || predictedMb([...cur.mems, f.knownMb]) <= targetBatchMb);
191
+ const add = (cur, f) => {
192
+ cur.files.push(f.file);
193
+ if (cur.cases != null && f.cases != null) cur.cases += f.cases; else cur.cases = null;
194
+ if (!cur.categories.includes(f.category)) cur.categories.push(f.category);
195
+ if (f.knownMb != null) { cur.mems.push(f.knownMb); cur.memMb = (cur.memMb ?? 0) + f.knownMb; }
196
+ cur.ms += f.ms ?? 0;
197
+ };
198
+ const finish = (b) => { const { ms, mems, ...rest } = b; return W > 1 ? { ...rest, workers: Math.min(W, b.files.length), ...(ms > 0 ? { estMs: ms } : {}) } : rest; };
199
+ const cap = batchFiles * W;
200
+ const known = info.filter((f) => !isSolo(f) && f.ms != null);
201
+ if (W > 1 && known.length) {
202
+ // Duration-aware packing. Batches run one after another, so a batch costs ~max(longest file, sum/W).
203
+ // Sorting by duration (longest first) and filling each batch with similar-length files lets the long
204
+ // files run CONCURRENTLY in one batch instead of each one becoming its own sequential tail.
205
+ // A batch closes before its work would exceed W lanes as long as its first (longest) file, or on cap/budget/memory.
206
+ const pool = info.filter((f) => !isSolo(f));
207
+ const sorted = known.map((f) => f.ms).sort((x, y) => x - y);
208
+ const median = sorted[Math.floor(sorted.length / 2)];
209
+ const byMs = pool.map((f) => ({ ...f, ms: f.ms ?? median }))
210
+ .sort((x, y) => y.ms - x.ms || (x.file < y.file ? -1 : 1));
211
+ for (const f of info) if (isSolo(f)) batches.push(soloBatch(f));
212
+ let cur = null;
213
+ let lane = 0;
214
+ // Floor so short files are not split into many tiny batches (each fresh process costs ~1 s to start).
215
+ const MIN_BATCH_WORK_MS = 60_000;
216
+ for (const f of byMs) {
217
+ if (cur && (!fits(cur, f, cap) || cur.ms + f.ms > Math.max(lane * W, MIN_BATCH_WORK_MS))) { batches.push(finish(cur)); cur = null; }
218
+ if (!cur) { cur = newBatch(f); lane = f.ms; }
219
+ add(cur, f);
220
+ }
221
+ if (cur && cur.files.length) batches.push(finish(cur));
222
+ return batches.map((b, i) => ({ index: i + 1, ...b }));
223
+ }
224
+ let cur = null;
225
+ const close = () => { if (cur && cur.files.length) batches.push(finish(cur)); cur = null; };
226
+ for (const f of info) {
227
+ if (isSolo(f)) { close(); batches.push(soloBatch(f)); continue; }
228
+ if (!cur || !fits(cur, f, cap)) { close(); cur = newBatch(f); }
229
+ add(cur, f);
187
230
  }
188
231
  close();
189
232
  return batches.map((b, i) => ({ index: i + 1, ...b }));
@@ -224,7 +267,7 @@ export function timeWrapper(platform = process.platform, fileExists = fs.existsS
224
267
 
225
268
  const OUTCOMES = ['passed', 'failed', 'error', 'skipped', 'xfailed', 'xpassed'];
226
269
 
227
- export function aggregate({ inventory, batches, batchResults, guard = null, heavyMb = DEFAULTS.heavyMb, framework, version, runId, startedAt, finishedAt, deferred = null }) {
270
+ export function aggregate({ inventory, batches, batchResults, guard = null, heavyMb = DEFAULTS.heavyMb, framework, version, runId, startedAt, finishedAt, deferred = null, workers = 1 }) {
228
271
  const counts = Object.fromEntries(OUTCOMES.map((o) => [o, 0]));
229
272
  const failedIds = [];
230
273
  const outcomeById = new Map();
@@ -267,7 +310,7 @@ export function aggregate({ inventory, batches, batchResults, guard = null, heav
267
310
  else if (counts.failed || counts.error || fileErrors.length) verdict = 'FAIL';
268
311
  else verdict = 'PASS';
269
312
  return {
270
- runId, framework, frameworkVersion: version ?? null, startedAt, finishedAt,
313
+ runId, framework, frameworkVersion: version ?? null, workers, startedAt, finishedAt,
271
314
  durationMs: finishedAt && startedAt ? Date.parse(finishedAt) - Date.parse(startedAt) : null,
272
315
  inventory: { files: inventory.files.length, tests: total, idLevel: Boolean(inventory.ids), duplicateIds: inventory.duplicates },
273
316
  batches: { planned: batches.length, completed: completed.length, incomplete, notRun },
@@ -390,7 +433,7 @@ export async function runBatch(ctx, adapter, batch, { wrap = timeWrapper() } = {
390
433
  const logFile = path.join(dir, 'output.log');
391
434
  const tmp = path.join(dir, 'tmp');
392
435
  fs.mkdirSync(tmp, { recursive: true });
393
- const command = adapter.batchCommand(ctx, batch.files, report);
436
+ const command = adapter.batchCommand(batch.workers != null ? { ...ctx, workers: batch.workers } : ctx, batch.files, report);
394
437
  const t0 = Date.now();
395
438
  const proc = await spawnBatch({ ...command, env: { ...command.env, UKIT_TEST_TMPDIR: tmp }, cwd: ctx.root, logFile, timeoutMs: ctx.timeoutMs, wrap });
396
439
  const durationMs = Date.now() - t0;
@@ -409,7 +452,7 @@ export async function runBatch(ctx, adapter, batch, { wrap = timeWrapper() } = {
409
452
  index: batch.index, files: batch.files, cases: batch.cases, durationMs, exitCode: proc.code, signal: proc.signal,
410
453
  timedOut: proc.timedOut, complete: !crashed, error: crashed ? (proc.error ?? (proc.timedOut ? `timed out after ${ctx.timeoutMs} ms` : parsed.error ?? `exit ${proc.code}${proc.signal ? ` signal ${proc.signal}` : ''}`)) : null,
411
454
  peakRss, peakRssSource: timeRss != null ? `${wrap.cmd} ${wrap.flag}` : pluginRss != null ? 'in-process ru_maxrss' : 'unknown',
412
- results: parsed.results ?? [], fileErrors: parsed.fileErrors ?? [],
455
+ results: parsed.results ?? [], fileErrors: parsed.fileErrors ?? [], fileMs: parsed.fileMs ?? null,
413
456
  liveThreads: parsed.session?.liveThreads ?? [], liveChildren: parsed.session?.liveChildren ?? [],
414
457
  logTail: crashed ? log.slice(-2000) : undefined,
415
458
  };
@@ -459,6 +502,7 @@ export function makeContext(args, root) {
459
502
  heavyMb: args.heavyMb ?? config.heavyMb ?? DEFAULTS.heavyMb,
460
503
  batchFiles: args.batchFiles ?? config.batchFiles ?? DEFAULTS.batchFiles,
461
504
  batchCases: args.batchCases ?? config.batchCases ?? null,
505
+ workers: (() => { const w = args.workers ?? config.workers ?? 1; return Number.isInteger(w) && w >= 1 ? w : 1; })(),
462
506
  criticalFreeMb: args.criticalFreeMb ?? config.criticalFreeMb ?? DEFAULTS.criticalFreeMb,
463
507
  guard: [...(config.guard ?? []), ...args.guard],
464
508
  };
@@ -468,9 +512,16 @@ export function readHistory(storage) {
468
512
  try { const h = JSON.parse(fs.readFileSync(path.join(storage, 'history.json'), 'utf8')); return h && typeof h === 'object' ? h : { files: {} }; } catch { return { files: {} }; }
469
513
  }
470
514
 
471
- // Only single-file batches give per-file truth; multi-file peaks stay batch-level evidence.
515
+ // Only single-file batches give per-file memory truth; multi-file peaks stay batch-level evidence.
516
+ // Per-file durations come from the framework report of any completed batch (planning hint for balancing).
472
517
  export function updateHistory(history, batchResults) {
473
518
  const next = { files: { ...(history.files ?? {}) }, updatedAt: new Date().toISOString() };
519
+ for (const b of batchResults) {
520
+ if (!b.complete || !b.fileMs) continue;
521
+ for (const [file, ms] of Object.entries(b.fileMs)) {
522
+ if (b.files.includes(file) && Number.isFinite(ms)) next.files[file] = { ...(next.files[file] ?? {}), ms, at: next.updatedAt };
523
+ }
524
+ }
474
525
  for (const b of batchResults) {
475
526
  if (b.complete && b.files.length === 1 && b.peakRss != null) {
476
527
  next.files[b.files[0]] = { isolatedPeakMb: toMb(b.peakRss), ms: b.durationMs, at: next.updatedAt };
@@ -496,7 +547,7 @@ function discoverAndPlan(ctx, adapter) {
496
547
  if (!discovered.ok) return { error: discovered.error, version: discovered.version };
497
548
  const inventory = buildInventory(discovered);
498
549
  const history = readHistory(ctx.storage);
499
- const batches = planBatches(inventory, { batchFiles: ctx.batchFiles, batchCases: ctx.batchCases, budgets: resolveBudgets(ctx.config), config: ctx.config, history });
550
+ const batches = planBatches(inventory, { batchFiles: ctx.batchFiles, batchCases: ctx.batchCases, budgets: resolveBudgets(ctx.config), config: ctx.config, history, workers: ctx.workers });
500
551
  const check = verifyPlan(inventory, batches);
501
552
  if (check.missing.length || check.duplicated.length || check.extra.length) return { error: `internal plan invariant broken: ${JSON.stringify(check)}`, version: discovered.version };
502
553
  return { inventory, batches, version: discovered.version };
@@ -512,7 +563,7 @@ export async function runSuite(ctx, framework, deps = {}) {
512
563
  return { runId: ctx.runId, framework, frameworkVersion: planned.version ?? null, verdict: 'INCOMPLETE', exitCode: EXIT.INCOMPLETE, error: planned.error };
513
564
  }
514
565
  const { inventory, batches } = planned;
515
- fs.writeFileSync(path.join(ctx.runDir, 'manifest.json'), `${JSON.stringify({ framework, files: inventory.files, ids: inventory.ids, batches: batches.map((b) => ({ index: b.index, files: b.files, cases: b.cases })) }, null, 2)}\n`);
566
+ fs.writeFileSync(path.join(ctx.runDir, 'manifest.json'), `${JSON.stringify({ framework, workers: ctx.workers, files: inventory.files, ids: inventory.ids, batches: batches.map((b) => ({ index: b.index, files: b.files, cases: b.cases, ...(b.workers != null ? { workers: b.workers } : {}) })) }, null, 2)}\n`);
516
567
  const guard = ctx.guard.length ? createGuard(ctx.root, ctx.guard) : null;
517
568
  const batchResults = [];
518
569
  let deferred = null;
@@ -523,7 +574,7 @@ export async function runSuite(ctx, framework, deps = {}) {
523
574
  batchResults.push(result);
524
575
  deps.onBatch?.(result, batches.length);
525
576
  }
526
- const summary = aggregate({ inventory, batches, batchResults, guard: guard ? guard.check() : null, heavyMb: ctx.heavyMb, framework, version: planned.version, runId: ctx.runId, startedAt, finishedAt: new Date().toISOString(), deferred });
577
+ const summary = aggregate({ inventory, batches, batchResults, guard: guard ? guard.check() : null, heavyMb: ctx.heavyMb, framework, version: planned.version, runId: ctx.runId, startedAt, finishedAt: new Date().toISOString(), deferred, workers: ctx.workers });
527
578
  if (guard?.truncated) summary.warnings.push({ kind: 'guard-truncated', detail: `guard snapshot capped at ${DEFAULTS.guardMaxEntries} entries — narrow --guard paths` });
528
579
  summary.batchDetail = batchResults.map((b) => ({ index: b.index, files: b.files.length, cases: b.cases, reported: b.results.length, durationMs: b.durationMs, msPerTest: b.msPerTest, peakMb: toMb(b.peakRss), peakSource: b.peakRssSource, complete: b.complete, error: b.error, silentFiles: b.silentFiles }));
529
580
  fs.mkdirSync(ctx.storage, { recursive: true });
@@ -781,6 +832,7 @@ export function renderSummary(s) {
781
832
  L.push(` inventory: ${s.inventory.files} files, ${s.inventory.tests ?? 'n/a (file-level)'} tests · reported ${s.reported}`);
782
833
  L.push(` batches: ${s.batches.completed}/${s.batches.planned} complete${s.batches.incomplete.length ? ` · incomplete #${s.batches.incomplete.join(',#')}` : ''}${s.batches.notRun.length ? ` · not run #${s.batches.notRun.join(',#')}` : ''}`);
783
834
  L.push(` passed ${c.passed} · failed ${c.failed} · error ${c.error} · skipped ${c.skipped} · xfailed ${c.xfailed} · xpassed ${c.xpassed}`);
835
+ L.push(` workers ${s.workers ?? 1}`);
784
836
  L.push(` duration ${Math.round((s.durationMs ?? 0) / 1000)} s · max batch RSS ${s.maxBatchRssMb ?? 'unknown'} MB`);
785
837
  for (const id of s.failedIds.slice(0, 50)) L.push(` FAILED ${id}`);
786
838
  if (s.failedIds.length > 50) L.push(` … ${s.failedIds.length - 50} more failed ids in summary.json`);
@@ -6078,6 +6078,8 @@ async function runEvaluateStop() {
6078
6078
  process.stderr.write(`[ukit-completion] ${result.reason}\n`);
6079
6079
  emit({ systemMessage: advisory ? `${message} ${advisory}` : message,
6080
6080
  ...(result.outcome === 'blocked' || result.outcome === 'handback' ? { outcome: 'blocked', complete: false } : {}),
6081
+ // R6-1: a WAIT release names the pending job/agent so later Stop lanes (mission gate) honour it.
6082
+ ...(result.wait === true && result.waitingOn ? { outcome: 'waiting', complete: false, waitingOn: result.waitingOn } : {}),
6081
6083
  });
6082
6084
  return;
6083
6085
  }
@@ -53,6 +53,19 @@ async function coherentRoutingContext(root, sessionId) {
53
53
  return state.routingContext || {};
54
54
  }
55
55
 
56
+ // Git HEAD sha read straight from .git (no spawn). A commit moves HEAD, which stales prior
57
+ // verification verdicts, so re-verifying after a commit is progress, not a stalled retry.
58
+ async function gitHead(root) {
59
+ try {
60
+ const head = (await fs.readFile(path.join(root, '.git', 'HEAD'), 'utf8')).trim();
61
+ const m = /^ref:\s*(\S+)$/.exec(head);
62
+ if (!m) return head.slice(0, 40);
63
+ try { return (await fs.readFile(path.join(root, '.git', ...m[1].split('/')), 'utf8')).trim().slice(0, 40); } catch {}
64
+ const packed = await fs.readFile(path.join(root, '.git', 'packed-refs'), 'utf8');
65
+ return packed.split('\n').find((l) => l.endsWith(` ${m[1]}`))?.split(' ')[0] || '';
66
+ } catch { return ''; }
67
+ }
68
+
56
69
  export async function progressFingerprint(root, runRoot = root, payload = {}) {
57
70
  let cur = 'no-run';
58
71
  try {
@@ -66,7 +79,7 @@ export async function progressFingerprint(root, runRoot = root, payload = {}) {
66
79
  const led = await readJson(cache(root, path.join('exec-ledger', `${id || 'default'}.json`)), {});
67
80
  const bank = (f) => Object.keys(led[f] && typeof led[f] === 'object' ? led[f] : {}).sort();
68
81
  const rc = await coherentRoutingContext(root, payload.session_id);
69
- return sha(JSON.stringify([cur, bank('bankedWrites'), bank('bankedVerifications'), rc.lastExplicitUserPromptText || '', rc.mutationOrder, rc.planOnly]));
82
+ return sha(JSON.stringify([cur, bank('bankedWrites'), bank('bankedVerifications'), rc.lastExplicitUserPromptText || '', rc.mutationOrder, rc.planOnly, await gitHead(root)]));
70
83
  }
71
84
 
72
85
  // Mode: router-stamped routingContext only.
@@ -142,8 +155,10 @@ export async function applyLoopBreak({ merged, projectRoot, runRoot, payload, se
142
155
  });
143
156
  if (!res?.limitReached) return merged;
144
157
  const minutes = Math.max(0, Math.round((now - res.firstBlockedAt) / 60_000));
158
+ // attemptCount includes the current block, which is released rather than refused.
159
+ const refused = Math.max(1, res.attemptCount - 1);
145
160
  const note = [
146
- `[ukit-loop-breaker] BLOCKED/ESCALATED: ${merged.policyOwner} refused this stop ${res.attemptCount - 1} consecutive times with no change in the work state (~${minutes} min, mode ${mode || 'UNKNOWN'}).`,
161
+ `[ukit-loop-breaker] BLOCKED/ESCALATED: ${merged.policyOwner} refused this stop ${refused} consecutive ${refused === 1 ? 'time' : 'times'} with no change in the work state (~${minutes} min, mode ${mode || 'UNKNOWN'}).`,
147
162
  `Unresolved blocker: ${String(merged.reason || '').split('\n', 1)[0].slice(0, 200)}`,
148
163
  'Stop released. This is NOT approval: completion evidence was not accepted by the blocking policy; this does not mean no verification ran; no safety/permission denial is lifted.',
149
164
  'Report it verbatim; do not retry, wake up, or resume any handoff.',
@@ -40,6 +40,10 @@ export function overlapScore(a, b) {
40
40
 
41
41
  const RE = {
42
42
  question: /^(?:what|how|why|where|when|which|who|whom|is|are|was|were|does|do|did|can|could|should|would|will|la gi|tai sao|nhu the nao|o dau|bao nhieu|co phai|lam sao)\b|\?\s*$/,
43
+ // R6-2: Vietnamese status questions rarely end with '?' — a trailing question particle marks them.
44
+ viQuestionTail: /\b(?:chua|khong|ko|nhi|chua nhi|duoc chua)\s*[?!.]*$/,
45
+ // Progress/status checks are questions even when they name a work verb ("đã fix chưa", "xong tới đâu rồi").
46
+ statusQuestion: /\b(?:da|xong|fix|sua|chay|lam|done)\b.*\bchua\s*[?!.]*$|\b(?:toi dau|den dau|the nao|ra sao|sao) roi\s*[?!.]*$|\btien do\b.*\b(?:roi|the nao|ra sao)\b|\broi sao\s*[?!.]*$|^(?:sao|tai sao) (?:van|lai|chua|khong|ko|con)\b|^(?:is it|are we|is this) (?:done|finished|ready)\b/,
43
47
  imperative: /\b(?:implement|add|fix|create|make|build|change|update|remove|delete|write|refactor|include|replace|rename|move|thay|doi|them|sua|xoa|tao|lam|cap nhat|viet)\b/,
44
48
  supersede: /\b(?:instead of|no longer|rather than|replace|replaced|switch from|change\b.+\bto|thay vi|khong con|doi\b.+\bsang|doi\b.+\bthanh|bo\b.+\bdung)\b/,
45
49
  defect: /\b(?:fix|bug|bugs|broken|crash|crashes|regress\w*|fails?|failing|loi|hong|khong chay|sua loi)\b/,
@@ -55,9 +59,24 @@ const RE = {
55
59
  const FILE_RE = /(?:[\w@.-]+\/)+[\w@.-]+|\b[\w-]+\.(?:mjs|cjs|js|jsx|ts|tsx|json|md|css|scss|html|py|sh|yml|yaml|go|rs|java|sql)\b/g;
56
60
 
57
61
  const cleanFiles = (a) => [...new Set((a || []).map((x) => x.replace(/[.,;:]+$/, '')))];
62
+ // A status check only owns the segment when no other clause carries a work request:
63
+ // "da fix chua?" is a question, "them nut export, chay test chua" is still work.
64
+ // Clauses split on punctuation and conjunctions; a clause is a work order only when it
65
+ // STARTS with an imperative verb ("sua login", "them nut export") — "da sua" (past marker)
66
+ // reports status, so "da sua va chay test chua" stays a question.
67
+ const CLAUSE_SPLIT = /\s*[,;]\s*|\s+(?:va|roi|and|then|thi|sau do)\s+/;
68
+ const IMPERATIVE_START = new RegExp(`^(?:(?:please|hay|giup|lam on|ok|oke|cu|tiep tuc)\\s+)*${RE.imperative.source}`);
69
+ function isStatusQuestion(f) {
70
+ if (!RE.statusQuestion.test(f)) return false;
71
+ const clauses = f.split(CLAUSE_SPLIT).map((c) => c.trim()).filter(Boolean);
72
+ if (clauses.length < 2) return true;
73
+ return !clauses.some((c) => !RE.statusQuestion.test(c) && IMPERATIVE_START.test(c));
74
+ }
75
+
58
76
  function kindOf(segment) {
59
77
  const f = foldText(segment);
60
- if (RE.question.test(f) && !RE.imperative.test(f)) return 'question';
78
+ if (isStatusQuestion(f)) return 'question';
79
+ if ((RE.question.test(f) || RE.viQuestionTail.test(f)) && !RE.imperative.test(f)) return 'question';
61
80
  if (RE.prohibition.test(f)) return 'prohibition';
62
81
  if (RE.defect.test(f)) return 'defect';
63
82
  if (RE.test.test(f)) return 'test';
@@ -1471,22 +1471,32 @@ export function isVerbatimOutputCommand(command) {
1471
1471
  // monotonically) up to RANKED_TABLE_MAX_TOKENS passes through raw. The configured
1472
1472
  // outputMaxTokens budget still governs every other output.
1473
1473
  const RANKED_TABLE_MAX_TOKENS = 6000;
1474
- const RANKED_LINE_RE = /^\s*(\d+(?:\.\d+)?)(?:\s|[:|,x×]|$)/;
1474
+ // R6-10: a rank prefix `N.` / `N)` counts too (" 1. 38 class…"), and a multi-section report
1475
+ // (sections split by non-numbered header lines, numbering restarting per section) is ranked when
1476
+ // every contiguous numbered run is itself monotonic.
1477
+ const RANKED_LINE_RE = /^\s*(\d+(?:\.\d+)?)(?:\s|[:|,x×.)]|$)/;
1475
1478
  export function isPassThroughOutput(text) {
1476
1479
  const lines = String(text ?? '').split('\n').filter((l) => l.trim());
1477
1480
  if (estimateTokenCount(String(text ?? '')) > RANKED_TABLE_MAX_TOKENS) return false;
1478
- const nums = [];
1481
+ const runs = [];
1482
+ let run = null;
1483
+ let numbered = 0;
1479
1484
  for (const line of lines) {
1480
1485
  const m = RANKED_LINE_RE.exec(stripAnsi(line));
1481
- if (m) nums.push(Number(m[1]));
1482
- }
1483
- if (nums.length < 8 || nums.length < lines.length * 0.6) return false;
1484
- let asc = true; let desc = true;
1485
- for (let i = 1; i < nums.length; i += 1) {
1486
- if (nums[i] < nums[i - 1]) asc = false;
1487
- if (nums[i] > nums[i - 1]) desc = false;
1488
- }
1489
- return asc || desc;
1486
+ if (!m) { run = null; continue; }
1487
+ if (!run) { run = []; runs.push(run); }
1488
+ run.push(Number(m[1]));
1489
+ numbered += 1;
1490
+ }
1491
+ if (numbered < 8 || numbered < lines.length * 0.6) return false;
1492
+ return runs.every((nums) => {
1493
+ let asc = true; let desc = true;
1494
+ for (let i = 1; i < nums.length; i += 1) {
1495
+ if (nums[i] < nums[i - 1]) asc = false;
1496
+ if (nums[i] > nums[i - 1]) desc = false;
1497
+ }
1498
+ return asc || desc;
1499
+ });
1490
1500
  }
1491
1501
 
1492
1502
  function mergeDeep(base, override) {
@@ -105,12 +105,28 @@ function selfTree(rows, selfPid) {
105
105
  return set;
106
106
  }
107
107
 
108
+ // Agent host processes (Claude Code / codex / omp). A shell whose ancestor chain reaches a live
109
+ // host outside our own tree belongs to ANOTHER live session: never kill or report it.
110
+ const HOST_RE = /^(?:\S*\/)?(?:claude|codex|omp)(?:\s|$)|^(?:\S*\/)?node\s+(?:\S+\s+)*\S*\/(?:claude|codex|omp)(?:\.m?js)?(?:\s|$)/;
111
+ function ownedByOtherLiveHost(row, byPid, selfSet) {
112
+ for (let p = row.ppid, n = 0; p > 1 && n < 64; n += 1) {
113
+ if (selfSet.has(p)) return false;
114
+ const a = byPid.get(p);
115
+ if (!a) return false;
116
+ if (HOST_RE.test(a.command.trimStart())) return true;
117
+ p = a.ppid;
118
+ }
119
+ return false;
120
+ }
121
+
108
122
  /** Pure classification of ps rows -> [{ kind, pid, ageMin, text, deterministic }]. */
109
123
  export function classifyShells(rows, { staleMinutes, uid = null, selfPid = process.pid }) {
110
124
  const selfSet = selfTree(rows, selfPid);
125
+ const byPid = new Map(rows.map((r) => [r.pid, r]));
111
126
  const out = [];
112
127
  for (const row of rows) {
113
128
  if (excluded(row, selfSet, uid)) continue;
129
+ if (ownedByOtherLiveHost(row, byPid, selfSet)) continue; // another live session's shell: skip, never kill
114
130
  const cmd = row.command;
115
131
  const isShell = SHELL_C_RE.test(cmd) || cmd.includes(SNAPSHOT_MARKER);
116
132
  const old = row.ageMin >= staleMinutes;
@@ -247,6 +247,8 @@ export function normalizeEvaluatorStdout(stdout) {
247
247
  if (parsed && typeof parsed.systemMessage === 'string' && parsed.systemMessage) {
248
248
  return { kind: 'advisory', systemMessage: parsed.systemMessage,
249
249
  ...(parsed.outcome === 'blocked' && parsed.complete === false ? { outcome: 'blocked', complete: false } : {}),
250
+ ...(parsed.outcome === 'waiting' && parsed.complete === false && typeof parsed.waitingOn === 'string' && parsed.waitingOn
251
+ ? { outcome: 'waiting', complete: false, waitingOn: parsed.waitingOn.slice(0, 80) } : {}),
250
252
  };
251
253
  }
252
254
  // A message-less non-completion release (the finite handback was already delivered) is never a pass.
@@ -374,6 +376,7 @@ export function coordinateStopDecisions({ completion = null, watchdog = null, ha
374
376
  policyOwner: 'none',
375
377
  policies,
376
378
  ...(completion?.outcome === 'blocked' && completion?.complete === false ? { blockedOutcome: true } : {}),
379
+ ...(completion?.outcome === 'waiting' && completion?.waitingOn ? { waitingOn: completion.waitingOn } : {}),
377
380
  };
378
381
  }
379
382
 
@@ -2631,7 +2634,22 @@ const RESUME_RE = new RegExp(
2631
2634
  'iu',
2632
2635
  );
2633
2636
  const SYNTHETIC_USER_PREFIX = /^(?:<system-reminder|<task-notification|<local-command|<user-prompt-submit-hook|Stop hook feedback|\[ukit|Caveat:|\[Request interrupted)/i;
2634
- const RESUME_COMMAND_TAG = /^<command-name>\/?(?:ukit:)?handoff-(?:fullstack|implement)(?![\w-])/;
2637
+ // Lazy: the mission classifier is optional for this module (partial installs / sandboxes); without it a
2638
+ // trailing '?' is the only question signal.
2639
+ let classifyPromptFn;
2640
+ async function loadClassifyPrompt() {
2641
+ if (classifyPromptFn === undefined) {
2642
+ try { classifyPromptFn = (await import('./mission/classify.mjs')).classifyPrompt || null; } catch { classifyPromptFn = null; }
2643
+ }
2644
+ return classifyPromptFn;
2645
+ }
2646
+ async function isReadOnlyOwnerQuestion(text) {
2647
+ const classify = await loadClassifyPrompt();
2648
+ if (typeof classify !== 'function') return /\?\s*$/.test(text);
2649
+ try { return classify({ text }).relation?.type === 'question'; } catch { return false; }
2650
+ }
2651
+ const PEER_ENVELOPE_START =/^(?:Another Claude session sent a message|<(?:agent|teammate)-message[\s>])/;
2652
+ const RESUME_COMMAND_TAG =/^<command-name>\/?(?:ukit:)?handoff-(?:fullstack|implement)(?![\w-])/;
2635
2653
 
2636
2654
  function genuineUserText(entry) {
2637
2655
  if (!entry || entry.type !== 'user' || entry.isSidechain === true || entry.isMeta === true) return null;
@@ -2693,10 +2711,18 @@ export async function detectUserInterruption(transcriptPath, {
2693
2711
  const text = genuineUserText(entry);
2694
2712
  if (text === null) continue;
2695
2713
  if (RESUME_COMMAND_TAG.test(text)) return { kind: null };
2696
- if (text.length > INTERRUPT_MAX_TEXT) continue;
2697
- if (CANCEL_RE.test(text)) return { kind: 'cancel' };
2698
- if (PAUSE_RE.test(text)) return { kind: 'pause' };
2699
- if (RESUME_RE.test(text)) return { kind: null };
2714
+ // Peer-envelope-shaped text (merged peer block) is not a decisive owner turn: keep scanning.
2715
+ if (PEER_ENVELOPE_START.test(text)) continue;
2716
+ if (text.length <= INTERRUPT_MAX_TEXT) {
2717
+ if (CANCEL_RE.test(text)) return { kind: 'cancel' };
2718
+ if (PAUSE_RE.test(text)) return { kind: 'pause' };
2719
+ if (RESUME_RE.test(text)) return { kind: null };
2720
+ }
2721
+ // R6-7: a read-only question during a pause ("health check: is everything ok?") keeps the pause;
2722
+ // any later owner WORK request (long or short) supersedes an older pause/cancel — one "dừng đi"
2723
+ // must not release every later stop of the session.
2724
+ if (await isReadOnlyOwnerQuestion(text)) continue;
2725
+ return { kind: null };
2700
2726
  }
2701
2727
  return { kind: null };
2702
2728
  } catch {
@@ -3178,6 +3204,11 @@ export async function evaluateMissionGate({ merged, projectRoot, payload = {}, o
3178
3204
  const g = await gm.loadGraph({ projectRoot, missionId: mid });
3179
3205
  const live = (r) => (r.status === 'active' || r.status === 'conflict') && r.kind !== 'question';
3180
3206
  if (!Object.values(g.state.reqs).some(live)) return merged;
3207
+ // R6-1: the completion gate released this Stop as a WAIT on a pending host background job/agent.
3208
+ // Blocking cannot produce that result, so the mission gate releases too (advisory, no block budget).
3209
+ if (typeof merged.waitingOn === 'string' && merged.waitingOn) {
3210
+ return { ...merged, systemMessage: [merged.systemMessage, `[ukit-mission] waiting on ${merged.waitingOn}; the mission continues when its task-notification arrives (not completion).`].filter(Boolean).join('\n') };
3211
+ }
3181
3212
 
3182
3213
  // Ledger evidence: a passing verification receipt newer than the task's done claim verifies its ACs.
3183
3214
  const receipt = await newestPassingVerification(projectRoot);
@@ -93,7 +93,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
93
93
  <!-- RULES: BUDGET-02 BUDGET-03 -->
94
94
  - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
95
95
  <!-- RULE: TEST-01 -->
96
- - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never add parallel workers or launch a second copy. Targeted 1-3 file runs use the bare runner directly.
96
+ - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never launch a second copy or add your own parallel workers; in-batch workers come only from the runner's `workers` setting. Targeted 1-3 file runs use the bare runner directly.
97
97
  - **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
98
98
  - **No hung shells:** a `[ukit-shell-watch] ACTION` line means kill the listed hung shells/stalled tasks and finish their work before the new prompt. Hookless engines (Codex): check `ps` for stale agent shells at the start of each prompt. Wait loops poll a pidfile / `kill -0 <pid>`, never a self-matching `pgrep -f`.
99
99
 
@@ -93,7 +93,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
93
93
  <!-- RULES: BUDGET-02 BUDGET-03 -->
94
94
  - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
95
95
  <!-- RULE: TEST-01 -->
96
- - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never add parallel workers or launch a second copy. Targeted 1-3 file runs use the bare runner directly.
96
+ - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never launch a second copy or add your own parallel workers; in-batch workers come only from the runner's `workers` setting. Targeted 1-3 file runs use the bare runner directly.
97
97
  - **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
98
98
  - **No hung shells:** a `[ukit-shell-watch] ACTION` line means kill the listed hung shells/stalled tasks and finish their work before the new prompt. Hookless engines (Codex): check `ps` for stale agent shells at the start of each prompt. Wait loops poll a pidfile / `kill -0 <pid>`, never a self-matching `pgrep -f`.
99
99
 
@@ -90,7 +90,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
90
90
  <!-- RULES: BUDGET-02 BUDGET-03 -->
91
91
  - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
92
92
  <!-- RULE: TEST-01 -->
93
- - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never add parallel workers or launch a second copy. Targeted 1-3 file runs use the bare runner directly.
93
+ - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never launch a second copy or add your own parallel workers; in-batch workers come only from the runner's `workers` setting. Targeted 1-3 file runs use the bare runner directly.
94
94
  - **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
95
95
  - **No hung shells:** a `[ukit-shell-watch] ACTION` line means kill the listed hung shells/stalled tasks and finish their work before the new prompt. Hookless engines (Codex): check `ps` for stale agent shells at the start of each prompt. Wait loops poll a pidfile / `kill -0 <pid>`, never a self-matching `pgrep -f`.
96
96