@ours.network/install 1.1.1 → 1.2.0-nightly.2

package/assets/scripts/build/build.mjs

@@ -0,0 +1,49 @@
+/** Acquire selected packages, build Git sources once, write the final manifest. */
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { SOURCE_ROOT, CONFIG, OUT, ROOT, SELECTED, archive, manifest, run, capture, inheritedLock } from './build-common.mjs';
+const recipes = ['sdk', 'telegram', 'cowork', 'messenger', 'fleet', 'mcp'];
+const packages = Object.fromEntries([...SELECTED].map(name => [name, CONFIG.packages[name]]));
+for (const [name, selection] of Object.entries(packages)) {
+  const keys = Object.keys(selection || {}).sort().join(',');
+  if (keys === 'source') {
+    const source = selection.source;
+    if (!recipes.includes(source)) throw Error(`Unknown source recipe: ${source}`);
+    const spec = CONFIG.sources[source];
+    if (spec?.type !== 'git' || !/^[0-9a-f]{40}$/.test(spec.commit)) throw Error(`${source}: expected Git URL and full commit SHA`);
+  } else if (keys === 'type,version' && selection.type === 'npm') {
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(selection.version)) throw Error(`${name}: expected exact npm version`);
+  } else throw Error(`${name}: select a Git source or exact npm version`);
+}
+mkdirSync(OUT, { recursive: true });
+for (const [name, selection] of Object.entries(packages)) {
+  if (selection.type !== 'npm') continue;
+  const result = JSON.parse(capture(['npm', 'pack', name + '@' + selection.version, '--ignore-scripts', '--json', '--pack-destination', OUT], ROOT))[0];
+  renameSync(join(OUT, result.filename), archive(name));
+}
+const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+if (existsSync('/run/secrets/github_token')) Object.assign(env, {
+  GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'credential.helper',
+  GIT_CONFIG_VALUE_0: '!f() { printf "username=x-access-token\\npassword="; cat /run/secrets/github_token; printf "\\n"; }; f',
+});
+for (const source of recipes) {
+  if (!Object.values(packages).some(item => item.source === source)) continue;
+  const spec = CONFIG.sources[source], directory = join(SOURCE_ROOT, source);
+  mkdirSync(directory, { recursive: true });
+  const git = (...args) => execFileSync('git', args, { cwd: directory, env, stdio: ['inherit', 'inherit', 'inherit', ...inheritedLock] });
+  git('init', '-q'); git('remote', 'add', 'origin', spec.url);
+  git('fetch', 'origin', spec.commit); git('checkout', '--detach', 'FETCH_HEAD');
+  if (capture(['git', 'rev-parse', 'HEAD'], directory).trim() !== spec.commit) throw Error(`${source}: checkout does not match selected commit`);
+  git('submodule', 'update', '--init', '--recursive', '--depth=1');
+  run([process.execPath, fileURLToPath(new URL(`build-${source}.mjs`, import.meta.url))], ROOT);
+}
+for (const [name, selection] of Object.entries(packages)) {
+  const packed = manifest(archive(name));
+  if (packed.name !== name || (selection.type === 'npm' && packed.version !== selection.version)) throw Error(`Packed output does not match selection: ${name}`);
+}
+writeFileSync(join(ROOT, 'package.json'), JSON.stringify({
+  name: 'ours-container-runtime', version: '0.1.0', private: true,
+  dependencies: Object.fromEntries(Object.keys(packages).map(name => [name, 'file:' + relative(ROOT, archive(name))])),
+}, null, 2) + '\n');

package/assets/scripts/build/record-build.mjs

