johns-harness 2026.9.17 → 2026.9.18

package/README.md

@@ -73,8 +73,8 @@ node johnness.mjs --help
 ### Verify
 
 ```bash
-npm test                        # 827 tests against the installed dependency tree
-bash scripts/verify-patches.sh  # 405 checks across every patch family
+npm test                        # 850 tests against the installed dependency tree
+bash scripts/verify-patches.sh  # 417 checks across every patch family
 ```
 
 ## Launch a swarm with one command
@@ -187,7 +187,7 @@ The log is a [`RULES.md`](RULES.md) workspace convention enforced through the ac
 
 ## Patch families
 
-The runtime carries 65 patch families. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 405 checks against the package tree and installed dependencies, and 827 tests run against the installed dependency tree.
+The runtime carries 65 patch families plus the 65.1 safe-update amendment. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 417 checks against the package tree and installed dependencies, and 850 tests run against the installed dependency tree.
 
 Every family follows the same six steps: reproduce the failure, trace the exact runtime path, make the smallest source-level change that restores the invariant, add a regression test and a patch marker, run the verifier, and retain rollback artifacts. The full index: [`docs/PATCHES.md`](docs/PATCHES.md).
 

package/dist/gateway-cli-B7fBU7gD.js

@@ -1,3 +1,5 @@
+// JOHNNESS_PATCH_SAFE_VOLUME_UPDATE_65_1
+import { readInstalledVersion as readUpdatedRuntimeVersion } from "./update-command.js";
 // JOHNNESS_PATCH_CATALOG_REFRESH_65
 import { refreshJohnnessCatalog65 } from "./catalog-refresh.js";
 import { g as resolveStateDir, i as isNixMode, l as resolveGatewayLockDir, o as resolveConfigPath, r as STATE_DIR, t as CONFIG_PATH, u as resolveGatewayPort } from "./paths-BJV7vkaX.js";
@@ -21754,6 +21756,10 @@ async function scheduleRestartSentinelWake(_params) {
 	const sentinel = await consumeRestartSentinel();
 	if (!sentinel) return;
 	const payload = sentinel.payload;
+	if (payload.stats?.mode === "chat.update") {
+		const running = readUpdatedRuntimeVersion();
+		payload.message = running === payload.stats.targetVersion ? `johns-harness is now on ${running}. The new runtime has booted.` : `Update restart complete. Running johns-harness ${running}; requested ${payload.stats.targetVersion ?? "unknown"}.`;
+	}
 	const sessionKey = payload.sessionKey?.trim();
 	const message = formatRestartSentinelMessage(payload);
 	const summary = summarizeRestartSentinel(payload);

package/dist/gateway-cli-BCNMwzNq.js

@@ -1,3 +1,5 @@
+// JOHNNESS_PATCH_SAFE_VOLUME_UPDATE_65_1
+import { readInstalledVersion as readUpdatedRuntimeVersion } from "./update-command.js";
 // JOHNNESS_PATCH_CATALOG_REFRESH_65
 import { refreshJohnnessCatalog65 } from "./catalog-refresh.js";
 import { a as logVerbose, d as colorize, f as isRich, g as getResolvedLoggerSettings, h as getLogger, m as getChildLogger, p as theme, s as setVerbose } from "./globals-Bv4ZcVWM.js";
@@ -21756,6 +21758,10 @@ async function scheduleRestartSentinelWake(_params) {
 	const sentinel = await consumeRestartSentinel();
 	if (!sentinel) return;
 	const payload = sentinel.payload;
+	if (payload.stats?.mode === "chat.update") {
+		const running = readUpdatedRuntimeVersion();
+		payload.message = running === payload.stats.targetVersion ? `johns-harness is now on ${running}. The new runtime has booted.` : `Update restart complete. Running johns-harness ${running}; requested ${payload.stats.targetVersion ?? "unknown"}.`;
+	}
 	const sessionKey = payload.sessionKey?.trim();
 	const message = formatRestartSentinelMessage(payload);
 	const summary = summarizeRestartSentinel(payload);

package/dist/runtime-integrity.js

@@ -0,0 +1,53 @@
+// JOHNNESS_PATCH_SAFE_VOLUME_UPDATE_65_1
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+export const RECEIPT = '.johnness-runtime-integrity.json';
+export const packageRootForPrefix = (prefix, platform = process.platform) => path.join(prefix, platform === 'win32' ? '' : 'lib', 'node_modules', 'johns-harness');
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const safeRelative = name => typeof name === 'string' && name.length > 0 && !path.isAbsolute(name) && !name.startsWith('node_modules/') && name !== 'node_modules' && !name.split(/[\\/]/).some(p => p === '..' || p === '');
+export function inventoryPackage(root) {
+  const files = [];
+  function walk(dir) {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a,b) => a.name.localeCompare(b.name))) {
+      if ((e.name === 'node_modules' && dir === root) || e.name === '.git') continue;
+      const file = path.join(dir, e.name);
+      if (e.isSymbolicLink()) throw new Error('Package artifact contains a symlink');
+      if (e.isDirectory()) walk(file);
+      else if (e.isFile()) { const bytes = fs.readFileSync(file); files.push([path.relative(root, file).split(path.sep).join('/'), bytes.length, hash(bytes)]); }
+    }
+  }
+  walk(root);
+  return files;
+}
+export function validateRuntimeTree(root, { receipt, expectedVersion, legacy = true } = {}) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name !== 'johns-harness' || !pkg.version || (expectedVersion && pkg.version !== expectedVersion)) throw new Error('package version mismatch');
+    for (const rel of ['johnness.mjs', 'dist/entry.js', 'extensions/telegram/index.ts']) {
+      const stat = fs.lstatSync(path.join(root, rel));
+      if (!stat.isFile() || stat.size === 0) throw new Error(`missing or empty entry: ${rel}`);
+    }
+    if (!receipt && !legacy) throw new Error('integrity receipt missing');
+    if (receipt) {
+      if (receipt.version !== pkg.version || !Array.isArray(receipt.files) || !receipt.files.length) throw new Error('invalid integrity receipt');
+      const seen = new Set();
+      for (const [rel, size, digest] of receipt.files) {
+        if (!safeRelative(rel) || seen.has(rel) || !Number.isSafeInteger(size) || size < 0 || !/^[a-f0-9]{64}$/.test(digest)) throw new Error('unsafe integrity entry');
+        seen.add(rel);
+        const stat = fs.lstatSync(path.join(root, rel));
+        if (!stat.isFile() || stat.size !== size) throw new Error(`incomplete artifact: ${rel}`);
+        if (hash(fs.readFileSync(path.join(root, rel))) !== digest) throw new Error(`artifact hash mismatch: ${rel}`);
+      }
+      for (const rel of ['package.json','johnness.mjs','dist/entry.js','extensions/telegram/index.ts']) if (!seen.has(rel)) throw new Error('incomplete receipt coverage');
+    }
+    return { ok: true, version: pkg.version };
+  } catch (error) { return { ok: false, reason: error.code ?? error.message }; }
+}
+export function inspectPrefix(prefix, platform = process.platform) {
+  let receipt;
+  const receiptFile = path.join(prefix, RECEIPT);
+  try { if (fs.existsSync(receiptFile)) receipt = JSON.parse(fs.readFileSync(receiptFile, 'utf8')); }
+  catch { return { ok: false, reason: 'invalid integrity receipt' }; }
+  return validateRuntimeTree(packageRootForPrefix(prefix, platform), { receipt });
+}

