@getopencrawl/cli 0.1.0 → 0.1.1

package/src/capture.test.mjs

@@ -0,0 +1,171 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { validateCaptureReceipt } from './capture.mjs';
+
+const SCRIPT=fileURLToPath(new URL('../bin/opencrawl.mjs',import.meta.url));
+const identity={user:{id:'usr_'+'a'.repeat(32)},workspace:{id:'ws_'+'b'.repeat(32)}};
+const doc='doc_'+'c'.repeat(32),key='oc_synthetic_capture';
+function run(args,env,cwd,input='') {
+  return new Promise((resolve,reject)=>{
+    const child=spawn(process.execPath,[SCRIPT,...args],{env,cwd,stdio:['pipe','pipe','pipe']});let stdout='',stderr='';
+    const timer=setTimeout(()=>child.kill('SIGKILL'),15000);
+    child.stdout.on('data',chunk=>stdout+=chunk);child.stderr.on('data',chunk=>stderr+=chunk);
+    child.on('error',reject);child.on('close',code=>{clearTimeout(timer);resolve({code,stdout,stderr});});child.stdin.end(input);
+  });
+}
+async function fixture(t,{provider='codex',capture=true,environment=false}={}) {
+  const dir=await fs.mkdtemp(path.join(os.tmpdir(),'oc-capture-')),config=path.join(dir,'config'),project=path.join(dir,'project');await fs.mkdir(project);
+  const env={...process.env};for(const name of Object.keys(env))if(name.startsWith('OPENCRAWL_'))delete env[name];env.OPENCRAWL_CONFIG_DIR=config;
+  const calls=[],sessions=new Map();let behavior='ok',who=identity;
+  const server=http.createServer(async(req,res)=>{
+    let raw='';for await(const chunk of req)raw+=chunk;const body=raw?JSON.parse(raw):null;calls.push({route:req.url,body});
+    const reply=(status,value)=>{res.writeHead(status,{'Content-Type':'application/json'});res.end(JSON.stringify(value));};
+    if(req.headers.authorization!=='Bearer '+key)return reply(401,{detail:'PRIVATE_PROVIDER_ERROR'});
+    if(req.url==='/api/auth/me')return reply(200,who);
+    if(req.url==='/api/v1/context')return reply(200,{context:'[S1] Earlier synthetic evidence'});
+    if(req.url==='/mcp')return reply(200,{jsonrpc:'2.0',id:body.id,result:{tools:[]}});
+    if(req.url==='/api/v1/sessions/events') {
+      if(['401','403','409','410','413','422','429','500'].includes(behavior))return reply(Number(behavior),{detail:{code:'synthetic',message:'PRIVATE_PROVIDER_ERROR'}});
+      let rows=sessions.get(body.session_id)||new Map(),accepted=0,replayed=0;
+      for(const event of body.events){const prior=rows.get(event.id);if(prior){if(JSON.stringify(prior)!==JSON.stringify(event))return reply(409,{detail:'changed'});replayed++;}else{rows.set(event.id,event);accepted++;}}
+      sessions.set(body.session_id,rows);
+      if(behavior==='lost'){req.socket.destroy();return;}
+      return reply(200,{document_id:doc,lexical_ready:true,semantic_ready:false,semantic:{status:'pending',indexed_chunks:0,total_chunks:1},event_count:rows.size,accepted_events:accepted,replayed_events:replayed});
+    }
+    if(req.url.startsWith('/api/v1/sessions/events/status?')) {
+      if(behavior==='slow_status')await new Promise(resolve=>setTimeout(resolve,1000));
+      if(behavior==='500')return reply(500,{detail:'PRIVATE_PROVIDER_ERROR'});
+      if(behavior==='410')return reply(410,{detail:{code:'session_deleted',message:'Deleted'}});
+      const rows=sessions.get(new URL(req.url,'http://localhost').searchParams.get('session_id'));
+      return rows?reply(200,{document_id:doc,lexical_ready:true,semantic_ready:true,semantic:{status:'ready',indexed_chunks:1,total_chunks:1},event_count:rows.size}):reply(404,{detail:'Unknown'});
+    }
+    reply(404,{});
+  });await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve));const url='http://127.0.0.1:'+server.address().port;
+  t.after(async()=>{await new Promise(resolve=>server.close(resolve));await fs.rm(dir,{recursive:true,force:true});});
+  let bound;
+  if(environment){env.OPENCRAWL_TEST_CAPTURE_KEY=key;bound=['--credential-env','OPENCRAWL_TEST_CAPTURE_KEY','--server',url];}
+  else {assert.equal((await run(['login','--server',url],env,project,key+'\n')).code,0);bound=[];}
+  const installed=await run(['install',provider,...(capture?['--capture']:[]),...bound],env,project);assert.equal(installed.code,0,installed.stderr);
+  const settingsFile=path.join(project,provider==='codex'?'.codex/hooks.json':'.claude/settings.local.json');
+  let hooks={};try{hooks=JSON.parse(await fs.readFile(settingsFile,'utf8')).hooks||{};}catch(error){if(error.code!=='ENOENT')throw error;}
+  const entry=hooks.UserPromptSubmit?.flatMap(group=>group.hooks).find(hook=>hook.command.includes('opencrawl-managed-capture'));
+  const configValue=environment?null:JSON.parse(await fs.readFile(path.join(config,'config.json')));
+  const args=environment?[...bound,'--expect-user',identity.user.id,'--expect-workspace',identity.workspace.id]:['--account',configValue.activeProfile,'--server',url];
+  const command=(name,...rest)=>run([name,...rest,...args],env,project);
+  const hook=(event,extra={},overrides={})=>run(['capture-hook','--provider',provider,'--project',project,...args],{...env,...overrides},project,JSON.stringify({session_id:'synthetic-session',turn_id:'turn-1',cwd:project,hook_event_name:event,...extra}));
+  const readState=async()=>{const file=(await fs.readdir(path.join(config,'capture'))).find(value=>value.endsWith('.json'));const location=path.join(config,'capture',file);return{file:location,value:JSON.parse(await fs.readFile(location))};};
+  return{dir,config,project,env,url,args,calls,sessions,hooks,entry,installed,command,hook,readState,setBehavior:value=>behavior=value,setIdentity:value=>who=value};
+}
+
+test('retrieval-only installs do not create capture hooks or spool',async t=>{
+  const f=await fixture(t,{capture:false});assert.equal(f.entry,undefined);await assert.rejects(fs.stat(path.join(f.config,'capture')),{code:'ENOENT'});
+});
+for(const provider of ['claude-code','codex'])test(`${provider} capture install is private, pinned, idempotent and preserves other hooks`,async t=>{
+  const f=await fixture(t,{provider});assert.ok(f.entry);assert.equal(f.entry.timeout,10);assert.ok(f.hooks.Stop);
+  assert.ok(f.entry.command.includes('--account')&&f.entry.command.includes('--project')&&!f.entry.command.includes(key));
+  const file=path.join(f.project,provider==='codex'?'.codex/hooks.json':'.claude/settings.local.json');const settings=JSON.parse(await fs.readFile(file));settings.hooks.Stop.unshift({hooks:[{type:'command',command:'echo unrelated'}]});await fs.writeFile(file,JSON.stringify(settings));
+  assert.equal((await run(['install',provider,'--capture'],f.env,f.project)).code,0);
+  assert.equal((await run(['install',provider,'--capture'],f.env,f.project)).code,0);
+  const current=JSON.parse(await fs.readFile(file));assert.equal(current.hooks.Stop.flatMap(group=>group.hooks).length,2);assert.equal(current.hooks.Stop[0].hooks[0].command,'echo unrelated');
+  const state=await f.readState();assert.equal((await fs.stat(state.file)).mode&0o777,0o600);assert.equal(state.value.sessions.length,0);
+});
+test('prompt retrieves old evidence first then captures; Stop is quiet and deduplicated',async t=>{
+  const f=await fixture(t);f.calls.length=0;
+  const prompt=await f.hook('UserPromptSubmit',{prompt:'The synthetic user asks a question.'});assert.equal(prompt.code,0);assert.match(JSON.parse(prompt.stdout).hookSpecificOutput.additionalContext,/Earlier synthetic/);
+  assert.ok(f.calls.findIndex(call=>call.route==='/api/v1/context')<f.calls.findIndex(call=>call.route==='/api/v1/sessions/events'));
+  assert.deepEqual(JSON.parse((await f.hook('Stop',{last_assistant_message:'Synthetic final answer'})).stdout),{});
+  await f.hook('Stop',{last_assistant_message:'Synthetic final answer'});await f.hook('UserPromptSubmit',{prompt:'The synthetic user asks a question.'});
+  assert.equal([...f.sessions.values()][0].size,2);const state=(await f.readState()).value;
+  assert.equal(state.sessions[0].events.length,2);assert.ok(state.sessions[0].events.every(event=>event.content===undefined));
+  assert.equal(state.sessions[0].receipt.semantic_ready,false);
+  const result=await f.command('capture','status','--provider','codex','--json');const observed=JSON.parse(result.stdout);assert.equal(observed.sessions[0].last_acknowledgement.semantic_ready,true);assert.ok(!result.stdout.includes('Synthetic final answer'));
+});
+test('new Codex turns append stable distinct events even when prompt text repeats',async t=>{
+  const f=await fixture(t);for(const id of ['turn-1','turn-2']){await f.hook('UserPromptSubmit',{turn_id:id,prompt:'Same exact question'});await f.hook('Stop',{turn_id:id,last_assistant_message:'Same answer'});}
+  const rows=[...f.sessions.values()][0];assert.equal(rows.size,4);assert.deepEqual([...rows.values()].map(event=>event.sequence),[0,1,2,3]);
+});
+test('Claude pairs new prompts with Stop without reading transcript paths',async t=>{
+  const f=await fixture(t,{provider:'claude-code'});for(let index=0;index<2;index++){await f.hook('UserPromptSubmit',{turn_id:undefined,prompt:'Repeat prompt',transcript_path:'/does/not/exist'});await f.hook('Stop',{turn_id:undefined,last_assistant_message:'Repeat answer',transcript_path:'/does/not/exist'});await f.hook('Stop',{turn_id:undefined,last_assistant_message:'Repeat answer'});}
+  assert.equal([...f.sessions.values()][0].size,4);
+});
+test('different project cwd is rejected before retrieval or event publication',async t=>{
+  const f=await fixture(t);const other=path.join(f.dir,'other');await fs.mkdir(other);f.calls.length=0;
+  const result=await f.hook('UserPromptSubmit',{cwd:other,prompt:'PRIVATE_OTHER_PROJECT'});assert.equal(result.code,0);assert.deepEqual(JSON.parse(result.stdout),{});assert.equal(f.calls.length,0);assert.ok(!JSON.stringify((await f.readState()).value).includes('PRIVATE_OTHER_PROJECT'));
+});
+test('lost acknowledgement remains queued and explicit flush replays exact events once',async t=>{
+  const f=await fixture(t);f.setBehavior('lost');await f.hook('UserPromptSubmit',{prompt:'Durable synthetic event'});let state=(await f.readState()).value;
+  assert.equal(state.sessions[0].events[0].state,'queued');assert.equal(state.sessions[0].receipt,undefined);assert.equal([...f.sessions.values()][0].size,1);
+  f.setBehavior('ok');const result=await f.command('capture','flush','--provider','codex','--json');assert.equal(result.code,0,result.stderr);assert.equal([...f.sessions.values()][0].size,1);state=(await f.readState()).value;assert.equal(state.sessions[0].events[0].state,'acknowledged');
+  const posts=f.calls.filter(call=>call.route==='/api/v1/sessions/events');assert.deepEqual(posts[0].body,posts[1].body);
+});
+for(const status of ['409','410'])test(`${status} permanently blocks this session without recreating its ID`,async t=>{
+  const f=await fixture(t);f.setBehavior(status);await f.hook('UserPromptSubmit',{prompt:'Synthetic blocked event'});const before=f.calls.filter(call=>call.route==='/api/v1/sessions/events').length;
+  f.setBehavior('ok');const result=await f.command('capture','flush','--provider','codex','--json');assert.equal(result.code,1);await f.hook('Stop',{last_assistant_message:'No resurrection'});assert.equal(f.calls.filter(call=>call.route==='/api/v1/sessions/events').length,before);assert.ok(!result.stdout.includes('PRIVATE_PROVIDER_ERROR'));
+});
+test('capture pause prevents collection and resume starts only new hook messages',async t=>{
+  const f=await fixture(t);assert.equal((await f.command('capture','pause','--provider','codex')).code,0);await f.hook('UserPromptSubmit',{prompt:'Do not collect'});assert.equal((await f.readState()).value.sessions.length,0);
+  await f.command('capture','resume','--provider','codex');await f.hook('UserPromptSubmit',{prompt:'Collect this future message'});assert.equal([...f.sessions.values()][0].size,1);
+});
+test('deleted session remains permanently blocked through identity failure and recovery',async t=>{
+  const f=await fixture(t,{environment:true});f.setBehavior('410');await f.hook('UserPromptSubmit',{prompt:'Deleted synthetic session'});
+  const before=f.calls.filter(call=>call.route==='/api/v1/sessions/events').length;
+  f.setIdentity({...identity,user:{id:'usr_'+'d'.repeat(32)}});await f.hook('Stop',{last_assistant_message:'Must never be collected'});
+  assert.equal((await f.readState()).value.sessions[0].issue,'session_deleted');
+  f.setIdentity(identity);f.setBehavior('ok');await f.hook('UserPromptSubmit',{turn_id:'turn-2',prompt:'Must not restart deleted capture'});
+  const result=await f.command('capture','flush','--provider','codex','--json');assert.equal(result.code,1);
+  assert.equal(f.calls.filter(call=>call.route==='/api/v1/sessions/events').length,before);
+  const session=(await f.readState()).value.sessions[0];assert.equal(session.issue,'session_deleted');assert.equal(session.events.length,1);
+});
+test('environment install saves no key and rejects a changed account before sending content',async t=>{
+  const f=await fixture(t,{environment:true});assert.ok(f.entry.command.includes('--expect-user'));assert.ok(!f.entry.command.includes(key));await assert.rejects(fs.stat(path.join(f.config,'config.json')),{code:'ENOENT'});
+  for(const argument of ['capture','status','--provider','codex','--project',f.project,'--credential-env','OPENCRAWL_TEST_CAPTURE_KEY','--server',f.url,'--expect-user',identity.user.id,'--expect-workspace',identity.workspace.id])assert.ok(f.installed.stdout.includes(argument));
+  assert.ok(!f.installed.stdout.includes(key));
+  await f.hook('UserPromptSubmit',{prompt:'Initial synthetic event'});const before=f.calls.filter(call=>call.route==='/api/v1/sessions/events'||call.route==='/api/v1/context').length;
+  f.setIdentity({...identity,user:{id:'usr_'+'d'.repeat(32)}});await f.hook('Stop',{last_assistant_message:'Must stay locally queued'});assert.equal(f.calls.filter(call=>call.route==='/api/v1/sessions/events'||call.route==='/api/v1/context').length,before);
+  const result=await f.command('capture','flush','--provider','codex','--json');assert.equal(result.code,1);assert.ok(!result.stdout.includes(key));
+});
+test('missing environment key does not fall back and hooks remain nonblocking',async t=>{
+  const f=await fixture(t,{environment:true});f.calls.length=0;const result=await f.hook('UserPromptSubmit',{prompt:'No key'}, {OPENCRAWL_TEST_CAPTURE_KEY:''});assert.equal(result.code,0);assert.deepEqual(JSON.parse(result.stdout),{});assert.equal(f.calls.length,0);
+});
+test('environment-bound retrieval-only hook and MCP reject changed workspace before private queries',async t=>{
+  const f=await fixture(t,{environment:true,capture:false,provider:'claude-code'});
+  const prompt=JSON.stringify({prompt:'Private synthetic retrieval query'}),rpc='{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"opencrawl_search","arguments":{"query":"Private synthetic query"}}}\n';
+  assert.match((await f.command('hook')).stdout,/^$/);
+  assert.equal((await run(['mcp',...f.args],f.env,f.project,rpc)).code,0);
+  assert.ok((await run(['hook',...f.args],f.env,f.project,prompt)).stdout.includes('Earlier synthetic'));
+  f.setIdentity({...identity,workspace:{id:'ws_'+'e'.repeat(32)}});f.calls.length=0;
+  const hooked=await run(['hook',...f.args],f.env,f.project,prompt);assert.equal(hooked.code,0);assert.equal(hooked.stdout,'');
+  assert.equal((await run(['mcp',...f.args],f.env,f.project,rpc)).code,1);
+  assert.ok(f.calls.every(call=>call.route==='/api/auth/me'));
+});
+test('oversized messages and orphan Stop cannot create partial conversations',async t=>{
+  const f=await fixture(t);await f.hook('Stop',{last_assistant_message:'Orphan'});assert.equal(f.sessions.size,0);
+  const result=await f.hook('UserPromptSubmit',{prompt:'x'.repeat(65537)});assert.equal(result.code,0);assert.equal(f.sessions.size,0);assert.equal((await f.readState()).value.sessions.length,0);
+});
+test('invalid receipt does not establish indexing',()=>{
+  assert.throws(()=>validateCaptureReceipt({document_id:doc,lexical_ready:true,semantic_ready:false,semantic:{status:'pending',indexed_chunks:0,total_chunks:1},event_count:1,accepted_events:0,replayed_events:0},1));
+});
+test('status network wait releases capture lock for new hook events',async t=>{
+  const f=await fixture(t);await f.hook('UserPromptSubmit',{prompt:'First message'});f.setBehavior('slow_status');
+  const pending=f.command('capture','status','--provider','codex','--json');
+  for(let index=0;index<100&&!f.calls.some(call=>call.route.includes('/events/status?'));index++)await new Promise(resolve=>setTimeout(resolve,10));
+  const reply=await f.hook('Stop',{last_assistant_message:'Captured during a status request'});assert.equal(reply.stderr,'');assert.equal([...f.sessions.values()][0].size,2);assert.equal((await pending).code,0);
+});
+test('failed current verification cannot relabel historical acknowledgements as currently ready',async t=>{
+  const f=await fixture(t);await f.hook('UserPromptSubmit',{prompt:'Earlier acknowledged message'});f.setBehavior('500');
+  const result=await f.command('capture','status','--provider','codex','--json'),session=JSON.parse(result.stdout).sessions[0];
+  assert.equal(result.code,1);assert.equal(session.state,'verification_unavailable');assert.equal(session.last_acknowledgement.lexical_ready,true);assert.equal(session.current_verification.state,'unavailable');assert.ok(!result.stdout.includes('PRIVATE_PROVIDER_ERROR'));
+});
+test('encoded oversized control characters cannot leave an unsendable pending event',async t=>{
+  const f=await fixture(t);await f.hook('UserPromptSubmit',{prompt:'\u0001'.repeat(50000)});assert.equal(f.sessions.size,0);assert.equal((await f.readState()).value.sessions.length,0);
+});
+test('changed repeated event is blocked without silently replacing captured content',async t=>{
+  const f=await fixture(t);await f.hook('UserPromptSubmit',{prompt:'Original event'});await f.hook('UserPromptSubmit',{prompt:'Changed payload for same turn'});
+  const state=(await f.readState()).value;assert.equal(state.sessions[0].issue,'event_conflict');assert.equal([...f.sessions.values()][0].size,1);
+});

