kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/tools/stream-lease.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+'use strict';
+var fs=require('fs');
+var path=require('path');
+function resolveBase(){
+  var env=process.env.CLAUDE_PROJECT_DIR;
+  if(env&&fs.existsSync(path.join(env,'.kenaz')))return env;
+  var dir=path.resolve(__dirname);
+  for(var i=0;i<8;i++){
+    if(fs.existsSync(path.join(dir,'.kenaz')))return dir;
+    var parent=path.dirname(dir);if(parent===dir)break;dir=parent;
+  }
+  return process.cwd();
+}
+var BASE=resolveBase();
+var LEASES_DIR=path.join(BASE,'.kenaz','specialist','sessions','leases');
+var STREAM_ID_FILE=path.join(BASE,'.kenaz','specialist','current_stream.json');
+function ensureLeasesDir(){if(!fs.existsSync(LEASES_DIR))fs.mkdirSync(LEASES_DIR,{recursive:true});}
+function leasePath(sid){return path.join(LEASES_DIR,sid+'.json');}
+function isPidAlive(pid){
+  if(!pid||pid<=0)return false;
+  try{process.kill(pid,0);return true;}
+  catch(e){if(e.code==='EPERM')return true;return false;}
+}
+function heartbeatAgeMs(l){if(!l.heartbeat_at)return Infinity;return Date.now()-new Date(l.heartbeat_at).getTime();}
+function fmtAge(ms){if(ms===Infinity)return 'inf';if(ms<120000)return Math.round(ms/1000)+'s';if(ms<7200000)return Math.round(ms/60000)+'m';return (ms/3600000).toFixed(1)+'h';}
+// TASK_1792: liveness = heartbeat freshness ONLY (was: pid alive OR heartbeat fresh, TASK_1761).
+// The `isPidAlive(l.pid) ||` term was removed because it was a false-POSITIVE source, not the
+// false-negative safeguard the old comment claimed: the registered pid exits by design
+// (heartbeats are renewed by lease-touch.js on UserPromptSubmit), and Windows recycles pids
+// aggressively -- an unrelated short-lived process occupying the recorded pid made a dead
+// session probe "live" forever, so the lease could never satisfy cmdReap's !isSessionLive
+// filter (immortal lease). pid probing is also nondeterministic: observed 2026-07-25, `list`
+// said [live] while `reap` one second later classified the same lease stale. Heartbeat
+// freshness is the only reliable, deterministic signal. isPidAlive itself is correct and
+// stays exported for other consumers (claim markers, integration.js).
+// Threshold 8h (was 45min): heartbeats only advance on UserPromptSubmit, so a live session
+// running long dispatch chains without user input can legitimately idle for hours; at 45min
+// the boot banner suggested an executable `reap --session-id` against live peers. 8h covers
+// a realistic no-prompt working stretch, while a crash-orphaned lease (SessionEnd release
+// never fired) still ages out of gates within the same working day. Bulk reap floor stays 24h.
+var LIVENESS_THRESHOLD_MS=8*60*60*1000;
+function isSessionLive(l){if(!l)return false;return heartbeatAgeMs(l)<LIVENESS_THRESHOLD_MS;}
+var LABELS=['stream-A','stream-B','stream-C'];
+function assignLabel(ll){
+  var used=new Set(ll.map(function(x){return x.label;}));
+  for(var i=0;i<LABELS.length;i++){if(!used.has(LABELS[i]))return LABELS[i];}
+  return 'stream-'+String.fromCharCode('D'.charCodeAt(0)+ll.length-LABELS.length);
+}
+function readAllLeases(){
+  ensureLeasesDir();var files;
+  try{files=fs.readdirSync(LEASES_DIR).filter(function(f){return f.endsWith('.json');});}catch(e){return [];}
+  var r=[];for(var i=0;i<files.length;i++){try{r.push(JSON.parse(fs.readFileSync(path.join(LEASES_DIR,files[i]),'utf8')));}catch(e){}}return r;
+}
+function readLease(sid){try{return JSON.parse(fs.readFileSync(leasePath(sid),'utf8'));}catch(e){return null;}}
+// TASK_1764: look up lease by stable conversation_id anchor.
+function findLeaseByConversationId(convId){
+  if(!convId)return null;
+  var all=readAllLeases();
+  for(var i=0;i<all.length;i++){if(all[i].conversation_id===convId)return all[i];}
+  return null;
+}
+// TASK_1766 (BUG-8 fix) / TASK_1863 (shared by fresh + reuse register paths):
+// write per-conversation scratch_<convId>.json as identity anchor. This replaces
+// single-slot current_stream.json as bind source for lease-touch/stream-delta.
+// Written BEFORE current_stream -- both sessions can bind via their own scratch file
+// regardless of which session wins the current_stream overwrite race.
+// current_stream.json: kept for display/solo-legacy (not used for binding when scratch exists).
+// TASK_1764 (BUG-manual-register): only written when conversation_id is present
+// (ownership-anchored) OR forceStream (--scratch) is set.
+function writeIdentityAnchors(sid,label,pid,convId,startedAt,forceStream){
+  var SESSIONS_DIR=path.join(BASE,'.kenaz','specialist','sessions');
+  if(convId){
+    try{
+      if(!fs.existsSync(SESSIONS_DIR))fs.mkdirSync(SESSIONS_DIR,{recursive:true});
+      var scratchFile=path.join(SESSIONS_DIR,'scratch_'+convId+'.json');
+      fs.writeFileSync(scratchFile,JSON.stringify({session_id:sid,conversation_id:convId,pid:pid,started_at:startedAt},null,2),'utf8');
+    }catch(e){}
+  }
+  if(convId||forceStream){
+    try{fs.writeFileSync(STREAM_ID_FILE,JSON.stringify({session_id:sid,label:label,pid:pid,conversation_id:convId,started_at:startedAt},null,2),'utf8');}catch(e){}
+  }else{
+    try{process.stderr.write('[stream-lease] WARNING: register without --conversation-id; current_stream.json NOT updated (use --scratch to force)\n');}catch(e){}
+  }
+}
+function cmdRegister(args){
+  var sid=args['session-id']||args['session_id'];
+  if(!sid){process.stderr.write('register: --session-id required\n');process.exit(1);}
+  var pid=isNaN(parseInt(args['pid'],10))?process.ppid:parseInt(args['pid'],10);
+  var convId=args['conversation-id']||args['conversation_id']||null;
+  // TASK_1983 (R1): the project this session is working on. Lease files carried
+  // no project association before this -- the "active projects" set (features/
+  // session/active_projects.rs on the Rust side) is defined as the projects with
+  // a LIVE lease, so a lease that cannot name its project cannot be counted.
+  // Optional for back-compat: a lease written by a caller that never passes
+  // --project-path simply has no project_path field and is skipped by readers
+  // that need one (see active_projects.rs's LeaseFile contract).
+  var projectPath=args['project-path']||args['project_path']||null;
+  ensureLeasesDir();
+  // TASK_1863: re-registering within the SAME conversation must not mint a new
+  // stream lease. Boot scripts (ansuz-boot-fast) register on every run; the
+  // script's process exits immediately but the fresh lease stays heartbeat-live
+  // for LIVENESS_THRESHOLD_MS (8h) -- a ghost stream that pollutes the
+  // Multi-Ansuz banner and feeds the same-task/scope gate as a live peer
+  // (measured 2026-08-13: 4 ghosts at 11h+ age; the leaked claim_TASK_1861
+  // owner was such a ghost). conversation_id is the stable identity anchor
+  // (TASK_1764): reuse the existing lease -- keep its session_id, label and
+  // claimed/scope state, refresh heartbeat/pid/phase/theme.
+  var existing=convId?findLeaseByConversationId(convId):null;
+  // Keep the registering/reused session even when resuming after days away.
+  reapExpiredLeases([sid,existing&&existing.session_id]);
+  if(existing){
+    var rnow=new Date().toISOString();
+    existing.heartbeat_at=rnow;
+    existing.pid=pid;
+    if(args['phase'])existing.phase=args['phase'];
+    if(args['theme'])existing.theme=args['theme'];
+    if(projectPath)existing.project_path=projectPath;
+    try{fs.writeFileSync(leasePath(existing.session_id),JSON.stringify(existing,null,2),'utf8');}catch(e){}
+    writeIdentityAnchors(existing.session_id,existing.label,pid,convId,existing.started_at||rnow,false);
+    process.stdout.write('registered '+existing.session_id+' as '+(existing.label||existing.session_id)+' (reused: conversation already holds this lease)\n');
+    return;
+  }
+  var liveEx=readAllLeases().filter(function(l){return l.session_id!==sid&&isSessionLive(l);});
+  var label=assignLabel(liveEx);var now=new Date().toISOString();
+  var lease={session_id:sid,pid:pid,conversation_id:convId,
+    label:label,theme:args['theme']||null,started_at:now,heartbeat_at:now,
+    claimed_tasks:[],scope_leases:[],resource_leases:[],phase:args['phase']||null,
+    project_path:projectPath};
+  fs.writeFileSync(leasePath(sid),JSON.stringify(lease,null,2),'utf8');
+  var scratch=('scratch' in args)||args['scratch']===true;
+  writeIdentityAnchors(sid,label,pid,convId,now,scratch);
+  process.stdout.write('registered '+sid+' as '+label+'\n');
+}
+function cmdTouch(args){
+  var sid=args['session-id']||args['session_id'];
+  if(!sid){process.stderr.write('touch: --session-id required\n');process.exit(1);}
+  var lease=readLease(sid);if(!lease)return;
+  lease.heartbeat_at=new Date().toISOString();
+  // M1.5 (TASK_1761): optional --pid to refresh anchor (hook passes process.ppid = harness pid)
+  if(args['pid']){var np=parseInt(args['pid'],10);if(!isNaN(np)&&np>0)lease.pid=np;}
+  // TASK_1983 (R1): touch fires every UserPromptSubmit with CLAUDE_PROJECT_DIR readily
+  // available (lease-touch.js) -- self-heals project_path if register never set it,
+  // and follows a session that later moves to a different project (rare but possible).
+  var touchProjectPath=args['project-path']||args['project_path'];
+  if(touchProjectPath)lease.project_path=touchProjectPath;
+  try{fs.writeFileSync(leasePath(sid),JSON.stringify(lease,null,2),'utf8');}catch(e){}
+}
+function cmdRelease(args){
+  var sid=args['session-id']||args['session_id'];
+  if(!sid){process.stderr.write('release: --session-id required\n');process.exit(1);}
+  try{fs.unlinkSync(leasePath(sid));}catch(e){}
+  try{if(fs.existsSync(STREAM_ID_FILE)){var cur=JSON.parse(fs.readFileSync(STREAM_ID_FILE,'utf8'));if(cur.session_id===sid)fs.unlinkSync(STREAM_ID_FILE);}}catch(e){}
+}
+function cmdList(args){
+  var leases=readAllLeases();
+  var annotated=leases.map(function(l){var ageMs=heartbeatAgeMs(l);var obj=JSON.parse(JSON.stringify(l));obj._live=isSessionLive(l);obj._heartbeat_age=ageMs===Infinity?Infinity:Math.round(ageMs/1000);return obj;});
+  if(args['format']==='json'){process.stdout.write(JSON.stringify(annotated,null,2)+'\n');return;}
+  if(annotated.length===0){process.stdout.write('(no leases)\n');return;}
+  for(var i=0;i<annotated.length;i++){
+    var l=annotated[i];var status=l._live?'live':'stale';
+    var age=fmtAge(l._heartbeat_age===Infinity?Infinity:l._heartbeat_age*1000);
+    var tasks=(l.claimed_tasks&&l.claimed_tasks.length)?'  tasks='+l.claimed_tasks.join(','): '';
+    process.stdout.write('['+status+'] '+( l.label||l.session_id)+'  pid='+l.pid+'  heartbeat='+age+' ago'+tasks+'\n');
+  }
+}
+var REAP_THRESHOLD_MS=24*60*60*1000;
+// Automatic maintenance is stricter than manual reap: unknown timestamps and
+// current identity anchors are retained. Re-read before unlink so a heartbeat
+// renewed since the initial directory scan is not deleted.
+function reapExpiredLeases(protectedIds){
+  var protectedSet=new Set(protectedIds||[]);
+  try{protectedSet.add(JSON.parse(fs.readFileSync(STREAM_ID_FILE,'utf8')).session_id);}catch(e){}
+  var removed=[];
+  readAllLeases().forEach(function(l){
+    var sid=l&&l.session_id;
+    if(typeof sid!=='string'||!sid||sid==='.'||sid==='..'||/[\\/]/.test(sid)||protectedSet.has(sid))return;
+    var age=heartbeatAgeMs(l);
+    if(!Number.isFinite(age)||age<REAP_THRESHOLD_MS||isSessionLive(l))return;
+    var fresh=readLease(sid);
+    if(!fresh||fresh.session_id!==sid)return;
+    var freshAge=heartbeatAgeMs(fresh);
+    if(!Number.isFinite(freshAge)||freshAge<REAP_THRESHOLD_MS||isSessionLive(fresh))return;
+    try{fs.unlinkSync(leasePath(sid));removed.push(sid);}catch(e){}
+  });
+  return removed;
+}
+// TASK_2246: unlink + verify. A swallowed unlink error printed 'reaped' for a lease that survived
+// (Windows EBUSY/EPERM from antivirus or a concurrent hook read). ENOENT = already gone = success.
+function unlinkLeaseVerified(key,label){
+  var err=null;
+  try{fs.unlinkSync(leasePath(key));}catch(e){err=e;}
+  if(fs.existsSync(leasePath(key))){
+    process.stderr.write('reap: FAILED to remove lease '+(label||key)+' ('+key+'.json)'+(err?': '+(err.code||err.message):'')+' -- it still exists\n');
+    process.exitCode=1;return false;
+  }
+  return true;
+}
+function cmdReap(args){
+  var dryRun=('dry-run' in args)||args['dry-run']===true;
+  // TASK_1791: targeted reap -- clears ONE specific stale lease with no 24h age floor.
+  // Safe: isSessionLive guard refuses any live session (heartbeat within LIVENESS_THRESHOLD_MS,
+  // TASK_1792: 8h, heartbeat-only), so an open-but-idle session cannot be reaped. This closes
+  // the liveness-24h dead zone where the boot banner flagged a stale lease but bulk reap said
+  // '(nothing to reap)'.
+  // TASK_1792 follow-up: --force escape hatch. LIVENESS_THRESHOLD_MS also gates the claim
+  // gate (dispatch.js) and task ownership (task-api.js), so a hard-crashed session -- one
+  // whose SessionEnd release never fired -- holds its claims and scope leases for the full
+  // 8h, and the guard above refuses to clear it because it still reads as live. --force is
+  // the deliberate human override for exactly that case. It is intentionally NOT accepted
+  // by bulk reap: overriding liveness must always name one specific session.
+  var force=('force' in args)||args['force']===true;
+  var sid=args['session-id']||args['session_id'];
+  if(sid&&sid!==true){
+    var one=readLease(sid);
+    if(!one){process.stdout.write('(no lease for session '+sid+')\n');return;}
+    if(isSessionLive(one)&&!force){process.stdout.write('refused: '+(one.label||sid)+' is live (heartbeat within '+fmtAge(LIVENESS_THRESHOLD_MS)+') -- not reaping. If this session is known dead (crashed without releasing), re-run with --force\n');process.exitCode=1;return;}
+    if(isSessionLive(one)&&force){process.stdout.write('warning: '+(one.label||sid)+' still reads as live (heartbeat '+fmtAge(heartbeatAgeMs(one))+' ago) -- forcing\n');}
+    var oneAge=fmtAge(heartbeatAgeMs(one));
+    if(dryRun){process.stdout.write('[dry-run] would reap '+(one.label||sid)+'  heartbeat='+oneAge+' ago\n');return;}
+    // TASK_2246: unlink by the lookup key (the filename readLease read), not the file-content session_id.
+    if(unlinkLeaseVerified(sid,one.label))process.stdout.write('reaped '+(one.label||sid)+'\n');
+    return;
+  }
+  // TASK_2246: bulk reap never overrides liveness (see comment above) -- reject instead of silently ignoring.
+  if(force){process.stderr.write('reap: --force is not accepted by bulk reap; name one session with --session-id=<sid> --force\n');process.exitCode=1;return;}
+  var staleAll=readAllLeases().filter(function(l){return !isSessionLive(l);});
+  var stale=staleAll.filter(function(l){return heartbeatAgeMs(l)>=REAP_THRESHOLD_MS;});
+  if(stale.length===0){
+    if(staleAll.length>0){
+      // Dead-zone guidance (TASK_1791): stale leases exist but are below the 24h bulk threshold.
+      process.stdout.write('(nothing to reap -- '+staleAll.length+' stale lease(s) below the 24h bulk threshold)\n');
+      for(var j=0;j<staleAll.length;j++){var s=staleAll[j];
+        process.stdout.write('  [stale] '+(s.label||s.session_id)+'  heartbeat='+fmtAge(heartbeatAgeMs(s))+' ago -- clear now: node .specialist/tools/stream-lease.js reap --session-id='+s.session_id+'\n');}
+    }else{
+      process.stdout.write('(nothing to reap)\n');
+    }
+    return;
+  }
+  for(var i=0;i<stale.length;i++){var l=stale[i];var age=fmtAge(heartbeatAgeMs(l));
+    if(dryRun){process.stdout.write('[dry-run] would reap '+( l.label||l.session_id)+'  heartbeat='+age+' ago\n');}
+    else if(unlinkLeaseVerified(l.session_id,l.label)){process.stdout.write('reaped '+( l.label||l.session_id)+'\n');}
+  }
+}
+function parseArgs(argv){var args={};for(var i=0;i<argv.length;i++){var av=argv[i];if(av.indexOf('--')===0){var eq=av.indexOf('=');if(eq===-1)args[av.slice(2)]=true;else args[av.slice(2,eq)]=av.slice(eq+1);}}return args;}
+function cmdResourceRelease(args){
+  var name=args['name'];if(!name){process.stderr.write('resource-release: --name=<resource-name> required\n');process.exit(1);}
+  var lockPath=require('path').join(BASE,'.kenaz','locks','resource_'+name+'.lock');
+  try{require('fs').unlinkSync(lockPath);process.stdout.write('released resource lock: '+name+'\n');}
+  catch(e){if(e.code!=='ENOENT'){process.stderr.write('resource-release error: '+e.message+'\n');process.exit(1);}else{process.stdout.write('(resource lock not found: '+name+')\n');}}
+}
+
+function main(){var cmd=process.argv[2];var args=parseArgs(process.argv.slice(3));switch(cmd){
+  case 'register':return cmdRegister(args);
+  case 'touch':return cmdTouch(args);
+  case 'release':return cmdRelease(args);
+  case 'list':return cmdList(args);
+  case 'reap':return cmdReap(args);
+  case 'resource-release':return cmdResourceRelease(args);
+  default:process.stderr.write('Usage: stream-lease.js register|touch|release|list|reap|resource-release [--options]\n       reap [--dry-run]                          bulk: clears leases idle >=24h\n       reap --session-id=<sid> [--dry-run]       targeted: clears one stale lease, refuses live\n       reap --session-id=<sid> --force           override the live guard (crashed session)\n');process.exit(1);
+}}
+if(require.main===module)main();
+module.exports={resolveBase:resolveBase,isPidAlive:isPidAlive,heartbeatAgeMs:heartbeatAgeMs,fmtAge:fmtAge,isSessionLive:isSessionLive,LIVENESS_THRESHOLD_MS:LIVENESS_THRESHOLD_MS,REAP_THRESHOLD_MS:REAP_THRESHOLD_MS,reapExpiredLeases:reapExpiredLeases,readAllLeases:readAllLeases,readLease:readLease,findLeaseByConversationId:findLeaseByConversationId,LEASES_DIR:LEASES_DIR,STREAM_ID_FILE:STREAM_ID_FILE};

