@ngockhoale/ukit 3.5.13 → 3.5.14

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.
@@ -497,28 +497,265 @@ async function evaluate({ rawInput, projectRoot, env }) {
497
497
  return bodies;
498
498
  };
499
499
 
500
+ // Field-telemetry #4 (2026-11-20): quote/substitution/heredoc-aware split of
501
+ // a command into its top-level list segments. The old
502
+ // `command.split(/\|\||&&|;|\||\n/)` cut INSIDE quotes, so `grep -E
503
+ // "release|history"` produced a bare `history` segment, and heredoc body
504
+ // lines were parsed as commands. Returns the segments, the command text with
505
+ // heredoc bodies removed, and the bodies of UNQUOTED heredocs (where `$(…)`
506
+ // still expands); quoted-delimiter heredoc bodies (`<<'EOF'`) are literal
507
+ // data and dropped. Unbalanced input consumes the rest of the text (bash
508
+ // would reject it; the scan stays pessimistic, never skips content).
509
+ const skipBalancedSubst = (src, i) => {
510
+ // src[i] === '$' && src[i+1] === '(' -> index after the matching ')'.
511
+ let d = 1;
512
+ let j = i + 2;
513
+ while (j < src.length && d > 0) {
514
+ const b = src[j];
515
+ if (b === '\\') { j += 2; continue; }
516
+ if (b === "'") { const e = src.indexOf("'", j + 1); j = e === -1 ? src.length : e + 1; continue; }
517
+ if (b === '"') {
518
+ j += 1;
519
+ while (j < src.length && src[j] !== '"') {
520
+ if (src[j] === '\\') { j += 2; continue; }
521
+ if (src[j] === '$' && src[j + 1] === '(') { j = skipBalancedSubst(src, j); continue; }
522
+ j += 1;
523
+ }
524
+ j += 1;
525
+ continue;
526
+ }
527
+ if (b === '`') { const e = src.indexOf('`', j + 1); j = e === -1 ? src.length : e + 1; continue; }
528
+ if (b === '(') d += 1;
529
+ else if (b === ')') d -= 1;
530
+ j += 1;
531
+ }
532
+ return Math.min(j, src.length);
533
+ };
534
+ const splitTopLevel = (command) => {
535
+ const src = String(command ?? '');
536
+ const segments = [];
537
+ const heredocBodies = [];
538
+ let stripped = '';
539
+ let cur = '';
540
+ const seps = []; // separator FOLLOWING each segment ('|', '||', ';', '&&', '&', '\n', '')
541
+ const pending = []; // { delim, quoted, stripTabs }
542
+ const push = (sep = '') => { segments.push(cur); seps.push(sep); cur = ''; };
543
+ let i = 0;
544
+ while (i < src.length) {
545
+ const ch = src[i];
546
+ if (ch === '\\') { const s = src.slice(i, i + 2); cur += s; stripped += s; i += 2; continue; }
547
+ if (ch === "'") {
548
+ const e = src.indexOf("'", i + 1);
549
+ const end = e === -1 ? src.length : e + 1;
550
+ cur += src.slice(i, end); stripped += src.slice(i, end); i = end; continue;
551
+ }
552
+ if (ch === '"') {
553
+ let j = i + 1;
554
+ while (j < src.length && src[j] !== '"') {
555
+ if (src[j] === '\\') { j += 2; continue; }
556
+ if (src[j] === '$' && src[j + 1] === '(') { j = skipBalancedSubst(src, j); continue; }
557
+ if (src[j] === '`') { const e = src.indexOf('`', j + 1); j = e === -1 ? src.length : e + 1; continue; }
558
+ j += 1;
559
+ }
560
+ const end = Math.min(j + 1, src.length);
561
+ cur += src.slice(i, end); stripped += src.slice(i, end); i = end; continue;
562
+ }
563
+ if (ch === '`') {
564
+ const e = src.indexOf('`', i + 1);
565
+ const end = e === -1 ? src.length : e + 1;
566
+ cur += src.slice(i, end); stripped += src.slice(i, end); i = end; continue;
567
+ }
568
+ if (ch === '$' && src[i + 1] === '(') {
569
+ const end = skipBalancedSubst(src, i);
570
+ cur += src.slice(i, end); stripped += src.slice(i, end); i = end; continue;
571
+ }
572
+ if (ch === '<' && src[i + 1] === '<' && src[i + 2] !== '<') {
573
+ // Heredoc operator: record the delimiter; the body starts after the
574
+ // next unquoted newline.
575
+ let j = i + 2;
576
+ const stripTabs = src[j] === '-';
577
+ if (stripTabs) j += 1;
578
+ while (src[j] === ' ' || src[j] === '\t') j += 1;
579
+ const wordStart = j;
580
+ while (j < src.length && !/[\s;&|<>()]/.test(src[j])) {
581
+ if (src[j] === "'") { const e = src.indexOf("'", j + 1); j = e === -1 ? src.length : e + 1; continue; }
582
+ if (src[j] === '"') { const e = src.indexOf('"', j + 1); j = e === -1 ? src.length : e + 1; continue; }
583
+ if (src[j] === '\\') { j += 2; continue; }
584
+ j += 1;
585
+ }
586
+ const word = src.slice(wordStart, j);
587
+ if (word) {
588
+ pending.push({ delim: stripQuotes(word), quoted: /["'\\]/.test(word), stripTabs });
589
+ }
590
+ cur += src.slice(i, j); stripped += src.slice(i, j); i = j; continue;
591
+ }
592
+ if (ch === '\n') {
593
+ push('\n');
594
+ stripped += '\n';
595
+ i += 1;
596
+ // Consume heredoc bodies, in operator order, line by line.
597
+ while (pending.length) {
598
+ const doc = pending.shift();
599
+ const bodyLines = [];
600
+ let closed = false;
601
+ while (i < src.length) {
602
+ const nl = src.indexOf('\n', i);
603
+ const lineEnd = nl === -1 ? src.length : nl;
604
+ const line = src.slice(i, lineEnd);
605
+ i = nl === -1 ? src.length : nl + 1;
606
+ const cmp = doc.stripTabs ? line.replace(/^\t+/, '') : line;
607
+ if (cmp === doc.delim) { closed = true; break; }
608
+ bodyLines.push(line);
609
+ }
610
+ if (!doc.quoted) heredocBodies.push(bodyLines.join('\n'));
611
+ if (!closed) break;
612
+ }
613
+ continue;
614
+ }
615
+ if (ch === ';' || ch === '|') {
616
+ const two = src[i + 1] === ch || (ch === '|' && src[i + 1] === '&');
617
+ push(two ? ch + src[i + 1] : ch);
618
+ stripped += ch;
619
+ i += two ? 2 : 1;
620
+ continue;
621
+ }
622
+ if (ch === '&') {
623
+ const prev = src[i - 1];
624
+ if (src[i + 1] === '&') { push('&&'); stripped += '&&'; i += 2; continue; }
625
+ // `2>&1`, `&>file`, `>&2` are redirects, not list separators.
626
+ if (prev !== '>' && prev !== '<' && src[i + 1] !== '>') { push('&'); stripped += '&'; i += 1; continue; }
627
+ }
628
+ cur += ch; stripped += ch; i += 1;
629
+ }
630
+ push();
631
+ return { segments, seps, stripped, heredocBodies };
632
+ };
633
+
634
+ // grep-family verbs: the first positional operand is the PATTERN (unless
635
+ // -e/-f/--regexp/--file supplied it), never a file. `grep -v "^./\.env"`
636
+ // reads stdin. `-f FILE` / `--file=FILE` does read FILE, so it stays
637
+ // classified like any file operand.
638
+ const PATTERN_VERBS = new Set(['grep', 'egrep', 'fgrep', 'rg', 'zgrep']);
639
+ const PATTERN_FLAG_OPERANDS = new Set([
640
+ '-A', '-B', '-C', '-m', '-d', '-D', '-g', '-t', '-T', '-M', '-j',
641
+ '--include', '--exclude', '--exclude-dir', '--glob', '--type', '--type-not',
642
+ '--max-count', '--context', '--after-context', '--before-context',
643
+ ]);
644
+ const patternOperandIndex = (tokens, verbIdx) => {
645
+ let explicit = false;
646
+ let firstPositional = -1;
647
+ let endOfFlags = false;
648
+ for (let k = verbIdx + 1; k < tokens.length; k += 1) {
649
+ const t = stripQuotes(tokens[k]);
650
+ if (!endOfFlags && t === '--') { endOfFlags = true; continue; }
651
+ if (!endOfFlags && t.startsWith('-') && t.length > 1) {
652
+ if (/^--(regexp|file)(=|$)/.test(t) || /^-[^-]*[ef]/.test(t)) explicit = true;
653
+ // -e PATTERN as a separate word: that word is a pattern, skip it.
654
+ // Flags whose operand is a separate word (`-A 3`, `rg -g '*.ts'`)
655
+ // also consume it, so the operand is never mistaken for the pattern.
656
+ if (/^(-[^-]*e|--regexp)$/.test(t) || PATTERN_FLAG_OPERANDS.has(t)) k += 1;
657
+ continue;
658
+ }
659
+ if (firstPositional === -1) firstPositional = k;
660
+ }
661
+ return explicit ? -1 : firstPositional;
662
+ };
663
+ const regexpOperandIndexes = (tokens, verbIdx) => {
664
+ const idx = new Set();
665
+ for (let k = verbIdx + 1; k < tokens.length; k += 1) {
666
+ const t = stripQuotes(tokens[k]);
667
+ if (t === '--') break;
668
+ if (/^(-[^-]*e|--regexp)$/.test(t)) { idx.add(k + 1); k += 1; }
669
+ }
670
+ return idx;
671
+ };
672
+
673
+ const JQ_SECRET_FIELD_RE = /(token|secret|password|passwd|api[_-]?key|auth|credential|private)/i;
674
+ // Count-only / list-only grep flags (-c, -q, -l, -L, --count, --quiet,
675
+ // --files-with-matches) print a number or file names, never matched text.
676
+ // `-o`/`-n`/`-h` and friends are NOT in this set, so `grep -oE '^KEY_' .env`
677
+ // stays blocked (it prints key names/values).
678
+ // Only REAL flag words count: the operand of -e/--regexp and of operand-taking
679
+ // flags (-A/-m/...) is skipped, so `grep -e -c -e . .env` is not count-only.
680
+ // Any value-printing flag (-o/-n/-b/-A/-B/-C/-f, --only-matching, ...) next to
681
+ // -c/-l/-q disqualifies the call: the guard stays conservative.
682
+ const VALUE_PRINT_LONG_RE = /^--(only-matching|line-number|byte-offset|context|after-context|before-context|file|replace|passthru|json|vimgrep)(=|$)/;
683
+ const isCountOnlyGrep = (tokens, verbIdx) => {
684
+ let countOnly = false;
685
+ for (let k = verbIdx + 1; k < tokens.length; k += 1) {
686
+ const t = stripQuotes(tokens[k]);
687
+ if (t === '--') break;
688
+ if (!t.startsWith('-') || t.length < 2) continue;
689
+ if (/^(-[^-]*e|--regexp)$/.test(t) || PATTERN_FLAG_OPERANDS.has(t)) { k += 1; }
690
+ if (t.startsWith('--')) {
691
+ if (VALUE_PRINT_LONG_RE.test(t)) return false;
692
+ if (/^--(count|quiet|silent|files-with-matches|files-without-match)$/.test(t)) countOnly = true;
693
+ continue;
694
+ }
695
+ // Short cluster: letters up to the first operand-taking letter are flags;
696
+ // the rest of the word is that flag's attached operand.
697
+ const flags = t.slice(1).replace(/([efmABCdDgtTMj]).*$/, '$1');
698
+ if (/[onbABCf]/.test(flags)) return false;
699
+ if (/[cqlL]/.test(flags)) countOnly = true;
700
+ }
701
+ return countOnly;
702
+ };
703
+ // `env | grep -c X` / `printenv | grep -q X`: decided per segment — only an
704
+ // env/printenv segment whose OWN pipe feeds a count-only grep is exempt.
705
+ const envPipedToCountGrep = (segments, seps, si) => {
706
+ if (seps[si] !== '|' || si + 1 >= segments.length) return false;
707
+ const next = splitShellWords(String(segments[si + 1]).trim()).filter((t) => stripQuotes(t) !== '');
708
+ if (!next.length) return false;
709
+ const nextHead = cleanPathToken(next[0]).replace(/^.*\//, '');
710
+ return PATTERN_VERBS.has(nextHead) && isCountOnlyGrep(next, 0);
711
+ };
712
+
500
713
  const scanBashShapes = (command, depth = 0) => {
501
714
  const found = [];
715
+ const { segments, seps, stripped, heredocBodies } = splitTopLevel(command);
502
716
  // Substitution bodies are extracted BEFORE segment splitting — a `;`
503
717
  // inside `$(…)` belongs to the substitution, not the top level. Each body
504
718
  // is scanned recursively AND its words are classified directly: `cat
505
719
  // $(echo .env)` produces the file via substitution, a route no segment
506
- // split can see.
720
+ // split can see. Quoted heredoc bodies are literal (already dropped);
721
+ // unquoted heredoc bodies still expand `$(…)`/backticks, and quotes there
722
+ // are literal characters, so they are neutralised before extraction.
723
+ const substSources = [stripped, ...heredocBodies.map((b) => b.replace(/["']/g, ' '))];
507
724
  if (depth < MAX_SUBST_DEPTH) {
508
- for (const body of extractSubstBodies(command)) {
725
+ for (const body of substSources.flatMap((s) => extractSubstBodies(s))) {
509
726
  for (const inner of scanBashShapes(body, depth + 1)) found.push(inner);
510
- for (const rawTok of splitShellWords(body)) {
511
- const cleaned = cleanPathToken(rawTok);
512
- const kind = classifySecretFile(cleaned);
513
- if (kind && !pathAllowed(cleaned)) {
514
- found.push({ label: `${kind} referenced in command substitution`, value: cleaned, isPath: true });
727
+ // Per segment: a grep-family PATTERN operand (`grep -x id_rsa`,
728
+ // `grep -E "^\.env"`) is a regexp, not a file; a `jq` path
729
+ // (`.env.FOO`) is a JSON path, not a dotenv file.
730
+ for (const bodySeg of splitTopLevel(body).segments) {
731
+ const segTokens = splitShellWords(bodySeg.trim()).filter((t) => stripQuotes(t) !== '');
732
+ if (!segTokens.length) continue;
733
+ const segHead = cleanPathToken(segTokens[0]).replace(/^.*\//, '');
734
+ const skip = new Set();
735
+ if (PATTERN_VERBS.has(segHead)) {
736
+ const pi = patternOperandIndex(segTokens, 0);
737
+ if (pi !== -1) skip.add(pi);
738
+ for (const ri of regexpOperandIndexes(segTokens, 0)) skip.add(ri);
515
739
  }
740
+ segTokens.forEach((rawTok, ti) => {
741
+ if (skip.has(ti)) return;
742
+ const cleaned = cleanPathToken(rawTok);
743
+ const kind = classifySecretFile(cleaned);
744
+ if (!kind || pathAllowed(cleaned)) return;
745
+ if (segHead === 'jq' && /^\.env\./.test(cleaned)) {
746
+ // jq path into a JSON document: only credential-named fields matter.
747
+ if (JQ_SECRET_FIELD_RE.test(cleaned)) {
748
+ found.push({ label: 'jq path reads a credential field of a JSON document referenced in command substitution', value: cleaned, isPath: true });
749
+ }
750
+ return;
751
+ }
752
+ found.push({ label: `${kind} referenced in command substitution`, value: cleaned, isPath: true });
753
+ });
516
754
  }
517
755
  }
518
756
  }
519
- const segments = command.split(/\|\||&&|;|\||\n/);
520
- for (const rawSegment of segments) {
521
- const segment = rawSegment.trim();
757
+ for (let si = 0; si < segments.length; si += 1) {
758
+ const segment = segments[si].trim();
522
759
  if (!segment) continue;
523
760
  // Shell word semantics: whitespace AND `<`/`>` split words, quoted runs
524
761
  // (`"a b"`), escapes and `${IFS}` separators behave like the shell —
@@ -536,6 +773,7 @@ async function evaluate({ rawInput, projectRoot, env }) {
536
773
  const unquote = stripQuotes;
537
774
 
538
775
  if ((head === 'env' || head === 'printenv' || head === 'history') && tokens.length === 1) {
776
+ if (head !== 'history' && envPipedToCountGrep(segments, seps, si)) continue;
539
777
  found.push({ label: `bare \`${head}\` dumps environment/history (may contain tokens)`, value: segment });
540
778
  continue;
541
779
  }
@@ -674,8 +912,19 @@ async function evaluate({ rawInput, projectRoot, env }) {
674
912
  const headBase = effectiveHead.replace(/^.*\//, '');
675
913
 
676
914
  if (DUMP_VERBS.has(headBase)) {
677
- for (const token of tokens.slice(headIdx + 1)) {
678
- const cleaned = cleanPathToken(token);
915
+ const isPatternVerb = PATTERN_VERBS.has(headBase);
916
+ const patternIdx = isPatternVerb ? patternOperandIndex(tokens, headIdx) : -1;
917
+ const regexpIdx = isPatternVerb ? regexpOperandIndexes(tokens, headIdx) : new Set();
918
+ const countOnly = isPatternVerb && isCountOnlyGrep(tokens, headIdx);
919
+ for (let k = headIdx + 1; k < tokens.length; k += 1) {
920
+ if (k === patternIdx || regexpIdx.has(k) || countOnly) continue;
921
+ const token = tokens[k];
922
+ // Attached pattern-file operand (`--file=.env`, `-f.env`) reads that
923
+ // file: classify the value, not the whole flag word.
924
+ const attachedFile = isPatternVerb
925
+ ? /^(?:--file=|-[^-]*f)(.+)$/.exec(stripQuotes(token))
926
+ : null;
927
+ const cleaned = cleanPathToken(attachedFile ? attachedFile[1] : token);
679
928
  const kind = classifySecretFile(cleaned);
680
929
  if (kind && !pathAllowed(cleaned)) {
681
930
  found.push({ label: `${effectiveHead} reads ${kind}`, value: cleaned, isPath: true });
@@ -789,6 +1038,41 @@ async function evaluate({ rawInput, projectRoot, env }) {
789
1038
  return verdict && Array.isArray(verdict.labels) ? verdict.labels : [];
790
1039
  };
791
1040
 
1041
+ // Fixture/doc keys in a Bash command (heredoc test files, `memory propose`
1042
+ // examples) are not secrets: gitleaks/trufflehog ship the same kind of
1043
+ // stopword/placeholder allowlist. A vendor-shaped match whose body holds an
1044
+ // alphabet/digit run or an obvious placeholder word is neutralised before the
1045
+ // scan; random-looking keys are untouched. Bash channel only.
1046
+ const PLACEHOLDER_KEY_RE = /\b(?:sk-|gh[pousr]_)[A-Za-z0-9_-]{20,}/g;
1047
+ const PLACEHOLDER_WORD_RE = /(claude|secret|canary|example|sample|fake|dummy|placeholder|redacted|changeme|your[_-]?key|x{6,})/gi;
1048
+ // A placeholder word must be a real share of the body (>= 1/4), so a random
1049
+ // key that merely contains "secret" somewhere is not exempted.
1050
+ const placeholderShare = (body) => (body.match(PLACEHOLDER_WORD_RE) || []).join('').length / Math.max(1, body.length);
1051
+ // Longest ascending alphabet/digit run (a-b-c-d..., 1-2-3-4...) in a key body.
1052
+ const longestSequentialRun = (body) => {
1053
+ const lower = body.toLowerCase();
1054
+ let run = 1;
1055
+ let best = 1;
1056
+ for (let i = 1; i < lower.length; i += 1) {
1057
+ const sameClass = /[a-z]/.test(lower[i]) === /[a-z]/.test(lower[i - 1]);
1058
+ run = lower.charCodeAt(i) - lower.charCodeAt(i - 1) === 1 && sameClass && /[a-z0-9]/.test(lower[i]) ? run + 1 : 1;
1059
+ if (run > best) best = run;
1060
+ }
1061
+ return best;
1062
+ };
1063
+ const stripPlaceholderKeys = (text) => {
1064
+ const inHeredoc = text.includes('<<');
1065
+ return text.replace(PLACEHOLDER_KEY_RE, (m) => {
1066
+ // Anthropic-shaped keys are never treated as fixtures.
1067
+ if (/^sk-ant-/i.test(m)) return m;
1068
+ const body = m.replace(/^(?:sk-|gh[pousr]_)/, '');
1069
+ const run = longestSequentialRun(body);
1070
+ // Full-alphabet run (26) is never random; a shorter ascending run only
1071
+ // counts as a fixture inside a heredoc body (test file being written).
1072
+ return placeholderShare(body) >= 0.25 || run >= 26 || (inHeredoc && run >= 8) ? '<placeholder-key>' : m;
1073
+ });
1074
+ };
1075
+
792
1076
  const seenLabels = new Set();
793
1077
  for (const { channel, text } of textChannels) {
794
1078
  for (const label of scanTextLabels(text)) {
@@ -808,7 +1092,7 @@ async function evaluate({ rawInput, projectRoot, env }) {
808
1092
  if (allowedValueHashes.has(sha256(finding.value))) continue;
809
1093
  findings.push({ label: `${finding.label} in bash command`, value: finding.value });
810
1094
  }
811
- for (const label of scanTextLabels(bashCommand)) {
1095
+ for (const label of scanTextLabels(stripPlaceholderKeys(bashCommand))) {
812
1096
  const key = `bash:${label}`;
813
1097
  if (seenLabels.has(key)) continue;
814
1098
  seenLabels.add(key);
@@ -243,13 +243,7 @@ async function main() {
243
243
  const result = await verifyPostEdit({ projectRoot, payload });
244
244
  if (json) {
245
245
  process.stdout.write(`${JSON.stringify(result)}\n`);
246
- } else if (result.status === 'ok') {
247
- // A plain-text line would make the chain's merged stdout invalid JSON and Claude Code
248
- // would drop a later step's additionalContext (edit-hint). omp's bridge appends step
249
- // stdout verbatim to the tool result, so omp keeps the plain line.
250
- const line = `[ukit-safe-patch] ${result.message}`;
251
- if (payload?.ukit_harness === 'omp' || process.env.UKIT_HARNESS === 'omp') process.stdout.write(`${line}\n`);
252
- else emitSystemMessage(line);
246
+ // status 'ok' is silent: exit 0 with no output (Claude Code hook convention; 798x field noise).
253
247
  } else if (result.status === 'advisory') {
254
248
  process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
255
249
  process.stderr.write('[ukit-safe-patch] handoff authoring advisory — change is already written; continue updating docs/AI_HANDOFF/.\n');
@@ -276,6 +270,8 @@ async function main() {
276
270
 
277
271
  if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
278
272
  main().catch((error) => {
273
+ // OS temp scratch targets are never project scope: skip silently.
274
+ if (error?.osTemp) process.exit(0);
279
275
  process.stderr.write(`[ukit-safe-patch] post-edit ERROR: ${error?.message || error}\n`);
280
276
  // BUG-C23-01: stderr-only crash announces nothing to the user — §8 requires
281
277
  // the paired stdout systemMessage before the non-zero exit.
@@ -90,6 +90,7 @@ async function main() {
90
90
 
91
91
  if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
92
92
  main().catch((error) => {
93
+ if (error?.osTemp) process.exit(0); // OS temp scratch target: silent skip
93
94
  process.stderr.write(`[ukit-safe-patch] backup ERROR: ${error?.message || error}\n`);
94
95
  process.exit(1);
95
96
  });
@@ -1551,13 +1551,13 @@ async function runCli() {
1551
1551
  if (nextState?.phase === 'hard') {
1552
1552
  process.stdout.write(
1553
1553
  `[ukit-skill-router] Context pressure: hard (est ${nextState.estimatedTotalTokens} / soft ${nextState.softThreshold} / hard ${nextState.hardThreshold}). `
1554
- + 'FIRST THING IN YOUR REPLY, tell the user plainly — do not stay silent: "Context sắp đầy — hãy gõ /compact ngay bây giờ (run /compact now)". '
1555
- + 'Then hold heavy work: no new investigations, subagents, or large edits until the user has compacted.\n',
1554
+ + 'Do NOT end the turn to ask the user for /compact — keep working: land the step in flight, persist remaining steps to docs/STATUS.md, '
1555
+ + 'delegate broad reads/searches to subagents, and continue the task. The host auto-compacts and UKit resumes from disk.\n',
1556
1556
  );
1557
1557
  } else if (nextState?.phase === 'soft') {
1558
1558
  process.stdout.write(
1559
1559
  `[ukit-skill-router] Context pressure: soft (est ${nextState.estimatedTotalTokens} / soft ${nextState.softThreshold} / hard ${nextState.hardThreshold}). `
1560
- + 'Finish the current step, then tell the user to run /compact at the next natural pause instead of continuing indefinitely.\n',
1560
+ + 'Keep working; keep replies and reads lean and persist progress to docs/STATUS.md so a host auto-compact resumes cleanly.\n',
1561
1561
  );
1562
1562
  }
1563
1563
  }
@@ -1042,6 +1042,56 @@ function maskedVerificationStage(command, depth = 0, options = {}) {
1042
1042
  return sawRunner ? null : text;
1043
1043
  }
1044
1044
 
1045
+ // Field telemetry #3 (2026-11-20): `runner > log 2>&1; echo "exit=$?"` and zsh
1046
+ // `runner | tail; echo "exit=${pipestatus[1]}"` were the top "unproven" storms. A status echoed
1047
+ // IMMEDIATELY after the runner IS the runner's status — the same proof OpenHands (PS1 `"exit_code": "$?"`)
1048
+ // and SWE-ReX (`echo $?` after each command) rely on. Accepted only when: the echo is the LAST unit, holds
1049
+ // exactly one status reference and no other expansion, the reference points at the single runner (bash
1050
+ // PIPESTATUS is 0-based, zsh pipestatus 1-based; `$?` only after a non-pipeline runner), the command before
1051
+ // the echo is itself unmasked, and the LAST stdout line is exactly the echo literal with a number. Anything
1052
+ // else returns null and the caller keeps the fail-closed "unproven" verdict.
1053
+ const STATUS_ECHO_RE = /^echo\s+(?:"([^"$`\\]*)(\$\?|\$\{\?\}|\$\{PIPESTATUS\[(\d)\]\}|\$\{pipestatus\[(\d)\]\})([^"$`\\]*)"|([^\s"'$`\\;|&<>()]*)(\$\?|\$\{\?\}|\$\{PIPESTATUS\[(\d)\]\}|\$\{pipestatus\[(\d)\]\})([^\s"'$`\\;|&<>()]*))$/;
1054
+ function bashStdoutText(response) {
1055
+ if (typeof response === 'string') return response;
1056
+ if (!response || typeof response !== 'object' || Array.isArray(response)) return '';
1057
+ for (const key of ['stdout', 'output', 'content']) if (typeof response[key] === 'string') return response[key];
1058
+ return '';
1059
+ }
1060
+ function printedRunnerStatus(command, toolResponse) {
1061
+ const text = String(command || '').trim();
1062
+ if (!text || /\n/.test(text) || executableSubstitutions(text).length) return null;
1063
+ const units = verificationShellUnits(text);
1064
+ if (!units || units.length < 2) return null;
1065
+ const echo = units[units.length - 1];
1066
+ const m = STATUS_ECHO_RE.exec(echo.text);
1067
+ if (!m || echo.separator) return null;
1068
+ const before = m[1] ?? m[6] ?? '';
1069
+ const ref = m[2] ?? m[7];
1070
+ const after = m[5] ?? m[10] ?? '';
1071
+ const bashIdx = m[3] ?? m[8];
1072
+ const zshIdx = m[4] ?? m[9];
1073
+ const end = units.length - 2;
1074
+ if (units[end].separator !== ';') return null;
1075
+ let start = end;
1076
+ while (start > 0 && (units[start - 1].separator === '|' || units[start - 1].separator === '|&')) start -= 1;
1077
+ let stage;
1078
+ if (bashIdx !== undefined) stage = Number(bashIdx);
1079
+ else if (zshIdx !== undefined) stage = Number(zshIdx) - 1;
1080
+ else if (ref === '$?' || ref === '${?}') stage = start === end ? 0 : -1;
1081
+ if (!(stage >= 0) || start + stage > end) return null;
1082
+ const runner = units[start + stage];
1083
+ if (!isVerificationCommand(runner.text)) return null;
1084
+ for (let i = start; i <= end; i += 1) if (i !== start + stage && isVerificationCommand(units[i].text)) return null;
1085
+ // The prefix plus the runner alone must already be an unmasked verification command.
1086
+ const head = [...units.slice(0, start).map((u) => `${u.text} ${u.separator}`), runner.text].join(' ');
1087
+ if (maskedVerificationStage(head) !== null) return null;
1088
+ const lines = bashStdoutText(toolResponse).replace(/\s+$/, '').split(/\r?\n/);
1089
+ const last = lines[lines.length - 1] ?? '';
1090
+ if (!last.startsWith(before) || !last.endsWith(after)) return null;
1091
+ const digits = last.slice(before.length, last.length - after.length);
1092
+ return /^\d{1,3}$/.test(digits) ? Number(digits) : null;
1093
+ }
1094
+
1045
1095
  // Announce through the in-proc hook emitter only (never fd 1 from library callers).
1046
1096
  // Host launch acknowledgement of a backgrounded Bash call (Claude Code: structured
1047
1097
  // `backgroundTaskId`, or the fixed "running in background" text). Structured field first.
@@ -1134,7 +1184,7 @@ function hostCompletionExit(transcriptPath, id) {
1134
1184
  // ANY notification, with or without an exit code, ends the pending state), memoized per (path, mtimeMs, size) so repeated Stop checks do not re-read the file.
1135
1185
  const HOST_SCAN_CACHE = [];
1136
1186
  function scanHostNotifications(transcriptPath) {
1137
- const empty = { notified: new Set(), exits: new Map() };
1187
+ const empty = { notified: new Set(), exits: new Map(), asyncAgents: new Map() };
1138
1188
  if (!transcriptPath) return empty;
1139
1189
  let st;
1140
1190
  try { st = fsSync.statSync(transcriptPath); } catch { return empty; }
@@ -1142,11 +1192,22 @@ function scanHostNotifications(transcriptPath) {
1142
1192
  if (hit) return hit.scan;
1143
1193
  let raw;
1144
1194
  try { raw = fsSync.readFileSync(transcriptPath, 'utf8'); } catch { return empty; }
1145
- const scan = { notified: new Set(), exits: new Map() };
1195
+ const scan = { notified: new Set(), exits: new Map(), asyncAgents: new Map() };
1146
1196
  for (const line of raw.split('\n')) {
1147
- if (!line.includes('<task-id>')) continue;
1197
+ const asyncLaunch = line.includes('"async_launched"');
1198
+ if (!asyncLaunch && !line.includes('<task-id>')) continue;
1148
1199
  let o;
1149
1200
  try { o = JSON.parse(line); } catch { continue; }
1201
+ // Field telemetry #1 (2026-11-20): Claude Code background subagents (`Agent` with run_in_background) are
1202
+ // host-written `toolUseResult: { isAsync, status: 'async_launched', agentId }` tool results, finished by the
1203
+ // same <task-notification> as a background shell. 149 of 487 Stop blocks fired while such an agent was still
1204
+ // running — blocking cannot produce its result, so it gets the same bounded WAIT as a background shell.
1205
+ const tur = o?.type === 'user' ? o.toolUseResult : null;
1206
+ if (asyncLaunch && tur && tur.isAsync === true && tur.status === 'async_launched'
1207
+ && typeof tur.agentId === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(tur.agentId)) {
1208
+ scan.asyncAgents.set(tur.agentId, Date.parse(o.timestamp) || 0);
1209
+ continue;
1210
+ }
1150
1211
  let text = null;
1151
1212
  if (o?.type === 'queue-operation' && o.operation === 'enqueue' && typeof o.content === 'string') text = o.content;
1152
1213
  else if (o?.type === 'user' && typeof o.message?.content === 'string') text = o.message.content;
@@ -3357,6 +3418,21 @@ function pendingBackgroundJob(ledger, { unreleasedOnly = false } = {}) {
3357
3418
  return null;
3358
3419
  }
3359
3420
 
3421
+ // A host background subagent launched during this task ledger and not yet finished (no task-notification).
3422
+ // Claude Code only (host-written transcript); other hosts return null and keep their existing behaviour.
3423
+ function pendingAsyncAgent(ledger, { unreleasedOnly = false } = {}) {
3424
+ if (!ledger?.transcriptPath) return null;
3425
+ const scan = scanHostNotifications(ledger.transcriptPath);
3426
+ const since = Number(ledger.startedAt) || 0;
3427
+ let latest = null;
3428
+ for (const [id, ts] of scan.asyncAgents) {
3429
+ if (scan.notified.has(id) || (since && ts && ts + 2000 < since)) continue;
3430
+ if (unreleasedOnly && (ledger.waitReleasedFor || []).includes(id)) continue;
3431
+ latest = id;
3432
+ }
3433
+ return latest;
3434
+ }
3435
+
3360
3436
  function liveBaseLedger(event, current, payload, routeState, harness, fallbackLedger, projectRoot = null) {
3361
3437
  if (current && routeState?.taskInstanceId && current.taskInstanceId !== routeState.taskInstanceId
3362
3438
  && routeState.predecessor && current.taskInstanceId === routeState.predecessor.predecessorTaskInstanceId) {
@@ -3851,6 +3927,14 @@ export async function recordExecutionReceipt({
3851
3927
  if (ledgerMessageEmitter) {
3852
3928
  try { ledgerMessageEmitter(`${JSON.stringify({ systemMessage: isOmpBackgroundId(receipt.backgroundTaskId) ? `UKit execution-ledger: UNSUPPORTED_EVIDENCE — omp job ${receipt.backgroundTaskId} has no exit status and cannot count as a pass; run the verification once in the foreground (async:false) for a native exit.` : `UKit execution-ledger: background verification ${receipt.backgroundTaskId || '(unknown id)'} is pending. Wait for the same job; do not launch a duplicate. After the host task-notification, Read its tasks/<id>.output through the final exit footer to ingest completion; Bash/grep does not ingest it.` })}\n`); } catch { /* advisory */ }
3853
3929
  }
3930
+ } else if (maskedStage && receipt.success && recognizedRunner
3931
+ && (exitCode === 0 || (exitCode === null && hostProvesCleanBashExit(harness, payload, toolResponse)))
3932
+ && printedRunnerStatus(toolInput.command, toolResponse) !== null) {
3933
+ // The wrapper exited cleanly AND printed the runner's own status as its last line.
3934
+ const printed = printedRunnerStatus(toolInput.command, toolResponse);
3935
+ receipt.exitCode = printed;
3936
+ receipt.exitProof = 'printed-status';
3937
+ receipt.success = printed === 0;
3854
3938
  } else if (maskedStage && receipt.success) {
3855
3939
  receipt.success = false;
3856
3940
  receipt.exitStatusUnproven = true;
@@ -5140,6 +5224,11 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
5140
5224
  // At most ONE WAIT release per (task, job id): the CLI records it (`wait-released`), after which a job that
5141
5225
  // is still pending falls back to the normal gate (finite cap, pending-job wording, never an edit demand).
5142
5226
  const waitingOn = pendingBackgroundJob(effectiveLedger, { unreleasedOnly: true });
5227
+ const waitingAgent = waitingOn ? null : pendingAsyncAgent(effectiveLedger, { unreleasedOnly: true });
5228
+ if (waitingAgent) {
5229
+ return { continue: false, notify: true, complete: false, wait: true, outcome: 'waiting', waitingOn: waitingAgent, missingEvidence,
5230
+ reason: `UKit WAIT: a background subagent this task launched is still running. Blocking this Stop cannot produce its result, so it is released without spending continuation budget. Missing ${missingEvidence.join(', ')} until the subagent reports back; when its task-notification arrives, review its result, then run the verification yourself and continue. Do not launch a duplicate agent.` };
5231
+ }
5143
5232
  if (waitingOn) {
5144
5233
  return { continue: false, notify: true, complete: false, wait: true, outcome: 'waiting', waitingOn, missingEvidence,
5145
5234
  reason: `UKit WAIT: background job ${waitingOn} is pending. Wait for the same job; do not launch a duplicate. This Stop is released without spending continuation budget and without demanding an edit. Missing ${missingEvidence.join(', ')} until the host task-notification arrives; then Read tasks/${waitingOn}.output through the exit footer and continue with the next milestone (artifact verification, authorized deploy, live verification). Do not relaunch the job.` };
@@ -1463,6 +1463,32 @@ export function isVerbatimOutputCommand(command) {
1463
1463
  return false;
1464
1464
  }
1465
1465
 
1466
+ // Field telemetry #11 (2026-11-20): a numerically ranked cluster list (~50 lines) came back
1467
+ // reordered with its middle dropped — the line picker lifts "important" lines ahead of the
1468
+ // rest, which destroys the order a ranked/sorted table IS. rtk-ai/rtk (#582) reports the
1469
+ // same lesson: summarising content whose structure is the information costs more turns than
1470
+ // it saves. A count-ranked table (≥ 8 lines led by a number, ≥ 60% of lines, sorted
1471
+ // monotonically) up to RANKED_TABLE_MAX_TOKENS passes through raw. The configured
1472
+ // outputMaxTokens budget still governs every other output.
1473
+ const RANKED_TABLE_MAX_TOKENS = 6000;
1474
+ const RANKED_LINE_RE = /^\s*(\d+(?:\.\d+)?)(?:\s|[:|,x×]|$)/;
1475
+ export function isPassThroughOutput(text) {
1476
+ const lines = String(text ?? '').split('\n').filter((l) => l.trim());
1477
+ if (estimateTokenCount(String(text ?? '')) > RANKED_TABLE_MAX_TOKENS) return false;
1478
+ const nums = [];
1479
+ for (const line of lines) {
1480
+ 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;
1490
+ }
1491
+
1466
1492
  function mergeDeep(base, override) {
1467
1493
  if (!override || typeof override !== 'object' || Array.isArray(override)) {
1468
1494
  return override === undefined ? base : override;
@@ -1558,7 +1584,8 @@ async function main() {
1558
1584
  }
1559
1585
 
1560
1586
  // 3.5.11: content reads, bounded pipelines and chained commands pass through raw.
1561
- if (isVerbatimOutputCommand(command)) {
1587
+ // 3.5.14 (#11): count-ranked tables pass through raw (their order is the content).
1588
+ if (isVerbatimOutputCommand(command) || isPassThroughOutput(stdout)) {
1562
1589
  process.exit(0);
1563
1590
  return;
1564
1591
  }
@@ -1,6 +1,7 @@
1
1
  import fs from 'node:fs/promises';
2
2
  import fsSync from 'node:fs';
3
3
  import path from 'node:path';
4
+ import os from 'node:os';
4
5
  import { spawnSync } from 'node:child_process';
5
6
 
6
7
  export const DEFAULT_SAFE_PATCH_CONFIG = {
@@ -80,6 +81,26 @@ export function resolveProjectFile(projectRoot, filePath) {
80
81
  };
81
82
  }
82
83
 
84
+ function osTempRoots() {
85
+ const roots = ['/tmp', '/private/tmp', os.tmpdir(), process.env.TMPDIR].filter(Boolean);
86
+ for (const r of [...roots]) { try { roots.push(fsSync.realpathSync(r)); } catch { /* absent root */ } }
87
+ return [...new Set(roots.map((r) => path.resolve(r)))].filter((r) => r !== path.parse(r).root);
88
+ }
89
+
90
+ /** True when an absolute target lies strictly inside an OS temp dir (scratch files; never project scope). */
91
+ export function isOsTempPath(filePath, projectRoot) {
92
+ const raw = String(filePath || '').trim();
93
+ if (!raw || !path.isAbsolute(raw)) return false;
94
+ const candidates = [path.resolve(raw), realpathNearest(path.resolve(raw))].filter(Boolean);
95
+ // A project that itself lives inside a temp root (sandboxes) gets no exemption for that root.
96
+ const home = projectRoot ? [path.resolve(projectRoot), realpathNearest(path.resolve(projectRoot))].filter(Boolean) : [];
97
+ const insideRoot = (c, root) => { const rel = path.relative(root, c); return rel && !rel.startsWith('..') && !path.isAbsolute(rel); };
98
+ return candidates.some((c) => osTempRoots().filter((root) => !home.some((h) => insideRoot(h, root) || h === root)).some((root) => {
99
+ const rel = path.relative(root, c);
100
+ return rel && !rel.startsWith('..') && !path.isAbsolute(rel);
101
+ }));
102
+ }
103
+
83
104
  function realpathNearest(absolute) {
84
105
  // Real path of the deepest existing ancestor + the not-yet-existing tail, so a Write
85
106
  // that creates a new file is judged by where it would actually land (symlinks resolved).
@@ -145,6 +166,7 @@ export function resolveEditTarget(projectRoot, filePath) {
145
166
  };
146
167
  }
147
168
  }
169
+ if (isOsTempPath(filePath, root)) error.osTemp = true;
148
170
  throw error;
149
171
  }
150
172
  }