package/src/client.mjs

@@ -131,7 +131,12 @@ export async function createClient(overrides = {}) {
     try {
       response = await fetch(destination.href, { method, headers, body: body === undefined ? undefined : multipart ? body : JSON.stringify(body),
         signal: controller.signal, redirect: 'error' });
-    } catch (error) { throw new Error(error.name === 'TimeoutError' ? 'OpenCrawl request timed out.' : 'Cannot reach OpenCrawl. Check your server URL and connection.'); }
+    } catch (error) {
+      const failure=new Error(error.name === 'TimeoutError' ? 'OpenCrawl request timed out.' : 'Cannot reach OpenCrawl. Check your server URL and connection.');
+      // A user's own interruption is final; a lost connection or timeout may succeed on another try.
+      if(!signal?.aborted)failure.transient=true;
+      throw failure;
+    }
     if(responseType==='png'&&response.ok){
       const cap=2*1024*1024;if(response.headers.get('content-type')?.split(';')[0]?.trim()!=='image/png'||Number(response.headers.get('content-length'))>cap){await response.body?.cancel();throw new Error('Invalid bounded PNG response.');}
       const reader=response.body?.getReader();if(!reader)throw new Error('Missing PNG response.');const bytes=Buffer.alloc(cap);let length=0;const cancel=()=>{void reader.cancel().catch(()=>{});};if(controller.signal.aborted)cancel();else controller.signal.addEventListener('abort',cancel,{once:true});
@@ -154,10 +159,13 @@ export async function createClient(overrides = {}) {
       text=bytes.subarray(0,length).toString('utf8');
     } else text = await response.text();
     let value;
-    try { value = text ? JSON.parse(text) : null; } catch { throw new Error(`Server returned an unexpected response (${response.status}).`); }
+    try { value = text ? JSON.parse(text) : null; } catch {
+      // A proxy's error page (for example a 502 while the server restarts) is not JSON.
+      const failure=new Error(`Server returned an unexpected response (${response.status}).`);if(!response.ok)failure.status=response.status;throw failure;
+    }
     if (!response.ok) {
       const detail = typeof value?.detail === 'string' ? value.detail : typeof value?.error === 'string' ? value.error : response.statusText;
-      const error=new Error(`OpenCrawl ${response.status}: ${detail}`);error.status=response.status;
+      const error=new Error(`OpenCrawl ${response.status}: ${detail}`);error.status=response.status;error.detail=String(detail||'').slice(0,300);
       if (typeof value?.code === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(value.code)) error.code=value.code;
       throw error;
     }
@@ -167,9 +175,9 @@ export async function createClient(overrides = {}) {
 }
 export async function search(query, options = {}) {
   const client = await createClient(options);
-  return client.request('/api/v1/search', { method: 'POST', body: { query, limit: options.limit || 8, ...(options.source_ids === undefined ? {} : {source_ids: options.source_ids}) } });
+  return client.request('/api/v1/search', { method: 'POST', body: { query, limit: options.limit || 8, ...(options.source_ids === undefined ? {} : {source_ids: options.source_ids}), ...(options.customer ? {customer: options.customer} : {}) } });
 }
 export async function context(query, options = {}) {
   const client = await createClient(options);
-  return client.request('/api/v1/context', { method: 'POST', body: { query, limit: options.limit || 8, budget: options.budget || 2000, ...(options.source_ids === undefined ? {} : {source_ids: options.source_ids}) } });
+  return client.request('/api/v1/context', { method: 'POST', body: { query, limit: options.limit || 8, budget: options.budget || 2000, ...(options.source_ids === undefined ? {} : {source_ids: options.source_ids}), ...(options.customer ? {customer: options.customer} : {}) } });
 }

package/src/client.test.mjs

@@ -0,0 +1,34 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateBaseUrl, search, context } from './client.mjs';
+test('credentials are never accepted inside the server URL', () => {
+  assert.throws(() => validateBaseUrl('https://secret@example.com'));
+  assert.throws(() => validateBaseUrl('https://example.com?key=secret'));
+});
+test('exported retrieval helpers distinguish omitted scope from an explicit empty selection', async t => {
+  const bodies = [];
+  t.mock.method(globalThis, 'fetch', async (_url, options) => {
+    bodies.push(JSON.parse(options.body));
+    return new Response('{}', {headers: {'content-type': 'application/json'}});
+  });
+  for (const invoke of [search, context]) {
+    const options = {server: 'https://example.test', token: 'oc_synthetic'};
+    await invoke('question', options);
+    assert.equal(Object.hasOwn(bodies.at(-1), 'source_ids'), false);
+    await invoke('question', {...options, source_ids: []});
+    assert.deepEqual(bodies.at(-1).source_ids, []);
+    await invoke('question', {...options, source_ids: ['src_alpha']});
+    assert.deepEqual(bodies.at(-1).source_ids, ['src_alpha']);
+  }
+});
+test('remote hosts require transport encryption', () => {
+  assert.throws(() => validateBaseUrl('http://example.com'));
+  assert.equal(validateBaseUrl('http://127.0.0.1:8000/'), 'http://127.0.0.1:8000');
+  assert.equal(validateBaseUrl('https://opencrawl.example/'), 'https://opencrawl.example');
+});
+test('PNG transport is bounded, authenticated and cancellation-aware',async t=>{
+ const {createClient}=await import('./client.mjs'),fs=await import('node:fs/promises');const f=JSON.parse(await fs.readFile(new URL('./fixtures/product-monitor-contract.json',import.meta.url)));const png=Buffer.from(f.capture_request.screenshot_png_base64,'base64'),calls=[];
+ t.mock.method(globalThis,'fetch',async(url,o)=>{calls.push([url,o]);return new Response(png,{headers:{'content-type':'image/png'}});});const c=await createClient({server:'https://api.example',token:'synthetic-token'});assert.deepEqual(await c.request('/api/v1/product-monitors/snapshots/fixture/image',{responseType:'png'}),png);assert.equal(calls[0][1].headers.Accept,'image/png');assert.equal(calls[0][1].redirect,'error');assert.equal(calls[0][1].headers.Authorization,'Bearer synthetic-token');
+ t.mock.method(globalThis,'fetch',async()=>new Response(new Uint8Array(2097153),{headers:{'content-type':'image/png'}}));await assert.rejects(c.request('/api/v1/product-monitors/snapshots/fixture/image',{responseType:'png'}),/limit/);
+ let cancelled=false;const abort=new AbortController();t.mock.method(globalThis,'fetch',async()=>new Response(new ReadableStream({start(){setTimeout(()=>abort.abort(),10);},cancel(){cancelled=true}}),{headers:{'content-type':'image/png'}}));await assert.rejects(c.request('/api/v1/product-monitors/snapshots/fixture/image',{responseType:'png',signal:abort.signal}),/cancelled/);assert.equal(cancelled,true);
+});