package/dist/runtime-path.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// JOHNNESS_PATCH_SAFE_VOLUME_UPDATE_65_1
+import { inspectPrefix } from "./runtime-integrity.js";
 // JOHNNESS_PATCH_UPDATE_COMMAND_62
 // `johnness-runtime-path`: print the johnness executable an entrypoint should exec.
 // Prefers the volume runtime installed by `/update` at
@@ -45,9 +47,13 @@ export function resolveRuntimePath({ env = process.env, imageRoot = path.resolve
   const volumeRoot = path.join(prefix, platform === "win32" ? "" : "lib", "node_modules", PACKAGE);
   const volumeBin = path.join(volumeRoot, "johnness.mjs");
   const volumeVersion = readVersion(volumeRoot);
-  if (!volumeVersion || !fs.existsSync(volumeBin)) return { bin: imageBin, source: "image", version: imageVersion };
-  if (imageVersion && compare(volumeVersion, imageVersion) < 0) return { bin: imageBin, source: "image", version: imageVersion, skipped: volumeVersion };
-  return { bin: volumeBin, source: "volume", version: volumeVersion };
+  const candidates = [[prefix, "volume"], [prefix + ".previous", "previous"]];
+  for (const [candidate, source] of candidates) {
+    const checked = inspectPrefix(candidate, platform);
+    if (!checked.ok || (imageVersion && compare(checked.version, imageVersion) < 0)) continue;
+    return { bin: path.join(candidate, platform === "win32" ? "" : "lib", "node_modules", PACKAGE, "johnness.mjs"), source, version: checked.version };
+  }
+  return { bin: imageBin, source: "image", version: imageVersion, ...(volumeVersion ? { skipped: volumeVersion } : {}) };
 }
 
 const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);

package/dist/update-cli-Cm_l3W29.js

@@ -1,3 +1,4 @@
+// JOHNNESS_PATCH_SAFE_VOLUME_UPDATE_65_1
 import { p as theme } from "./globals-Bv4ZcVWM.js";
 import { g as resolveStateDir, n as DEFAULT_GATEWAY_PORT, u as resolveGatewayPort } from "./paths-BfR2LXbA.js";
 import { f as defaultRuntime } from "./subsystem-Cf9yS0UI.js";
