stateport 0.0.0-stage → 1.0.0-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StatePort contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# StatePort
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Save a browser reproduction as a State Card, verify a fix against the same
+conditions, and reopen it in a later coding-agent session.
+
+Requires an existing Node.js 24.x/npm installation. Install with `npx stateport`
+(PowerShell: `npx.cmd stateport`). The transparent bootstrap verifies and downloads
+the platform runtime and configures the detected supported coding agent.
+Desktop is optional. Capture uses a separate StatePort-owned browser profile.
+The system-browser runtime excludes Chromium; the pinned browser fallback is a
+separate explicit, integrity-checked download. Developer execution requires
+valid StatePort Developer access.
+
+Documentation: https://docs.stateport.dev/
+Source: https://github.com/StatePort-Dev/stateport-agent-skills/tree/main/bootstrap
+
+## What happens next
+
+The terminal shows download progress, a component checklist (runtime, browser,
+skills and coding-agent connection), and concrete next steps with an example
+request for your agent. Existing edited/foreign settings are preserved; a setup
+conflict is clearly marked incomplete and exits with code 1. Runtime installation
+and host tool discovery are separate outcomes.
+
+Use `npx stateport --json` for scripts or an authorized same-chat agent setup.
+It returns the exact verified `currentTask` launcher descriptor. Human text is
+not a machine protocol. MCP/task-session remain machine-only automatically.
+`--help` and `--version` do not install anything. `NO_COLOR` disables colour;
+redirected output is plain text.
+
+Bootstrap rc.6 delivers these terminal improvements while retaining signed
+runtime rc.5 and skills beta.82. No runtime or browser artifact is replaced.

