stateport 0.0.0-stage → 1.0.0-rc.5

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,15 @@
-# 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

package/bin/stateport.mjs

@@ -0,0 +1,133 @@
+#!/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';
+
+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');
+}
+const write = value => process.stdout.write(JSON.stringify(value) + '\n');
+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() {
+  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 args = process.argv.slice(2);
+  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']);
+  const command = commands.has(args[0]) ? args.shift() : 'install';
+  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)); 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 (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);
+    write({ status: 'rolled_back', runtime: runtime.productVersion, setup: await run(runtime, ['setup'], true), hostDiscovered: 'unverified' }); 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');
+  } 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);
+  write({ 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: false });
+}
+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/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');
+}

package/lib/install.mjs

@@ -0,0 +1,233 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, readlink, rename, rm, writeFile, symlink } from 'node:fs/promises';
+import { createHash, randomBytes } from 'node:crypto';
+import { dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+import { validArchivePath, validateBundleLinks } from './archive.mjs';
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const hex = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const maximumPayloadBytes = 512 * 1024 * 1024;
+const missing = error => error?.code === 'ENOENT';
+
+export async function safePath(path) {
+  const absolute = resolve(path), root = parse(absolute).root;
+  let cursor = root;
+  for (const part of relative(root, absolute).split(/[\\/]/)) {
+    if (!part) continue; cursor = join(cursor, part);
+    try { const stat = await lstat(cursor); if (stat.isSymbolicLink()) throw Error('UNSAFE_PATH'); }
+    catch (error) { if (missing(error)) break; throw error; }
+  }
+}
+export async function directory(path) {
+  await safePath(path); await mkdir(path, { recursive: true, mode: 0o700 }); await safePath(path);
+  if (!(await lstat(path)).isDirectory()) throw Error('UNSAFE_PATH');
+}
+export async function bytes(path, maximumBytes) {
+  await safePath(path);
+  const before = await lstat(path);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > maximumBytes) throw Error('UNSAFE_PATH');
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino || stat.size > maximumBytes) throw Error('UNSAFE_PATH');
+    const value = await handle.readFile();
+    if (value.length > maximumBytes) throw Error('PAYLOAD_SIZE');
+    return value;
+  } finally { await handle.close(); }
+}
+function manifest(value) {
+  if (!value || !['agent-runtime-candidate/1.0.0','agent-runtime-candidate/1.1.0','agent-runtime-candidate/1.2.0'].includes(value.schemaVersion) || value.entry !== 'main.cjs' || value.nodeCandidate !== '24.x' || typeof value.productVersion !== 'string' || value.productVersion.length > 128 || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.productVersion)) throw Error('MANIFEST_INVALID');
+  if (value.schemaVersion === 'agent-runtime-candidate/1.2.0' && value.archiveFormat !== 'ustar+pax-path/1') throw Error('MANIFEST_INVALID');
+  if (value.platform !== process.platform || value.arch !== process.arch) throw Error('PLATFORM_MISMATCH');
+  if (!Array.isArray(value.files) || value.files.length < 1 || value.files.length > 4096) throw Error('MANIFEST_INVALID');
+  const names = new Set(); let total = 0;
+  for (const file of value.files) {
+    if (!validArchivePath(file.path, value.schemaVersion === 'agent-runtime-candidate/1.2.0' ? 1024 : 255) || file.path === 'candidate.json') throw Error('MANIFEST_PATH');
+    if (file.executable !== undefined && typeof file.executable !== 'boolean') throw Error('MANIFEST_INVALID');
+    const lower = file.path.toLowerCase();
+    if (names.has(lower)) throw Error('MANIFEST_PATH'); names.add(lower);
+    if (file.kind === 'symlink') {
+      if (value.schemaVersion === 'agent-runtime-candidate/1.0.0' || process.platform === 'win32') throw Error('BUNDLE_LINK_UNSUPPORTED');
+      continue;
+    }
+    if (file.kind !== undefined) throw Error('MANIFEST_INVALID');
+    if (!Number.isSafeInteger(file.bytes) || file.bytes < 0 || !hex(file.sha256)) throw Error('MANIFEST_INVALID');
+    total += file.bytes; if (!Number.isSafeInteger(total) || total > maximumPayloadBytes) throw Error('PAYLOAD_SIZE');
+  }
+  if (!names.has('main.cjs')) throw Error('MANIFEST_INVALID');
+  validateBundleLinks(value.files);
+  return value;
+}
+async function loadManifest(source, expectedDigest) {
+  if (!hex(expectedDigest)) throw Error('MANIFEST_INTEGRITY');
+  const raw = await bytes(join(source, 'candidate.json'), 1024 * 1024);
+  if (digest(raw) !== expectedDigest) throw Error('MANIFEST_INTEGRITY');
+  return { raw, value: manifest(JSON.parse(raw.toString('utf8'))) };
+}
+async function verifyPayload(root, value) {
+  for (const file of value.files) {
+    if (file.kind === 'symlink') {
+      const path = join(root, file.path); await safePath(dirname(path));
+      if (!(await lstat(path)).isSymbolicLink() || await readlink(path) !== file.target) throw Error('PAYLOAD_INTEGRITY');
+      continue;
+    }
+    const data = await bytes(join(root, file.path), file.bytes);
+    if (data.length !== file.bytes || digest(data) !== file.sha256) throw Error('PAYLOAD_INTEGRITY');
+  }
+  const expected = new Set(['candidate.json', ...value.files.map(file => file.path)]);
+  async function walk(path) {
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      const child = join(path, entry.name);
+      if (entry.isSymbolicLink()) {
+        const name = relative(root, child).split('\\').join('/');
+        if (!value.files.some(file => file.path === name && file.kind === 'symlink') || !expected.delete(name)) throw Error('UNSAFE_PATH');
+        continue;
+      }
+      if (entry.isDirectory()) await walk(child);
+      else if (!entry.isFile() || !expected.delete(relative(root, child).split('\\').join('/'))) throw Error('PAYLOAD_CONFLICT');
+    }
+  }
+  await walk(root); if (expected.size) throw Error('PAYLOAD_INTEGRITY');
+}
+async function withLock(cache, work) {
+  if (!isAbsolute(cache)) throw Error('UNSAFE_PATH');
+  await directory(cache);
+  const lock = join(cache, '.install.lock');
+  await safePath(lock);
+  try { await mkdir(lock, { mode: 0o700 }); } catch { throw Error('INSTALL_BUSY_OR_RECOVERY_REQUIRED'); }
+  try { return await work(); }
+  finally { await safePath(lock); await rm(lock, { recursive: true }); }
+}
+async function pointer(cache) {
+  let raw;
+  try { raw = await bytes(join(cache, 'current.json'), 4096); } catch (error) { if (missing(error)) return undefined; throw error; }
+  const value = JSON.parse(raw.toString('utf8'));
+  if (value.schemaVersion !== 'agent-install-pointer/1' || !hex(value.current) || (value.previous !== null && !hex(value.previous)) || Object.keys(value).sort().join(',') !== 'current,previous,schemaVersion') throw Error('INSTALL_CONFLICT');
+  return { value, raw };
+}
+async function switchPointer(cache, value, before) {
+  const current = await pointer(cache);
+  if (current?.raw.toString('utf8') !== before?.raw.toString('utf8')) throw Error('INSTALL_CONFLICT');
+  const temporary = join(cache, `.current-${randomBytes(16).toString('hex')}`);
+  try {
+    await writeFile(temporary, JSON.stringify(value) + '\n', { mode: 0o600, flag: 'wx', flush: true });
+    await safePath(join(cache, 'current.json')); await rename(temporary, join(cache, 'current.json')); await syncDirectory(cache);
+  }
+  finally { await safePath(temporary); await rm(temporary, { force: true }); }
+}
+// Directory sync is meaningful on supported POSIX filesystems. Windows does not
+// expose directory fsync through this API; flushed files + rename still retain
+// immutable payloads. Native crash/power-loss qualification stays independent.
+async function syncDirectory(path) {
+  if (process.platform === 'win32') return;
+  const handle = await open(path, constants.O_RDONLY);
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+async function syncTree(root) {
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    if (entry.isDirectory()) await syncTree(join(root, entry.name));
+  }
+  await syncDirectory(root);
+}
+export async function atomicJson(cache, name, value) {
+  if (!/^[a-z][a-z0-9-]*\.json$/.test(name)) throw Error('UNSAFE_PATH');
+  await directory(cache);
+  const target = join(cache, name), temporary = join(cache, `.write-${randomBytes(16).toString('hex')}`);
+  await safePath(target);
+  try {
+    await writeFile(temporary, JSON.stringify(value) + '\n', { mode: 0o600, flag: 'wx', flush: true });
+    await safePath(target); await rename(temporary, target); await syncDirectory(cache);
+  } finally { await safePath(temporary); await rm(temporary, { force: true }); }
+}
+export async function readInstalled(cache, manifestSha256) {
+  if (!hex(manifestSha256)) throw Error('MANIFEST_INTEGRITY');
+  const runtimeRoot = join(cache, 'versions', manifestSha256);
+  const loaded = await loadManifest(runtimeRoot, manifestSha256);
+  await verifyPayload(runtimeRoot, loaded.value);
+  return { digest: manifestSha256, runtimeRoot, entry: join(runtimeRoot, 'main.cjs'), productVersion: loaded.value.productVersion, browserPreference: loaded.value.browserPreference ?? 'system', generation: loaded.value.generation };
+}
+export async function readCurrent(cache) {
+  const current = await pointer(cache); if (!current) return undefined;
+  return readInstalled(cache, current.value.current);
+}
+export async function readPrevious(cache) {
+  const current = await pointer(cache);
+  return current?.value.previous ? readInstalled(cache, current.value.previous) : undefined;
+}
+async function stageVerified({ source, cache, manifestSha256 }) {
+  source = resolve(source);
+  const loaded = await loadManifest(source, manifestSha256);
+  await verifyPayload(source, loaded.value);
+  const versions = join(cache, 'versions'); await directory(versions);
+  const destination = join(versions, manifestSha256);
+  let exists = true;
+  try { await lstat(destination); } catch (error) { if (missing(error)) exists = false; else throw error; }
+  if (exists) { const saved = await loadManifest(destination, manifestSha256); await verifyPayload(destination, saved.value); }
+  else {
+    const stage = join(versions, `.stage-${randomBytes(16).toString('hex')}`); await directory(stage);
+    try {
+      for (const file of loaded.value.files.filter(file => file.kind !== 'symlink')) {
+        const data = await bytes(join(source, file.path), file.bytes);
+        if (data.length !== file.bytes || digest(data) !== file.sha256) throw Error('PAYLOAD_INTEGRITY');
+        const target = join(stage, file.path); await directory(dirname(target));
+        await writeFile(target, data, { flag: 'wx', mode: file.executable ? 0o700 : 0o600, flush: true });
+      }
+      for (const file of loaded.value.files.filter(file => file.kind === 'symlink')) {
+        const target = join(stage, file.path); await directory(dirname(target)); await symlink(file.target, target);
+      }
+      await writeFile(join(stage, 'candidate.json'), loaded.raw, { flag: 'wx', mode: 0o600, flush: true });
+      await verifyPayload(stage, loaded.value); await syncTree(stage);
+      await safePath(destination); await rename(stage, destination); await syncDirectory(versions);
+    } finally { await safePath(stage); await rm(stage, { recursive: true, force: true }); }
+  }
+  return readInstalled(cache, manifestSha256);
+}
+async function activateVerified(cache, manifestSha256) {
+  const installed = await readInstalled(cache, manifestSha256), before = await pointer(cache);
+  if (before?.value.current === manifestSha256) return { ...installed, unchanged: true };
+  await switchPointer(cache, { schemaVersion: 'agent-install-pointer/1', current: manifestSha256, previous: before?.value.current ?? null }, before);
+  return { ...installed, unchanged: false };
+}
+/** The sole mutation lock. The callback may stage/activate without reentrant locks. */
+export async function withInstallTransaction(cache, work) {
+  return withLock(cache, () => work({
+    stage: options => stageVerified({ ...options, cache }),
+    activate: manifestSha256 => activateVerified(cache, manifestSha256),
+    current: () => readCurrent(cache),
+    installed: manifestSha256 => readInstalled(cache, manifestSha256),
+    previous: async () => { const current = await pointer(cache); return current?.value.previous ? readInstalled(cache, current.value.previous) : undefined; },
+    uninstall: () => uninstallVerified(cache),
+    write: (name, value) => atomicJson(cache, name, value),
+  }));
+}
+export async function stageCandidate(options) {
+  return withInstallTransaction(options.cache, transaction => transaction.stage(options));
+}
+export async function activateCandidate(cache, manifestSha256) {
+  return withInstallTransaction(cache, transaction => transaction.activate(manifestSha256));
+}
+export async function installCandidate(options) {
+  return withInstallTransaction(options.cache, async transaction => {
+    await transaction.stage(options);
+    return transaction.activate(options.manifestSha256);
+  });
+}
+export async function rollback(cache) {
+  return withLock(cache, async () => {
+    const before = await pointer(cache);
+    if (!before?.value.previous) throw Error('ROLLBACK_UNAVAILABLE');
+    const loaded = await loadManifest(join(cache, 'versions', before.value.previous), before.value.previous);
+    await verifyPayload(join(cache, 'versions', before.value.previous), loaded.value);
+    await switchPointer(cache, { schemaVersion: 'agent-install-pointer/1', current: before.value.previous, previous: before.value.current }, before);
+    return readCurrent(cache);
+  });
+}
+export async function uninstallPointer(cache) {
+  return withLock(cache, () => uninstallVerified(cache));
+}
+async function uninstallVerified(cache) {
+  const current = await readCurrent(cache);
+  if (current) { await rm(join(cache, 'current.json')); await syncDirectory(cache); }
+  // Exact runtime versions are retained: active processes and rollback never lose their code.
+  return { status: 'uninstalled', retainedRuntimeCache: true, userData: 'preserved' };
+}

