@ours.network/install 1.2.1-nightly.4 → 1.2.1-nightly.40

package/lib/container-engine.mjs

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, resolve } from 'node:path';
+
+export const engineName = record => record.containerEngine === undefined ? 'docker' : record.containerEngine;
+const path = value => typeof value === 'string' && isAbsolute(value) && resolve(value) === value && !/[\x00-\x1f]/.test(value);
+export function validateContainerEngine(record) {
+  const engine = engineName(record);
+  if (!['docker', 'podman'].includes(engine) || (record.mode !== 'docker' && (record.containerEngine !== undefined || record.containerBinding !== undefined))) throw new Error('Invalid container engine selection');
+  const b = record.containerBinding;
+  if (engine === 'docker') {
+    if (b !== undefined) throw new Error('Unexpected Docker backend binding');
+    return;
+  }
+  if (!b || b.version !== 1 || !Number.isInteger(b.uid) || b.uid <= 0 || !path(b.graphRoot) || !path(b.runRoot)
+    || !/^[a-f0-9]{64}$/.test(b.namespaceDigest ?? '') || !path(b.socket) || !path(b.provider) || typeof b.driver !== 'string' || !/^[a-z0-9]+$/.test(b.driver)
+    || Object.keys(b).some(k => !['version', 'uid', 'graphRoot', 'runRoot', 'socket', 'provider', 'driver', 'namespaceDigest'].includes(k))) throw new Error('Invalid rootless Podman backend binding');
+}
+function podmanEnvironment(record, env, uid) {
+  validateContainerEngine(record);
+  const b = record.containerBinding;
+  if (uid !== b.uid) throw new Error('Podman installation belongs to another rootless owner');
+  for (const key of ['CONTAINER_HOST', 'CONTAINER_CONNECTION', 'CONTAINERS_STORAGE_CONF', 'CONTAINERS_CONF', 'PODMAN_USERNS', 'STORAGE_DRIVER', 'STORAGE_OPTS']) {
+    if (env[key]) throw new Error(`${key} conflicts with the retained local Podman backend`);
+  }
+  if ((env.OURS_PODMAN_SOCKET && env.OURS_PODMAN_SOCKET !== b.socket) || env.DOCKER_CONTEXT || (env.DOCKER_HOST && env.DOCKER_HOST !== `unix://${b.socket}`)
+    || (env.PODMAN_COMPOSE_PROVIDER && env.PODMAN_COMPOSE_PROVIDER !== b.provider)) throw new Error('Environment conflicts with the retained Podman backend/provider');
+  return { DOCKER_CONTEXT: undefined, DOCKER_HOST: `unix://${b.socket}`, PODMAN_COMPOSE_PROVIDER: b.provider, PODMAN_COMPOSE_WARNING_LOGS: 'false' };
+}
+/** The only container command boundary. Legacy records keep their Docker path. */
+export async function runContainer(effects, record, args, options = {}) {
+  if (engineName(record) === 'docker') return effects.run('docker', args, options);
+  const env = { ...(effects.env ?? {}), ...(options.env ?? {}) };
+  const selected = podmanEnvironment(record, env, process.getuid?.());
+  const b = record.containerBinding;
+  if (args[0] === 'build' && !args.some(arg => arg === '--format' || arg.startsWith('--format='))) args = ['build', '--format', 'docker', ...args.slice(1)];
+  // Docker reports a missing object as 1; Podman inspect uses 125. Probe exact
+  // existence separately so transport/permission failures are never absence.
+  if (['image', 'volume'].includes(args[0]) && args[1] === 'inspect' && options.allowCodes?.includes(1)) {
+    const found = await runContainer(effects, record, [args[0], 'exists', args.at(-1)], { ...options, allowCodes: [1] });
+    if (found.code === 1) return { code: 1, stdout: '', ok: false };
+  }
+  // Native commands and the Compose provider must address the SAME local store.
+  const prefix = args[0] === 'compose' ? ['--remote', '--url', `unix://${b.socket}`] : ['--remote=false', '--root', b.graphRoot, '--runroot', b.runRoot, '--storage-driver', b.driver];
+  const result = await effects.run('podman', [...prefix, ...args],
+    { ...options, env: { ...options.env, ...selected } });
+  if (args[0] === 'image' && args[1] === 'inspect' && !args.includes('--format') && result.code === 0) {
+    const images = JSON.parse(result.stdout);
+    for (const value of images) if (/^[a-f0-9]{64}$/.test(value.Id)) value.Id = `sha256:${value.Id}`;
+    return { ...result, stdout: JSON.stringify(images) };
+  }
+  return result;
+}
+export function namespaceDigest(info) {
+  const maps = info.host?.idMappings;
+  const normalized = ['uidmap', 'gidmap'].map(key => {
+    const rows = maps?.[key];
+    if (!Array.isArray(rows) || !rows.length) throw new Error('Podman user namespace mappings are unavailable');
+    return rows.map(row => {
+      const values = [row.container_id, row.host_id, row.size];
+      if (values.some(value => !Number.isInteger(value) || value < 0) || row.size < 1) throw new Error('Invalid Podman namespace mapping');
+      return values;
+    }).sort((a, b) => a[0] - b[0]);
+  });
+  return createHash('sha256').update(JSON.stringify(normalized)).digest('hex');
+}
+export async function bindPodman(effects, record) {
+  if (effects.platform.platform !== 'linux' || process.getuid?.() === 0) throw new Error('Podman server installation requires a non-root Linux user');
+  const env = effects.env ?? {};
+  const provider = record.containerBinding?.provider ?? env.PODMAN_COMPOSE_PROVIDER;
+  if (!path(provider)) throw new Error('Set PODMAN_COMPOSE_PROVIDER to an absolute standalone Docker Compose executable path');
+  // Reject ambient redirection before even probing an unbound store.
+  for (const key of ['CONTAINER_HOST', 'CONTAINER_CONNECTION', 'CONTAINERS_STORAGE_CONF', 'CONTAINERS_CONF', 'PODMAN_USERNS', 'STORAGE_DRIVER', 'STORAGE_OPTS', 'DOCKER_CONTEXT']) {
+    if (env[key]) throw new Error(`${key} conflicts with local rootless Podman`);
+  }
+  const info = JSON.parse((await effects.run('podman', ['--remote=false', 'info', '--format', 'json'])).stdout);
+  if (info.host?.security?.rootless !== true) throw new Error('Podman must report rootless=true');
+  const socket = record.containerBinding?.socket ?? env.OURS_PODMAN_SOCKET ?? info.host.remoteSocket?.path;
+  const observed = { version: 1, uid: process.getuid(), graphRoot: info.store?.graphRoot, runRoot: info.store?.runRoot, driver: info.store?.graphDriverName, socket, provider, namespaceDigest: namespaceDigest(info) };
+  validateContainerEngine({ ...record, containerBinding: observed });
+  if (record.containerBinding && Object.keys(observed).some(k => observed[k] !== record.containerBinding[k])) throw new Error('Podman backend differs from retained installation');
+  podmanEnvironment({ ...record, containerBinding: observed }, env, process.getuid());
+  const api = JSON.parse((await effects.run('podman', ['--remote', '--url', `unix://${socket}`, 'info', '--format', 'json'])).stdout);
+  if (api.host?.security?.rootless !== true || api.store?.graphRoot !== observed.graphRoot || api.store?.runRoot !== observed.runRoot || api.store?.graphDriverName !== observed.driver || namespaceDigest(api) !== observed.namespaceDigest) throw new Error('Podman socket does not address the selected rootless storage; enable the user podman.socket');
+  const version = (await effects.run(provider, ['version', '--short'])).stdout.trim();
+  const match = /^v?(\d+)\.(\d+)\./.exec(version);
+  if (!match || +match[1] < 2 || (+match[1] === 2 && +match[2] < 35)) throw new Error('Standalone Docker Compose 2.35+ is required');
+  record.containerBinding = observed;
+}
+
+/** Resolve Compose rather than maintaining a second, drifting build definition. */
+export function nativeBuildCommands(config, services, env = {}) {
+  const commands = [], seen = new Set();
+  for (const name of services) {
+    const service = config.services?.[name], build = service?.build;
+    if (!build || typeof build !== 'object' || !path(build.context) || !service.image) throw new Error(`Missing resolved build definition for ${name}`);
+    const supported = ['context', 'dockerfile', 'target', 'args', 'secrets', 'cache_from', 'cache_to', 'platforms', 'labels', 'no_cache', 'pull'];
+    if (Object.keys(build).some(k => !supported.includes(k))) throw new Error(`Unsupported Podman build option for ${name}`);
+    const args = ['build', '--format', 'docker', '--layers', '--file', resolve(build.context, build.dockerfile ?? 'Dockerfile'), '--tag', service.image];
+    if (build.target) args.push('--target', build.target);
+    const platforms = build.platforms ?? (service.platform ? [service.platform] : []);
+    if (platforms.length > 1) throw new Error('Multi-platform Podman builds are not supported');
+    if (platforms.length) args.push('--platform', platforms[0]);
+    for (const [key, value] of Object.entries(build.args ?? {})) {
+      if (value === null) throw new Error(`Unresolved build argument: ${key}`);
+      args.push('--build-arg', `${key}=${value}`);
+    }
+    for (const [key, value] of Object.entries(build.labels ?? {})) args.push('--label', `${key}=${value}`);
+    for (const key of ['cache_from', 'cache_to']) for (const value of build[key] ?? []) args.push('--' + key.replace('_', '-'), value);
+    if (build.no_cache) args.push('--no-cache');
+    if (build.pull) args.push('--pull=always');
+    for (const secret of build.secrets ?? []) {
+      const source = typeof secret === 'string' ? secret : secret.source;
+      const id = typeof secret === 'string' ? source : secret.target ?? source;
+      const definition = config.secrets?.[source];
+      if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error('Invalid build secret ID');
+      if (definition?.environment) {
+        // Native local Podman supports type=env; values never enter argv/files.
+        if (env[definition.environment]) args.push('--secret', `id=${id},type=env,env=${definition.environment}`);
+      } else if (definition?.file && path(definition.file)) args.push('--secret', `id=${id},src=${definition.file}`);
+      else throw new Error(`Unsupported build secret: ${source}`);
+    }
+    args.push(build.context);
+    const key = JSON.stringify(args);
+    if (!seen.has(key)) { seen.add(key); commands.push(args); }
+  }
+  return commands;
+}