package/bin/stateport.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { installCandidate, readCurrent, withInstallTransaction } from '../lib/install.mjs';
+import { installPublishedRelease } from '../lib/release.mjs';
+import { readUpdatePolicy, setUpdatePolicy } from '../lib/update-policy.mjs';
+import { updateStatus, checkForUpdates, selectSessionRuntime, rollbackGeneration } from '../lib/updates.mjs';
+import { updateControl } from '../lib/controls.mjs';
+import { ensureLauncher } from '../lib/launcher.mjs';
+import { createCliOutput, installNeedsAttention } from '../lib/cli-output.mjs';
+
+const rawArgs = process.argv.slice(2);
+const protocolCommands = new Set(['mcp', 'task-session', 'task-start', 'task-call', 'task-tools', 'task-close']);
+const output = createCliOutput({ json: rawArgs.includes('--json') || protocolCommands.has(rawArgs.find(arg => arg !== '--json')) });
+const write = (value, kind) => output.emit(value, kind);
+
+function cacheRoot() {
+  const configured = process.platform === 'win32' ? process.env.LOCALAPPDATA : process.platform === 'linux' ? process.env.XDG_DATA_HOME : undefined;
+  const base = configured && isAbsolute(configured) ? configured
+    : process.platform === 'win32' ? join(homedir(), 'AppData', 'Local')
+      : process.platform === 'darwin' ? join(homedir(), 'Library', 'Caches') : join(homedir(), '.local', 'share');
+  return join(base, 'StatePort', 'agent-runtime');
+}
+async function run(runtime, args, capture = false) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [runtime.entry, ...args], { stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit', windowsHide: true });
+    let output = ''; let size = 0;
+    child.stdout?.on('data', chunk => { size += chunk.length; if (size > 1024 * 1024) child.kill(); else output += chunk; });
+    // No captured native/backend error strings enter bootstrap diagnostics.
+    child.stderr?.resume();
+    child.once('error', () => reject(Error('RUNTIME_UNAVAILABLE')));
+    child.once('close', code => {
+      if (code !== 0) { reject(Error('RUNTIME_FAILED')); return; }
+      if (!capture) { resolve(undefined); return; }
+      try { resolve(JSON.parse(output)); } catch { reject(Error('RUNTIME_REPLY_INVALID')); }
+    });
+  });
+}
+async function main() {
+  const args = rawArgs.filter(arg => arg !== '--json');
+  if (rawArgs.filter(arg => arg === '--json').length > 1) throw Error('INVALID_ARGUMENTS');
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) { output.help(); return; }
+  if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
+    const metadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    if (rawArgs.includes('--json')) write({ version: metadata.version }); else process.stdout.write(metadata.version + '\n');
+    return;
+  }
+  if (Number(process.versions.node.split('.')[0]) !== 24) throw Error('NODE_24_LTS_CANDIDATE_REQUIRED');
+  if (!((process.platform === 'linux' || process.platform === 'win32') && process.arch === 'x64') && !(process.platform === 'darwin' && process.arch === 'arm64')) throw Error('PLATFORM_UNSUPPORTED');
+  const commands = new Set(['install', 'update', 'updates', 'repair-launcher', 'rollback', 'uninstall', 'browser-install', 'doctor', 'open', 'access', 'mcp', 'task-session', 'task-start', 'task-call', 'task-tools', 'task-close']);
+  if (args[0] && !args[0].startsWith('--') && !commands.has(args[0])) throw Error('INVALID_ARGUMENTS');
+  const command = commands.has(args[0]) ? args.shift() : 'install';
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) { output.help(); return; }
+  const cache = cacheRoot();
+  const trust = JSON.parse(await readFile(new URL('../update-release.json', import.meta.url), 'utf8'));
+  if (command === 'repair-launcher') {
+    if (args.length !== 1 || args[0] !== '--confirm') throw Error('INVALID_ARGUMENTS');
+    const runtime = await readCurrent(cache);
+    if (runtime?.generation?.launcher !== 1) throw Error('LAUNCHER_REPAIR_UNSUPPORTED');
+    write({ status: 'launcher_repaired', launcher: await ensureLauncher(cache, trust, { repair: true }), userData: 'preserved', editedLoader: 'backed_up_if_changed' }); return;
+  }
+  if (command === 'updates') { write(await updateControl(cache, trust, args), 'updates'); return; }
+  if (['doctor', 'open', 'access', 'mcp', 'task-session', 'task-start', 'task-call', 'task-tools', 'task-close'].includes(command)) {
+    const runtime = await readCurrent(cache); if (!runtime) throw Error('RUNTIME_NOT_INSTALLED');
+    if (command === 'doctor') { write(await run(runtime, ['doctor', ...args], true), 'doctor'); return; }
+    if (runtime.generation) {
+      // Stable loader performs safe next-session resolution. Read-only and
+      // existing task-call/close commands never trigger update checks.
+      const loader = join(cache, 'launcher', 'main.cjs');
+      await run({ entry: loader }, [command, ...args]); return;
+    }
+    await run(runtime, [command, ...args]); return;
+  }
+  if (command === 'uninstall') {
+    if (args.length) throw Error('INVALID_ARGUMENTS');
+    await withInstallTransaction(cache, async transaction => {
+      const runtime = await transaction.current();
+      if (runtime) {
+        const setup = await run(runtime, ['remove-agent-setup'], true);
+        if (setup.status !== 'removed') { write({ status: 'conflict', setup, userData: 'preserved' }); process.exitCode = 1; return; }
+      }
+      write(await transaction.uninstall());
+    }); return;
+  }
+  if (command === 'rollback') {
+    if (args.length) throw Error('INVALID_ARGUMENTS');
+    const policy = await readUpdatePolicy(cache);
+    if (policy.mode === 'pinned') throw Error('PIN_RELEASE_REQUIRED');
+    const runtime = await rollbackGeneration(cache);
+    const result = { status: 'rolled_back', runtime: runtime.productVersion, doctor: await run(runtime, ['doctor'], true), setup: await run(runtime, ['setup'], true), hostDiscovered: 'unverified' };
+    write(result); if (installNeedsAttention(result)) process.exitCode = 1; return;
+  }
+  let source, manifestSha256, agent, offline = false, confirmDownload, consentUpdates = false;
+  while (args.length) {
+    const option = args.shift();
+    if (option === '--offline' && !offline) { offline = true; continue; }
+    if (option === '--consent-updates' && !consentUpdates) { consentUpdates = true; continue; }
+    const value = args.shift();
+    if (!value) throw Error('INVALID_ARGUMENTS');
+    if (option === '--candidate-dir' && !source) source = value;
+    else if (option === '--manifest-sha256' && !manifestSha256) manifestSha256 = value;
+    else if (option === '--agent' && !agent && ['codex', 'claude', 'cursor'].includes(value)) agent = value;
+    else if (option === '--confirm-download' && !confirmDownload && /^[a-f0-9]{64}$/.test(value)) confirmDownload = value;
+    else throw Error('INVALID_ARGUMENTS');
+  }
+  if ((source && !manifestSha256) || (!source && manifestSha256) || (source && offline)) throw Error('INVALID_ARGUMENTS');
+  let runtime;
+  const policy = await readUpdatePolicy(cache);
+  if (policy.mode === 'pinned' && (command === 'update' || command === 'browser-install' || (manifestSha256 && manifestSha256 !== policy.pin.digest))) throw Error('PIN_RELEASE_REQUIRED');
+  if (command === 'update' && !source && !offline && trust.status === 'published') {
+    const outcome = await checkForUpdates(cache, trust, { force: true, manual: true, confirmDownload });
+    const selected = await selectSessionRuntime(cache, trust, { manual: true });
+    write({ status: 'update_checked', outcome, selected: { version: selected.productVersion, digest: selected.digest }, updates: await updateStatus(cache) }); return;
+  }
+  if (offline) {
+    runtime = await readCurrent(cache); if (!runtime) throw Error('OFFLINE_CACHE_UNAVAILABLE');
+    runtime = { ...runtime, unchanged: true };
+  } else if (!source) {
+    const release = JSON.parse(await readFile(new URL('../release.json', import.meta.url), 'utf8'));
+    if (release.status === 'unpublished') throw Error('PUBLIC_RUNTIME_RELEASE_UNPUBLISHED');
+    const current = await readCurrent(cache);
+    runtime = await installPublishedRelease(release, cache, fetch, { browserPreference: command === 'browser-install' || current?.browserPreference === 'pinned' ? 'pinned' : 'system', confirmDownload, onDownload: info => write({ status: 'downloading_verified_release', ...info }) });
+    if (runtime.status === 'browser_download_required') { write(runtime); return; }
+  }
+  write({ status: 'installing_candidate', permissions: ['copy verified runtime to user-owned versioned cache', 'configure unchanged owned agent skills/MCP'], trial: 'not_started' });
+  runtime ??= await installCandidate({ source, cache, manifestSha256 });
+  // Persist a quiet Notify default; repeat setup never changes existing policy.
+  if (consentUpdates) await setUpdatePolicy(cache, { mode: 'auto', consent: true });
+  else {
+    const { atomicJson } = await import('../lib/install.mjs');
+    await withInstallTransaction(cache, async () => atomicJson(cache, 'update-policy.json', await readUpdatePolicy(cache)));
+  }
+  const launcher = runtime.generation ? await ensureLauncher(cache, trust) : undefined;
+  const doctor = await run(runtime, ['doctor'], true);
+  const setup = await run(runtime, agent ? ['setup', '--agent', agent] : ['setup'], true);
+  const release = JSON.parse(await readFile(new URL('../release.json', import.meta.url), 'utf8'));
+  const result = { status: 'candidate_installed', version: runtime.productVersion, unchanged: runtime.unchanged, doctor, setup,
+    cache: offline ? 'verified_offline' : 'verified', hostDiscovered: 'unverified', updates: { mode: (await readUpdatePolicy(cache)).mode, delivery: 'candidate', launcher }, currentTask: {
+      command: process.execPath, args: [launcher ?? runtime.entry, 'task-session'], selection: 'verified_at_new_session_start', protocol: 'agent-task-session/1',
+      version: runtime.productVersion, digest: runtime.digest, generation: runtime.generation,
+      input: 'The installed version below is an offer; the ready frame binds the selected runtime at new-session start. Keep this host execution session and stdin open. First JSON line has project, scope, optional deadlineMs. Example for an originally authorized fix task: {"project":"/absolute/original/project","scope":{"userRequestedTask":true,"intent":"fix_verify","sourceOrigins":["http://127.0.0.1:3000"],"frontendOrigins":["http://127.0.0.1:3001"],"stateCardIds":[]},"deadlineMs":600000}. Replace project/origins/Card IDs from the original user task; installation grants no scope. Then JSON lines: operation tools; operation call with requestId/name/arguments; operation close.',
+      permissions: 'Use normal host approval for this exact runtime command when required. Installation does not grant browser, project or task permissions.',
+    }, published: !source && release.status === 'published' && release.version === runtime.productVersion };
+  write(result);
+  if (installNeedsAttention(result)) process.exitCode = 1;
+}
+void main().catch(error => {
+  const code = error instanceof Error && /^[A-Z0-9_]+$/.test(error.message) ? error.message : 'INSTALL_FAILED';
+  write({ status: 'blocked', code, nodePrerequisite: code.startsWith('NODE_') ? 'https://nodejs.org/en/download' : undefined });
+  process.exitCode = 1;
+});