package/lib/launcher.mjs

@@ -0,0 +1,55 @@
+import { readFile, writeFile, rename, rm, mkdir, lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { bytes, directory, safePath, withInstallTransaction } from './install.mjs';
+
+const loader = `// StatePort loader contract 1. Repair explicitly through the official bootstrap.
+(async () => {
+  const { join } = require('node:path');
+  const { pathToFileURL } = require('node:url');
+  const { readCurrent, bytes } = await import('./lib/install.mjs');
+  const cache = join(__dirname, '..');
+  const runtime = await readCurrent(cache);
+  if (!runtime) throw Error('RUNTIME_NOT_INSTALLED');
+  if (!runtime.generation || runtime.generation.launcher !== 1) throw Error('LAUNCHER_REPAIR_REQUIRED');
+  const trust = JSON.parse((await bytes(join(__dirname, 'release.json'), 65536)).toString('utf8'));
+  const { launchSession } = await import(pathToFileURL(join(runtime.runtimeRoot, 'distribution', 'session.mjs')).href);
+  await launchSession({ cache, runtime, trust, args: process.argv.slice(2) });
+})().catch(() => { process.stderr.write('STATEPORT_LAUNCHER_UNAVAILABLE\\n'); process.exitCode = 1; });
+`;
+/** Install once from trusted bootstrap bytes. Future generation updates never
+ * rewrite this loader/npm cache; changed loader/key requires explicit repair. */
+export async function ensureLauncher(cache, trust, { repair = false } = {}) {
+  return withInstallTransaction(cache, async () => {
+    const target = join(cache, 'launcher'); await safePath(target);
+    const expected = new Map([['main.cjs', Buffer.from(loader)], ['release.json', Buffer.from(JSON.stringify(trust) + '\n')]]);
+    for (const name of ['install.mjs', 'archive.mjs']) expected.set(`lib/${name}`, await readFile(new URL(name, import.meta.url)));
+    try {
+      for (const [name, value] of expected) if (!(await bytes(join(target, name), value.length)).equals(value)) throw Error('LAUNCHER_REPAIR_REQUIRED');
+      return join(target, 'main.cjs');
+    } catch (error) { if (!repair && error?.code !== 'ENOENT') throw Error('LAUNCHER_REPAIR_REQUIRED'); }
+    // A partially existing/foreign loader is a conflict, not a repair request.
+    let backup;
+    try {
+      const existing = await lstat(target);
+      if (!repair || !existing.isDirectory() || existing.isSymbolicLink()) throw Error('LAUNCHER_REPAIR_REQUIRED');
+      backup = join(cache, `.launcher-backup-${randomBytes(16).toString('hex')}`);
+    } catch (error) { if (error?.code !== 'ENOENT') throw error; }
+    const stage = join(cache, `.launcher-${randomBytes(16).toString('hex')}`); await directory(stage);
+    try {
+      for (const [name, value] of expected) {
+        const path = join(stage, name); await mkdir(join(path, '..'), { recursive: true, mode: 0o700 });
+        await writeFile(path, value, { mode: 0o600, flag: 'wx', flush: true });
+      }
+      await safePath(target);
+      if (backup) await rename(target, backup);
+      await rename(stage, target);
+    } catch (error) {
+      if (backup) {
+        try { await lstat(target); } catch (missing) { if (missing?.code === 'ENOENT') await rename(backup, target); }
+      }
+      throw error;
+    } finally { await rm(stage, { recursive: true, force: true }); }
+    return join(target, 'main.cjs');
+  });
+}

package/lib/release.mjs

@@ -0,0 +1,154 @@
+import { createHash, verify } from 'node:crypto';
+import { mkdir, mkdtemp, rm, writeFile, symlink, realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { decodeRuntimeArchive } from './archive.mjs';
+import { installCandidate } from './install.mjs';
+
+const sha = bytes => createHash('sha256').update(bytes).digest('hex');
+const hex = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+export function trustedUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'https:' || url.username || url.password || !['github.com', 'objects.githubusercontent.com', 'release-assets.githubusercontent.com'].includes(url.hostname)) throw Error('RELEASE_URL');
+  if (url.hostname === 'github.com' && !url.pathname.startsWith('/StatePort-Dev/stateport-releases/releases/download/')) throw Error('RELEASE_URL');
+  return url.href;
+}
+function trustedMetadataUrl(value, channel) {
+  if (!['stable', 'beta', 'rc'].includes(channel)) throw Error('RELEASE_URL');
+  const url = new URL(value);
+  if (url.hostname !== 'raw.githubusercontent.com') return trustedUrl(value);
+  // Only the signed channel document may be mutable. Runtime archives still
+  // use immutable release assets and never inherit this metadata exception.
+  if (url.protocol !== 'https:' || url.username || url.password || url.port || url.search || url.hash
+    || url.pathname !== `/StatePort-Dev/stateport-releases/main/channels/${channel}.json`) throw Error('RELEASE_URL');
+  return url.href;
+}
+function signedDocument(envelope, config, pinned = true) {
+  if (config.status !== 'published') throw Error('RELEASE_UNPUBLISHED');
+  if (!config.publicKey || envelope?.keyId !== config.keyId) throw Error('RELEASE_KEY');
+  if (typeof envelope.payload !== 'string' || envelope.payload.length > 1398104 || typeof envelope.signature !== 'string' || envelope.signature.length !== 88 || !/^[A-Za-z0-9+/]+={0,2}$/.test(envelope.payload) || !/^[A-Za-z0-9+/]+={0,2}$/.test(envelope.signature)) throw Error('RELEASE_INTEGRITY');
+  const bytes = Buffer.from(envelope.payload, 'base64');
+  if (bytes.length > 1024 * 1024 || (pinned && (!hex(config.manifestSha256) || sha(bytes) !== config.manifestSha256))) throw Error('RELEASE_INTEGRITY');
+  if (!verify(null, bytes, config.publicKey, Buffer.from(envelope.signature, 'base64'))) throw Error('RELEASE_SIGNATURE');
+  return { document: JSON.parse(bytes.toString('utf8')), digest: sha(bytes) };
+}
+export function verifyReleaseEnvelope(envelope, config) {
+  const { document } = signedDocument(envelope, config);
+  if (document.schemaVersion !== 'agent-runtime-release/1' || document.version !== config.version) throw Error('RELEASE_VERSION');
+  return validateAssets(document);
+}
+function validateAssets(document) {
+  if (!Array.isArray(document.assets) || document.assets.length !== 3) {
+    // A unit fixture can explicitly supply all three; publication cannot omit macOS.
+    throw Error('RELEASE_PLATFORM_MATRIX');
+  }
+  const platforms = new Set();
+  for (const asset of document.assets) {
+    const key = `${asset.platform}-${asset.arch}`;
+    if (!['linux-x64', 'win32-x64', 'darwin-arm64'].includes(key) || platforms.has(key)) throw Error('RELEASE_PLATFORM_MATRIX'); platforms.add(key);
+    for (const payload of [asset, asset.browserFallback]) {
+      if (!payload || !Number.isSafeInteger(payload.bytes) || payload.bytes < 1 || payload.bytes > 512 * 1024 * 1024 || !hex(payload.sha256) || !hex(payload.manifestSha256)) throw Error('RELEASE_ASSET');
+      trustedUrl(payload.url);
+    }
+  }
+  return document;
+}
+export async function download(url, maximumBytes, fetcher, options = {}) {
+  const validateUrl = options.metadataChannel === undefined ? trustedUrl : value => trustedMetadataUrl(value, options.metadataChannel);
+  url = validateUrl(url);
+  const timeout = AbortSignal.timeout(options.timeoutMs ?? 120_000);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+  for (let hop = 0; hop <= 5; hop++) {
+    const response = await fetcher(url, { redirect: 'manual', credentials: 'omit', referrerPolicy: 'no-referrer', signal });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const location = response.headers.get('location'); await response.body?.cancel();
+      if (!location) throw Error('RELEASE_HTTP'); url = validateUrl(new URL(location, url).href); continue;
+    }
+    if (!response.ok || !response.body) throw Error('RELEASE_HTTP');
+    const chunks = []; let size = 0;
+    for await (const chunk of response.body) { size += chunk.length; if (size > maximumBytes) throw Error('RELEASE_SIZE'); chunks.push(Buffer.from(chunk)); }
+    return Buffer.concat(chunks);
+  }
+  throw Error('RELEASE_REDIRECTS');
+}
+export async function installPublishedRelease(config, cache, fetcher = fetch, options = {}) {
+  if (config.status !== 'published') throw Error('RELEASE_UNPUBLISHED');
+  const envelope = JSON.parse((await download(config.url, 2 * 1024 * 1024, fetcher)).toString('utf8'));
+  const document = verifyReleaseEnvelope(envelope, config);
+  return installReleaseDocument(document, cache, fetcher, options);
+}
+/** One archive verifier/extractor for explicit and opportunistic delivery. */
+export async function installReleaseDocument(document, cache, fetcher = fetch, options = {}) {
+  validateAssets(document);
+  const platform = document.assets.find(asset => asset.platform === process.platform && asset.arch === process.arch);
+  if (!platform) throw Error('PLATFORM_UNSUPPORTED');
+  const asset = options.browserPreference === 'pinned' ? platform.browserFallback : platform;
+  if (options.browserPreference === 'pinned' && options.confirmDownload !== asset.sha256) return {
+    status: 'browser_download_required', bytes: asset.bytes, sha256: asset.sha256, version: document.version,
+    action: 'Repeat browser-install with --confirm-download and this exact SHA-256 after host approval. No browser downloaded yet.',
+  };
+  options.onDownload?.({ bytes: asset.bytes, version: document.version, browser: options.browserPreference === 'pinned' ? 'pinned_chromium' : 'system' });
+  const bytes = await download(asset.url, asset.bytes, fetcher, options);
+  if (bytes.length !== asset.bytes || sha(bytes) !== asset.sha256) throw Error('RELEASE_ASSET_INTEGRITY');
+  const files = decodeRuntimeArchive(bytes, { allowBundleLinks: true, allowPathHeaders: true });
+  const metadataFile = files.find(file => file.path === 'candidate.json');
+  if (!metadataFile || sha(metadataFile.bytes) !== asset.manifestSha256) throw Error('RELEASE_ASSET_INTEGRITY');
+  const metadata = JSON.parse(metadataFile.bytes.toString('utf8'));
+  if (metadata.productVersion !== document.version) throw Error('RELEASE_VERSION');
+  if (options.generation && JSON.stringify(metadata.generation) !== JSON.stringify(options.generation)) throw Error('RELEASE_GENERATION');
+  if ((metadata.browserPreference ?? 'system') !== (options.browserPreference ?? 'system')) throw Error('RELEASE_BROWSER_VARIANT');
+  // macOS aliases /var to /private/var. Resolve only the trusted OS temporary
+  // root before allocating our unique directory; payload/cache paths stay strict.
+  const temporary = await mkdtemp(join(await realpath(tmpdir()), 'stateport-release-'));
+  try {
+    for (const file of files.filter(file => file.kind !== 'symlink')) {
+      const path = join(temporary, file.path); await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+      await writeFile(path, file.bytes, { flag: 'wx', mode: file.executable ? 0o700 : 0o600 });
+    }
+    for (const file of files.filter(file => file.kind === 'symlink')) {
+      if (process.platform === 'win32') throw Error('BUNDLE_LINK_UNSUPPORTED');
+      const path = join(temporary, file.path); await mkdir(dirname(path), { recursive: true, mode: 0o700 }); await symlink(file.target, path);
+    }
+    return await (options.install ?? installCandidate)({ source: temporary, cache, manifestSha256: asset.manifestSha256 });
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+function semverParts(value) {
+  if (typeof value !== 'string' || value.length > 128 || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/.test(value)) throw Error('RELEASE_VERSION');
+  const [base, ...suffix] = value.split('-');
+  const parts = base.split('.').map(Number);
+  if (parts.some(part => !Number.isSafeInteger(part))) throw Error('RELEASE_VERSION');
+  const pre = suffix.join('-').split('.').filter(Boolean);
+  if (pre.some(part => /^0\d+$/.test(part))) throw Error('RELEASE_VERSION');
+  return { parts, pre };
+}
+export function compareVersions(a, b) {
+  const x = semverParts(a), y = semverParts(b);
+  for (let i = 0; i < 3; i++) if (x.parts[i] !== y.parts[i]) return Math.sign(x.parts[i] - y.parts[i]);
+  if (!x.pre.length || !y.pre.length) return x.pre.length === y.pre.length ? 0 : x.pre.length ? -1 : 1;
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const a = x.pre[i], b = y.pre[i]; if (a === b) continue;
+    if (a === undefined || b === undefined) return a === undefined ? -1 : 1;
+    const an = /^\d+$/.test(a), bn = /^\d+$/.test(b);
+    if (an && bn) return a.length === b.length ? (a < b ? -1 : 1) : Math.sign(a.length - b.length);
+    if (an !== bn) return an ? -1 : 1;
+    return a < b ? -1 : 1;
+  }
+  return 0;
+}
+/** Dynamic selection is authenticated by the same independently pinned key,
+ * never by a digest returned beside an untrusted download. */
+export function verifyChannelEnvelope(envelope, trust, highWater = {}) {
+  const verified = signedDocument(envelope, trust, false), d = verified.document;
+  const keys = 'assets,channel,publisher,schemaVersion,sequence,version';
+  if (d.schemaVersion !== 'agent-runtime-release/2' || Object.keys(d).sort().join(',') !== keys || !Number.isSafeInteger(d.sequence) || d.sequence < 1) throw Error('RELEASE_SCHEMA');
+  semverParts(d.version);
+  if (d.publisher !== trust.publisher || trust.publisher !== 'StatePort-Dev') throw Error('RELEASE_PUBLISHER');
+  if (d.channel !== trust.channel || !['stable', 'beta', 'rc'].includes(d.channel)) throw Error('RELEASE_CHANNEL');
+  if ((d.channel === 'stable' && d.version.includes('-')) || (d.channel !== 'stable' && !d.version.includes(`-${d.channel}.`))) throw Error('RELEASE_CHANNEL');
+  if (highWater.sequence && (d.sequence < highWater.sequence || (d.sequence === highWater.sequence && verified.digest !== highWater.releaseDigest))) throw Error('RELEASE_REPLAY');
+  if (highWater.version && compareVersions(d.version, highWater.version) < 0) throw Error('RELEASE_DOWNGRADE');
+  if (highWater.version === d.version && highWater.releaseDigest !== verified.digest) throw Error('RELEASE_VERSION_REPLACED');
+  validateAssets(d);
+  return verified;
+}

package/lib/session.mjs

@@ -0,0 +1,55 @@
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { selectSessionRuntime, quarantineStartup } from './updates.mjs';
+import { updateControl } from './controls.mjs';
+
+/** A task-session or stdio MCP selects exactly once. Its runtime child and every
+ * worker retain that immutable path. There is no post-operation retry/fallback. */
+export async function launchSession({ cache, runtime, trust, args }) {
+  const [command = 'doctor'] = args;
+  if (command === 'updates') {
+    process.stdout.write(JSON.stringify(await updateControl(cache, trust, args.slice(1), runtime)) + '\n'); return;
+  }
+  const newSession = ['mcp', 'task-session', 'task-start', 'open'].includes(command);
+  const selected = newSession ? await selectSessionRuntime(cache, trust) : runtime;
+  const child = fork(selected.entry, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], windowsHide: true });
+  let ready = !newSession;
+  let job;
+  const stopJob = () => {
+    if (!job || job.exitCode !== null) return;
+    job.send?.({ operation: 'abort' }, () => {});
+    const timer = setTimeout(() => { if (job.exitCode === null) job.kill(); }, 1000); timer.unref();
+  };
+  const startJob = () => {
+    if (!newSession || trust.status !== 'published' || job) return;
+    // Trusted runtime-owned implementation, finite IPC owner and hard ceiling.
+    job = fork(fileURLToPath(new URL('update-job.mjs', import.meta.url)), [], { stdio: ['ignore', 'ignore', 'ignore', 'ipc'], windowsHide: true });
+    job.on('error', () => {});
+    job.on('message', message => {
+      if (message?.protocol === 'agent-update-notice/1' && typeof message.version === 'string'
+        && /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(message.version) && /^[a-f0-9]{64}$/.test(message.digest)) {
+        process.stderr.write(`StatePort ${message.version} available. Check updates status.\n`);
+      }
+    });
+    job.send({ operation: 'check', cache, trust });
+    const maximum = setTimeout(stopJob, 131_000); maximum.unref();
+    job.once('exit', () => clearTimeout(maximum));
+  };
+  child.on('message', message => {
+    if (message?.protocol === 'agent-launch-ready/1') ready = true;
+    if (message?.protocol === 'agent-update-use/1') startJob();
+  });
+  const signals = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK'];
+  const handlers = signals.map(signal => {
+    const handler = () => { stopJob(); try { child.kill(signal); } catch { child.kill(); } };
+    process.on(signal, handler); return [signal, handler];
+  });
+  await new Promise(resolve => {
+    child.once('error', () => { process.exitCode = 1; resolve(); });
+    child.once('exit', (code, signal) => { process.exitCode = code ?? (signal ? 1 : 0); resolve(); });
+  });
+  stopJob();
+  for (const [signal, handler] of handlers) process.off(signal, handler);
+  if (job?.connected) job.disconnect();
+  if (!ready && selected.digest !== runtime.digest) await quarantineStartup(cache, selected.digest, runtime).catch(() => {});
+}

