@volter/supercode-teams 0.2.165 → 0.2.167

package/bin/workspace/args.mjs

@@ -1,6 +1,6 @@
 const BOOLEANS = new Set([
   'json', 'help', 'live', 'saved', 'watch', 'paginate', 'token-stdin',
-  'invite-stdin', 'include-children', 'rotate', 'install', 'force',
+  'invite-stdin', 'enrollment-stdin', 'include-children', 'rotate', 'install', 'force',
   'take-control', 'dry-run', 'volter', 'foreground', 'no-connect', 'record-only', 'workplace-only',
 ]);
 
@@ -11,7 +11,7 @@ const VALUES = new Set([
   'out', 'ttl', 'type', 'name', 'visibility', 'backfill', 'format', 'to',
   'grant', 'binding', 'caps', 'fidelity', 'cwd', 'root', 'workspace-from', 'since', 'until', 'session',
   'on', 'timeout', 'plan', 'tmux-socket', 'volter-issuer', 'workplace', 'organization', 'key', 'room',
-  'conversation', 'rh2', 'scope', 'agent', 'body-file',
+  'conversation', 'rh2', 'scope', 'agent', 'body-file', 'enrollment',
 ]);
 
 export function parseArgs(argv) {

package/bin/workspace.mjs

@@ -2,7 +2,7 @@
 import { hostname } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { existsSync, readFileSync, realpathSync, rmSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { basename, isAbsolute, join, resolve } from 'node:path';
 import { execFileSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
@@ -47,6 +47,7 @@ export async function workspaceMain(argv = process.argv.slice(2), env = process.
   if (verb === 'server') return serverCommand({ flags, sub, rest, home, output });
   if (verb === 'login') return loginCommand({ flags, origin: sub, rest, home, output });
   if (verb === 'auth') return authCommand({ flags, sub, rest, home, contexts, output, env, dependencies });
+  if (verb === 'connect' && flags.enrollment_stdin) adoptEnrollment(contexts, home, flags);
   const explicitContext = flags.context ?? env.SUPERCODE_CONTEXT;
   let selected = explicitContext ?? contexts.read().current;
   const urlReference = verb === 'sessions' ? rest.find(value => /^https?:\/\//.test(value)) : null;
@@ -55,6 +56,8 @@ export async function workspaceMain(argv = process.argv.slice(2), env = process.
   if (selected === 'local') return localCommand({ verb, sub, rest, flags, output });
   const { client, context } = fromContext({ supercodeHome: home, name: selected, fetch: globalThis.fetch });
   const team = client.team(context.team_id);
+  // A machine-only context (a box enrolled by its custodian) holds its machine credential and nothing a person has.
+  if (context.machine_only && !['connect', 'disconnect', 'status'].includes(verb)) usage(`context ${selected} is machine ${context.machine_name}'s: run teams ${verb} where a person is signed in`);
   const command = { flags, rest, output, client, context, team, explicitContext, home, contextName: selected, env, dependencies };
   if (teamsPrefix && ['list', 'create'].includes(verb)) return teamsCommand(verb, sub, command);
   if (verb === 'apps' || verb === 'app-installations') return appsCommand(verb,sub,{...command,output:value=>output(flags.json?value:redactAppSecrets(value))});
@@ -588,6 +591,26 @@ async function sourcesCommand(sub, command) {
 }
 
 async function machinesCommand(sub, { flags, rest, output, client, context, team }) {
+  if (sub === 'remove') {
+    // The custodian revokes a machine: its credentials, links and grants end, and every later door is refused.
+    requireArgs(rest, 1, 1, 'teams machines remove MACHINE_ID'); const current = await team.machines.get(rest[0]);
+    await client.request('DELETE', teamPath(context, `/machines/${rest[0]}`), { ifMatch: current.data.revision });
+    return output({ version: 1, context: scope(context), data: { removed: rest[0] } });
+  }
+  if (sub === 'enroll') {
+    // The signed-in person enrolls another machine as its custodian. The file carries only that machine's own
+    // credential; the machine connects from it (teams connect --enrollment-stdin) and never holds a person's.
+    requireArgs(rest, 0, 0, 'teams machines enroll --name NAME --out PATH'); if (!flags.name) usage('--name is required');
+    if (!flags.out) usage('--out is required to deliver the machine credential'); const destination = reserveProtected(flags.out, { force: flags.force });
+    try {
+      const enrollment_key = crypto.randomUUID();
+      const response = await team.machines.create({ name: flags.name, enrollment_key });
+      let credential = response.data.credential;
+      if (!credential) credential = (await client.request('POST', teamPath(context, `/sources/${response.data.source.id}/credentials`), { body: { rotate: true } })).data;
+      destination.write({ version: 1, kind: 'machine-enrollment', origin: context.origin, server_id: context.server_id, team_id: context.team_id, team_name: context.team_name ?? null, enrollment_key, machine: response.data.machine, source: response.data.source, credential });
+      return output({ version: 1, context: scope(context), data: { machine: response.data.machine, source: response.data.source, written_to: resolve(flags.out) } });
+    } catch (error) { destination.abort(); throw error; }
+  }
   if (['subscribe','unsubscribe','events'].includes(sub)) {
     requireArgs(rest,sub==='events'?0:1,sub==='events'?0:1,`teams machines ${sub} ${sub==='events'?'':'ADDRESS'}`);
     const channel=await openLocalMachine(paths(teamsHome()).socket);
@@ -647,11 +670,24 @@ async function machinesCommand(sub, { flags, rest, output, client, context, team
       return output(await client.request('POST', machineBase, { body: { subject_id: subject, caps, targets, expires_at: Date.now() + ttl } }));
     }
   }
-  usage('teams machines list|roots|access|authorize-continuation|subscribe|unsubscribe|events');
+  usage('teams machines list|roots|access|enroll|remove|authorize-continuation|subscribe|unsubscribe|events');
 }
 
 async function syncCommand(sub, { flags, rest, output, client, context, team, home }) {
   if (sub === 'list') return output(await team.syncRules.list(optional(flags, ['machine'])));
+  if (sub === 'add' && flags.enrollment) {
+    // A custodian's rule for a machine it enrolled: the path is the machine's own, and its root id is the one the
+    // machine's connector registers for it (sha256 of machine id and path). The harness is named, as this computer
+    // cannot ask that machine's native core.
+    requireArgs(rest, 0, 0, 'teams sync add --enrollment FILE --repo PATH --harness ID'); if (!flags.repo) usage('--repo is required'); if (!flags.harness) usage('--harness is required with --enrollment');
+    const enrolled = JSON.parse(readFileSync(resolve(flags.enrollment), 'utf8'));
+    if (enrolled.kind !== 'machine-enrollment' || enrolled.team_id !== context.team_id) usage('--enrollment names no machine of this team');
+    // connect registers the folder's real path; name it the same way (absolute, normalized, no symlink).
+    if (!isAbsolute(flags.repo)) usage('--repo with --enrollment is the machine\'s absolute path');
+    const repo = resolve(flags.repo);
+    const root_id = `root_${createHash('sha256').update(`${enrolled.machine.id}\0${repo}`).digest('hex').slice(0, 32)}`;
+    return output(await team.syncRules.create({ machine_id: enrolled.machine.id, source_id: enrolled.source.id, selector: { root_id, harnesses: [flags.harness] }, visibility: flags.visibility ?? 'restricted', backfill: backfill(flags.backfill ?? 'none') }));
+  }
   if (sub === 'add') {
     requireArgs(rest, 0, 0, 'teams sync add --repo PATH'); if (!flags.repo) usage('--repo is required');
     const enrollment = new WorkspaceContexts(home).connector(context.server_id, context.team_id).read();
@@ -683,16 +719,38 @@ async function stopRunningConnector(saved) {
   for (let waited = 0; running.pid > 0 && alive() && waited < 15_000; waited += 250) await new Promise(resolve => setTimeout(resolve, 250));
 }
 
+/**
+ * The machine side of `teams machines enroll`: the enrollment on stdin becomes this home's machine-only context (its
+ * machine credential, never a person's) and its connector state, and the connect that follows starts from them.
+ */
+function adoptEnrollment(contexts, home, flags) {
+  let enrolled;
+  try { enrolled = JSON.parse(readFileSync(0, 'utf8')); } catch { usage('stdin is not JSON: pipe the file teams machines enroll --out wrote'); }
+  if (enrolled?.version !== 1 || enrolled.kind !== 'machine-enrollment' || !enrolled.credential?.token || !enrolled.machine?.id || !enrolled.source?.id || !enrolled.enrollment_key) usage('stdin is not a machine enrollment (teams machines enroll --out)');
+  const connector = contexts.connector(enrolled.server_id, enrolled.team_id), saved = connector.read();
+  if (saved?.machine && saved.machine.id !== enrolled.machine.id) usage(`this home is already connected as ${saved.machine.name ?? saved.machine.id}; disconnect it first`);
+  const name = flags.context ?? 'machine', existing = contexts.read().contexts[name];
+  if (existing && !(existing.machine_only && existing.server_id === enrolled.server_id && existing.team_id === enrolled.team_id)) usage(`context ${name} is not this machine's; name another with --context`);
+  const credentialId = `cred_${crypto.randomUUID().replaceAll('-', '')}`;
+  contexts.writeCredential(credentialId, { token: enrolled.credential.token, kind: 'machine', expires_at: enrolled.credential.expires_at ?? null, server_id: enrolled.server_id, origin: enrolled.origin });
+  contexts.upsert(name, { origin: enrolled.origin, server_id: enrolled.server_id, team_id: enrolled.team_id, team_name: enrolled.team_name ?? null, principal_id: null, credential_ref: credentialId, label: null, machine_only: true, machine_name: enrolled.machine.name });
+  if (!saved?.machine) connector.write({ version: 1, enrollment_key: enrolled.enrollment_key, phase: 'enrolled', machine: enrolled.machine, source: enrolled.source, credential: enrolled.credential });
+  if (!contexts.read().current) contexts.use(name);
+  flags.context = name;
+}
+
 async function connectorCommand(verb, { flags, rest, output, client, context, team, contextName }, home) {
   requireArgs(rest, 0, 0, `teams ${verb}`); const state = new WorkspaceContexts(home).connector(context.server_id, context.team_id);
   if (verb === 'status') {
-    let reachable = true; let account = null; try { account = await client.me(); } catch { reachable = false; }
+    // A machine has no account to name: its own door answering its credential is the answer.
+    let reachable = true; let account = null;
+    try { if (context.machine_only) { const enrolled = state.read(); await client.request('GET', teamPath(context, `/machines/${enrolled?.machine?.id}/configuration`)); } else account = await client.me(); } catch { reachable = false; }
     const saved = state.read(); const running = saved?.process?.socket ? await activeSocket(saved.process.socket) : false;
     // A connector deep in a large capture can miss the probe's second while its process lives on: it is busy, not stopped.
     const busy = !running && Boolean(saved?.process) && lifecycleHeld(state.directory);
     // What the connector could not sync, as it last wrote it to its state (it is written while it runs).
     const sync = saved ? readSyncStatus(state.directory) ?? { not_syncing: [], last_error: null, queued_captures: 0 } : null;
-    const value = { version: 1, context: scope(context), data: { reachable, account, connector: saved ? { enrolled: true, running: running || busy, ...(busy ? { busy: true } : {}), machine: saved.machine, source: saved.source, sync } : { enrolled: false, running: false }, sources: reachable ? (await team.sources.list()).items : [] } };
+    const value = { version: 1, context: scope(context), data: { reachable, account, connector: saved ? { enrolled: true, running: running || busy, ...(busy ? { busy: true } : {}), machine: saved.machine, source: saved.source, sync } : { enrolled: false, running: false }, sources: reachable && !context.machine_only ? (await team.sources.list()).items : [] } };
     if (flags.json) return output(value);
     const lines = [`Team       ${context.team_name ?? context.team_id} · ${new URL(context.origin).host}${reachable ? '' : ' · unreachable'}`];
     lines.push(saved?.machine ? `Connector  ${saved.machine.name ?? saved.machine.id} · ${running ? 'running' : busy ? 'running (busy: its control socket did not answer within 1 s)' : 'not running'}${saved.service?.kind ? ` (${saved.service.kind})` : ''}` : 'Connector  not connected (supercode teams connect)');
@@ -846,6 +904,9 @@ async function connectorCommand(verb, { flags, rest, output, client, context, te
   }
   // Uninstalling a Windows task already stopped its connector, so only one still answering is asked to stop.
   if (enrollment.process?.socket && enrollment.process?.token && await activeSocket(enrollment.process.socket)) await requestStop(enrollment.process.socket, enrollment.process.token);
+  // A machine its custodian enrolled stops here; revoking it is the custodian's (teams machines remove).
+  // It keeps its enrollment, so connect resumes it; the custodian's removal is what ends it.
+  if (context.machine_only) { state.update((current) => ({ ...current, process: null, service: null })); return output({ version: 1, context: scope(context), data: { disconnected: true, machine_id: enrollment.machine.id, revoked: false } }); }
   const machine = await team.machines.get(enrollment.machine.id);
   await client.request('DELETE', teamPath(context, `/machines/${enrollment.machine.id}`), { ifMatch: machine.data.revision });
   state.remove();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-teams",
-  "version": "0.2.165",
+  "version": "0.2.167",
   "type": "module",
   "description": "A machine daemon serving this machine's doors, and a local or remote Teams server for shared session discovery, OpenTelemetry ingestion and access to enrolled machines.",
   "license": "MIT",

package/server/harness-routes.mjs

@@ -28,11 +28,17 @@ import { fail, parseJson, result, send, guardedMutation, requireRevision, checkR
 /** The `sub` a token says it is for, unverified: for a log line only, never for a decision. */
 function unverifiedSubject(token){try{return String(JSON.parse(Buffer.from(String(token).split('.')[1]??'','base64url').toString('utf8')).sub??'').slice(0,80)||'-';}catch{return '-';}}
 
+// URL encoding belongs to the HTTP boundary; native references retain their literal bytes in the store.
+function sessionRef(value) {
+  try { return decodeURIComponent(value); }
+  catch { fail(400, 'invalid_request', 'session reference has invalid URL encoding'); }
+}
+
 async function preAuth({ api, req, res, path, requestId }) {
   let early;
   if(req.method==='POST'&&(early=/^\/api\/v1\/teams\/([^/]+)\/sessions\/([^/]+)\/room-notices$/.exec(path))){
     const access=await delegatedRoomNoticeOf(api,bearer(req.headers.authorization));
-    if(!access || access.teamId!==early[1] || access.sessionRef!==decodeURIComponent(early[2])) fail(401,'authentication_required','authentication required');
+    if(!access || access.teamId!==early[1] || access.sessionRef!==sessionRef(early[2])) fail(401,'authentication_required','authentication required');
     checkRate(api,`room-notices:${access.issuer}:${access.teamId}`,120,10);
     const receipt=await deliverSessionRoomNotice(api,access);
     send(res,200,{data:receipt},requestId);return true;
@@ -46,12 +52,12 @@ async function preAuth({ api, req, res, path, requestId }) {
   if(req.method==='POST'&&(early=/^\/api\/v1\/teams\/([^/]+)\/sessions\/([^/]+)\/viewer-errors$/.exec(path))){
     const presented=bearer(req.headers.authorization)??'';checkRate(api,`viewer-errors:${hashToken(presented)}`,30,10);
     const access=looksDelegated(presented)?await delegatedSessionOf(api,presented):null,body=await parseJson(req).catch(()=>({})),text=(value,limit)=>typeof value==='string'?value.replace(/\s+/g,' ').slice(0,limit):null;
-    console.log(`viewer-error team=${early[1]} session=${decodeURIComponent(early[2]).slice(0,120)} subject=${access?access.subject:`unverified:${text(unverifiedSubject(presented),80)}`} scope=${access?.scope??'-'} room=${access?.room??'-'} stage=${text(body?.stage,40)} status=${Number.isSafeInteger(body?.status)?body.status:'-'} message=${JSON.stringify(text(body?.message,400))}`);
+    console.log(`viewer-error team=${early[1]} session=${sessionRef(early[2]).slice(0,120)} subject=${access?access.subject:`unverified:${text(unverifiedSubject(presented),80)}`} scope=${access?.scope??'-'} room=${access?.room??'-'} stage=${text(body?.stage,40)} status=${Number.isSafeInteger(body?.status)?body.status:'-'} message=${JSON.stringify(text(body?.message,400))}`);
     send(res,204,null,requestId);return true;
   }
   if(req.method==='GET'&&(early=/^\/api\/v1\/teams\/([^/]+)\/sessions\/([^/]+)(\/messages|\/events)?$/.exec(path))&&looksDelegated(bearer(req.headers.authorization))){
     const access=await delegatedSessionOf(api,bearer(req.headers.authorization));
-    const ref=decodeURIComponent(early[2]);
+    const ref=sessionRef(early[2]);
     if(!access||access.teamId!==early[1]||access.sessionRef!==ref){console.log(`session-view refused team=${early[1]} session=${ref.slice(0,120)} subject=${access?access.subject:`unverified:${unverifiedSubject(bearer(req.headers.authorization))}`} reason=${!access?'token not admitted':'token names another session'}`);fail(401,'authentication_required','authentication required');}
     const auth={kind:'session_view',team_id:early[1],principal_id:null,credential_id:null,bound:{installationId:access.installationId,installedAt:access.installedAt,issuer:access.issuer,room:access.room,conversation:access.conversation,expiresAt:access.expiresAt}};
     const url=new URL(req.url,'http://local');
@@ -85,18 +91,18 @@ async function team({ api, req, res, auth, url, path, sub, requestId }) {
   if(req.method==='GET'&&sub==='/sessions/search'){await listSessions(api,res,auth,url,requestId,true);return true;}
   if(req.method==='GET'&&sub==='/sessions/events'){await handleCatalogEvents({api,req,res,auth,url,requestId,qobj,canReadMerged,readerProjection,fail});return true;}
   if(req.method==='POST'&&sub==='/correlations'){await correlateRoute(api,req,res,auth,path,requestId);return true;}
-  if(req.method==='GET'&&(m=/^\/sessions\/([^/]+)$/.exec(sub))){await sessionDescriptor(api,res,auth,m[1],requestId);return true;}
-  if((req.method==='PATCH'||req.method==='DELETE')&&(m=/^\/sessions\/([^/]+)$/.exec(sub))){await mutateSession(api,req,res,auth,m[1],requestId);return true;}
-  if(req.method==='GET'&&(m=/^\/sessions\/([^/]+)\/messages$/.exec(sub))){await readSession(api,res,auth,m[1],url,requestId);return true;}
-  if(req.method==='GET'&&(m=/^\/sessions\/([^/]+)\/artifacts\/([^/]+)$/.exec(sub))){await readArtifact(api,req,res,auth,m[1],m[2],requestId);return true;}
-  if(req.method==='POST'&&(m=/^\/sessions\/([^/]+)\/exports$/.exec(sub))){await exportSessionRoute({api,req,res,auth,sessionId:m[1],requestId,parseJson,exact,fail,send,result,guardedMutation});return true;}
-  if(req.method==='POST'&&(m=/^\/sessions\/([^/]+)\/continuations$/.exec(sub))){await continuationRoute({api,req,res,auth,sessionId:m[1],requestId,parseJson,exact,fail,send,result,guardedMutation});return true;}
-  if(req.method==='GET'&&(m=/^\/sessions\/([^/]+)\/events$/.exec(sub))){await handleSessionEvents({api,req,res,auth,id:m[1],url,requestId,resolve,canReadMerged,readerProjection,fail});return true;}
-  if(['GET','POST','DELETE'].includes(req.method)&&(m=/^\/sessions\/([^/]+)\/view-bindings$/.exec(sub))){await viewBindingRoute(api,req,res,auth,m[1],requestId);return true;}
-  if((m=/^\/sessions\/([^/]+)\/access(?:\/([^/]+))?$/.exec(sub))){await accessRoute(api,req,res,auth,m[1],m[2],requestId);return true;}
+  if(req.method==='GET'&&(m=/^\/sessions\/([^/]+)$/.exec(sub))){await sessionDescriptor(api,res,auth,sessionRef(m[1]),requestId);return true;}
+  if((req.method==='PATCH'||req.method==='DELETE')&&(m=/^\/sessions\/([^/]+)$/.exec(sub))){await mutateSession(api,req,res,auth,sessionRef(m[1]),requestId);return true;}
+  if(req.method==='GET'&&(m=/^\/sessions\/([^/]+)\/messages$/.exec(sub))){await readSession(api,res,auth,sessionRef(m[1]),url,requestId);return true;}
+  if(req.method==='GET'&&(m=/^\/sessions\/([^/]+)\/artifacts\/([^/]+)$/.exec(sub))){await readArtifact(api,req,res,auth,sessionRef(m[1]),m[2],requestId);return true;}
+  if(req.method==='POST'&&(m=/^\/sessions\/([^/]+)\/exports$/.exec(sub))){await exportSessionRoute({api,req,res,auth,sessionId:sessionRef(m[1]),requestId,parseJson,exact,fail,send,result,guardedMutation});return true;}
+  if(req.method==='POST'&&(m=/^\/sessions\/([^/]+)\/continuations$/.exec(sub))){await continuationRoute({api,req,res,auth,sessionId:sessionRef(m[1]),requestId,parseJson,exact,fail,send,result,guardedMutation});return true;}
+  if(req.method==='GET'&&(m=/^\/sessions\/([^/]+)\/events$/.exec(sub))){await handleSessionEvents({api,req,res,auth,id:sessionRef(m[1]),url,requestId,resolve,canReadMerged,readerProjection,fail});return true;}
+  if(['GET','POST','DELETE'].includes(req.method)&&(m=/^\/sessions\/([^/]+)\/view-bindings$/.exec(sub))){await viewBindingRoute(api,req,res,auth,sessionRef(m[1]),requestId);return true;}
+  if((m=/^\/sessions\/([^/]+)\/access(?:\/([^/]+))?$/.exec(sub))){await accessRoute(api,req,res,auth,sessionRef(m[1]),m[2],requestId);return true;}
   if((m=/^\/machines\/([^/]+)\/grants(?:\/([^/]+))?$/.exec(sub))){await liveGrantRoute({api,req,res,auth,machineId:m[1],grantId:m[2],url,requestId,parseJson,exact,fail,send,result,guardedMutation,requireRevision});return true;}
   if((m=/^\/machines\/([^/]+)\/effects(?:\/([^/]+)(?:\/(claim|result))?)?$/.exec(sub))){await machineEffectRoute({api,req,res,auth,machineId:m[1],effectId:m[2],action:m[3],url,requestId,parseJson,exact,fail,send,result,guardedMutation});return true;}
-  if(req.method==='POST'&&(m=/^\/sessions\/([^/]+)\/attachments$/.exec(sub))){await createAttachment({api,req,res,auth,sessionId:m[1],requestId,parseJson,exact,fail,send,result,guardedMutation,resolve});return true;}
+  if(req.method==='POST'&&(m=/^\/sessions\/([^/]+)\/attachments$/.exec(sub))){await createAttachment({api,req,res,auth,sessionId:sessionRef(m[1]),requestId,parseJson,exact,fail,send,result,guardedMutation,resolve});return true;}
   if(req.method==='POST'&&(m=/^\/attachments\/([^/]+)\/actions$/.exec(sub))){await attachmentActionRoute({api,req,res,auth,attachmentId:m[1],requestId,parseJson,exact,fail,send,result,guardedMutation,resolve});return true;}
   if(req.method==='DELETE'&&(m=/^\/attachments\/([^/]+)$/.exec(sub))){await detachAttachmentRoute({api,res,auth,attachmentId:m[1],requestId,fail,send,guardedMutation});return true;}
   if(req.method==='GET'&&(m=/^\/operations\/([^/]+)$/.exec(sub))){await operationRoute({api,res,auth,operationId:m[1],requestId,fail,send,result,guardedMutation});return true;}
@@ -159,12 +165,8 @@ async function listSessions(api,res,auth,url,requestId,search){
     {kind:'query',sql:'SELECT * FROM session_grants WHERE team_id=?',params:[auth.team_id]}
   );
   if(cursorKey)statements.push({kind:'query',sql:`SELECT s.*,v.revision version_revision,v.descriptor_json,v.sort_at FROM ${cursorVersions} JOIN session_versions v ON v.team_id=? AND v.session_id=json_extract(j.value,'$[0]') AND v.revision=json_extract(j.value,'$[1]') JOIN sessions s ON s.team_id=v.team_id AND s.id=v.session_id WHERE s.deleted_at IS NULL AND v.revision<>s.revision`,params:[...cursorKey,auth.team_id]});
-  if(search){
-    statements.push({kind:'query',sql:'SELECT m.id,m.session_id,s.revision revision,m.recorded_at,m.search_text FROM sessions s JOIN messages m ON m.team_id=s.team_id AND m.session_id=s.id AND m.revision<=s.revision AND s.revision<COALESCE(m.until_revision,m.revision+1) WHERE s.team_id=? AND s.deleted_at IS NULL',params:[auth.team_id]});
-    if(cursorKey)statements.push({kind:'query',sql:`SELECT m.id,m.session_id,json_extract(j.value,'$[1]') revision,m.recorded_at,m.search_text FROM ${cursorVersions} JOIN messages m ON m.team_id=? AND m.session_id=json_extract(j.value,'$[0]') AND m.revision<=json_extract(j.value,'$[1]') AND json_extract(j.value,'$[1]')<COALESCE(m.until_revision,m.revision+1) JOIN sessions s ON s.team_id=m.team_id AND s.id=m.session_id WHERE s.deleted_at IS NULL AND json_extract(j.value,'$[1]')<>s.revision`,params:[...cursorKey,auth.team_id]});
-  }
   const values=await api.store.snapshot(statements),offset=cursorKey?1:0,cursor=cursorKey?values[0]:null,team=values[offset],credential=values[offset+1],membership=values[offset+2],currentRows=values[offset+3],allGrants=values[offset+4];
-  let at=offset+5;const olderRows=cursorKey?values[at++]:[],allMessages=search?[...values[at++],...(cursorKey?values[at++]:[])]:[];
+  const olderRows=cursorKey?values[offset+5]:[];
   const rows=[...currentRows,...olderRows],currentById=new Map(currentRows.map(row=>[row.id,row]));
   const boundaryNow=api.clock.nowMs();
   if(!membership?.active||credential?.revoked_at!=null||(credential?.expires_at!=null&&credential.expires_at<=boundaryNow))fail(401,'authentication_required','authentication required');
@@ -173,9 +175,8 @@ async function listSessions(api,res,auth,url,requestId,search){
     if(cursor.kind!==(search?'search':'list')||cursor.expires_at<=boundaryNow||cursor.auth_epoch!==team.auth_epoch||canonicalJson(JSON.parse(cursor.query_json))!==canonicalJson(normalizedQuery))fail(409,'resync_required','cursor expired, mismatched, or authorization changed');
     tuples=JSON.parse(cursor.snapshot_json);
   }else tuples=rows.filter(row=>row.revision===row.version_revision).map(row=>[row.id,row.version_revision]);
-  const rowByVersion=new Map(rows.map(row=>[`${row.id}:${row.version_revision}`,row])),grantsBySession=new Map(),messagesByVersion=new Map();
+  const rowByVersion=new Map(rows.map(row=>[`${row.id}:${row.version_revision}`,row])),grantsBySession=new Map();
   for(const grant of allGrants){const list=grantsBySession.get(grant.session_id)??[];list.push(grant);grantsBySession.set(grant.session_id,list);}
-  for(const message of allMessages){const key=`${message.session_id}:${message.revision}`,list=messagesByVersion.get(key)??[];list.push(message);messagesByVersion.set(key,list);}
   const hits=[],hitTuples=[];
   for(const [id,revision]of tuples){
     const row=rowByVersion.get(`${id}:${revision}`),current=currentById.get(id);
@@ -190,7 +191,20 @@ async function listSessions(api,res,auth,url,requestId,search){
     if(query.until!==undefined&&row.sort_at>=query.until)continue;
     if(query.include_children===false&&view.parent_id!==null)continue;
     let hit=view;
-    if(search){const needle=normalizeSearch(query.query.trim()),messages=messagesByVersion.get(`${id}:${revision}`)??[],matches=[],title=normalizeSearch(view.title??'');if(title.includes(needle))matches.push({message_id:null,field:'title',excerpt:title,offset:title.indexOf(needle)});for(const message of messages){const text=normalizeSearch(message.search_text),at=text.indexOf(needle);if(at>=0&&matches.length<3)matches.push({message_id:message.id,field:'content',excerpt:[...text].slice(Math.max(0,at-120),at+needle.length+120).join(''),offset:at});}if(!matches.length)continue;hit={session:view,matches,match_at:Math.max(...messages.map(message=>message.recorded_at??0),row.sort_at),indexed_revision:revision};}
+    if(search){
+      const needle=normalizeSearch(query.query.trim()),matches=[],title=normalizeSearch(view.title??'');
+      if(title.includes(needle))matches.push({message_id:null,field:'title',excerpt:title,offset:[...title.slice(0,title.indexOf(needle))].length});
+      // search_text is normalized on ingestion. SQLite matches the pinned version and returns only three bounded
+      // excerpts; neither nonmatching/private transcripts nor the org's retained text enter the Worker's heap.
+      const found=await api.store.query(`SELECT m.id,instr(m.search_text,?)-1 offset,
+        substr(m.search_text,max(1,instr(m.search_text,?)-120),length(?)+240) excerpt
+        FROM messages m WHERE m.team_id=? AND m.session_id=? AND ${MESSAGE_AT('m')}
+        AND instr(m.search_text,?)>0 ORDER BY m.ordinal,m.id LIMIT ?`,[needle,needle,needle,auth.team_id,id,revision,revision,needle,3-matches.length]);
+      matches.push(...found.map(message=>({message_id:message.id,field:'content',excerpt:message.excerpt,offset:message.offset})));
+      if(!matches.length)continue;
+      const latest=await api.store.one(`SELECT max(recorded_at) at FROM messages m WHERE m.team_id=? AND m.session_id=? AND ${MESSAGE_AT('m')}`,[auth.team_id,id,revision,revision]);
+      hit={session:view,matches,match_at:Math.max(latest?.at??0,row.sort_at),indexed_revision:revision};
+    }
     hits.push(hit);hitTuples.push([id,revision]);
   }
   const limit=query.limit??50,page=hits.slice(0,limit);let next=null;