package/lib/diagnostics.mjs

@@ -0,0 +1 @@
+export { redactDiagnostic, commandFailure, installerFailure } from '../assets/scripts/runtime/diagnostics.mjs';

package/lib/docker-conversion-runtime.mjs

@@ -1,3 +1,4 @@
+import { runContainer } from './container-engine.mjs';
 import * as fs from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -33,7 +34,7 @@ ENTRYPOINT ["node", "/opt/ours/docker/state-operation.mjs"]
 `);
     // Build maintenance first: both targets inherit the same retained runtime.
     for (const target of ['maintenance', 'runtime']) {
-      await effects.run('docker', ['build', '--platform', 'linux/amd64', '--target', target,
+      await runContainer(effects, record, ['build', '--platform', 'linux/amd64', '--target', target,
         '--tag', `${record.project}:${target}`, context]);
     }
     atomicWriteConfig(compose, fs.readFileSync(join(assets, 'docker-compose.yaml')));
@@ -82,7 +83,7 @@ export async function runDockerConversion(record, selected, operation, label, ef
   const path = join(record.root, `.conversion-compose-${randomUUID()}.json`);
   try {
     fs.writeFileSync(path, JSON.stringify(definition), { mode: 0o600, flag: 'wx' });
-    const result = await effects.run('docker', ['compose', '--file', path, '--project-name', record.project,
+    const result = await runContainer(effects, record, ['compose', '--file', path, '--project-name', record.project,
       'run', '--rm', '--no-deps', '-T', 'state-operation', operation, ...(label ? [label] : [])]);
     if (operation === 'cleanup') {
       const summary = JSON.parse(result.stdout);

package/lib/docker-layout-installation.mjs

@@ -1,3 +1,4 @@
+import { runContainer } from './container-engine.mjs';
 import * as fs from 'node:fs';
 import { join, basename } from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -46,7 +47,7 @@ export async function convertDockerInstallation(record, operation, effects) {
   await effects.serverLifecycle(record, 'start', running);
   const cleanup = await effects.runDockerConversion(record, volumes, 'cleanup');
   if (cleanup.emptyVolumes.length) {
-    await effects.run('docker', ['volume', 'rm', ...cleanup.emptyVolumes.map(alias => volumes.sources[alias])]);
+    await runContainer(effects, record, ['volume', 'rm', ...cleanup.emptyVolumes.map(alias => volumes.sources[alias])]);
   }
   try {
     const stat = fs.lstatSync(source.configPath);

package/lib/docker-recovery.mjs

@@ -0,0 +1,55 @@
+import { readFileSync, lstatSync, realpathSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteConfig } from './config.mjs';
+import { engineName, runContainer } from './container-engine.mjs';
+
+const assets = new URL('../assets/', import.meta.url);
+const files = ['scripts/runtime/recover.mjs', 'scripts/runtime/dependency-ready.mjs',
+  ...['entrypoint.sh', 'start-telegram.sh', 'start-cowork.sh', 'start-messenger.sh'].map(f => `scripts/runtime/${f}`)];
+const owned = (path, directory = false) => {
+  const s = lstatSync(path);
+  if (!(directory ? s.isDirectory() : s.isFile()) || s.uid !== process.getuid() || (!directory && s.nlink !== 1)
+    || realpathSync(path) !== path || (s.mode & 0o7000)) throw new Error('Unsafe retained recovery delivery');
+};
+/** Refresh installer-owned runtime scripts without changing source selection or state. */
+export function refreshDockerRecovery(record) {
+  for (const dir of [record.root, record.workDir, join(record.workDir, 'scripts'), join(record.workDir, 'scripts/runtime')]) owned(dir, true);
+  const marker = join(record.workDir, '.recovery-rebuild');
+  let changed = false;
+  const replace = (name, bytes) => {
+    const path = join(record.workDir, name);
+    if (existsSync(path)) { owned(path); if (readFileSync(path).equals(bytes)) return; }
+    // Persist before edits, so interruption cannot reuse an image lacking recovery.
+    atomicWriteConfig(marker, 'required\n'); changed = true;
+    atomicWriteConfig(path, bytes.toString());
+  };
+  for (const name of files) replace(name, readFileSync(new URL(name, assets)));
+  const dockerfile = join(record.workDir, 'Dockerfile'); owned(dockerfile);
+  const text = readFileSync(dockerfile, 'utf8');
+  const line = 'COPY --chmod=644 scripts/runtime/recover.mjs scripts/runtime/dependency-ready.mjs /opt/ours/docker/';
+  if (!text.includes('scripts/runtime/recover.mjs')) replace('Dockerfile', Buffer.from(text.replace('FROM node:24 AS maintenance', `${line}\nFROM node:24 AS maintenance`)));
+  return changed || existsSync(marker);
+}
+
+/** An overlay also applies to retained Compose files, with one-shot jobs untouched. */
+export function recoveryCompose(record) {
+  return { services: Object.fromEntries(record.services.map(name => [name, { restart: 'unless-stopped' }])) };
+}
+
+/** Change only exact project-owned long-running containers; never start/recreate. */
+export async function reconcileDockerRecovery(record, effects) {
+  if (engineName(record) !== 'docker') return;
+  const query = await runContainer(effects, record, ['ps', '-aq', '--no-trunc', '--filter', `label=com.docker.compose.project=${record.project}`]);
+  const ids = query.stdout.split(/\s+/).filter(Boolean);
+  if (!ids.length) return;
+  const inspected = JSON.parse((await runContainer(effects, record, ['inspect', ...ids])).stdout);
+  const selected = [];
+  for (const c of inspected) {
+    const labels = c.Config?.Labels;
+    if (labels?.['com.docker.compose.project'] !== record.project) throw new Error('Recovery container project ownership differs');
+    if (!record.services.includes(labels['com.docker.compose.service']) || labels['com.docker.compose.oneoff']?.toLowerCase() !== 'false') continue;
+    if (!ids.includes(c.Id)) throw new Error('Recovery container identity differs');
+    if (c.HostConfig?.RestartPolicy?.Name !== 'unless-stopped') selected.push(c.Id);
+  }
+  if (selected.length) await runContainer(effects, record, ['update', '--restart', 'unless-stopped', ...selected]);
+}

package/lib/docker-runtime-repair.mjs

@@ -0,0 +1,160 @@
+import { engineName, runContainer } from './container-engine.mjs';
+/** Qualify cached images before reuse; repair only the known root-owned 0600 policy. */
+import { existsSync, readdirSync, lstatSync, readFileSync, writeFileSync, mkdtempSync, rmSync, realpathSync, openSync, closeSync, fstatSync, fchmodSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { atomicWriteConfig } from './config.mjs';
+
+const policyPath = '/opt/ours/sources.json';
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const fail = message => { throw new Error(`Docker runtime verification refused: ${message}`); };
+const imageId = value => /^sha256:[0-9a-f]{64}$/.test(value ?? '');
+
+export function refreshDockerPolicyCopy(record) {
+  let rebuildScripts = false;
+  if (record.workDir !== join(record.root, 'runtime')) fail('Unsafe retained Dockerfile: runtime directory differs from installation record');
+  for (const directory of [record.root, record.workDir]) {
+    const stat = lstatSync(directory);
+    if (!stat.isDirectory() || realpathSync(directory) !== directory) fail('Unsafe retained Dockerfile: installation directory is linked or not canonical');
+    if (stat.uid !== process.getuid()) fail('Unsafe retained Dockerfile: installation directory belongs to another user');
+    if (stat.mode & 0o7077) fail('Unsafe retained Dockerfile: installation directory must be owner-private (0700)');
+  }
+  const path = join(record.workDir, 'Dockerfile');
+  let fd;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { fail(`Unsafe retained Dockerfile: cannot open a regular unlinked file (${error.code})`); }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) fail('Unsafe retained Dockerfile: expected a regular file');
+    if (stat.nlink !== 1) fail('Unsafe retained Dockerfile: hard links are not supported');
+    if (stat.uid !== process.getuid()) fail(`Unsafe retained Dockerfile: file owner ${stat.uid} differs from current user ${process.getuid()}`);
+    if (stat.mode & 0o7000) fail('Unsafe retained Dockerfile: special permission bits are not supported');
+    // Asset copies can retain 0664 under umask 002. Private canonical ancestors
+    // exclude other users; normalize this owned inode without following links.
+    fchmodSync(fd, 0o600);
+    const text = readFileSync(fd, 'utf8');
+    const current = lstatSync(path);
+    if (current.dev !== stat.dev || current.ino !== stat.ino || current.nlink !== 1) fail('Unsafe retained Dockerfile: file changed during normalization');
+    const oldLine = /^COPY sources\.json \/opt\/ours\/sources\.json$/m;
+    let updated = text.replace(oldLine, 'COPY --chmod=644 sources.json /opt/ours/sources.json');
+    // Only the shipped script COPY instructions are normalized. Existing image
+    // repair remains narrow; a private build context needs an actual rebuild.
+    const beforeScripts = updated;
+    const shipped = readFileSync(new URL('../assets/Dockerfile', import.meta.url), 'utf8');
+    const scriptCopies = new Map(shipped.split('\n').filter(line => line.startsWith('COPY --chmod=644 scripts/')).map(line => [line.replace(' --chmod=644', ''), line]));
+    updated = updated.split('\n').map(line => scriptCopies.get(line) || line).join('\n');
+    if (updated !== beforeScripts) {
+      for (const directory of ['scripts/maintenance', 'scripts/runtime']) {
+        const base = join(record.workDir, directory);
+        const dir = lstatSync(base);
+        if (!dir.isDirectory() || dir.uid !== process.getuid() || realpathSync(base) !== base) fail('Unsafe retained scripts directory');
+        for (const name of readdirSync(base)) {
+          if (!/\.(?:mjs|sh)$/.test(name)) continue;
+          const file = join(base, name), st = lstatSync(file);
+          if (!st.isFile() || st.nlink !== 1 || st.uid !== process.getuid() || realpathSync(file) !== file) fail('Unsafe retained script file');
+          if (!(st.mode & 0o004)) rebuildScripts = true;
+        }
+      }
+    }
+    // Store the need across an interrupted build. It is cleared only after the
+    // rebuilt image passes the same nonroot release/runtime qualification.
+    const marker = join(record.workDir, '.script-permissions-rebuild');
+    if (rebuildScripts) atomicWriteConfig(marker, 'required\n');
+    if (updated !== text) atomicWriteConfig(path, updated);
+    return rebuildScripts || existsSync(marker);
+  } finally { closeSync(fd); }
+}
+
+const probeScript = `
+const fs = require('node:fs'), crypto = require('node:crypto');
+(async () => {
+  const path = '${policyPath}', s = fs.lstatSync(path);
+  if (!s.isFile() || s.nlink !== 1 || s.uid !== 0 || s.gid !== 0 || ![0o600, 0o644].includes(s.mode & 0o7777)) throw new Error('Unsupported policy ownership/type/mode');
+  let bytes;
+  try { bytes = fs.readFileSync(path); }
+  catch (error) { if (process.getuid() !== 0 && error.code === 'EACCES') { process.exitCode = 74; return; } throw error; }
+  const graph = await import('/opt/ours/maintenance/release-graph.mjs');
+  graph.verifyRuntimeRelease('/opt/ours');
+  const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+  const records = {};
+  for (const name of ['package.json', 'package-lock.json', 'dependency-tree.json', 'build-context.json']) {
+    const file = '/opt/ours/' + name, stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.nlink !== 1) throw new Error('Unsupported build record');
+    records[name] = hash(fs.readFileSync(file));
+  }
+  console.log(JSON.stringify({ uid: s.uid, gid: s.gid, regular: true, links: s.nlink, mode: s.mode & 0o7777, policyHash: hash(bytes), records }));
+})().catch(error => { console.error(error.message); process.exitCode = 1; });
+`;
+
+export async function qualifyDockerRuntime(record, effects) {
+  if (!/^ours-[a-z0-9-]+$/.test(record.project ?? '')) fail('unexpected installation project');
+  const uid = record.uid ?? 1000, gid = record.gid ?? 1000;
+  if (![uid, gid].every(n => Number.isInteger(n) && n > 0)) fail('non-root runtime UID/GID required');
+  const tag = `${record.project}:runtime`;
+  const inspect = async target => {
+    const { stdout } = await runContainer(effects, record, ['image', 'inspect', target], { timeout: 60000 });
+    const [value] = JSON.parse(stdout);
+    if (!imageId(value?.Id) || !Array.isArray(value.RootFS?.Layers) || value.Config?.Labels?.['network.ours.build-context'] !== '1') fail('image lacks recognized build metadata');
+    return value;
+  };
+  const probe = async (id, user) => {
+    const name = `ours-runtime-probe-${randomUUID()}`;
+    try {
+      const result = await runContainer(effects, record, ['run', '--rm', '--name', name, '--read-only', '--network', 'none', '--cap-drop', 'ALL',
+        '--security-opt', 'no-new-privileges:true', '--pids-limit', '64', '--memory', '256m', '--user', user, '--entrypoint', 'node', id, '-e', probeScript],
+      { allowCodes: [1, 74], timeout: 60000 });
+      return { code: result.code, report: result.code === 0 ? JSON.parse(result.stdout) : null };
+    } catch (error) {
+      // A killed Docker client can leave its own bounded probe container behind.
+      try { await runContainer(effects, record, ['rm', '-f', name], { allowCodes: [1], timeout: 10000 }); } catch {}
+      throw error;
+    }
+  };
+  const policy = readFileSync(record.sourcesPath), expectedHash = digest(policy);
+  const check = (report, mode, stage) => {
+    const expected = { mode, uid: 0, gid: 0, regular: true, links: 1, policyHash: expectedHash };
+    const mismatched = Object.keys(expected).filter(key => report?.[key] !== expected[key]);
+    if (mismatched.length) {
+      // Only fixed field names, a bounded numeric mode and a comparison boolean
+      // enter diagnostics. Never disclose policy content, hashes or probe output.
+      const observedMode = Number.isInteger(report?.mode) && report.mode >= 0 && report.mode <= 0o7777
+        ? report.mode.toString(8).padStart(4, '0') : 'invalid';
+      fail(`image policy verification failed (stage=${stage}; engine=${engineName(record)}; mismatched=${mismatched.join(',')}; mode=${observedMode}; expectedMode=${mode.toString(8).padStart(4, '0')}; policyMatch=${report?.policyHash === expectedHash})`);
+    }
+  };
+  const original = await inspect(tag);
+  const ordinary = await probe(original.Id, `${uid}:${gid}`);
+  if (ordinary.code === 0) { check(ordinary.report, 0o644, 'ordinary'); return; }
+  if (ordinary.code !== 74) fail('cached image is unusable; automatic repair only supports the known source-policy permission defect');
+  const privileged = await probe(original.Id, '0:0');
+  if (privileged.code !== 0) fail('original release graph could not be verified');
+  check(privileged.report, 0o600, 'privileged');
+  effects.out?.('Repairing cached Docker image permissions; keeping the selected packages and stored data.');
+  const directory = mkdtempSync(join(record.root, '.image-permissions-'));
+  const name = `ours-permission-repair-${randomUUID()}`, baseTag = `${name}:base`, candidateTag = `${name}:candidate`;
+  try {
+    // Unique local alias transports the immutable ID into BuildKit. The resulting
+    // layer ancestry and complete execution config are checked before publication.
+    await runContainer(effects, record, ['image', 'tag', original.Id, baseTag]);
+    if ((await inspect(baseTag)).Id !== original.Id) fail('repair base image changed');
+    writeFileSync(join(directory, 'sources.json'), policy, { mode: 0o600, flag: 'wx' });
+    writeFileSync(join(directory, 'Dockerfile'), `FROM ${baseTag}\nCOPY --chmod=644 sources.json ${policyPath}\n`, { mode: 0o600, flag: 'wx' });
+    await runContainer(effects, record, ['build', '--network=none', '--pull=false', '--tag', candidateTag, directory], { stream: true, timeout: 120000 });
+    const candidate = await inspect(candidateTag);
+    if (!isDeepStrictEqual(candidate.Config, original.Config) || !isDeepStrictEqual(candidate.RootFS.Layers.slice(0, original.RootFS.Layers.length), original.RootFS.Layers)
+        || candidate.RootFS.Layers.length !== original.RootFS.Layers.length + 1) fail('repair changed image execution settings or ancestry');
+    const verified = await probe(candidate.Id, `${uid}:${gid}`);
+    if (verified.code !== 0) fail('repaired image did not pass runtime verification');
+    check(verified.report, 0o644, 'repaired');
+    if (!isDeepStrictEqual(verified.report.records, privileged.report.records)) fail('repair changed build provenance');
+    if ((await inspect(tag)).Id !== original.Id) fail('selected image changed during repair; retry setup');
+    await runContainer(effects, record, ['image', 'tag', candidate.Id, tag]);
+    effects.out?.('Cached Docker image repaired and verified; continuing setup.');
+  } finally {
+    for (const temporary of [candidateTag, baseTag]) {
+      try { await runContainer(effects, record, ['image', 'rm', temporary], { allowCodes: [1], timeout: 10000 }); } catch {}
+    }
+    rmSync(directory, { recursive: true, force: true });
+  }
+}