package/lib/update-job.mjs

@@ -0,0 +1,16 @@
+import { checkForUpdates } from './updates.mjs';
+const abort = new AbortController();
+let started = false;
+const maximum = setTimeout(() => { abort.abort(); process.exit(0); }, 131_000);
+maximum.unref();
+process.once('disconnect', () => { abort.abort(); process.exit(0); });
+process.on('message', async message => {
+  if (message?.operation === 'abort') { abort.abort(); return; }
+  if (started || message?.operation !== 'check' || !process.connected) return;
+  started = true;
+  try {
+    const result = await checkForUpdates(message.cache, message.trust, { signal: abort.signal });
+    if (result.notice && process.connected) process.send?.({ protocol: 'agent-update-notice/1', ...result.notice });
+  }
+  finally { clearTimeout(maximum); if (process.connected) process.disconnect(); }
+});

package/lib/update-policy.mjs

@@ -0,0 +1,66 @@
+import { join } from 'node:path';
+import { bytes, withInstallTransaction } from './install.mjs';
+
+export const UPDATE_TTL_MS = 86_400_000;
+export const hex = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const version = value => typeof value === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)?$/.test(value);
+export async function readJson(cache, name, fallback) {
+  try { return JSON.parse((await bytes(join(cache, name), 131072)).toString('utf8')); }
+  catch (error) { if (error?.code === 'ENOENT') return structuredClone(fallback); throw Error('UPDATE_STATE_INVALID'); }
+}
+export async function readUpdatePolicy(cache) {
+  const policy = await readJson(cache, 'update-policy.json', { schemaVersion: 'agent-update-policy/1', mode: 'notify', channel: 'rc', consent: false, pin: null });
+  if (policy.schemaVersion !== 'agent-update-policy/1' || !['auto', 'notify', 'pinned'].includes(policy.mode)
+    || !['stable', 'beta', 'rc'].includes(policy.channel) || typeof policy.consent !== 'boolean'
+    || (policy.mode === 'auto' && !policy.consent)
+    || (policy.mode === 'pinned' ? !policy.pin || !hex(policy.pin.digest) || !version(policy.pin.version) : policy.pin !== null)
+    || Object.keys(policy).sort().join(',') !== 'channel,consent,mode,pin,schemaVersion') throw Error('UPDATE_POLICY_INVALID');
+  return policy;
+}
+export async function setUpdatePolicy(cache, change) {
+  return withInstallTransaction(cache, async transaction => {
+    const before = await readUpdatePolicy(cache);
+    if (before.mode === 'pinned' && change.mode !== 'pinned' && change.releasePin !== true) throw Error('PIN_RELEASE_REQUIRED');
+    if (!['auto', 'notify', 'pinned'].includes(change.mode)) throw Error('UPDATE_POLICY_INVALID');
+    if (change.mode === 'auto' && change.consent !== true && !before.consent) throw Error('UPDATE_CONSENT_REQUIRED');
+    const policy = { schemaVersion: before.schemaVersion, mode: change.mode, channel: change.channel ?? before.channel,
+      consent: change.mode === 'auto' ? true : before.consent, pin: change.mode === 'pinned' ? change.pin : null };
+    if (!['stable', 'beta', 'rc'].includes(policy.channel) || (policy.pin !== null && (!policy.pin || !hex(policy.pin.digest) || !version(policy.pin.version)))) throw Error('UPDATE_POLICY_INVALID');
+    if (policy.pin) {
+      const installed = await transaction.installed(policy.pin.digest);
+      if (installed.productVersion !== policy.pin.version) throw Error('UPDATE_PIN_INVALID');
+    }
+    await transaction.write('update-policy.json', policy);
+    // Pending bytes remain cached; a policy change never kills an active process.
+    return policy;
+  });
+}
+export function checkDue(state, now = Date.now()) {
+  if (!Number.isSafeInteger(now) || now < 0) return false;
+  if (!Number.isSafeInteger(state.checkedAt) || state.checkedAt < 0) return true;
+  if (state.checkedAt > now + UPDATE_TTL_MS) return true; // rebase once under the shared lock
+  return now - state.checkedAt >= UPDATE_TTL_MS;
+}
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  return value;
+}
+export function validGeneration(value) {
+  const keys = 'arch,browser,launcher,mcp,nativeABI,nodeMajor,permissions,platform,schemaVersion,skills,storageRead,storageWrite,task,taskSession';
+  return value && Object.keys(value).sort().join(',') === keys && value.schemaVersion === 'agent-generation/1'
+    && value.launcher === 1 && value.nodeMajor === 24 && value.nativeABI === process.versions.modules
+    && value.platform === process.platform && value.arch === process.arch
+    && value.task === 'agent-task/1' && value.taskSession === 'agent-task-session/1'
+    && ['mcp', 'skills', 'storageRead', 'storageWrite'].every(key => hex(value[key]))
+    && Array.isArray(value.permissions) && value.permissions.length > 0 && value.permissions.length <= 16
+    && value.permissions.every(item => typeof item === 'string' && /^[a-z_-]{1,64}$/.test(item))
+    && value.browser && Object.keys(value.browser).sort().join(',') === 'payload,playwright,preference'
+    && ['system', 'pinned'].includes(value.browser.preference) && value.browser.playwright === '1.63.0'
+    && (value.browser.preference === 'system' ? value.browser.payload === null : hex(value.browser.payload));
+}
+/** Unknown contracts, different instructions or schemas require explicit setup/restart. */
+export function compatibleGeneration(running, candidate) {
+  if (!validGeneration(running) || !validGeneration(candidate)) return 'UPDATE_INCOMPATIBLE';
+  return JSON.stringify(canonical(running)) === JSON.stringify(canonical(candidate)) ? null : 'UPDATE_INCOMPATIBLE';
+}