package/src/connect.test.mjs

@@ -0,0 +1,131 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {connectCommand,connectRequest} from './connect.mjs';
+
+const id='src_'+'a'.repeat(32),user='usr_'+'b'.repeat(32),workspace='ws_'+'c'.repeat(32),nonce='n'.repeat(43);
+const job=()=>({id:'job_'+'d'.repeat(32),status:'queued',kind:'sync',source_id:id});
+const failure=(status)=>Object.assign(new Error('sensitive provider payload ak_do_not_echo'),status?{status}:{});
+async function fixture(t) {
+ const directory=await fs.mkdtemp(path.join(os.tmpdir(),'opencrawl-connect-')),before=process.env.OPENCRAWL_CONFIG_DIR;
+ process.env.OPENCRAWL_CONFIG_DIR=directory;t.after(async()=>{if(before===undefined)delete process.env.OPENCRAWL_CONFIG_DIR;else process.env.OPENCRAWL_CONFIG_DIR=before;await fs.rm(directory,{recursive:true,force:true});});
+ const calls=[],state={authorization:'pending',expires:Math.floor(Date.now()/1000)+900,configured:false,jobs:[],source:{id,kind:'composio',owner_id:user,workspace_id:workspace,name:'Synthetic app',status:'pending',config:{toolkit:'github',connected_account_id:'private_provider_id',_connection_attempt_hash:'private_hash'},visibility:'private',sync_interval_minutes:1440}};
+ const value=()=>({source_id:id,authorization:{state:state.authorization,attempt_pending:state.authorization==='pending',attempt_expires_at:state.expires},scope:{configured:state.configured,adapter_supported:true,required_fields:['repository'],missing_fields:state.configured?[]:['repository'],summary:state.configured?'Repository selected':'Choose repository'},ingestion:{state:state.authorization==='verified'?(state.configured?'idle':'config_required'):'idle',indexed_document_count:0,jobs:state.jobs},issue:null,coverage:{state:'unknown'}});
+ const client={baseUrl:'https://app.example',async request(route,options={}){
+   calls.push({route,...options});if(state.before)await state.before(route,options);
+   if(route==='/api/auth/me')return{user:{id:user},workspace:{id:workspace}};
+   if(route==='/api/v1/sources')return {items:[state.source,{...state.source,id:'src_'+'f'.repeat(32),owner_id:'usr_'+'f'.repeat(32)}]};
+   if(route.endsWith('/setup'))return value();
+   if(route==='/api/v1/sources/connect'||route.endsWith('/reconnect'))return{source_id:id,url:'https://connect.example/authorize?opaque=synthetic',attempt:nonce,expires_at:state.expires};
+   if(route.endsWith('/connection-check')){state.authorization='verified';state.source.status='active';if(state.configured)state.jobs=[job()];if(state.checkLost)throw failure();return value();}
+   if(options.method==='PATCH'){state.source={...state.source,...options.body,config:{...state.source.config,...options.body.config}};state.configured=!!state.source.config.repository;if(state.configureLost)throw failure();return state.source;}
+   if(route.endsWith('/sync')){state.jobs=[job()];if(state.syncLost)throw failure();return{job:state.jobs[0]};}
+   throw new Error('Unexpected fixture request '+route);
+ }};
+ const run=async(rest,options={})=>{let out='',err='';const code=await connectCommand(rest,{json:true,...options},client,{stdout:v=>out+=v,stderr:v=>err+=v});return{code,data:JSON.parse(out),out,err};};
+ const ledger=async()=>{const files=(await fs.readdir(path.join(directory,'connections'))).filter(v=>v.endsWith('.json'));assert.equal(files.length,1);const file=path.join(directory,'connections',files[0]);return{file,value:JSON.parse(await fs.readFile(file,'utf8'))};};
+ return{directory,calls,state,client,run,ledger};
+}
+test('commands preserve alias and reject invalid or privileged scope fields',()=>{
+ assert.equal(connectRequest(['github'],{}).toolkit,'github');assert.equal(connectRequest([],{query:'Salesforce'}).route,'/api/v1/sources/catalogue?q=Salesforce');
+ assert.deepEqual(connectRequest(['configure',id],{repository:'owner/repo','max-pages':'1','include-comments':'false','sync-every':'0'}).body,{sync_interval_minutes:0,config:{repository:'owner/repo',max_pages:1,include_comments:false}});
+ for(const [rest,options] of [[['check','../oops'],{}],[['start'],{}],[['status',id,'extra'],{}],[['configure',id],{repository:'../repo'}],[['configure',id],{channels:'C1,C1'}],[['configure',id],{'max-pages':'1e2'}],[['configure',id],{'include-comments':'yes'}],[['configure',id],{'instance-url':'https://evil.example'}],[['configure',id],{'connected-account-id':'other'}],[['configure',id],{}],[['check',id],{attempt:nonce}]])assert.throws(()=>connectRequest(rest,options));
+});
+test('private durable attempt survives restart but nonce and provider identities never appear in output',async t=>{
+ const f=await fixture(t),started=await f.run(['github']);assert.equal(started.code,0);assert.equal(started.data.source_id,id);assert.ok(started.data.authorization_url);assert.ok(!started.out.includes(nonce));
+ const {file,value}=await f.ledger();assert.equal(value.records[0].attempt,nonce);assert.equal((await fs.stat(file)).mode&0o777,0o600);assert.equal((await fs.stat(path.dirname(file))).mode&0o777,0o700);
+ const status=await f.run(['status',id]);assert.equal(status.data.receipt.receipt_id,started.data.receipt.receipt_id);assert.ok(!status.out.includes('private_provider_id'));assert.ok(!status.out.includes('private_hash'));assert.ok(!status.out.includes(nonce));
+ const checked=await f.run(['check',id]);assert.equal(checked.code,0);assert.equal(checked.data.setup.authorization.state,'verified');assert.match(checked.err,/may queue/);assert.equal((await f.ledger()).value.records[0].attempt,undefined);
+ assert.equal(f.calls.filter(v=>v.route.endsWith('/connection-check')).length,1);
+});
+test('status and setup are read-only even with a pending provider attempt',async t=>{
+ const f=await fixture(t);await f.run(['start','github']);f.calls.length=0;
+ for(const args of [['status'],['status',id],['setup',id]])assert.equal((await f.run(args)).code,0);
+ assert.ok(f.calls.every(v=>!v.method||v.method==='GET'));const list=await f.run(['status']);assert.equal(list.data.sources.length,1);
+});
+test('lost browser callback and repeated check reconcile verified setup without another write',async t=>{
+ const f=await fixture(t);await f.run(['github']);f.state.authorization='verified';f.state.configured=true;f.state.jobs=[job()];f.calls.length=0;
+ const checked=await f.run(['check',id]);assert.equal(checked.code,0);assert.equal(checked.data.setup.authorization.state,'verified');assert.ok(f.calls.every(v=>!v.method));
+ assert.equal((await f.ledger()).value.records[0].attempt,undefined);
+});
+test('lost check acceptance reads current setup and never repeats provider verification or first sync',async t=>{
+ const f=await fixture(t);await f.run(['github']);f.state.checkLost=true;f.state.configured=true;
+ const checked=await f.run(['check',id]);assert.equal(checked.code,0);assert.equal(checked.data.setup.authorization.state,'verified');
+ assert.equal(f.calls.filter(v=>v.route.endsWith('/connection-check')).length,1);assert.equal(f.calls.filter(v=>v.route.endsWith('/sync')).length,0);
+ const next=await f.run(['sync',id]);assert.equal(next.code,0);assert.equal(next.data.job.id,job().id);assert.equal(f.calls.filter(v=>v.route.endsWith('/sync')).length,0);
+});
+test('an unreconciled check preserves uncertainty and secrets stay private',async t=>{
+ const f=await fixture(t);await f.run(['github']);let lost=false;f.state.before=(route)=>{if(route.endsWith('/connection-check')){lost=true;throw failure();}if(route.endsWith('/setup')&&lost)throw failure();};
+ const checked=await f.run(['check',id]);assert.equal(checked.code,1);assert.equal(checked.data.receipt.operation.state,'unconfirmed');assert.ok(!checked.out.includes('ak_do_not_echo'));assert.ok(!checked.out.includes(nonce));
+ assert.equal(f.calls.filter(v=>v.route.endsWith('/connection-check')).length,1);
+});
+test('expired and replaced attempts require explicit reconnect, never stale nonce submission',async t=>{
+ const f=await fixture(t);await f.run(['github']);f.state.expires+=1;
+ const checked=await f.run(['check',id]);assert.equal(checked.code,1);assert.match(checked.data.error.message,/reconnect/);assert.equal(f.calls.filter(v=>v.route.endsWith('/connection-check')).length,0);
+ const restarted=await f.run(['reconnect',id]);assert.equal(restarted.code,0);assert.equal((await f.ledger()).value.records[0].state,'superseded');
+});
+test('lost start blocks blind repeated start and does not infer a source from the owner list',async t=>{
+ const f=await fixture(t);f.state.before=route=>{if(route==='/api/v1/sources/connect')throw failure();};
+ const started=await f.run(['github']);assert.equal(started.code,1);assert.equal(started.data.source_id,null);
+ assert.equal((await f.run(['github'])).code,1);assert.equal(f.calls.filter(v=>v.route==='/api/v1/sources/connect').length,1);
+ const status=await f.run(['status']);assert.equal(status.data.receipts[0].source_id,null);assert.equal(status.data.sources[0].id,id);
+ const fresh=await f.run(['reconnect',id]);assert.equal(fresh.code,0);assert.equal(fresh.data.source_id,id);assert.equal((await f.ledger()).value.records[0].source_id,null);
+});
+test('source-less rejected or lost starts require status then an explicitly acknowledged new attempt',async t=>{
+ const f=await fixture(t);f.state.before=route=>{if(route==='/api/v1/sources/connect')throw failure(503);};
+ const started=await f.run(['github']);assert.equal(started.code,1);assert.equal(started.data.source_id,null);
+ assert.equal((await f.run(['start','github'],{'acknowledge-unknown':true})).code,1);
+ await f.run(['status']);assert.equal((await f.run(['github'])).code,1);assert.equal(f.calls.filter(v=>v.route==='/api/v1/sources/connect').length,1);
+ f.state.before=null;const replacement=await f.run(['start','github'],{'acknowledge-unknown':true});assert.equal(replacement.code,0);assert.match(replacement.err,/may replace or create/);
+ const records=(await f.ledger()).value.records;assert.equal(records.length,2);assert.equal(records[0].source_id,null);assert.equal(records[0].state,'unconfirmed');assert.ok(records[0].new_start_acknowledged_at);assert.equal(records[1].source_id,id);
+ // A known source is never replaced through this source-less recovery option.
+ assert.equal((await f.run(['start','github'],{'acknowledge-unknown':true})).code,1);assert.equal(f.calls.filter(v=>v.route==='/api/v1/sources/connect').length,2);
+});
+test('fresh identity must match a saved account and revoked credentials cannot publish an attempt',async t=>{
+ const f=await fixture(t);f.client.profile={userId:user,workspaceId:'ws_'+'e'.repeat(32),server:f.client.baseUrl};
+ assert.equal((await f.run(['github'])).code,1);assert.equal(f.calls.length,1);await assert.rejects(fs.stat(path.join(f.directory,'connections')),{code:'ENOENT'});
+ f.client.profile=null;f.state.before=()=>{throw failure(401);};assert.equal((await f.run(['github'])).data.error.status,401);assert.equal(f.calls.filter(v=>v.method==='POST').length,0);
+});
+test('a changed server identity cannot reuse another namespace nonce',async t=>{
+ const f=await fixture(t);await f.run(['github']);f.client.baseUrl='https://second.example';
+ const checked=await f.run(['check',id]);assert.equal(checked.code,1);assert.equal(f.calls.filter(v=>v.route.endsWith('/connection-check')).length,0);
+});
+test('configure is explicit, preserves server-owned keys, never syncs, and retains unknown receipt',async t=>{
+ const f=await fixture(t);f.state.authorization='verified';f.state.configureLost=true;
+ const result=await f.run(['configure',id],{repository:'owner/repo','max-pages':'1','include-comments':'false','sync-every':'0'});assert.equal(result.code,1);
+ const patch=f.calls.find(v=>v.method==='PATCH');assert.deepEqual(patch.body,{sync_interval_minutes:0,config:{repository:'owner/repo',max_pages:1,include_comments:false}});assert.equal(f.calls.filter(v=>v.route.endsWith('/sync')).length,0);
+ const status=await f.run(['setup',id]);assert.equal(status.data.source.config.repository,'owner/repo');assert.equal(status.data.receipt.operation.state,'unconfirmed');assert.ok(!status.out.includes('private_provider_id'));
+});
+test('sync acceptance is durable and unknown completed work requires explicit acknowledgement before another sync',async t=>{
+ const f=await fixture(t);f.state.authorization='verified';f.state.configured=true;f.state.source.config.repository='owner/repo';f.state.syncLost=true;
+ const first=await f.run(['sync',id]);assert.equal(first.code,1);assert.equal(first.data.receipt.operation.state,'unconfirmed');
+ f.state.jobs[0].status='completed';assert.equal((await f.run(['configure',id],{name:'Renamed source'})).code,0);assert.equal((await f.run(['sync',id])).code,1);assert.equal(f.calls.filter(v=>v.route.endsWith('/sync')).length,1);
+ f.state.syncLost=false;const second=await f.run(['sync',id],{'acknowledge-unknown':true});assert.equal(second.code,0);assert.equal(second.data.job.id,job().id);assert.equal((await f.ledger()).value.records[0].operation.job_id,job().id);
+});
+test('missing required scope stops first sync',async t=>{
+ const f=await fixture(t);f.state.authorization='verified';const result=await f.run(['sync',id]);assert.equal(result.code,1);assert.equal(f.calls.filter(v=>v.route.endsWith('/sync')).length,0);
+});
+test('invalid authorization URLs or mismatched source receipts never publish a usable nonce',async t=>{
+ const f=await fixture(t),original=f.client.request.bind(f.client);
+ f.client.request=async(route,options)=>route==='/api/v1/sources/connect'?{source_id:id,url:'javascript:alert(1)',attempt:nonce,expires_at:f.state.expires}:original(route,options);
+ const result=await f.run(['github']);assert.equal(result.code,1);assert.equal(result.data.authorization_url,undefined);assert.ok(!result.out.includes(nonce));assert.equal((await f.ledger()).value.records[0].attempt,undefined);
+});
+test('corrupt, permissive, or symlinked receipt files fail closed before provider writes',async t=>{
+ const f=await fixture(t);await f.run(['github']);const {file}=await f.ledger();f.calls.length=0;
+ await fs.chmod(file,0o644);assert.equal((await f.run(['check',id])).code,1);
+ await fs.chmod(file,0o600);await fs.writeFile(file,'{broken');assert.equal((await f.run(['check',id])).code,1);
+ await fs.unlink(file);const target=path.join(f.directory,'outside');await fs.writeFile(target,'{}');await fs.symlink(target,file);assert.equal((await f.run(['check',id])).code,1);
+ assert.equal(f.calls.filter(v=>v.method==='POST').length,0);assert.equal(await fs.readFile(target,'utf8'),'{}');
+});
+test('concurrent start commands serialize locally and never duplicate provider creation',async t=>{
+ const f=await fixture(t);let release,entered;const blocked=new Promise(r=>release=r),ready=new Promise(r=>entered=r);
+ f.state.before=async route=>{if(route==='/api/v1/sources/connect'){entered();await blocked;}};
+ const first=f.run(['github']);await ready;const second=await f.run(['github']);assert.equal(second.code,1);assert.match(second.data.error.message,/still be running/);release();assert.equal((await first).code,0);
+ assert.equal(f.calls.filter(v=>v.route==='/api/v1/sources/connect').length,1);
+});
+test('human output escapes hostile source fields while JSON keeps exact safe metadata',async t=>{
+ const f=await fixture(t);f.state.source.name='Unsafe\x1b]0;title\x07';let text='';
+ assert.equal(await connectCommand(['status'],{},f.client,{stdout:v=>text+=v,stderr:v=>text+=v}),0);assert.ok(!text.includes('\x1b'));assert.match(text,/\\u001b/);
+});

