@volter/supercode-teams 0.2.20

package/bin/workspace.mjs

@@ -0,0 +1,726 @@
+#!/usr/bin/env node
+import { hostname } from 'node:os';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+import { WorkspaceContexts, fromContext, loginContext } from '../context.mjs';
+import { productionIds } from '@volter/teams/server/core';
+import { makeToken } from '@volter/teams/server/auth';
+import { moveWorkspace } from '../workspace-move.mjs';
+import { TeamsConnector } from '../connector/index.mjs';
+import { CONTINUATION_FIDELITY, CONTINUATION_HARNESSES } from '../connector/native-continuation.mjs';
+import { TeamsMachine } from '../machine.mjs';
+import { teamsHome, paths } from '@volter/teams/home';
+import { loadOrCreateKeyPair, publicKeyId } from '@volter/teams/identity';
+import { duration, parseArgs, positiveInteger, requireArgs, usage } from './workspace/args.mjs';
+import { reserveArtifactDirectory, reserveProtected, writeProtected } from './workspace/files.mjs';
+import { acquireLifecycle, activeSocket, requestStop } from './workspace/lifecycle.mjs';
+import { volterDeviceSignIn } from './workspace/volter-device.mjs';
+import { loginSummary, signInToTeams } from './workspace/volter-login.mjs';
+
+const ERROR_EXITS = { invalid_request: 2, ambiguous_reference: 2, authentication_required: 3, not_found: 4, forbidden: 4, unsupported: 5, machine_offline: 5, controller_busy: 6, conflict: 6, resync_required: 6, revision_mismatch: 6, idempotency_conflict: 6, batch_gap: 6, capture_conflict: 6, source_paused: 6 };
+
+export async function workspaceMain(argv = process.argv.slice(2), env = process.env, dependencies = {}) {
+  const { flags, positionals } = parseArgs(argv);
+  const teamsPrefix = positionals[0] === 'teams';
+  if (teamsPrefix) positionals.shift();
+  const [verb, sub, ...rest] = positionals;
+  if (flags.help || verb === undefined) return printHelp();
+  const home = env.SUPERCODE_HOME ?? resolve(teamsHome(), '..');
+  const contexts = new WorkspaceContexts(home);
+  const outputStream = dependencies.stdout ?? process.stdout;
+  const output = value => outputStream.write(flags.json ? `${JSON.stringify(value)}\n` : humanOutput(value));
+  if (verb === 'context') return contextCommand({ contexts, flags, sub, rest, output });
+  if (verb === 'server') return serverCommand({ flags, sub, rest, home, output });
+  if (verb === 'login') return loginCommand({ flags, origin: sub, rest, home, output });
+  const explicitContext = flags.context ?? env.SUPERCODE_CONTEXT;
+  let selected = explicitContext ?? contexts.read().current;
+  const urlReference = verb === 'sessions' ? rest.find(value => /^https?:\/\//.test(value)) : null;
+  if (!explicitContext && urlReference) selected = contextForUrl(contexts.read(), urlReference) ?? selected;
+  if (!selected) usage('no workspace context selected');
+  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);
+  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 === 'sessions') return sessionsCommand(sub, command);
+  if (verb === 'members') return membersCommand(sub, command);
+  if (verb === 'groups') return groupsCommand(sub, command);
+  if (verb === 'sources') return sourcesCommand(sub, command);
+  if (verb === 'machines') return machinesCommand(sub, command);
+  if (verb === 'identity') return identityCommand(sub, command);
+  if (verb === 'sync') return syncCommand(sub, command);
+  if (['connect', 'disconnect', 'status'].includes(verb)) return connectorCommand(verb, command, home);
+  if (verb === 'publish' || verb === 'unpublish') return publishCommand(verb, sub, command);
+  usage(`unsupported workspace command ${verb}`);
+}
+
+async function teamsCommand(verb, sub, { flags, rest, output, client }) {
+  if (verb === 'list') { only(flags, ['json', 'help', 'context', 'cursor', 'limit']); requireArgs(rest, 0, 0, 'teams list'); return output(await client.teams({ cursor: flags.cursor, limit: positiveInteger(flags.limit, 50, 'limit') })); }
+  const names = [sub, ...rest].filter(value => value !== undefined);
+  only(flags, ['json', 'help', 'context']); requireArgs(names, 1, 1, 'teams create NAME');
+  return output(await client.createTeam({ name: names[0] }));
+}
+
+async function localCommand({ verb, sub, rest, flags, output }) {
+  if (verb !== 'sessions' || !['list', 'ls'].includes(sub)) unsupported('this command is unavailable in the local context');
+  only(flags, ['json', 'help', 'context', 'cwd', 'harness', 'limit', 'include_children']);
+  requireArgs(rest, 0, 0, 'sessions list');
+  const binary = process.env.SUPERCODE_BIN ?? process.env.SUPERCODE_TEAMS_TEST_BIN ?? 'supercode';
+  const core = new SupercodeHarnessClient({ command: binary, args: ['harness', 'serve'] });
+  try {
+    const page = await core.discover({ workspace: flags.cwd ?? undefined, harnesses: flags.harness ? [flags.harness] : undefined, limit: positiveInteger(flags.limit, 50, 'limit'), includeChildSessions: Boolean(flags.include_children) });
+    return output({ version: 1, context: { local: true }, items: page.sessions ?? [], next_cursor: page.next_cursor ?? null, coverage: page.coverage ?? null });
+  } finally { core.close(); }
+}
+
+async function contextCommand({ contexts, flags, sub, rest, output }) {
+  if (sub === 'list') { requireArgs(rest, 0, 0, 'context list'); return output(contexts.read()); }
+  if (sub === 'show') {
+    requireArgs(rest, 0, 1, 'context show [NAME]');
+    const document = contexts.read(); const name = rest[0] ?? document.current;
+    if (!name) usage('no workspace context selected');
+    if (name === 'local') return output({ name, local: true });
+    if (!document.contexts[name]) notFound(`unknown context ${name}`);
+    return output({ name, ...document.contexts[name] });
+  }
+  if (sub === 'use') { requireArgs(rest, 1, 1, 'context use NAME'); contexts.use(rest[0]); return output({ current: rest[0] }); }
+  if (sub === 'remove') { requireArgs(rest, 1, 1, 'context remove NAME'); contexts.remove(rest[0]); return output({ removed: rest[0] }); }
+  if (sub === 'create') {
+    requireArgs(rest, 1, 1, 'context create NAME --server ORIGIN --team ID --credential-ref ID');
+    for (const key of ['server', 'team', 'credential_ref']) if (!flags[key]) usage(`--${key.replaceAll('_', '-')} is required`);
+    return output(await contexts.createAuthenticated(rest[0], { origin: flags.server, teamId: flags.team, credentialRef: flags.credential_ref, fetch: globalThis.fetch }));
+  }
+  usage('context create|list|show|use|remove');
+}
+
+async function serverCommand({ flags, sub, rest, home, output }) {
+  requireArgs(rest, 0, 0, 'teams server start|token');
+  if (sub === 'token') {
+    // A fresh owner credential for a hosted server's first start (its bootstrap secret). Printed to
+    // stdout only, for a pipe into the platform's secret store and then `teams login --token-stdin`.
+    process.stdout.write(makeToken(productionIds.next('credential')) + '\n');
+    return;
+  }
+  if (sub !== 'start') usage('teams server start|token');
+  // The Node host's store is node:sqlite (Node 22.5+); only this verb loads it, so every client
+  // verb runs on the Node 20 the package declares.
+  const { createTeamsServer } = await import('../server/index.mjs');
+  const server = createTeamsServer({ dataDir: flags.data_dir ?? resolve(home, 'teams', 'server'), listen: hostPort(flags.listen ?? '127.0.0.1:7331'), publicOrigin: flags.public_origin ?? null, identityIssuer: flags.volter_issuer ?? null, delegatedIssuer: flags.delegated_issuer ?? null, ...(flags.init_team ? { initTeam: flags.init_team } : {}) });
+  output(await server.start());
+  await new Promise(resolveStop => { const stop = async () => { await server.close(); resolveStop(); }; process.once('SIGINT', stop); process.once('SIGTERM', stop); });
+}
+
+/** The Teams server a login reaches when none is named: Volter's. */
+const DEFAULT_TEAMS_ORIGIN = 'https://supercode-teams.aaron-0ed.workers.dev';
+
+async function loginCommand({ flags, origin, rest, home, output }) {
+  requireArgs(rest, 0, 0, 'teams login [ORIGIN] [--team NAME_OR_ID] [--as NAME]');
+  if (flags.token_stdin && flags.invite_stdin) usage('choose only one of --token-stdin or --invite-stdin');
+  origin ??= process.env.SUPERCODE_TEAMS_ORIGIN ?? DEFAULT_TEAMS_ORIGIN;
+  const local = ['localhost', '127.0.0.1', '::1', '[::1]'].includes(new URL(origin).hostname);
+  if (!flags.team && (flags.token_stdin || (local && !flags.volter))) usage('--team names the team to sign in to with a token');
+  // Signing in with Volter (protocol P02), the default for a remote server: the member linked to that identity, a
+  // member of the organization the server links to a team, or with --invite-stdin the invited member. Without --team
+  // the person chooses among the teams they may use (volter-login.mjs), each a context named after it unless --as
+  // names the one.
+  if (flags.volter || (!local && !flags.token_stdin && !flags.invite_stdin)) {
+    if (flags.token_stdin) usage('--volter signs in instead of --token-stdin');
+    const invite = flags.invite_stdin ? inviteCode(readFileSync(0, 'utf8').trim()) : null;
+    const signIn = { ...(flags.volter_issuer ? { issuer: flags.volter_issuer } : {}), audience: new URL(origin).origin };
+    if (invite || flags.team) {
+      const identityToken = await volterDeviceSignIn(signIn);
+      return signedIn(flags, output, await loginContext({ supercodeHome: home, name: flags.as ?? null, origin, teamId: flags.team ?? null, token: null, invite, identityToken, as: flags.as ?? null, fetch: globalThis.fetch }));
+    }
+    const signedInTo = await volterDeviceSignIn({ ...signIn, finish: ({ token, ask }) => signInToTeams({ supercodeHome: home, origin, identityToken: token, ask, as: flags.as ?? null }) });
+    if (flags.json) return output(signedInTo.saved.length === 1 && !signedInTo.failed.length ? signedInTo.saved[0] : signedInTo);
+    process.stdout.write(loginSummary(signedInTo, origin));
+    return;
+  }
+  let token = null, invite = null;
+  if (flags.token_stdin || flags.invite_stdin) { const secret = readFileSync(0, 'utf8').trim(); if (!secret) usage('stdin credential is empty'); token = flags.token_stdin ? secret : null; invite = flags.invite_stdin ? inviteCode(secret) : null; }
+  else { const url = new URL(origin); if (!['localhost', '127.0.0.1', '::1', '[::1]'].includes(url.hostname)) usage('remote login requires --token-stdin or --invite-stdin'); try { token = JSON.parse(readFileSync(resolve(home, 'teams', 'server', 'bootstrap-credential.json'), 'utf8')).token; } catch { usage('local bootstrap credential was not found; use --token-stdin or --invite-stdin'); } }
+  return signedIn(flags, output, await loginContext({ supercodeHome: home, name: flags.as ?? null, origin, teamId: flags.team ?? null, token, invite, as: flags.as ?? null, fetch: globalThis.fetch }));
+}
+
+/** What a login says: the context as JSON, or to a person, the team they are in and the next step. */
+function signedIn(flags, output, saved) {
+  if (flags.json) return output(saved);
+  process.stdout.write(`Signed in to team ${saved.team_name ?? saved.team_id} (${new URL(saved.origin).host}). Next, from the folder you work in: supercode teams connect\n`);
+}
+
+/** `identity link`: the signed-in member links their Volter identity, so `teams login --volter` finds them. */
+async function identityCommand(sub, { flags, rest, output, client, context }) {
+  only(flags, ['json', 'help', 'context', 'volter_issuer']); requireArgs(rest, 0, 0, 'identity link');
+  if (sub !== 'link') usage('identity link');
+  const accessToken = await volterDeviceSignIn({ ...(flags.volter_issuer ? { issuer: flags.volter_issuer } : {}), audience: new URL(context.origin).origin });
+  return output(await client.request('POST', '/api/v1/me/identities', { body: { access_token: accessToken } }));
+}
+
+async function sessionsCommand(sub, command) {
+  const { flags, rest, output, team, context, explicitContext } = command;
+  if (sub === 'list' || sub === 'ls') {
+    only(flags, ['json', 'help', 'context', 'live', 'saved', 'watch', 'paginate', 'after', 'user', 'repo', 'harness', 'machine', 'source', 'cursor', 'limit', 'include_children', 'since', 'until', 'cwd']);
+    requireArgs(rest, 0, 0, 'sessions list'); if (flags.live || flags.saved) unsupported('remote contexts do not expose local --live/--saved backends');
+    const query = await listQuery(flags, command); if (flags.watch && flags.paginate) usage('--watch and --paginate are incompatible');
+    if (flags.watch) return stream(team.sessions.watch(query, { after: flags.after }), flags.json);
+    if (!flags.paginate) return output(await team.sessions.list(query));
+    const items = []; let page; do { page = await team.sessions.list({ ...query, cursor: page?.next_cursor }); items.push(...page.items); } while (page.next_cursor);
+    return output({ ...page, items, next_cursor: null });
+  }
+  if (sub === 'search') { only(flags, ['json', 'help', 'context', 'user', 'repo', 'harness', 'machine', 'source', 'cursor', 'limit', 'include_children', 'since', 'until', 'cwd']); requireArgs(rest, 1, Infinity, 'sessions search QUERY'); return output(await team.sessions.search({ ...await listQuery(flags, command), query: rest.join(' ') })); }
+  if (sub === 'access') {
+    const [action, reference, ...overflow] = rest;
+    if (!action || !reference || overflow.length) usage('sessions access list|grant|revoke REF');
+    const id = sessionReference(reference, context.origin, context.team_id, Boolean(explicitContext));
+    return sessionAccess(action, flags, team.sessions.get(id), output);
+  }
+  const reference = rest[0]; if (!reference) usage(`sessions ${sub} requires REF`);
+  const id = sessionReference(reference, context.origin, context.team_id, Boolean(explicitContext)); const session = team.sessions.get(id);
+  if (sub === 'show') { only(flags, ['json', 'help', 'context', 'tail', 'before', 'revision']); requireArgs(rest, 1, 1, 'sessions show REF'); if (flags.before && flags.revision) usage('--before and --revision are mutually exclusive'); return output(await session.read({ tail: positiveInteger(flags.tail, 100, 'tail'), ...optional(flags, ['before', 'revision']) })); }
+  if (sub === 'follow') { only(flags, ['json', 'help', 'context', 'tail', 'after']); requireArgs(rest, 1, 1, 'sessions follow REF'); return stream(session.follow({ tail: positiveInteger(flags.tail, 100, 'tail'), ...optional(flags, ['after']) }), flags.json); }
+  if (sub === 'attach') return attachSession(session, command);
+  if (sub === 'export') return exportSession(session, command);
+  if (sub === 'continue') return continueSession(session, command);
+  if (sub === 'url') { only(flags, ['json', 'help', 'context']); requireArgs(rest, 1, 1, 'sessions url REF'); const descriptor = await session.descriptor(); return output({ version: 1, context: scope(context), data: { url: `${context.origin}/teams/${context.team_id}/sessions/${descriptor.data.id}` } }); }
+  if (sub === 'rename') { only(flags, ['json', 'help', 'context']); requireArgs(rest, 2, 2, 'sessions rename REF TITLE'); const descriptor = await session.descriptor(); return output(await command.client.request('PATCH', session.path, { body: { title: rest[1] }, ifMatch: descriptor.data.revision })); }
+  if (sub === 'delete') { only(flags, ['json', 'help', 'context']); requireArgs(rest, 1, 1, 'sessions delete REF'); const descriptor = await session.descriptor(); await command.client.request('DELETE', session.path, { ifMatch: descriptor.data.revision }); return output({ version: 1, context: scope(context), data: null }); }
+  unsupported(`sessions ${sub} is reserved for a later arc`);
+}
+
+async function attachSession(session, { flags, rest, output, team }) {
+  only(flags, ['json', 'help', 'context', 'binding', 'take_control']);
+  requireArgs(rest, 1, 1, 'sessions attach REF [--binding ID] [--take-control]');
+  const descriptor = (await session.descriptor()).data;
+  const running = descriptor.bindings.filter(binding => binding.state === 'running');
+  let binding;
+  if (flags.binding) binding = running.find(candidate => candidate.id === flags.binding);
+  else if (running.length === 1) [binding] = running;
+  else if (running.length > 1) usage('--binding is required when more than one live binding is eligible');
+  if (!binding) unsupported(running.length ? 'the selected binding is not live' : 'this session has no live native binding');
+  const attached = await session.attach({ binding_id: binding.id, mode: flags.take_control ? 'control' : 'observe' });
+  output(attached);
+  try {
+    for await (const frame of team.attachments.stream(attached.data)) process.stdout.write(flags.json ? `${JSON.stringify(frame)}\n` : humanOutput(frame));
+  } finally { await team.attachments.detach(attached.data.id).catch(() => {}); }
+}
+
+async function exportSession(session, { flags, rest, output, client, context }) {
+  only(flags, ['json', 'help', 'context', 'format', 'fidelity', 'out', 'force', 'timeout']);
+  requireArgs(rest, 1, 1, 'sessions export REF --format FORMAT --out PATH');
+  if (!flags.format || !flags.out) usage('--format and --out are required');
+  const native = !['text', 'html'].includes(flags.format), fidelity = flags.fidelity ?? (native ? 'byte_lossless' : undefined);
+  if (native && !['claude-code', 'codex', 'gemini', 'goose', 'opencode', 'pi', 'grok'].includes(flags.format)) usage('--format must be text, html, or a supported translated harness');
+  if (fidelity && !['byte_lossless', 'value_lossless', 'semantic'].includes(fidelity)) usage('--fidelity must be byte_lossless, value_lossless, or semantic');
+  const destination = native ? reserveArtifactDirectory(flags.out, { force: flags.force }) : reserveProtected(flags.out, { force: flags.force });
+  try {
+    const descriptor = await session.descriptor();
+    const started = await session.export({ format: flags.format, ...(fidelity ? { fidelity } : {}), revision: descriptor.data.revision });
+    const operation = await waitForOperation(client, context, started.data, flags.timeout ? duration(flags.timeout) : undefined);
+    const result = operation.result;
+    if (operation.state !== 'succeeded' || result?.kind !== 'export' || !Array.isArray(result.files)) throw new Error('export operation returned no verified artifact result');
+    if (result.source_session_id !== descriptor.data.id || result.source_revision !== descriptor.data.revision || result.format !== flags.format) throw new Error('export operation result does not match the requested source revision and format');
+    if (fidelity && !fidelitySatisfies(result.fidelity, fidelity)) throw new Error(`export operation returned ${result.fidelity ?? 'unknown'} fidelity below requested ${fidelity}`);
+    const primaries = result.files.filter(file => file.role === 'primary'); if (primaries.length !== 1) throw new Error('export result must contain exactly one primary file');
+    if (!native && result.files.length !== 1) throw new Error('text and HTML exports must contain exactly one file');
+    for (const file of result.files) {
+      const bytes = await downloadArtifact(client, context, result.source_session_id, file);
+      if (native) destination.write(file.relative_name, bytes); else destination.writeBytes(bytes);
+    }
+    if (native) destination.publish();
+    return output({ version: 1, context: scope(context), data: { ...operation, written_to: native ? resolve(flags.out, primaries[0].relative_name) : resolve(flags.out), fidelity: result.fidelity } });
+  } catch (error) { destination.abort(); throw error; }
+}
+
+async function continueSession(session, { flags, rest, output, client, context, team, home, env, dependencies }) {
+  only(flags, ['json', 'help', 'context', 'plan', 'on', 'harness', 'cwd', 'root', 'fidelity', 'dry_run', 'timeout', 'workspace_from']);
+  requireArgs(rest, 1, 1, 'sessions continue REF (--plan ID | --on local|MACHINE --harness ID --cwd PATH [--workspace-from MACHINE:PATH])');
+  if (flags.plan && ['on', 'harness', 'cwd', 'root', 'fidelity'].some(key => flags[key] !== undefined)) usage('--plan cannot be combined with --on, --harness, --cwd, --root, or --fidelity because the plan already pins them');
+  if (flags.plan) {
+    const descriptor = await session.descriptor();
+    const continuation = (await client.request('GET', teamPath(context, `/continuations/${flags.plan}`))).data;
+    if (continuation.source_id !== descriptor.data.id) notFound('continuation plan does not belong to the requested session');
+    if (flags.dry_run || continuation.state === 'refused') return output({ version: 1, context: scope(context), data: continuation });
+    if (continuation.operation_id !== null) {
+      if (continuation.destination.machine_id !== 'local') {
+        if (!continuation.operation_id) throw Object.assign(new Error('consumed continuation has no operation receipt'), { code: 'conflict', exitCode: 6 });
+        return output({ version: 1, context: scope(context), data: await waitForOperation(client, context, { id: continuation.operation_id, state: 'pending' }, flags.timeout ? duration(flags.timeout) : undefined) });
+      }
+      const statePath = join(home, 'teams', 'workspaces', 'continuations', context.server_id, context.team_id, continuation.id, 'state.json');
+      if (!existsSync(statePath)) {
+        const completion = { operation_id: continuation.operation_id, outcome: 'unknown', native_session_id: null, error: null };
+        const reported = await client.request('POST', teamPath(context, `/continuations/${continuation.id}/complete-local`), { body: completion });
+        await waitForOperation(client, context, reported.data, flags.timeout ? duration(flags.timeout) : undefined);
+        throw Object.assign(new Error('local continuation was consumed without a durable local receipt; native execution will not be repeated'), { code: 'conflict', exitCode: 6 });
+      }
+    }
+    if (continuation.state !== 'ready' && continuation.operation_id === null) throw Object.assign(new Error(`continuation is ${continuation.state}`), { code: 'conflict', exitCode: 6 });
+    if (continuation.destination.machine_id === 'local') return launchLocalContinuation({ continuation, fidelity: continuation.fidelity, client, context, home, output, timeout: flags.timeout ? duration(flags.timeout) : undefined, env, json: flags.json, eventStream: dependencies.stdout ?? process.stdout, nativeContinuationFactory: dependencies.nativeContinuationFactory, coreFactory: dependencies.coreFactory });
+    const launched = await client.request('POST', teamPath(context, `/continuations/${continuation.id}/launch`));
+    return output({ version: 1, context: scope(context), data: await waitForOperation(client, context, launched.data, flags.timeout ? duration(flags.timeout) : undefined) });
+  }
+  for (const key of ['on', 'harness', 'cwd']) if (!flags[key]) usage(`--${key.replaceAll('_', '-')} is required`);
+  if (!CONTINUATION_HARNESSES.has(flags.harness)) usage(`--harness must be one of ${[...CONTINUATION_HARNESSES].join(', ')}`);
+  const fidelity = flags.fidelity ?? CONTINUATION_FIDELITY; if (fidelity !== CONTINUATION_FIDELITY) usage(`continuation fidelity is ${CONTINUATION_FIDELITY}: a continued session is a new native session`);
+  if (flags.workspace_from) {
+    // The project goes first: moved from MACHINE:PATH into --cwd on the destination, published
+    // there only whole, and only then is the session continued into it.
+    if (flags.plan || flags.dry_run) usage('--workspace-from moves a project; it runs with --on, not --plan or --dry-run');
+    const spec = String(flags.workspace_from), at = spec.indexOf(':');
+    if (at <= 0 || !spec.slice(at + 1).startsWith('/')) usage('--workspace-from is MACHINE:/absolute/path');
+    const moved = await moveWorkspace({ from: spec.slice(0, at), to: flags.on === 'local' ? null : String(flags.on), path: spec.slice(at + 1), toPath: flags.on === 'local' ? resolve(flags.cwd) : String(flags.cwd), context: flags.context ?? null, home: teamsHome(env) });
+    process.stderr.write(`moved ${moved.bytes} bytes (sha256 ${moved.sha256}) from ${moved.from} to ${moved.to}:${moved.path}\n`);
+  }
+  let machine_id, root_id, cwd;
+  if (flags.on === 'local') { if (flags.root) usage('--root is only valid for a remote machine'); machine_id = 'local'; root_id = null; cwd = realpathSync(resolve(flags.cwd)); }
+  else {
+    if (!flags.root) usage('--root is required for a remote machine');
+    const machines = await team.machines.list(), matches = machines.items.filter(machine => machine.id === flags.on || machine.name === flags.on);
+    if (matches.length !== 1) usage(matches.length ? `machine name ${flags.on} is ambiguous` : `machine ${flags.on} is not accessible`);
+    machine_id = matches[0].id; root_id = flags.root; cwd = flags.cwd;
+  }
+  const descriptor = await session.descriptor();
+  let continuation = (await session.prepare({ source_revision: descriptor.data.revision, destination: { machine_id, root_id, cwd }, harness: flags.harness, fidelity })).data;
+  continuation = await waitForContinuation(client, context, continuation, flags.timeout ? duration(flags.timeout) : undefined);
+  if (flags.dry_run || continuation.state === 'refused') return output({ version: 1, context: scope(context), data: continuation });
+  if (continuation.state !== 'ready') throw Object.assign(new Error(`continuation is ${continuation.state}`), { code: 'conflict', exitCode: 6 });
+  if (machine_id === 'local') return launchLocalContinuation({ continuation, fidelity, client, context, home, output, timeout: flags.timeout ? duration(flags.timeout) : undefined, env, json: flags.json, eventStream: dependencies.stdout ?? process.stdout, nativeContinuationFactory: dependencies.nativeContinuationFactory, coreFactory: dependencies.coreFactory });
+  const launched = await client.request('POST', teamPath(context, `/continuations/${continuation.id}/launch`));
+  const operation = await waitForOperation(client, context, launched.data, flags.timeout ? duration(flags.timeout) : undefined);
+  return output({ version: 1, context: scope(context), data: operation });
+}
+
+async function launchLocalContinuation({ continuation, fidelity, client, context, home, output, timeout, env, json, eventStream, nativeContinuationFactory, coreFactory }) {
+  const localRoot = join(home, 'teams', 'workspaces', 'continuations', context.server_id, context.team_id, continuation.id), statePath = join(localRoot, 'state.json'), bundlePath = join(localRoot, 'bundle');
+  if (existsSync(statePath)) {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    if (state.version !== 1 || state.continuation_id !== continuation.id || !state.operation_id) throw Object.assign(new Error('local continuation durable state is invalid'), { code: 'conflict', exitCode: 6 });
+    const completion = state.phase === 'completed' && state.completion
+      ? state.completion
+      : { operation_id: state.operation_id, outcome: 'unknown', native_session_id: null, error: null };
+    if (state.phase !== 'completed') writeProtected(statePath, { ...state, phase: 'completed', completion }, { force: true });
+    const reported = await client.request('POST', teamPath(context, `/continuations/${continuation.id}/complete-local`), { body: completion });
+    const operation = await waitForOperation(client, context, reported.data, timeout);
+    if (completion.outcome !== 'running') throw Object.assign(new Error(completion.outcome === 'failed' ? completion.error.message : `native continuation outcome is unknown and will not be retried automatically${state.observed ? `: ${state.observed}` : ''}`), { code: completion.error?.code ?? 'conflict', exitCode: 6 });
+    return output({ version: 1, context: scope(context), data: operation });
+  }
+  let factory = nativeContinuationFactory;
+  if (!factory) {
+    try { ({ createNativeContinuationAdapter: factory } = await import('@volter/supercode-teams/connector/native-continuation')); } catch (error) { if (error.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED' && error.code !== 'ERR_MODULE_NOT_FOUND') throw error; }
+  }
+  if (!factory) unsupported('local continuation requires the reviewed connector native installer adapter');
+  const binary = env.SUPERCODE_TEAMS_TEST_BIN ?? env.SUPERCODE_BIN ?? 'supercode';
+  const core = coreFactory ? coreFactory({ command: binary, args: ['harness', 'serve'] }) : new SupercodeHarnessClient({ command: binary, args: ['harness', 'serve'] });
+  const adapter = factory({ core });
+  if (!adapter.supports({ harness: continuation.harness, fidelity })) { core.close(); unsupported(`local ${continuation.harness} continuation does not support the prepared fidelity`); }
+  const launched = await client.request('POST', teamPath(context, `/continuations/${continuation.id}/launch`)), ticket = launched.data.result;
+  if (launched.data.state !== 'running' || ticket?.kind !== 'local_launch' || ticket.continuation_id !== continuation.id || ticket.operation_id !== launched.data.id) { core.close(); throw new Error('local launch returned an invalid ticket'); }
+  if (Date.now() >= ticket.expires_at || ticket.destination.machine_id !== 'local' || ticket.destination.root_id !== null || ticket.destination.cwd !== continuation.destination.cwd || ticket.harness !== continuation.harness) { core.close(); throw Object.assign(new Error('local launch ticket target changed or expired'), { code: 'conflict', exitCode: 6 }); }
+  if (ticket.fidelity !== fidelity || ticket.artifact?.kind !== 'export' || ticket.artifact.format !== continuation.harness || !fidelitySatisfies(ticket.artifact.fidelity, fidelity) || !Array.isArray(ticket.artifact.files) || ticket.artifact.files.filter(file => file.role === 'primary').length !== 1) { core.close(); throw Object.assign(new Error('local launch ticket contains an invalid export bundle'), { code: 'conflict', exitCode: 6 }); }
+  const directory = reserveArtifactDirectory(bundlePath);
+  try {
+    for (const file of ticket.artifact.files) directory.write(file.relative_name, await downloadArtifact(client, context, ticket.artifact.source_session_id, file));
+    directory.publish();
+  } catch (error) { directory.abort(); core.close(); throw error; }
+  const current = (await client.request('GET', teamPath(context, `/continuations/${continuation.id}`))).data;
+  if (Date.now() >= current.expires_at || current.source_revision !== ticket.artifact.source_revision || current.source_id !== continuation.source_id || current.destination?.machine_id !== 'local' || current.destination?.cwd !== ticket.destination.cwd) { core.close(); throw Object.assign(new Error('local continuation authorization changed after artifact verification'), { code: 'conflict', exitCode: 6 }); }
+  writeProtected(statePath, { version: 1, phase: 'started', continuation_id: continuation.id, operation_id: ticket.operation_id, ticket, bundle: bundlePath });
+  let completion, runtime, observed = null;
+  try {
+    const native = await adapter.launch({ ticket, directory: bundlePath, fidelity });
+    if (!native?.native_session_id) throw Object.assign(new Error('native adapter returned no session identity'), { nativeOutcome: 'failed' });
+    runtime = native.runtime;
+    completion = { operation_id: ticket.operation_id, outcome: 'running', native_session_id: native.native_session_id, error: null };
+  } catch (error) {
+    completion = error.nativeOutcome === 'failed'
+      ? { operation_id: ticket.operation_id, outcome: 'failed', native_session_id: null, error: { code: error.code ?? 'unsupported', message: error.message, retryable: false } }
+      : { operation_id: ticket.operation_id, outcome: 'unknown', native_session_id: null, error: null };
+    // An unknown outcome is never retried, so its cause is the one thing the person can act on.
+    if (completion.outcome === 'unknown') observed = error.message;
+  }
+  writeProtected(statePath, { version: 1, phase: 'completed', continuation_id: continuation.id, operation_id: ticket.operation_id, ticket, bundle: bundlePath, completion, ...(observed ? { observed } : {}) }, { force: true });
+  let operation;
+  try {
+    const reported = await client.request('POST', teamPath(context, `/continuations/${continuation.id}/complete-local`), { body: completion });
+    operation = await waitForOperation(client, context, reported.data, timeout);
+    if (completion.outcome !== 'running') throw Object.assign(new Error(completion.outcome === 'failed' ? completion.error.message : `native continuation outcome is unknown and will not be retried automatically${observed ? `: ${observed}` : ''}`), { code: completion.error?.code ?? 'conflict', exitCode: 6 });
+  } catch (error) {
+    if (runtime) try { await runtime.close(); } catch {}
+    await core.close();
+    throw error;
+  }
+  output({ version: 1, context: scope(context), data: operation });
+  await ownForegroundRuntime(runtime, core, { json, eventStream, env });
+}
+
+async function ownForegroundRuntime(runtime, core, { json, eventStream, env }) {
+  try {
+    if (json) {
+      for await (const event of runtime.events()) eventStream.write(`${JSON.stringify(event)}\n`);
+      return;
+    }
+    const instructions = await runtime.terminalInstructions();
+    const launch = instructions?.launch;
+    if (!launch || typeof launch.program !== 'string' || !launch.program || !Array.isArray(launch.arguments) || launch.arguments.some(value => typeof value !== 'string') || typeof launch.cwd !== 'string' || !launch.cwd) unsupported('native runtime has no trusted terminal attachment frontend');
+    await new Promise((resolveExit, reject) => {
+      const child = spawn(launch.program, launch.arguments, { cwd: launch.cwd, env: { ...env, ...(launch.env ?? {}) }, stdio: 'inherit', shell: false });
+      child.once('error', reject);
+      child.once('close', code => code === 0 ? resolveExit() : reject(Object.assign(new Error(`native attachment frontend exited ${code}`), { code: 'conflict' })));
+    });
+  } finally {
+    try { await runtime.close(); } finally { await core.close(); }
+  }
+}
+
+async function sessionAccess(action, flags, session, output) {
+  const common = ['json', 'help', 'context'];
+  if (action === 'list') { only(flags, common); return output(await session.access()); }
+  if (action === 'grant') {
+    only(flags, [...common, 'to', 'role', 'ttl']);
+    if (!flags.to) usage('--to is required');
+    const target = /^(user|group):(.+)$/.exec(flags.to); if (!target) usage('--to must be user:ID or group:ID');
+    const access = await session.access();
+    return output(await session.grant({ subject: { kind: target[1] === 'user' ? 'principal' : 'group', id: target[2] }, role: flags.role ?? 'reader', expires_at: flags.ttl ? Date.now() + duration(flags.ttl) : null }, { ifMatch: access.data.revision }));
+  }
+  if (action === 'revoke') { only(flags, [...common, 'grant']); if (!flags.grant) usage('--grant is required'); const access = await session.access(); return output(await session.revoke(flags.grant, { ifMatch: access.data.revision })); }
+  usage('sessions access list|grant|revoke REF');
+}
+
+async function membersCommand(sub, { flags, rest, output, client, context }) {
+  const base = teamPath(context, '/members');
+  if (sub === 'invite') {
+    requireArgs(rest, 1, 1, 'teams members invite DISPLAY_NAME --out PATH'); if (!flags.out) usage('--out is required to deliver the invitation secret'); const destination = reserveProtected(flags.out, { force: flags.force });
+    let response; try { response = await client.request('POST', teamPath(context, '/invitations'), { body: { display_name: rest[0], role: flags.role ?? 'member', expires_in_ms: duration(flags.ttl, 86_400_000) } }); destination.write(response.data); } catch (error) { destination.abort(); throw error; }
+    const { enrollment_code: _secret, ...safe } = response.data;
+    return output({ ...response, data: { ...safe, written_to: resolve(flags.out) } });
+  }
+  if (sub === 'list') return output(await client.request('GET', base));
+  if (sub === 'remove' || sub === 'role') {
+    requireArgs(rest, 1, 1, `teams members ${sub} ID${sub === 'role' ? ' --role ROLE' : ''}`); if (sub === 'role' && !flags.role) usage('--role is required');
+    const membership = (await client.request('GET', base)).items.find(item => item.principal.id === rest[0]); if (!membership) notFound('member is not accessible');
+    if (sub === 'remove') { await client.request('DELETE', `${base}/${rest[0]}`, { ifMatch: membership.revision }); return output({ removed: rest[0] }); }
+    return output(await client.request('PATCH', `${base}/${rest[0]}`, { body: { role: flags.role }, ifMatch: membership.revision }));
+  }
+  usage('teams members invite|list|remove|role');
+}
+
+async function groupsCommand(sub, { rest, output, client, context }) {
+  const base = teamPath(context, '/groups');
+  if (sub === 'list') return output(await client.request('GET', base));
+  if (sub === 'create') { requireArgs(rest, 1, 1, 'teams groups create NAME'); return output(await client.request('POST', base, { body: { name: rest[0] } })); }
+  if (sub === 'remove' || sub === 'add-member' || sub === 'remove-member') {
+    requireArgs(rest, sub === 'remove' ? 1 : 2, sub === 'remove' ? 1 : 2, `teams groups ${sub} GROUP_ID${sub === 'remove' ? '' : ' PRINCIPAL_ID'}`);
+    const group = (await client.request('GET', base)).items.find(item => item.id === rest[0]); if (!group) notFound('group is not accessible');
+    if (sub === 'remove') { await client.request('DELETE', `${base}/${rest[0]}`, { ifMatch: group.revision }); return output({ removed: rest[0] }); }
+    const path = `${base}/${rest[0]}/members/${rest[1]}`, method = sub === 'add-member' ? 'PUT' : 'DELETE'; await client.request(method, path, { ...(method === 'PUT' ? { body: {} } : {}), ifMatch: group.revision }); return output({ group_id: rest[0], principal_id: rest[1], member: method === 'PUT' });
+  }
+  usage('teams groups list|create|remove|add-member|remove-member');
+}
+
+async function sourcesCommand(sub, command) {
+  const { flags, rest, output, client, context, team } = command;
+  if (sub === 'list') return output(await team.sources.list());
+  if (sub === 'create') { requireArgs(rest, 0, 0, 'teams sources create --type otlp --name NAME'); if (flags.type !== 'otlp' || !flags.name) usage('--type otlp and --name are required'); return output(await team.sources.create({ name: flags.name, kind: 'otlp', custodian_id: context.principal_id, visibility: flags.visibility ?? 'restricted' })); }
+  if (sub === 'credentials') {
+    requireArgs(rest, 2, 2, 'teams sources credentials create SOURCE --out PATH'); if (rest[0] !== 'create') usage('teams sources credentials create SOURCE --out PATH'); const destination = reserveProtected(flags.out, { force: flags.force });
+    let response; try { response = await client.request('POST', teamPath(context, `/sources/${rest[1]}/credentials`), { body: { rotate: Boolean(flags.rotate) } }); destination.write(response.data); } catch (error) { destination.abort(); throw error; }
+    return output({ ...response, data: { kind: response.data.kind, expires_at: response.data.expires_at, written_to: resolve(flags.out) } });
+  }
+  const source = rest[0]; if (!source) usage(`teams sources ${sub} requires SOURCE`);
+  if (sub === 'status') return output(await team.sources.get(source));
+  if (sub === 'pause' || sub === 'revoke') { const current = await team.sources.get(source); return output(await team.sources.update(source, { state: sub === 'pause' ? 'paused' : 'revoked' }, { ifMatch: current.data.revision })); }
+  if (sub === 'config') { requireArgs(rest, 1, 1, 'teams sources config SOURCE --format otel-collector'); if (flags.format !== 'otel-collector') usage('--format otel-collector is required'); const response = await client.request('GET', teamPath(context, `/sources/${source}/config?format=otel-collector`)); if (flags.json) return output(response); process.stdout.write(response.data.content.endsWith('\n') ? response.data.content : `${response.data.content}\n`); return; }
+  usage('teams sources create|list|status|pause|revoke|credentials|config');
+}
+
+async function machinesCommand(sub, { flags, rest, output, client, context, team }) {
+  if (sub === 'list') return output(await team.machines.list());
+  if (sub === 'roots') { requireArgs(rest, 1, 1, 'teams machines roots MACHINE'); return output(await client.request('GET', teamPath(context, `/machines/${rest[0]}/roots`))); }
+  if (sub === 'authorize-continuation') {
+    requireArgs(rest, 1, 1, 'teams machines authorize-continuation CONTINUATION --ttl DURATION');
+    if (!flags.ttl) usage('--ttl is required');
+    const ttl = duration(flags.ttl); if (ttl > 15 * 60_000) usage('--ttl cannot exceed the continuation plan lifetime of 15m');
+    // The destination custodian need not be the plan requester. GET is deliberately
+    // requester-only; the authorization route validates the requested expiry itself.
+    const expires_at = Date.now() + ttl;
+    return output(await client.request('POST', teamPath(context, `/continuations/${rest[0]}/authorize-destination`), { body: { expires_at } }));
+  }
+  if (sub === 'access') {
+    const [action, reference] = rest; if (!action || !reference) usage('teams machines access grant|list|revoke MACHINE');
+    const machine = reference.startsWith('mach_') ? reference : await resolveName((await team.machines.list()).items, reference, item => item.name, item => item.id, 'machine');
+    const machineBase = teamPath(context, `/machines/${machine}/access`), liveBase = teamPath(context, `/machines/${machine}/grants`);
+    if (action === 'list') {
+      const [machineGrants, liveGrants] = await Promise.all([client.request('GET', machineBase), client.request('GET', liveBase)]);
+      return output({ version: 1, context: scope(context), data: { machine_grants: machineGrants.items, live_grants: liveGrants.items } });
+    }
+    if (action === 'revoke') {
+      if (!flags.grant) usage('--grant is required');
+      // A grant id names one row in exactly one of the two tables.
+      for (const base of [machineBase, liveBase]) {
+        let grant;
+        try { grant = await client.request('GET', `${base}/${flags.grant}`); } catch (error) { if (error.code === 'not_found') continue; throw error; }
+        await client.request('DELETE', `${base}/${flags.grant}`, { ifMatch: grant.data.revision });
+        return output({ revoked: flags.grant });
+      }
+      notFound('grant is not accessible');
+    }
+    if (action === 'grant') {
+      for (const key of ['to', 'caps', 'ttl']) if (!flags[key]) usage(`--${key} is required`);
+      const subject = /^(user|service|group):(.+)$/.exec(flags.to)?.[2]; if (!subject) usage('--to must be user:ID, service:ID or group:ID');
+      const ttl = duration(flags.ttl);
+      if (flags.session || flags.binding) {
+        // One session binding's native live actions (§5).
+        if (!flags.session || !flags.binding) usage('--session and --binding go together');
+        if (ttl > 60 * 60_000) usage('--ttl cannot exceed 1h for a session live grant');
+        const allowed = new Set(['attach_observe', 'interact', 'approve', 'interrupt', 'terminate']);
+        const actions = flags.caps.split(',').map(cap => cap === 'observe' ? 'attach_observe' : cap);
+        if (!actions.length || actions.some(action => !allowed.has(action))) usage('--caps contains an unsupported live action');
+        return output(await client.request('POST', liveBase, { body: { machine_id: machine, subject_id: subject, session_id: flags.session, binding_id: flags.binding, actions, expires_at: Date.now() + ttl } }));
+      }
+      // The machine's doors (§11): operate, or view|observe|interact|control|files|ports on --on targets.
+      const caps = flags.caps.split(',').map(cap => cap.trim()).filter(Boolean);
+      // `*` carries only operate and view; any other capability names the targets it reaches.
+      if (!flags.on && !caps.every(cap => cap === 'operate' || cap === 'view')) usage('--on is required for ' + caps.filter(cap => cap !== 'operate' && cap !== 'view').join(',') + ' (e.g. --on pane:<ctx>, pane:*, root:/path)');
+      const targets = flags.on ? flags.on.split(',').map(target => target.trim()).filter(Boolean) : ['*'];
+      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');
+}
+
+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') {
+    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();
+    if (!enrollment?.machine?.id) unsupported('this context has no connector enrollment');
+    const path = realpathSync(resolve(flags.repo)), root = enrollment.roots?.find(item => item.path === path);
+    if (!root) unsupported('the connector has not registered that repository root; restart connect with --cwd PATH');
+    if (flags.harness && !root.harnesses.includes(flags.harness)) unsupported(`the native core does not report a ${flags.harness} discovery adapter`);
+    return output(await team.syncRules.create({ machine_id: enrollment.machine.id, source_id: enrollment.source.id, selector: { root_id: root.id, harnesses: flags.harness ? [flags.harness] : root.harnesses }, visibility: flags.visibility ?? 'restricted', backfill: backfill(flags.backfill ?? 'none') }));
+  }
+  const id = rest[0]; if (!id) usage(`teams sync ${sub} requires RULE_ID`); const base = teamPath(context, `/sync-rules/${id}`);
+  if (sub === 'show') return output(await client.request('GET', base));
+  if (sub === 'remove' || sub === 'pause' || sub === 'resume') {
+    const current = await client.request('GET', base);
+    if (sub === 'remove') { await client.request('DELETE', base, { ifMatch: current.data.revision }); return output({ removed: id }); }
+    if (sub === 'resume' && !flags.backfill) usage('--backfill is required');
+    return output(await client.request('PATCH', base, { body: sub === 'pause' ? { state: 'paused' } : { state: 'active', backfill: backfill(flags.backfill) }, ifMatch: current.data.revision }));
+  }
+  usage('teams sync add|list|show|pause|resume|remove');
+}
+
+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; } const saved = state.read(); const running = saved?.process?.socket ? await activeSocket(saved.process.socket) : false; return output({ version: 1, context: scope(context), data: { reachable, account, connector: saved ? { enrolled: true, running, machine: saved.machine, source: saved.source } : { enrolled: false, running: false }, sources: reachable ? (await team.sources.list()).items : [] } }); }
+  if (verb === 'connect') {
+    let saved = state.read();
+    if (!saved) { const enrollment_key = crypto.randomUUID(); saved = { version: 1, enrollment_key, phase: 'enrolling' }; state.write(saved); }
+    if (!saved.machine) {
+      const response = await team.machines.create({ name: flags.name ?? hostname(), enrollment_key: saved.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;
+      saved = state.update(current => ({ ...current, ...response.data, credential, phase: 'enrolled' }));
+    }
+    if (!saved.credential?.token) unsupported('saved enrollment has no reusable machine credential; disconnect and enroll again');
+    const binary = process.env.SUPERCODE_TEAMS_TEST_BIN ?? process.env.SUPERCODE_BIN ?? 'supercode';
+    const core = new SupercodeHarnessClient({ command: binary, args: ['harness', 'serve'] });
+    let support;
+    try { support = await core.supportReport(); } catch (error) { core.close(); throw error; }
+    const harnesses = [...new Set((support.harnesses ?? []).map(item => item.id).filter(id => typeof id === 'string'))];
+    if (!harnesses.length) { core.close(); unsupported('the native core reported no discoverable harness adapters'); }
+    const path = realpathSync(resolve(flags.cwd ?? '.'));
+    const root = { id: `root_${createHash('sha256').update(`${saved.machine.id}\0${path}`).digest('hex').slice(0, 32)}`, machine_id: saved.machine.id, name: basename(path), harnesses, path };
+    saved = state.update(current => ({ ...current, roots: [root] }));
+    // Run from a terminal, connect installs the service that keeps this machine connected (launchd or systemd) and
+    // returns; the service itself runs connect without a terminal, in the foreground. --foreground runs it here.
+    if (flags.install || (!flags.foreground && process.stdin.isTTY && process.stdout.isTTY)) {
+      const serviceBin = process.env.SUPERCODE_BIN;
+      if (!serviceBin) unsupported('--install requires invocation through the native supercode CLI');
+      const service = JSON.parse(execFileSync(serviceBin, ['__teams-connector-service', 'install', contextName, path, context.server_id, context.team_id], { encoding: 'utf8' }));
+      saved = state.update(current => ({ ...current, service }));
+      core.close();
+      if (!flags.json) {
+        process.stdout.write(`Connected ${saved.machine.name} to team ${context.team_name ?? context.team_id}; it stays connected (a ${service.kind ?? 'background'} service).\n`);
+        for (const line of service.message_tools ?? []) process.stdout.write(`  ${line}\n`);
+        return;
+      }
+      return output({ version: 1, context: scope(context), data: { machine: saved.machine, source: saved.source, service } });
+    }
+    let stopConnector;
+    let lifecycle;
+    try { lifecycle = await acquireLifecycle(state.directory, () => stopConnector?.()); } catch (error) { core.close(); throw error; }
+    saved = state.update(current => ({ ...current, process: { pid: process.pid, started_at: Date.now(), socket: lifecycle.socketPath, token: lifecycle.token } }));
+    // The machine daemon serves this machine's doors on its local socket and, through the link, to
+    // callers the server admits; its host key id rides the connector's heartbeat.
+    const daemonHome = teamsHome();
+    const hostKeyId = publicKeyId(loadOrCreateKeyPair(paths(daemonHome).machineKey).publicKeyPem);
+    const connector = new TeamsConnector({ server: context.origin, teamId: context.team_id, machineId: saved.machine.id, sourceId: saved.source.id, credential: saved.credential.token, stateDir: state.directory, core, hostKeyId });
+    const machine = new TeamsMachine({ home: daemonHome, supercode: binary, ...(flags.tmux_socket ? { tmuxSocket: String(flags.tmux_socket) } : {}), link: { server: context.origin, teamId: context.team_id, machineId: saved.machine.id, credential: saved.credential.token, incarnationId: connector.state.incarnation_id, configuration: () => connector.configuration() } });
+    const stopAll = async () => { await machine.stop().catch(() => {}); await connector.stop(); await core.close(); await lifecycle.close(); state.update(current => current ? ({ ...current, process: undefined }) : null); };
+    try { await connector.start({ roots: () => saved.roots }); await machine.start(); } catch (error) { await stopAll(); throw error; }
+    output({ version: 1, context: scope(context), data: { machine: saved.machine, source: saved.source, roots: saved.roots.map(({ path: _path, ...item }) => item), socket: machine.socketPath, foreground: true } });
+    await new Promise(resolveStop => { let stopped = false; stopConnector = async () => { if (stopped) return; stopped = true; await stopAll(); resolveStop(); }; process.once('SIGINT', stopConnector); process.once('SIGTERM', stopConnector); });
+    return;
+  }
+  const enrollment = state.read();
+  if (!enrollment?.machine?.id) return output({ version: 1, context: scope(context), data: { disconnected: false } });
+  if (enrollment.service) {
+    const serviceBin = process.env.SUPERCODE_BIN;
+    if (!serviceBin) unsupported('disconnecting an installed connector requires invocation through the native supercode CLI');
+    execFileSync(serviceBin, ['__teams-connector-service', 'uninstall', contextName, enrollment.roots?.[0]?.path ?? '.', context.server_id, context.team_id], { encoding: 'utf8' });
+  }
+  if (enrollment.process?.socket && enrollment.process?.token) await requestStop(enrollment.process.socket, enrollment.process.token);
+  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();
+  return output({ version: 1, context: scope(context), data: { disconnected: true, machine_id: enrollment.machine.id } });
+}
+
+/**
+ * PUBLISH: one pane or folder of a machine of this team, put into a workplace Room as a Surface (RH2's Surface
+ * door). The workplace decides who in the Room may see or drive it and signs them delegated tokens; this server
+ * admits those if it was started with that workplace as its delegated issuer (server/delegated.mjs). The machine is
+ * the one `teams connect` enrolled here, or `--machine NAME`. The workplace credential is a session token, from
+ * --token-stdin or WORKPLACE_TOKEN. `unpublish SURFACE` retires it.
+ */
+async function publishCommand(verb, sub, { flags, rest, output, context, team, home, env }) {
+  only(flags, ['json', 'help', 'context', 'room', 'workplace', 'organization', 'name', 'key', 'machine', 'token_stdin']);
+  if (!flags.room || !flags.workplace || !flags.organization) usage(`teams ${verb} needs --room ROOM --workplace ORIGIN --organization ORG`);
+  const workplace = new URL(flags.workplace).origin;
+  const token = flags.token_stdin ? readFileSync(0, 'utf8').trim() : env.WORKPLACE_TOKEN;
+  if (!token) usage('the workplace credential comes from --token-stdin or WORKPLACE_TOKEN');
+  const roomPath = `${workplace}/api/v3/rooms/${encodeURIComponent(flags.room)}/surfaces`;
+  let url, body;
+  if (verb === 'unpublish') {
+    requireArgs([sub, ...rest].filter(Boolean), 1, 1, 'teams unpublish SURFACE --room ROOM --workplace ORIGIN --organization ORG');
+    url = `${roomPath}/${encodeURIComponent(sub)}/retire`; body = {};
+  } else {
+    if (sub !== 'pane' && sub !== 'root') usage('teams publish pane CONTEXT_KEY|root PATH --room ROOM --workplace ORIGIN --organization ORG [--name NAME] [--key KEY] [--machine NAME]');
+    requireArgs(rest, 1, 1, `teams publish ${sub}`);
+    const machine = flags.machine
+      ? resolveName((await team.machines.list()).items ?? [], flags.machine, item => item.name, item => item.id, 'machine')
+      : new WorkspaceContexts(home).connector(context.server_id, context.team_id).read()?.machine?.id;
+    if (!machine) usage('this machine is not connected to the team: run teams connect, or name --machine');
+    // A folder on this machine is its real path; on another machine, the path as given there.
+    const target = sub === 'pane' ? `pane:${rest[0]}` : `root:${flags.machine ? rest[0] : realpathSync(resolve(rest[0]))}`;
+    if (sub === 'root' && !target.startsWith('root:/')) usage('a folder on another machine is named by its absolute path');
+    const label = sub === 'pane' ? rest[0] : basename(target.slice(5)) || 'root';
+    const key = flags.key ?? `${sub === 'pane' ? 'pane' : 'folder'}-${label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || createHash('sha256').update(target).digest('hex').slice(0, 8)}`;
+    url = roomPath;
+    body = { config: { machine, target, team: context.team_id, teamsUrl: new URL(context.origin).origin }, key, kind: sub === 'pane' ? 'pane' : 'folder', name: flags.name ?? label };
+  }
+  const response = await fetch(url, { body: JSON.stringify(body), headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', origin: workplace, 'x-rh2-organization': String(flags.organization) }, method: 'POST' });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) throw Object.assign(new Error(payload?.error?.message ?? `the workplace answered ${response.status}`), { code: response.status === 403 || response.status === 404 ? 'forbidden' : response.status === 401 ? 'authentication_required' : 'invalid_request' });
+  return output({ version: 1, context: scope(context), data: payload?.data ?? null });
+}
+
+async function listQuery(flags, { client, context, team }) {
+  const now = Date.now(), since = flags.since ? absoluteTime(flags.since, now) : undefined, until = flags.until ? absoluteTime(flags.until, now) : undefined;
+  if (since !== undefined && until !== undefined && since >= until) usage('--since must precede --until');
+  const query = { ...optional(flags, ['harness', 'cursor']), limit: positiveInteger(flags.limit, 50, 'limit'), include_children: Boolean(flags.include_children), ...(since !== undefined ? { since } : {}), ...(until !== undefined ? { until } : {}) };
+  if (flags.repo) query.repo = repositoryKey(flags.repo, flags.cwd);
+  if (flags.user) query.user = flags.user === 'me' || flags.user.startsWith('usr_') ? flags.user : await resolveName((await client.request('GET', teamPath(context, '/members'))).items, flags.user, item => item.principal?.display_name ?? item.display_name, item => item.principal?.id ?? item.principal_id ?? item.id, 'user');
+  if (flags.machine) query.machine = flags.machine.startsWith('mach_') ? flags.machine : await resolveName((await team.machines.list()).items, flags.machine, item => item.name, item => item.id, 'machine');
+  if (flags.source) query.source = flags.source.startsWith('src_') ? flags.source : await resolveName((await team.sources.list()).items, flags.source, item => item.name, item => item.id, 'source');
+  return query;
+}
+function absoluteTime(value, now) { if (/^\d{4}-\d\d-\d\dT/.test(value)) { const time = Date.parse(value); if (Number.isFinite(time)) return time; } return now - duration(value); }
+function resolveName(items, name, label, id, kind) { const matches = items.filter(item => label(item) === name); if (matches.length > 1) throw Object.assign(new Error(`ambiguous ${kind} name ${name}`), { code: 'ambiguous_reference', exitCode: 2 }); if (!matches.length) notFound(`${kind} ${name} is not accessible`); return id(matches[0]); }
+function repositoryKey(value, cwd) { if (value !== '.') return value; let remotes; try { remotes = execFileSync('git', ['config', '--get-all', 'remote.origin.url'], { cwd, encoding: 'utf8' }).trim().split('\n').filter(Boolean); } catch { usage('--repo . requires one origin remote'); } const keys = [...new Set(remotes.map(remoteKey))]; if (keys.length !== 1) usage('--repo . requires exactly one distinct origin remote'); return keys[0]; }
+function remoteKey(value) { const scp = /^(?:[^@]+@)?([^:]+):(.+)$/.exec(value); if (scp && !value.includes('://')) return `${scp[1]}/${scp[2].replace(/\.git$/, '')}`; const url = new URL(value); return `${url.host}${url.pathname}`.replace(/\.git$/, '').replace(/\/$/, ''); }
+function optional(object, keys) { return Object.fromEntries(keys.filter(key => object[key] !== undefined).map(key => [key, key === 'revision' ? positiveInteger(object[key], undefined, key) : object[key]])); }
+async function waitForOperation(client, context, operation, timeoutMs = 15 * 60_000) {
+  let current = operation, delayMs = 250; const deadline = Date.now() + timeoutMs;
+  while (['pending', 'running'].includes(current.state)) {
+    if (Date.now() >= deadline) throw Object.assign(new Error(`operation ${current.id} did not finish before the client timeout`), { code: 'controller_busy', exitCode: 6 });
+    await new Promise(resolveWait => setTimeout(resolveWait, Math.min(delayMs, Math.max(1, deadline - Date.now()))));
+    current = (await client.request('GET', teamPath(context, `/operations/${current.id}`))).data;
+    delayMs = Math.min(delayMs * 2, 5_000);
+  }
+  if (current.state === 'failed') throw Object.assign(new Error(current.error?.message ?? `operation ${current.id} failed`), current.error ?? { code: 'invalid_request' });
+  return current;
+}
+async function waitForContinuation(client, context, continuation, timeoutMs = 15 * 60_000) {
+  let current = continuation, delayMs = 250; const deadline = Date.now() + timeoutMs;
+  while (current.state === 'preparing') {
+    if (Date.now() >= deadline) throw Object.assign(new Error(`continuation ${current.id} was not prepared before the client timeout`), { code: 'controller_busy', exitCode: 6 });
+    await new Promise(resolveWait => setTimeout(resolveWait, Math.min(delayMs, Math.max(1, deadline - Date.now()))));
+    current = (await client.request('GET', teamPath(context, `/continuations/${current.id}`))).data;
+    delayMs = Math.min(delayMs * 2, 5_000);
+  }
+  return current;
+}
+async function downloadArtifact(client, context, sessionId, file) {
+  if (!/^upload_[a-z0-9]+$/i.test(file.upload_id) || !Number.isSafeInteger(file.byte_length) || file.byte_length < 0 || !/^[a-f0-9]{64}$/.test(file.sha256)) throw new Error('export returned an invalid artifact manifest');
+  const response = await client.fetch(client.server + teamPath(context, `/sessions/${sessionId}/artifacts/${file.upload_id}`), { redirect: 'manual', headers: { Authorization: `Bearer ${client.credential}` } });
+  if (response.type === 'opaqueredirect' || response.status >= 300 && response.status < 400) throw new Error('cross-origin artifact redirects are refused');
+  if (!response.ok) { let failure; try { failure = await response.json(); } catch {} throw Object.assign(new Error(failure?.error?.message ?? `artifact download failed: HTTP ${response.status}`), failure?.error, { status: response.status }); }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (bytes.byteLength !== file.byte_length || createHash('sha256').update(bytes).digest('hex') !== file.sha256) throw new Error(`artifact ${file.relative_name} failed length or SHA-256 verification`);
+  return bytes;
+}
+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); }
+function only(flags, allowed) { for (const key of Object.keys(flags)) if (!allowed.includes(key)) usage(`--${key.replaceAll('_', '-')} is not valid for this command`); }
+function backfill(value) { const parsed = duration(value, undefined, { allowWords: true }); return parsed === 'all' || parsed === 'none' ? { mode: parsed } : { mode: 'since', since: Date.now() - parsed }; }
+function teamPath(context, suffix) { return `/api/v1/teams/${context.team_id}${suffix}`; }
+function scope(context) { return { server_id: context.server_id, team_id: context.team_id, principal_id: context.principal_id }; }
+/** An invitation on stdin: the file `members invite --out` writes, or its bare enrollment code. */
+function inviteCode(secret) { if (!secret.startsWith('{')) return secret; let parsed; try { parsed = JSON.parse(secret); } catch { usage('--invite-stdin must be an invitation file or its enrollment code'); } if (typeof parsed?.enrollment_code !== 'string') usage('the invitation file has no enrollment_code'); return parsed.enrollment_code; }
+function hostPort(text) { const match = /^(.*):(\d+)$/.exec(text); if (!match || !match[1]) usage('--listen must be HOST:PORT'); return { host: match[1], port: Number(match[2]) }; }
+function sessionReference(value, selectedOrigin, selectedTeam, explicit) { if (!/^https?:\/\//.test(value)) return value; const url = new URL(value), parts = url.pathname.split('/').filter(Boolean); if (explicit && url.origin !== new URL(selectedOrigin).origin) usage('session URL origin conflicts with the explicit context'); if (url.origin !== new URL(selectedOrigin).origin) unsupported('the URL origin is not authenticated by the selected context'); if (parts.length !== 4 || parts[0] !== 'teams' || parts[1] !== selectedTeam || parts[2] !== 'sessions') usage('session URL must identify the selected immutable team and session'); return parts[3]; }
+function contextForUrl(document, value) { const url = new URL(value); const parts = url.pathname.split('/').filter(Boolean); const teamAt = parts.indexOf('teams'); const team = teamAt >= 0 ? parts[teamAt + 1] : null; const matches = Object.entries(document.contexts).filter(([, context]) => context.origin === url.origin && (!team || context.team_id === team)); if (matches.length > 1) usage('session URL matches more than one authenticated context'); return matches[0]?.[0] ?? null; }
+function humanOutput(value) {
+  const context = value?.context ? `Context: ${value.context.server_id}/${value.context.team_id}\n` : '';
+  if (Array.isArray(value?.items)) {
+    if (!value.items.length) return `${context}No items.\n`;
+    const rows = value.items.map(humanRow), columns = [...new Set(rows.flatMap(row => Object.keys(row)))];
+    const widths = columns.map(column => Math.max(column.length, ...rows.map(row => String(row[column] ?? '').length)));
+    const line = row => columns.map((column, index) => String(row[column] ?? '').padEnd(widths[index])).join('  ').trimEnd();
+    return `${context}${line(Object.fromEntries(columns.map(column => [column, column])))}\n${rows.map(line).join('\n')}\n${value.next_cursor ? `Next cursor: ${value.next_cursor}\n` : ''}`;
+  }
+  // A session read: its header, then the conversation as a person reads it.
+  if (value?.descriptor && Array.isArray(value.messages)) return `${context}${humanTranscript(value.descriptor, value.messages)}${value.before_cursor ? `Earlier: --before ${value.before_cursor}\n` : ''}`;
+  const data = value?.data ?? value;
+  if (data === null) return `${context}Done.\n`;
+  if (typeof data === 'string') return `${context}${data}\n`;
+  const row = humanRow(data);
+  return `${context}${Object.entries(row).map(([key, item]) => `${key}: ${item}`).join('\n')}\n`;
+}
+function humanTranscript(descriptor, messages) {
+  const when = descriptor.recorded_activity_at ? new Date(descriptor.recorded_activity_at).toISOString() : 'unknown';
+  const head = `${descriptor.title ?? descriptor.id} · ${descriptor.harness ?? 'unknown harness'} · ${descriptor.user?.principal_id ?? descriptor.user?.reported_user ?? 'unknown user'} · last activity ${when}\n`;
+  const coverage = descriptor.coverage && descriptor.coverage.completeness !== 'complete' ? `coverage: ${descriptor.coverage.completeness}${descriptor.coverage.reasons?.length ? ` (${descriptor.coverage.reasons.join(', ')})` : ''}\n` : '';
+  const text = content => typeof content === 'string' ? content : Array.isArray(content) ? content.map(part => typeof part === 'string' ? part : part?.text ?? (part?.type ? `[${part.type}]` : '')).filter(Boolean).join('\n') : content == null ? '' : JSON.stringify(content);
+  const calls = value => (value.tool_calls ?? []).map(call => `[${call.function?.name ?? call.name ?? 'tool'}] ${String(call.function?.arguments ?? call.arguments ?? '').slice(0, 200)}`).join('\n');
+  const lines = messages.map(message => { const value = message.value ?? message; const body = [text(value.content ?? value.text).trim(), calls(value)].filter(Boolean).join('\n'); return `\n${value.role ?? 'message'}:\n${body || '(no text)'}\n`; });
+  return head + coverage + (lines.length ? lines.join('') : '\n(no messages in this window)\n');
+}
+function humanRow(value) { if (!value || typeof value !== 'object') return { value }; const descriptor = value.session ?? value; return Object.fromEntries(Object.entries(descriptor).filter(([, item]) => item === null || ['string', 'number', 'boolean'].includes(typeof item)).slice(0, 8)); }
+async function stream(iterator, json) { for await (const event of iterator) process.stdout.write(json ? `${JSON.stringify(event)}\n` : humanOutput(event)); }
+function unsupported(message) { throw Object.assign(new Error(message), { code: 'unsupported', exitCode: 5 }); }
+function notFound(message) { throw Object.assign(new Error(message), { code: 'not_found', exitCode: 4 }); }
+function printHelp() {
+  process.stdout.write(`supercode workspace commands:
+  context create|list|show|use|remove
+  teams list|create
+  login [ORIGIN] [--team TEAM] [--as CONTEXT] [--token-stdin|--invite-stdin]   (Volter sign-in in the browser by default)
+  identity link
+  server start [--volter-issuer ORIGIN] [--delegated-issuer ORIGIN]
+  publish pane|root TARGET --room ROOM --workplace ORIGIN --organization ORG [--name] [--key] [--machine] [--token-stdin]
+  unpublish SURFACE --room ROOM --workplace ORIGIN --organization ORG [--token-stdin]
+  connect|disconnect|status
+  members invite|list|remove|role
+  groups list|create|remove|add-member|remove-member
+  sources create|list|status|pause|revoke|credentials|config
+  machines list|roots|access|authorize-continuation
+  sync add|list|show|pause|resume|remove
+  sessions list|search|show|follow|access|rename|delete|url|attach|export|continue
+Use --help with a command for its required arguments and options.
+`);
+}
+export function errorExit(error) { return error.exitCode ?? ERROR_EXITS[error.code] ?? 1; }
+if (import.meta.url === new URL(`file://${process.argv[1]}`).href) workspaceMain().catch(error => { process.stderr.write(`${JSON.stringify({ version: 1, error: { code: error.code ?? 'invalid_request', message: error.message } })}\n`); process.exit(errorExit(error)); });