package/lib/updates.mjs

@@ -0,0 +1,206 @@
+import { spawn } from 'node:child_process';
+import { withInstallTransaction, readCurrent, readInstalled, readPrevious } from './install.mjs';
+import { readJson, readUpdatePolicy, checkDue, compatibleGeneration, hex } from './update-policy.mjs';
+import { download, verifyChannelEnvelope, installReleaseDocument, compareVersions } from './release.mjs';
+
+const empty = () => ({ schemaVersion: 'agent-update-state/1', checkedAt: null, water: {}, available: null, pending: null, quarantine: [], hold: null });
+async function stateFor(cache) {
+  const state = await readJson(cache, 'update-state.json', empty());
+  if (state.schemaVersion !== 'agent-update-state/1' || Object.keys(state).sort().join(',') !== 'available,checkedAt,hold,pending,quarantine,schemaVersion,water'
+    || (state.checkedAt !== null && (!Number.isSafeInteger(state.checkedAt) || state.checkedAt < 0))
+    || !state.water || typeof state.water !== 'object' || Array.isArray(state.water)
+    || !Array.isArray(state.quarantine) || state.quarantine.length > 32 || !state.quarantine.every(hex)
+    || (state.hold !== null && (typeof state.hold !== 'string' || !/^UPDATE_[A-Z_]{1,64}$/.test(state.hold)))) throw Error('UPDATE_STATE_INVALID');
+  for (const [channel, water] of Object.entries(state.water)) {
+    if (!['stable', 'beta', 'rc'].includes(channel) || !water || !Number.isSafeInteger(water.sequence) || water.sequence < 1
+      || !hex(water.releaseDigest) || typeof water.version !== 'string' || (water.notifiedDigest !== undefined && !hex(water.notifiedDigest))) throw Error('UPDATE_STATE_INVALID');
+  }
+  return state;
+}
+function channelTrust(trust, policy) {
+  if (trust.status !== 'published') throw Error('UPDATE_NOT_CONFIGURED');
+  const url = trust.channels?.[policy.channel] ?? (trust.channel === policy.channel ? trust.url : undefined);
+  if (!url) throw Error('UPDATE_CHANNEL_UNAVAILABLE');
+  return { ...trust, channel: policy.channel, url };
+}
+function assetFor(document, browserPreference) {
+  const platform = document.assets.find(asset => asset.platform === process.platform && asset.arch === process.arch);
+  if (!platform) throw Error('UPDATE_INCOMPATIBLE');
+  return browserPreference === 'pinned' ? platform.browserFallback : platform;
+}
+function quarantined(state, digest) { return state.quarantine.includes(digest); }
+function quarantine(state, digest) {
+  state.quarantine = [...state.quarantine.filter(value => value !== digest), digest].slice(-32);
+  state.pending = null; state.hold = 'UPDATE_QUARANTINED';
+}
+const safeReasons = new Set(['UPDATE_INCOMPATIBLE', 'UPDATE_QUARANTINED', 'UPDATE_INTEGRATION_HELD', 'UPDATE_NOT_CONFIGURED', 'UPDATE_CHANNEL_UNAVAILABLE', 'UPDATE_BROWSER_CONFIRMATION_REQUIRED']);
+const reason = error => safeReasons.has(error?.message) ? error.message : 'UPDATE_CHECK_FAILED';
+
+/** Only a verified runtime can reach this child. No shell, Cards, vault writes,
+ * Capture, entitlement activation or user operation; stderr is never projected. */
+export async function readiness(runtime, { integration = false, signal } = {}) {
+  return new Promise(resolve => {
+    const child = spawn(process.execPath, [runtime.entry, 'update-readiness'], { windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'], signal });
+    let text = '', size = 0, finished = false;
+    const finish = result => { if (!finished) { finished = true; clearTimeout(timer); resolve(result); } };
+    const timer = setTimeout(() => { child.kill(); finish(false); }, 10_000);
+    child.stdout.on('data', chunk => { size += chunk.length; if (size > 65536) { child.kill(); finish(false); } else text += chunk; });
+    child.on('error', () => finish(false));
+    child.on('close', code => {
+      try {
+        const reply = JSON.parse(text);
+        finish(code === 0 && reply.status === 'ready' && reply.version === runtime.productVersion && reply.execution === 'allowed'
+          && compatibleGeneration(runtime.generation, reply.generation) === null
+          && (!integration || reply.integration === 'unchanged'));
+      } catch { finish(false); }
+    });
+  });
+}
+export async function updateStatus(cache, running) {
+  const current = await readCurrent(cache), policy = await readUpdatePolicy(cache), state = await stateFor(cache);
+  const previous = await readPrevious(cache).catch(() => undefined);
+  const summary = runtime => runtime ? { version: runtime.productVersion, digest: runtime.digest } : null;
+  const advertised = value => value && typeof value.version === 'string' && hex(value.digest) ? { version: value.version, digest: value.digest } : null;
+  return { schemaVersion: 'agent-update-status/1', running: summary(running), selected: summary(current), previous: summary(previous), mode: policy.mode, channel: policy.channel,
+    pin: policy.pin, checkedAt: state.checkedAt === null ? null : new Date(state.checkedAt).toISOString(), available: advertised(state.available),
+    pending: advertised(state.pending), hold: policy.mode === 'pinned' ? 'UPDATE_PINNED' : state.hold,
+    applies: state.pending ? 'next_eligible_session' : null };
+}
+/** One finite, shared, opportunistic transaction; errors never gate current work. */
+export async function checkForUpdates(cache, trust, options = {}) {
+  if (trust.status !== 'published') return { status: 'not_configured' };
+  try {
+    return await withInstallTransaction(cache, async transaction => {
+      const policy = await readUpdatePolicy(cache), state = await stateFor(cache);
+      if (policy.mode === 'pinned') return { status: 'pinned' };
+      const now = options.now ?? Date.now();
+      if (!options.force && !checkDue(state, now)) return { status: 'throttled' };
+      const current = await transaction.current();
+      if (!current) return { status: 'not_installed' };
+      const config = channelTrust(trust, policy);
+      state.checkedAt = now; state.hold = null;
+      // Persist attempt before any network: failure/crash does not create a storm.
+      await transaction.write('update-state.json', state);
+      let notice;
+      try {
+        const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(130_000)]) : AbortSignal.timeout(130_000);
+        const envelope = JSON.parse((await download(config.url, 2 * 1024 * 1024, options.fetcher ?? fetch, { signal, timeoutMs: 5_000, metadataChannel: policy.channel })).toString('utf8'));
+        const verified = verifyChannelEnvelope(envelope, config, state.water[policy.channel]);
+        const document = verified.document, asset = assetFor(document, current.browserPreference);
+        // A channel never replaces an installed version with different bytes.
+        const order = compareVersions(document.version, current.productVersion);
+        if (order < 0 || (order === 0 && asset.manifestSha256 !== current.digest)) throw Error('UPDATE_INCOMPATIBLE');
+        state.water[policy.channel] = { ...state.water[policy.channel], sequence: document.sequence, version: document.version, releaseDigest: verified.digest };
+        state.available = { version: document.version, digest: asset.manifestSha256 };
+        if (policy.mode === 'notify' && order > 0 && state.water[policy.channel].notifiedDigest !== asset.manifestSha256) {
+          notice = { version: document.version, digest: asset.manifestSha256 };
+          // Optional inert high-water metadata; older readers ignore it. No
+          // new execution/trust authority is derived from notification state.
+          state.water[policy.channel].notifiedDigest = asset.manifestSha256;
+        }
+        if (order === 0) { state.available = null; state.pending = null; }
+        else if (quarantined(state, asset.manifestSha256)) state.hold = 'UPDATE_QUARANTINED';
+        else if (compatibleGeneration(current.generation, asset.generation)) state.hold = 'UPDATE_INCOMPATIBLE';
+        else if (policy.mode === 'auto' || options.manual === true) {
+          if (current.browserPreference === 'pinned' && options.confirmDownload !== asset.sha256) throw Error('UPDATE_BROWSER_CONFIRMATION_REQUIRED');
+          let candidate;
+          try { candidate = await transaction.installed(asset.manifestSha256); }
+          catch (error) {
+            if (error?.code !== 'ENOENT') throw error; // edited cache is never repaired silently
+            candidate = await installReleaseDocument(document, cache, options.fetcher ?? fetch, {
+              browserPreference: current.browserPreference, confirmDownload: options.confirmDownload, generation: asset.generation,
+              signal, install: transaction.stage,
+            });
+          }
+          if (candidate.productVersion !== document.version || compatibleGeneration(candidate.generation, asset.generation)) throw Error('UPDATE_INCOMPATIBLE');
+          if (!(await (options.readiness ?? readiness)(candidate, { signal }))) quarantine(state, candidate.digest);
+          else state.pending = { version: candidate.productVersion, digest: candidate.digest, envelope };
+        }
+      } catch (error) { state.hold = reason(error); }
+      await transaction.write('update-state.json', state);
+      return { status: state.pending ? 'pending_next_session' : state.hold ? 'held' : 'checked', ...(notice ? { notice } : {}) };
+    });
+  } catch { return { status: 'unavailable' }; }
+}
+/** Resolves once, before a new task/MCP process. Calls already inside a task
+ * never use this function. A failed candidate never causes action replay. */
+export async function selectSessionRuntime(cache, trust, options = {}) {
+  const before = await readCurrent(cache);
+  if (!before) throw Error('RUNTIME_NOT_INSTALLED');
+  try {
+    return await withInstallTransaction(cache, async transaction => {
+      const current = await transaction.current(), policy = await readUpdatePolicy(cache), state = await stateFor(cache);
+      if (policy.mode === 'pinned') {
+        const pinned = await transaction.installed(policy.pin.digest);
+        if (pinned.productVersion !== policy.pin.version || compatibleGeneration(current.generation, pinned.generation)) throw Error('UPDATE_INCOMPATIBLE');
+        if (!(await (options.readiness ?? readiness)(pinned))) throw Error('UPDATE_INCOMPATIBLE');
+        return pinned;
+      }
+      if ((policy.mode !== 'auto' && options.manual !== true) || !state.pending) return current;
+      const pending = state.pending;
+      try {
+        const config = channelTrust(trust, policy), verified = verifyChannelEnvelope(pending.envelope, config, state.water[policy.channel]);
+        const asset = assetFor(verified.document, current.browserPreference);
+        if (pending.digest !== asset.manifestSha256 || pending.version !== verified.document.version || quarantined(state, pending.digest)
+          || compareVersions(pending.version, current.productVersion) <= 0 || compatibleGeneration(current.generation, asset.generation)) throw Error('UPDATE_INCOMPATIBLE');
+        const candidate = await transaction.installed(pending.digest);
+        if (compatibleGeneration(candidate.generation, asset.generation)) throw Error('UPDATE_INCOMPATIBLE');
+        if (!(await (options.ownership ?? (runtime => readiness(runtime, { integration: true })))(current))) {
+          state.hold = 'UPDATE_INTEGRATION_HELD'; await transaction.write('update-state.json', state); return current;
+        }
+        if (!(await (options.readiness ?? readiness)(candidate))) {
+          quarantine(state, candidate.digest); await transaction.write('update-state.json', state); return current;
+        }
+        const selected = await transaction.activate(candidate.digest);
+        state.pending = null; state.hold = null;
+        await transaction.write('update-state.json', state);
+        return selected;
+      } catch {
+        if (hex(pending.digest)) quarantine(state, pending.digest);
+        else state.hold = 'UPDATE_CHECK_FAILED';
+        await transaction.write('update-state.json', state);
+        return current;
+      }
+    });
+  } catch {
+    // An explicit exact pin cannot silently execute different bytes, even if
+    // its preflight or the shared lock is unavailable. Read-only recovery stays.
+    const policy = await readUpdatePolicy(cache).catch(() => undefined);
+    if (policy?.mode === 'pinned' && policy.pin.digest !== before.digest) throw Error('UPDATE_PIN_UNAVAILABLE');
+    return before; // other unknown lock/cache/policy never gates installed recovery
+  }
+}
+export async function retryQuarantine(cache, digest) {
+  if (!hex(digest)) throw Error('INVALID_ARGUMENTS');
+  return withInstallTransaction(cache, async transaction => {
+    const state = await stateFor(cache);
+    state.quarantine = state.quarantine.filter(value => value !== digest); state.hold = null;
+    await transaction.write('update-state.json', state);
+    return { status: 'retry_allowed', digest };
+  });
+}
+export async function rollbackGeneration(cache, options = {}) {
+  return withInstallTransaction(cache, async transaction => {
+    const current = await transaction.current(), previous = await transaction.previous();
+    if (!current || !previous) throw Error('ROLLBACK_UNAVAILABLE');
+    if (compatibleGeneration(current.generation, previous.generation)) throw Error('UPDATE_INCOMPATIBLE');
+    if (!(await (options.readiness ?? readiness)(previous))) throw Error('UPDATE_ROLLBACK_UNAVAILABLE');
+    const state = await stateFor(cache);
+    const selected = await transaction.activate(previous.digest);
+    state.pending = null; state.hold = 'UPDATE_ROLLED_BACK';
+    await transaction.write('update-state.json', state);
+    return selected;
+  });
+}
+/** Restore code for future sessions only. Never replays this process's request. */
+export async function quarantineStartup(cache, digest, previous, options = {}) {
+  return withInstallTransaction(cache, async transaction => {
+    const state = await stateFor(cache), current = await transaction.current();
+    quarantine(state, digest);
+    if (current?.digest === digest && previous && previous.digest !== digest) {
+      const saved = await transaction.installed(previous.digest);
+      if (!compatibleGeneration(current.generation, saved.generation) && await (options.readiness ?? readiness)(saved)) await transaction.activate(saved.digest);
+    }
+    await transaction.write('update-state.json', state);
+  });
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "stateport",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc.5",
+  "private": false,
+  "description": "StatePort agent runtime bootstrap",
+  "type": "module",
+  "bin": {
+    "stateport": "./bin/stateport.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "release.json",
+    "update-release.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "scripts": {
+    "build": "node --check bin/stateport.mjs",
+    "check": "node --test tests/*.test.mjs"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/StatePort-Dev/stateport-agent-skills.git",
+    "directory": "bootstrap"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/release.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "agent-bootstrap-release/1.0.0",
+  "status": "published",
+  "version": "1.0.0-rc.5",
+  "url": "https://github.com/StatePort-Dev/stateport-releases/releases/download/v1.0.0-rc.5-agent.1/release.json",
+  "manifestSha256": "c092f1970cb90b7b648278989275c9c3ab5ed9217a30fcaea31b31103f2598e4",
+  "keyId": "stateport-agent-release-2026-11-03",
+  "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA8uC2jzpeW53A/MGquI0i7vjAHRpk6MKslN2asEIQQjs=\n-----END PUBLIC KEY-----\n"
+}

package/update-release.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "agent-update-trust/1",
+  "status": "published",
+  "publisher": "StatePort-Dev",
+  "channel": "rc",
+  "url": "https://raw.githubusercontent.com/StatePort-Dev/stateport-releases/main/channels/rc.json",
+  "keyId": "stateport-agent-release-2026-11-03",
+  "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA8uC2jzpeW53A/MGquI0i7vjAHRpk6MKslN2asEIQQjs=\n-----END PUBLIC KEY-----\n"
+}