nubos-pilot 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to nubos-pilot are documented in this file. Format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
 follows [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.3] — 2026-06-24
+
+A finished milestone can no longer block the start of the next one with a stale checkpoint.
+
+- `init resume-work` now reconciles every checkpoint against git before deciding orphan: a checkpoint whose task already has a `task(<id>):` commit is a tombstone left behind when the checkpoint was never unlinked (a crash between commit and unlink, or a commit made outside `commit-task`). Those are pruned silently and reported in `pruned_checkpoints`; only genuinely uncommitted checkpoints still surface as `orphan`. Git is the source of truth, so a committed task is never mistaken for in-flight work.
+- `np:doctor` is git-aware for the same case: a committed-but-unlinked checkpoint is reported as `info` / `fixable: auto` with the commit sha, not as a manual-fix `warn`.
+- The `execute-phase` orphan-checkpoint guard's two remediation options are now wired — "reset-slice" and "resume" were previously no-op `case` branches that left the file in place, so the prompt re-fired on every run.
+
+Full documentation at <https://pilot.nubos.cloud>.
+
 ## [1.3.0] — 2026-06-17
 
 Run any agent on any model, not only Claude.

package/bin/np-tools/_commands.cjs

@@ -89,6 +89,8 @@ const COMMANDS = [
   { name: 'knowledge-index',         category: 'Utility', description: 'Build BM25-light index over .nubos-pilot/**/*.md → .nubos-pilot/state/knowledge-index.json', description_de: 'Baut BM25-Light-Index über .nubos-pilot/**/*.md → .nubos-pilot/state/knowledge-index.json' },
   { name: 'knowledge-search',        category: 'Utility', description: 'Query the knowledge index; returns top-N JSON hits (rel_path + lines + score + preview). Pass --task <id> inside a Nubosloop task to record Rule 9 audit evidence', description_de: 'Sucht im Knowledge-Index; liefert Top-N-JSON-Treffer (rel_path + Zeilen + Score + Preview). --task <id> innerhalb eines Nubosloop-Tasks schreibt den Rule-9-Audit-Nachweis' },
   { name: 'knowledge-stats',         category: 'Utility', description: 'Print knowledge-index size + grouping (auto-builds if missing)', description_de: 'Gibt Knowledge-Index-Größe + Gruppierung aus (baut auto bei Fehlen)' },
+  { name: 'elision-get',             category: 'Utility', description: 'Retrieve the original text behind a ⟦elided:<hash>⟧ compression marker. Reversible context compression (ADR-Elision). Positional <hash> or --hash; --json for envelope', description_de: 'Holt den Originaltext hinter einem ⟦elided:<hash>⟧ Kompressions-Marker. Reversible Kontext-Kompression (ADR-Elision). Positional <hash> oder --hash; --json für Envelope' },
+  { name: 'elision-bench',           category: 'Utility', description: 'Measure elision compression: deterministic fidelity (ratio + critical-line preservation + byte-exact reversibility) over a fixture corpus; --with-model adds answer-equivalence (raw vs compressed). --size <small|medium|large> runs a scaled corpus with a deterministic --holdout control group (--max-cases N) and an estimated token saving (--price-per-mtok <p> [--currency EUR] adds a cost estimate). --json, --tier <name>', description_de: 'Misst die Elision-Kompression: deterministische Fidelity (Ratio + Erhalt kritischer Zeilen + byte-exakte Reversibilität) über ein Fixture-Korpus; --with-model ergänzt Antwort-Äquivalenz (roh vs. komprimiert). --size <small|medium|large> fährt ein skaliertes Korpus mit deterministischer --holdout-Kontrollgruppe (--max-cases N) und geschätzter Token-Ersparnis (--price-per-mtok <p> [--currency EUR] ergänzt eine Kostenschätzung). --json, --tier <name>' },
   { name: 'context-stats',           category: 'Utility', description: 'Aggregated context-budget stats (file counts + bytes per group, knowledge-index size)', description_de: 'Aggregierte Context-Budget-Stats (Dateien/Bytes pro Gruppe, Knowledge-Index-Größe)' },
   { name: 'session-snapshot-write',  category: 'Utility', description: 'Capture session snapshot (current_task + recent commits + open handoffs) for resume', description_de: 'Erfasst Session-Snapshot (current_task + letzte Commits + offene Handoffs) für Resume' },
   { name: 'session-snapshot-read',   category: 'Utility', description: 'Print last session snapshot as JSON', description_de: 'Gibt letzten Session-Snapshot als JSON aus' },

package/bin/np-tools/_elision-proxy-entry.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+const proxy = require('../../lib/elision-proxy.cjs');
+
+proxy.start({
+  cwd: process.env.ELISION_PROXY_CWD || process.cwd(),
+  upstream: process.env.ELISION_PROXY_UPSTREAM || undefined,
+}).then(({ baseUrl }) => {
+  if (process.send) process.send({ ready: true, baseUrl });
+}).catch((err) => {
+  if (process.send) process.send({ ready: false, error: String(err && err.message) });
+  process.exit(1);
+});

package/bin/np-tools/doctor.cjs

@@ -543,6 +543,28 @@ function _checkOrphanCheckpoints(projectRoot) {
     catch { continue; }
     if (!cp || cp.status !== 'in-progress') continue;
     if (currentTask === taskId) continue;
+
+    let committedSha = null;
+    try { committedSha = require('../../lib/checkpoint-reconcile.cjs').committedSha(taskId, projectRoot); }
+    catch { committedSha = null; }
+
+    if (committedSha) {
+      issues.push({
+        id: 'orphan-checkpoint',
+        severity: 'info',
+        fixable: 'auto',
+        details: {
+          task_id: taskId,
+          checkpoint: path.relative(projectRoot, cpPath),
+          current_task: currentTask,
+          committed_sha: committedSha,
+          hint: 'Task is already committed (' + committedSha.slice(0, 8) + ') but its checkpoint was never unlinked. '
+            + 'A stale tombstone, not in-flight work. `np-tools resume-work` reconciles it against git and prunes it automatically.',
+        },
+      });
+      continue;
+    }
+
     issues.push({
       id: 'orphan-checkpoint',
       severity: 'warn',
@@ -551,9 +573,9 @@ function _checkOrphanCheckpoints(projectRoot) {
         task_id: taskId,
         checkpoint: path.relative(projectRoot, cpPath),
         current_task: currentTask,
-        hint: 'Checkpoint marks task as in-progress but STATE.md.current_task does not match. '
-          + 'Likely a crash during finishTask between STATE-clear and checkpoint-unlink. '
-          + 'Run `np-tools undo-task ' + taskId + '` to clean up, or delete manually after verifying the task is genuinely done.',
+        hint: 'Checkpoint marks task as in-progress, no matching commit exists, and STATE.md.current_task does not match. '
+          + 'Likely a genuine crash mid-flight. '
+          + 'Run `np-tools undo-task ' + taskId + '` to clean up, or resume the task, after verifying its state.',
       },
     });
   }

package/bin/np-tools/elision-bench.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+const bench = require('../../lib/elision-bench.cjs');
+
+function _parseArgs(args) {
+  const out = { json: false, withModel: false, tier: 'frontier', size: null, holdout: 0.2, maxCases: null, charsPerToken: null, pricePerMTok: null, currency: null };
+  for (let i = 0; i < (args || []).length; i += 1) {
+    const a = args[i];
+    if (a === '--json') { out.json = true; continue; }
+    if (a === '--with-model') { out.withModel = true; continue; }
+    if (a === '--tier') { out.tier = args[++i] || out.tier; continue; }
+    if (a === '--size') { out.size = args[++i] || out.size; continue; }
+    if (a === '--holdout') { const v = parseFloat(args[++i]); if (Number.isFinite(v)) out.holdout = v; continue; }
+    if (a === '--max-cases') { const v = parseInt(args[++i], 10); if (Number.isFinite(v)) out.maxCases = v; continue; }
+    if (a === '--chars-per-token') { const v = parseFloat(args[++i]); if (Number.isFinite(v)) out.charsPerToken = v; continue; }
+    if (a === '--price-per-mtok') { const v = parseFloat(args[++i]); if (Number.isFinite(v)) out.pricePerMTok = v; continue; }
+    if (a === '--currency') { out.currency = args[++i] || out.currency; continue; }
+  }
+  return out;
+}
+
+async function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const parsed = _parseArgs(args || []);
+
+  if (parsed.size) {
+    const scale = bench.runScale({ cwd, size: parsed.size, holdoutRatio: parsed.holdout, maxCases: parsed.maxCases, charsPerToken: parsed.charsPerToken, pricePerMTok: parsed.pricePerMTok, currency: parsed.currency });
+    stdout.write((parsed.json ? JSON.stringify({ scale }) : bench.formatScale(scale)) + '\n');
+    return scale.summary.invariants_ok ? 0 : 1;
+  }
+
+  const fidelity = bench.runFidelity({ cwd });
+  let equivalence = null;
+
+  if (parsed.withModel) {
+    const { resolveFromConfig } = require('./resolve-model.cjs');
+    const { chat } = require('../../lib/runtime/providers/openai-compat.cjs');
+    const res = resolveFromConfig({ agentOrTier: parsed.tier, cwd, format: 'json' });
+    if (!res || !res.model || !res.baseUrl) {
+      stdout.write((parsed.json ? JSON.stringify({ fidelity, equivalence: null, error: 'no-provider' }) : 'No off-host provider resolved for tier "' + parsed.tier + '" — equivalence skipped.') + '\n');
+      return fidelity.summary.invariants_ok ? 0 : 1;
+    }
+    const provider = { baseUrl: res.baseUrl, apiKeyEnv: res.apiKeyEnv, model: res.model };
+    equivalence = await bench.runEquivalence({ chatImpl: chat, provider });
+  }
+
+  if (parsed.json) {
+    stdout.write(JSON.stringify({ fidelity, equivalence }) + '\n');
+  } else {
+    stdout.write(bench.formatReport(fidelity) + '\n');
+    if (equivalence) {
+      stdout.write('\nAnswer equivalence — ' + equivalence.summary.equivalent + '/' + equivalence.summary.cases
+        + ' equivalent, regressions: ' + (equivalence.summary.regressions.length ? equivalence.summary.regressions.join(', ') : 'none') + '\n');
+      for (const c of equivalence.cases) {
+        stdout.write('  ' + (c.regression ? '✗' : '✓') + ' ' + c.name + ' (raw '
+          + (c.raw_ok ? 'ok' : 'miss') + ', compressed ' + (c.compressed_ok ? 'ok' : 'miss') + ')\n');
+      }
+    }
+  }
+
+  const ok = fidelity.summary.invariants_ok && (!equivalence || equivalence.summary.no_regression);
+  return ok ? 0 : 1;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/elision-get.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const elision = require('../../lib/elision.cjs');
+
+function _parseArgs(args) {
+  const out = { hash: null, json: false };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--hash') { out.hash = args[++i] || null; continue; }
+    if (a === '--json') { out.json = true; continue; }
+    positional.push(a);
+  }
+  if (out.hash == null) out.hash = positional.join('').trim() || null;
+  return out;
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const parsed = _parseArgs(args || []);
+  if (!parsed.hash) {
+    throw new NubosPilotError(
+      'elision-get-missing-hash',
+      'elision-get requires a hash (positional or --hash)',
+      { hint: 'hash is the 12-char id from a ⟦elided:…⟧ marker' },
+    );
+  }
+  const result = elision.retrieve(parsed.hash, cwd);
+  if (parsed.json) {
+    stdout.write(JSON.stringify(result));
+    return result.status === 'ok' ? 0 : 1;
+  }
+  if (result.status === 'ok') {
+    stdout.write(result.original);
+    return 0;
+  }
+  if (result.status === 'expired') {
+    stdout.write('[elision ' + parsed.hash + ' expired — original no longer cached (ttl elapsed)]\n');
+    return 1;
+  }
+  stdout.write('[elision ' + parsed.hash + ' not found]\n');
+  return 1;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/elision-get.test.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const elisionGet = require('./elision-get.cjs');
+const elision = require('../../lib/elision.cjs');
+const { NubosPilotError } = require('../../lib/core.cjs');
+
+function sandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-elisionget-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  return root;
+}
+
+function capture() {
+  const chunks = [];
+  return { stream: { write: (s) => chunks.push(s) }, text: () => chunks.join('') };
+}
+
+test('ELISIONGET-1: prints the original for a known hash', () => {
+  const root = sandbox();
+  try {
+    const hash = elision.store('the original payload', { type: 'plain' }, root);
+    const out = capture();
+    const code = elisionGet.run([hash], { cwd: root, stdout: out.stream });
+    assert.equal(code, 0);
+    assert.equal(out.text(), 'the original payload');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('ELISIONGET-2: unknown hash exits 1 with a not-found notice', () => {
+  const root = sandbox();
+  try {
+    const out = capture();
+    const code = elisionGet.run(['aaaaaaaaaaaa'], { cwd: root, stdout: out.stream });
+    assert.equal(code, 1);
+    assert.match(out.text(), /not found/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('ELISIONGET-3: --json emits the retrieval envelope', () => {
+  const root = sandbox();
+  try {
+    const hash = elision.store('payload', { type: 'plain' }, root);
+    const out = capture();
+    const code = elisionGet.run([hash, '--json'], { cwd: root, stdout: out.stream });
+    assert.equal(code, 0);
+    const env = JSON.parse(out.text());
+    assert.equal(env.status, 'ok');
+    assert.equal(env.original, 'payload');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('ELISIONGET-4: missing hash throws', () => {
+  assert.throws(() => elisionGet.run([], { cwd: process.cwd(), stdout: { write() {} } }), NubosPilotError);
+});

package/bin/np-tools/loop-run-round.cjs

@@ -6,16 +6,37 @@ const path = require('node:path');
 const { NubosPilotError, safeAssign } = require('../../lib/core.cjs');
 const safePath = require('../../lib/safe-path.cjs');
 
-function _resolveInsideCwdOrTmp(p, cwd, label, errorCode) {
-  return safePath.assertInsideCwdOrTmp(p, cwd, label, errorCode);
-}
 const checkpoint = require('../../lib/checkpoint.cjs');
 const nubosloop = require('../../lib/nubosloop.cjs');
 const messaging = require('../../lib/messaging.cjs');
+const compress = require('../../lib/compress.cjs');
+const elision = require('../../lib/elision.cjs');
+const logger = require('../../lib/logger.cjs').child('loop-run-round');
 const args = require('./_args.cjs');
 
 const { TASK_ID_RE } = require('../../lib/ids.cjs');
 
+function _resolveInsideCwdOrTmp(p, cwd, label, errorCode) {
+  return safePath.assertInsideCwdOrTmp(p, cwd, label, errorCode);
+}
+
+function _verifyExcerpt(verifyOutput, cwd) {
+  const s = String(verifyOutput);
+  const cx = elision.compressionContext(cwd);
+  const maxBytes = cx.verifyMaxBytes;
+  if (s.length <= maxBytes) return s;
+  if (cx.enabled) {
+    try {
+      const crushed = compress.crushLogToBudget(s, maxBytes);
+      if (crushed && crushed.length < s.length) {
+        const hash = cx.store ? cx.store(s, 'log') : null;
+        return crushed + (hash ? '\n' + compress.marker(hash, 'full verify log') : '');
+      }
+    } catch (err) { logger.warn('verify compression skipped', { cause: err && err.message }); }
+  }
+  return '…[truncated head, original ' + s.length + ' bytes — see VERIFY_LOG]\n' + s.slice(-maxBytes);
+}
+
 const VALID_PHASES = new Set([
   'preflight',
   'post-researcher',
@@ -182,16 +203,9 @@ function _runPostExecutor(taskId, list, cwd) {
     }
   }
   const green = code === 0;
-  const VERIFY_TAIL_BYTES = 2000;
   let verifyExcerpt = null;
   if (verifyOutput) {
-    const s = String(verifyOutput);
-    if (s.length > VERIFY_TAIL_BYTES) {
-      verifyExcerpt = '…[truncated head, original ' + s.length + ' bytes — see VERIFY_LOG]\n'
-        + s.slice(-VERIFY_TAIL_BYTES);
-    } else {
-      verifyExcerpt = s;
-    }
+    verifyExcerpt = _verifyExcerpt(verifyOutput, cwd);
   }
   const merged = checkpoint.mergeCheckpoint(
     taskId,

package/bin/np-tools/plan-milestone.cjs

@@ -95,6 +95,7 @@ async function _initPayload(mNum, cwd, opts) {
     const spawnSpecs = swarm.buildSpawnSpecs(
       { milestone: mNum, milestone_id: layout.mId(mNum), goal: def.goal || '' },
       swarmOpts.k,
+      { cwd },
     );
     let cacheHit = null;
     let cacheMiss = null;

package/bin/np-tools/research-phase.cjs

@@ -107,7 +107,7 @@ async function run(args, ctx) {
   const tmDetail = textMode.resolveTextModeDetail(cwd);
 
   const swarmOpts = swarm.resolveSwarmOpts(cwd);
-  const spawnSpecs = swarm.buildSpawnSpecs({ milestone: mNum, milestone_id: mIdStr, goal: def.goal || '' }, swarmOpts.k);
+  const spawnSpecs = swarm.buildSpawnSpecs({ milestone: mNum, milestone_id: mIdStr, goal: def.goal || '' }, swarmOpts.k, { cwd });
 
   let cacheHit = null;
   let cacheMiss = null;

package/bin/np-tools/resume-work.cjs

@@ -3,6 +3,7 @@ const path = require('node:path');
 const { NubosPilotError } = require('../../lib/core.cjs');
 const { readState } = require('../../lib/state.cjs');
 const { readCheckpoint, listCheckpoints } = require('../../lib/checkpoint.cjs');
+const { reconcileCommittedCheckpoints } = require('../../lib/checkpoint-reconcile.cjs');
 const { TASK_ID_RE } = require('../../lib/ids.cjs');
 const textMode = require('../../lib/text-mode.cjs');
 const layout = require('../../lib/layout.cjs');
@@ -48,6 +49,12 @@ function run(_args, ctx) {
 
   const state = _safeReadState(cwd);
   const currentTask = state && state.frontmatter ? state.frontmatter.current_task : null;
+
+  let pruned = [];
+  try {
+    pruned = reconcileCommittedCheckpoints(cwd, { exclude: currentTask }).pruned;
+  } catch { pruned = []; }
+
   const cpFiles = listCheckpoints(cwd);
 
   let payload;
@@ -104,6 +111,8 @@ function run(_args, ctx) {
     };
   }
 
+  if (pruned.length > 0) payload.pruned_checkpoints = pruned;
+
   const tmDetail = textMode.resolveTextModeDetail(cwd);
   payload.text_mode = tmDetail.enabled;
   payload.text_mode_source = tmDetail.source;

package/bin/np-tools/resume-work.test.cjs

@@ -3,9 +3,10 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const { execFileSync } = require('node:child_process');
 
 const subcmd = require('./resume-work.cjs');
-const { startTask } = require('../../lib/checkpoint.cjs');
+const { startTask, listCheckpoints } = require('../../lib/checkpoint.cjs');
 
 const _roots = [];
 
@@ -78,6 +79,25 @@ test('RW-3: orphan when checkpoint files exist but no matching STATE.current_tas
   assert.ok(p.checkpoint_ids.includes('M006-S001-T0005'));
 });
 
+test('RW-5: committed orphan is reconciled against git and pruned (not surfaced)', () => {
+  const root = makeRoot(null);
+  execFileSync('git', ['init', '-q', '-b', 'main', root], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'chore: init'], { stdio: 'pipe' });
+  startTask({ id: 'M013-S005-T0002', phase: 6, plan: '06-01', wave: 1 }, root);
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'task(M013-S005-T0002): demo'], { stdio: 'pipe' });
+  const statePath = path.join(root, '.nubos-pilot', 'STATE.md');
+  fs.writeFileSync(statePath, fs.readFileSync(statePath, 'utf-8').replace(/current_task:.*/, 'current_task: null'), 'utf-8');
+
+  const cap = _capture();
+  const p = subcmd.run([], { cwd: root, stdout: cap.stub });
+  assert.equal(p.status, 'clean');
+  assert.ok(Array.isArray(p.pruned_checkpoints));
+  assert.equal(p.pruned_checkpoints[0].task_id, 'M013-S005-T0002');
+  assert.deepEqual(listCheckpoints(root), []);
+});
+
 test('RW-4: malformed checkpoint → checkpoint-schema-mismatch (T-06-12)', () => {
   const root = makeRoot('M006-S001-T0009');
   const cpDir = path.join(root, '.nubos-pilot', 'checkpoints');

package/bin/np-tools/spawn-headless.cjs

@@ -9,8 +9,35 @@ const { NubosPilotError, atomicWriteFileSync, appendJsonl, findProjectRoot } = r
 const runContext = require('../../lib/run-context.cjs');
 const safePath = require('../../lib/safe-path.cjs');
 const headlessGuard = require('../../lib/headless-guard.cjs');
+const compress = require('../../lib/compress.cjs');
+const elision = require('../../lib/elision.cjs');
+const elisionProxy = require('../../lib/elision-proxy.cjs');
+const steering = require('../../lib/output-steering.cjs');
+const logger = require('../../lib/logger.cjs').child('spawn-headless');
 const args = require('./_args.cjs');
 
+const PROXY_START_TIMEOUT_MS = 5000;
+
+function _startCompressionProxy(cwd) {
+  const upstream = process.env.ANTHROPIC_BASE_URL || '';
+  return new Promise((resolve, reject) => {
+    const proc = child_process.fork(path.join(__dirname, '_elision-proxy-entry.cjs'), [], {
+      env: Object.assign({}, process.env, { ELISION_PROXY_CWD: cwd, ELISION_PROXY_UPSTREAM: upstream }),
+      stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
+    });
+    const timer = setTimeout(() => {
+      try { proc.kill(); } catch { /* already gone */ }
+      reject(new NubosPilotError('elision-proxy-start-timeout', 'compression proxy did not report ready in time', {}));
+    }, PROXY_START_TIMEOUT_MS);
+    proc.once('message', (m) => {
+      clearTimeout(timer);
+      if (m && m.ready) resolve({ proc, baseUrl: m.baseUrl });
+      else { try { proc.kill(); } catch { /* already gone */ } reject(new NubosPilotError('elision-proxy-start-failed', String(m && m.error), {})); }
+    });
+    proc.once('error', (err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
 function _sha256(s) {
   return crypto.createHash('sha256').update(s == null ? '' : String(s)).digest('hex');
 }
@@ -159,6 +186,20 @@ function _composePrompt(agentBody, userPrompt) {
   return agentBody.trimEnd() + '\n\n---\n\n' + userPrompt.trimEnd() + '\n';
 }
 
+function _maybeCompressPrompt(prompt, cwd) {
+  const none = { prompt, stats: null };
+  const cx = elision.compressionContext(cwd);
+  if (!cx.enabled) return none;
+  try {
+    const out = compress.compressPrompt(prompt, { minBlockBytes: cx.minBlockBytes, store: cx.store });
+    if (!out || out.stats.blocks_compressed === 0) return none;
+    return { prompt: out.text, stats: out.stats };
+  } catch (err) {
+    logger.warn('compression skipped', { cause: err && err.message });
+    return none;
+  }
+}
+
 function _stripFrontmatter(md) {
   if (!md.startsWith('---\n')) return md;
   const end = md.indexOf('\n---\n', 4);
@@ -304,20 +345,15 @@ async function run(argv, ctx) {
   }
 
   const agentPath = _resolveAgentPath(agent, cwd);
-  const agentBody = _stripFrontmatter(fs.readFileSync(agentPath, 'utf-8'));
+  let agentBody = _stripFrontmatter(fs.readFileSync(agentPath, 'utf-8'));
+  const _os = elision.compressionContext(cwd).outputSteering;
+  if (_os && _os.enabled) agentBody = steering.enrichSystemPrompt(agentBody, _os.profile);
   const userPrompt = _readPromptFile(promptPath, cwd);
-  const composedPrompt = _composePrompt(agentBody, userPrompt);
+  let composedPrompt = _composePrompt(agentBody, userPrompt);
   const resolvedOutput = _ensureOutputDir(outputPath, cwd);
 
   const runId = runContext.getRunId();
 
-  // ADR-0021: off-host routing. If the agent routes to an openai-compat provider,
-  // run the nubos-pilot dispatch loop instead of `claude -p`, writing the result
-  // in the same {result,...} envelope `claude --output-format json` produces so the
-  // callers (review/extract parseXxxOutput → outer.result) parse it unchanged. The
-  // native path below is untouched. run() is async; the CLI dispatcher already
-  // awaits returned promises (handleRunResult), and the two in-process callers
-  // (review.cjs / extract.cjs) await runReview/runExtract.
   const resolveKind = context.resolveImpl || _defaultResolveKind;
   let routed;
   try { routed = resolveKind(agent, cwd); } catch { routed = { kind: 'native' }; }
@@ -329,6 +365,9 @@ async function run(argv, ctx) {
     });
   }
 
+  const compression = _maybeCompressPrompt(composedPrompt, cwd);
+  composedPrompt = compression.prompt;
+
   let lockRoot;
   try { lockRoot = findProjectRoot(cwd); }
   catch { lockRoot = cwd; }
@@ -344,6 +383,17 @@ async function run(argv, ctx) {
   const childEnv = _filterSpawnEnv(process.env);
   Object.assign(childEnv, headlessGuard.childSpawnEnv(process.env));
 
+  let proxyProc = null;
+  if (elisionProxy.proxyEnabled(cwd)) {
+    try {
+      const started = await _startCompressionProxy(cwd);
+      proxyProc = started.proc;
+      childEnv.ANTHROPIC_BASE_URL = started.baseUrl;
+    } catch (err) {
+      logger.warn('compression proxy unavailable; spawning without it', { cause: err && err.message });
+    }
+  }
+
   const bin = _claudeBinary();
   const claudeArgs = ['-p', '--output-format', 'json'];
   const startedAt = new Date().toISOString();
@@ -365,6 +415,7 @@ async function run(argv, ctx) {
       { bin, cause: err && err.code },
     );
   } finally {
+    if (proxyProc) { try { proxyProc.kill(); } catch { /* already exited */ } }
     lock.release();
   }
   if (result.error && result.error.code === 'ENOENT') {
@@ -406,6 +457,7 @@ async function run(argv, ctx) {
     tokens_in: claudeMeta.tokens_in == null ? null : claudeMeta.tokens_in,
     tokens_out: claudeMeta.tokens_out == null ? null : claudeMeta.tokens_out,
     payload_parse_ok: claudeMeta.parse_ok,
+    compression: compression.stats || null,
   };
   try { appendJsonl(spawnTrailPath, spawnRecord, { maxLineBytes: 16 * 1024, mode: 0o600 }); }
   catch (err) {
@@ -431,6 +483,7 @@ async function run(argv, ctx) {
     tokens_in: spawnRecord.tokens_in,
     tokens_out: spawnRecord.tokens_out,
     payload_parse_ok: spawnRecord.payload_parse_ok,
+    compression: compression.stats || null,
   };
   stdout.write(JSON.stringify(payload) + '\n');
   if (exitCode !== 0) return 2;

package/lib/cache-align.cjs

@@ -0,0 +1,78 @@
+'use strict';
+
+const UUID_RE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+const ISO_RE = /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+const JWT_RE = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/;
+const HEX_RE = /\b[0-9a-f]{32,64}\b/i;
+const VOLATILE = Object.freeze([
+  ['uuid', UUID_RE],
+  ['iso_datetime', ISO_RE],
+  ['jwt', JWT_RE],
+  ['hex_hash', HEX_RE],
+]);
+
+function _systemText(system) {
+  if (typeof system === 'string') return system;
+  if (Array.isArray(system)) {
+    return system.map((b) => (b && typeof b.text === 'string' ? b.text : '')).join('\n');
+  }
+  return '';
+}
+
+function detectVolatile(system) {
+  const text = _systemText(system);
+  const findings = [];
+  for (const [kind, re] of VOLATILE) {
+    const m = text.match(re);
+    if (m) findings.push({ kind, sample_len: m[0].length });
+  }
+  return findings;
+}
+
+function _sortKeys(v) {
+  if (Array.isArray(v)) return v.map(_sortKeys);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = _sortKeys(v[k]);
+    return out;
+  }
+  return v;
+}
+
+function _byCodepoint(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function normalizeTools(tools) {
+  return tools
+    .map(_sortKeys)
+    .map((t) => ({ t, name: String(t && t.name), body: JSON.stringify(t) }))
+    .sort((a, b) => _byCodepoint(a.name, b.name) || _byCodepoint(a.body, b.body))
+    .map((x) => x.t);
+}
+
+function _anyCacheControl(system, tools) {
+  if (Array.isArray(system) && system.some((b) => b && b.cache_control)) return true;
+  if (Array.isArray(tools) && tools.some((t) => t && t.cache_control)) return true;
+  return false;
+}
+
+function alignAnthropicBody(body) {
+  const findings = detectVolatile(body && body.system);
+  if (!body || !Array.isArray(body.tools) || body.tools.length === 0) {
+    return { body, findings, applied: false };
+  }
+  if (_anyCacheControl(body.system, body.tools)) {
+    return { body, findings, applied: false };
+  }
+  const tools = normalizeTools(body.tools);
+  const last = tools.length - 1;
+  tools[last] = Object.assign({}, tools[last], { cache_control: { type: 'ephemeral' } });
+  return { body: Object.assign({}, body, { tools }), findings, applied: true };
+}
+
+module.exports = {
+  detectVolatile,
+  normalizeTools,
+  alignAnthropicBody,
+};