package/core/.specialist/tools/task-bridge-jev.test.js

@@ -0,0 +1,170 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const { loadOptionalContext } = require('./jev-optional-context');
+
+function bridgeFixture(loader, effects, reqOverrides = {}, stdoutWrite = text => effects.push({ type: 'stdout', text })) {
+  const module = { exports: {} };
+  vm.runInNewContext(fs.readFileSync(path.join(__dirname, 'task-bridge.js'), 'utf8'), {
+    module, __dirname, console,
+    process: { argv: [], env: {}, cwd: () => path.resolve('.'), stdout: { write: text => stdoutWrite(text) } },
+    require(id) {
+      if (Object.prototype.hasOwnProperty.call(reqOverrides, id)) return reqOverrides[id];
+      if (id === 'path') return path;
+      if (id === 'fs') return {};
+      if (id === 'os') return require('node:os'); // TASK_1977 R2: jev session-state dir (os.tmpdir())
+      if (id.endsWith('task-api.js')) return { TaskAPI: class { constructor() { assert.fail('unexpected task API'); } } };
+      if (id === './jev-optional-context') return { loadOptionalContext: loader };
+      assert.fail(`unexpected dependency ${id}`);
+    },
+  });
+  return module.exports;
+}
+
+test('actual bridge awaits loaded DATA after reminder, preserves original empty/error workflow', async () => {
+  const effects = [], received = [];
+  const bridge = bridgeFixture(async args => {
+    received.push(args); await new Promise(resolve => setTimeout(resolve, 5));
+    return { context: 'OPTIONAL_DATA\n' };
+  }, effects);
+  const project = path.resolve('selected-project');
+  await bridge.handleHookEvent({ hook_event_name: 'UserPromptSubmit', project_path: project, specialist: 'Ansuz', prompt: 'plan work' });
+  assert.match(effects[0].text, /Task Bridge/);
+  assert.equal(effects[1].text, 'OPTIONAL_DATA\n');
+  assert.equal(received[0].projectPath, project);
+  assert.equal(received[0].specialist, 'Ansuz');
+  for (const loader of [async () => ({ context: '' }), async () => { throw new Error('offline'); }]) {
+    const output = [], fallback = bridgeFixture(loader, output);
+    await fallback.handleHookEvent({ hook_event_name: 'UserPromptSubmit', prompt: 'hello' });
+    assert.deepEqual(output, []);
+  }
+  await bridge.handleHookEvent({ hook_event_name: 'Stop' });
+  assert.equal(received.length, 1);
+});
+
+test('actual native main -> bridge -> loader emits locally ranked DATA before exit using pinned project', async t => {
+  const root = fs.mkdtempSync(path.resolve('.kenaz/jev-bridge-test-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  fs.writeFileSync(path.join(root, 'reference.txt'), 'SYNTHETIC_LOCAL_REFERENCE');
+  const effects = [], requests = [];
+  const project = path.resolve('selected-project'), cwd = path.resolve('unrelated-cwd');
+  const bridge = bridgeFixture(args => loadOptionalContext(args, {
+    coreRoot: root, enabled: selected => selected === project,
+    catalog: [{ id: 'reference', source: 'reference.txt', purpose: 'Static supplemental reference purpose' }],
+    postRank: async payload => { requests.push(payload); await new Promise(resolve => setTimeout(resolve, 10)); return { status: 'ranked', orderedIds: ['reference'], scores: [3] }; }, // scores required since a4276eef2 (relevance floor)
+  }), effects, {}, text => shimContext.process.stdout.write(text)); // real path: bridge writes through the shim's wrapped stdout
+  const shimDir = path.resolve(__dirname, '../../.formation/bifrost/openai');
+  const input = Buffer.from(JSON.stringify({ hook_event_name: 'UserPromptSubmit', cwd, prompt: 'explain this feature' }));
+  let consumed = false, finish;
+  const exited = new Promise(resolve => { finish = resolve; });
+  // The shim runs main() only as the entry script (TASK_2299: `require.main === module`).
+  const shimModule = { exports: {} };
+  const shimContext = {
+    __dirname: shimDir, Buffer, console, module: shimModule,
+    process: { env: { KENAZ_CONSOLIDATE_ROOT: project }, cwd: () => cwd,
+      stdout: { write: () => true }, stderr: { write: () => true }, // the shim wraps stdout.write to capture bridge output
+      exit: code => { effects.push({ type: 'exit', code }); finish(); } },
+    require(id) {
+      if (id === 'path') return path;
+      if (id === 'fs') return {
+        readSync: (_fd, target) => { if (consumed) return 0; consumed = true; input.copy(target); return input.length; },
+        // TASK_2299: the shim folds captured bridge output into ONE hookSpecificOutput JSON on fd 1
+        writeSync: (fd, out) => { assert.equal(fd, 1); effects.push({ type: 'stdout', text: JSON.parse(out).hookSpecificOutput.additionalContext }); },
+      };
+      if (id === 'http' || id === 'child_process') return {}; // shim requires both at load (TASK_2299 peer pull)
+      if (id.endsWith('_peer-project-root.js')) return { resolvePeerProjectRoot: dir => dir }; // peer pull is env-gated off here
+      if (id.endsWith('task-bridge.js')) return bridge;
+      if (id.endsWith('consolidate.js')) return { runStopConsolidation: () => assert.fail('unexpected Stop') };
+      assert.fail(`unexpected dependency ${id}`);
+    },
+  };
+  shimContext.require.main = shimModule;
+  vm.runInNewContext(fs.readFileSync(path.join(shimDir, 'codex-hook-shim.js'), 'utf8'), shimContext);
+  await exited;
+  assert.equal(requests[0].projectPath, project);
+  assert.equal(requests[0].taskContext, 'explain this feature');
+  assert.ok(!JSON.stringify(requests).includes('SYNTHETIC_LOCAL_REFERENCE'));
+  assert.equal(effects[0].type, 'stdout');
+  assert.match(effects[0].text, /SYNTHETIC_LOCAL_REFERENCE/);
+  assert.match(effects[0].text, /reference DATA/);
+  assert.equal(effects[1].type, 'exit');
+  assert.equal(effects[1].code, 0);
+});
+
+// TASK_1977 R2/R4(c): the "Optional local reference DATA" block should only
+// be re-emitted when the selected reference id set changes for a session (or
+// on that session's first prompt). Uses the REAL fs/os so state persists
+// across handleHookEvent calls the way it does in production (each hook
+// invocation is a fresh process reading/writing the same tmpdir file).
+test('jev DATA block emits only when the selected reference id set changes for a session', async t => {
+  const realFs = require('node:fs');
+  const realOs = require('node:os');
+  const stateDir = path.join(realOs.tmpdir(), 'kenaz-jev-session-state');
+  const sessionId = `t1977-${process.pid}-${Date.now()}`;
+  const otherSessionId = `${sessionId}-other`;
+  t.after(() => {
+    for (const id of [sessionId, otherSessionId]) {
+      try { realFs.unlinkSync(path.join(stateDir, `${id}.json`)); } catch { /* already gone */ }
+    }
+  });
+
+  let selectedIds = ['a', 'b'];
+  const loader = async () => ({ context: 'DATA_1\n', selectedIds });
+
+  // Turn 1: first prompt of this session -> no prior state -> emits.
+  const t1 = [];
+  await bridgeFixture(loader, t1, { fs: realFs, os: realOs })
+    .handleHookEvent({ hook_event_name: 'UserPromptSubmit', session_id: sessionId, prompt: 'first' });
+  assert.deepEqual(t1.map(e => e.text), ['DATA_1\n']);
+
+  // Turn 2: identical selection -> no re-emit.
+  const t2 = [];
+  await bridgeFixture(loader, t2, { fs: realFs, os: realOs })
+    .handleHookEvent({ hook_event_name: 'UserPromptSubmit', session_id: sessionId, prompt: 'second' });
+  assert.deepEqual(t2, []);
+
+  // Turn 3: changed selection (order-independent set comparison: same members,
+  // different order should NOT count as changed on its own -- verify via a
+  // genuinely different set) -> emits again.
+  selectedIds = ['b', 'c'];
+  const loader2 = async () => ({ context: 'DATA_2\n', selectedIds });
+  const t3 = [];
+  await bridgeFixture(loader2, t3, { fs: realFs, os: realOs })
+    .handleHookEvent({ hook_event_name: 'UserPromptSubmit', session_id: sessionId, prompt: 'third' });
+  assert.deepEqual(t3.map(e => e.text), ['DATA_2\n']);
+
+  // Turn 4: SAME set as turn 3 but reordered by the ranker -> still no re-emit
+  // (comparison is by set membership, not rank order).
+  selectedIds = ['c', 'b'];
+  const loader3 = async () => ({ context: 'DATA_2\n', selectedIds });
+  const t4 = [];
+  await bridgeFixture(loader3, t4, { fs: realFs, os: realOs })
+    .handleHookEvent({ hook_event_name: 'UserPromptSubmit', session_id: sessionId, prompt: 'fourth' });
+  assert.deepEqual(t4, []);
+
+  // New session, same selection as turn 4 -> emits (first prompt of THAT session).
+  const t5 = [];
+  await bridgeFixture(loader3, t5, { fs: realFs, os: realOs })
+    .handleHookEvent({ hook_event_name: 'UserPromptSubmit', session_id: otherSessionId, prompt: 'fifth' });
+  assert.deepEqual(t5.map(e => e.text), ['DATA_2\n']);
+});
+
+// TASK_1977 R2: existing fallbacks (OFF/missing_key/timeout/invalid -> empty
+// context) are untouched by the session-gating -- no session state file is
+// ever written when there's nothing to emit.
+test('jev empty-context fallbacks are unaffected by session gating', async t => {
+  const realFs = require('node:fs');
+  const realOs = require('node:os');
+  const stateDir = path.join(realOs.tmpdir(), 'kenaz-jev-session-state');
+  const sessionId = `t1977-empty-${process.pid}-${Date.now()}`;
+  t.after(() => { try { realFs.unlinkSync(path.join(stateDir, `${sessionId}.json`)); } catch { /* already gone */ } });
+
+  const effects = [];
+  await bridgeFixture(async () => ({ context: '' }), effects, { fs: realFs, os: realOs })
+    .handleHookEvent({ hook_event_name: 'UserPromptSubmit', session_id: sessionId, prompt: 'hello' });
+  assert.deepEqual(effects, []);
+  assert.equal(realFs.existsSync(path.join(stateDir, `${sessionId}.json`)), false);
+});