@ran-sh/dsh-crew 1.0.3 → 1.1.1

package/src/install/npx-lifecycle.mjs

@@ -30,17 +30,18 @@ import {
   readdirSync,
   readFileSync,
   realpathSync,
+  renameSync,
   rmSync,
   copyFileSync,
   writeFileSync,
 } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import * as realInstaller from './install.mjs';
-import { crewProfileDir } from './install.mjs';
-import { ensureCrewDshRuntime, ensureCrewPluginRegistration, removeCrewPluginRegistration } from '../dsh-cli-runtime.mjs';
+import { crewDshHome, crewProfileDir } from './install.mjs';
+import { ensureCrewDshRuntime, ensureCrewPluginRegistration, removeCrewPluginRegistration, migrateCrewDshRuntime, installDshInto, restoreRetainedRuntime, crewDshRuntimeRoot, payloadDshVersion, TARGET_DSH_VERSION } from '../dsh-cli-runtime.mjs';
 import {
   ensureOfficialWebIntegration,
   officialWebIntegrationStatus,
@@ -53,6 +54,10 @@ export const CURRENT_POINTER_FILENAME = 'current.json';
 export const KEEP_RELEASES = 2;
 export const INCOMPLETE_MARKER = '.dsh-crew-incomplete';
 const CREW_ROUTE_BASE = '/_dsh/dsh-crew';
+// Exact DSH cohort version: dotted numeric with optional -prerelease suffix.
+// Anything else (ranges, "../..", paths) is NOT an authorized cohort value
+// and must never reach rename/rmSync authority via retained-runtimes keys.
+export const EXACT_DSH_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 
 export function npmCliInvocation(args, {
   platform = process.platform,
@@ -126,23 +131,585 @@ function isoNow() {
  * manifest to count as installed.
  */
 export function readCurrentPointer({ home = homedir() } = {}) {
+  const state = readCurrentPointerState({ home });
+  return state.status === 'valid' ? state.pointer : null;
+}
+
+// Tri-state pointer read: ABSENT (no file) / VALID / MALFORMED (present
+// but unparseable or schema-invalid). Recovery must never merge ABSENT
+// and MALFORMED: a corrupt pointer fails closed with the journal retained.
+export function readCurrentPointerState({ home = homedir() } = {}) {
   const file = currentPointerFile({ home });
-  if (!existsSync(file)) return null;
+  if (!existsSync(file)) return { status: 'absent', file };
   let raw;
-  try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
-  if (!raw || typeof raw !== 'object') return null;
-  if (typeof raw.name !== 'string' || typeof raw.version !== 'string' || typeof raw.path !== 'string') return null;
-  if (!isAbsolute(raw.path)) return null;
-  return raw;
+  try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch {
+    return { status: 'malformed', file, code: 'POINTER_UNPARSEABLE' };
+  }
+  if (!raw || typeof raw !== 'object') return { status: 'malformed', file, code: 'POINTER_NOT_OBJECT' };
+  if (typeof raw.name !== 'string' || raw.name.length === 0
+    || typeof raw.version !== 'string' || raw.version.length === 0
+    || typeof raw.path !== 'string' || raw.path.length === 0) {
+    return { status: 'malformed', file, code: 'POINTER_FIELDS_INVALID' };
+  }
+  if (!isAbsolute(raw.path)) return { status: 'malformed', file, code: 'POINTER_PATH_NOT_ABSOLUTE' };
+  return { status: 'valid', file, pointer: raw };
+}
+
+function validJournalRelease(value) {
+  return !!value && typeof value === 'object'
+    && typeof value.name === 'string' && value.name.length > 0
+    && typeof value.version === 'string' && value.version.length > 0
+    && typeof value.path === 'string' && isAbsolute(value.path);
+}
+
+function validJournalCandidate(value) {
+  return !!value && typeof value === 'object'
+    && typeof value.name === 'string' && value.name.length > 0
+    && typeof value.version === 'string' && value.version.length > 0
+    && typeof value.stageDir === 'string' && isAbsolute(value.stageDir);
+}
+
+function writeFileAtomic(file, content) {
+  // Same-directory temp + rename: a crash can never leave a truncated
+  // pointer or journal behind to be misread as valid state.
+  mkdirSync(dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, content);
+  try {
+    renameSync(temp, file);
+  } catch (error) {
+    try { rmSync(temp, { force: true }); } catch {}
+    throw error;
+  }
 }
 
 function writeCurrentPointer({ home, name, version, path }) {
-  mkdirSync(dirname(currentPointerFile({ home })), { recursive: true });
   const pointer = { name, version, path, installed_at: isoNow(), managed_by: 'npx' };
-  writeFileSync(currentPointerFile({ home }), JSON.stringify(pointer, null, 2) + '\n');
+  writeFileAtomic(currentPointerFile({ home }), JSON.stringify(pointer, null, 2) + '\n');
   return pointer;
 }
 
+export const UPDATE_JOURNAL_FILENAME = 'update-journal.json';
+export const UPDATE_LOCK_FILENAME = 'update-in-progress.lock';
+
+export function updateJournalFile({ home = homedir() } = {}) {
+  return join(crewAppRoot({ home }), UPDATE_JOURNAL_FILENAME);
+}
+
+export function updateLockFile({ home = homedir() } = {}) {
+  return join(crewAppRoot({ home }), UPDATE_LOCK_FILENAME);
+}
+
+export function acquireUpdateLock({ home = homedir() } = {}) {
+  const file = updateLockFile({ home });
+  mkdirSync(dirname(file), { recursive: true });
+  const nonce = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const record = { pid: process.pid, started_at: isoNow(), nonce, hostname: process.env.COMPUTERNAME ?? null };
+  try {
+    writeFileSync(file, JSON.stringify(record) + '\n', { flag: 'wx' });
+    return { ok: true, owner: true, nonce };
+  } catch (error) {
+    if (error?.code !== 'EEXIST') {
+      return { ok: false, code: 'UPDATE_LOCK_FAILED', error: String(error?.message ?? error) };
+    }
+    return tryReclaimUpdateLock({ home, record });
+  }
+}
+
+function lockOwnerAlive(record) {
+  const pid = Number(record?.pid);
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // ESRCH = no such process (dead owner, safe to reclaim).
+    // EPERM = process exists but we cannot signal it (live owner, keep).
+    return error?.code !== 'ESRCH';
+  }
+}
+
+// Stale-lock reclaim with a single atomic claim: each contender writes its
+// full claim into a UNIQUE temp dir, then renames that dir onto the fixed
+// arbitration path. Rename-onto-existing is atomic on the same filesystem:
+// exactly one contender wins; the loser gets EEXIST and backs off. No
+// shared claim.json is ever overwritten, so two contenders can never both
+// believe they own the reclaim. A crashed winner leaves a stale arbitration
+// dir: a later contender quarantines the whole dir (atomic rename away)
+// only after proving the recorded owner dead, then restarts contention
+// from the top. The winner's finally removes the arbitration dir only when
+// its claim nonce still matches (CAS), never unconditionally.
+function tryReclaimUpdateLock({ home, record }) {
+  const file = updateLockFile({ home });
+  const arbitrationPath = `${file}.arbitration`;
+  const myClaim = { pid: process.pid, nonce: record.nonce, started_at: isoNow() };
+  for (let round = 0; round < 3; round += 1) {
+    let current = null;
+    try { current = JSON.parse(readFileSync(file, 'utf8')); } catch { current = null; }
+    if (!current || typeof current !== 'object') {
+      // Unparseable lock: fail closed, keep for operator inspection.
+      return { ok: false, code: 'UPDATE_LOCK_CORRUPT' };
+    }
+    if (lockOwnerAlive(current)) {
+      return { ok: false, code: 'UPDATE_IN_PROGRESS' };
+    }
+    // Single atomic claim: unique temp dir -> rename onto fixed path.
+    const tmpDir = `${arbitrationPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+    try {
+      mkdirSync(tmpDir, { recursive: true });
+      writeFileSync(join(tmpDir, 'claim.json'), JSON.stringify(myClaim) + '\n', { flag: 'wx' });
+    } catch (error) {
+      try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+      return { ok: false, code: 'UPDATE_LOCK_FAILED', error: String(error?.message ?? error) };
+    }
+    let claimed = false;
+    try {
+      renameSync(tmpDir, arbitrationPath);
+      claimed = true;
+    } catch (error) {
+      try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+      if (error?.code !== 'EEXIST' && error?.code !== 'EPERM' && error?.code !== 'ENOTEMPTY') {
+        return { ok: false, code: 'UPDATE_LOCK_FAILED', error: String(error?.message ?? error) };
+      }
+      // Arbitration path occupied: quarantine it only when its recorded
+      // owner is provably dead; a live contender's claim is never touched.
+      let guard = null;
+      try { guard = JSON.parse(readFileSync(join(arbitrationPath, 'claim.json'), 'utf8')); } catch { guard = null; }
+      if (!guard || typeof guard !== 'object' || lockOwnerAlive(guard)) {
+        return { ok: false, code: 'UPDATE_IN_PROGRESS' };
+      }
+      const quarantine = `${arbitrationPath}.quarantine.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+      try {
+        renameSync(arbitrationPath, quarantine);
+        try { rmSync(quarantine, { recursive: true, force: true }); } catch {}
+      } catch {
+        return { ok: false, code: 'UPDATE_IN_PROGRESS' };
+      }
+      continue;
+    }
+    try {
+      // Winner: re-verify the main lock is still the same dead record.
+      let reread = null;
+      try { reread = JSON.parse(readFileSync(file, 'utf8')); } catch { reread = null; }
+      if (!reread || reread.nonce !== current.nonce || reread.pid !== current.pid) {
+        return { ok: false, code: 'UPDATE_IN_PROGRESS' };
+      }
+      if (lockOwnerAlive(reread)) {
+        return { ok: false, code: 'UPDATE_IN_PROGRESS' };
+      }
+      rmSync(file, { force: true });
+      try {
+        writeFileSync(file, JSON.stringify(record) + '\n', { flag: 'wx' });
+        return { ok: true, owner: true, nonce: record.nonce, reclaimed: true };
+      } catch (error) {
+        if (error?.code === 'EEXIST') return { ok: false, code: 'UPDATE_IN_PROGRESS' };
+        return { ok: false, code: 'UPDATE_LOCK_FAILED', error: String(error?.message ?? error) };
+      }
+    } finally {
+      // CAS cleanup: remove the arbitration dir only when its claim is
+      // still ours; never delete another contender's claim.
+      try {
+        const mine = JSON.parse(readFileSync(join(arbitrationPath, 'claim.json'), 'utf8'));
+        if (mine?.nonce === myClaim.nonce && mine?.pid === process.pid) {
+          rmSync(arbitrationPath, { recursive: true, force: true });
+        }
+      } catch {}
+    }
+  }
+  return { ok: false, code: 'UPDATE_IN_PROGRESS' };
+}
+
+export function releaseUpdateLock({ home = homedir(), nonce = null } = {}) {
+  // Nonce-checked release: a stale owner finalizer must never delete a
+  // replacement owner's lock. Without an expected nonce this is best-effort
+  // legacy behavior; with one it fails closed on mismatch.
+  if (nonce !== null && nonce !== undefined) {
+    let current = null;
+    try { current = JSON.parse(readFileSync(updateLockFile({ home }), 'utf8')); } catch { current = null; }
+    if (!current || current.nonce !== nonce) {
+      return { ok: false, code: 'NOT_OWNER' };
+    }
+  }
+  try { rmSync(updateLockFile({ home }), { force: true }); } catch {}
+  return { ok: true };
+}
+
+function readUpdateJournal({ home = homedir() } = {}) {
+  const file = updateJournalFile({ home });
+  if (!existsSync(file)) return null;
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    // A truncated journal is a crash artifact, NOT absence: fail closed and
+    // keep the file so an operator can inspect it instead of silently
+    // treating an interrupted transaction as clean.
+    return { malformed: true, file };
+  }
+  if (!raw || typeof raw !== 'object' || typeof raw.stage !== 'string') {
+    return { malformed: true, file };
+  }
+  // Full schema check: a semantically broken journal (null candidate,
+  // incomplete prior) must fail closed, never enter recovery.
+  if (!validJournalCandidate(raw.candidate)) {
+    return { malformed: true, file, code: 'JOURNAL_CANDIDATE_SCHEMA_INVALID' };
+  }
+  if (raw.prior !== null && raw.prior !== undefined && !validJournalRelease(raw.prior)) {
+    return { malformed: true, file, code: 'JOURNAL_PRIOR_SCHEMA_INVALID' };
+  }
+  return raw;
+}
+
+// Synchronously read the @deepseek-ai/dsh version a runtime tree ships.
+function readRuntimeTreeVersionSync(root) {
+  if (!root || typeof root !== 'string') return null;
+  try {
+    const parsed = JSON.parse(readFileSync(join(root, 'node_modules', '@deepseek-ai', 'dsh', 'package.json'), 'utf8'));
+    return typeof parsed.version === 'string' && parsed.version.length > 0 ? parsed.version : null;
+  } catch { return null; }
+}
+
+function writeUpdateJournal({ home, stage, prior = null, candidate = null, verified = false, runtime = null }) {
+  const record = { stage, prior, candidate, verified: verified === true, updated_at: isoNow() };
+  if (runtime && typeof runtime === 'object') record.runtime = runtime;
+  writeFileAtomic(updateJournalFile({ home }), JSON.stringify(record, null, 2) + '\n');
+  return record;
+}
+
+// Atomically mark the current journal verified AFTER re-checking its
+// identity matches the expected stage/prior/candidate. A crash between
+// verification success and this write leaves the journal unverified, so
+// reconcile refuses to finalize it.
+export function markJournalVerified({ home = homedir(), stage, prior = null, candidate = null, runtime = null } = {}) {
+  const current = readUpdateJournal({ home });
+  if (!current || current.malformed) return { ok: false, code: 'JOURNAL_NOT_FOUND' };
+  const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+  if (current.stage !== stage || !same(current.prior, prior) || !same(current.candidate, candidate)) {
+    return { ok: false, code: 'JOURNAL_IDENTITY_MISMATCH' };
+  }
+  writeUpdateJournal({ home, stage, prior, candidate, verified: true, runtime });
+  return { ok: true };
+}
+
+function clearUpdateJournal({ home = homedir() } = {}) {
+  try { rmSync(updateJournalFile({ home }), { force: true }); } catch {}
+}
+
+// Synchronous profile-registration compensation for crash recovery:
+// re-point the dedicated Crew profile at the prior release. Host
+// integrations (Codex/ZCode/startup/Claude) are repaired by the next
+// successful install/update activation; the profile link is the surface
+// that must never dangle at a deleted candidate.
+function compensateActivationSync({ home, prior, manifest, log, installer }) {
+  if (!prior?.path || !existsSync(prior.path)) return { ok: false, code: 'PRIOR_RELEASE_MISSING' };
+  if (!manifest?.name) return { ok: false, code: 'PRIOR_MANIFEST_INVALID' };
+  const registration = ensureCrewPluginRegistration({ home, root: prior.path, name: manifest.name });
+  if (!registration.ok) return { ok: false, code: registration.code ?? 'PRIOR_REGISTRATION_FAILED' };
+  return { ok: true, version: manifest.version, path: prior.path };
+}
+
+// Undo a first-install candidate's activation surfaces: remove its profile
+// registration (dependency + bundle + junction) ONLY when each surface
+// still references THIS journal's candidate. The dependency must resolve
+// to exactly link:<candidateRealPath> (normalized slashes); a later
+// legitimate registration pointing elsewhere is never removed. Mixed or
+// unjudgeable state fails closed with the journal retained. When the
+// profile manifest is missing/unreadable the junction is still handled
+// independently so a "junction created, manifest never written" crash
+// cannot leave a dangling junction.
+function undoCandidateActivationSync({ home, candidateDir, candidateName }) {
+  if (!candidateDir || !candidateName) return { ok: true, undone: false };
+  const profileRoot = crewProfileDir({ home });
+  const profileFile = join(profileRoot, 'package.json');
+  let manifest = null;
+  let manifestReadable = true;
+  try { manifest = JSON.parse(readFileSync(profileFile, 'utf8')); } catch { manifest = null; manifestReadable = false; }
+  const linkPath = join(profileRoot, 'node_modules', ...candidateName.split('/'));
+  let linked = null;
+  try {
+    if (lstatSync(linkPath).isSymbolicLink()) linked = realpathSync(linkPath);
+  } catch { linked = null; }
+  let candidateReal = null;
+  try { candidateReal = realpathSync(candidateDir); } catch { candidateReal = candidateDir; }
+  const expectedDep = `link:${String(candidateReal).replace(/\\/g, '/')}`;
+  const rawDep = manifest?.dependencies?.[candidateName];
+  const depPointsAtCandidate = typeof rawDep === 'string'
+    && rawDep.replace(/\\/g, '/') === expectedDep;
+  const bundleNamesCandidate = Array.isArray(manifest?.dsh?.profile?.bundles) && manifest.dsh.profile.bundles.includes(candidateName);
+  const linkPointsAtCandidate = linked !== null && linked === candidateReal;
+  // Bundle carries no path: it NEVER grants deletion authority by itself.
+  // It is removed only when dependency or junction proves THIS journal's
+  // candidate still owns the registration. A re-pointed dep/junction with
+  // a leftover same-name bundle fails closed (journal retained).
+  const identityEvidence = depPointsAtCandidate || linkPointsAtCandidate;
+  const bundlePointsAtCandidate = bundleNamesCandidate && identityEvidence;
+  // Manifest unreadable but junction dangles at candidate: remove junction.
+  if (!manifestReadable) {
+    if (!linkPointsAtCandidate) return { ok: true, undone: false };
+    try { rmSync(linkPath, { force: true }); } catch (error) {
+      return { ok: false, code: 'CANDIDATE_UNDO_FAILED', error: String(error?.message ?? error) };
+    }
+    return { ok: true, undone: true };
+  }
+  if (!manifest) return { ok: true, undone: false };
+  // Same-name package re-pointed elsewhere (dep or junction references a
+  // different target) while the bundle still names it: mixed state that
+  // cannot prove THIS candidate owns the registration. Fail closed,
+  // retain the journal for operator inspection.
+  const depPointsElsewhere = typeof rawDep === 'string' && !depPointsAtCandidate;
+  const linkPointsElsewhere = linked !== null && !linkPointsAtCandidate;
+  if ((depPointsElsewhere || linkPointsElsewhere) && bundleNamesCandidate) {
+    return { ok: false, code: 'CANDIDATE_UNDO_AMBIGUOUS', error: 'same-name package re-pointed elsewhere; refusing bundle removal' };
+  }
+  if (!depPointsAtCandidate && !bundlePointsAtCandidate && !linkPointsAtCandidate) {
+    return { ok: true, undone: false };
+  }
+  // Partial registration: only undo the surfaces that reference THIS
+  // candidate; leave anything already re-pointed elsewhere untouched.
+  try {
+    const next = { ...manifest };
+    if (depPointsAtCandidate) {
+      next.dependencies = { ...manifest.dependencies };
+      delete next.dependencies[candidateName];
+      if (Object.keys(next.dependencies).length === 0) delete next.dependencies;
+    }
+    if (bundlePointsAtCandidate) {
+      next.dsh = { ...manifest.dsh, profile: { ...manifest.dsh.profile, bundles: manifest.dsh.profile.bundles.filter((b) => b !== candidateName) } };
+    }
+    writeFileAtomic(profileFile, JSON.stringify(next, null, 2) + '\n');
+    if (linkPointsAtCandidate) rmSync(linkPath, { force: true });
+  } catch (error) {
+    return { ok: false, code: 'CANDIDATE_UNDO_FAILED', error: String(error?.message ?? error) };
+  }
+  return { ok: true, undone: true };
+}
+
+// Canonical containment validation for a journal's runtime segment. Recovery
+// may rename/recursively-delete these roots, so liveRoot and retainedRoot
+// must be EXACTLY the canonical Crew-owned paths (resolved, never a suffix
+// match), and a parked prior root must be a DIRECT child of the harness home
+// whose basename matches the lifecycle's own runtime-prev-* naming.
+function validateJournalRuntimeSegment({ home, rt }) {
+  const harnessRoot = resolve(crewDshHome({ home }));
+  const canonicalLive = resolve(crewDshRuntimeRoot({ home }));
+  const canonicalRetained = resolve(join(harnessRoot, 'retained-runtimes'));
+  // A coordinated-update journal MUST carry a runtime segment: without it
+  // recovery could restore the payload but leave a candidate-cohort runtime
+  // behind (an unsupported pair) and clear the journal.
+  if (!rt || typeof rt !== 'object') return { ok: false, error: 'runtime segment missing from coordinated-update journal' };
+  if (typeof rt.liveRoot !== 'string' || resolve(rt.liveRoot) !== canonicalLive) {
+    return { ok: false, error: `liveRoot is not the canonical Crew runtime root (${rt.liveRoot})` };
+  }
+  if (typeof rt.candidateVersion !== 'string' || !EXACT_DSH_VERSION_RE.test(rt.candidateVersion)) {
+    return { ok: false, error: 'candidateVersion is not an exact version' };
+  }
+  if (rt.priorVersion !== undefined && rt.priorVersion !== null
+    && (typeof rt.priorVersion !== 'string' || !EXACT_DSH_VERSION_RE.test(rt.priorVersion))) {
+    return { ok: false, error: 'priorVersion is not an exact version' };
+  }
+  if (rt.priorRoot !== undefined && rt.priorRoot !== null) {
+    if (typeof rt.priorRoot !== 'string') return { ok: false, error: 'priorRoot is not a path' };
+    const priorResolved = resolve(rt.priorRoot);
+    // Direct child of the harness home only.
+    if (dirname(priorResolved) !== harnessRoot) {
+      return { ok: false, error: `priorRoot is not a direct child of the Crew harness home (${rt.priorRoot})` };
+    }
+    const base = priorResolved.split(/[\\/]/).filter(Boolean).at(-1) ?? '';
+    if (!/^runtime-prev-[0-9a-z-]+$/i.test(base)) {
+      return { ok: false, error: `priorRoot basename is not a lifecycle runtime-prev-* dir (${base})` };
+    }
+  }
+  if (rt.retainedRoot !== undefined && rt.retainedRoot !== null) {
+    if (typeof rt.retainedRoot !== 'string' || resolve(rt.retainedRoot) !== canonicalRetained) {
+      return { ok: false, error: `retainedRoot is not the canonical retained-runtimes dir (${rt.retainedRoot})` };
+    }
+  }
+  return { ok: true };
+}
+
+// Reconcile a leftover journal from a crashed update/install. The single
+// commit point is the pointer write: pointer == candidate means committed
+// (finalize, do NOT roll back); pointer == prior/absent means pre-commit
+// (restore activation surfaces, drop candidate). A malformed journal fails
+// closed and is retained for operator inspection.
+export function reconcileUpdateJournal({ home = homedir(), log = () => {}, installer = realInstaller } = {}) {
+  const journal = readUpdateJournal({ home });
+  if (!journal) return { ok: true, reconciled: false };
+  if (journal.malformed) {
+    return { ok: false, code: journal.code ?? 'JOURNAL_MALFORMED', file: journal.file };
+  }
+  // Tri-state pointer: a corrupt pointer is NOT absence. Recovery with a
+  // malformed pointer fails closed with the journal retained.
+  const pointerState = readCurrentPointerState({ home });
+  if (pointerState.status === 'malformed') {
+    return { ok: false, code: 'POINTER_MALFORMED', file: pointerState.file, error: pointerState.code ?? 'pointer unreadable; refusing recovery' };
+  }
+  const pointer = pointerState.status === 'valid' ? pointerState.pointer : null;
+  const candidateDir = journal.candidate?.stageDir ?? null;
+  const candidateManifest = candidateDir && existsSync(candidateDir) ? readManifest(candidateDir) : null;
+
+  // A coordinated-update journal MUST carry a runtime segment; recovery may
+  // rename or recursively delete its roots, so validate them canonically
+  // BEFORE granting any destructive authority: liveRoot/retainedRoot must be
+  // the exact canonical Crew-owned paths (resolved, no suffix games) and a
+  // parked prior root must be a direct child of the harness home matching
+  // the lifecycle's own runtime-prev-* naming. A missing or invalid segment
+  // fails closed and touches nothing.
+  if (journal.stage === 'coordinated-update') {
+    const validation = validateJournalRuntimeSegment({ home, rt: journal.runtime });
+    if (!validation.ok) {
+      return { ok: false, code: 'JOURNAL_RUNTIME_INVALID', stage: journal.stage, error: validation.error, file: updateJournalFile({ home }) };
+    }
+  }
+
+  // Committed side: pointer must match the FULL journal candidate identity
+  // (name + version + path), and the candidate manifest is verified against
+  // the JOURNAL candidate name/version (not its own). A rollback journal
+  // additionally requires explicit verification: pointer==target alone
+  // never means a verified rollback commit (activation + restart +
+  // dual-domain verification may never have completed).
+  const candidateIdent = journal.candidate ?? null;
+  const pointerMatchesCandidate = candidateDir !== null
+    && pointer?.path === candidateDir
+    && typeof pointer?.name === 'string' && pointer.name.length > 0
+    && typeof pointer?.version === 'string' && pointer.version.length > 0
+    && pointer.name === candidateIdent?.name
+    && pointer.version === candidateIdent?.version;
+  if (candidateDir && pointer?.path === candidateDir && !pointerMatchesCandidate) {
+    return { ok: false, code: 'JOURNAL_POINTER_DIVERGED', stage: journal.stage, error: 'pointer path matches candidate but name/version do not; refusing recovery' };
+  }
+  if (journal.stage === 'rollback' && pointerMatchesCandidate && journal.verified !== true) {
+    return { ok: false, code: 'JOURNAL_ROLLBACK_UNVERIFIED', stage: journal.stage, error: 'rollback journal not marked verified; refusing finalize' };
+  }
+  if (journal.stage === 'coordinated-update' && pointerMatchesCandidate && journal.verified !== true) {
+    return { ok: false, code: 'JOURNAL_COORDINATED_UNVERIFIED', stage: journal.stage, error: 'coordinated-update journal not marked verified; refusing finalize' };
+  }
+  if (journal.stage === 'coordinated-update' && pointerMatchesCandidate) {
+    // Coordinated commit also requires the live runtime to report the
+    // candidate cohort. We cannot reach the network synchronously here, so
+    // verify against the journal's recorded runtime roots: the live tree must
+    // BE the candidate runtime (candidateRoot moved onto liveRoot).
+    const rt = journal.runtime ?? null;
+    if (rt?.candidateVersion && rt?.liveRoot) {
+      const liveVersion = readRuntimeTreeVersionSync(rt.liveRoot);
+      if (liveVersion !== rt.candidateVersion) {
+        return { ok: false, code: 'JOURNAL_COORDINATED_RUNTIME_MISMATCH', stage: journal.stage, error: `live runtime is ${liveVersion ?? 'unknown'} but coordinated journal expects ${rt.candidateVersion}; refusing finalize` };
+      }
+    }
+  }
+  if (pointerMatchesCandidate) {
+    if (!candidateManifest?.name || !candidateManifest?.version) {
+      return { ok: false, code: 'JOURNAL_CANDIDATE_INVALID', stage: journal.stage };
+    }
+    const validated = validateInstalledPayload(candidateDir, { expectedName: candidateIdent.name, expectedVersion: candidateIdent.version });
+    if (!validated.ok) {
+      return { ok: false, code: 'JOURNAL_CANDIDATE_INVALID', stage: journal.stage, error: (validated.errors ?? []).join('; ') };
+    }
+    clearUpdateJournal({ home });
+    gcOldReleases({ home, protect: journal.prior?.path ?? null });
+    log(`- recovered update journal at stage ${journal.stage}: candidate ${candidateIdent.version} already committed, finalized`);
+    return { ok: true, reconciled: true, stage: journal.stage, committed: true };
+  }
+
+  // Diverged side: pointer references neither candidate nor prior. No
+  // authority to decide which release should win: fail closed, touch
+  // nothing (no registration change, no release delete, no journal clear).
+  const priorPath = journal.prior?.path ?? null;
+  const priorMatches = priorPath !== null
+    && pointer?.path === priorPath
+    && pointer?.name === journal.prior?.name
+    && pointer?.version === journal.prior?.version;
+  const isAbsent = !pointer;
+  if (!priorMatches && !isAbsent) {
+    return { ok: false, code: 'JOURNAL_POINTER_DIVERGED', stage: journal.stage, error: `pointer references unexpected release ${pointer?.path ?? 'unknown'}; refusing recovery` };
+  }
+
+  // Pre-commit side: prior stays authoritative. Re-point live activation
+  // surfaces back at prior (a crash between activation and pointer write
+  // leaves them on the candidate), then drop the candidate. A rollback
+  // journal's candidate is a RETAINED release, never an orphan stage: it
+  // must be preserved even when the pointer still references prior. A
+  // coordinated-update journal additionally carries a runtime segment: a
+  // crash mid-swap may have left the live runtime on the CANDIDATE cohort
+  // while the pointer (and payload) still reference prior — that unsupported
+  // combination must be restored to the prior cohort synchronously here.
+  if (priorPath) {
+    if (!existsSync(journal.prior.path)) {
+      return { ok: false, code: 'JOURNAL_PRIOR_MISSING', stage: journal.stage, error: 'prior release disappeared; refusing silent recovery' };
+    }
+    const rt = journal.stage === 'coordinated-update' ? journal.runtime ?? null : null;
+    if (rt?.priorVersion && rt?.liveRoot) {
+      const liveVersion = readRuntimeTreeVersionSync(rt.liveRoot);
+      if (liveVersion !== rt.priorVersion) {
+        // Move the parked prior tree back onto liveRoot. This is a pure
+        // directory swap: no network, no registry, safe under a stale lock.
+        const parked = rt.priorRoot && existsSync(rt.priorRoot) ? rt.priorRoot : null;
+        if (!parked && rt.candidateRoot && existsSync(rt.candidateRoot)) {
+          // Fall back: liveRoot may hold the candidate tree and the prior
+          // tree may have been consumed into retained-runtimes. Attempt the
+          // retained path next.
+        }
+        if (parked) {
+          try {
+            rmSync(rt.liveRoot, { recursive: true, force: true });
+            renameSync(parked, rt.liveRoot);
+          } catch (error) {
+            return { ok: false, code: 'JOURNAL_COORDINATED_RUNTIME_RESTORE_FAILED', stage: journal.stage, error: `prior runtime restore failed: ${error?.message ?? error}` };
+          }
+        } else {
+          // No parked tree: try the retained-runtimes/<priorVersion> copy.
+          const retainedDir = rt.retainedRoot ? join(rt.retainedRoot, rt.priorVersion) : null;
+          let restored = false;
+          if (retainedDir && existsSync(retainedDir)) {
+            try {
+              rmSync(rt.liveRoot, { recursive: true, force: true });
+              renameSync(retainedDir, rt.liveRoot);
+              restored = true;
+            } catch { /* fall through to fail closed */ }
+          }
+          if (!restored) {
+            return { ok: false, code: 'JOURNAL_COORDINATED_RUNTIME_RESTORE_FAILED', stage: journal.stage, error: 'prior runtime tree unavailable for synchronous recovery; run update --candidate to re-migrate' };
+          }
+        }
+        log(`- coordinated recovery: restored prior DSH runtime (@${rt.priorVersion})`);
+      }
+    }
+    const priorManifest = readManifest(journal.prior.path);
+    const compensated = compensateActivationSync({ home, prior: journal.prior, manifest: priorManifest, log, installer });
+    if (!compensated.ok) {
+      return { ok: false, code: 'JOURNAL_COMPENSATE_FAILED', stage: journal.stage, error: compensated.error ?? compensated.code };
+    }
+    if (journal.stage !== 'rollback' && journal.stage !== 'coordinated-update' && candidateDir && existsSync(candidateDir)) {
+      // A coordinated-update candidate stage is consumed into the runtime
+      // swap already; if it still exists it is an orphan of the failed swap
+      // and may be removed. (rollback candidates are retained releases.)
+      try { rmSync(candidateDir, { recursive: true, force: true }); } catch {}
+    }
+    clearUpdateJournal({ home });
+    log(`- recovered update journal at stage ${journal.stage}: restored prior release ${journal.prior.version}`);
+    return { ok: true, reconciled: true, stage: journal.stage, committed: false };
+  }
+
+  // First-install pre-commit: no prior exists. Undo the candidate's
+  // activation surfaces FIRST (a crash between activation and pointer
+  // write leaves the profile link on the candidate), then remove the
+  // orphan candidate pointer + dir. Journal clears only after successful
+  // compensation.
+  const undone = undoCandidateActivationSync({ home, candidateDir, candidateName: journal.candidate?.name ?? null });
+  if (!undone.ok) {
+    return { ok: false, code: 'JOURNAL_UNDO_FAILED', stage: journal.stage, error: undone.error ?? undone.code };
+  }
+  if (candidateDir && existsSync(candidateDir)) {
+    try { rmSync(candidateDir, { recursive: true, force: true }); } catch {}
+  }
+  if (pointer && candidateDir && pointer.path === candidateDir) {
+    try { rmSync(currentPointerFile({ home }), { force: true }); } catch {}
+  }
+  clearUpdateJournal({ home });
+  log(`- recovered first-install journal at stage ${journal.stage}: removed orphan candidate`);
+  return { ok: true, reconciled: true, stage: journal.stage, committed: false };
+}
+
 // ---- dependency tree materialization ----------------------------------------
 
 function listPackageEdges(manifest) {
@@ -468,24 +1035,53 @@ export function validateInstalledPayload(dir, { expectedName, expectedVersion, a
 }
 
 // ---- release commit / activation ---------------------------------------------
+// Transactional commit: stage -> journal(activating) -> activation ->
+// pointer write LAST -> clear journal -> GC (prior protected until commit).
+// A crash at any point before the pointer write leaves the prior release
+// authoritative and the journal behind for reconcileUpdateJournal.
+export function beginReleaseActivation({ stageDir, manifest, home, prior = null }) {
+  // Journal FIRST, marker removal second: a crash between the two leaves a
+  // journaled (recoverable) candidate, never a marker-free orphan that
+  // looks complete but was never in a transaction. Marker removal failure
+  // aborts the transaction instead of proceeding with a half-marked stage.
+  writeUpdateJournal({
+    home,
+    stage: 'activating',
+    prior: prior ? { name: prior.name, version: prior.version, path: prior.path } : null,
+    candidate: { name: manifest.name, version: manifest.version, stageDir },
+  });
+  try {
+    rmSync(join(stageDir, INCOMPLETE_MARKER), { force: true });
+  } catch (error) {
+    throw Object.assign(new Error(`cannot clear stage marker: ${error?.message ?? error}`), { code: 'STAGE_MARKER_REMOVE_FAILED' });
+  }
+  if (existsSync(join(stageDir, INCOMPLETE_MARKER))) {
+    throw Object.assign(new Error('stage marker still present after removal'), { code: 'STAGE_MARKER_REMOVE_FAILED' });
+  }
+  return stageDir;
+}
 
-function commitStagedRelease({ stageDir, manifest, home }) {
-  rmSync(join(stageDir, INCOMPLETE_MARKER));
+export function commitActivatedRelease({ stageDir, manifest, home, prior = null }) {
   writeCurrentPointer({ home, name: manifest.name, version: manifest.version, path: stageDir });
-  gcOldReleases({ home });
+  clearUpdateJournal({ home });
+  gcOldReleases({ home, protect: prior?.path ?? null });
   return stageDir;
 }
 
+function commitStagedRelease({ stageDir, manifest, home, prior = null }) {
+  return commitActivatedRelease({ stageDir, manifest, home, prior });
+}
+
 const STALE_INCOMPLETE_MS = 24 * 60 * 60 * 1000;
 
-function gcOldReleases({ home, keep = KEEP_RELEASES }) {
+function gcOldReleases({ home, keep = KEEP_RELEASES, protect = null }) {
   const pointer = readCurrentPointer({ home });
   const releasesDir = crewReleasesDir({ home });
   if (!existsSync(releasesDir)) return;
   const removed = [];
   const dirs = readdirSync(releasesDir)
     .map((name) => join(releasesDir, name))
-    .filter((dir) => !pointer || dir !== pointer.path);
+    .filter((dir) => (!pointer || dir !== pointer.path) && (!protect || dir !== protect));
   const incomplete = [];
   const complete = [];
   for (const dir of dirs) {
@@ -532,14 +1128,65 @@ export function listManagedReleases({ home = homedir() } = {}) {
     .sort((a, b) => compareVersions(b.version, a.version) || b.path.localeCompare(a.path));
 }
 
+// Unified restart client: request a Crew 3210 restart through the durable
+// supervisor control channel. The hub (3210) writes a restart request; the
+// Windows supervisor executes it and writes a VERIFIED result. This polls
+// until the result arrives (or the timeout elapses). NEVER talks to the
+// legacy 3080 supervisor endpoint.
+export async function requestCrewRuntimeRestart({
+  reason = null,
+  fetchImpl = globalThis.fetch,
+  pollIntervalMs = 1_000,
+  timeoutMs = 90_000,
+  log = () => {},
+} = {}) {
+  const base = 'http://127.0.0.1:3210/_dsh/dsh-crew/runtime';
+  let created;
+  try {
+    const response = await fetchImpl(`${base}/restart-request`, {
+      method: 'POST',
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify({ confirm: true, reason }),
+    });
+    created = await response.json();
+    if (!response.ok || created?.ok !== true) {
+      return { ok: false, code: created?.code ?? 'CREW_3210_RESTART_REQUEST_FAILED', error: created?.error ?? `restart request failed (HTTP ${response.status})` };
+    }
+  } catch (error) {
+    return { ok: false, code: 'CREW_3210_RESTART_REQUEST_UNREACHABLE', error: String(error?.message ?? error) };
+  }
+  const requestId = created.request_id;
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    if (Date.now() > deadline) {
+      return { ok: false, code: 'CREW_3210_RESTART_TIMEOUT', error: `restart request ${requestId} not verified within ${timeoutMs}ms`, request_id: requestId };
+    }
+    try {
+      const statusResponse = await fetchImpl(`${base}/restart-status?id=${encodeURIComponent(requestId)}`, { headers: { accept: 'application/json' } });
+      const status = await statusResponse.json();
+      if (!statusResponse.ok || status?.ok !== true) {
+        // 404 while the watcher has not yet picked the request up is normal.
+        if (statusResponse.status === 404) continue;
+        return { ok: false, code: status?.code ?? 'CREW_3210_RESTART_STATUS_FAILED', error: status?.error ?? 'restart status query failed', request_id: requestId };
+      }
+      if (status.state === 'VERIFIED') {
+        log(`- Crew 3210 restart verified (request ${requestId})`);
+        return { ok: true, state: 'VERIFIED', request_id: requestId, detail: status.detail ?? null };
+      }
+      if (status.state === 'RESTART_REQUEST_EXPIRED' || status.state === 'SUPERVISOR_OWNERSHIP_CONFLICT' || status.state === 'SUPERVISOR_STOP_FAILED' || status.state === 'VERIFY_FAILED') {
+        return { ok: false, code: `CREW_3210_RESTART_${status.state}`, error: `restart ended in state ${status.state}`, request_id: requestId, detail: status.detail ?? null };
+      }
+      // RESTART_REQUESTED: still pending; keep polling.
+    } catch (error) {
+      // Hub may be briefly down mid-restart; keep polling until the deadline.
+      log(`- restart poll transient error: ${String(error?.message ?? error)}`);
+    }
+  }
+}
+
 async function restartOwnedRuntime(fetchImpl = globalThis.fetch) {
-  const response = await fetchImpl('http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart', {
-    method: 'POST',
-    headers: { accept: 'application/json', 'content-type': 'application/json' },
-    body: JSON.stringify({ confirm: true }),
-  });
-  const body = await response.json();
-  return response.ok && body?.ok === true ? body : { ok: false, code: body?.code ?? 'CREW_3210_RESTART_FAILED' };
+  return requestCrewRuntimeRestart({ fetchImpl, reason: 'lifecycle restart' });
 }
 
 async function verifyRuntimeVersion(version, fetchImpl = globalThis.fetch) {
@@ -550,6 +1197,262 @@ async function verifyRuntimeVersion(version, fetchImpl = globalThis.fetch) {
     : { ok: false, code: 'RUNTIME_VERSION_MISMATCH' };
 }
 
+// Cohort verifier: compares the TARGET DSH cohort against the Hub's
+// dsh_version domain (the installed @deepseek-ai/dsh package), NEVER
+// against Crew's own runtime_version (the dsh-crew release). A null
+// dsh_version means unknown cohort and fails closed.
+export async function verifyCrewDshCohort(version, fetchImpl = globalThis.fetch) {
+  let body = null;
+  try {
+    const response = await fetchImpl('http://127.0.0.1:3210/_dsh/dsh-crew/extension', { headers: { accept: 'application/json' } });
+    body = await response.json();
+    if (!response.ok) return { ok: false, code: 'DSH_COHORT_UNREACHABLE' };
+  } catch (error) {
+    return { ok: false, code: 'DSH_COHORT_UNREACHABLE', error: String(error?.message ?? error) };
+  }
+  const dshVersion = body?.extension?.runtime?.dsh_version ?? body?.runtime?.dsh_version ?? null;
+  if (typeof dshVersion !== 'string' || dshVersion.length === 0) {
+    return { ok: false, code: 'DSH_COHORT_UNKNOWN' };
+  }
+  return dshVersion === version
+    ? { ok: true, dsh_version: dshVersion }
+    : { ok: false, code: 'DSH_COHORT_MISMATCH', installed: dshVersion, target: version };
+}
+
+// Full Crew-owned 3210 identity check: service + execution plane + profile
+// + port + non-empty runtime_id, plus the exact target COHORT version read
+// from the dsh_version domain (the installed @deepseek-ai/dsh package).
+// Never compares the cohort against Crew's own runtime_version.
+export async function verifyCrewRuntimeIdentity(version, fetchImpl = globalThis.fetch) {
+  let body = null;
+  try {
+    const response = await fetchImpl('http://127.0.0.1:3210/_dsh/dsh-crew/extension', { headers: { accept: 'application/json' } });
+    body = await response.json();
+    if (!response.ok) return { ok: false, code: 'RUNTIME_IDENTITY_UNREACHABLE' };
+  } catch (error) {
+    return { ok: false, code: 'RUNTIME_IDENTITY_UNREACHABLE', error: String(error?.message ?? error) };
+  }
+  const runtime = body?.extension?.runtime ?? null;
+  const checks = [
+    body?.ok === true,
+    runtime?.service === 'dsh-crew-hub',
+    runtime?.execution_plane === 'hub-3210',
+    runtime?.profile === 'dsh-crew',
+    Number(runtime?.listen_port) === 3210,
+    typeof runtime?.runtime_id === 'string' && runtime.runtime_id.trim().length > 0,
+  ];
+  if (!checks.every(Boolean)) return { ok: false, code: 'RUNTIME_IDENTITY_MISMATCH' };
+  const cohort = await verifyCrewDshCohort(version, fetchImpl);
+  if (!cohort.ok) return cohort;
+  return { ok: true, runtime_id: runtime.runtime_id, dsh_version: cohort.dsh_version };
+}
+
+// Dual-domain post-restart verifier for rollback: the restarted 3210 must
+// report BOTH the expected Crew release version (runtime_version domain)
+// AND the expected DSH cohort (dsh_version domain), alongside full 3210
+// identity. A stale old-Crew process on the right cohort (or vice versa)
+// fails closed instead of reporting rollback success.
+export async function verifyRollbackTarget({ crewVersion, dshVersion, fetchImpl = globalThis.fetch } = {}) {
+  let body = null;
+  try {
+    const response = await fetchImpl('http://127.0.0.1:3210/_dsh/dsh-crew/extension', { headers: { accept: 'application/json' } });
+    body = await response.json();
+    if (!response.ok) return { ok: false, code: 'RUNTIME_IDENTITY_UNREACHABLE' };
+  } catch (error) {
+    return { ok: false, code: 'RUNTIME_IDENTITY_UNREACHABLE', error: String(error?.message ?? error) };
+  }
+  const runtime = body?.extension?.runtime ?? null;
+  const checks = [
+    body?.ok === true,
+    runtime?.service === 'dsh-crew-hub',
+    runtime?.execution_plane === 'hub-3210',
+    runtime?.profile === 'dsh-crew',
+    Number(runtime?.listen_port) === 3210,
+    typeof runtime?.runtime_id === 'string' && runtime.runtime_id.trim().length > 0,
+  ];
+  if (!checks.every(Boolean)) return { ok: false, code: 'RUNTIME_IDENTITY_MISMATCH' };
+  if (typeof crewVersion === 'string' && runtime?.runtime_version !== crewVersion) {
+    return { ok: false, code: 'CREW_VERSION_MISMATCH', installed: runtime?.runtime_version ?? null, target: crewVersion };
+  }
+  if (typeof dshVersion === 'string') {
+    const cohort = await verifyCrewDshCohort(dshVersion, fetchImpl);
+    if (!cohort.ok) return cohort;
+    return { ok: true, runtime_id: runtime.runtime_id, runtime_version: runtime?.runtime_version ?? null, dsh_version: cohort.dsh_version };
+  }
+  return { ok: true, runtime_id: runtime.runtime_id, runtime_version: runtime?.runtime_version ?? null };
+}
+
+// Crew-owned stop/start for cohort migration go through the Windows
+// launcher supervisor (the ONLY process authority) via durable maintenance
+// requests. The npx process owns the runtime TREE swap; the supervisor owns
+// the PROCESS stop/start. The Node sidecar supervisor is deliberately not
+// used here: two authorities must never share the same kill rights.
+function crewSupervisor({ home = homedir() } = {}) {
+  // The ONLY Crew app root both the hub and the Windows launcher agree on.
+  // Requests written anywhere else are invisible to the supervisor.
+  const appRoot = join(home, '.config', 'dsh-crew');
+  const pollMs = 1_000;
+  const timeoutMs = 90_000;
+  // One maintenance transaction = one lease + the pre-stop identity proven
+  // live. stop() fetches the CURRENT live runtime_id (the process exists);
+  // start() reuses that proven identity + lease (the process is stopped by
+  // design and cannot re-prove itself). This pairs stop and start into a
+  // single one-shot transaction instead of two independent requests.
+  let transaction = null;
+  async function fetchCrewIdentity() {
+    try {
+      const response = await fetch('http://127.0.0.1:3210/_dsh/dsh-crew/extension', { headers: { accept: 'application/json' } });
+      if (!response.ok) return null;
+      const body = await response.json();
+      const runtime = body?.extension?.runtime ?? null;
+      return runtime?.runtime_id ? { execution_plane: 'hub-3210', profile: 'dsh-crew', listen_port: 3210, runtime_id: runtime.runtime_id } : null;
+    } catch { return null; }
+  }
+  async function writeMaintenance({ operation, lease, identity, extra = null }) {
+    const { createSupervisorRequest, maintenanceResultsDir } = await import('../supervisor/restart-request.mjs');
+    const created = createSupervisorRequest({
+      appRoot,
+      operation,
+      runtimeIdentity: identity,
+      lease,
+      extra,
+    });
+    if (!created.ok) return created;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      await new Promise((resolve) => setTimeout(resolve, pollMs));
+      if (Date.now() > deadline) {
+        return { ok: false, code: 'MAINTENANCE_TIMEOUT', error: `${operation} ${created.request.request_id} not completed within ${timeoutMs}ms` };
+      }
+      const resultFile = join(maintenanceResultsDir(appRoot), `${created.request.request_id}.json`);
+      let result = null;
+      try {
+        if (existsSync(resultFile)) {
+          result = JSON.parse(readFileSync(resultFile, 'utf8'));
+        }
+      } catch { /* not yet */ }
+      if (!result || result.request_id !== created.request.request_id) continue;
+      if (result.state === 'STOPPED' || result.state === 'VERIFIED') {
+        return { ok: true, state: result.state, request_id: result.request_id, detail: result.detail ?? null };
+      }
+      return { ok: false, code: `MAINTENANCE_${result.state ?? 'FAILED'}`, error: `maintenance ended in state ${result.state}`, detail: result.detail ?? null };
+    }
+  }
+  return {
+    stopOwnedBackend: async () => {
+      const identity = await fetchCrewIdentity();
+      if (!identity?.runtime_id) {
+        transaction = null;
+        return { ok: false, code: 'MAINTENANCE_IDENTITY_UNAVAILABLE', error: 'live 3210 runtime_id unavailable' };
+      }
+      transaction = { lease: `txn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`, runtime_id: identity.runtime_id };
+      const result = await writeMaintenance({ operation: 'maintenance-stop', lease: transaction.lease, identity });
+      if (!result.ok) {
+        // A failed stop must not leave a usable lease behind: clear it so a
+        // later startOwnedBackend() fails closed instead of presenting a
+        // stale transaction.
+        transaction = null;
+      }
+      return result;
+    },
+    startOwnedBackend: async () => {
+      // Reuse the proven stop-phase identity + lease: the process is stopped
+      // by design and fetching identity now would always fail.
+      if (!transaction?.lease || !transaction?.runtime_id) {
+        return { ok: false, code: 'MAINTENANCE_NO_TRANSACTION', error: 'maintenance-start requires a completed maintenance-stop in the same supervisor' };
+      }
+      const identity = { execution_plane: 'hub-3210', profile: 'dsh-crew', listen_port: 3210, runtime_id: transaction.runtime_id };
+      const result = await writeMaintenance({ operation: 'maintenance-start', lease: transaction.lease, identity });
+      transaction = null;
+      return result;
+    },
+  };
+}
+
+// ---- release cohort resolution -------------------------------------------------
+
+// Lifecycle-owned cohort sidecar for a managed release directory. Historical
+// releases (pre-1.0.4) do not pin @deepseek-ai/dsh in their immutable
+// manifest; this records the cohort fact the lifecycle observed for them.
+const cohortFile = (releaseDir) => join(releaseDir, 'release-cohort.json');
+
+// Exact DSH cohort version helper: delegates to the module-level regex.
+export function isExactDshVersion(value) {
+  return typeof value === 'string' && EXACT_DSH_VERSION_RE.test(value);
+}
+
+export function writeReleaseCohort({ releaseDir, dshVersion, source }) {
+  if (!releaseDir || !existsSync(releaseDir) || !isExactDshVersion(dshVersion)) return null;
+  try {
+    const record = {
+      schema_version: 1,
+      release: readManifest(releaseDir)?.version ?? null,
+      dsh_version: dshVersion,
+      source: source ?? 'observed',
+      recorded_at: isoNow(),
+    };
+    writeFileAtomic(cohortFile(releaseDir), JSON.stringify(record, null, 2) + '\n');
+    return record;
+  } catch { return null; }
+}
+
+// Read + validate the cohort sidecar. Returns:
+//   { ok: true, dshVersion }   valid sidecar
+//   { ok: false, present: false }  no sidecar file
+//   { ok: false, present: true, reason }  sidecar EXISTS but is invalid —
+//     callers MUST fail closed on this (never silently fall back to live
+//     discovery, because the recorded value may be corrupt and would feed
+//     rmSync/rename authority).
+function readReleaseCohortSidecar(releaseDir) {
+  const file = cohortFile(releaseDir);
+  if (!existsSync(file)) return { ok: false, present: false };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return { ok: false, present: true, reason: 'sidecar unparseable' };
+  }
+  if (parsed?.schema_version !== 1) {
+    return { ok: false, present: true, reason: 'sidecar schema_version invalid' };
+  }
+  if (!isExactDshVersion(parsed.dsh_version)) {
+    return { ok: false, present: true, reason: `sidecar dsh_version is not an exact version (${String(parsed.dsh_version)})` };
+  }
+  const manifest = readManifest(releaseDir);
+  if (typeof parsed.release !== 'string' || parsed.release.length === 0 || parsed.release !== manifest?.version) {
+    return { ok: false, present: true, reason: 'sidecar release identity does not match the release manifest' };
+  }
+  return { ok: true, dshVersion: parsed.dsh_version };
+}
+
+// Resolve the DSH cohort a managed release corresponds to. Priority:
+//   1. exact @deepseek-ai/dsh pin in the release manifest (dependencies,
+//      then peerDependencies)
+//   2. lifecycle-owned sidecar (release-cohort.json) — if the sidecar EXISTS
+//      but is invalid, FAIL CLOSED (return {invalid:true}) instead of falling
+//      back, because the corrupt value must never be silently ignored.
+//   3. legacy discovery: the release predates cohort awareness; fall back to
+//      the current live runtime tree's cohort ONLY when explicitly allowed
+//      (the caller is the forward-upgrade path that will immediately migrate
+//      to the target). Never used for rollback targeting.
+// Returns { ok:true, dshVersion } | { ok:false, code } | { ok:false, code,
+// invalid:true } when a present-but-invalid sidecar blocks resolution.
+export function resolveReleaseCohort({ releaseDir, allowLegacyLiveFallback = false, readRuntimeVersion = () => null } = {}) {
+  const manifest = readManifest(releaseDir);
+  const pinned = payloadDshVersion(manifest);
+  if (pinned) return { ok: true, dshVersion: pinned };
+  const sidecar = readReleaseCohortSidecar(releaseDir);
+  if (sidecar.ok) return { ok: true, dshVersion: sidecar.dshVersion };
+  if (sidecar.present) {
+    return { ok: false, code: 'RELEASE_COHORT_SIDECAR_INVALID', invalid: true, error: sidecar.reason ?? 'sidecar invalid' };
+  }
+  if (allowLegacyLiveFallback) {
+    const live = readRuntimeVersion();
+    if (isExactDshVersion(live)) return { ok: true, dshVersion: live };
+  }
+  return { ok: false, code: 'RELEASE_COHORT_UNKNOWN' };
+}
+
 export async function npxReleases({ home = homedir(), log = console.log } = {}) {
   const releases = listManagedReleases({ home });
   log(JSON.stringify(releases, null, 2));
@@ -564,11 +1467,30 @@ export async function npxRollback({
   ensureRuntime,
   validatePayload = validateInstalledPayload,
   activate,
-  restart = () => restartOwnedRuntime(),
-  verifyRuntime = (targetVersion) => verifyRuntimeVersion(targetVersion),
+  restart,
+  verifyRuntime,
+  supervisorFactory = crewSupervisor,
 } = {}) {
   const targetVersion = typeof version === 'string' ? version.trim() : '';
   if (!targetVersion) return { ok: false, error: 'rollback requires a target version' };
+  // Rollback shares the update mutual-exclusion lock: it mutates the same
+  // pointer/registration/runtime surfaces as install/update, and the watch
+  // supervisor must observe-only while it runs.
+  const updateLock = acquireUpdateLock({ home });
+  if (!updateLock.ok) return { ok: false, error: `another update is in progress (${updateLock.code})` };
+  try {
+    return await npxRollbackInner({ home, version: targetVersion, log, installer, ensureRuntime, validatePayload, activate, restart, verifyRuntime, supervisorFactory });
+  } finally {
+    releaseUpdateLock({ home, nonce: updateLock.nonce ?? null });
+  }
+}
+
+async function npxRollbackInner({ home, version: targetVersion, log, installer, ensureRuntime, validatePayload, activate, restart, verifyRuntime, supervisorFactory }) {
+  // Journal-aware entry: refuse to overwrite a journal left by a crashed
+  // transaction. Reconcile it first (or fail closed) instead of silently
+  // replacing it with the rollback intent.
+  const pending = reconcileUpdateJournal({ home, log });
+  if (!pending.ok) return { ok: false, error: `refusing rollback with unreconciled journal (${pending.code ?? 'unknown'})` };
   const current = readCurrentPointer({ home });
   if (!current?.path || !existsSync(current.path)) return { ok: false, error: 'no active Crew payload to roll back' };
   const target = listManagedReleases({ home }).find((release) => release.version === targetVersion);
@@ -578,39 +1500,175 @@ export async function npxRollback({
   const validation = validatePayload(target.path, { expectedName: targetManifest?.name, expectedVersion: targetManifest?.version });
   if (!validation.ok) return { ok: false, error: 'target release failed payload validation' };
   const previousManifest = readManifest(current.path);
+  // Cross-cohort rollback: derive the DSH cohort each payload corresponds to
+  // through the FULL resolution chain (manifest exact pin -> lifecycle
+  // release-cohort.json sidecar). Never assume the running code's TARGET:
+  // 1.0.4/rc.1 rolling back to 1.0.3 must restore alpha.5, not verify
+  // against rc.1. A present-but-invalid sidecar fails closed (its recorded
+  // value would otherwise feed rmSync/rename authority). The production path
+  // (no injected verifyRuntime) fails closed when the cohort is unknown;
+  // callers that inject their own verifier/restart mocks (tests, custom
+  // drivers) own the cohort contract and may leave it unset, in which case
+  // no runtime swap is attempted.
+  const productionVerify = typeof verifyRuntime !== 'function';
+  const targetCohort = resolveReleaseCohort({ releaseDir: target.path, allowLegacyLiveFallback: false });
+  const priorCohort = resolveReleaseCohort({ releaseDir: current.path, allowLegacyLiveFallback: false });
+  if (targetCohort.invalid || priorCohort.invalid) {
+    return { ok: false, code: 'RELEASE_COHORT_SIDECAR_INVALID', error: targetCohort.invalid ? targetCohort.error : priorCohort.error };
+  }
+  const targetDshVersion = targetCohort.ok ? targetCohort.dshVersion : null;
+  const priorDshVersion = priorCohort.ok ? priorCohort.dshVersion : null;
+  const cohortKnown = targetDshVersion !== null && priorDshVersion !== null;
+  if (productionVerify && !cohortKnown) {
+    return { ok: false, code: 'RELEASE_DSH_COHORT_UNKNOWN', error: 'release cohort cannot be resolved (no manifest pin and no valid sidecar)' };
+  }
   const activateReleaseFn = activate ?? (({ releaseDir, manifest }) => activateRelease({ home, releaseDir, manifest, log, installer, ensureRuntime }));
+  // Direct-owned restart/verify through ONE supervisor instance. No legacy
+  // 3080 bridge: rollback must work with the bridge fully absent.
+  const supervisor = supervisorFactory({ home });
+  const stopFn = () => supervisor.stopOwnedBackend();
+  const restartFn = restart ?? (async () => {
+    const stopped = await supervisor.stopOwnedBackend();
+    if (!stopped.ok) return stopped;
+    return supervisor.startOwnedBackend();
+  });
+  // Dual-domain post-restart verification: the restarted 3210 must report
+  // BOTH the target Crew release (runtime_version) AND the cohort that
+  // release pins (dsh_version). A stale old-Crew process on the wrong
+  // cohort (or vice versa) fails closed. The verifier is version-parametric
+  // in BOTH domains: target verification checks target crew+cohort,
+  // compensation verification checks prior crew+cohort.
+  const verifyFn = verifyRuntime ?? ((crewVersion, dshVersion) => verifyRollbackTarget({ crewVersion, dshVersion }));
+  // Journal the rollback intent BEFORE switching anything. The rollback
+  // journal carries an explicit verified flag: pointer==target alone does
+  // NOT mean committed until activation + restart + dual verification all
+  // succeed and the journal is marked verified.
+  writeUpdateJournal({
+    home,
+    stage: 'rollback',
+    prior: { name: current.name, version: current.version, path: current.path },
+    candidate: { name: target.name, version: target.version, stageDir: target.path },
+  });
   const switchPointer = (release) => writeCurrentPointer({ home, name: release.name, version: release.version, path: release.path });
+  // Cohort switch for cross-cohort rollback: when the payload we are rolling
+  // back to pins a different DSH cohort than the one currently live, prepare
+  // the target runtime tree (disk-only, process NOT started) BEFORE
+  // activating the older payload. The 3210 is started exactly ONCE after
+  // both the tree and the payload are in place, so an unsupported
+  // payload/cohort pair is never booted. Prefer the retained offline tree;
+  // a registry re-stage is the last resort (migrateCrewDshRuntime prepares
+  // the live tree in place and restarts it — used only when no retained copy
+  // exists and the caller accepts the network dependency).
+  async function ensureTargetCohort() {
+    if (!cohortKnown) return { ok: true, changed: false, unknown: true, prepared: false };
+    // Decide from the DISK runtime tree, never a live 3210 fetch: the hub
+    // may be down, mid-restart, or a stale process (the very condition the
+    // supervisor cohort check exists to catch). The tree that the next boot
+    // will load is the source of truth for whether a swap is needed.
+    const liveDsh = readRuntimeTreeVersionSync(crewDshRuntimeRoot({ home }));
+    if (liveDsh === targetDshVersion) return { ok: true, changed: false, prepared: false };
+    // Prepare the retained tree WITHOUT starting the 3210 (pair ordering).
+    const prepared = await restoreRetainedRuntime({
+      home,
+      version: targetDshVersion,
+      stopOwned: stopFn,
+      log,
+      prepareOnly: true,
+    });
+    if (prepared.ok) return { ok: true, changed: true, prepared: true, version: targetDshVersion };
+    return { ok: false, code: 'ROLLBACK_RUNTIME_RESTORE_FAILED', error: `cohort ${targetDshVersion} is not retained and cannot be restored offline`, detail: prepared };
+  }
   try {
+    const cohort = await ensureTargetCohort();
+    if (!cohort.ok) throw Object.assign(new Error(cohort.error), { code: cohort.code });
+    // Activate the target payload BEFORE any start: with the target tree
+    // already on disk (or the live tree already matching), the 3210 must
+    // never boot while the profile still points at the prior payload.
     switchPointer(target);
     if (!await activateReleaseFn({ releaseDir: target.path, manifest: targetManifest })) throw new Error('target release activation failed');
-    const restarted = await restart(target.version);
-    if (restarted?.ok === false) throw Object.assign(new Error('target runtime restart failed'), { code: restarted.code });
-    const runtime = await verifyRuntime(target.version);
-    if (runtime?.ok !== true) throw Object.assign(new Error('target runtime verification failed'), { code: runtime?.code ?? 'RUNTIME_VERSION_MISMATCH' });
+    // Start ONCE after tree + payload both target the rollback release.
+    let restarted = null;
+    if (cohort.changed) {
+      // Tree was swapped by the prepare step; the process is stopped.
+      restarted = await supervisor.startOwnedBackend();
+      if (restarted?.ok === false) throw Object.assign(new Error('target runtime restart failed'), { code: restarted.code });
+    } else {
+      restarted = await restartFn(target.version);
+      if (restarted?.ok === false) throw Object.assign(new Error('target runtime restart failed'), { code: restarted.code });
+    }
+    const runtime = await verifyFn(target.version, cohortKnown ? targetDshVersion : undefined);
+    if (runtime?.ok !== true) throw Object.assign(new Error('target runtime verification failed'), { code: runtime?.code ?? 'RUNTIME_IDENTITY_MISMATCH' });
     log(`✓ rolled back Crew payload to ${target.version}`);
+    // Persist verification BEFORE clearing: a crash between verify
+    // success and journal clear must still finalize on recovery.
+    const marked = markJournalVerified({
+      home,
+      stage: 'rollback',
+      prior: { name: current.name, version: current.version, path: current.path },
+      candidate: { name: target.name, version: target.version, stageDir: target.path },
+    });
+    if (!marked.ok) throw Object.assign(new Error('rollback journal mark-verified failed'), { code: marked.code ?? 'JOURNAL_MARK_FAILED' });
+    clearUpdateJournal({ home });
     return { ok: true, rolled_back: true, version: target.version, path: target.path, restart: restarted, runtime };
   } catch (error) {
     const prior = { name: current.name, version: current.version, path: current.path };
     let recovery;
     try {
+      // Pair-ordered compensation: prepare the PRIOR runtime tree (disk only,
+      // process stopped), activate the prior payload, THEN start once and
+      // dual-verify — the 3210 never boots a mismatched pair. When the
+      // cohort contract is unknown (injected mocks own it), skip the runtime
+      // swap and restore the payload only.
+      let processStopped = false;
+      if (cohortKnown) {
+        const priorCohortOk = await restoreRetainedRuntime({
+          home,
+          version: priorDshVersion,
+          stopOwned: stopFn,
+          log,
+          prepareOnly: true,
+        });
+        if (priorCohortOk.ok) {
+          // Retained tree swapped in; the 3210 is stopped and must be
+          // started after the payload activation below.
+          processStopped = true;
+        } else {
+          // Fall back to a registry install at the live root — PREPARE ONLY:
+          // the process stays stopped until the prior payload is activated,
+          // so an unsupported payload/cohort pair is never booted.
+          const m = await migrateCrewDshRuntime({
+            home,
+            version: priorDshVersion,
+            stopOwned: stopFn,
+            log,
+            prepareOnly: true,
+          });
+          if (!m.ok) throw Object.assign(new Error('prior cohort could not be restored'), { stage: 'cohort' });
+          processStopped = true;
+        }
+      }
       switchPointer(prior);
       if (!previousManifest) throw Object.assign(new Error('previous release manifest unavailable'), { stage: 'activation' });
       const activated = await activateReleaseFn({ releaseDir: prior.path, manifest: previousManifest });
       if (activated !== true) throw Object.assign(new Error('previous release activation failed'), { stage: 'activation' });
-      const restarted = await restart(prior.version);
+      // Start ONCE: tree + payload both point at the prior release now.
+      const restarted = processStopped
+        ? await supervisor.startOwnedBackend()
+        : await restartFn(prior.version);
       if (restarted?.ok !== true) throw Object.assign(new Error('previous runtime restart failed'), { stage: 'restart' });
-      const runtime = await verifyRuntime(prior.version);
+      const runtime = await verifyFn(prior.version, cohortKnown ? priorDshVersion : undefined);
       if (runtime?.ok !== true) throw Object.assign(new Error('previous runtime verification failed'), { stage: 'verification' });
       const restoredPointer = readCurrentPointer({ home });
       if (restoredPointer?.path !== prior.path || restoredPointer.version !== prior.version) {
         throw Object.assign(new Error('previous release pointer was not restored'), { stage: 'pointer' });
       }
       recovery = { ok: true, version: prior.version, path: prior.path };
+      clearUpdateJournal({ home });
     } catch (recoveryError) {
       recovery = {
         ok: false,
         code: 'RELEASE_ROLLBACK_RECOVERY_FAILED',
-        stage: ['activation', 'restart', 'verification', 'pointer'].includes(recoveryError?.stage) ? recoveryError.stage : 'unknown',
+        stage: ['cohort', 'activation', 'restart', 'verification', 'pointer'].includes(recoveryError?.stage) ? recoveryError.stage : 'unknown',
       };
     }
     return {
@@ -649,21 +1707,330 @@ export function sanitizedPackageManagerEnv(baseEnv = process.env) {
   return env;
 }
 
-async function ensureRuntimeStep({ home, log, ensureRuntime }) {
-  const ensure = ensureRuntime ?? ((opts) => {
+// Production migration adapter: builds the migrate callback used by the
+// default ensureRuntimeStep path. Exactly ONE supervisor instance is
+// created per migration and reused by stop/start/verify/rollback so the
+// child identity stays coherent. Exported so tests can prove the
+// production default wiring (single instance, full identity verify)
+// instead of hand-injecting three mock callbacks.
+export function buildProductionMigration({ home, log = () => {}, stopOwned, startOwned, verifyOwned, supervisorFactory = crewSupervisor } = {}) {
+  const supervisor = supervisorFactory({ home });
+  return (opts) => migrateCrewDshRuntime({
+    home,
+    version: TARGET_DSH_VERSION,
+    stopOwned: stopOwned ?? (() => supervisor.stopOwnedBackend()),
+    startOwned: startOwned ?? (() => supervisor.startOwnedBackend()),
+    verifyOwned: verifyOwned ?? (() => verifyCrewRuntimeIdentity(TARGET_DSH_VERSION)),
+    ...opts,
+  });
+}
+
+async function ensureRuntimeStep({ home, log, ensureRuntime, migrateRuntime, stopOwned, startOwned, verifyOwned, supervisorFactory = crewSupervisor }) {  const ensure = ensureRuntime ?? ((opts) => {
     const r = ensureCrewDshRuntime({ ...opts, env: sanitizedPackageManagerEnv() });
     if (!r.ok && r.stderrTail) {
       log(`  (runtime installer said: ${r.stderrTail})`);
     }
+    if (!r.ok && r.code === 'DSH_RUNTIME_COHORT_MISMATCH') {
+      return { ok: false, code: r.code, error: r.error, installed: r.installed, target: r.target, needsMigration: true };
+    }
     return r.ok ? { ok: true, version: r.cli?.version ?? null } : { ok: false, error: r.error ?? r.code ?? 'runtime bootstrap failed' };
   });
+  // Production migration wiring: ONE supervisor instance per migration,
+  // reused by stop/start/verify/rollback so child identity stays coherent.
+  // No legacy bridge involved. Missing callbacks fail closed inside
+  // migrateCrewDshRuntime.
+  const migrate = migrateRuntime ?? buildProductionMigration({ home, log, stopOwned, startOwned, verifyOwned, supervisorFactory });
   const r = await ensure({ home });
-  if (!r?.ok) {
-    log(`✗ reusable Crew DSH runtime unavailable: ${r?.error ?? 'unknown error'}`);
-    return false;
+  if (r?.ok) {
+    log(`✓ reusable Crew DSH runtime${r.version ? ` (@${r.version})` : ''}`);
+    return true;
+  }
+  if (r?.needsMigration === true) {
+    log(`- runtime cohort stale (${r.installed} -> ${r.target}); migrating via staged transaction`);
+    const m = await migrate({ log });
+    if (!m?.ok) {
+      log(`✗ runtime cohort migration failed: ${m?.error ?? m?.code ?? 'unknown error'}`);
+      return false;
+    }
+    log(`✓ runtime cohort migrated (@${m.version})`);
+    return true;
+  }
+  log(`✗ reusable Crew DSH runtime unavailable: ${r?.error ?? 'unknown error'}`);
+  return false;
+}
+
+// ---- coordinated payload + cohort transaction ---------------------------------
+
+// Perform an update whose candidate payload pins a DIFFERENT DSH cohort than
+// the currently live one (e.g. 1.0.3/alpha.5 -> 1.0.4/rc.1). The payload
+// activation and the runtime swap are one transaction so the 3210 never runs
+// an unsupported payload/cohort combination:
+//
+//   1. stage candidate payload            (caller did)
+//   2. stage target DSH cohort            (no live touch)
+//   3. write durable journal              (runtime segment included)
+//   4. stop owned 3210 ONCE
+//   5. swap runtime live -> retained-prior, staged -> live
+//   6. activate candidate Crew payload
+//   7. start owned 3210 ONCE
+//   8. dual verify: runtime_version == candidate version AND
+//                   dsh_version     == candidate cohort
+//   9. mark journal verified
+//  10. write current.json LAST (commit point)
+//  11. clear journal
+//
+// Any failure before step 10 compensates: restore prior payload + prior
+// cohort (retained offline tree first, registry re-stage as fallback) and
+// restart, verifying the prior dual identity before clearing the journal.
+export async function performCoordinatedCohortUpdate({
+  home = homedir(),
+  log = console.log,
+  prior,                 // current pointer record
+  priorDshVersion,       // cohort pinned by the prior payload
+  candidateManifest,     // candidate payload manifest
+  candidateDshVersion,   // cohort pinned by the candidate payload
+  stageDir,              // validated candidate payload stage dir
+  installer = realInstaller,
+  activate = null,       // injectable activation (tests)
+  stopOwned,
+  startOwned,
+  verifyOwned,
+  supervisorFactory = crewSupervisor,
+  stageOptions = {},
+} = {}) {
+  if (!candidateManifest?.name || !candidateManifest?.version) return { ok: false, error: 'candidate manifest invalid' };
+  if (!prior?.path || !existsSync(prior.path)) return { ok: false, error: 'prior payload missing for coordinated update' };
+  const supervisor = supervisorFactory({ home });
+  const stopFn = stopOwned ?? (() => supervisor.stopOwnedBackend());
+  const startFn = startOwned ?? (() => supervisor.startOwnedBackend());
+  const verifyFn = verifyOwned ?? ((crewVersion, dshVersion) => verifyRollbackTarget({ crewVersion, dshVersion }));
+  const activateFn = activate ?? (({ releaseDir, manifest }) => activateRelease({ home, releaseDir, manifest, log, installer }));
+
+  const liveRoot = crewDshRuntimeRoot({ home });
+  const retainedRoot = join(crewDshHome({ home }), 'retained-runtimes');
+  // Plan the prior-tree parking path BEFORE any destructive step and persist
+  // it in the journal so a crash mid-swap is synchronously recoverable by
+  // reconcileUpdateJournal (it can move priorRoot back onto liveRoot without
+  // needing to know any in-memory nonce).
+  const prevPath = join(crewDshHome({ home }), `runtime-prev-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`);
+
+  // Journal the full coordinated intent BEFORE any destructive step. The
+  // journal carries prior+candidate dshVersion plus runtime roots so a crash
+  // at any point is recoverable by reconcileUpdateJournal.
+  writeUpdateJournal({
+    home,
+    stage: 'coordinated-update',
+    prior: { name: prior.name, version: prior.version, path: prior.path, dshVersion: priorDshVersion },
+    candidate: { name: candidateManifest.name, version: candidateManifest.version, stageDir, dshVersion: candidateDshVersion },
+    runtime: {
+      state: 'staged',
+      liveRoot,
+      priorRoot: prevPath,
+      priorVersion: priorDshVersion,
+      candidateVersion: candidateDshVersion,
+      retainedRoot,
+    },
+  });
+
+  const switchPointer = (release) => writeCurrentPointer({ home, name: release.name, version: release.version, path: release.path });
+  const priorRelease = { name: prior.name, version: prior.version, path: prior.path };
+  const candidateRelease = { name: candidateManifest.name, version: candidateManifest.version, path: stageDir };
+
+  async function compensate() {
+    // Pair-ordered compensation: prepare the PRIOR runtime tree (disk only,
+    // process left stopped — whether from the retained tree or a registry
+    // install), activate the prior payload, then start ONCE and dual-verify
+    // prior identity. The 3210 is never started while tree and payload
+    // disagree, and never started twice.
+    // Retained offline tree first (prepare-only)...
+    const priorCohortOk = await restoreRetainedRuntime({
+      home,
+      version: priorDshVersion,
+      stopOwned: stopFn,
+      log,
+      prepareOnly: true,
+    });
+    if (!priorCohortOk.ok) {
+      // ...then registry install at the live root, prepare-only: the process
+      // stays stopped until the matching payload is activated below.
+      const migrated = await migrateCrewDshRuntime({
+        home,
+        version: priorDshVersion,
+        stopOwned: stopFn,
+        log,
+        prepareOnly: true,
+      });
+      if (!migrated.ok) {
+        return { ok: false, code: 'COORDINATED_COMPENSATE_COHORT_FAILED', error: migrated.error ?? 'prior cohort restore failed' };
+      }
+    }
+    const activated = await activateFn({ releaseDir: prior.path, manifest: readManifest(prior.path) });
+    if (activated !== true) return { ok: false, code: 'COORDINATED_COMPENSATE_ACTIVATION_FAILED' };
+    // Start ONCE: tree + payload both point at the prior release now.
+    const restarted = await startFn();
+    if (restarted?.ok !== true) return { ok: false, code: restarted?.code ?? 'COORDINATED_COMPENSATE_RESTART_FAILED' };
+    const verified = await verifyFn(prior.version, priorDshVersion);
+    if (verified?.ok !== true) return { ok: false, code: verified?.code ?? 'COORDINATED_COMPENSATE_VERIFY_FAILED' };
+    switchPointer(priorRelease);
+    return { ok: true };
+  }
+
+  try {
+    // Stop ONCE, install the target cohort AT the live root (pnpm shims are
+    // absolute-path; the tree must be born at its final resting path),
+    // activate payload, start ONCE.
+    const stopped = await stopFn();
+    if (!stopped.ok) {
+      // Nothing was swapped yet; just clear the journal (no activation ran).
+      clearUpdateJournal({ home });
+      return { ok: false, code: stopped.code ?? 'COORDINATED_STOP_FAILED', error: stopped.error ?? 'could not stop owned 3210' };
+    }
+    let liveMoved = false;
+    try {
+      // Move live runtime aside, retaining its tree for offline rollback.
+      if (existsSync(liveRoot)) {
+        // prevPath is unique per attempt and already recorded in the journal.
+        try { rmSync(prevPath, { recursive: true, force: true }); } catch {}
+        renameSync(liveRoot, prevPath);
+        liveMoved = true;
+      }
+      mkdirSync(liveRoot, { recursive: true });
+    } catch (error) {
+      // Park failed: restore live tree before anything else.
+      try {
+        if (liveMoved && !existsSync(liveRoot) && prevPath && existsSync(prevPath)) renameSync(prevPath, liveRoot);
+      } catch { /* best effort */ }
+      const comp = await compensate();
+      return finalizeCompensationFailure({ home, code: 'COORDINATED_RUNTIME_PARK_FAILED', error: String(error?.message ?? error), comp });
+    }
+    // Install the target cohort at the live root. On failure, roll back the
+    // parked prior tree and compensate the payload.
+    const installed = installDshInto({ root: liveRoot, version: candidateDshVersion, ...stageOptions });
+    if (!installed.ok) {
+      let comp = { ok: false };
+      try {
+        rmSync(liveRoot, { recursive: true, force: true });
+        if (liveMoved && existsSync(prevPath)) renameSync(prevPath, liveRoot);
+        comp = await compensate();
+      } catch { /* compensate below already reports */ }
+      return finalizeCompensationFailure({ home, code: installed.code ?? 'COORDINATED_RUNTIME_INSTALL_FAILED', error: installed.error ?? 'runtime install at live root failed', comp });
+    }
+    // Runtime now on candidate cohort; live tree preserved at prevPath.
+    const activated = await activateFn({ releaseDir: stageDir, manifest: candidateManifest });
+    if (activated !== true) {
+      const comp = await compensate();
+      return finalizeCompensationFailure({ home, code: null, error: 'candidate activation failed', comp });
+    }
+    const started = await startFn();
+    if (started?.ok !== true) {
+      const comp = await compensate();
+      return finalizeCompensationFailure({ home, code: started?.code ?? 'COORDINATED_START_FAILED', error: started?.error ?? 'restart after coordinated update failed', comp });
+    }
+    const verified = await verifyFn(candidateManifest.version, candidateDshVersion);
+    if (verified?.ok !== true) {
+      const comp = await compensate();
+      return finalizeCompensationFailure({ home, code: verified?.code ?? 'COORDINATED_VERIFY_FAILED', error: verified?.error ?? 'dual identity verification failed', comp });
+    }
+
+    // Durable retention of the parked prior tree is a COMMIT PREREQUISITE:
+    // "update complete" must imply the offline rollback source for the
+    // previous cohort is durable. A failed retain never grants delete
+    // authority over the parked tree; it aborts the commit and compensates.
+    if (prevPath && existsSync(prevPath)) {
+      const retained = retainParkedRuntimeTree({ home, prevPath, priorDshVersion });
+      if (!retained.ok) {
+        // Leave the parked tree in place (it is the only prior copy); do NOT
+        // commit. Compensate so the live pair returns to prior.
+        const comp = await compensate().catch(() => ({ ok: false }));
+        return finalizeCompensationFailure({ home, code: 'COORDINATED_RETAIN_FAILED', error: retained.error ?? 'could not durably retain prior runtime', comp, parked: prevPath });
+      }
+    }
+
+    // Mark the journal verified BEFORE the pointer write. Crash recovery
+    // then has a clean WAL relation: pointer==prior means not committed,
+    // pointer==candidate with verified journal means committed.
+    const marked = markJournalVerified({
+      home,
+      stage: 'coordinated-update',
+      prior: { name: prior.name, version: prior.version, path: prior.path, dshVersion: priorDshVersion },
+      candidate: { name: candidateManifest.name, version: candidateManifest.version, stageDir, dshVersion: candidateDshVersion },
+      runtime: {
+        state: 'verified',
+        liveRoot,
+        candidateRoot: liveRoot,
+        priorVersion: priorDshVersion,
+        candidateVersion: candidateDshVersion,
+        retainedRoot,
+      },
+    });
+    if (!marked.ok) {
+      const comp = await compensate().catch(() => ({ ok: false }));
+      return finalizeCompensationFailure({ home, code: marked.code ?? 'JOURNAL_MARK_FAILED', error: 'coordinated journal mark-verified failed', comp });
+    }
+
+    // COMMIT POINT / LAST: pointer write after the verified journal.
+    switchPointer(candidateRelease);
+
+    clearUpdateJournal({ home });
+    log(`✓ coordinated update committed: Crew ${candidateManifest.version} + DSH ${candidateDshVersion}`);
+    return { ok: true, version: candidateManifest.version, path: stageDir, dsh_version: candidateDshVersion, restarted: started };
+  } catch (error) {
+    const comp = await compensate().catch(() => ({ ok: false }));
+    return finalizeCompensationFailure({ home, code: null, error: error?.message ?? 'coordinated update failed', comp });
+  }
+}
+
+// Shared failure exit for a compensated coordinated transaction. The journal
+// is cleared ONLY when compensation fully succeeded (prior payload
+// activated, prior runtime restored, restart + dual verify passed). When
+// compensation itself failed, the journal is the ONLY durable recovery
+// witness describing priorRoot/liveRoot/versions — it must survive so the
+// next reconcile can finish the recovery. A compensation-failed marker is
+// appended so operators can see why the journal is still present.
+function finalizeCompensationFailure({ home, code, error, comp, parked = null }) {
+  if (comp.ok === true) {
+    clearUpdateJournal({ home });
+  } else {
+    // Compensation failed: RETAIN the journal (never delete the recovery
+    // witness) and annotate it with the failure for the next reconcile pass.
+    try {
+      const file = updateJournalFile({ home });
+      if (existsSync(file)) {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        raw.compensation_failed = true;
+        raw.compensation_error = String(error ?? comp.error ?? 'compensation failed');
+        writeFileAtomic(file, JSON.stringify(raw, null, 2) + '\n');
+      }
+    } catch { /* best effort annotation; journal itself stays untouched */ }
+  }
+  return { ok: false, code: code ?? undefined, error: error ?? 'coordinated update failed', compensated: comp.ok === true, compensation_failed: comp.ok !== true, parked };
+}
+
+// Unified durable retention of a parked prior runtime tree. NEVER deletes
+// the parked tree on failure: the caller decides whether to compensate
+// (abort the commit) or surface the parked path as a durable rollback
+// source. Bounded retry absorbs transient Windows file-handle contention
+// right after the new 3210 starts.
+function retainParkedRuntimeTree({ home, prevPath, priorDshVersion, rename = renameSync }) {
+  try {
+    if (!existsSync(prevPath)) return { ok: true, retained: false };
+    const retainedRoot = join(crewDshHome({ home }), 'retained-runtimes');
+    const target = join(retainedRoot, priorDshVersion);
+    mkdirSync(retainedRoot, { recursive: true });
+    if (existsSync(target)) rmSync(target, { recursive: true, force: true });
+    const delays = [0, 50, 150, 400];
+    let lastError = null;
+    for (const delay of delays) {
+      if (delay > 0) { const until = Date.now() + delay; while (Date.now() < until) { /* busy-wait bounded */ } }
+      try {
+        rename(prevPath, target);
+        return { ok: true, retained: true, version: priorDshVersion, path: target };
+      } catch (error) { lastError = error; }
+    }
+    return { ok: false, retained: false, prevPath, error: String(lastError?.message ?? lastError) };
+  } catch (error) {
+    return { ok: false, retained: false, prevPath, error: String(error?.message ?? error) };
   }
-  log(`✓ reusable Crew DSH runtime${r.version ? ` (@${r.version})` : ''}`);
-  return true;
 }
 
 // ---- commands -----------------------------------------------------------------
@@ -715,49 +2082,36 @@ async function activateRelease({ home, releaseDir, manifest, log, installer }) {
   }
   log('✓ Claude Code integration');
 
+  // The official ~/.dsh/profiles/web tree is read-only: activation never
+  // repairs or mutates the official bridge. The isolated 3210 Crew backend
+  // is the only runtime Crew owns.
   const official = officialWebIntegrationStatus({ home });
-  if (official.enabled) {
-    const repaired = ensureOfficialWebIntegration({ home, releaseDir });
-    if (!repaired.ok) {
-      log(`✗ official 3080 bridge repair failed (${repaired.code ?? 'unknown'})`);
-      return false;
-    }
-    log('✓ official 3080 UI bridge → isolated Crew backend on 3210');
+  if (official.legacy_present) {
+    log('- legacy official 3080 bridge record present but deprecated; official web profile is read-only and untouched');
   }
   return true;
 }
 
+// Compensate a failed candidate activation by re-pointing live activation
+// surfaces (profile registration + host integrations) back at the prior
+// release. Rewriting current.json alone is NOT enough: a crash between
+// activation and pointer commit leaves live surfaces on the candidate.
+async function compensateActivation({ home, prior, log, installer }) {
+  if (!prior?.path || !existsSync(prior.path)) return { ok: false, code: 'PRIOR_RELEASE_MISSING' };
+  const manifest = readManifest(prior.path);
+  if (!manifest?.name || !manifest?.version) return { ok: false, code: 'PRIOR_MANIFEST_INVALID' };
+  const ok = await activateRelease({ home, releaseDir: prior.path, manifest, log, installer });
+  return ok ? { ok: true, version: manifest.version, path: prior.path } : { ok: false, code: 'PRIOR_ACTIVATION_FAILED' };
+}
+
 export async function npxIntegrate({ home = homedir(), log = console.log } = {}) {
-  const pointer = readCurrentPointer({ home });
-  if (!pointer || !existsSync(pointer.path)) {
-    log('✗ install DSH Crew before enabling the official 3080 integration');
-    return { ok: false, error: 'DSH Crew is not installed' };
-  }
-  const validated = validateInstalledPayload(pointer.path, { expectedName: pointer.name, expectedVersion: pointer.version });
-  if (!validated.ok) {
-    log('✗ installed DSH Crew payload is damaged; run dsh-crew update first');
-    return { ok: false, error: 'installed payload invalid' };
-  }
-  const result = ensureOfficialWebIntegration({ home, releaseDir: pointer.path });
-  if (!result.ok) {
-    log(`✗ official 3080 integration failed (${result.code ?? 'unknown'})`);
-    return { ok: false, error: result.code ?? 'integration failed' };
-  }
-  log(result.changed
-    ? '✓ official 3080 UI connected to the isolated Crew backend on 3210'
-    : '- official 3080 UI integration already healthy');
-  log(`  backup: ${result.backupFile}`);
-  return { ok: true, changed: result.changed, backupFile: result.backupFile };
+  log('✗ official 3080 integration is disabled: the official web profile is read-only');
+  return { ok: false, error: 'OFFICIAL_WEB_PROFILE_READ_ONLY' };
 }
 
 export async function npxDetach({ home = homedir(), log = console.log } = {}) {
-  const result = removeOfficialWebIntegration({ home });
-  if (!result.ok) {
-    log(`✗ official 3080 integration removal failed (${result.code ?? 'unknown'})`);
-    return { ok: false, error: result.code ?? 'detach failed' };
-  }
-  log(result.removed ? '✓ official 3080 bridge removed; isolated 3210 mode remains available' : '- official 3080 bridge already absent');
-  return { ok: true, removed: result.removed };
+  log('✗ official 3080 detach is disabled: the official web profile is read-only');
+  return { ok: false, error: 'OFFICIAL_WEB_PROFILE_READ_ONLY' };
 }
 
 export async function npxInstall({
@@ -769,6 +2123,18 @@ export async function npxInstall({
   npmInstaller,
 } = {}) {
   log('DSH Crew installer (npx-managed)');
+  const updateLock = acquireUpdateLock({ home });
+  if (!updateLock.ok) return { ok: false, error: `another update is in progress (${updateLock.code})` };
+  try {
+    return await npxInstallInner({ home, log, sourceRoot, installer, ensureRuntime, npmInstaller });
+  } finally {
+    releaseUpdateLock({ home, nonce: updateLock.nonce ?? null });
+  }
+}
+
+async function npxInstallInner({ home, log, sourceRoot, installer, ensureRuntime, npmInstaller }) {
+  const reconciled = reconcileUpdateJournal({ home, log });
+  if (!reconciled.ok) return { ok: false, error: `update journal recovery failed (${reconciled.code ?? 'unknown'})` };
   const candidateRoot = sourceRoot ?? runningPackageRoot();
   const manifest = readManifest(candidateRoot);
   if (!manifest?.name || !manifest?.version) return { ok: false, error: 'candidate package manifest invalid' };
@@ -792,13 +2158,24 @@ export async function npxInstall({
   }
   log(`✓ candidate payload staged (${manifest.version})`);
 
-  const releaseDir = commitStagedRelease({ stageDir: staged.stageDir, manifest, home });
-  log(`✓ durable release committed under Crew-owned state`);
+  // Transaction order: stage -> runtime gate -> journal(begin) ->
+  // activation -> pointer commit LAST -> clear journal -> GC. A crash
+  // anywhere before the pointer write leaves the prior release
+  // authoritative for reconcileUpdateJournal.
+  const prior = readCurrentPointer({ home });
+  if (!await ensureRuntimeStep({ home, log, ensureRuntime })) return { ok: false, error: 'Crew DSH runtime bootstrap failed' };
 
-  const activated = await activateRelease({ home, releaseDir, manifest, log, installer });
-  if (!activated) return { ok: false, error: 'activation failed' };
+  beginReleaseActivation({ stageDir: staged.stageDir, manifest, home, prior });
+  log(`✓ candidate payload staged (${manifest.version})`);
 
-  if (!await ensureRuntimeStep({ home, log, ensureRuntime })) return { ok: false, error: 'Crew DSH runtime bootstrap failed' };
+  const activated = await activateRelease({ home, releaseDir: staged.stageDir, manifest, log, installer });
+  if (!activated) {
+    const compensated = prior?.path ? await compensateActivation({ home, prior, log, installer }) : null;
+    return { ok: false, error: 'activation failed', compensated: compensated?.ok === true };
+  }
+
+  const releaseDir = commitActivatedRelease({ stageDir: staged.stageDir, manifest, home, prior });
+  log(`✓ durable release committed under Crew-owned state`);
 
   log('');
   log('Done.');
@@ -954,6 +2331,18 @@ export async function npxUpdate({
   runner = spawnSync,
 } = {}) {
   log('DSH Crew updater');
+  const updateLock = acquireUpdateLock({ home });
+  if (!updateLock.ok) return { ok: false, error: `another update is in progress (${updateLock.code})` };
+  try {
+    return await npxUpdateInner({ home, log, sourceRoot, candidate, spec, installer, ensureRuntime, npmInstaller, runner });
+  } finally {
+    releaseUpdateLock({ home, nonce: updateLock.nonce ?? null });
+  }
+}
+
+async function npxUpdateInner({ home, log, sourceRoot, candidate, spec, installer, ensureRuntime, npmInstaller, runner = spawnSync }) {
+  const journalRecovery = reconcileUpdateJournal({ home, log });
+  if (!journalRecovery.ok) return { ok: false, error: `update journal recovery failed (${journalRecovery.code ?? 'unknown'})` };
   // Candidate resolution: explicit path/dir override > a newer validated
   // running launcher > configured npm registry (@latest). This makes the
   // supported legacy bootstrap (`npm install -g ...@latest`, then `update`)
@@ -1018,14 +2407,97 @@ export async function npxUpdate({
     }
     log(`✓ candidate payload staged and validated (${manifest.version})`);
 
-    const releaseDir = commitStagedRelease({ stageDir: staged.stageDir, manifest, home });
-    log('✓ durable release committed under Crew-owned state');
-
-    const activated = await activateRelease({ home, releaseDir, manifest, log, installer });
-    if (!activated) return { ok: false, error: 'activation failed' };
+    // Transaction order: stage -> runtime gate -> journal(begin) ->
+    // activation -> pointer commit LAST -> clear journal -> GC. A crash
+    // anywhere before the pointer write leaves the prior release
+    // authoritative for reconcileUpdateJournal.
+    const prior = readCurrentPointer({ home });
+    const priorManifest = prior?.path ? readManifest(prior.path) : null;
+    const candidateDsh = payloadDshVersion(manifest);
+    // Resolve the PRIOR cohort through the full resolution chain. Historical
+    // releases (pre-1.0.4) carry no manifest pin, so for the FORWARD upgrade
+    // path the live runtime tree's current cohort is the authoritative fact
+    // (it is exactly the cohort this upgrade will migrate away from). This
+    // guarantees even a legacy unpinned 1.0.3 prior routes through the
+    // coordinated payload+runtime transaction instead of the standalone
+    // migrate path. A present-but-invalid sidecar fails closed.
+    let priorDsh = null;
+    if (prior?.path) {
+      const priorCohort = resolveReleaseCohort({
+        releaseDir: prior.path,
+        allowLegacyLiveFallback: true,
+        readRuntimeVersion: () => readRuntimeTreeVersionSync(crewDshRuntimeRoot({ home })),
+      });
+      if (priorCohort.invalid) {
+        return { ok: false, error: `prior release cohort sidecar invalid (${priorCohort.error ?? 'unknown'})` };
+      }
+      priorDsh = priorCohort.ok ? priorCohort.dshVersion : null;
+    }
+    const needsCohortSwap = candidateDsh !== null && priorDsh !== null && candidateDsh !== priorDsh;
+
+    if (needsCohortSwap) {
+      // Cross-cohort update: payload activation and runtime swap are ONE
+      // coordinated transaction so the 3210 never runs an unsupported
+      // payload/cohort combination.
+      log(`- cross-cohort update: DSH ${priorDsh} -> ${candidateDsh}; running coordinated payload+runtime transaction`);
+      // The discovered prior cohort must be DURABLY recorded as a sidecar
+      // BEFORE the transaction: "update complete" must imply the legacy
+      // release can later be rolled back offline. Write then READ BACK
+      // (without live fallback) — a writer that returned null OR a sidecar
+      // that does not round-trip to the discovered cohort aborts before any
+      // runtime park / payload activation / pointer mutation. A pre-existing
+      // valid sidecar for the same cohort also satisfies the read-back.
+      const persistResult = writeReleaseCohort({ releaseDir: prior.path, dshVersion: priorDsh, source: 'discovered-live-runtime' });
+      const readBack = resolveReleaseCohort({ releaseDir: prior.path, allowLegacyLiveFallback: false });
+      const sidecarDurable = persistResult !== null
+        && readBack.ok === true
+        && readBack.dshVersion === priorDsh;
+      if (!sidecarDurable) {
+        return {
+          ok: false,
+          code: 'RELEASE_COHORT_SIDECAR_PERSIST_FAILED',
+          error: `prior release cohort sidecar could not be durably persisted (${readBack.ok ? 'read-back mismatch' : readBack.error ?? 'write failed'}); refusing cross-cohort update that could not be rolled back offline`,
+        };
+      }
+      const coordinated = await performCoordinatedCohortUpdate({
+        home,
+        log,
+        prior,
+        priorDshVersion: priorDsh,
+        candidateManifest: manifest,
+        candidateDshVersion: candidateDsh,
+        stageDir: staged.stageDir,
+        installer,
+      });
+      if (!coordinated.ok) {
+        return { ok: false, error: `coordinated cohort update failed${coordinated.code ? ` (${coordinated.code})` : ''}`, compensated: coordinated.compensated === true };
+      }
+      // Record the candidate cohort sidecar for the newly committed release.
+      const committedRelease = readCurrentPointer({ home });
+      if (committedRelease?.path) writeReleaseCohort({ releaseDir: committedRelease.path, dshVersion: candidateDsh, source: 'manifest-pin' });
+      noteLauncherDivergence({ log, home });
+      log('');
+      log('Done.');
+      log('Restart DeepSeek Harness and Codex Desktop.');
+      return { ok: true, updated: true, version: manifest.version, path: staged.stageDir, coordinated: true, dsh_version: candidateDsh };
+    }
 
     if (!await ensureRuntimeStep({ home, log, ensureRuntime })) return { ok: false, error: 'Crew DSH runtime bootstrap failed' };
 
+    beginReleaseActivation({ stageDir: staged.stageDir, manifest, home, prior });
+
+    const activated = await activateRelease({ home, releaseDir: staged.stageDir, manifest, log, installer });
+    if (!activated) {
+      const compensated = prior?.path ? await compensateActivation({ home, prior, log, installer }) : null;
+      return { ok: false, error: 'activation failed', compensated: compensated?.ok === true };
+    }
+
+    const releaseDir = commitActivatedRelease({ stageDir: staged.stageDir, manifest, home, prior });
+    log('✓ durable release committed under Crew-owned state');
+    // Record the cohort sidecar for the committed release (exact pin when
+    // available, else the live cohort the activation just ran on).
+    if (candidateDsh) writeReleaseCohort({ releaseDir, dshVersion: candidateDsh, source: 'manifest-pin' });
+
     noteLauncherDivergence({ log, home });
     log('');
     log('Done.');
@@ -1111,7 +2583,7 @@ export function npxStatus({
   const zcode = st?.zcode?.installed ? 'installed' : 'not installed';
   const claude = st?.claude?.installed ? 'installed' : 'not installed';
   const official = officialWebIntegrationStatus({ home, releaseDir: pointer?.path });
-  const officialWeb = !official.enabled ? 'disabled' : official.healthy ? 'installed' : 'needs repair';
+  const officialWeb = !official.legacy_present ? 'not present (native 3210 control plane)' : official.healthy ? 'legacy full bridge present (deprecated; manual cleanup available)' : 'legacy full bridge record present but unhealthy (deprecated)';
   const startupState = installer.windowsStartupStatus?.({ home });
   const windowsStartup = !startupState?.supported ? 'not supported'
     : startupState.ready ? 'installed' : startupState.installed ? 'needs repair' : 'not installed';
@@ -1181,7 +2653,8 @@ export async function npxUninstall({
   else if (startup?.supported) log('✓ Windows login startup removed');
 
   const official = removeOfficialWebIntegration({ home, preserveIntent: !purge, remember: !purge });
-  if (!official.ok) fail(`official 3080 bridge removal failed (${official.code ?? 'unknown'})`);
+  if (!official.ok && official.code !== 'OFFICIAL_WEB_PROFILE_READ_ONLY') fail(`official 3080 bridge removal failed (${official.code ?? 'unknown'})`);
+  else if (official.code === 'OFFICIAL_WEB_PROFILE_READ_ONLY') log('- official 3080 bridge left untouched (official web profile is read-only)');
   else log(official.removed ? '✓ official 3080 bridge removed' : '- official 3080 bridge already absent');
 
   if (name) {
@@ -1222,8 +2695,8 @@ export const USAGE = `usage: dsh-crew <command> [--purge] [--candidate <path>]
 
 Commands:
   install     persist the candidate package into Crew-owned state and register it
-  integrate   show Crew inside the official 3080 UI; backend stays isolated on 3210
-  detach      remove only the official 3080 bridge; isolated 3210 mode remains available
+  integrate   disabled: the official web profile is read-only (legacy bridge retired)
+  detach      disabled: the official web profile is read-only (legacy bridge retired)
   status      read-only report of launcher/installed versions and integrations
   inspect     print the machine-readable extension capability/readiness contract
   jobs        machine-first job API: list|get|watch|cancel|submit
@@ -1460,13 +2933,8 @@ export async function npxProviders({
   let body = await response.json();
   if (!response.ok || body?.ok === false) throw new Error(body?.code ?? body?.error ?? 'Crew provider API unavailable');
   if (action === 'delete' && body?.restart_required === true && body?.result?.state === 'RESTART_PENDING') {
-    const restartResponse = await fetchImpl('http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart', {
-      method: 'POST',
-      headers: { accept: 'application/json', 'content-type': 'application/json' },
-      body: JSON.stringify({ confirm: true }),
-    });
-    const restartBody = await restartResponse.json();
-    if (!restartResponse.ok || restartBody?.ok !== true) throw new Error(restartBody?.code ?? restartBody?.error ?? 'Crew 3210 restart failed');
+    const restartBody = await requestCrewRuntimeRestart({ fetchImpl, reason: `providers ${action}` });
+    if (restartBody?.ok !== true) throw new Error(restartBody?.error ?? restartBody?.code ?? 'Crew 3210 restart failed');
     const verifyUrl = `${base}/${encodeURIComponent(id)}/verify-delete`;
     const verifyResponse = await fetchImpl(verifyUrl, {
       method: 'POST',
@@ -1478,11 +2946,8 @@ export async function npxProviders({
     body = { ...body, restart: restartBody, verification: verifyBody };
   }
   if (action === 'migrate' && body?.restart_required === true && body?.result?.state === 'RESTART_PENDING') {
-    const restartResponse = await fetchImpl('http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart', {
-      method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ confirm: true }),
-    });
-    const restartBody = await restartResponse.json();
-    if (!restartResponse.ok || restartBody?.ok !== true) throw new Error(restartBody?.code ?? restartBody?.error ?? 'Crew 3210 restart failed');
+    const restartBody = await requestCrewRuntimeRestart({ fetchImpl, reason: `providers ${action}` });
+    if (restartBody?.ok !== true) throw new Error(restartBody?.error ?? restartBody?.code ?? 'Crew 3210 restart failed');
     const verifyResponse = await fetchImpl(`${base}/${encodeURIComponent(id)}/verify-migration`, {
       method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ transaction_id: resolvedPlan, confirm: true }),
     });
@@ -1491,11 +2956,8 @@ export async function npxProviders({
     body = { ...body, restart: restartBody, verification: verifyBody };
   }
   if (action === 'rollback-migration' && body?.restart_required === true && body?.state === 'ROLLBACK_RESTART_PENDING') {
-    const restartResponse = await fetchImpl('http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart', {
-      method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ confirm: true }),
-    });
-    const restartBody = await restartResponse.json();
-    if (!restartResponse.ok || restartBody?.ok !== true) throw new Error(restartBody?.code ?? restartBody?.error ?? 'Crew 3210 restart failed');
+    const restartBody = await requestCrewRuntimeRestart({ fetchImpl, reason: `providers ${action}` });
+    if (restartBody?.ok !== true) throw new Error(restartBody?.error ?? restartBody?.code ?? 'Crew 3210 restart failed');
     const verifyResponse = await fetchImpl(`${base}/${encodeURIComponent(id)}/verify-rollback-migration`, {
       method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ transaction_id: resolvedPlan, confirm: true }),
     });
@@ -1504,13 +2966,8 @@ export async function npxProviders({
     body = { ...body, restart: restartBody, verification: verifyBody };
   }
   if (action === 'rollback' && body?.restart_required === true && body?.state === 'ROLLBACK_PENDING') {
-    const restartResponse = await fetchImpl('http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart', {
-      method: 'POST',
-      headers: { accept: 'application/json', 'content-type': 'application/json' },
-      body: JSON.stringify({ confirm: true }),
-    });
-    const restartBody = await restartResponse.json();
-    if (!restartResponse.ok || restartBody?.ok !== true) throw new Error(restartBody?.code ?? restartBody?.error ?? 'Crew 3210 restart failed');
+    const restartBody = await requestCrewRuntimeRestart({ fetchImpl, reason: `providers ${action}` });
+    if (restartBody?.ok !== true) throw new Error(restartBody?.error ?? restartBody?.code ?? 'Crew 3210 restart failed');
     const verifyUrl = `${base}/${encodeURIComponent(id)}/verify-rollback`;
     const verifyResponse = await fetchImpl(verifyUrl, {
       method: 'POST',