@volter/supercode-teams 0.2.20

package/bin/teams.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+// The teams CLI. `supercode teams …` spawns this; it is also runnable directly
+// as `supercode-teams …`.
+//
+// Machine verbs act on this OS user's machine daemon through its local socket,
+// or, with `--machine NAME`, on an enrolled machine through the selected Teams
+// context's server:
+//
+//   machine start [--home dir] [--tmux-socket name] [--verbose]   run the daemon (local door only)
+//   machine status                                               the running daemon, if any
+//   describe                                     the host-key-signed statement
+//   panes ls | capture <pane> | close <pane>
+//   input <pane> <text> [--no-enter]
+//   suspend <pane> [--interrupt] | resume <pane> [--input text]   refuse/allow remote input on a pane
+//   files ls|get|put|stat|search <path> [--out f] [--in f] [--query q]
+//   ports ls | resolve <pane>          port <pane>/<n> [--listen host:port]
+//   browser <profile> [--listen host:port]   a browser-profile served here as a local CDP endpoint
+//   browser --list                          the machine's browser profiles (view on browser-profile:*)
+//   title set <pane> <text> | title ls
+//   attention ls | rank | request <pane> [--urgency now|soon|whenever] [--reason text] | clear <pane>
+//   watch [--interval ms] [--for ms]
+//   rpc <harness.v1 method> [json-params]   operators: one harness.v1 request
+//   log verify
+//
+// Every other verb (server, login, context, connect, disconnect, status,
+// members, groups, sources, sync, machines, sessions) is the Teams workspace
+// CLI in ./workspace.mjs.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+import { TeamsMachine } from '../machine.mjs';
+import { harnessTransport, nodeRpc, forwardPort, watchMachine } from '../client.mjs';
+import { attachBrowserProfile, listBrowserProfiles } from '../browser-attach.mjs';
+import { openMachine } from '../machine-door.mjs';
+import { moveWorkspace } from '../workspace-move.mjs';
+import { teamsHome, paths, readJson, AccountLog, parseHostPort } from '@volter/teams/home';
+import { NODE_PROTOCOL } from '@volter/teams/channel';
+
+const MACHINE_VERBS = new Set(['machine', 'describe', 'panes', 'input', 'suspend', 'resume', 'files', 'ports', 'port', 'browser', 'stream', 'jobs', 'workspace', 'title', 'attention', 'watch', 'rpc', 'log', 'mail']);
+// Every flag a machine verb reads; any other is refused rather than silently ignored.
+const KNOWN_FLAGS = new Set(['home', 'machine', 'context', 'floor', 'supercode', 'tmux-socket', 'verbose', 'lines', 'input', 'name', 'for', 'urgency', 'reason', 'interrupt', 'query', 'out', 'in', 'interval', 'no-enter', 'when-composer-empty', 'listen', 'list', 'from', 'to', 'path', 'to-path']);
+
+const argv = process.argv.slice(2);
+const flags = {};
+const positional = [];
+for (let i = 0; i < argv.length; i += 1) {
+  const a = argv[i];
+  if (a === '--') { positional.push(...argv.slice(i + 1)); break; }
+  if (a.startsWith('--')) {
+    const eq = a.indexOf('=');
+    if (eq > 0) { flags[a.slice(2, eq)] = a.slice(eq + 1); continue; } // --args=--norc
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith('--')) { flags[key] = next; i += 1; } else flags[key] = true;
+  } else positional.push(a);
+}
+const [verb, sub, ...rest] = positional;
+
+const MACHINE_HELP = 'machine verbs: machine start|status, describe, panes, input, suspend, resume, files, ports, port, stream, jobs, workspace, title, attention, watch, rpc, log, browser (add --machine NAME for an enrolled machine)';
+
+if (verb === undefined || verb === 'help') {
+  process.stdout.write(`supercode teams: ${MACHINE_HELP}\n`);
+  const { workspaceMain } = await import('./workspace.mjs');
+  await workspaceMain(['--help']);
+  process.exit(0);
+}
+if (!MACHINE_VERBS.has(verb)) {
+  const { workspaceMain } = await import('./workspace.mjs');
+  await workspaceMain(argv).catch((error) => {
+    process.stderr.write(JSON.stringify({ version: 1, error: { code: error.code ?? 'invalid_request', message: error.message } }) + '\n');
+    process.exit(error.exitCode ?? ({ 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 }[error.code] ?? 1));
+  });
+  process.exit(0);
+}
+
+const home = flags.home ? String(flags.home) : teamsHome();
+const p = paths(home);
+const out = (value) => process.stdout.write((typeof value === 'string' ? value : JSON.stringify(value, null, 2)) + '\n');
+const die = (message, code = 2) => { process.stderr.write(`supercode teams: ${message}\n`); process.exit(code); };
+for (const flag of Object.keys(flags)) if (!KNOWN_FLAGS.has(flag)) die(`unknown flag: --${flag}`);
+
+async function machineChannel() {
+  return openMachine({ machine: flags.machine ? String(flags.machine) : null, context: flags.context ? String(flags.context) : null, home });
+}
+
+async function withNode(fn) {
+  const channel = await machineChannel();
+  try {
+    const rpc = await nodeRpc(channel);
+    return await fn(rpc, channel);
+  } finally {
+    channel.close();
+  }
+}
+
+async function main() {
+  switch (verb) {
+    case 'machine': {
+      if (sub === 'start') {
+        const machine = new TeamsMachine({
+          home,
+          floor: flags.floor ? Number(flags.floor) : null,
+          supercode: flags.supercode ?? 'supercode',
+          // A named tmux server keeps a daemon's panes off the default socket.
+          ...(flags['tmux-socket'] ? { tmuxSocket: String(flags['tmux-socket']) } : {}),
+        });
+        // --verbose narrates every door with its latency, so a slow machine is diagnosed from its own log.
+        machine.on('door', (d) => { if (flags.verbose) process.stderr.write(`door ${d.method} ${d.outcome} ${d.ms}ms${d.detail ? ` ${d.detail}` : ''}\n`); });
+        machine.on('serve-stderr', (t) => process.stderr.write(t));
+        machine.on('serve-exit', (e) => process.stderr.write(`harness serve exited: ${JSON.stringify(e)}\n`));
+        machine.on('unrouted-notification', (m) => { if (flags.verbose) process.stderr.write(`unrouted: ${m.method}\n`); });
+        const socket = await machine.start();
+        out({ id: machine.id, socket, home, protocol: NODE_PROTOCOL, floor: machine.floor });
+        const stop = async () => { await machine.stop(); process.exit(0); };
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+        return;
+      }
+      if (sub === 'status') { out(readJson(p.machine, { running: false })); return; }
+      die('machine start|status');
+    }
+    case 'describe':
+      return withNode(async (rpc) => out(await rpc.call('describe')));
+    case 'panes': {
+      if (sub === 'ls') return withNode(async (rpc) => out(await rpc.call('panes.list')));
+      if (sub === 'capture') return withNode(async (rpc) => out((await rpc.call('panes.capture', { pane: rest[0], lines: Number(flags.lines ?? 200) })).text));
+      if (sub === 'close') return withNode(async (rpc) => out(await rpc.call('panes.close', { pane: rest[0] })));
+      die('panes ls|capture|close');
+    }
+    case 'title': {
+      if (sub === 'set') return withNode(async (rpc) => out(await rpc.call('title.set', { target: `pane:${rest[0]}`, title: rest.slice(1).join(' ') || null })));
+      if (sub === 'ls' || sub === undefined) return withNode(async (rpc) => out(await rpc.call('title.list')));
+      die('title set <pane> <text> | title ls');
+    }
+    case 'attention': {
+      // The machine computes the label; this prints it. Sorted by rank so the most
+      // urgent pane is the first line, which is the only ordering a person
+      // reading a fleet list ever wants.
+      if (sub === 'ls' || sub === undefined) {
+        return withNode(async (rpc) => {
+          const rows = await rpc.call('attention.snapshot');
+          out([...rows].sort((a, b) => a.rank - b.rank));
+        });
+      }
+      if (sub === 'rank') return withNode(async (rpc) => out(await rpc.call('attention.rank')));
+      if (sub === 'request') return withNode(async (rpc) => out(await rpc.call('attention.request', { pane: rest[0], urgency: flags.urgency ? String(flags.urgency) : undefined, reason: flags.reason ? String(flags.reason) : null })));
+      if (sub === 'clear') return withNode(async (rpc) => out(await rpc.call('attention.clear', { pane: rest[0] })));
+      die('attention ls | rank | request <pane> [--urgency now|soon|whenever] [--reason text] | clear <pane>');
+    }
+    case 'suspend':
+      return withNode(async (rpc) => out(await rpc.call('panes.suspend', { pane: sub, interrupt: Boolean(flags.interrupt) })));
+    case 'resume':
+      return withNode(async (rpc) => out(await rpc.call('panes.resume', { pane: sub, input: flags.input ? String(flags.input) : null })));
+    case 'files': {
+      const path = rest[0];
+      if (sub === 'ls') return withNode(async (rpc) => out(await rpc.call('files.list', { path })));
+      if (sub === 'stat') return withNode(async (rpc) => out(await rpc.call('files.stat', { path })));
+      if (sub === 'search') return withNode(async (rpc) => out(await rpc.call('files.search', { path, query: flags.query ?? '' })));
+      if (sub === 'get') return withNode(async (rpc) => {
+        const result = await rpc.call('files.read', { path });
+        const bytes = Buffer.from(result.bytes, 'base64');
+        if (flags.out) writeFileSync(flags.out, bytes); else process.stdout.write(bytes);
+      });
+      if (sub === 'put') return withNode(async (rpc) => {
+        const bytes = flags.in ? readFileSync(flags.in) : readFileSync(0);
+        out(await rpc.call('files.write', { path, bytes: bytes.toString('base64'), truncate: true }));
+      });
+      die('files ls|stat|search|get|put <path>');
+    }
+    case 'ports': {
+      if (sub === 'ls' || sub === undefined) return withNode(async (rpc) => out(await rpc.call('ports.list')));
+      if (sub === 'resolve') return withNode(async (rpc) => out(await rpc.call('ports.resolve', { pane: rest[0] })));
+      die('ports ls|resolve <pane>');
+    }
+    case 'watch': {
+      // `watch [--interval ms]`: the machine's live state as JSON lines — one snapshot, then deltas — until ctrl-c.
+      const channel = await machineChannel();
+      const w = await watchMachine(channel, { intervalMs: Number(flags.interval ?? 1000) });
+      w.on('snapshot', (s) => out(JSON.stringify(s)));
+      w.on('delta', (d) => out(JSON.stringify(d)));
+      w.on('error-message', (m) => process.stderr.write(`[watch: ${m}]\n`));
+      w.on('close', (reason) => { process.stderr.write(`[watch ended${reason ? `: ${reason}` : ''}]\n`); channel.close(); process.exit(0); });
+      if (typeof flags.for === 'string') setTimeout(() => { w.close(); }, Number(flags.for));
+      return;
+    }
+    case 'input':
+      // `input <pane> <text>`: one delivery through the host's own sendInput; gated like control.
+      // `--when-composer-empty`: a user's own turn, typed only into an empty composer
+      // (answers `delivered: false` with the reason when it holds a draft).
+      if (flags['when-composer-empty']) return withNode(async (rpc) => out(await rpc.call('panes.turn', { pane: sub, text: rest.join(' ') })));
+      return withNode(async (rpc) => out(await rpc.call('panes.input', { pane: sub, text: rest.join(' '), submit: !flags['no-enter'] })));
+    case 'port': {
+      // `port <pane>/<n> [--listen host:port]`: a machine port forwarded here. Stays up until ctrl-c.
+      const spec = String(sub ?? '');
+      const slash = spec.lastIndexOf('/');
+      const pane = slash > 0 ? spec.slice(0, slash) : null;
+      const portNumber = Number(slash >= 0 ? spec.slice(slash + 1) : spec);
+      if (!Number.isInteger(portNumber)) die('port <pane>/<n> [--listen host:port]');
+      const channel = await machineChannel();
+      const fwd = await forwardPort(channel, { pane, port: portNumber, listen: parseHostPort(flags.listen) });
+      out({ local: fwd.address, remote: `${pane ?? '*'}/${portNumber}` });
+      const stop = async () => { await fwd.close(); channel.close(); process.exit(0); };
+      process.on('SIGINT', stop);
+      process.on('SIGTERM', stop);
+      return;
+    }
+    case 'browser': {
+      // `browser <profile> [--listen host:port]`: a machine's browser profile as a local CDP
+      // endpoint (connectOverCDP to the printed address). Stays up until ctrl-c.
+      if (flags.list) {
+        const channel = await machineChannel();
+        try { out(await listBrowserProfiles(channel)); } finally { channel.close(); }
+        return;
+      }
+      if (!sub) die('browser <profile> [--listen host:port] [--machine NAME] | browser --list [--machine NAME]');
+      const attached = await attachBrowserProfile(() => machineChannel(), { profile: String(sub), listen: parseHostPort(flags.listen) });
+      out({ cdp: attached.address, target: `browser-profile:${sub}` });
+      const stop = async () => { await attached.close(); process.exit(0); };
+      process.on('SIGINT', stop);
+      process.on('SIGTERM', stop);
+      return;
+    }
+    case 'stream': {
+      // `stream exec|sftp [--machine NAME]`: this process's stdin and stdout carried to one of the
+      // machine's execution streams, the transport a pilot's exec client and SSHFS (passive) use.
+      if (sub !== 'exec' && sub !== 'sftp') die('stream exec|sftp [--machine NAME]');
+      const channel = await machineChannel();
+      let stream;
+      try { stream = await channel.open(sub, {}); } catch (error) { die(error.message, 1); }
+      stream.on('data', (chunk) => process.stdout.write(Buffer.from(chunk, 'base64')));
+      stream.on('close', () => { channel.close(); process.stdout.end(() => process.exit(0)); });
+      process.stdin.on('data', (bytes) => { if (!stream.closed) stream.write(bytes.toString('base64')); });
+      process.stdin.on('end', () => stream.close('input ended'));
+      return;
+    }
+    case 'mail': {
+      // `mail --machine NAME`: one `supercode message` request (JSON on stdin) to that
+      // machine's mail door, and its answer (one JSON line) on stdout.
+      const chunks = [];
+      for await (const chunk of process.stdin) chunks.push(chunk);
+      let request;
+      try { request = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { die('mail reads one JSON request on stdin'); }
+      const channel = await machineChannel();
+      let stream;
+      try { stream = await channel.open('mail', { request }); } catch (error) { die(error.message, 1); }
+      let answered = false;
+      stream.on('data', (chunk) => { answered = true; process.stdout.write(`${chunk}\n`); });
+      stream.on('close', (reason) => {
+        channel.close();
+        if (!answered) process.stdout.write(`${JSON.stringify({ outcome: 'failed', detail: String(reason ?? 'the mail door closed without answering') })}\n`);
+        process.exit(0);
+      });
+      return;
+    }
+    case 'workspace': {
+      // `workspace move --from A --to B --path P [--to-path Q]`: the project leaves A and arrives
+      // at B, published there only if every byte arrived (sha256 on commit) and neither machine
+      // runs an exec job. A is left as it was; B's path must not exist.
+      if (sub !== 'move' || !flags.from || !flags.to || !flags.path) die('workspace move --from MACHINE --to MACHINE --path P [--to-path Q]');
+      try {
+        out(await moveWorkspace({ from: String(flags.from), to: String(flags.to), path: String(flags.path), toPath: String(flags['to-path'] ?? flags.path), context: flags.context ? String(flags.context) : null, home }));
+      } catch (error) { die(error.message, error.exitCode ?? 1); }
+      return;
+    }
+    case 'jobs':
+      // `jobs [--machine NAME]`: the execution jobs the machine's daemon owns now.
+      return withNode(async (rpc) => out(await rpc.call('jobs.list', {})));
+    case 'rpc': {
+      const channel = await machineChannel();
+      const client = new SupercodeHarnessClient({ transport: harnessTransport(channel) });
+      try {
+        await client.start?.();
+        const params = rest[0] ? JSON.parse(rest[0]) : {};
+        const method = sub.startsWith('harness.v1.') ? sub : `harness.v1.${sub}`;
+        out(await client.request(method, params));
+      } finally {
+        await client.close?.();
+        channel.close();
+      }
+      return;
+    }
+    case 'log': {
+      if (sub !== 'verify') die('log verify');
+      out(AccountLog.verify(p.log));
+      return;
+    }
+    default:
+      die(MACHINE_HELP);
+  }
+}
+
+main().catch((error) => die(error.message ?? String(error), error.code === 'machine_offline' ? 5 : 1));

package/bin/workspace/args.mjs

@@ -0,0 +1,66 @@
+const BOOLEANS = new Set([
+  'json', 'help', 'live', 'saved', 'watch', 'paginate', 'token-stdin',
+  'invite-stdin', 'include-children', 'rotate', 'install', 'force',
+  'take-control', 'dry-run', 'volter', 'foreground',
+]);
+
+const VALUES = new Set([
+  'context', 'server', 'team', 'credential-ref', 'data-dir', 'listen',
+  'public-origin', 'init-team', 'as', 'user', 'repo', 'harness', 'machine',
+  'source', 'cursor', 'limit', 'tail', 'before', 'after', 'revision', 'role',
+  'out', 'ttl', 'type', 'name', 'visibility', 'backfill', 'format', 'to',
+  'grant', 'binding', 'caps', 'fidelity', 'cwd', 'root', 'workspace-from', 'since', 'until', 'session',
+  'on', 'timeout', 'plan', 'tmux-socket', 'volter-issuer', 'delegated-issuer', 'workplace', 'organization', 'key', 'room',
+]);
+
+export function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--') {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!argument.startsWith('--')) {
+      positionals.push(argument);
+      continue;
+    }
+    const equals = argument.indexOf('=');
+    const raw = argument.slice(2, equals < 0 ? undefined : equals);
+    const key = raw.replaceAll('-', '_');
+    if (!BOOLEANS.has(raw) && !VALUES.has(raw)) usage(`unknown option --${raw}`);
+    if (Object.hasOwn(flags, key)) usage(`duplicate option --${raw}`);
+    if (BOOLEANS.has(raw)) {
+      if (equals >= 0) usage(`--${raw} does not take a value`);
+      flags[key] = true;
+      continue;
+    }
+    const value = equals >= 0 ? argument.slice(equals + 1) : argv[++index];
+    if (value === undefined || value.startsWith('--')) usage(`--${raw} requires a value`);
+    flags[key] = value;
+  }
+  return { flags, positionals };
+}
+
+export function usage(message) {
+  throw Object.assign(new Error(message), { code: 'invalid_request', exitCode: 2 });
+}
+
+export function requireArgs(actual, min, max, syntax) {
+  if (actual.length < min || actual.length > max) usage(`usage: ${syntax}`);
+}
+
+export function positiveInteger(value, fallback, name) {
+  if (value === undefined) return fallback;
+  if (!/^[1-9]\d*$/.test(value)) usage(`--${name} must be a positive integer`);
+  return Number(value);
+}
+
+export function duration(value, fallback, { allowWords = false } = {}) {
+  if (value === undefined) return fallback;
+  if (allowWords && ['all', 'none'].includes(value)) return value;
+  const match = /^([1-9]\d*)([smhd])$/.exec(value);
+  if (!match) usage('duration must be a positive integer followed by s, m, h, or d');
+  return Number(match[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2]];
+}