package/lib/archive.mjs

@@ -0,0 +1,142 @@
+import { gzipSync, gunzipSync } from 'node:zlib';
+import { posix } from 'node:path';
+
+const MAX_BYTES = 512 * 1024 * 1024;
+export function validArchivePath(path, maximumLength = 1024) {
+  return typeof path === 'string' && path.length <= maximumLength && /^[A-Za-z0-9_.@ ()+-]+(?:\/[A-Za-z0-9_.@ ()+-]+)*$/.test(path)
+    && path.split('/').every(part => part.length <= 255 && part !== '.' && part !== '..' && !/[. ]$/.test(part) && !/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?: *\.| *$)/i.test(part));
+}
+function ustarParts(path) {
+  if (Buffer.byteLength(path) > 255) return undefined;
+  if (Buffer.byteLength(path) <= 100) return { name: path, prefix: '' };
+  let split = path.lastIndexOf('/');
+  while (split >= 0 && (Buffer.byteLength(path.slice(0, split)) > 155 || Buffer.byteLength(path.slice(split + 1)) > 100)) split = path.lastIndexOf('/', split - 1);
+  return split < 0 ? undefined : { prefix: path.slice(0, split), name: path.slice(split + 1) };
+}
+function pathHeader(path) {
+  const tail = ` path=${path}\n`; let size = Buffer.byteLength(tail) + 1;
+  while (String(size).length + Buffer.byteLength(tail) !== size) size = String(size).length + Buffer.byteLength(tail);
+  return Buffer.from(`${size}${tail}`);
+}
+function parsePathHeader(bytes) {
+  const space = bytes.indexOf(32), length = bytes.subarray(0, space).toString('utf8');
+  if (space < 1 || !/^[1-9][0-9]{0,3}$/.test(length) || Number(length) !== bytes.length || bytes.at(-1) !== 10 || bytes.subarray(space + 1, space + 6).toString('utf8') !== 'path=') throw Error('ARCHIVE_PAX');
+  const path = bytes.subarray(space + 6, -1).toString('utf8');
+  // One non-sticky path record for the verified browser closure only. No global,
+  // linkpath, size, uid, xattr, duplicate record or arbitrary metadata overrides.
+  if (!validArchivePath(path) || !/^bundled-browser\/browser\/chromium-[0-9]+\//.test(path) || ustarParts(path)) throw Error('ARCHIVE_PAX');
+  return path;
+}
+function requirePathHeaderSchema(files) {
+  const metadata = files.find(file => file.path === 'candidate.json');
+  try {
+    if (!metadata || !Buffer.isBuffer(metadata.bytes) || metadata.bytes.length > 1024 * 1024) throw Error();
+    const value = JSON.parse(metadata.bytes.toString('utf8'));
+    if (value.schemaVersion !== 'agent-runtime-candidate/1.2.0' || value.archiveFormat !== 'ustar+pax-path/1') throw Error();
+  } catch { throw Error('ARCHIVE_SCHEMA'); }
+}
+function field(header, offset, length) { return header.subarray(offset, offset + length).toString('utf8').replace(/\0.*$/s, ''); }
+function octal(header, offset, length) {
+  const value = field(header, offset, length).trim();
+  if (!/^[0-7]+$/.test(value)) throw Error('ARCHIVE_NUMBER');
+  const result = Number.parseInt(value, 8); if (!Number.isSafeInteger(result)) throw Error('ARCHIVE_NUMBER'); return result;
+}
+function checksum(header) { return header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0); }
+export function validateBundleLinks(files) {
+  const links = new Map(files.filter(file => file.kind === 'symlink').map(file => [file.path, file]));
+  const regular = files.filter(file => file.kind !== 'symlink').map(file => file.path);
+  function target(file) {
+    const prefix = file.path.split('/').slice(0, 3).join('/') + '/';
+    if (!/^bundled-browser\/browser\/chromium-[0-9]+\//.test(file.path) || typeof file.target !== 'string' || file.target.length > 100 || file.target.includes('\\') || posix.isAbsolute(file.target)) throw Error('ARCHIVE_LINK');
+    let concrete = false;
+    for (const part of file.target.split('/')) {
+      if (!part || ((part === '.' || part === '..') && concrete)) throw Error('ARCHIVE_LINK');
+      if (part !== '.' && part !== '..') concrete = true;
+    }
+    const resolved = posix.normalize(posix.join(posix.dirname(file.path), file.target));
+    if (!validArchivePath(resolved) || !resolved.startsWith(prefix)) throw Error('ARCHIVE_LINK');
+    return resolved;
+  }
+  function resolveLink(path, visited = new Set()) {
+    for (const [name, file] of links) if (path === name || path.startsWith(name + '/')) {
+      if (visited.has(name) || visited.size >= 64) throw Error('ARCHIVE_LINK');
+      return resolveLink(target(file) + path.slice(name.length), new Set([...visited, name]));
+    }
+    if (!regular.some(name => name === path || name.startsWith(path + '/'))) throw Error('ARCHIVE_LINK');
+    return path;
+  }
+  for (const file of links.values()) {
+    if (files.some(other => other.path.startsWith(file.path + '/'))) throw Error('ARCHIVE_LINK');
+    resolveLink(target(file), new Set([file.path]));
+  }
+}
+export function decodeRuntimeArchive(compressed, options = {}) {
+  if (!Buffer.isBuffer(compressed) || compressed.length > MAX_BYTES) throw Error('ARCHIVE_SIZE');
+  const tar = gunzipSync(compressed, { maxOutputLength: MAX_BYTES });
+  if (tar.length % 512) throw Error('ARCHIVE_TRUNCATED');
+  const files = [], seen = new Set(); let offset = 0, pendingPath, usesPathHeaders = false, headers = 0;
+  while (offset < tar.length) {
+    const header = tar.subarray(offset, offset + 512); offset += 512;
+    if (header.every(byte => byte === 0)) {
+      if (pendingPath !== undefined) throw Error('ARCHIVE_PAX');
+      if (!tar.subarray(offset).every(byte => byte === 0)) throw Error('ARCHIVE_TRAILING_DATA');
+      if (usesPathHeaders) requirePathHeaderSchema(files);
+      validateBundleLinks(files); return files;
+    }
+    if (++headers > 8192) throw Error('ARCHIVE_SIZE');
+    if (octal(header, 148, 8) !== checksum(header)) throw Error('ARCHIVE_CHECKSUM');
+    const isLink = header[156] === 50, isPathHeader = header[156] === 120;
+    if (header[156] !== 0 && header[156] !== 48 && !(isLink && options.allowBundleLinks === true) && !(isPathHeader && options.allowPathHeaders === true)) throw Error('ARCHIVE_TYPE');
+    const prefix = field(header, 345, 155), name = field(header, 0, 100), physicalPath = prefix ? prefix + '/' + name : name;
+    if (!validArchivePath(physicalPath, 255)) throw Error('ARCHIVE_PATH');
+    const size = octal(header, 124, 12), mode = octal(header, 100, 8);
+    if (size > MAX_BYTES || offset + Math.ceil(size / 512) * 512 > tar.length) throw Error('ARCHIVE_SIZE');
+    if (isPathHeader) {
+      if (pendingPath !== undefined || size < 1 || size > 2048) throw Error('ARCHIVE_PAX');
+      pendingPath = parsePathHeader(tar.subarray(offset, offset + size)); usesPathHeaders = true;
+      offset += Math.ceil(size / 512) * 512; continue;
+    }
+    const path = pendingPath ?? physicalPath; pendingPath = undefined;
+    if (seen.has(path.toLowerCase())) throw Error('ARCHIVE_PATH'); seen.add(path.toLowerCase());
+    if (files.length >= 4096) throw Error('ARCHIVE_SIZE');
+    if (isLink) { if (size !== 0) throw Error('ARCHIVE_LINK'); files.push({ path, kind: 'symlink', target: field(header, 157, 100) }); continue; }
+    if (size > MAX_BYTES || offset + size > tar.length || files.length >= 4096) throw Error('ARCHIVE_SIZE');
+    files.push({ path, bytes: Buffer.from(tar.subarray(offset, offset + size)), ...(mode & 0o111 ? { executable: true } : {}) });
+    offset += Math.ceil(size / 512) * 512;
+  }
+  throw Error('ARCHIVE_TERMINATOR_MISSING');
+}
+export function encodeRuntimeArchive(files, options = {}) {
+  validateBundleLinks(files);
+  const chunks = [], seen = new Set(); let total = 1024, usesPathHeaders = false;
+  const append = (header, data) => {
+    const padding = Buffer.alloc((512 - data.length % 512) % 512);
+    total += 512 + data.length + padding.length; if (total > MAX_BYTES) throw Error('ARCHIVE_SIZE');
+    chunks.push(header, data, padding);
+  };
+  const makeHeader = (path, type, data, file = {}) => {
+    const parts = ustarParts(path); if (!parts) throw Error('ARCHIVE_PATH');
+    const header = Buffer.alloc(512); header.write(parts.name, 0); header.write(parts.prefix, 345);
+    const number = (value, offset, length) => { const text = value.toString(8).padStart(length - 1, '0'); if (text.length >= length) throw Error('ARCHIVE_SIZE'); header.write(text + '\0', offset); };
+    number(file.executable ? 0o755 : 0o644, 100, 8); number(0, 108, 8); number(0, 116, 8); number(data.length, 124, 12); number(0, 136, 12);
+    header[156] = type; if (type === 50) header.write(file.target, 157);
+    header.write('ustar\0', 257); header.write('00', 263);
+    header.write(checksum(header).toString(8).padStart(6, '0') + '\0 ', 148);
+    return header;
+  };
+  for (const file of files) {
+    if (!validArchivePath(file.path) || seen.has(file.path.toLowerCase())) throw Error('ARCHIVE_PATH'); seen.add(file.path.toLowerCase());
+    const isLink = file.kind === 'symlink', data = isLink ? Buffer.alloc(0) : file.bytes;
+    if (!Buffer.isBuffer(data) || files.length > 4096) throw Error('ARCHIVE_SIZE');
+    let physicalPath = file.path;
+    if (!ustarParts(file.path)) {
+      if (options.allowPathHeaders !== true) throw Error('ARCHIVE_PATH');
+      const record = pathHeader(file.path); parsePathHeader(record); usesPathHeaders = true;
+      append(makeHeader('PaxHeaders/browser', 120, record), record);
+      physicalPath = 'Payload/browser';
+    }
+    append(makeHeader(physicalPath, isLink ? 50 : 48, data, file), data);
+  }
+  if (usesPathHeaders) requirePathHeaderSchema(files);
+  return gzipSync(Buffer.concat([...chunks, Buffer.alloc(1024)]));
+}

package/lib/cli-output.mjs

@@ -0,0 +1,159 @@
+import { homedir } from 'node:os';
+
+const agents = { codex: 'Codex', claude: 'Claude Code', cursor: 'Cursor' };
+const browsers = { chrome: 'Google Chrome', msedge: 'Microsoft Edge', chromium: 'Chromium' };
+// Runtime/config strings are data, including when printed to a terminal.
+export const terminalText = value => String(value ?? '').replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, '').slice(0, 4096);
+const size = bytes => Number.isSafeInteger(bytes) && bytes > 0 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : 'size unavailable';
+const version = value => /^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(value ?? '') ? value : 'unknown version';
+const homePath = value => {
+  const text = terminalText(value), home = homedir();
+  return text.startsWith(home + '/') || text.startsWith(home + '\\') ? '~' + text.slice(home.length) : text;
+};
+export function installNeedsAttention(value) {
+  return value.setup?.status !== 'installed' || value.doctor?.browser?.status !== 'found';
+}
+
+const recovery = {
+  INVALID_ARGUMENTS: ['That command is not recognised.', 'Run npx stateport --help to see the available commands.'],
+  PLATFORM_UNSUPPORTED: ['This platform is not supported yet.', 'Use Windows x64, macOS Apple Silicon, or Linux x64.'],
+  NODE_24_LTS_CANDIDATE_REQUIRED: ['StatePort needs Node.js 24.', ['Install Node.js 24: https://nodejs.org/en/download', 'Run npx stateport again.']],
+  RUNTIME_NOT_INSTALLED: ['StatePort is not installed yet.', 'Run npx stateport to install it.'],
+  OFFLINE_CACHE_UNAVAILABLE: ['No verified offline installation was found.', 'Connect to the internet and run npx stateport once.'],
+  PUBLIC_RUNTIME_RELEASE_UNPUBLISHED: ['This build has no public runtime configured.', 'Use the official npm package: npx stateport.'],
+  PIN_RELEASE_REQUIRED: ['This installation is pinned to an exact version.', 'To allow changes, run npx stateport updates notify --release-pin.'],
+  UPDATE_INCOMPATIBLE: ['This update needs a reviewed setup.', 'Run npx stateport to review the new installation; restart your coding agent afterwards.'],
+  LAUNCHER_REPAIR_REQUIRED: ['The StatePort launcher needs repair.', 'Run npx stateport repair-launcher --confirm. Changed launcher files are backed up.'],
+  RECOVERY_REQUIRED: ['An interrupted setup needs attention.', 'Keep the existing files. Review npx stateport doctor --json before trying again.'],
+  INSTALL_BUSY: ['Another StatePort installation is in progress.', 'Let it finish, then run this command again.'],
+  INSTALL_LOCKED: ['Another StatePort installation may still be running.', 'Let it finish before retrying. Do not delete an active installation lock.'],
+  INSTALL_BUSY_OR_RECOVERY_REQUIRED: ['Another setup may be running or was interrupted.', 'Let any active setup finish. Keep the lock and existing files if recovery is needed.'],
+  ROLLBACK_UNAVAILABLE: ['No previous runtime is available to restore.', 'Keep the current installation, or run npx stateport to review the published version.'],
+  UPDATE_ROLLBACK_UNAVAILABLE: ['The previous runtime could not be verified.', 'Keep the current installation. Review npx stateport doctor --json.'],
+  RELEASE_HTTP: ['The runtime download could not be completed.', 'Check your connection and try npx stateport again.'],
+  RELEASE_REDIRECTS: ['The download destination could not be verified.', 'Try again later using npx stateport.'],
+};
+
+export function createCliOutput({ json = false, stream = process.stdout, env = process.env, columns = stream.columns ?? 80 } = {}) {
+  const color = Boolean(stream.isTTY && env.TERM !== 'dumb' && env.NO_COLOR === undefined);
+  const paint = (code, text) => color ? `\x1b[${code}m${text}\x1b[0m` : text;
+  const width = Math.max(24, Math.min(80, Number(columns) || 80)) - 4;
+  let started = false;
+  const line = (text = '', style) => {
+    if (!text) { stream.write('\n'); return; }
+    // Wrap before colouring; text is printable, never executable terminal markup.
+    let remaining = terminalText(text);
+    while (remaining.length > width) {
+      let end = remaining.lastIndexOf(' ', width);
+      if (end < Math.floor(width / 3)) end = width;
+      const part = remaining.slice(0, end); stream.write('  ' + (style ? paint(style, part) : part) + '\n');
+      remaining = remaining.slice(end).trimStart();
+    }
+    stream.write('  ' + (style ? paint(style, remaining) : remaining) + '\n');
+  };
+  const heading = text => { line(); line(text, '1'); };
+  // Keep commands on one logical line; terminal soft wrapping stays copyable.
+  const command = text => stream.write('  ' + paint('36', terminalText(text)) + '\n');
+  const check = (ok, label, detail) => line(`${ok ? '✓' : '!'} ${label.padEnd(13)} ${terminalText(detail)}`, ok ? '32' : '33');
+  const next = (steps, title = 'Next') => { heading(title); steps.forEach((step, index) => line(`${index + 1}. ${step}`)); };
+  const begin = () => { if (json || started) return; started = true; line(); line('StatePort', '1;31'); line('Reproduce a bug. Verify the fix.', '2'); };
+  const footer = () => { line(); line('Capture is free. A Developer trial starts only when you choose it.', '2'); line(); };
+  function installation(value, title) {
+    const setup = value.setup ?? {}, result = setup.result ?? {}, agent = agents[setup.agent] ?? 'Coding agent';
+    const configured = setup.status === 'installed', browser = value.doctor?.browser;
+    const attention = installNeedsAttention(value);
+    heading(title ?? (attention ? 'Installed — setup needs attention' : value.unchanged ? 'Already installed' : 'Installed'));
+    check(true, 'Runtime', version(value.version) + (value.cache === 'verified_offline' ? ' · verified offline cache' : ' · verified'));
+    check(browser?.status === 'found', 'Browser', browser?.status === 'found' ? `${browsers[browser.channel] ?? 'System browser'} · found` : 'not found');
+    check(configured, 'Skills', configured ? `${version(result.version)} · ${result.unchanged ? 'up to date' : 'installed'}` : result.reason === 'CONFLICT' ? 'not updated · existing installation' : 'not configured');
+    check(configured, setup.agent ? `${agent} MCP` : 'Agent', configured ? 'configured' : setup.agent ? 'not configured' : 'not selected');
+    if (result.reason === 'CONFLICT') {
+      heading(`${agent} connection needs attention`);
+      line('Existing StatePort settings or skills conflict with this installation.');
+      line('Your existing setup has been preserved.');
+      if (setup.configuration?.path) line(`Review: ${homePath(setup.configuration.path)}`);
+      next([`Review the existing StatePort installation in ${agent}.`, 'To switch, remove the old setup using its original installer.', 'After removal, run npx stateport again.']);
+    } else if (result.reason === 'HOST_MISSING') {
+      next([`Install or open ${agent} in this user account.`, `Run npx stateport install --agent ${setup.agent} again.`]);
+    } else if (setup.status === 'guided_setup_required') {
+      heading('Choose your coding agent');
+      if (setup.reason === 'COPILOT_ADAPTER_REQUIRED') line('Copilot needs its documented MCP/skills setup.');
+      else line('No supported coding agent was detected in this user account.');
+      line('Run the command for the agent you use:');
+      for (const [key, name] of Object.entries(agents)) { line(name); command(`npx stateport install --agent ${key}`); }
+    } else if (!configured) {
+      heading(`${agent} setup could not finish`);
+      line(`Reason: ${terminalText(result.reason ?? 'SETUP_UNAVAILABLE')}`);
+      if (setup.configuration?.path) line(`Review: ${homePath(setup.configuration.path)}`);
+      next(['Review npx stateport doctor --json for diagnostics.', 'Resolve the reported issue, then run npx stateport again.']);
+    } else if (browser?.status !== 'found') {
+      next(['Install Google Chrome or Microsoft Edge on Windows.', 'Or run npx stateport browser-install to review the optional Chromium download.']);
+    } else {
+      next([setup.agent === 'cursor' ? 'Open Cursor and start a new chat.' : `Restart ${agent} and open a new chat.`, 'Give your agent the page URL and steps. For example:'], `Next in ${agent}`);
+      line(); line('“Use StatePort to reproduce this bug: <URL and steps>.”', '36');
+      line(); line('Your agent will ask for any permissions it needs.');
+      if (setup.agent === 'cursor') line('If StatePort is not listed, restart Cursor to reload its tools.');
+    }
+    footer();
+  }
+  function doctor(value) {
+    heading('Installation check'); check(Boolean(value.version), 'Runtime', version(value.version));
+    check(value.browser?.status === 'found', 'Browser', value.browser?.status === 'found' ? `${browsers[value.browser.channel] ?? 'System browser'} · found` : 'not found');
+    if (value.vault) check(['roundtrip_passed', 'available'].includes(value.vault.status), 'OS key store', terminalText(value.vault.status));
+    line(); line('For full diagnostics: npx stateport doctor --json'); line();
+  }
+  const emit = (value, kind = value.status) => {
+    if (json) { stream.write(JSON.stringify(value) + '\n'); return; }
+    begin();
+    if (kind === 'candidate_installed') { installation(value); return; }
+    if (kind === 'doctor') { doctor(value); return; }
+    if (kind === 'downloading_verified_release') { line(); line(`↓ Downloading ${value.browser === 'pinned_chromium' ? 'optional Chromium runtime' : 'StatePort runtime'} · ${size(value.bytes)}`); return; }
+    if (kind === 'installing_candidate') { line('Checking runtime and setting up your coding agent…', '2'); return; }
+    if (kind === 'browser_download_required') {
+      heading('Optional Chromium download'); line(`Download: ${size(value.bytes)}`);
+      line('Your current browser selection is unchanged.');
+      next(['Review the download size, then confirm its exact SHA-256:']);
+      command(`npx stateport browser-install --confirm-download ${terminalText(value.sha256)}`); line(); return;
+    }
+    if (kind === 'blocked') {
+      const code = terminalText(value.code);
+      const fallback = /INTEGRITY|SIGNATURE|RELEASE_KEY|MANIFEST|ARCHIVE|INVENTORY/.test(code)
+        ? ['The runtime could not be verified.', 'Try again later using the official npx stateport command.']
+        : ['StatePort could not finish this command.', 'Run npx stateport doctor --json to inspect the installation.'];
+      const [title, step] = recovery[code] ?? fallback;
+      heading(title); next(Array.isArray(step) ? step : [step]); line(); line(`Error: ${code === 'NODE_24_LTS_CANDIDATE_REQUIRED' ? 'NODE_VERSION_UNSUPPORTED' : code}`, '2'); line(); return;
+    }
+    if (kind === 'uninstalled') { heading('StatePort connection removed'); check(true, 'User data', 'Cards and protected data preserved'); line('Verified runtime cache is retained for active processes.'); next(['Run npx stateport whenever you want to connect again.']); line(); return; }
+    if (kind === 'conflict') { heading('Uninstall stopped — existing setup needs review'); line('Edited or foreign settings were preserved.'); next(['Review the existing StatePort setup with its original installer.']); line(); return; }
+    if (kind === 'launcher_repaired') { heading('Launcher repaired'); line('Changed launcher files were backed up. User data is preserved.'); next(['Restart your coding agent.']); line(); return; }
+    if (kind === 'rolled_back') { installation({ ...value, version: value.runtime }, installNeedsAttention(value) ? 'Runtime restored — setup needs attention' : 'Previous runtime restored'); return; }
+    if (kind === 'update_checked') {
+      heading('Update check complete'); line(`Selected runtime: ${version(value.selected?.version)}`); line(updateMessage(value.outcome?.status));
+      if (value.outcome?.status === 'held') next(['Review npx stateport updates status --json for the exact hold reason.']);
+      else if (value.outcome?.status === 'pending_next_session') next(['Start a new agent session to use the selected runtime.']);
+      line(); return;
+    }
+    if (kind === 'updates') {
+      heading('Updates');
+      if (value.mode) line(`Mode: ${({ notify: 'Notify · ask before updating', auto: 'Auto · compatible updates only', pinned: 'Pinned · exact version' })[value.mode] ?? terminalText(value.mode)}`);
+      if (value.channel) line(`Channel: ${terminalText(value.channel)}`);
+      if (value.selected?.version) line(`Selected: ${version(value.selected.version)}`);
+      if (value.pending?.version) line(`Prepared: ${version(value.pending.version)} · for a new session`);
+      if (value.hold) line(`Attention: ${terminalText(value.hold)}`);
+      if (value.status) line(updateMessage(value.status));
+      line(); line('Details: npx stateport updates status --json'); line(); return;
+    }
+    heading('Command complete'); line('Details are available with --json.'); line();
+  };
+  return { begin, emit, help: () => {
+    if (json) { emit({ name: 'stateport', commands: ['install', 'doctor', 'update', 'updates', 'browser-install', 'rollback', 'uninstall', 'repair-launcher'], options: ['--json', '--help', '--version'] }); return; }
+    begin(); heading('Get started'); line('npx stateport'); line('Install StatePort and connect your coding agent.');
+    heading('Manage your installation');
+    for (const [command, description] of [['install --agent cursor', 'Choose Cursor, codex or claude'], ['doctor', 'Check runtime and browser'], ['update', 'Check for an update'], ['updates status', 'Show update policy'], ['browser-install', 'Review optional Chromium download'], ['rollback', 'Restore the retained previous runtime'], ['uninstall', 'Remove unchanged owned agent setup'], ['repair-launcher --confirm', 'Repair the launcher; keep a backup']]) line(`npx stateport ${command}  — ${description}`);
+    heading('Options'); line('--json     Machine-readable output for agents and scripts'); line('--offline  Use a verified installation without downloading'); line('--version  Show installer version'); line();
+  } };
+}
+
+function updateMessage(status) {
+  return ({ not_configured: 'No public update channel is configured for this build.', unavailable: 'The update check is unavailable. Existing installed work can continue.', not_installed: 'Run npx stateport first.', pinned: 'An exact version is pinned.', throttled: 'An update check ran recently.', up_to_date: 'You are up to date.', staged: 'An update is prepared for a new session.', pending_next_session: 'An update is prepared for a new session.', held: 'The update was not applied. Your current runtime is kept.', checked: 'Check complete. No update was selected.', update_available: 'An update is available for review.', retry_allowed: 'Retry is enabled for the selected version.', incompatible: 'This update needs reviewed setup.' })[status] ?? terminalText(status ?? 'No change');
+}

