@volter/supercode-teams 0.2.20

package/connector/index.mjs

@@ -0,0 +1,174 @@
+import { mkdirSync, readFileSync, writeFileSync, renameSync, existsSync, chmodSync, realpathSync, statSync, openSync, closeSync, fsyncSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { randomBytes, createHash } from 'node:crypto';
+import { canonicalJson } from '../contracts/index.mjs';
+import { EffectConsumer } from './effects.mjs';
+import { NativeEffects } from './native-effects.mjs';
+
+const hash=value=>createHash('sha256').update(value).digest('hex');
+const recordedAt=entry=>{if(Number.isSafeInteger(entry.recorded_at))return entry.recorded_at;if(Number.isSafeInteger(entry.timestamp))return entry.timestamp;const value=entry.metadata?.timestamp??entry.value?.metadata?.timestamp??entry.timestamp;if(typeof value!=='string')return null;const parsed=Date.parse(value);return Number.isSafeInteger(parsed)?parsed:null;};
+const serverOrigin=value=>{const url=new URL(value),loopback=url.hostname==='localhost'||url.hostname==='::1'||url.hostname==='[::1]'||/^127(?:\.\d{1,3}){3}$/.test(url.hostname);if(!['http:','https:'].includes(url.protocol)||url.username||url.password||url.search||url.hash||(url.pathname!==''&&url.pathname!=='/')||(url.protocol==='http:'&&!loopback))throw new TypeError('server must be an HTTPS origin (HTTP is loopback-only)');return url.origin;};
+function atomic(path, value) {
+  const temporary = `${path}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`;
+  const fd = openSync(temporary, 'wx', 0o600);
+  try { writeFileSync(fd, JSON.stringify(value, null, 2) + '\n'); fsyncSync(fd); }
+  catch (error) { try { unlinkSync(temporary); } catch {} throw error; }
+  finally { closeSync(fd); }
+  renameSync(temporary, path);
+  chmodSync(path, 0o600);
+  // Node cannot open a directory descriptor on Windows. The file is flushed on
+  // every platform; server-side claimed state also prevents replay after restart.
+  if (process.platform !== 'win32') {
+    const directory = openSync(dirname(path), 'r');
+    try { fsyncSync(directory); } finally { closeSync(directory); }
+  }
+}
+export class TeamsConnector {
+  constructor({server,teamId,machineId,sourceId,credential,stateDir,core,hostKeyId=null,effectExecutor=null,clock={nowMs:()=>Date.now()},fetch:fetchImpl=globalThis.fetch}){Object.assign(this,{server:serverOrigin(server),teamId,machineId,sourceId,credential,stateDir,core,hostKeyId,effectExecutor,clock,fetch:fetchImpl});mkdirSync(stateDir,{recursive:true,mode:0o700});chmodSync(stateDir,0o700);this.statePath=join(stateDir,'connector.json');this.state=existsSync(this.statePath)?JSON.parse(readFileSync(this.statePath,'utf8')):{version:1,sequence:0,origins:{},outbox:[]};this.state.effects??={};this.state.incarnation_id=`inc_${randomBytes(16).toString('hex')}`;this.abort=new AbortController();this.work=Promise.resolve();this.nativeEffects=new NativeEffects(this);this.effects=new EffectConsumer(this,effectExecutor?{prepare:async effect=>({execute:()=>effectExecutor(effect,{core:this.core,signal:this.abort.signal})})}:this.nativeEffects);this.save();}
+  save(){atomic(this.statePath,this.state);} async request(method,path,body){const json=body===undefined?undefined:JSON.stringify(body),mutation=['POST','PATCH','DELETE'].includes(method);const response=await this.fetch(this.server+`/api/v1/teams/${this.teamId}`+path,{method,redirect:'manual',headers:{Authorization:`Bearer ${this.credential}`,'Content-Type':'application/json',...(mutation?{'Idempotency-Key':hash(`${method}\n${path}\n${json??''}`)}:{})},body:json,signal:this.abort.signal});if(response.type==='opaqueredirect'||response.status>=300&&response.status<400)throw Object.assign(new Error('cross-origin redirects are refused'),{code:'invalid_request',status:400});const value=await response.json();if(!response.ok)throw Object.assign(new Error(value.error?.message??`HTTP ${response.status}`),value.error,{status:response.status});return value.data;}
+  async configuration(){const value=await this.request('GET',`/machines/${this.machineId}/configuration`);this.configurationValue=value;return value;}
+  async start({bindings=()=>[],roots=()=>[]}={}) {
+    await this.configuration();
+    const heartbeat = async () => {
+      this.state.sequence += 1;
+      await this.request('POST', `/machines/${this.machineId}/heartbeat`, {
+        incarnation_id: this.state.incarnation_id, sequence: this.state.sequence,
+        bindings: [...this.nativeEffects.published(), ...await bindings()],
+        roots: this.localRoots.map(({id,machine_id,name,harnesses})=>({id,machine_id,name,harnesses})),
+        ...(this.hostKeyId ? { host_key_id: this.hostKeyId } : {}),
+      });
+      this.save();
+    };
+    const beat = async () => {
+      this.localRoots = await roots();
+      await heartbeat();
+      const configuration = await this.configuration();
+      await this.syncConfiguredSessions(configuration, this.localRoots);
+      await heartbeat();
+      await this.pollEffects();
+    };
+    await beat();
+    let running = false;
+    this.timer = setInterval(() => {
+      if (running || this.abort.signal.aborted) return;
+      running = true;
+      void beat().catch(error => { this.lastError = error; }).finally(() => { running = false; });
+    }, 15000);
+    return this.configurationValue;
+  }
+  async effectFetch(method, path, {body, contentType='application/json', raw=false, freshKey=false}={}) {
+    const response = await this.fetch(this.server + `/api/v1/teams/${this.teamId}` + path, {
+      method, redirect: 'manual', headers: {
+        Authorization: `Bearer ${this.credential}`, Accept: raw ? 'application/octet-stream' : 'application/json',
+        'Content-Type': contentType, 'X-Teams-Incarnation': this.state.incarnation_id,
+        ...(['POST','DELETE'].includes(method) && contentType === 'application/json' ? {'Idempotency-Key': freshKey ? randomBytes(24).toString('hex') : hash(`${method}\n${path}\n${body??''}`)} : {}),
+      }, body, ...(body instanceof ReadableStream ? {duplex:'half'} : {}), signal: this.abort.signal,
+    });
+    if (response.type === 'opaqueredirect' || response.status >= 300 && response.status < 400) throw Object.assign(new Error('redirects are refused'), {code:'invalid_request',status:400});
+    if (!response.ok) {
+      const value = await response.json();
+      throw Object.assign(new Error(value.error?.message ?? `HTTP ${response.status}`), value.error, {status:response.status});
+    }
+    if (raw) return response;
+    if (response.status === 204) return null;
+    const value = await response.json();
+    return value.data ?? value;
+  }
+  effectRequest(method, path, body, options={}) { return this.effectFetch(method,path,{...options,body:body===undefined?undefined:JSON.stringify(body)}); }
+  pollEffects() { return this.effects.poll(); }
+  async syncConfiguredSessions(configuration,roots){
+    if(typeof this.core.discover!=='function')return;
+    this.followers??=new Map();
+    this.nativeEffects.beginDiscovery();
+    const activeRules=new Map(configuration.rules.filter(item=>item.state==='active').map(rule=>[rule.id,rule]));
+    for(const [key,follower] of this.followers){const rule=activeRules.get(follower.ruleId);if(!rule||rule.revision!==follower.ruleRevision){follower.controller.abort();this.followers.delete(key);}}
+    for(const rule of activeRules.values()){
+      const root=roots.find(item=>item.id===rule.selector.root_id);
+      if(!root)continue;
+      const descriptors=[];
+      let cursor;
+      do {
+        const page=await this.core.discover({workspace:root.path??root.workspace,harnesses:rule.selector.harnesses,homes:root.homes,limit:2048,...(cursor?{cursor}:{})});
+        descriptors.push(...(page.sessions??page.entries??[]));
+        cursor=page.next_cursor??page.nextCursor??null;
+      } while(cursor);
+      for(const descriptor of descriptors){
+        const locator=descriptor.locator,nativeSessionId=locator?.session_id,harness=locator?.harness;
+        if(!locator||!nativeSessionId||!harness)continue;
+        const options={locator,descriptor,harness,nativeSessionId,ruleId:rule.id,ruleRevision:rule.revision,backfill:rule.backfill,rootPath:root.path??root.workspace};
+        await this.capture(options);
+        try { await this.nativeEffects.discover(descriptor, rule.id); } catch (error) { this.lastError = error; }
+        const key=`${rule.id}:${harness}:${nativeSessionId}`;
+        if(this.followers.has(key)||typeof this.core.session(locator).follow!=='function')continue;
+        const controller=new AbortController(),stop=()=>controller.abort(this.abort.signal.reason);this.abort.signal.addEventListener('abort',stop,{once:true});
+        const task=(async()=>{for await(const _event of this.core.session(locator).follow({signal:controller.signal})){if(controller.signal.aborted)break;await this.capture(options);}})().catch(error=>{if(!controller.signal.aborted)this.lastError=error;}).finally(()=>{this.abort.signal.removeEventListener('abort',stop);this.followers.delete(key);});
+        this.followers.set(key,{ruleId:rule.id,ruleRevision:rule.revision,controller,task});
+      }
+    }
+    this.nativeEffects.endDiscovery();
+  }
+  capture(options) {
+    const work=this.work.then(()=>this.captureSerial(options));
+    this.work=work.catch(()=>{});
+    return work;
+  }
+  async captureSerial({locator,descriptor=null,harness,nativeSessionId,visibility='restricted',ruleId=null,ruleRevision=null,coverage={completeness:'complete',reasons:[],missing:[]},backfill='all',rootPath=null}) {
+    if(this.state.outbox.length)await this.flushSerial();
+    const configuration=await this.configuration(),rule=configuration.rules.find(item=>item.id===ruleId&&item.revision===ruleRevision&&item.state==='active');if(!rule)throw Object.assign(new Error('sync rule is absent, inactive, or stale'),{code:'forbidden'});visibility=rule.visibility;
+    const artifactSource=locator?.storage?.kind==='file'&&existsSync(locator.storage.path)?realpathSync(locator.storage.path):null;
+    const artifactBefore=artifactSource?statSync(artifactSource):null;
+    const loaded=await this.core.session(locator).load(),configuredBackfill=rule.backfill??backfill??'all',backfillPolicy=typeof configuredBackfill==='string'?{mode:configuredBackfill,since:null}:configuredBackfill;
+    const key=`${harness}:${nativeSessionId}`,previous=this.state.origins[key]??null;
+    let messages=(loaded.messages??loaded.turns??[]).map((entry,index)=>{const value=entry.value??Object.fromEntries(Object.entries(entry).filter(([key])=>!['id','native_key','recorded_at','timestamp'].includes(key)));return{native_key:entry.id??entry.native_key??String(index),recorded_at:recordedAt(entry),value};});
+    if(previous?.last_rule_revision===ruleRevision&&previous?.backfill_mode===backfillPolicy.mode&&previous?.observed_keys?.length===messages.length&&messages.every((message,index)=>message.native_key===previous.observed_keys[index]&&hash(canonicalJson(message.value))===previous.observed_digests?.[index]))return null;
+    let effectivePrevious=previous;
+    if(!previous&&backfillPolicy.mode==='none'){this.state.origins[key]={generation:1,sequence:0,digest:null,baseline:messages.map(x=>x.native_key),baseline_digests:messages.map(x=>hash(canonicalJson(x.value))),observed_keys:messages.map(x=>x.native_key),observed_digests:messages.map(x=>hash(canonicalJson(x.value))),last_rule_revision:ruleRevision,backfill_mode:backfillPolicy.mode};this.save();return null;}
+    if(!previous&&backfillPolicy.mode==='since'){
+      if(!Number.isSafeInteger(backfillPolicy.since))throw Object.assign(new Error('since backfill requires an integer timestamp'),{code:'invalid_request'});
+      const excluded=messages.filter(message=>message.recorded_at==null||message.recorded_at<backfillPolicy.since);
+      effectivePrevious={generation:1,sequence:0,digest:null,baseline:excluded.map(message=>message.native_key),baseline_digests:excluded.map(message=>hash(canonicalJson(message.value)))};
+      this.state.origins[key]=effectivePrevious;
+    }
+    if(previous?.observed_keys?.every(x=>/^\d+$/.test(x))){
+      const prefix=messages.slice(0,previous.observed_keys.length);
+      const rewritten=prefix.length!==previous.observed_keys.length||prefix.some((message,index)=>message.native_key!==previous.observed_keys[index]||hash(canonicalJson(message.value))!==previous.observed_digests?.[index]);
+      if(rewritten)throw Object.assign(new Error('index-key source rewrote its baseline; explicit backfill is required'),{code:'resync_required'});
+    }
+    const clearBaseline=backfillPolicy.mode==='all';
+    if(effectivePrevious?.baseline&&!clearBaseline)messages=messages.filter(x=>!effectivePrevious.baseline.includes(x.native_key));
+    if(!messages.length)return null;
+    const captureId=`cap_${randomBytes(16).toString('hex')}`,generation=effectivePrevious?.generation??1,sequence=(effectivePrevious?.sequence??0)+1;
+    const begin={native_session_id:nativeSessionId,harness,generation,sequence,capture_id:captureId,previous_digest:effectivePrevious?.digest??null,visibility,rule_id:ruleId,rule_revision:ruleRevision};
+    const parts=[];for(let index=0;index<messages.length;index+=500)parts.push({capture_id:captureId,index:parts.length,messages:messages.slice(index,index+500)});
+    const artifacts=[];
+    // Native stores normally live in harness homes outside the repository. The locator is
+    // accepted only when it came from this configured core discovery, and raw bytes are safe
+    // to publish only when the complete native history is in the permitted projection.
+    let nativeBundle=null;
+    // A session in a shared SQLite store (OpenCode, Goose) has no file of its own to stat; it is
+    // stable when the core reads back the same messages this capture publishes.
+    const sqliteSource=locator?.storage?.kind==='sqlite';
+    if((artifactSource||sqliteSource)&&backfillPolicy.mode==='all'&&!effectivePrevious?.baseline&&typeof this.core.translateSession==='function'){
+      if(artifactSource&&!artifactBefore.isFile())throw Object.assign(new Error('native artifact locator is not a regular file'),{code:'invalid_request'});
+      const translated=(await this.core.translateSession({locator,target_harness:harness})).artifact;
+      const changed=new Error('native session changed while it was being captured');
+      if(artifactSource){const after=statSync(artifactSource);if(artifactBefore.dev!==after.dev||artifactBefore.ino!==after.ino||artifactBefore.size!==after.size||artifactBefore.mtimeMs!==after.mtimeMs)throw Object.assign(changed,{code:'resync_required'});}
+      else{const digest=entries=>hash(canonicalJson((entries.messages??entries.turns??[]).map(entry=>entry.value??entry)));if(digest(await this.core.session(locator).load())!==digest(loaded))throw Object.assign(changed,{code:'resync_required'});}
+      const translatedFiles=translated.files?.length?translated.files:[{path:translated.suggested_filename??(artifactSource?basename(artifactSource):`${nativeSessionId}.json`),content:translated.content,role:'primary'}];
+      if(translatedFiles.filter(file=>file.role==='primary').length!==1)throw Object.assign(new Error('native codec bundle must contain exactly one primary file'),{code:'fidelity_unavailable'});
+      let total=0;const bundleFiles=[];
+      for(const file of translatedFiles){const bytes=Buffer.from(file.content,'utf8');total+=bytes.length;if(total>256*1024*1024)throw Object.assign(new Error('native artifact bundle exceeds 256 MiB'),{code:'request_too_large'});const uploadId=`upload_${randomBytes(16).toString('hex')}`,chunks=[];for(let at=0,index=0;at<bytes.length||index===0;at+=1024*1024,index++){const chunk=bytes.subarray(at,Math.min(bytes.length,at+1024*1024));chunks.push({upload_id:uploadId,index,sha256:hash(chunk),bytes_base64:chunk.toString('base64')});if(bytes.length===0)break;}artifacts.push({manifest:{upload_id:uploadId,relative_name:file.path,sha256:hash(bytes),byte_length:bytes.length,chunks:chunks.length,media_type:'application/octet-stream',role:file.role==='source_recovery'?'sidecar':'native'},chunks});bundleFiles.push({upload_id:uploadId,role:file.role});}
+      nativeBundle={id:bundleFiles.find(file=>file.role==='primary').upload_id,harness,fidelity:translated.fidelity,residue:translated.residue??[],files:bundleFiles};
+    }
+    const recordedTimes=messages.map(message=>message.recorded_at).filter(Number.isSafeInteger),commit={capture_id:captureId,parts:parts.length,digest:'',title:descriptor?.title??null,repository:null,reported_user:null,recorded_activity_at:recordedTimes.length?Math.max(...recordedTimes):null,parent_native_id:descriptor?.parent_session_id??null,coverage:effectivePrevious?.baseline&&!clearBaseline?{...coverage,completeness:'partial',reasons:[...new Set([...coverage.reasons,'prefix_not_captured'])]}:coverage,artifacts:artifacts.map(item=>item.manifest),...(nativeBundle?{native_bundle:nativeBundle}:{})};
+    const digestCommit={...commit};delete digestCommit.digest;commit.digest=hash(canonicalJson({begin,parts,commit:digestCommit}));
+    this.state.outbox.push({begin,parts,commit,artifacts,clearBaseline,backfillMode:backfillPolicy.mode,observed:{keys:(loaded.messages??loaded.turns??[]).map((entry,index)=>entry.id??entry.native_key??String(index)),digests:(loaded.messages??loaded.turns??[]).map(entry=>hash(canonicalJson(entry.value??Object.fromEntries(Object.entries(entry).filter(([key])=>!['id','native_key','recorded_at','timestamp'].includes(key))))))}});this.save();return this.flushSerial();
+  }
+  flush() {
+    const work=this.work.then(()=>this.flushSerial());
+    this.work=work.catch(()=>{});
+    return work;
+  }
+  async flushSerial(){let latest=null;while(this.state.outbox.length){const item=this.state.outbox[0];const begun=await this.request('POST',`/sources/${this.sourceId}/captures`,item.begin);let receipt;if(begun.state==='committed')receipt=begun.receipt;else{for(const part of item.parts)await this.request('PUT',`/sources/${this.sourceId}/captures/${item.begin.capture_id}/parts/${part.index}`,part);for(const artifact of item.artifacts??[])for(const chunk of artifact.chunks)await this.request('PUT',`/sources/${this.sourceId}/uploads/${chunk.upload_id}/chunks/${chunk.index}`,chunk);receipt=await this.request('POST',`/sources/${this.sourceId}/captures/${item.begin.capture_id}/commit`,item.commit);}const key=`${item.begin.harness}:${item.begin.native_session_id}`,prior=this.state.origins[key]??{},next={...prior,generation:item.begin.generation,sequence:item.begin.sequence,digest:item.commit.digest,observed_keys:item.observed?.keys??prior.observed_keys,observed_digests:item.observed?.digests??prior.observed_digests,last_rule_revision:item.begin.rule_revision,backfill_mode:item.backfillMode};if(item.clearBaseline){delete next.baseline;delete next.baseline_digests;}this.state.origins[key]=next;this.state.outbox.shift();this.save();latest=receipt;}return latest;}
+  stop(){if(this.timer)clearInterval(this.timer);this.abort.abort();for(const follower of this.followers?.values()??[])follower.controller.abort();return this.nativeEffects.close();}
+}

package/connector/native-continuation.d.ts

@@ -0,0 +1,8 @@
+import type { SupercodeHarnessClient, ManagedRuntime } from '@volter/supercode-harness-sdk';
+import type { LocalLaunchTicket } from '../contracts/index.js';
+
+export interface NativeContinuationAdapter {
+  supports(request: { harness: string; fidelity: string }): boolean;
+  launch(request: { ticket: LocalLaunchTicket; directory: string; fidelity?: string; signal?: AbortSignal }): Promise<{ native_session_id: string; runtime: ManagedRuntime }>;
+}
+export declare function createNativeContinuationAdapter(options: { core: SupercodeHarnessClient }): NativeContinuationAdapter;

package/connector/native-continuation.mjs

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+// A continuation materializes a new native session (new ids), so value_lossless is the only
+// fidelity it delivers.
+export const CONTINUATION_HARNESSES = new Set(['claude-code', 'codex', 'pi', 'grok', 'opencode']);
+export const CONTINUATION_FIDELITY = 'value_lossless';
+
+export function createNativeContinuationAdapter({ core }) {
+  if (!core || typeof core.materializeSession !== 'function' || typeof core.resumeManagedRuntime !== 'function') {
+    throw new TypeError('native continuation requires a materialization-capable core client');
+  }
+  return {
+    supports({ harness, fidelity }) {
+      return CONTINUATION_HARNESSES.has(harness) && fidelity === CONTINUATION_FIDELITY;
+    },
+    async launch({ ticket, directory, fidelity = ticket?.fidelity, signal }) {
+      if (!this.supports({ harness: ticket?.harness, fidelity }) || !fidelitySatisfies(ticket?.artifact?.fidelity, fidelity)) throw unsupported('native continuation format or fidelity is unsupported');
+      if (signal?.aborted) throw signal.reason ?? new Error('native continuation was aborted');
+      const files = ticket.artifact.files.map(file => {
+        const path = resolve(directory, file.relative_name);
+        if (!path.startsWith(`${resolve(directory)}/`)) throw unsupported('native continuation artifact escapes its verified directory');
+        return { path: file.relative_name, content: readFileSync(path, 'utf8'), role: file.role };
+      });
+      const primary = files.filter(file => file.role === 'primary');
+      if (primary.length !== 1) throw unsupported('native continuation requires exactly one primary artifact');
+      const materialized = await core.materializeSession({
+        artifact: {
+          source_harness: ticket.harness,
+          target_harness: ticket.harness,
+          session_id: null,
+          content: primary[0].content,
+          suggested_filename: primary[0].path,
+          files,
+          fidelity,
+          residue: ticket.artifact.residue ?? [],
+        },
+        cwd: ticket.destination.cwd,
+      }, { signal });
+      const locator = materialized?.locator;
+      if (!locator?.session_id || locator.harness !== ticket.harness) throw unsupported('core materialization returned no resumable native identity');
+      const runtime = await core.resumeManagedRuntime({ harness: locator.harness, runtime_id: locator.session_id, cwd: ticket.destination.cwd }, { signal });
+      if (!runtime?.handle?.runtime_id) { await runtime?.close?.().catch(() => {}); throw unsupported('native runtime resume returned no runtime identity'); }
+      return { native_session_id: locator.session_id, runtime };
+    },
+  };
+}
+
+function unsupported(message) { return Object.assign(new Error(message), { code: 'unsupported', nativeOutcome: 'failed' }); }
+function fidelitySatisfies(actual, requested) { return ({ semantic: 0, value_lossless: 1, byte_lossless: 2 }[actual] ?? -1) >= ({ semantic: 0, value_lossless: 1, byte_lossless: 2 }[requested] ?? Infinity); }

package/connector/native-effects.mjs

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve, relative, dirname, isAbsolute, sep } from 'node:path';
+
+const digest = value => createHash('sha256').update(value).digest('hex');
+const refused = (message, code = 'unsupported') => Object.assign(new Error(message), { code, nativeOutcome: 'failed', teamsSafeMessage: true });
+const within = (root, path) => { const name = relative(root, path); return name === '' || !isAbsolute(name) && name !== '..' && !name.startsWith(`..${sep}`); };
+const LIMIT = 1024 * 1024;
+
+export class NativeEffects {
+  constructor(connector) { this.c = connector; this.bindings = new Map(); this.attachments = new Map(); this.ownedRuntimes = new Set(); }
+  async discover(descriptor, ruleId) {
+    const c = this.c, locator = descriptor.locator;
+    if (!descriptor.live_endpoint?.startsWith('supercode-live://') || !descriptor.cwd || !c.core.attachManagedRuntime || !c.core.runtimeCapabilities) return;
+    const id = `bind_${digest(`${c.machineId}:${c.state.incarnation_id}:${locator.harness}:${locator.session_id}`).slice(0,32)}`;
+    const params = { harness: locator.harness, runtime_id: locator.session_id, cwd: descriptor.cwd, base_url: descriptor.live_endpoint };
+    const existing = this.bindings.get(id);
+    if (existing && JSON.stringify(existing.params) === JSON.stringify(params)) { existing.seen = true; existing.ruleId = ruleId; return; }
+    const { capabilities } = await c.core.runtimeCapabilities(params);
+    if (!capabilities.attach_existing_process || !capabilities.stream_events) return;
+    const runtime = await c.core.attachManagedRuntime(params);
+    try {
+      const actions = ['attach_observe'];
+      if (capabilities.send_input) actions.push('interact');
+      if (capabilities.interrupt) actions.push('interrupt');
+      if (capabilities.respond_to_requests) actions.push('approve');
+      this.bindings.set(id, { params, ruleId, seen: true, descriptor: {
+        id, machine_id: c.machineId, incarnation_id: c.state.incarnation_id,
+        native_runtime_id: runtime.handle.runtime_id, native_session_id: locator.session_id,
+        harness: locator.harness, state: 'running', observed_at: c.clock.nowMs(), native_capabilities: actions,
+      } });
+    } finally { await runtime.close(); } // This backend's close detaches the observer only.
+  }
+  beginDiscovery() { for (const binding of this.bindings.values()) binding.seen = false; }
+  endDiscovery() { for (const [id, binding] of this.bindings) if (!binding.seen) this.bindings.delete(id); }
+  published() { return [...this.bindings.values()].map(binding => ({ ...binding.descriptor, observed_at: this.c.clock.nowMs() })); }
+  async prepare(effect) {
+    if (effect.kind === 'continue') return this.prepareContinuation(effect);
+    const binding = this.bindings.get(effect.binding_id);
+    if (!binding) throw refused('native binding is no longer available', 'missing_context');
+    const action = effect.kind === 'input' ? 'interact' : effect.kind === 'attach' ? 'attach_observe' : effect.kind;
+    if (!binding.descriptor.native_capabilities.includes(action)) throw refused('native binding does not support this action');
+    if (effect.kind === 'attach') {
+      if (effect.payload.mode === 'control' && !binding.descriptor.native_capabilities.includes('interact')) throw refused('native binding cannot accept input');
+      return { execute: async () => {
+        const runtime = await this.c.core.attachManagedRuntime(binding.params, { signal: this.c.abort.signal });
+        if (effect.payload.mode === 'control') {
+          if (typeof runtime.acquireControl !== 'function') { await runtime.close(); throw refused('native control lease acquisition is unsupported'); }
+          try { await runtime.acquireControl({signal:this.c.abort.signal}); }
+          catch (error) { await runtime.close(); throw Object.assign(refused('native control lease is unavailable'),{sdkCode:error.sdkCode,data:error.data,code:error.code}); }
+        }
+        if (runtime.handle.runtime_id !== binding.descriptor.native_runtime_id) { await runtime.close(); throw refused('native binding identity changed', 'conflict'); }
+        const entry = { runtime, effect, binding, active: false, queue: [], bytes: 0, requests: new Map(), sending: null, closed: false };
+        entry.listener = frame => {
+          if (entry.closed) return;
+          if (frame.type === 'request') entry.requests.set(JSON.stringify(frame.requestId), frame);
+          const bytes = Buffer.byteLength(JSON.stringify(frame)) + 1;
+          if (bytes > LIMIT || entry.bytes + bytes > LIMIT) { this.c.lastError = refused('native attachment buffer exceeded 1 MiB', 'resync_required'); void this.closeAttachment(entry); return; }
+          entry.queue.push(frame); entry.bytes += bytes;
+          entry.wake?.();
+        };
+        runtime.on('event', entry.listener);
+        this.attachments.set(effect.payload.attachment_id, entry);
+        return { native_session_id: binding.descriptor.native_session_id, runtime_id: runtime.handle.runtime_id };
+      } };
+    }
+    const entry = this.attachments.get(effect.payload.attachment_id);
+    if (!entry || entry.closed || !entry.active || entry.effect.binding_id !== effect.binding_id) throw refused('native attachment is unavailable', 'missing_context');
+    let request, option;
+    if (effect.kind === 'approve') {
+      request = [...entry.requests.values()].find(item => String(item.requestId) === effect.payload.request_id);
+      option = request?.options.find(item => item.kind === (effect.payload.decision === 'allow_once' ? 'allow_once' : 'reject_once'));
+      if (!option) throw refused('native permission request or exact decision is unavailable', 'missing_context');
+    }
+    return { execute: async () => {
+      if (effect.kind === 'input') await entry.runtime.sendInput(effect.payload.text, { signal: this.c.abort.signal });
+      else if (effect.kind === 'interrupt') await entry.runtime.interrupt({ signal: this.c.abort.signal });
+      else if (effect.kind === 'approve') { await entry.runtime.respond(request.requestId, option.response, { signal: this.c.abort.signal }); entry.requests.delete(JSON.stringify(request.requestId)); }
+      else throw refused('native termination is not supported by an observer connection');
+      return { native_session_id: binding.descriptor.native_session_id, runtime_id: entry.runtime.handle.runtime_id };
+    } };
+  }
+  async activate(effect) {
+    if (effect.kind !== 'attach') return;
+    const entry = this.attachments.get(effect.payload.attachment_id);
+    if (!entry || entry.closed) throw refused('native observer closed before activation', 'missing_context');
+    if (entry.active) return;
+    entry.active = true;
+    const stream = new ReadableStream({
+      pull: async controller => {
+        while (!entry.closed && !entry.queue.length) await new Promise(resolve => { entry.wake = resolve; });
+        entry.wake = null;
+        if (entry.closed) { controller.close(); return; }
+        const frame = entry.queue.shift(), line = `${JSON.stringify(frame)}\n`;
+        entry.bytes -= Buffer.byteLength(line);
+        controller.enqueue(Buffer.from(line));
+        if (frame.type === 'closed' || frame.type === 'error' && frame.terminal) controller.close();
+      },
+      cancel: () => { entry.wake?.(); },
+    }, {highWaterMark:0});
+    // One bounded streaming request per attachment, rather than one HTTP mutation
+    // for every token. A failed response closes this observer; frames are never replayed.
+    entry.sending = this.frames(entry, stream).catch(error => { this.c.lastError = error; }).finally(() => this.closeAttachment(entry));
+  }
+  async discard(effect) { if (effect.kind === 'attach') await this.closeAttachment(this.attachments.get(effect.payload.attachment_id)); }
+  frames(entry, body) { return this.c.effectFetch('POST', `/machines/${this.c.machineId}/attachments/${entry.effect.payload.attachment_id}/frames`, { body, contentType: 'application/x-ndjson' }); }
+  async recheck() {
+    for (const entry of this.attachments.values()) {
+      if (entry.closed) continue;
+      if (entry.effect.expires_at <= this.c.clock.nowMs() || !this.bindings.has(entry.effect.binding_id)) { await this.closeAttachment(entry); continue; }
+      if (entry.active) try { await this.frames(entry, ''); await entry.runtime.heartbeat?.({signal:this.c.abort.signal}); } catch (error) { this.c.lastError = error; await this.closeAttachment(entry); }
+    }
+  }
+  async closeAttachment(entry) {
+    if (!entry || entry.closed) return;
+    entry.closed = true; entry.queue = []; entry.bytes = 0; entry.wake?.();
+    entry.runtime.off('event', entry.listener);
+    this.attachments.delete(entry.effect.payload.attachment_id);
+    await entry.runtime.close().catch(error => { this.c.lastError = error; });
+    if (!this.c.abort.signal.aborted) await this.c.effectRequest('DELETE', `/machines/${this.c.machineId}/attachments/${entry.effect.payload.attachment_id}`).catch(error => { this.c.lastError = error; });
+  }
+  async prepareContinuation(effect) {
+    const c = this.c, path = `/machines/${c.machineId}/effects/${effect.id}`;
+    const ticket = await c.effectRequest('GET', `${path}/continuation`);
+    if (ticket.kind !== 'remote_launch' || ticket.destination?.machine_id !== c.machineId || ticket.continuation_id !== effect.payload.continuation_id || ticket.expires_at <= c.clock.nowMs()) throw refused('invalid remote continuation ticket', 'invalid_request');
+    const root = c.localRoots?.find(item => item.id === ticket.destination.root_id);
+    if (!root) throw refused('destination root is not registered', 'missing_context');
+    const rootPath = realpathSync(root.path ?? root.workspace), cwd = realpathSync(resolve(rootPath, ticket.destination.cwd));
+    if (!within(rootPath, cwd) || !statSync(cwd).isDirectory()) throw refused('destination cwd escapes the configured root', 'forbidden');
+    const { createNativeContinuationAdapter } = await import('./native-continuation.mjs');
+    const adapter = createNativeContinuationAdapter({ core: c.core });
+    if (!adapter.supports({ harness: ticket.harness, fidelity: ticket.fidelity })) throw refused('native continuation format or requested fidelity is unsupported');
+    if (!Array.isArray(ticket.artifact?.files) || ticket.artifact.files.filter(file => file.role === 'primary').length !== 1) throw refused('invalid native artifact bundle', 'invalid_request');
+    const stage = mkdtempSync(join(c.stateDir, 'continuation-'));
+    try {
+      let total = 0;
+      for (const file of ticket.artifact.files) {
+        const name = file.relative_name;
+        if (typeof name !== 'string' || !name || name.includes('\\') || isAbsolute(name) || name.split('/').some(part => !part || part === '.' || part === '..') || !/^upload_[A-Za-z0-9_-]+$/.test(file.upload_id)) throw refused('unsafe artifact file', 'invalid_request');
+        if (!Number.isSafeInteger(file.byte_length) || file.byte_length < 0 || (total += file.byte_length) > 256 * 1024 * 1024) throw refused('native artifact bundle exceeds its bound', 'request_too_large');
+        const response = await c.effectFetch('GET', `${path}/artifacts/${file.upload_id}`, { raw: true });
+        const parts = []; let size = 0;
+        for await (const part of response.body) { size += part.length; if (size > file.byte_length) throw refused('artifact length mismatch', 'conflict'); parts.push(part); }
+        const bytes = Buffer.concat(parts);
+        if (bytes.length !== file.byte_length || digest(bytes) !== file.sha256) throw refused('artifact checksum mismatch', 'conflict');
+        const target = join(stage, name); mkdirSync(dirname(target), { recursive: true, mode: 0o700 }); writeFileSync(target, bytes, { flag: 'wx', mode: 0o600 });
+      }
+      return { dispose: () => rmSync(stage, { recursive: true, force: true }), execute: async () => {
+        if (realpathSync(resolve(rootPath, ticket.destination.cwd)) !== cwd || realpathSync(root.path ?? root.workspace) !== rootPath) throw refused('destination root changed', 'conflict');
+        // Recheck the pinned ticket after download and immediately before native work.
+        const fresh = await c.effectRequest('GET', `${path}/continuation`);
+        if (JSON.stringify(fresh) !== JSON.stringify(ticket)) throw refused('continuation ticket changed', 'conflict');
+        const launched = await adapter.launch({ ticket: { ...ticket, kind: 'local_launch', destination: { cwd } }, directory: stage, signal: c.abort.signal });
+        this.ownedRuntimes.add(launched.runtime);
+        return { native_session_id: launched.native_session_id, runtime_id: launched.runtime.handle.runtime_id };
+      } };
+    } catch (error) { rmSync(stage, { recursive: true, force: true }); throw error; }
+  }
+  async close() {
+    await Promise.allSettled([...this.attachments.values()].map(entry => this.closeAttachment(entry)));
+    await Promise.allSettled([...this.ownedRuntimes].map(runtime => runtime.close()));
+    this.ownedRuntimes.clear();
+  }
+}