package/bin/workspace/files.mjs

@@ -0,0 +1,110 @@
+import { chmodSync, closeSync, existsSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { usage } from './args.mjs';
+
+export function assertWritable(path, { force = false } = {}) {
+  if (!path) usage('--out is required');
+  if (existsSync(path) && !force) usage(`refusing to overwrite existing file ${path}; pass --force`);
+}
+
+export function writeProtected(path, value, { force = false } = {}) {
+  assertWritable(path, { force });
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`;
+  const descriptor = openSync(temporary, 'wx', 0o600);
+  try { writeFileSync(descriptor, JSON.stringify(value, null, 2) + '\n'); } finally { closeSync(descriptor); }
+  try {
+    if (force) renameSync(temporary, path);
+    else { linkSync(temporary, path); unlinkSync(temporary); }
+  } catch (error) { try { unlinkSync(temporary); } catch {} if (error.code === 'EEXIST') usage(`refusing to overwrite existing file ${path}; pass --force`); throw error; }
+  chmodSync(path, 0o600);
+}
+
+export function reserveProtected(path, { force = false } = {}) {
+  if (!path) usage('--out is required');
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  if (!force) {
+    let descriptor;
+    try { descriptor = openSync(path, 'wx', 0o600); } catch (error) { if (error.code === 'EEXIST') usage(`refusing to overwrite existing file ${path}; pass --force`); throw error; }
+    let settled = false;
+    return {
+      write(value) { if (settled) throw new Error('output reservation is already settled'); writeFileSync(descriptor, JSON.stringify(value, null, 2) + '\n'); closeSync(descriptor); descriptor = null; chmodSync(path, 0o600); settled = true; },
+      writeBytes(value) { if (settled) throw new Error('output reservation is already settled'); writeFileSync(descriptor, value); closeSync(descriptor); descriptor = null; chmodSync(path, 0o600); settled = true; },
+      abort() { if (settled) return; if (descriptor !== null) closeSync(descriptor); try { unlinkSync(path); } catch {} settled = true; },
+    };
+  }
+  const temporary = `${path}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`, descriptor = openSync(temporary, 'wx', 0o600);
+  let settled = false;
+  return {
+    write(value) { if (settled) throw new Error('output reservation is already settled'); writeFileSync(descriptor, JSON.stringify(value, null, 2) + '\n'); closeSync(descriptor); renameSync(temporary, path); chmodSync(path, 0o600); settled = true; },
+    writeBytes(value) { if (settled) throw new Error('output reservation is already settled'); writeFileSync(descriptor, value); closeSync(descriptor); renameSync(temporary, path); chmodSync(path, 0o600); settled = true; },
+    abort() { if (settled) return; closeSync(descriptor); try { unlinkSync(temporary); } catch {} settled = true; },
+  };
+}
+
+export function reserveArtifactDirectory(path, { force = false } = {}) {
+  if (!path) usage('--out is required');
+  path = resolve(path);
+  const parent = dirname(path), lock = `${path}.export-lock`, stage = `${path}.stage.${process.pid}.${randomBytes(12).toString('hex')}`;
+  mkdirSync(parent, { recursive: true, mode: 0o700 });
+  try { mkdirSync(lock, { mode: 0o700 }); } catch (error) { if (error.code === 'EEXIST') usage(`export destination ${path} is reserved by another writer`); throw error; }
+  let destinationIdentity = null;
+  try {
+    if (existsSync(path)) {
+      if (!force) usage(`refusing to overwrite existing directory ${path}; pass --force`);
+      const status = lstatSync(path);
+      if (!status.isDirectory() || status.isSymbolicLink()) usage(`export destination ${path} must be a real directory`);
+      destinationIdentity = { dev: status.dev, ino: status.ino };
+    }
+    mkdirSync(stage, { mode: 0o700 });
+  } catch (error) { rmSync(lock, { recursive: true, force: true }); throw error; }
+  let settled = false;
+  const safe = name => {
+    if (typeof name !== 'string' || !name || isAbsolute(name)) usage('export contains an unsafe relative filename');
+    const clean = normalize(name); if (clean === '..' || clean.startsWith(`..${sep}`) || clean.includes(`.${sep}..${sep}`)) usage('export contains an unsafe relative filename');
+    const target = resolve(stage, clean); if (relative(stage, target).startsWith('..')) usage('export filename escapes its destination');
+    return { clean, target };
+  };
+  return {
+    path,
+    write(name, bytes) { const { target } = safe(name); mkdirSync(dirname(target), { recursive: true, mode: 0o700 }); const fd = openSync(target, 'wx', 0o600); try { writeFileSync(fd, bytes); } finally { closeSync(fd); } },
+    publish() {
+      if (settled) throw new Error('artifact directory reservation is already settled');
+      const current = existsSync(path) ? lstatSync(path) : null;
+      if (!destinationIdentity) {
+        if (current) usage(`refusing to overwrite existing directory ${path}; pass --force`);
+        renameSync(stage, path);
+      } else {
+        if (!current || !current.isDirectory() || current.isSymbolicLink() || current.dev !== destinationIdentity.dev || current.ino !== destinationIdentity.ino) usage(`export destination ${path} changed while the export was staged`);
+        const stagedFiles = [];
+        const inspectTree = (source, relativeRoot = '') => {
+          for (const entry of readdirSync(source, { withFileTypes: true })) {
+            const relativeName = join(relativeRoot, entry.name), target = join(path, relativeName);
+            let cursor = path;
+            for (const segment of relativeName.split(sep).slice(0, -1)) {
+              cursor = join(cursor, segment);
+              if (existsSync(cursor)) {
+                const status = lstatSync(cursor);
+                if (!status.isDirectory() || status.isSymbolicLink()) usage(`export path ${cursor} is not a real directory`);
+              }
+            }
+            if (entry.isDirectory()) inspectTree(join(source, entry.name), relativeName);
+            else {
+              if (existsSync(target) && lstatSync(target).isSymbolicLink()) usage(`export path ${target} is a symlink`);
+              stagedFiles.push({ from: join(source, entry.name), to: target });
+            }
+          }
+        };
+        inspectTree(stage);
+        for (const { to } of stagedFiles) mkdirSync(dirname(to), { recursive: true, mode: 0o700 });
+        const afterPreflight = lstatSync(path);
+        if (!afterPreflight.isDirectory() || afterPreflight.isSymbolicLink() || afterPreflight.dev !== destinationIdentity.dev || afterPreflight.ino !== destinationIdentity.ino) usage(`export destination ${path} changed while the export was staged`);
+        for (const { from, to } of stagedFiles) { renameSync(from, to); chmodSync(to, 0o600); }
+        rmSync(stage, { recursive: true, force: true });
+      }
+      rmSync(lock, { recursive: true, force: true }); settled = true;
+    },
+    abort() { if (settled) return; rmSync(stage, { recursive: true, force: true }); rmSync(lock, { recursive: true, force: true }); settled = true; },
+  };
+}

package/bin/workspace/lifecycle.mjs

@@ -0,0 +1,113 @@
+import { createConnection, createServer } from 'node:net';
+import { mkdirSync, renameSync, rmSync, unlinkSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { shortSocketPath, ensureSocketDirectory } from '@volter/teams/home';
+import { execFileSync } from 'node:child_process';
+
+const wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds));
+const processIdentity = pid => {
+  try { return execFileSync('/bin/ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', timeout: 1_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null; }
+  catch { return null; }
+};
+const readOwner = lock => {
+  try { return JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8')); }
+  catch { return null; }
+};
+const sameOwner = owner => owner?.pid > 0 && owner.start === processIdentity(owner.pid);
+
+export async function activeSocket(path) {
+  return new Promise(resolve => {
+    const socket = createConnection(path);
+    let settled = false;
+    const finish = value => { if (settled) return; settled = true; socket.destroy(); resolve(value); };
+    socket.setTimeout(1_000, () => finish(false));
+    socket.once('connect', () => socket.end('probe\n'));
+    socket.once('data', () => finish(true));
+    socket.once('end', () => finish(true));
+    socket.once('error', () => finish(false));
+  });
+}
+
+export async function acquireLifecycle(directory, onStop) {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const lock = join(directory, 'lifecycle.lock'), socketPath = shortSocketPath(directory, 'control.sock');
+  ensureSocketDirectory(socketPath);
+  const token = randomBytes(32).toString('base64url');
+  const owner = { version: 1, token, pid: process.pid, start: processIdentity(process.pid), created_at: Date.now() };
+  for (;;) {
+    try {
+      mkdirSync(lock, { mode: 0o700 });
+      writeFileSync(join(lock, 'owner.json'), `${JSON.stringify(owner)}\n`, { mode: 0o600, flag: 'wx' });
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const current = readOwner(lock);
+      // A live exact process identity owns the lock even before its control
+      // socket is bound. A just-created incomplete record receives the same
+      // startup protection rather than being stolen by a concurrent caller.
+      if (sameOwner(current) || !current || Date.now() - Number(current.created_at ?? 0) < 10_000) {
+        throw Object.assign(new Error('connector is already running or starting'), { code: 'conflict', exitCode: 6 });
+      }
+      const stale = `${lock}.stale.${randomBytes(8).toString('hex')}`;
+      try {
+        // rename is the atomic claim. Re-read the moved inode before deleting:
+        // another recoverer may already have replaced `lock` with its live
+        // ownership record after our stale read. In that case restore it and
+        // refuse instead of stealing the successor.
+        renameSync(lock, stale);
+        if (readOwner(stale)?.token !== current.token) {
+          try { renameSync(stale, lock); } catch {}
+          throw Object.assign(new Error('connector ownership changed during stale recovery'), { code: 'conflict', exitCode: 6 });
+        }
+        rmSync(stale, { recursive: true, force: true });
+      }
+      catch (renameError) { if (renameError.code !== 'ENOENT') throw renameError; }
+    }
+  }
+  try { unlinkSync(socketPath); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const server = createServer(connection => {
+    let body = ''; connection.setEncoding('utf8');
+    connection.on('error', () => {});
+    connection.on('data', chunk => { body += chunk; if (body.length > 1024) connection.destroy(); });
+    connection.on('end', () => {
+      if (body.trim() !== token) { connection.end('forbidden\n'); return; }
+      connection.end('ok\n', () => { void onStop(); });
+    });
+  });
+  try {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(socketPath, resolve); });
+  } catch (error) {
+    if (readOwner(lock)?.token === token) rmSync(lock, { recursive: true, force: true });
+    throw error;
+  }
+  return {
+    token,
+    socketPath,
+    close: async () => {
+      await new Promise(resolve => server.close(resolve));
+      if (readOwner(lock)?.token !== token) return;
+      try { unlinkSync(socketPath); } catch {}
+      rmSync(lock, { recursive: true, force: true });
+    },
+  };
+}
+
+export async function requestStop(socketPath, token) {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      const reply = await new Promise((resolve, reject) => {
+        const socket = createConnection(socketPath); let text = '', settled = false;
+        const finish = (error, value) => { if (settled) return; settled = true; socket.destroy(); error ? reject(error) : resolve(value); };
+        socket.setTimeout(500, () => finish(new Error('connector control request timed out')));
+        socket.setEncoding('utf8');
+        socket.once('connect', () => socket.end(`${token}\n`));
+        socket.on('data', chunk => { text += chunk; if (text.length > 1024) finish(new Error('connector control reply is too large')); });
+        socket.once('end', () => finish(null, text));
+        socket.once('error', error => finish(error));
+      });
+      if (reply.trim() !== 'ok') throw new Error('connector control token was rejected');
+      return;
+    } catch (error) { if (attempt === 4) throw error; await wait(50); }
+  }
+}

package/bin/workspace/volter-device.mjs

@@ -0,0 +1,42 @@
+// Signing a person in with Volter from a terminal: through this machine's one shared Volter sign-in
+// (`@volter/identity`, `volter login`). When someone has already signed in on this machine (with `volter login` or
+// any Volter tool), no prompt appears; otherwise the person signs in once, in the browser where there is one and by
+// a device code where there is not, and the result is kept for every tool. Either way the Teams server gets its own access token, whose
+// audience is that server.
+import { DEFAULT_ISSUER, signIn, tokenFor } from '@volter/identity';
+
+export const VOLTER_ISSUER = DEFAULT_ISSUER;
+
+/**
+ * The Teams server's access token, or with `finish` what finish makes of it. `finish({ token, ask })` runs once the
+ * person is signed in: `ask(question)` puts a question in the browser tab they signed in from, and is null when there
+ * is none (they were signed in already, or signed in by a device code). It returns `{ result, page }`: the result is
+ * this function's, and `page` what the tab ends on.
+ */
+export async function volterDeviceSignIn({ issuer = VOLTER_ISSUER, audience, say = (line) => process.stderr.write(`${line}\n`), finish = null }) {
+  issuer = new URL(issuer).origin;
+  const held = await tokenFor(audience);
+  if (held) return finish ? (await finish({ token: held, ask: null })).result : held;
+  let finished = null;
+  const token = async () => {
+    const value = await tokenFor(audience);
+    if (!value) throw new Error('the Volter sign-in did not keep');
+    return value;
+  };
+  await signIn({
+    issuer,
+    prompt: ({ url, userCode, opened }) => {
+      say(opened
+        ? `Your browser is open to sign in with Volter; finish there. (If it did not open: ${url})`
+        : `To sign in with Volter, open ${url}${userCode ? ` and enter the code ${userCode}` : ''}`);
+      say('Every Volter tool on this machine will use this sign-in.');
+    },
+    finish: async ({ ask }) => {
+      finished = finish ? await finish({ token: await token(), ask: ask ?? null }) : { result: await token() };
+      return finished.page;
+    },
+  });
+  // An @volter/identity before 0.4 does not run `finish`; the sign-in is kept all the same.
+  finished ??= finish ? await finish({ token: await token(), ask: null }) : { result: await token() };
+  return finished.result;
+}