package/lib/controls.mjs

@@ -0,0 +1,23 @@
+import { readInstalled } from './install.mjs';
+import { readUpdatePolicy, setUpdatePolicy, hex } from './update-policy.mjs';
+import { updateStatus, checkForUpdates, retryQuarantine } from './updates.mjs';
+
+/** Shared transparent-bootstrap and verified installed-launcher CLI surface. */
+export async function updateControl(cache, trust, args, running) {
+  const [action = 'status', ...extra] = args;
+  if (action === 'status' && !extra.length) return updateStatus(cache, running);
+  if (action === 'check' && !extra.length) return checkForUpdates(cache, trust, { force: true });
+  if (action === 'retry' && extra.length === 1 && hex(extra[0])) return retryQuarantine(cache, extra[0]);
+  if (action === 'auto' && extra.length === 1 && extra[0] === '--consent') return setUpdatePolicy(cache, { mode: 'auto', consent: true });
+  if (action === 'notify' && (!extra.length || (extra.length === 1 && extra[0] === '--release-pin'))) return setUpdatePolicy(cache, { mode: 'notify', releasePin: extra[0] === '--release-pin' });
+  if (action === 'pin' && extra.length === 1 && hex(extra[0])) {
+    const runtime = await readInstalled(cache, extra[0]);
+    return setUpdatePolicy(cache, { mode: 'pinned', pin: { version: runtime.productVersion, digest: runtime.digest } });
+  }
+  if (action === 'channel' && extra.length === 2 && ['stable', 'beta', 'rc'].includes(extra[0]) && extra[1] === '--confirm') {
+    const policy = await readUpdatePolicy(cache);
+    if (trust.status === 'published' && !trust.channels?.[extra[0]] && trust.channel !== extra[0]) throw Error('UPDATE_CHANNEL_UNAVAILABLE');
+    return setUpdatePolicy(cache, { mode: policy.mode, channel: extra[0], pin: policy.pin });
+  }
+  throw Error('INVALID_ARGUMENTS');
+}