@@ -0,0 +1,31 @@
+/** Finalize freshly installed runtime records; never migrate historic builds here. */
+import * as fs from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { createBuildContext, CONTEXT } from '../maintenance/build-context.mjs';
+export function finalizeBuild(root) {
+  if (fs.realpathSync(root) !== root) throw new Error('Build root must be canonical');
+  try { fs.lstatSync(join(root, CONTEXT)); throw new Error('Existing context cannot be regenerated'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const protect = (path, directory = false) => {
+    const st = fs.lstatSync(path);
+    if (!(directory ? st.isDirectory() : st.isFile()) || st.uid !== process.getuid() || (!directory && st.nlink !== 1) || fs.realpathSync(path) !== path) throw new Error('Unsafe owned build input: ' + path);
+    fs.chmodSync(path, directory ? 0o700 : 0o600);
+  };
+  for (const path of [root, join(root, 'docker'), join(root, 'docker/vendor')]) protect(path, true);
+  for (const name of ['package.json', 'package-lock.json']) protect(join(root, name));
+  const manifest = JSON.parse(fs.readFileSync(join(root, 'package.json')));
+  for (const spec of Object.values(manifest.dependencies ?? {})) {
+    if (typeof spec !== 'string' || !/^file:docker\/vendor\/ours\.network-[a-z-]+\.tgz$/.test(spec)) throw new Error('Unexpected installer vendor reference');
+    protect(join(root, spec.slice(5)));
+  }
+  const tree = execFileSync('npm', ['ls', '--omit=dev', '--all', '--json'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  JSON.parse(tree);
+  const path = join(root, 'dependency-tree.json');
+  // Fresh finalization may not overwrite a retained tree or follow a symlink.
+  fs.writeFileSync(path, tree, { flag: 'wx', mode: 0o600 });
+  fs.chmodSync(path, 0o600);
+  return createBuildContext(root);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) finalizeBuild(resolve(process.env.OURS_BUILD_ROOT || '/opt/ours'));

package/assets/scripts/maintenance/README.md

@@ -0,0 +1,35 @@
+# State maintenance
+
+The installer coordinates stopped server components and invokes the same Node.js
+maintenance implementation in package and Docker installations. Package mode uses
+the installed `ours-install` assets and dependencies. Docker uses a separate
+maintenance image with dependencies taken from the installer's `package.json`.
+
+```sh
+ours-install server backup server before-change --state-dir /path/to/installation
+ours-install server restore server before-change --state-dir /path/to/installation
+```
+
+Backup and restore support the full server or an addressed daemon, Telegram,
+Cowork or Messenger domain. Daemon archives include MCP preferences. Daemon
+restore/reset replaces both trees together and preserves other component data
+and current credentials. Addressed reset requires `--confirm`; full-server reset
+is not supported. Managed legacy installations convert to the shared layout
+through the installer before ordinary startup; plain script calls are not a
+substitute for that coordinated conversion.
+
+| File | Responsibility |
+|---|---|
+| `state-operation.mjs` | Validates the selected state, stages replacements and invokes owning package commands to retain current authority |
+| `state-archive.mjs` | Creates, validates and extracts format-1 archives, preserving private permissions and timestamps |
+| `state-native.mjs` | Provides the existing OS file-lock and atomic directory operations through Koffi |
+| `docker-layout-conversion.mjs` | Stages, validates and publishes the managed legacy Docker state layout under installer coordination |
+
+Archives are stored in `storage/backups`, outside `storage/state` but on the same
+storage volume. Removing that volume removes its backups too. Restore creates a
+backup before replacing state. Compatibility across arbitrary builds or
+instances is not established; `--compatible` records an operator's explicit
+compatibility decision. A failed operation leaves affected services stopped.
+
+Maintenance uses the installer's Node.js runtime and npm dependencies. There is
+no Python fallback or separate operator shell script.

package/assets/scripts/maintenance/build-context.mjs

@@ -0,0 +1,162 @@
+/** Verified installer vendor bindings. Context hashes are consistency, not signatures. */
+import * as fs from 'node:fs';
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { semanticRecordEqual } from './provenance-compare.mjs';
+
+export const BASE_RECORDS = ['package-lock.json', 'dependency-tree.json'];
+export const CONTEXT = 'build-context.json';
+const admitted = new WeakMap();
+const packages = new Set(['sdk', 'cli', 'mcp', 'tg-connector', 'cowork', 'messenger-server', 'fleet', 'codex', 'claude-code', 'install'].map(n => '@ours.network/' + n));
+const digest = (bytes, algorithm = 'sha256', encoding = 'hex') => createHash(algorithm).update(bytes).digest(encoding);
+const fail = text => { throw new Error(`Build context: ${text}`); };
+const keys = (v, expected) => v && !Array.isArray(v) && typeof v === 'object' && Object.keys(v).sort().join('\0') === [...expected].sort().join('\0');
+const vendorPath = name => `docker/vendor/ours.network-${name.slice('@ours.network/'.length)}.tgz`;
+const exists = path => { try { fs.lstatSync(path); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } };
+export const recordNames = records => Object.hasOwn(records, CONTEXT) ? [...BASE_RECORDS, CONTEXT] : [...BASE_RECORDS];
+
+function view(records) {
+  if (!keys(records, recordNames(records)) || !Object.values(records).every(Buffer.isBuffer)) fail('invalid record set');
+  if (!Object.hasOwn(records, CONTEXT)) return null;
+  const bytes = records[CONTEXT];
+  let c, lock, tree;
+  try { c = JSON.parse(bytes); lock = JSON.parse(records[BASE_RECORDS[0]]); tree = JSON.parse(records[BASE_RECORDS[1]]); }
+  catch { fail('invalid JSON'); }
+  // The creator owns this encoding: reject duplicate keys and alternate ambiguous JSON.
+  if (!bytes.equals(Buffer.from(JSON.stringify(c, null, 2) + '\n'))) fail('noncanonical context JSON');
+  for (const name of BASE_RECORDS) {
+    if (!semanticRecordEqual(name, records[name], Buffer.concat([records[name], Buffer.from('\n')]))) fail('unsupported build record shape');
+  }
+  if (!keys(c, ['schema', 'buildRoot', 'records', 'vendors']) || c.schema !== 1) fail('unsupported schema');
+  if (typeof c.buildRoot !== 'string' || !isAbsolute(c.buildRoot) || resolve(c.buildRoot) !== c.buildRoot || c.buildRoot.includes('\0')) fail('invalid build root');
+  if (!keys(c.records, BASE_RECORDS)) fail('invalid record digests');
+  for (const name of BASE_RECORDS) if (c.records[name] !== digest(records[name])) fail('record digest mismatch');
+  if (!Array.isArray(c.vendors) || !c.vendors.length) fail('missing vendor bindings');
+  const names = c.vendors.map(v => v?.name);
+  if (new Set(names).size !== names.length || names.join('\0') !== [...names].sort().join('\0')) fail('noncanonical vendor set');
+  const deps = lock?.packages?.['']?.dependencies;
+  if (lock.lockfileVersion !== 3 || !keys(deps, names) || !keys(tree.dependencies, names)) fail('vendor selection differs from records');
+  for (const v of c.vendors) {
+    if (!keys(v, ['name', 'version', 'relativePath', 'integrity']) || !packages.has(v.name) || v.relativePath !== vendorPath(v.name)) fail('invalid vendor binding');
+    if (typeof v.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(v.version) || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(v.integrity)) fail('invalid vendor version/integrity');
+    const entry = lock.packages['node_modules/' + v.name], node = tree.dependencies[v.name];
+    if (!entry || entry.version !== v.version || entry.integrity !== v.integrity || entry.resolved !== 'file:' + v.relativePath || deps[v.name] !== 'file:' + v.relativePath || entry.link) fail('vendor lock binding mismatch');
+    if (!node || node.version !== v.version || node.resolved !== 'file:' + join(c.buildRoot, v.relativePath)) fail('vendor tree binding mismatch');
+    node.resolved = 'file:' + v.relativePath;
+  }
+  return { vendors: c.vendors, tree: Buffer.from(JSON.stringify(tree)) };
+}
+
+export function validateBuildRecordSet(records) { view(records); }
+
+function safeFile(path, privateFile = false) {
+  const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.nlink !== 1 || ![process.getuid(), 0].includes(st.uid) || (st.mode & 0o7022) || (privateFile && (st.uid !== process.getuid() || st.gid !== process.getgid() || (st.mode & 0o777) !== 0o600))) fail('unsafe regular file ownership/permissions');
+    return fs.readFileSync(fd);
+  } finally { fs.closeSync(fd); }
+}
+
+/** Only protected filesystem records enter the comparison API. Missing context is legacy. */
+export function readBuildRecords(directory, { privateFiles = false, marker = false } = {}) {
+  const st = fs.lstatSync(directory);
+  if (!st.isDirectory() || fs.realpathSync(directory) !== directory || ![process.getuid(), 0].includes(st.uid) || (st.mode & 0o7022)) fail('unsafe record directory');
+  const names = [...BASE_RECORDS, ...(exists(join(directory, CONTEXT)) ? [CONTEXT] : [])];
+  if (marker && fs.readdirSync(directory).sort().join('\0') !== [...names].sort().join('\0')) fail('mixed or incomplete marker records');
+  const records = Object.fromEntries(names.map(name => [name, safeFile(join(directory, name), privateFiles)]));
+  const normalized = view(records);
+  // Snapshot privately as well as exposing buffers: caller mutation never alters admitted evidence.
+  const handle = {};
+  for (const [name, bytes] of Object.entries(records)) Object.defineProperty(handle, name, { enumerable: true, get: () => Buffer.from(bytes) });
+  admitted.set(handle, { records, normalized });
+  return Object.freeze(handle);
+}
+
+export function equalBuildRecords(a, b) {
+  const x = admitted.get(a), y = admitted.get(b);
+  if (!x || !y) fail('comparison requires verified record handles');
+  if (!semanticRecordEqual(BASE_RECORDS[0], x.records[BASE_RECORDS[0]], y.records[BASE_RECORDS[0]])) return false;
+  if (x.normalized && y.normalized) {
+    if (JSON.stringify(x.normalized.vendors) !== JSON.stringify(y.normalized.vendors)) return false;
+    return semanticRecordEqual(BASE_RECORDS[1], x.normalized.tree, y.normalized.tree);
+  }
+  // No one-sided normalization/adoption of historic records.
+  return semanticRecordEqual(BASE_RECORDS[1], x.records[BASE_RECORDS[1]], y.records[BASE_RECORDS[1]]);
+}
+
+export function createBuildContext(root) {
+  if (fs.realpathSync(root) !== root || resolve(root) !== root) fail('build root must be canonical');
+  const destination = join(root, CONTEXT);
+  if (exists(destination)) fail('context already exists; never regenerate historic evidence');
+  const records = readBuildRecords(root);
+  const lock = JSON.parse(records['package-lock.json']);
+  const deps = lock?.packages?.['']?.dependencies;
+  if (!deps || Array.isArray(deps) || typeof deps !== 'object') fail('missing vendor dependencies');
+  const manifest = JSON.parse(safeFile(join(root, 'package.json')));
+  if (manifest.name !== lock.name || manifest.version !== lock.version || !keys(manifest.dependencies, Object.keys(deps)) || Object.keys(deps).some(n => manifest.dependencies[n] !== deps[n])) fail('runtime manifest differs from lock selection');
+  const vendors = [];
+  for (const name of Object.keys(deps).sort()) {
+    if (!packages.has(name)) fail('unknown vendor package');
+    const relativePath = vendorPath(name), path = join(root, relativePath);
+    let part = root;
+    for (const component of relativePath.split('/')) {
+      part = join(part, component); const st = fs.lstatSync(part);
+      if (st.isSymbolicLink() || ![process.getuid(), 0].includes(st.uid) || fs.realpathSync(part) !== part || (st.mode & 0o7022)) fail('vendor path is not canonical or is writable by others');
+    }
+    if (relative(root, path).startsWith('..')) fail('vendor path escaped root');
+    const bytes = safeFile(path), integrity = 'sha512-' + digest(bytes, 'sha512', 'base64');
+    const entry = lock.packages['node_modules/' + name];
+    if (!entry || entry.integrity !== integrity) fail('tar integrity mismatch');
+    const before = fs.statSync(path);
+    const metadata = JSON.parse(execFileSync('npm', ['pack', '--dry-run', '--ignore-scripts', '--json', path], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
+    const after = fs.statSync(path);
+    if (before.dev !== after.dev || before.ino !== after.ino || !safeFile(path).equals(bytes)) fail('tar changed during verification');
+    if (metadata.length !== 1 || metadata[0].name !== name || metadata[0].version !== entry.version) fail('tar package identity mismatch');
+    vendors.push({ name, version: entry.version, relativePath, integrity });
+  }
+  const context = { schema: 1, buildRoot: root, records: Object.fromEntries(BASE_RECORDS.map(n => [n, digest(records[n])])), vendors };
+  const bytes = Buffer.from(JSON.stringify(context, null, 2) + '\n');
+  view({ ...records, [CONTEXT]: bytes });
+  for (const name of BASE_RECORDS) if (!safeFile(join(root, name)).equals(records[name])) fail('records changed during verification');
+  const sync = path => { const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } };
+  for (const name of BASE_RECORDS) sync(join(root, name));
+  const temp = join(root, '.' + CONTEXT + '-' + randomUUID());
+  try {
+    fs.writeFileSync(temp, bytes, { flag: 'wx', mode: 0o600 });
+    fs.chmodSync(temp, 0o600);
+    sync(temp);
+    // link publishes atomically without replacement; unlink the private temp immediately.
+    fs.linkSync(temp, destination);
+  } finally { if (exists(temp)) fs.unlinkSync(temp); }
+  sync(root);
+  return readBuildRecords(root);
+}
+
+/** Fresh marker publication only; an existing generation requires explicit maintenance. */
+export function initializeBuildMarker(marker, records) {
+  const selected = admitted.get(records);
+  if (!selected) fail('marker initialization requires verified record handles');
+  if (exists(marker) && fs.readdirSync(marker).length) {
+    const current = readBuildRecords(marker, { privateFiles: true, marker: true });
+    if (recordNames(current).length !== recordNames(records).length || recordNames(records).some(n => !current[n].equals(records[n]))) fail('existing state provenance differs; use reviewed update --compatible');
+    return;
+  }
+  const parent = resolve(marker, '..');
+  const st = fs.lstatSync(parent);
+  if (!st.isDirectory() || fs.realpathSync(parent) !== parent || st.uid !== process.getuid() || (st.mode & 0o7077)) fail('unsafe marker parent');
+  if (exists(marker)) {
+    const st = fs.lstatSync(marker);
+    if (!st.isDirectory() || fs.realpathSync(marker) !== marker || st.uid !== process.getuid() || (st.mode & 0o7077)) fail('unsafe marker directory');
+  }
+  const stage = fs.mkdtempSync(join(parent, '.provenance-'));
+  fs.chmodSync(stage, 0o700);
+  const sync = path => { const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } };
+  try {
+    for (const [name, bytes] of Object.entries(selected.records)) {
+      const path = join(stage, name); fs.writeFileSync(path, bytes, { flag: 'wx', mode: 0o600 }); fs.chmodSync(path, 0o600); sync(path);
+    }
+    sync(stage); fs.renameSync(stage, marker); sync(parent);
+  } finally { if (exists(stage)) fs.rmSync(stage, { recursive: true }); }
+}

package/assets/scripts/maintenance/docker-layout-conversion.mjs

@@ -0,0 +1,238 @@
+/** Stopped legacy Docker volumes mapped into the shared server-state archive layout. */
+import * as fs from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { copyPrivateTree, scanSource, createArchive, validateArchive } from './state-archive.mjs';
+import { publishNoReplace } from './state-native.mjs';
+
+const COMPONENTS = ['daemon', 'telegram', 'cowork', 'messenger'];
+import { recordNames, readBuildRecords, validateBuildRecordSet } from './build-context.mjs';
+const DAEMON_STATE = '/var/lib/ours';
+const MCP_STATE = '/var/lib/ours-mcp';
+const LEGACY_MCP_CHILD = '.mcp';
+
+function privateBytes(path, ownership) {
+  const stat = fs.lstatSync(path);
+  if (!stat.isFile() || stat.uid !== ownership.uid || stat.gid !== ownership.gid || (stat.mode & 0o7777) !== 0o600) {
+    throw new Error(`Unsafe Docker conversion source file: ${path}`);
+  }
+  return fs.readFileSync(path);
+}
+
+function objectAt(path, ownership) {
+  const value = JSON.parse(privateBytes(path, ownership));
+  if (!value || Array.isArray(value) || typeof value !== 'object') {
+    throw new Error('Docker conversion configuration must be an object');
+  }
+  return value;
+}
+
+function validateProfile(profile, instanceId) {
+  if (profile?.endpoint !== 'http://127.0.0.1:3050'
+    || profile.expectedInstanceId !== instanceId
+    || profile.credentialPath !== join(DAEMON_STATE, 'daemon-token')) {
+    throw new Error('MCP profile does not select this Docker source');
+  }
+}
+
+/** Source mounts and writer exclusion are selected and held by the installer. */
+export async function stageDockerLayout(source, staging, options) {
+  if (resolve(source) !== source || fs.realpathSync(source) !== source
+    || source === dirname(source) || resolve(staging) !== staging
+    || fs.realpathSync(dirname(staging)) !== dirname(staging)
+    || staging === source || staging.startsWith(source + '/') || source.startsWith(staging + '/')) {
+    throw new Error('Docker staging must be canonical and outside the source tree');
+  }
+  const daemon = join(source, 'daemon', 'data');
+  const config = objectAt(join(daemon, 'config.json'), options);
+  if (config.stateDir !== DAEMON_STATE || config.port !== 3050) {
+    throw new Error('Daemon authority source differs from the selected Docker layout');
+  }
+  if (config.networkMcp?.applicationConfigPath !== join(DAEMON_STATE, LEGACY_MCP_CHILD, 'config.json')) {
+    throw new Error('MCP configuration selects an external or conflicting source');
+  }
+  validateProfile(config.networkMcp.profile, options.instanceId);
+  validateProfile(objectAt(join(daemon, LEGACY_MCP_CHILD, 'profile.json'), options), options.instanceId);
+  validateBuildRecordSet(options.provenance);
+  for (const name of recordNames(options.provenance)) {
+    if (!Buffer.isBuffer(options.provenance?.[name])) throw new Error('Selected build provenance is required');
+  }
+
+  fs.mkdirSync(staging, { mode: 0o700 });
+  try {
+    for (const component of COMPONENTS) {
+      const data = join(source, component, 'data');
+      const marker = join(data, '.ours-provenance');
+      if (fs.readdirSync(marker).sort().join() !== recordNames(options.provenance).sort().join()) {
+        throw new Error(`Incomplete source ${component} provenance`);
+      }
+      for (const name of recordNames(options.provenance)) {
+        if (!privateBytes(join(marker, name), options).equals(options.provenance[name])) {
+          throw new Error(`Source ${component} differs from the selected build`);
+        }
+      }
+      copyPrivateTree(data, join(staging, component), options);
+    }
+    fs.renameSync(join(staging, 'daemon', LEGACY_MCP_CHILD), join(staging, 'mcp'));
+    fs.mkdirSync(join(staging, 'credentials'), { mode: 0o700 });
+    for (const component of COMPONENTS.filter(name => name !== 'daemon')) {
+      const bytes = privateBytes(join(source, `${component}-credential`, 'daemon-token'), options);
+      if (!bytes.length) throw new Error('Current managed credential is empty');
+      const destination = join(staging, 'credentials', component);
+      fs.mkdirSync(destination, { mode: 0o700 });
+      fs.writeFileSync(join(destination, 'daemon-token'), bytes, { mode: 0o600, flag: 'wx' });
+    }
+    scanSource(staging, options);
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/** Bind only after the original payload has been archived and validated. */
+export function bindDockerLayout(staging, options) {
+  const configPath = join(staging, 'daemon', 'config.json');
+  const config = objectAt(configPath, options);
+  validateProfile(config.networkMcp?.profile, options.instanceId);
+  config.networkMcp.applicationConfigPath = join(MCP_STATE, 'config.json');
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+/** Offline validation also covers components intentionally left stopped. */
+export function validateDockerLayout(tree, options) {
+  validateBuildRecordSet(options.provenance);
+  scanSource(tree, options);
+  for (const component of COMPONENTS) {
+    if (fs.readdirSync(join(tree, component, '.ours-provenance')).sort().join() !== recordNames(options.provenance).sort().join()) throw new Error('Mixed component provenance');
+    for (const name of recordNames(options.provenance)) {
+      if (!privateBytes(join(tree, component, '.ours-provenance', name), options).equals(options.provenance[name])) {
+        throw new Error(`Converted ${component} differs from the selected build`);
+      }
+    }
+    const config = join(tree, component, 'config.json');
+    if (fs.existsSync(config)) objectAt(config, options);
+  }
+  const daemon = objectAt(join(tree, 'daemon/config.json'), options);
+  const profile = objectAt(join(tree, 'mcp/profile.json'), options);
+  validateProfile(profile, options.instanceId);
+  if (daemon.stateDir !== DAEMON_STATE || daemon.port !== 3050
+    || daemon.networkMcp?.applicationConfigPath !== join(MCP_STATE, 'config.json')
+    || JSON.stringify(daemon.networkMcp.profile) !== JSON.stringify(profile)
+    || objectAt(join(tree, 'cowork/config.json'), options).stateDir !== '/var/lib/ours-cowork') {
+    throw new Error('Converted Docker deployment configuration is inconsistent');
+  }
+  if (fs.existsSync(join(tree, 'mcp/config.json'))) objectAt(join(tree, 'mcp/config.json'), options);
+  for (const path of ['daemon/daemon-token', ...COMPONENTS.filter(name => name !== 'daemon').map(name => `credentials/${name}/daemon-token`)]) {
+    if (!privateBytes(join(tree, path), options).length) throw new Error('Converted managed credential is empty');
+  }
+}
+
+/** Requires a schema-1 pending record reserving this volume and excluded writers. */
+export async function prepareDockerLayout(source, storage, label, options) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(label)) throw new Error('Invalid conversion backup label');
+  if (resolve(storage) !== storage || fs.realpathSync(storage) !== storage
+    || resolve(source) !== source || fs.realpathSync(source) !== source
+    || storage === source || storage.startsWith(source + '/') || source.startsWith(storage + '/')) {
+    throw new Error('Conversion storage must be canonical and outside the source');
+  }
+  const privateDirectory = path => {
+    const stat = fs.lstatSync(path);
+    if (!stat.isDirectory() || stat.uid !== options.uid || stat.gid !== options.gid
+      || (stat.mode & 0o7777) !== 0o700) throw new Error(`Unsafe conversion directory: ${path}`);
+  };
+  privateDirectory(storage);
+  const maintenance = join(storage, '.maintenance');
+  const backups = join(storage, 'backups');
+  for (const path of [maintenance, backups]) {
+    if (!fs.existsSync(path)) fs.mkdirSync(path, { mode: 0o700 });
+    privateDirectory(path);
+  }
+  const staging = join(maintenance, 'layout-conversion');
+  const target = join(storage, 'state');
+  const removeOwnedTree = path => {
+    if (!fs.existsSync(path)) return;
+    scanSource(path, options);
+    fs.rmSync(path, { recursive: true });
+  };
+  removeOwnedTree(staging);
+  try {
+    await stageDockerLayout(source, staging, options);
+    const archiveOptions = { ...options, domain: 'server' };
+    const backup = join(backups, label);
+    if (fs.existsSync(backup)) await validateArchive(backup, archiveOptions);
+    else await createArchive(staging, backup, archiveOptions);
+    // The source remains mounted at its original runtime path for SDK selection.
+    execFileSync(options.cli, ['config', 'access-retain', '--config', options.configPath,
+      '--target-state-dir', join(staging, 'daemon'), '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    bindDockerLayout(staging, options);
+    validateDockerLayout(staging, options);
+    removeOwnedTree(target);
+    publishNoReplace(staging, target);
+  } finally {
+    removeOwnedTree(staging);
+  }
+}
+
+/** Remove only retired working data; volume-root archives remain untouched. */
+export function cleanupDockerSource(source, options) {
+  const empty = [];
+  const aliases = [...COMPONENTS, ...COMPONENTS.filter(name => name !== 'daemon').map(name => `${name}-credential`)];
+  for (const alias of aliases) {
+    const root = join(source, alias);
+    if (!fs.existsSync(root)) continue;
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.uid !== options.uid || stat.gid !== options.gid
+      || (stat.mode & 0o7777) !== 0o700) throw new Error(`Unsafe retired volume root: ${alias}`);
+    const credential = alias.endsWith('-credential');
+    const path = join(root, credential ? 'daemon-token' : 'data');
+    if (fs.existsSync(path)) {
+      if (credential) { privateBytes(path, options); fs.unlinkSync(path); }
+      else { scanSource(path, options); fs.rmSync(path, { recursive: true }); }
+    }
+    if (fs.readdirSync(root).length === 0) empty.push(alias);
+  }
+  return empty;
+}
+
+/** Internal one-shot container entrypoint; the installer owns writer exclusion. */
+export async function runDockerLayoutCommand(argv, env = process.env) {
+  const [operation, label] = argv;
+  if (!((operation === 'prepare' && argv.length === 2)
+    || (['validate', 'cleanup'].includes(operation) && argv.length === 1))) {
+    throw new Error('usage: prepare BACKUP_LABEL | validate | cleanup');
+  }
+  const storage = env.OURS_STATE_ROOT || '/storage';
+  const source = env.OURS_CONVERSION_SOURCE || '/source';
+  const build = env.OURS_BUILD_ROOT || '/opt/ours';
+  const options = {
+    uid: process.getuid(), gid: process.getgid(), instanceId: env.OURS_DAEMON_ID,
+    cli: env.OURS_CLI_PATH || '/opt/ours/node_modules/.bin/ours',
+    configPath: env.OURS_DAEMON_CONFIG || '/var/lib/ours/config.json',
+    provenance: readBuildRecords(build),
+  };
+  if (!options.uid || !options.gid) throw new Error('Conversion requires a non-root owner');
+  if (operation === 'cleanup') {
+    console.log(JSON.stringify({ emptyVolumes: cleanupDockerSource(source, options) }));
+    return;
+  }
+  try {
+    execFileSync(env.OURS_COWORK_CLI_PATH || '/opt/ours/node_modules/.bin/ours-cowork', ['--json', 'prepare-backup'], {
+      env: { ...env, OURS_COWORK_CONFIG: env.OURS_COWORK_CONFIG || '/var/lib/ours-cowork/config.json',
+        OURS_COWORK_STATE_DIR: env.OURS_COWORK_STATE_DIR || '/var/lib/ours-cowork' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch {
+    throw new Error('Cowork preparation failed; Docker conversion was not continued');
+  }
+  if (operation === 'prepare') await prepareDockerLayout(source, storage, label, options);
+  else validateDockerLayout(join(storage, 'state'), options);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  runDockerLayoutCommand(process.argv.slice(2)).catch(error => {
+    // Owner process errors may contain private output; keep it out of installer logs.
+    console.error(error?.status !== undefined ? 'Owner command failed during Docker conversion' : error.message);
+    process.exitCode = 1;
+  });
+}