package/context.mjs

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync, writeFileSync, renameSync, openSync, closeSync, unlinkSync, existsSync, chmodSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join, dirname } from 'node:path';
+import { TeamsClient } from './workspace-client.mjs';
+const NAME=/^[a-z][a-z0-9_-]{0,63}$/;
+const ID=/^[A-Za-z][A-Za-z0-9_-]{0,127}$/;
+function normalizeOrigin(value){const url=new URL(value);if(url.username||url.password||url.pathname!=='/'||url.search||url.hash)throw new Error('server must be a bare HTTP(S) origin');if(url.protocol!=='https:'&&!(url.protocol==='http:'&&['127.0.0.1','::1','[::1]','localhost'].includes(url.hostname)))throw new Error('non-loopback servers require HTTPS');return url.origin;}
+export function workspacePaths(supercodeHome){const root=join(supercodeHome,'teams','workspaces');return {root,contexts:join(root,'contexts.json'),credentials:join(root,'credentials'),connectors:join(root,'connectors')};}
+function locked(path,fn){mkdirSync(dirname(path),{recursive:true,mode:0o700});chmodSync(dirname(path),0o700);const lock=path+'.lock';let fd;try{fd=openSync(lock,'wx',0o600);}catch(e){throw Object.assign(new Error(`${path} is locked by another writer`),{code:'EBUSY',cause:e});}try{return fn();}finally{closeSync(fd);unlinkSync(lock);}}
+function read(path,fallback){return existsSync(path)?JSON.parse(readFileSync(path,'utf8')):fallback;}
+function atomic(path,value){const tmp=`${path}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`,fd=openSync(tmp,'wx',0o600);try{writeFileSync(fd,JSON.stringify(value,null,2)+'\n');}finally{closeSync(fd);}try{renameSync(tmp,path);}catch(error){try{unlinkSync(tmp);}catch{}throw error;}chmodSync(path,0o600);}
+export class WorkspaceContexts { constructor(supercodeHome){this.paths=workspacePaths(supercodeHome);} read(){return read(this.paths.contexts,{version:1,current:null,contexts:{}});} create(name,value){if(!NAME.test(name)||name==='local')throw new Error('context name must match [a-z][a-z0-9_-]{0,63} and cannot be local');return locked(this.paths.contexts,()=>{const doc=this.read();if(doc.contexts[name])throw new Error(`context ${name} already exists`);doc.contexts[name]=value;atomic(this.paths.contexts,doc);return value;});} use(name){return locked(this.paths.contexts,()=>{const doc=this.read();if(name!==null&&name!=='local'&&!doc.contexts[name])throw new Error(`unknown context ${name}`);doc.current=name;atomic(this.paths.contexts,doc);});} remove(name){return locked(this.paths.contexts,()=>{const doc=this.read();delete doc.contexts[name];if(doc.current===name)doc.current=null;atomic(this.paths.contexts,doc);});} writeCredential(id,value){mkdirSync(this.paths.credentials,{recursive:true,mode:0o700});locked(join(this.paths.credentials,`${id}.json`),()=>atomic(join(this.paths.credentials,`${id}.json`),value));} credential(id){return read(join(this.paths.credentials,`${id}.json`),null);} }
+WorkspaceContexts.prototype.upsert=function(name,value){if(!NAME.test(name)||name==='local')throw new Error('context name must match [a-z][a-z0-9_-]{0,63} and cannot be local');return locked(this.paths.contexts,()=>{const doc=this.read();doc.contexts[name]=value;atomic(this.paths.contexts,doc);return value;});};
+WorkspaceContexts.prototype.createAuthenticated=async function(name,{origin,teamId,credentialRef,fetch}){
+  if(!ID.test(teamId)||!/^cred_[A-Za-z0-9_-]+$/.test(credentialRef))throw new Error('team and credential reference must be immutable IDs');
+  const normalized=normalizeOrigin(origin),credential=this.credential(credentialRef);
+  if(!credential?.token)throw Object.assign(new Error(`credential ${credentialRef} is missing`),{code:'authentication_required'});
+  if(credential.origin!==normalized)throw Object.assign(new Error('credential origin does not match requested server'),{code:'authentication_required'});
+  const client=new TeamsClient({server:normalized,credential:credential.token,fetch});
+  const me=await client.me();
+  if(credential.server_id&&credential.server_id!==me.server_id)throw Object.assign(new Error('credential server audience does not match'),{code:'authentication_required'});
+  const membership=me.teams.find(item=>item.team.id===teamId);
+  if(!membership)throw Object.assign(new Error('credential is not a member of the requested team'),{code:'forbidden'});
+  return this.create(name,{origin:normalized,server_id:me.server_id,team_id:teamId,principal_id:me.principal.id,credential_ref:credentialRef});
+};
+WorkspaceContexts.prototype.connector=function(serverId,teamId){
+  if(!ID.test(serverId)||!ID.test(teamId))throw new Error('server and team must be immutable IDs');
+  const directory=join(this.paths.connectors,serverId,teamId),path=join(directory,'enrollment.json');
+  return {directory,read:()=>read(path,null),write:value=>{mkdirSync(directory,{recursive:true,mode:0o700});locked(path,()=>atomic(path,value));},update:fn=>{mkdirSync(directory,{recursive:true,mode:0o700});return locked(path,()=>{const value=fn(read(path,null));if(value===null){if(existsSync(path))unlinkSync(path);}else atomic(path,value);return value;});},remove:()=>{if(existsSync(path))locked(path,()=>unlinkSync(path));}};
+};
+export function fromContext({supercodeHome,name,fetch}){const contexts=new WorkspaceContexts(supercodeHome),doc=contexts.read(),selected=name??doc.current;if(!selected||selected==='local')throw new Error('a remote workspace context is required');const context=doc.contexts[selected];if(!context)throw new Error(`unknown context ${selected}`);const credential=contexts.credential(context.credential_ref);if(!credential?.token)throw Object.assign(new Error(`credential ${context.credential_ref} is missing`),{code:'authentication_required'});if(credential.server_id!==context.server_id||credential.origin!==context.origin)throw Object.assign(new Error('credential audience does not match context'),{code:'authentication_required'});return {client:new TeamsClient({server:context.origin,credential:credential.token,fetch}),context};}
+/** A context name from a team's name: `Volter` → `volter`. */
+export function contextNameOf(team){const name=String(team).toLowerCase().replace(/[^a-z0-9_-]+/g,'-').replace(/^[^a-z]+/,'').slice(0,64);return name||'team';}
+export async function loginContext({supercodeHome,name,origin,teamId,token,invite,identityToken=null,as,fetch}){if(token!=null&&(invite!=null||identityToken!=null))throw new Error('a token signs in alone');if(token==null&&invite==null&&identityToken==null)throw new Error('a token, an invitation or an identity is required');origin=normalizeOrigin(origin);let credential,serverId,principalId,resolvedTeam=teamId;if(invite){const response=await fetch(new URL('/api/v1/invitations/accept',origin),{method:'POST',redirect:'manual',headers:{'Content-Type':'application/json'},body:JSON.stringify({enrollment_code:invite,...(identityToken?{access_token:identityToken}:{})})});if(response.type==='opaqueredirect'||(response.status>=300&&response.status<400))throw new Error('cross-origin redirects are refused');if(!response.ok)throw new Error(`invitation failed: HTTP ${response.status}`);const value=await response.json();credential=value.credential;principalId=value.principal.id;resolvedTeam=value.team.id;token=credential.token;}else if(identityToken){const response=await fetch(new URL('/api/v1/login/volter',origin),{method:'POST',redirect:'manual',headers:{'Content-Type':'application/json'},body:JSON.stringify({access_token:identityToken,...(teamId?{team_id:teamId}:{})})});if(response.type==='opaqueredirect'||(response.status>=300&&response.status<400))throw new Error('cross-origin redirects are refused');if(!response.ok){const detail=await response.json().catch(()=>null);throw new Error(`sign-in failed: ${detail?.error?.message??`HTTP ${response.status}`}`);}const value=await response.json();credential=value.credential;principalId=value.principal.id;resolvedTeam=value.team.id;token=credential.token;}const client=new TeamsClient({server:origin,credential:token,fetch});const me=await client.me();serverId=me.server_id;const membership=me.teams.find(x=>x.team.id===resolvedTeam||x.team.name===resolvedTeam);if(!membership)throw new Error('credential is not a member of the requested team');name??=contextNameOf(membership.team.name);principalId??=me.principal.id;const store=new WorkspaceContexts(supercodeHome);const credentialId=`cred_${crypto.randomUUID().replaceAll('-','')}`;store.writeCredential(credentialId,{token,kind:credential?.kind??'user',expires_at:credential?.expires_at??null,server_id:serverId,origin});const saved=store.upsert(name,{origin,server_id:serverId,team_id:membership.team.id,team_name:membership.team.name,principal_id:principalId,credential_ref:credentialId,label:as??null});if(!store.read().current)store.use(name);return saved;}

package/contracts/adapter-map.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "doors": {
+    "discover": "harness.v1.sessions.discover",
+    "load": "harness.v1.sessions.load",
+    "watch": "harness.v1.sessions.follow",
+    "unwatch": "harness.v1.sessions.unfollow",
+    "export": "harness.v1.sessions.export",
+    "runtime_start": "harness.v1.runtimes.start",
+    "runtime_resume": "harness.v1.runtimes.resume",
+    "runtime_input": "harness.v1.runtimes.send_input",
+    "runtime_interrupt": "harness.v1.runtimes.interrupt",
+    "runtime_close": "harness.v1.runtimes.close"
+  },
+  "unsupported": []
+}