mixdog 0.9.17 → 0.9.19

package/scripts/recall-bench.mjs

@@ -113,13 +113,87 @@ function scoreTopNContains(lines, substrings, n) {
   return { perSubstring, hitAtN, mrr, n };
 }
 
-function evaluateCase(kase, { count, ms, isError }, quality) {
+// Parse leading "[YYYY-MM-DD HH:MM]" timestamps from result lines and check
+// they are non-increasing (newest-first). Returns null when fewer than 2
+// lines carry a parseable timestamp (nothing to order).
+function scoreRecencyOrdered(lines) {
+  const tsRe = /^\s*\[(\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2})/;
+  const headerRe = /^\s*##\s/;
+  const parse = (raw) => Date.parse(raw.replace(' ', 'T'));
+  // Non-increasing check within a single ordered list of {raw,ts}. Returns
+  // the first {prev,cur} pair where cur is newer than prev, else null.
+  const firstBreak = (stamps) => {
+    for (let i = 1; i < stamps.length; i++) {
+      if (Number.isFinite(stamps[i].ts) && Number.isFinite(stamps[i - 1].ts) && stamps[i].ts > stamps[i - 1].ts) {
+        return { prev: stamps[i - 1].raw, cur: stamps[i].raw };
+      }
+    }
+    return null;
+  };
+  const hasSessions = lines.some((l) => headerRe.test(l));
+  if (!hasSessions) {
+    // Ungrouped: single global non-increasing check over all timestamped lines.
+    const stamps = [];
+    for (const line of lines) {
+      const m = tsRe.exec(line);
+      if (m) stamps.push({ raw: m[1], ts: parse(m[1]) });
+    }
+    if (stamps.length < 2) return { parsed: stamps.length, groups: 0, ordered: true, firstViolation: null };
+    const b = firstBreak(stamps);
+    return { parsed: stamps.length, groups: 0, ordered: b === null, firstViolation: b };
+  }
+  // Session-grouped: partition timestamped lines by their "## session" header.
+  // Timestamps only compared WITHIN a group; groups themselves must descend by
+  // their first line's timestamp.
+  const groups = [];
+  let cur = null;
+  for (const line of lines) {
+    if (headerRe.test(line)) { cur = { stamps: [] }; groups.push(cur); continue; }
+    const m = tsRe.exec(line);
+    if (m && cur) cur.stamps.push({ raw: m[1], ts: parse(m[1]) });
+  }
+  const nonEmpty = groups.filter((g) => g.stamps.length);
+  const parsed = nonEmpty.reduce((s, g) => s + g.stamps.length, 0);
+  let firstViolation = null;
+  for (const g of nonEmpty) {
+    const b = firstBreak(g.stamps);
+    if (b) { firstViolation = { ...b, scope: 'within-session' }; break; }
+  }
+  if (!firstViolation) {
+    const heads = nonEmpty.map((g) => g.stamps[0]);
+    const b = firstBreak(heads);
+    if (b) firstViolation = { ...b, scope: 'across-sessions' };
+  }
+  return { parsed, groups: nonEmpty.length, ordered: firstViolation === null, firstViolation };
+}
+
+// Score expect.allContain: every result line must contain at least one of the
+// given substrings (case-insensitive). Returns offending lines (matching none).
+// Use for negative cases where rows legitimately mention the term.
+function scoreAllContain(lines, substrings) {
+  const needles = substrings.map((s) => String(s || '').toLowerCase()).filter(Boolean);
+  const offenders = lines.filter((line) => {
+    const l = line.toLowerCase();
+    return !needles.some((n) => l.includes(n));
+  });
+  return { needles: substrings, offenders, ok: offenders.length === 0 };
+}
+
+function evaluateCase(kase, { count, ms, isError }, quality, recency, allContain) {
   const warnings = [];
   if (isError) warnings.push('error result');
   if (ms > WARN_LATENCY_MS) warnings.push(`latency ${ms}ms > ${WARN_LATENCY_MS}ms`);
   if ((kase.expect === 'browse' || kase.expect === 'idlookup') && count === 0) {
     warnings.push('0 results for a browse/id-lookup case (expected data present)');
   }
+  if (kase.expect === 'empty' && count > 0) {
+    warnings.push(`expected empty but got ${count} result(s) — possible filler/unrelated match`);
+  }
+  if (allContain) {
+    for (const line of allContain.offenders) {
+      warnings.push(`allContain miss: result line contains none of [${allContain.needles.join(', ')}]: "${line}"`);
+    }
+  }
   if (quality) {
     for (const p of quality.perSubstring) {
       if (!p.hit) {
@@ -129,6 +203,10 @@ function evaluateCase(kase, { count, ms, isError }, quality) {
       }
     }
   }
+  if (recency && !recency.ordered && recency.firstViolation) {
+    const v = recency.firstViolation;
+    warnings.push(`recencyOrdered violation (${v.scope || 'global'}): ${v.cur} newer than prior ${v.prev}`);
+  }
   const status = warnings.length ? 'WARN' : 'PASS';
   return { status, warnings };
 }
@@ -156,7 +234,10 @@ async function runCase(memoryModule, kase) {
   const topNContains = expectObj && Array.isArray(expectObj.topNContains) ? expectObj.topNContains : null;
   const cutoffN = expectObj && Number.isInteger(expectObj.topN) ? expectObj.topN : 5;
   const quality = topNContains ? scoreTopNContains(resultLines(text), topNContains, cutoffN) : null;
-  const evalResult = evaluateCase({ ...kase, expect: expectKind }, { count, ms, isError }, quality);
+  const recency = expectObj && expectObj.recencyOrdered ? scoreRecencyOrdered(resultLines(text)) : null;
+  const allContainNeedles = expectObj && Array.isArray(expectObj.allContain) ? expectObj.allContain : null;
+  const allContain = allContainNeedles ? scoreAllContain(resultLines(text), allContainNeedles) : null;
+  const evalResult = evaluateCase({ ...kase, expect: expectKind }, { count, ms, isError }, quality, recency, allContain);
   return {
     id: kase.id,
     label: kase.label,
@@ -167,6 +248,8 @@ async function runCase(memoryModule, kase) {
     errMsg,
     top3: topN(text, 3),
     quality,
+    recency,
+    allContain,
     status: evalResult.status,
     warnings: evalResult.warnings,
   };
@@ -182,6 +265,9 @@ function printCase(row) {
       process.stdout.write(`    substr "${p.needle}" -> rank ${p.rank ?? 'none'}${p.hit ? '' : '  (miss)'}\n`);
     }
   }
+  if (row.recency) {
+    process.stdout.write(`  recency: ${row.recency.ordered ? 'ordered' : 'OUT-OF-ORDER'} (${row.recency.parsed} timestamped lines)\n`);
+  }
   if (row.top3.length) {
     for (const line of row.top3) process.stdout.write(`    - ${line}\n`);
   } else {
@@ -218,6 +304,7 @@ function printSummary(rows) {
 async function main() {
   const casesPath = argValue('cases', DEFAULT_CASES_PATH);
   const jsonMode = hasFlag('json');
+  const strict = hasFlag('strict');
   const cases = loadCases(casesPath);
 
   let memoryModule;
@@ -262,6 +349,8 @@ async function main() {
 
   const hardErrors = rows.filter((r) => r.isError);
   if (hardErrors.length) process.exitCode = 1;
+  // --strict: any WARN row fails the run. Default behavior (errors-only) unchanged.
+  if (strict && rows.some((r) => r.status === 'WARN')) process.exitCode = 1;
 }
 
 main().catch((e) => {

package/scripts/recall-usecase-cases.json

@@ -15,4 +15,4 @@
   { "id": "uc5-yesterday", "label": "UC5 calendar yesterday", "args": { "period": "yesterday", "limit": 10 }, "expect": "browse" },
   { "id": "uc5-thisweek", "label": "UC5 calendar this_week", "args": { "period": "this_week", "limit": 10 }, "expect": "browse" },
   { "id": "uc6-category", "label": "UC6 category decision 7d", "args": { "period": "7d", "category": "decision", "limit": 10 }, "expect": "browse" }
-]
+]

package/scripts/smoke-runtime-negative.ps1

@@ -1,106 +1,106 @@
-# smoke-runtime-negative.ps1 — Negative-path tests against released win32-x64
-# runtime tarball. Validates: download, sha256, corrupt-tarball, fresh-extract
-# boot, double-init refusal, hostile-env survival.
-#
-# Env: TAG / OS / ARCH / RUNTIME_RELEASE_REPOSITORY (default tribgames/mixdog)
-
-$ErrorActionPreference = 'Stop'
-
-$Tag         = if ($env:TAG)                { $env:TAG }  else { 'runtime-v0.4.0' }
-$Os          = if ($env:OS)                 { $env:OS }   else { 'win32' }
-$Arch        = if ($env:ARCH)               { $env:ARCH } else { 'x64' }
-$ReleaseRepo = if ($env:RUNTIME_RELEASE_REPOSITORY) { $env:RUNTIME_RELEASE_REPOSITORY } else { 'tribgames/mixdog' }
-$PgVer       = '16.4'
-$PgvectorVer = '0.8.2'
-
-$Asset = "mixdog-runtime-${Os}-${Arch}-pg${PgVer}-pgvector${PgvectorVer}.tar.gz"
-$Url   = "https://github.com/${ReleaseRepo}/releases/download/${Tag}/${Asset}"
-
-$Work = New-Item -ItemType Directory -Force -Path "$env:TEMP\smoke-$([guid]::NewGuid().ToString('N'))" | Select-Object -ExpandProperty FullName
-
-try {
-    Write-Host "==> Negative-path smoke for ${Os}-${Arch} from $Url"
-
-    Write-Host "==> Test 1: HEAD reaches release asset"
-    $resp = Invoke-WebRequest -Uri $Url -Method Head -UseBasicParsing -ErrorAction Stop
-    Write-Host "  HTTP $($resp.StatusCode)"
-
-    Write-Host "==> Test 2: full download + sha256"
-    $TarPath = Join-Path $Work $Asset
-    Invoke-WebRequest -Uri $Url -OutFile $TarPath -UseBasicParsing
-    $sha = (Get-FileHash -Algorithm SHA256 $TarPath).Hash.ToLower()
-    Write-Host "  sha256=$sha"
-
-    Write-Host "==> Test 3: corrupt tarball — flip a byte and ensure tar errors"
-    $CorruptPath = "$Work\corrupt.tar.gz"
-    Copy-Item $TarPath $CorruptPath
-    $bytes = [byte[]]::new(1); $rand = [System.Random]::new(); $rand.NextBytes($bytes)
-    $stream = [System.IO.File]::OpenWrite($CorruptPath)
-    $stream.Position = 102400
-    $stream.Write($bytes, 0, 1)
-    $stream.Close()
-    $CorruptDir = "$Work\corrupt"
-    New-Item -ItemType Directory -Force -Path $CorruptDir | Out-Null
-    $TarProc = Start-Process -FilePath tar -ArgumentList @('-xzf', $CorruptPath, '-C', $CorruptDir.Replace('\','/')) -Wait:$false -PassThru -WindowStyle Hidden
-    if (-not $TarProc.WaitForExit(15000)) {
-        Stop-Process -Id $TarProc.Id -Force -ErrorAction SilentlyContinue
-        Write-Host "  PASS: corrupted tarball extraction timed out and was stopped"
-    } elseif ($TarProc.ExitCode -eq 0) {
-        Write-Host "  WARN: corrupted tarball extracted without error (tar gzip recovery)"
-    } else {
-        Write-Host "  PASS: corrupted tarball rejected by tar (exit $($TarProc.ExitCode))"
-    }
-
-    Write-Host "==> Test 4: fresh-extract boot (extension load + distance query)"
-    $FreshDir = "$Work\fresh"
-    New-Item -ItemType Directory -Force -Path $FreshDir | Out-Null
-    & tar -xzf $TarPath -C ($FreshDir.Replace('\','/'))
-    if ($LASTEXITCODE -ne 0) { throw "fresh extract failed" }
-
-    $PgBin   = "$FreshDir\bin"
-    $Data    = "$FreshDir\pgdata"
-    $Log     = "$FreshDir\pg.log"
-    $Port    = 55897
-
-    # Hostile env: minimal PATH (System32 only), no PGROOT/PGDATA
-    $SavedPath = $env:PATH
-    $SavedPgRoot = $env:PGROOT
-    $env:PATH   = "$env:SystemRoot\System32;$env:SystemRoot"
-    $env:PGROOT = $null
-    $env:PGDATA = $null
-
-    try {
-        & "$PgBin\postgres.exe" --version
-        if ($LASTEXITCODE -ne 0) { throw "FAIL: postgres --version" }
-        & "$PgBin\initdb.exe" -D $Data --username=postgres --auth-local=trust --no-locale -E UTF8 | Out-Null
-        if ($LASTEXITCODE -ne 0) { throw "FAIL: initdb" }
-        & "$PgBin\pg_ctl.exe" -D $Data -o "-p $Port -h 127.0.0.1" -l $Log -w start
-        if ($LASTEXITCODE -ne 0) { Get-Content $Log | Select-Object -Last 30; throw "FAIL: pg_ctl start" }
-
-        try {
-            & "$PgBin\psql.exe" -h 127.0.0.1 -p $Port -U postgres -d postgres -c "CREATE EXTENSION vector;" | Out-Null
-            if ($LASTEXITCODE -ne 0) { throw "FAIL: CREATE EXTENSION" }
-            $ExtV = & "$PgBin\psql.exe" -h 127.0.0.1 -p $Port -U postgres -d postgres -tAc "SELECT extversion FROM pg_extension WHERE extname='vector';"
-            if ($ExtV.Trim() -ne $PgvectorVer) { throw "FAIL: extversion='$ExtV' expected='$PgvectorVer'" }
-            Write-Host "  PASS: fresh-extract boot + vector extension"
-        } finally {
-            & "$PgBin\pg_ctl.exe" -D $Data -m fast stop 2>$null | Out-Null
-        }
-
-        Write-Host "==> Test 5: second initdb on initialized dir refused"
-        $rc = (Start-Process -FilePath "$PgBin\initdb.exe" -ArgumentList "-D",$Data,"-U","postgres" -Wait -PassThru -NoNewWindow).ExitCode
-        if ($rc -eq 0) {
-            Write-Host "  WARN: second initdb succeeded (unexpected)"
-        } else {
-            Write-Host "  PASS: second initdb refused (exit $rc)"
-        }
-    } finally {
-        $env:PATH   = $SavedPath
-        $env:PGROOT = $SavedPgRoot
-    }
-
-    Write-Host "==> All negative-path smokes: PASS"
-}
-finally {
-    Remove-Item -Recurse -Force $Work -ErrorAction SilentlyContinue
-}
+# smoke-runtime-negative.ps1 — Negative-path tests against released win32-x64
+# runtime tarball. Validates: download, sha256, corrupt-tarball, fresh-extract
+# boot, double-init refusal, hostile-env survival.
+#
+# Env: TAG / OS / ARCH / RUNTIME_RELEASE_REPOSITORY (default tribgames/mixdog)
+
+$ErrorActionPreference = 'Stop'
+
+$Tag         = if ($env:TAG)                { $env:TAG }  else { 'runtime-v0.4.0' }
+$Os          = if ($env:OS)                 { $env:OS }   else { 'win32' }
+$Arch        = if ($env:ARCH)               { $env:ARCH } else { 'x64' }
+$ReleaseRepo = if ($env:RUNTIME_RELEASE_REPOSITORY) { $env:RUNTIME_RELEASE_REPOSITORY } else { 'tribgames/mixdog' }
+$PgVer       = '16.4'
+$PgvectorVer = '0.8.2'
+
+$Asset = "mixdog-runtime-${Os}-${Arch}-pg${PgVer}-pgvector${PgvectorVer}.tar.gz"
+$Url   = "https://github.com/${ReleaseRepo}/releases/download/${Tag}/${Asset}"
+
+$Work = New-Item -ItemType Directory -Force -Path "$env:TEMP\smoke-$([guid]::NewGuid().ToString('N'))" | Select-Object -ExpandProperty FullName
+
+try {
+    Write-Host "==> Negative-path smoke for ${Os}-${Arch} from $Url"
+
+    Write-Host "==> Test 1: HEAD reaches release asset"
+    $resp = Invoke-WebRequest -Uri $Url -Method Head -UseBasicParsing -ErrorAction Stop
+    Write-Host "  HTTP $($resp.StatusCode)"
+
+    Write-Host "==> Test 2: full download + sha256"
+    $TarPath = Join-Path $Work $Asset
+    Invoke-WebRequest -Uri $Url -OutFile $TarPath -UseBasicParsing
+    $sha = (Get-FileHash -Algorithm SHA256 $TarPath).Hash.ToLower()
+    Write-Host "  sha256=$sha"
+
+    Write-Host "==> Test 3: corrupt tarball — flip a byte and ensure tar errors"
+    $CorruptPath = "$Work\corrupt.tar.gz"
+    Copy-Item $TarPath $CorruptPath
+    $bytes = [byte[]]::new(1); $rand = [System.Random]::new(); $rand.NextBytes($bytes)
+    $stream = [System.IO.File]::OpenWrite($CorruptPath)
+    $stream.Position = 102400
+    $stream.Write($bytes, 0, 1)
+    $stream.Close()
+    $CorruptDir = "$Work\corrupt"
+    New-Item -ItemType Directory -Force -Path $CorruptDir | Out-Null
+    $TarProc = Start-Process -FilePath tar -ArgumentList @('-xzf', $CorruptPath, '-C', $CorruptDir.Replace('\','/')) -Wait:$false -PassThru -WindowStyle Hidden
+    if (-not $TarProc.WaitForExit(15000)) {
+        Stop-Process -Id $TarProc.Id -Force -ErrorAction SilentlyContinue
+        Write-Host "  PASS: corrupted tarball extraction timed out and was stopped"
+    } elseif ($TarProc.ExitCode -eq 0) {
+        Write-Host "  WARN: corrupted tarball extracted without error (tar gzip recovery)"
+    } else {
+        Write-Host "  PASS: corrupted tarball rejected by tar (exit $($TarProc.ExitCode))"
+    }
+
+    Write-Host "==> Test 4: fresh-extract boot (extension load + distance query)"
+    $FreshDir = "$Work\fresh"
+    New-Item -ItemType Directory -Force -Path $FreshDir | Out-Null
+    & tar -xzf $TarPath -C ($FreshDir.Replace('\','/'))
+    if ($LASTEXITCODE -ne 0) { throw "fresh extract failed" }
+
+    $PgBin   = "$FreshDir\bin"
+    $Data    = "$FreshDir\pgdata"
+    $Log     = "$FreshDir\pg.log"
+    $Port    = 55897
+
+    # Hostile env: minimal PATH (System32 only), no PGROOT/PGDATA
+    $SavedPath = $env:PATH
+    $SavedPgRoot = $env:PGROOT
+    $env:PATH   = "$env:SystemRoot\System32;$env:SystemRoot"
+    $env:PGROOT = $null
+    $env:PGDATA = $null
+
+    try {
+        & "$PgBin\postgres.exe" --version
+        if ($LASTEXITCODE -ne 0) { throw "FAIL: postgres --version" }
+        & "$PgBin\initdb.exe" -D $Data --username=postgres --auth-local=trust --no-locale -E UTF8 | Out-Null
+        if ($LASTEXITCODE -ne 0) { throw "FAIL: initdb" }
+        & "$PgBin\pg_ctl.exe" -D $Data -o "-p $Port -h 127.0.0.1" -l $Log -w start
+        if ($LASTEXITCODE -ne 0) { Get-Content $Log | Select-Object -Last 30; throw "FAIL: pg_ctl start" }
+
+        try {
+            & "$PgBin\psql.exe" -h 127.0.0.1 -p $Port -U postgres -d postgres -c "CREATE EXTENSION vector;" | Out-Null
+            if ($LASTEXITCODE -ne 0) { throw "FAIL: CREATE EXTENSION" }
+            $ExtV = & "$PgBin\psql.exe" -h 127.0.0.1 -p $Port -U postgres -d postgres -tAc "SELECT extversion FROM pg_extension WHERE extname='vector';"
+            if ($ExtV.Trim() -ne $PgvectorVer) { throw "FAIL: extversion='$ExtV' expected='$PgvectorVer'" }
+            Write-Host "  PASS: fresh-extract boot + vector extension"
+        } finally {
+            & "$PgBin\pg_ctl.exe" -D $Data -m fast stop 2>$null | Out-Null
+        }
+
+        Write-Host "==> Test 5: second initdb on initialized dir refused"
+        $rc = (Start-Process -FilePath "$PgBin\initdb.exe" -ArgumentList "-D",$Data,"-U","postgres" -Wait -PassThru -NoNewWindow).ExitCode
+        if ($rc -eq 0) {
+            Write-Host "  WARN: second initdb succeeded (unexpected)"
+        } else {
+            Write-Host "  PASS: second initdb refused (exit $rc)"
+        }
+    } finally {
+        $env:PATH   = $SavedPath
+        $env:PGROOT = $SavedPgRoot
+    }
+
+    Write-Host "==> All negative-path smokes: PASS"
+}
+finally {
+    Remove-Item -Recurse -Force $Work -ErrorAction SilentlyContinue
+}

package/scripts/tool-efficiency-diag.mjs

@@ -66,7 +66,10 @@ for (const target of ['heavy-worker', 'worker']) {
       }
       if (n === 'grep' && ['content', 'content_with_context'].includes(String(a.output_mode || ''))) {
         grepContent++;
-        if (a['-C'] != null || a['-A'] != null || a['-B'] != null) grepContentWithCtx++;
+        // Implicit context: output_mode content_with_context carries context
+        // without explicit -C/-A/-B flags.
+        if (a['-C'] != null || a['-A'] != null || a['-B'] != null
+          || String(a.output_mode) === 'content_with_context') grepContentWithCtx++;
         const gpath = typeof a.path === 'string' ? a.path : JSON.stringify(a.path || '');
         for (let j = i + 1; j < Math.min(i + 4, tools.length); j++) {
           const u = tools[j];
@@ -85,4 +88,4 @@ for (const target of ['heavy-worker', 'worker']) {
   console.log(`  single-call batches: ${batch1}/${batchTot} (${pct(batch1, batchTot)}%)`);
   console.log(`  content greps with -C/-A/-B: ${grepContentWithCtx}/${grepContent} (${pct(grepContentWithCtx, grepContent)}%)  grep->read follow-ups: ${grepThenRead}`);
   console.log(`  same-path re-reads >=3x: ${rereads}`);
-}
+}

package/scripts/tool-smoke.mjs

@@ -508,8 +508,8 @@ if (!/^read 2\b/m.test(String(readRegionBatchOut))
   || (String(readRegionBatchOut).match(/scripts\/smoke\.mjs \[full\] \[ok\]/g) || []).length < 2
   || !/1→import \{ spawnSync \}/.test(String(readRegionBatchOut))
   || !/3→import \{ fileURLToPath \}/.test(String(readRegionBatchOut))
-  || !/pass offset:2 to continue/.test(String(readRegionBatchOut))
-  || !/pass offset:4 to continue/.test(String(readRegionBatchOut))) {
+  || !/(pass offset:2 to continue|ONE window: offset:2, limit:\d+)/.test(String(readRegionBatchOut))
+  || !/(pass offset:4 to continue|ONE window: offset:4, limit:\d+)/.test(String(readRegionBatchOut))) {
   throw new Error(`read region batch must preserve both requested spans:\n${readRegionBatchOut}`);
 }
 
@@ -534,6 +534,46 @@ if (readStringifiedLineErr || readStringifiedLineArgs.path[0].offset !== 7 || re
   throw new Error(`read guard must losslessly convert legacy line/context inside stringified arrays to offset/limit: err=${readStringifiedLineErr} args=${JSON.stringify(readStringifiedLineArgs)}`);
 }
 
+// Absorb shape 1: region array + top-level offset/limit → top-level becomes
+// the default window for regions that lack their own; no hard error.
+const readRegionPlusTopLevelArgs = {
+  path: [{ path: 'scripts/smoke.mjs', offset: 3, limit: 4 }, { path: 'scripts/smoke.mjs' }],
+  offset: 0,
+  limit: 2,
+};
+const readRegionPlusTopLevelErr = validateBuiltinArgs('read', readRegionPlusTopLevelArgs);
+if (readRegionPlusTopLevelErr
+  || 'offset' in readRegionPlusTopLevelArgs || 'limit' in readRegionPlusTopLevelArgs
+  || readRegionPlusTopLevelArgs.path[0].offset !== 3 || readRegionPlusTopLevelArgs.path[0].limit !== 4
+  || readRegionPlusTopLevelArgs.path[1].offset !== 0 || readRegionPlusTopLevelArgs.path[1].limit !== 2) {
+  throw new Error(`read guard must absorb region-array + top-level offset/limit: err=${readRegionPlusTopLevelErr} args=${JSON.stringify(readRegionPlusTopLevelArgs)}`);
+}
+
+// Absorb shape 2: parallel offset/limit as JSON-stringified arrays with path[]
+// → zipped into per-file region objects (pairwise recovery), no int error.
+const readZipWindowArgs = {
+  path: ['scripts/smoke.mjs', 'scripts/smoke.mjs'],
+  offset: '[0, 5]',
+  limit: '[2, 3]',
+};
+const readZipWindowErr = validateBuiltinArgs('read', readZipWindowArgs);
+if (readZipWindowErr || !Array.isArray(readZipWindowArgs.path)
+  || readZipWindowArgs.path[0].offset !== 0 || readZipWindowArgs.path[0].limit !== 2
+  || readZipWindowArgs.path[1].offset !== 5 || readZipWindowArgs.path[1].limit !== 3
+  || 'offset' in readZipWindowArgs || 'limit' in readZipWindowArgs) {
+  throw new Error(`read guard must zip stringified offset/limit arrays onto path[]: err=${readZipWindowErr} args=${JSON.stringify(readZipWindowArgs)}`);
+}
+
+// Absorb shape 3: code_graph file/files as a JSON-stringified array → parsed to
+// a real array before lookup (dispatched into files[]).
+const cgStringifiedFileArgs = { mode: 'symbols', file: JSON.stringify(['a.mjs', 'b.mjs']) };
+const cgStringifiedFileErr = validateBuiltinArgs('code_graph', cgStringifiedFileArgs);
+if (cgStringifiedFileErr || 'file' in cgStringifiedFileArgs
+  || !Array.isArray(cgStringifiedFileArgs.files)
+  || cgStringifiedFileArgs.files[0] !== 'a.mjs' || cgStringifiedFileArgs.files[1] !== 'b.mjs') {
+  throw new Error(`code_graph guard must parse JSON-stringified file array: err=${cgStringifiedFileErr} args=${JSON.stringify(cgStringifiedFileArgs)}`);
+}
+
 const graphOut = await executeCodeGraphTool('code_graph', {
   mode: 'symbols',
   file: 'scripts/smoke.mjs',
@@ -549,6 +589,17 @@ if (!/# symbol_search executeBuiltinTool\b/.test(String(graphSymbolBatchOut)) ||
   throw new Error(`code_graph symbol_search symbols[] batch execution failed:\n${graphSymbolBatchOut}`);
 }
 
+// Absorb shape 3 (real dispatch): file as a JSON-stringified array batches per
+// file instead of hitting "file not found: [...]".
+const graphStringifiedFileOut = await executeCodeGraphTool('code_graph', {
+  mode: 'symbols',
+  file: JSON.stringify(['scripts/smoke.mjs']),
+}, root);
+if (/file not found/.test(String(graphStringifiedFileOut))
+  || !/binding|spawnSync|symbol/i.test(String(graphStringifiedFileOut))) {
+  throw new Error(`code_graph must parse JSON-stringified file array before lookup:\n${graphStringifiedFileOut}`);
+}
+
 const graphMissingFileOut = await executeCodeGraphTool('code_graph', {
   mode: 'symbols',
   file: 'src/runtime/loop.mjs',
@@ -634,6 +685,33 @@ if (!/^Error[\s:[]/.test(String(shellTimeoutOut)) || !/\[timeout: 500ms\b/.test(
   throw new Error(`bash timeout must be milliseconds and classified as Error:\n${shellTimeoutOut}`);
 }
 
+// Auto-promotion: a sync foreground command still running past the (soft)
+// promotion budget is detached into a tracked background task and returns the
+// same task_id envelope as explicit async — the caller never pre-chose async.
+// Shrink the budget via MIXDOG_SHELL_AUTO_BACKGROUND_MS so the smoke stays fast.
+const _priorAutoBgBudget = process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS;
+process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS = '800';
+let shellAutoPromoteOut;
+try {
+  shellAutoPromoteOut = await executeBuiltinTool('shell', {
+    command: 'Start-Sleep -Seconds 6; Write-Output tool-smoke-autopromote-done',
+    cwd: root,
+    timeout: 30_000,
+    shell: 'powershell',
+  }, root);
+} finally {
+  if (_priorAutoBgBudget === undefined) delete process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS;
+  else process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS = _priorAutoBgBudget;
+}
+if (!/auto-backgrounded/i.test(String(shellAutoPromoteOut)) || !/task_id:\s*\S+/i.test(String(shellAutoPromoteOut))) {
+  throw new Error(`shell auto-promotion must return a background task envelope (task_id + auto-backgrounded):\n${shellAutoPromoteOut}`);
+}
+// Clean up the promoted job so it doesn't outlive the smoke as an orphan.
+const _autoPromoteTaskId = (/task_id:\s*(\S+)/i.exec(String(shellAutoPromoteOut)) || [])[1];
+if (_autoPromoteTaskId) {
+  try { await executeBuiltinTool('task', { action: 'cancel', task_id: _autoPromoteTaskId }, root); } catch {}
+}
+
 const legacyEscapedAlternationErr = validateBuiltinArgs('grep', { pattern: 'state\\.items\\.map\\|items\\.map', path: root });
 if (legacyEscapedAlternationErr) {
   throw new Error(`grep legacy \\| alternation should be accepted: ${legacyEscapedAlternationErr}`);
@@ -1217,8 +1295,10 @@ setInternalToolsProvider({
     if (workerToolNames.includes('tool_search')) {
       throw new Error(`agent session schema must not expose deferred tool_search: ${workerToolNames.join(', ')}`);
     }
-    if (workerToolNames.includes('shell')) {
-      throw new Error(`read-write agent session schema must not expose shell: ${workerToolNames.join(', ')}`);
+    for (const name of ['shell', 'task']) {
+      if (!workerToolNames.includes(name)) {
+        throw new Error(`read-write agent session schema must expose ${name} for self-verification: ${workerToolNames.join(', ')}`);
+      }
     }
     for (const name of ['skills_list', 'skill_view', 'skill_execute']) {
       if (workerToolNames.includes(name)) {
@@ -1266,7 +1346,7 @@ setInternalToolsProvider({
     const fullTools = (fullAgentSession.tools || []).map((tool) => tool?.name).filter(Boolean);
     const publicExploreTools = (publicExploreSession.tools || []).map((tool) => tool?.name).filter(Boolean);
     const expectedReadTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'explore', 'search', 'web_fetch', 'Skill'];
-    const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'explore', 'search', 'web_fetch', 'Skill'];
+    const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'shell', 'task', 'explore', 'search', 'web_fetch', 'Skill'];
     if (JSON.stringify(readTools) !== JSON.stringify(expectedReadTools)) {
       throw new Error(`read agent schema must be fixed allow-list: expected=${expectedReadTools.join(', ')} actual=${readTools.join(', ')}`);
     }
@@ -1276,20 +1356,17 @@ setInternalToolsProvider({
     if (readTools.includes('tool_search') || writeTools.includes('tool_search')) {
       throw new Error(`agent session fixed schemas must omit tool_search: read=${readTools.join(', ')} write=${writeTools.join(', ')}`);
     }
-    if (readTools.includes('shell') || writeTools.includes('shell')) {
-      throw new Error(`read/read-write agent schemas must omit shell: read=${readTools.join(', ')} write=${writeTools.join(', ')}`);
+    if (readTools.includes('shell')) {
+      throw new Error(`read agent schema must omit shell: read=${readTools.join(', ')}`);
     }
     for (const name of ['shell', 'apply_patch', 'task']) {
       if (readTools.includes(name)) {
         throw new Error(`read agent schema must omit non-read tool ${name}: read=${readTools.join(', ')}`);
       }
     }
-    for (const name of ['apply_patch', 'task']) {
-      if (name === 'apply_patch' && !writeTools.includes(name)) {
-        throw new Error(`read-write agent schema must preserve apply_patch: write=${writeTools.join(', ')}`);
-      }
-      if (name !== 'apply_patch' && writeTools.includes(name)) {
-        throw new Error(`read-write agent schema must omit non-edit tool ${name}: write=${writeTools.join(', ')}`);
+    for (const name of ['apply_patch', 'shell', 'task']) {
+      if (!writeTools.includes(name)) {
+        throw new Error(`read-write agent schema must preserve ${name}: write=${writeTools.join(', ')}`);
       }
     }
     for (const name of ['memory', 'recall', 'reply']) {
@@ -1334,7 +1411,7 @@ setInternalToolsProvider({
   try {
     const resumed = await resumeSession(resumeAgentSession.id, 'full');
     const resumedTools = (resumed?.tools || []).map((tool) => tool?.name).filter(Boolean);
-    const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'explore', 'search', 'web_fetch', 'Skill'];
+    const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'shell', 'task', 'explore', 'search', 'web_fetch', 'Skill'];
     if (JSON.stringify(resumedTools) !== JSON.stringify(expectedWriteTools)) {
       throw new Error(`resumed read-write agent schema must keep fixed allow-list: expected=${expectedWriteTools.join(', ')} actual=${resumedTools.join(', ')}`);
     }
@@ -1522,7 +1599,7 @@ const readPathDescription = readPathSchema.description || '';
 if (!/File path/i.test(readPathDescription) || !/\{path,offset,limit\}\[\]/i.test(readPathDescription) || !/Pass arrays directly/i.test(readPathDescription) || !/legacy recovery only/i.test(readPathDescription)) {
   throw new Error('read schema must keep directory-vs-file guidance');
 }
-if (!/Dirs use list/i.test((BUILTIN_TOOLS.find((tool) => tool.name === 'read')?.description) || '')) {
+if (!/Not for directory listing/i.test((BUILTIN_TOOLS.find((tool) => tool.name === 'read')?.description) || '')) {
   throw new Error('read description must keep directory-vs-file guidance');
 }
 const readTool = BUILTIN_TOOLS.find((tool) => tool.name === 'read');
@@ -1533,7 +1610,7 @@ const readArrayItemAnyOf = readArraySchema?.items?.anyOf || [];
 if (!readArrayItemAnyOf.some((entry) => entry?.type === 'object' && entry?.properties?.offset && entry?.properties?.limit)) {
   throw new Error('read schema must expose array-of-region objects for batched spans');
 }
-if (/line\+context/i.test(readDescription) || !/numeric offset\+limit/i.test(readDescription) || !/Batch paths\/regions as real arrays/i.test(readDescription) || !/grep content_with_context or code_graph anchors/i.test(readDescription)) {
+if (/line\+context/i.test(readDescription) || !/numeric offset\+limit/i.test(readDescription) || !/Batch paths\/regions as real arrays/i.test(readDescription)) {
   throw new Error('read description must expose offset/limit as the single window form');
 }
 if (readProps.line || readProps.context) {
@@ -1596,9 +1673,6 @@ if (codeGraphSymbolSearchErr) {
 if (!/code structure\/flow/i.test(codeGraphDescription) || !/symbols\/references\/calls\/deps/i.test(codeGraphDescription)) {
   throw new Error('code_graph description must stay structure-oriented and name its symbol modes');
 }
-if (!/before text grep/i.test(codeGraphDescription)) {
-  throw new Error('code_graph description must steer symbol/caller lookups to structure lookup before grep');
-}
 if (!/repo-local/i.test(codeGraphDescription) || !/NOT web search|not web/i.test(codeGraphDescription)) {
   throw new Error('code_graph description must mark itself repo-local (not web search)');
 }
@@ -1853,23 +1927,23 @@ const grepPathDescription = grepTool?.inputSchema?.properties?.path?.description
 const grepGlobDescription = grepTool?.inputSchema?.properties?.glob?.description || '';
 const grepOutputModeDescription = grepTool?.inputSchema?.properties?.output_mode?.description || '';
 const grepHeadLimitDescription = grepTool?.inputSchema?.properties?.head_limit?.description || '';
-if (!/synonyms in pattern\[\]/i.test(grepPatternDescription) || !/OR in ONE grep/i.test(grepPatternDescription) || !/serial rewording/i.test(grepPatternDescription) || !/equivalent repeats/i.test(grepPatternDescription) || !/Narrowest file\/dir/i.test(grepPathDescription) || !/broad scopes return paths first/i.test(grepPathDescription) || !/refine from returned paths/i.test(grepPathDescription)) {
+if (!/Array = variants in one call/i.test(grepPatternDescription) || !/Known file or dir/i.test(grepPathDescription)) {
   throw new Error('grep schema must keep compact pattern/path guidance');
 }
-if (!/same grep/i.test(grepGlobDescription) || !/no follow-up grep/i.test(grepGlobDescription) || !/equivalent scope changes/i.test(grepGlobDescription)) {
-  throw new Error('grep glob schema must steer narrowing into the same grep call');
+if (!/narrow scope/i.test(grepGlobDescription)) {
+  throw new Error('grep glob schema must describe scope narrowing');
 }
-if (!/Broad scope: files_with_matches\/count/i.test(grepOutputModeDescription) || !/Narrow scope: content_with_context/i.test(grepOutputModeDescription) || !/answer from/i.test(grepOutputModeDescription) || !/skip read/i.test(grepOutputModeDescription) || !/span is not shown/i.test(grepOutputModeDescription)) {
-  throw new Error('grep output_mode schema must steer content_with_context away from follow-up reads');
+if (!/files_with_matches\/count/i.test(grepOutputModeDescription) || !/content_with_context/i.test(grepOutputModeDescription)) {
+  throw new Error('grep output_mode schema must name its output shapes');
 }
-if (grepTool?.inputSchema?.properties?.head_limit?.minimum !== 0 || !/keep small/i.test(grepHeadLimitDescription)) {
+if (grepTool?.inputSchema?.properties?.head_limit?.minimum !== 0 || !/Max results/i.test(grepHeadLimitDescription)) {
   throw new Error('grep head_limit schema must keep locator caps explicit');
 }
 if (grepTool?.inputSchema?.properties?.type) {
   throw new Error('grep type schema must stay hidden; prefer glob for extension narrowing');
 }
-if (!/code flow before text search/i.test(codeGraphProps.mode?.description || '') || !/one anchor is enough/i.test(codeGraphProps.symbols?.description || '') || !/one call/i.test(codeGraphProps.symbols?.description || '')) {
-  throw new Error('code_graph schema fields must steer away from repeated lookup loops');
+if (!/Repo-local/i.test(codeGraphProps.mode?.description || '') || !/one call/i.test(codeGraphProps.symbols?.description || '')) {
+  throw new Error('code_graph schema fields must stay compact and repo-local');
 }
 
 const longToolSearchText = compactToolSearchDescription(`${patchDescription}\n${patchDescription}`);

package/src/agents/debugger/AGENT.md

@@ -8,7 +8,7 @@ Root-cause analysis agent.
 
 Smallest confirmed cause chain before fixes. Return likely cause, evidence
 (`file:line`), smallest next check/fix. Mark confirmed facts vs inferences;
-avoid broad speculation. Fragments only; no narration, no report bloat.
+avoid broad speculation.
 
-Converge, don't sweep: when new reads stop adding evidence, report the best
-cause chain so far — a partial/blocked report is a valid completion.
+Converge, don't sweep: when new evidence stops accruing, report the best
+cause chain so far.