@@ -1049,6 +1050,7 @@ async function maybeRestartService(params) {
 	}
 }
 async function updateCommand(opts) {
+	if (await (await import("./update-command.js")).maybeHandleVolumeCliUpdate(opts, { exit: code => { process.exitCode = code; } })) return;
 	suppressDeprecations();
 	const timeoutMs = parseTimeoutMsOrExit(opts.timeout);
 	const shouldRestart = opts.restart !== false;

package/dist/update-command.js

@@ -1,3 +1,5 @@
+// JOHNNESS_PATCH_SAFE_VOLUME_UPDATE_65_1
+import { installVolumeRuntime } from "./volume-update.js";
 // JOHNNESS_PATCH_UPDATE_COMMAND_62
 // Owner-only `/update` chat command: install a newer johns-harness on the host the
 // gateway runs on, then restart into it. Two install targets, chosen automatically:
@@ -102,6 +104,7 @@ export function installArgv(target, spec) {
 }
 
 export function manualCommand(target, spec) {
+  if (target.mode === "volume") return `node ${JSON.stringify(path.join(path.dirname(installedPackageJson(target)), "johnness.mjs"))} update --tag ${spec.slice(spec.lastIndexOf("@") + 1)} --no-restart`;
   return installArgv(target, spec).join(" ");
 }
 
@@ -143,7 +146,10 @@ export async function runChatInstall({ tag, env = process.env, packageRoot, time
   const manual = manualCommand(target, spec);
   if (!target.prefix) return { ok: false, target, spec, manual, tail: "Could not detect an npm prefix for the running install." };
   const runUpdateStep = deps.runUpdateStep ?? (await loadUpdater()).runUpdateStep;
-  if (target.mode === "volume") await fsp.mkdir(target.prefix, { recursive: true });
+  if (target.mode === "volume") {
+    const result = await (deps.installVolumeRuntime ?? installVolumeRuntime)({ target, tag, packageRoot, timeoutMs, runUpdateStep, env, deps });
+    return { ...result, target, spec, manual };
+  }
   const step = await runUpdateStep({ name: "npm install", argv: installArgv(target, spec), timeoutMs });
   if (step.exitCode !== 0) return { ok: false, target, spec, manual, tail: redactTail(`${step.stdoutTail ?? ""}\n${step.stderrTail ?? ""}`) };
   let installedVersion = null;
@@ -154,6 +160,24 @@ export async function runChatInstall({ tag, env = process.env, packageRoot, time
   return { ok: true, target, spec, manual, installedVersion };
 }
 
+export async function maybeHandleVolumeCliUpdate(opts, deps = {}) {
+  const env = deps.env ?? process.env;
+  const target = resolveUpdatePrefix({ env, packageRoot: deps.packageRoot });
+  if (target.mode !== "volume") return false;
+  const log = deps.log ?? console.log, error = deps.error ?? console.error;
+  const tag = opts.tag ?? "latest";
+  if ((opts.channel && opts.channel !== "stable") || (tag !== "latest" && !VERSION_RE.test(tag))) {
+    error("Volume updates require --tag latest or an exact release version; the serving runtime was not changed.");
+    (deps.exit ?? (code => { process.exitCode = code; }))(1); return true;
+  }
+  if (opts.dryRun) { log(JSON.stringify({ dryRun: true, mode: "volume", prefix: target.prefix, stagesAndVerifies: true, ephemeralCache: true, keepsPreviousTree: false })); return true; }
+  const result = await runChatInstall({ tag, env, packageRoot: deps.packageRoot, deps, timeoutMs: deps.timeoutMs });
+  if (!result.ok) { error(redactTail(result.tail)); (deps.exit ?? (code => { process.exitCode = code; }))(1); return true; }
+  if (opts.json) log(JSON.stringify({ ok: true, version: result.installedVersion, prefix: target.prefix, restartRequired: true }));
+  else log(`Installed johns-harness ${result.installedVersion} safely. Restart the gateway supervisor to use it; no configuration was changed.`);
+  return true;
+}
+
 function buildRoute(params) {
   return {
     channel: params.ctx?.OriginatingChannel || params.command?.channel,
@@ -175,7 +199,7 @@ function buildRoute(params) {
 export async function restartIntoUpdate({ target, deps, log = console.info, exit = (code) => process.exit(code) }) {
   if (target.mode === "volume") {
     log("[update] volume runtime installed; exiting 75 for supervisor restart into the new runtime");
-    setTimeout(() => exit(75), 1500).unref?.();
+    setTimeout(() => (deps.exit ?? exit)(75), 1500).unref?.();
     return "supervisor";
   }
   try {
@@ -249,10 +273,10 @@ export async function handleUpdateCommand(params, allowTextCommands, { routeRepl
             status: "ok",
             ts: Date.now(),
             sessionKey: params.sessionKey,
-            deliveryContext: delivery?.deliveryContext,
-            threadId: delivery?.threadId,
+            deliveryContext: delivery?.deliveryContext ?? { channel: route.channel, to: route.to, accountId: route.accountId },
+            threadId: delivery?.threadId ?? route.threadId,
             message: `Updated johns-harness ${current} -> ${result.installedVersion} (${result.target.mode} prefix ${result.target.prefix}).`,
-            stats: { mode: "chat.update", reason: "/update" },
+            stats: { mode: "chat.update", reason: "/update", targetVersion: result.installedVersion },
           });
         } catch {}
       }
@@ -260,7 +284,7 @@ export async function handleUpdateCommand(params, allowTextCommands, { routeRepl
       const restartText = how === "supervisor"
         ? "Restarting through the supervisor; the entrypoint will start the new runtime."
         : how === "service" ? "Restarting the gateway service." : how === "gateway" ? "Restarting the gateway." : "Restart the gateway to finish (johnness gateway restart).";
-      await deliver(`Installed johns-harness ${result.installedVersion} into ${result.target.prefix}. ${restartText} I will confirm the running version when I am back.`);
+      if (result.target.mode !== "volume") await deliver(`Installed johns-harness ${result.installedVersion} into ${result.target.prefix}. ${restartText} I will confirm the running version when I am back.`);
     } catch (error) {
       await deliver(`Update failed: ${redactTail(error?.message ?? String(error), 5)}\nFix by hand: ${manualCommand(target, `${PACKAGE}@${targetVersion}`)}`);
     } finally {

package/dist/volume-update.js

@@ -0,0 +1,208 @@
+// JOHNNESS_PATCH_SAFE_VOLUME_UPDATE_65_1
+// Stage and verify first. Never run npm against the serving prefix.
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { x as extract, t as listTar } from 'tar';
+import { RECEIPT, inventoryPackage, packageRootForPrefix, validateRuntimeTree } from './runtime-integrity.js';
+
+const MB = 1024 * 1024;
+const sha = value => createHash('sha256').update(value).digest('hex');
+const exists = file => fs.existsSync(file);
+const within = (parent, child) => { const r = path.relative(path.resolve(parent), path.resolve(child)); return r === '' || (!r.startsWith('..'+path.sep) && r !== '..' && !path.isAbsolute(r)); };
+const readJson = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+
+export async function scanDependencies(root) {
+  const result = { bytes: 0, files: 0, dirs: 0, empty: new Set() };
+  if (!exists(root)) return result;
+  async function walk(dir) {
+    for (const e of await fsp.readdir(dir, { withFileTypes: true })) {
+      const file = path.join(dir, e.name);
+      if (e.isDirectory()) { result.dirs++; await walk(file); }
+      else if (e.isFile()) { const st = await fsp.stat(file); result.files++; result.bytes += st.size; if (!st.size) result.empty.add(path.relative(root, file)); }
+    }
+  }
+  await walk(root);
+  return result;
+}
+export async function verifyEmptyDependencies(root, empty, { fetchImpl = fetch, scratch, signal } = {}) {
+  const manifests = new Map();
+  for (const rel of empty) {
+    let dir = path.dirname(path.join(root, rel));
+    while (within(root, dir) && !exists(path.join(dir, 'package.json'))) dir = path.dirname(dir);
+    if (!within(root, dir)) throw new Error(`Unexpected empty dependency file: ${rel}`);
+    const pkg = readJson(path.join(dir, 'package.json')), member = 'package/' + path.relative(dir, path.join(root, rel)).split(path.sep).join('/');
+    const key = pkg.name + '@' + pkg.version;
+    if (!manifests.has(key)) {
+      const metaRes = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(pkg.name)}/${encodeURIComponent(pkg.version)}`, { signal });
+      if (!metaRes.ok) throw new Error('Cannot authenticate empty dependency fixtures');
+      const meta = await metaRes.json(), url = new URL(meta.dist?.tarball);
+      if (meta.name !== pkg.name || meta.version !== pkg.version || url.origin !== 'https://registry.npmjs.org' || !/^sha512-[A-Za-z0-9+/]+=*$/.test(meta.dist?.integrity ?? '')) throw new Error('Invalid dependency fixture metadata');
+      const res = await fetchImpl(url.href, { signal });
+      if (!res.ok) throw new Error('Cannot fetch dependency fixture manifest');
+      const archive = path.join(scratch, 'dependency-' + sha(key) + '.tgz');
+      const digest = createHash('sha512'); let received = 0;
+      await pipeline(Readable.fromWeb(res.body), new Transform({ transform(chunk, _enc, cb) { received += chunk.length; if (received > 512*MB) return cb(new Error('Dependency archive too large')); digest.update(chunk); cb(null, chunk); } }), fs.createWriteStream(archive, { flags: 'wx', mode: 0o600 }));
+      if ('sha512-' + digest.digest('base64') !== meta.dist.integrity) throw new Error('Dependency fixture integrity mismatch');
+      const allowed = new Set();
+      await listTar({ file: archive, strict: true, onReadEntry: entry => { if (entry.type === 'File' && entry.size === 0) allowed.add(entry.path); } });
+      await fsp.unlink(archive); manifests.set(key, allowed);
+    }
+    if (!manifests.get(key).has(member)) throw new Error(`Unexpected empty dependency file: ${rel}`);
+  }
+  return [...empty].sort();
+}
+export function requiredVolumeBytes({ tarballBytes, unpackedBytes, packageFiles = 0, dependencyBytes = 0, dependencyFiles = 0, dependencyDirs = 0, reuse = false }) {
+  return Math.ceil(Math.max(tarballBytes * 3, unpackedBytes + packageFiles * 4096 + 16 * MB + (reuse ? dependencyFiles * 512 + dependencyDirs * 4096 : dependencyBytes * 1.25)));
+}
+function matchingContract(oldRoot, nextRoot) {
+  try {
+    const a = readJson(path.join(oldRoot, 'package.json')), b = readJson(path.join(nextRoot, 'package.json'));
+    for (const key of ['dependencies','optionalDependencies','peerDependencies','engines']) if (JSON.stringify(a[key]) !== JSON.stringify(b[key])) return false;
+    // Only the known, identical postinstall may run against a link-cloned dependency tree.
+    for (const rel of ['scripts/postinstall.mjs','dist/migrate-plugin-adapters.js','dist/migrate-plan.js']) if (sha(fs.readFileSync(path.join(oldRoot, rel))) !== sha(fs.readFileSync(path.join(nextRoot, rel)))) return false;
+    return true;
+  } catch { return false; }
+}
+function mutableDependencyFiles(artifact) {
+  const mutable = new Set();
+  const vendor = path.join(artifact, 'vendor/patched-deps');
+  if (!exists(vendor)) return mutable;
+  function walk(dir) {
+    const manifest = path.join(dir, 'package.json');
+    if (exists(manifest)) {
+      const pkg = readJson(manifest);
+      for (const [rel] of inventoryPackage(dir)) if (rel !== 'package.json') mutable.add(path.join(pkg.name, rel));
+      return;
+    }
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) if (e.isDirectory()) walk(path.join(dir, e.name));
+  }
+  walk(vendor);
+  return mutable;
+}
+export async function cloneDependencies(source, target, mutable = new Set()) {
+  async function walk(dir, dest) {
+    await fsp.mkdir(dest, { recursive: true });
+    for (const e of await fsp.readdir(dir, { withFileTypes: true })) {
+      const from = path.join(dir, e.name), to = path.join(dest, e.name), rel = path.relative(source, from);
+      if (e.isDirectory()) await walk(from, to);
+      else if (e.isSymbolicLink()) {
+        if (rel === 'mr-memory' || [...mutable].some(p => p === rel || p.startsWith(rel+path.sep))) throw new Error('Mutable dependency is a symlink; fresh dependency install required');
+        await fsp.symlink(await fsp.readlink(from), to);
+      } else if (e.isFile()) {
+        const memoryAdapterFile = rel.startsWith('mr-memory'+path.sep) && !rel.startsWith(path.join('mr-memory','node_modules')+path.sep);
+        if (mutable.has(rel) || memoryAdapterFile) await fsp.copyFile(from, to);
+        else await fsp.link(from, to);
+      }
+    }
+  }
+  await walk(source, target);
+}
+function assertHealthy(root, receipt, version) {
+  const result = validateRuntimeTree(root, { receipt, expectedVersion: version, legacy: false });
+  if (!result.ok) throw new Error(`Incomplete staged runtime: ${result.reason}`);
+}
+function assertStep(step) {
+  if (step.exitCode !== 0 || /ENOSPC|TAR_ENTRY_ERROR|no space left on device/i.test(`${step.stderrTail??''}\n${step.stdoutTail??''}`)) throw new Error('Install step failed or reported incomplete extraction; serving runtime preserved');
+}
+
+export async function installVolumeRuntime({ target, tag, packageRoot, timeoutMs = 20*60000, runUpdateStep, env = process.env, deps = {} }) {
+  const prefix = path.resolve(target.prefix), parent = path.dirname(prefix);
+  const current = packageRootForPrefix(prefix), sourceRoot = exists(current) ? current : packageRoot;
+  const stage = prefix + '.stage-' + randomUUID(), previous = prefix + '.previous';
+  const lockPath = prefix + '.update.lock';
+  const rename = deps.rename ?? fsp.rename, remove = deps.remove ?? fsp.rm;
+  const fetchImpl = deps.fetch ?? fetch;
+  let lock, scratch, cache, response, promoted = false, previousMoved = false, recordWritten = false, cleanupStarted = false;
+  const recordPath = prefix + ".previous-version.json";
+  const previousRecord = exists(recordPath) ? await fsp.readFile(recordPath) : null;
+  try {
+    await fsp.mkdir(parent, { recursive: true });
+    lock = await fsp.open(lockPath, 'wx', 0o600);
+    await lock.writeFile(JSON.stringify({ pid: process.pid, startedAt: Date.now(), version: tag }));
+    if (exists(previous)) throw new Error('A previous interrupted update needs recovery before another install');
+    const signal = AbortSignal.timeout(timeoutMs);
+    const metadataResponse = await fetchImpl(`https://registry.npmjs.org/johns-harness/${encodeURIComponent(tag)}`, { signal });
+    if (!metadataResponse.ok) throw new Error(`Registry metadata HTTP ${metadataResponse.status} (E${metadataResponse.status})`);
+    const meta = await metadataResponse.json();
+    if (meta.name !== 'johns-harness' || !/^\d{4}\.\d{1,2}\.\d{1,2}(?:-[\w.-]+)?$/.test(meta.version) || (tag !== 'latest' && meta.version !== tag)) throw new Error('Registry package/version mismatch');
+    const url = new URL(meta.dist?.tarball);
+    if (url.origin !== 'https://registry.npmjs.org' || !/^sha512-[A-Za-z0-9+/]+=*$/.test(meta.dist?.integrity??'')) throw new Error('Registry artifact integrity metadata invalid');
+    response = await fetchImpl(url.href, { signal, headers: { 'accept-encoding': 'identity' } });
+    if (!response.ok) throw new Error(`Registry artifact HTTP ${response.status}`);
+    const tarballBytes = Number(response.headers.get('content-length'));
+    if (!Number.isSafeInteger(tarballBytes) || tarballBytes <= 0 || tarballBytes > 512*MB) throw new Error('Cannot establish a safe tarball size');
+    const available = async () => { const s = await (deps.statfs ?? fsp.statfs)(parent); return Number(s.bavail)*Number(s.bsize); };
+    const insistSpace = async required => { const free = await available(); if (free < required) throw new Error(`Insufficient volume space: need ${Math.ceil(required/MB)} MiB free, have ${Math.floor(free/MB)} MiB. Free at least ${Math.ceil((required-free)/MB)} MiB; live runtime untouched.`); };
+    await insistSpace(tarballBytes * 3);
+    scratch = await fsp.mkdtemp(path.join(deps.tempRoot ?? os.tmpdir(), 'johnness-update-'));
+    if (within(parent, scratch) || (env.JOHNNESS_STATE_DIR && within(env.JOHNNESS_STATE_DIR, scratch))) throw new Error('Update scratch/cache must be outside the persistent state volume');
+    cache = path.join(scratch, 'npm-cache');
+    await fsp.mkdir(cache);
+    const archive = path.join(scratch, 'package.tgz'), artifact = path.join(scratch, 'artifact');
+    const digest = createHash('sha512'); let received = 0;
+    await pipeline(Readable.fromWeb(response.body), new Transform({ transform(chunk, _enc, cb) { received += chunk.length; if (received > tarballBytes) return cb(new Error('Artifact exceeded declared size')); digest.update(chunk); cb(null, chunk); } }), fs.createWriteStream(archive, { flags: 'wx', mode: 0o600 }));
+    if (received !== tarballBytes || 'sha512-'+digest.digest('base64') !== meta.dist.integrity) throw new Error('Downloaded artifact integrity mismatch');
+    await fsp.mkdir(artifact);
+    await extract({ file: archive, cwd: artifact, strip: 1, strict: true, preservePaths: false, filter: (name, entry) => {
+      if (!name.startsWith('package/') || name.split('/').includes('..') || ['SymbolicLink','Link'].includes(entry.type)) throw new Error('Unsafe package archive member');
+      return true;
+    } });
+    const files = inventoryPackage(artifact), receipt = { managedBy: 'johnness-65.1', version: meta.version, integrity: meta.dist.integrity, files };
+    assertHealthy(artifact, receipt, meta.version);
+    const sourceDeps = sourceRoot && path.join(sourceRoot, 'node_modules');
+    const scanned = await scanDependencies(sourceDeps ?? path.join(scratch, 'none'));
+    let reuse = process.platform !== 'win32' && !!sourceDeps && exists(sourceDeps) && matchingContract(sourceRoot, artifact) && (await fsp.stat(sourceDeps)).dev === (await fsp.stat(parent)).dev;
+    const mutable = mutableDependencyFiles(artifact);
+    if (reuse) for (const name of ['mr-memory', ...new Set([...mutable].map(p => p.startsWith('@') ? p.split(path.sep).slice(0,2).join(path.sep) : p.split(path.sep)[0]))]) if (exists(path.join(sourceDeps,name)) && (await fsp.lstat(path.join(sourceDeps,name))).isSymbolicLink()) reuse = false;
+    await insistSpace(requiredVolumeBytes({ tarballBytes, unpackedBytes: files.reduce((n,f)=>n+f[1],0), packageFiles: files.length, dependencyBytes: scanned.bytes, dependencyFiles: scanned.files, dependencyDirs: scanned.dirs, reuse }));
+    const stagedRoot = packageRootForPrefix(stage);
+    await fsp.mkdir(path.dirname(stagedRoot), { recursive: true });
+    if (reuse) {
+      await fsp.cp(artifact, stagedRoot, { recursive: true, errorOnExist: true, force: false });
+      await cloneDependencies(sourceDeps, path.join(stagedRoot,'node_modules'), mutable);
+      assertHealthy(stagedRoot, receipt, meta.version);
+      assertStep(await runUpdateStep({ name: 'staged dependency patches', argv: [process.execPath, path.join(stagedRoot,'scripts/postinstall.mjs')], cwd: stagedRoot, timeoutMs }));
+      await fsp.mkdir(path.join(stage,'bin'), { recursive: true });
+      await fsp.symlink('../lib/node_modules/johns-harness/johnness.mjs', path.join(stage,'bin/johnness'));
+    } else {
+      assertStep(await runUpdateStep({ name: 'staged npm install', argv: ['env',`npm_config_cache=${cache}`,'npm','i','-g','--prefix',stage,'--cache',cache,'--prefer-offline','--no-audit','--no-fund',archive], timeoutMs }));
+    }
+    assertHealthy(stagedRoot, receipt, meta.version);
+    const afterDeps = await scanDependencies(path.join(stagedRoot,'node_modules'));
+    receipt.emptyDependencies = await (deps.verifyEmptyDependencies ?? verifyEmptyDependencies)(path.join(stagedRoot,'node_modules'), afterDeps.empty, { fetchImpl, scratch, signal });
+    await fsp.writeFile(path.join(stage, RECEIPT), JSON.stringify(receipt)+'\n', { mode: 0o600 });
+    const oldVersion = exists(current) ? readJson(path.join(current,'package.json')).version : null;
+    if (exists(prefix)) { await rename(prefix, previous); previousMoved = true; }
+    await rename(stage, prefix); promoted = true;
+    await deps.afterPromotion?.(prefix);
+    assertHealthy(packageRootForPrefix(prefix), receipt, meta.version);
+    // Commit is complete only after the old tree is gone. Keep version metadata, not code.
+    await fsp.writeFile(recordPath, JSON.stringify({ previousVersion: oldVersion, currentVersion: meta.version, rollback: oldVersion ? `johnness update --tag ${oldVersion}` : null })+'\n', { mode: 0o600 });
+    recordWritten = true;
+    if (previousMoved) { cleanupStarted = true; await remove(previous, { recursive: true, force: true }); }
+    return { ok: true, installedVersion: meta.version, reusedDependencies: reuse, verifiedFiles: files.length };
+  } catch (error) {
+    if (cleanupStarted) return { ok: false, installedVersion: tag, committed: true, tail: "New verified runtime committed, but old-tree cleanup failed. Serving the new runtime; remove the .previous directory before retrying. Never restore its partially deleted contents." };
+    if (previousMoved && exists(previous)) {
+      if (promoted && exists(prefix)) await rename(prefix, stage);
+      await rename(previous, prefix);
+      promoted = false;
+    }
+    if (promoted && !previousMoved && exists(prefix)) { await rename(prefix, stage); promoted = false; }
+    if (recordWritten && !promoted) {
+      if (previousRecord) await fsp.writeFile(recordPath, previousRecord);
+      else await fsp.unlink(recordPath).catch(()=>{});
+    }
+    return { ok: false, tail: String(error.code ?? error.message).replace(/(?:npm_[A-Za-z0-9]+|Bearer\s+\S+)/g, '<redacted>') };
+  } finally {
+    try { await response?.body?.cancel(); } catch {}
+    if (!promoted) await fsp.rm(stage, { recursive: true, force: true }).catch(()=>{});
+    if (scratch) await fsp.rm(scratch, { recursive: true, force: true }).catch(()=>{});
+    if (lock) { await lock.close(); await fsp.unlink(lockPath).catch(()=>{}); }
+  }
+}

package/docs/PATCHES.md

@@ -17,7 +17,7 @@ they predate ~2026-06-06).
 
 ## Index
 
-Family 01 is retired. Families 02 through 41 and 43 through 65 are live on `main`. Family 42 is omitted; native Codex OAuth ownership is Family 58.
+Family 01 is retired. Families 02 through 41 and 43 through 65, including the 65.1 amendment, are live on `main`. Family 42 is omitted; native Codex OAuth ownership is Family 58.
 
 1. **01, announce queue TTL, retired:** Removed the five-minute age filter that could discard delayed sub-agent completion announcements. [Details](#01--announce-ttl-retired-2026-07-30)
 2. **02, failover rotation:** Returns model selection to the highest-priority profile after its cooldown ends. [Details](#02--failover-rotation-undocumented)
@@ -85,6 +85,8 @@ Family 01 is retired. Families 02 through 41 and 43 through 65 are live on `main
 64. **64, Codex to API sibling fallback:** Any `openai-codex/<model>` failover tries `openai/<model>` first, before configured fallbacks, when an OpenAI API key is present. [Details](#64-codex-to-api-sibling-fallback)
 65. **65, catalog refresh and selection policy:** API cache defaults cannot create a model allowlist; shipped models remain authoritative and every boot refreshes version-stamped per-agent catalogs while preserving custom entries. [Details](#65-catalog-refresh-and-selection-policy)
 
+65.1. **65.1, safe staged volume updater:** Same-volume verified promotion, ephemeral npm cache, one final runtime tree and actual-version confirmation after boot. [Details](#651-safe-staged-in-place-volume-updater)
+
 ---
 
 ## 01 - announce-ttl (RETIRED 2026-07-30)
@@ -2464,3 +2466,59 @@ The durable choice is both a merged in-memory catalog and a refreshed on-disk sn
 Baseline: 812 tests and 395 verifier checks. Release: 827 tests and 405 verifier checks, plus the alias contract. Earlier families retain exact byte-identical replay; overlapping historical reconstructions apply Family 65 chronologically, not a relaxed comparison. The Family 59 README counters and pinned CLI artifact are synchronized.
 
 Rex-only deployment procedure: back up the existing state, install 2026.9.17 into the existing volume prefix, restart, inspect the boot/provider/stamp evidence, and use gateway `sessions.patch` on an isolated probe session for both Astra references. Preserve Rex's current OpenAI primary and sub-agent model. Rollback: `npm i -g --prefix /home/rex/.clawdbot/runtime/johnness johns-harness@2026.9.16`, then restart his machine. No other fleet agent is part of this release deployment.
+
+
+## 65.1 Safe staged in-place volume updater
+
+Release: **johns-harness 2026.9.18**. Marker: `JOHNNESS_PATCH_SAFE_VOLUME_UPDATE_65_1`.
+Patcher: `scripts/patch-safe-volume-update.py [root] [--check]`, seven runtime files,
+idempotent and fail-closed across every anchor. Verifier: **65.1.1 through 65.1.12**.
+
+- Chat `/update` and volume-mode CLI `johnness update --tag VERSION` use the same staged
+  installer. A cross-process lock guards the prefix. Download/cache live in an ephemeral
+  OS temp directory, never under persistent state. npm receives both `npm_config_cache`
+  and `--cache`. Network, npm, extraction and preflight failures preserve the live tree.
+- Preflight requires at least **3x compressed archive bytes**, then the greater of that
+  minimum and unpacked files, directory metadata and dependency staging costs. Refusals
+  report required/free MiB and exactly how much more to free.
+- The registry tarball is SHA-512 authenticated. An exact path/size/SHA-256 inventory
+  verifies every package file before and after installation and promotion, plus package
+  version and required entrypoints, including Telegram. One intentional package JSONL
+  and legitimate dependency fixtures may be empty only when publisher manifests say so.
+  Dependency empty fixtures are authenticated against their own integrity-checked tarballs.
+- Identical dependency and postinstall contracts can hardlink unchanged dependencies on
+  the same device. Vendored patch targets and mr-memory JavaScript receive private copies
+  before postinstall, so staging cannot mutate live shared inodes. Changed contracts use
+  a fresh npm install and the larger space requirement. No full dependency copy is retained.
+- Promotion uses same-volume renames, verifies the promoted tree, writes a small previous
+  version/reinstall record, then deletes the old tree. Success leaves exactly one runtime
+  tree. Chat does not try to send its final volume completion before exit; the existing
+  restart sentinel is consumed after channels start, and both gateway copies report the
+  actual booted package version rather than blindly claiming the requested version.
+
+### Failure boundaries and recovery
+
+Before old-tree deletion begins, caught failures restore the original live prefix. Renames
+are individually atomic, not a portable two-directory exchange transaction. The selector
+recognizes a valid `.previous` tree if interrupted between renames; a stale lock or previous
+path deliberately blocks another updater until the operator inspects/reconciles it. This
+release does not claim automatic recovery from every power-loss or filesystem failure.
+Once deletion starts, its contents cannot safely be rolled back: an exceptional cleanup
+failure reports `committed: true`, retains the verified NEW runtime, and requests removal
+of the partial `.previous` directory. It never restores a partially deleted old tree.
+Final confirmation uses the existing startup sentinel delivery lifecycle; transport failure
+is recorded as a system event, not guaranteed exactly-once delivery to an offline service.
+CLI volume installation reports the supervisor restart command; it does not kill another
+process. `--dry-run` displays the in-place plan without staging or modifying the prefix.
+
+Model defaults and fleet entrypoint config rewriting are unchanged. A 9.17 runtime cannot
+provide this new installer until bootstrapped from the 9.18 artifact. Once installed, the
+next `/update` uses this path natively.
+
+### Verification
+
+Full suite **850/850**, source and isolated npm-install verifier **417/417**, 23 focused
+safety tests. A fake volume exercises private staging, artifact verification, atomic rename
+promotion, old-tree removal and corrupt-stage rollback. Historical families 51/54/60/61/62/
+63/64/65 and alias contracts remain green; Family 65 replay layers the new amendment before
+byte-exact comparisons. Family 59's README snapshot keeps its exact counts synchronized.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "johns-harness",
-  "version": "2026.9.17",
+  "version": "2026.9.18",
   "description": "John's Harness: a production agent harness that runs autonomous coding agents as one cooperative swarm.",
   "keywords": [
     "ai-agents",