package/src/context.test.mjs

@@ -0,0 +1,32 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { coverageWarnings, hookContext, HOOK_CONTEXT_BUDGET, HOOK_RETRIEVAL_BUDGET, utf8Prefix } from './context.mjs';
+
+test('UTF-8 prefixes stay inside the byte budget at every multibyte boundary', () => {
+  const text = 'Aé漢😀Z';
+  for (let budget = 0; budget <= Buffer.byteLength(text) + 2; budget++) {
+    const bounded = utf8Prefix(text, budget);
+    assert.ok(Buffer.byteLength(bounded) <= budget);
+    assert.ok(text.startsWith(bounded));
+    assert.ok(!bounded.includes('\ufffd'));
+  }
+});
+
+test('hook budget includes wrapper and coverage warning, with room reserved before retrieval', () => {
+  const data = { context: '漢😀'.repeat(1000), coverage: { partial_semantic: true, warnings: ['Semantic search covered only part of this workspace.'] } };
+  const output = hookContext(data);
+  assert.ok(output.includes('Retrieval coverage:'));
+  assert.ok(output.includes('untrusted'));
+  assert.ok(output.endsWith('</opencrawl_context>'));
+  assert.ok(!output.includes('\ufffd'));
+  assert.ok(Buffer.byteLength(output) <= HOOK_CONTEXT_BUDGET);
+  const fullEvidence = 'x'.repeat(HOOK_RETRIEVAL_BUDGET);
+  assert.ok(hookContext({ ...data, context: fullEvidence }).includes(fullEvidence));
+});
+
+test('missing coverage remains quiet and an empty partial search remains explicit', () => {
+  assert.deepEqual(coverageWarnings({ context: 'test' }), []);
+  assert.equal(hookContext({ context: '' }), '');
+  assert.match(hookContext({ context: '', coverage: { partial_semantic: true } }), /only part/);
+  assert.match(coverageWarnings({ evidence: { semantic_status: 'unavailable; lexical fallback' } })[0], /keyword matching/);
+});

package/src/jobs.mjs

@@ -48,17 +48,26 @@ export function validateJob(job, id = job?.id) {
 }
 export const getJob = async (client, id, options = {}) => validateJob(await client.request(`/api/v1/jobs/${encodeURIComponent(identifier(id))}`, { maxResponseBytes: 512 * 1024, ...options }), id);
 
+// Failures that say nothing about the job itself: the server restarting, a proxy, the network. Polling keeps going.
+const TRANSIENT=new Set([408,425,429,500,502,503,504]);
+export function transient(error){return error?.transient===true||TRANSIENT.has(error?.status);}
+// Wait before the next poll after a transient failure: 2s, 4s, 8s, then every 15s, never past the deadline.
+export async function settle(failures,{signal,now,sleep,deadline}){const next=Math.min(deadline,now()+Math.min(15000,1000*2**failures));while(!signal?.aborted&&now()<next)await sleep(Math.min(100,next-now()));}
+
 export async function waitForJob(client, id, { timeout = 300, signal, now = () => performance.now(), sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), onUpdate = () => {}, initial, deadline } = {}) {
   identifier(id); const started = now(); deadline ??= started + timeout * 1000;
-  let job = initial ? validateJob(initial, id) : null;
+  let job = initial ? validateJob(initial, id) : null, failures = 0;
   const result = (outcome, error) => ({ job_id: id, job, wait: { outcome, elapsed_seconds: Math.max(0, Math.round((now() - started) / 1000)), ...(error ? { error } : {}) } });
   while (true) {
     if (signal?.aborted) return result('interrupted');
     if (job && TERMINAL.has(job.status)) return result(job.status);
     const remaining = deadline - now();
     if (remaining <= 0) return result('timeout');
-    try { job = await getJob(client, id, { timeout: Math.max(1, Math.min(30000, Math.ceil(remaining))), signal }); }
-    catch (error) { return result(signal?.aborted ? 'interrupted' : now() >= deadline ? 'timeout' : 'unavailable', requestFailure(error)); }
+    try { job = await getJob(client, id, { timeout: Math.max(1, Math.min(30000, Math.ceil(remaining))), signal }); failures = 0; }
+    catch (error) {
+      if (!signal?.aborted && now() < deadline && transient(error)) { await settle(++failures, {signal, now, sleep, deadline}); continue; }
+      return result(signal?.aborted ? 'interrupted' : now() >= deadline ? 'timeout' : 'unavailable', requestFailure(error));
+    }
     onUpdate(job);
     if (TERMINAL.has(job.status)) return result(job.status);
     // Short sleeps keep Ctrl+C responsive without extra server polling.

package/src/jobs.test.mjs

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { jobsCommand, waitForJob, waitOptions, renderJob } from './jobs.mjs';
+import { displayText, displayLine } from './display.mjs';
+
+const id = 'job_' + 'a'.repeat(32);
+const job = status => ({ id, status, kind: 'upload', indexed_documents: status === 'completed' ? 1 : 0, documents: [] });
+test('job waiting follows exact IDs and stops on terminal status without any mutation', async () => {
+  let time = 0; const calls = []; const statuses = ['queued', 'running', 'completed'];
+  const result = await waitForJob({ request: async (route, options) => { calls.push([route, options]); return job(statuses.shift()); } }, id, { now: () => time, sleep: async ms => { time += ms; } });
+  assert.equal(result.wait.outcome, 'completed'); assert.equal(result.job_id, id); assert.equal(time, 4000);
+  assert.equal(calls.length, 3); assert(calls.every(([route, options]) => route === `/api/v1/jobs/${id}` && !options.method && options.timeout <= 30000));
+});
+test('all unsuccessful terminal states retain the job and return unsuccessful wait receipts', async () => {
+  for (const status of ['failed', 'cancelled', 'discarded']) {
+    const result = await waitForJob({ request: async () => job(status) }, id);
+    assert.equal(result.wait.outcome, status); assert.equal(result.job.id, id);
+  }
+});
+test('finite timeout and interruption do not cancel or retry work', async () => {
+  let time = 0, calls = 0;
+  const result = await waitForJob({ request: async (route, options) => { calls++; assert(options.timeout <= 1000); return job('waiting'); } }, id, { timeout: 1, now: () => time, sleep: async ms => { time += ms; } });
+  assert.equal(result.wait.outcome, 'timeout'); assert.equal(calls, 1); assert.equal(result.job_id, id);
+  const controller = new AbortController(); controller.abort();
+  const interrupted = await waitForJob({ request: async () => { throw Error('must not call'); } }, id, { signal: controller.signal });
+  assert.equal(interrupted.wait.outcome, 'interrupted'); assert.equal(interrupted.job_id, id);
+});
+test('permission and unknown failures never imply completion', async () => {
+  for (const status of [401,403,404,422,undefined]) {
+    let calls = 0;
+    const result = await waitForJob({ request: async () => { calls++; const error = Error('RAW PRIVATE BODY'); error.status = status; throw error; } }, id);
+    assert.equal(result.wait.outcome, 'unavailable'); assert.equal(result.job_id, id); assert.equal(calls, 1); assert(!JSON.stringify(result).includes('RAW PRIVATE'));
+  }
+  const result = await waitForJob({ request: async () => job('surprise') }, id);
+  assert.equal(result.wait.outcome, 'unavailable'); assert.equal(result.job, null);
+});
+test('jobs validate option bounds before calling the server', async () => {
+  const client = { request: async () => { throw Error('unexpected call'); } };
+  for (const [rest, options] of [[['wait', id], { timeout: '0' }], [['wait', id], { timeout: '3601' }], [['list'], { limit: '1e2' }], [['show', '../secret'], {}], [['show', id], { retry: true }], [['list', 'extra'], {}]]) {
+    await assert.rejects(jobsCommand(rest, options, client), error => !error.message.includes('unexpected call'));
+  }
+  assert.throws(() => waitOptions({ timeout: '1' }), /requires --wait/);
+});
+test('job human display escapes terminal controls while JSON retains source text', async () => {
+  const value = { ...job('failed'), filename: 'report\u001b]52;copy\u0007.pdf', error: 'error\rreplacement\u202e', documents: [{ id: 'doc', title: 'a\nb' }] };
+  assert(!renderJob(value).includes('\u001b')); assert(renderJob(value).includes('\\u001b')); assert(renderJob(value).includes('a\\nb'));
+  assert.equal(displayText('a\nb\tc\u001b'), 'a\nb\tc\\u001b'); assert.equal(displayLine('a\nb'), 'a\\nb');
+  let output = ''; await jobsCommand(['show', id], { json: true }, { request: async () => value }, { stdout: text => { output += text; } });
+  assert.equal(JSON.parse(output).filename, value.filename);
+});
+
+test('a restart, proxy error or lost connection keeps the wait going until the job finishes', async () => {
+  let time = 0, calls = 0;
+  const failures = [502, 503, 429, 'network'];
+  const result = await waitForJob({ request: async () => {
+    calls++;
+    const next = failures.shift();
+    if (next === undefined) return job('completed');
+    const error = Error('RAW PRIVATE BODY'); if (next === 'network') error.transient = true; else error.status = next; throw error;
+  } }, id, { now: () => time, sleep: async ms => { time += ms; } });
+  assert.equal(result.wait.outcome, 'completed'); assert.equal(calls, 5);
+  assert(time >= 2000 + 4000 + 8000 + 15000);  // backs off instead of hammering a restarting server
+  // Still bounded by the caller's deadline.
+  time = 0;
+  const stuck = await waitForJob({ request: async () => { const error = Error('x'); error.status = 503; throw error; } }, id, { timeout: 60, now: () => time, sleep: async ms => { time += ms; } });
+  assert.equal(stuck.wait.outcome, 'timeout');
+});