@ran-sh/dsh-crew 1.10.1 → 1.10.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {

package/src/dsh-cli-runtime.mjs

@@ -11,6 +11,7 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   realpathSync,
   renameSync,
@@ -528,9 +529,21 @@ async function rollbackRuntimeSwap({ liveRoot, prevRoot, stopOwned, startOwned,
       return recovery;
     }
   }
-  try { rmSync(liveRoot, { recursive: true, force: true }); } catch {}
   try {
-    if (existsSync(prevRoot)) { rename(prevRoot, liveRoot); recovery.restore = true; }
+    rmSync(liveRoot, { recursive: true, force: true });
+  } catch (error) {
+    // A failed removal must stop the recovery. Swallowing it left the window
+    // open: the restore was attempted over whatever remained, and
+    // `startOwned()` ran regardless — so a tree that could not be removed was
+    // then asked to start again, which on Windows is exactly the case where
+    // live handles blocked the removal.
+    recovery.removeError = String(error?.message ?? error);
+    recovery.ok = false;
+    return recovery;
+  }
+  try {
+    if (!existsSync(prevRoot)) recovery.restoreError = `previous runtime is missing at ${prevRoot}`;
+    else { rename(prevRoot, liveRoot); recovery.restore = true; }
   } catch (error) {
     recovery.restoreError = String(error?.message ?? error);
   }
@@ -538,6 +551,14 @@ async function rollbackRuntimeSwap({ liveRoot, prevRoot, stopOwned, startOwned,
     recovery.ok = recovery.restore === true;
     return recovery;
   }
+  // Restart only on positive proof that the prior runtime is the tree now at the
+  // live root. Starting without it would run the failed candidate again, or
+  // nothing at all, and report it as a recovery.
+  if (recovery.restore !== true || !existsSync(liveRoot)) {
+    recovery.restartSkipped = 'the previous runtime was not restored';
+    recovery.ok = false;
+    return recovery;
+  }
   try {
     const restarted = await startOwned();
     recovery.restart = restarted?.ok === true;
@@ -551,6 +572,8 @@ async function rollbackRuntimeSwap({ liveRoot, prevRoot, stopOwned, startOwned,
 
 // ---- retained runtime cohorts -------------------------------------------------
 
+const DISPLACED_RUNTIME_PREFIX = 'runtime-displaced-';
+
 function retainedRuntimesRoot({ home }) {
   return join(crewDshHome({ home }), RETAINED_RUNTIMES_DIRNAME);
 }
@@ -572,12 +595,22 @@ function runtimeTreeVersion(root, read = readFileSync) {
 // Best-effort retention of the swapped-out prior runtime tree. Never throws
 // and never fails the caller: retention is an optimization for offline
 // rollback, not a correctness requirement of the migration itself.
-function retainPriorRuntime({ home, prevRoot, rename = renameSync }) {
+/**
+ * Retain a parked runtime tree under the version it ships.
+ *
+ * `removeUnreadable` exists for one caller: the rollback rotation, where the
+ * parked tree is the ONLY copy of the cohort just displaced. There, failing to
+ * read its version is not a reason to delete it — that would destroy the very
+ * copy the rotation exists to keep — so it stays parked and is found later by
+ * `findRetainedRuntime`. The forward migration path keeps the default, where an
+ * unreadable tree really is junk.
+ */
+function retainPriorRuntime({ home, prevRoot, rename = renameSync, removeUnreadable = true }) {
   try {
     if (!existsSync(prevRoot)) return { ok: true, retained: false };
     const version = runtimeTreeVersion(prevRoot);
     if (!version) {
-      // No version to key retention on; the tree is unreadable junk.
+      if (!removeUnreadable) return { ok: false, retained: false, prevRoot, error: 'parked cohort version unreadable; left in place' };
       try { rmSync(prevRoot, { recursive: true, force: true }); } catch {}
       return { ok: true, retained: false, reason: 'prior tree version unreadable; removed' };
     }
@@ -601,9 +634,24 @@ function retainPriorRuntime({ home, prevRoot, rename = renameSync }) {
 export function findRetainedRuntime({ home = homedir(), version, exists = existsSync, read = readFileSync } = {}) {
   if (typeof version !== 'string' || version.length === 0) return null;
   const dir = retainedRuntimeDir({ home, version });
-  if (!exists(dir)) return null;
-  if (runtimeTreeVersion(dir, read) !== version) return null;
-  return dir;
+  if (exists(dir) && runtimeTreeVersion(dir, read) === version) return dir;
+  // A rotation whose retain step failed leaves the displaced cohort parked in the
+  // harness home. It is a complete, valid copy of that cohort, so it is found
+  // here rather than being written off: otherwise a later offline rollback to
+  // that version reports RETAINED_MISSING while the tree sits on disk.
+  return findDisplacedRuntime({ home, version, exists, read });
+}
+
+function findDisplacedRuntime({ home, version, exists = existsSync, read = readFileSync }) {
+  let names;
+  try { names = readdirSync(crewDshHome({ home })); } catch { return null; }
+  for (const name of names) {
+    if (!name.startsWith(DISPLACED_RUNTIME_PREFIX)) continue;
+    const dir = join(crewDshHome({ home }), name);
+    if (!exists(dir)) continue;
+    if (runtimeTreeVersion(dir, read) === version) return dir;
+  }
+  return null;
 }
 
 // Offline cohort restore for cross-cohort rollback: move the retained tree
@@ -642,14 +690,34 @@ export async function restoreRetainedRuntime({
   if (!stop.ok) {
     return { ok: false, code: stop.code ?? 'DSH_RUNTIME_STOP_FAILED', error: stop.error ?? 'could not stop owned 3210' };
   }
+  // Park the displaced cohort instead of deleting it. Deleting it was what made a
+  // second rollback impossible: after B→A the B tree was gone, so a later A→B
+  // found no retained B. Retention has to rotate, like the forward path does.
+  const parked = join(crewDshHome({ home }), `${DISPLACED_RUNTIME_PREFIX}${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`);
+  let parkedLive = false;
+  try {
+    if (existsSync(liveRoot)) { rename(liveRoot, parked); parkedLive = true; }
+  } catch (error) {
+    return { ok: false, code: 'DSH_RUNTIME_PARK_FAILED', error: String(error?.message ?? error) };
+  }
   try {
-    if (existsSync(liveRoot)) rmSync(liveRoot, { recursive: true, force: true });
     rename(retained, liveRoot);
   } catch (error) {
-    // Restore the pre-existing live tree is impossible (it was replaced only
-    // on success above); report and let the caller reconcile.
+    // Put the displaced tree back: leaving the live root empty because a rename
+    // failed would take a working runtime down for nothing.
+    try { if (parkedLive && !existsSync(liveRoot)) rename(parked, liveRoot); } catch { /* reported below */ }
     return { ok: false, code: 'DSH_RUNTIME_RESTORE_SWAP_FAILED', error: String(error?.message ?? error) };
   }
+  // The cohort just displaced becomes the retained one, so the version this
+  // restore moved away from can still be rolled back to. This parked tree is the
+  // only copy of that cohort, so an unreadable version keeps it rather than
+  // deleting it, and a failure is surfaced instead of passing as a clean restore.
+  const rotated = parkedLive
+    ? retainPriorRuntime({ home, prevRoot: parked, rename, removeUnreadable: false })
+    : { ok: true, retained: false };
+  if (parkedLive && rotated.ok === false) {
+    log(`! could not retain the displaced runtime cohort; it remains at ${parked}: ${rotated.error ?? ''}`);
+  }
   if (prepareOnly) {
     log(`- runtime tree prepared offline from retained tree (@${version}); process not started`);
     return { ok: true, version, liveRoot, prepared: true };

package/src/install/npx-lifecycle.mjs

@@ -161,21 +161,62 @@ export function readCurrentPointerState({ home = homedir() } = {}) {
     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 };
+  // The pointer names the release that is live, and recovery acts on it. A path
+  // outside the managed releases directory is a corrupt or tampered pointer, not
+  // a release, so it fails closed exactly like the other malformed cases — and
+  // the canonical value is what the caller gets, so every later use acts on the
+  // path that was checked.
+  const canonical = managedReleasePath({ home, value: raw.path });
+  if (canonical === null) {
+    return { status: 'malformed', file, code: 'POINTER_PATH_OUTSIDE_RELEASES' };
+  }
+  return { status: 'valid', file, pointer: { ...raw, path: canonical } };
+}
+
+/**
+ * Resolve a path that a journal, the pointer, or recovery is about to act on, and
+ * refuse it unless it is inside the Crew-owned releases directory.
+ *
+ * An absolute path is not enough. Recovery recursively deletes the journal's
+ * candidate stage directory and moves the pointer's release, so a syntactically
+ * valid but corrupt or tampered journal naming any absolute path would grant
+ * delete authority over it — including the official `~/.dsh` tree this plugin is
+ * required never to touch. Containment is therefore checked before any read,
+ * write, delete or activation, and a path that fails it is treated exactly like
+ * a malformed journal: nothing is touched and the state is retained.
+ */
+export function managedReleasePath({ home = homedir(), value } = {}) {
+  if (typeof value !== 'string' || value.length === 0 || !isAbsolute(value)) return null;
+  const releases = realpathOr(resolve(crewReleasesDir({ home })));
+  const candidate = realpathOr(resolve(value));
+  // Resolve both sides before comparing: `..` segments and symlinks must not be
+  // able to leave the managed directory after the check.
+  const relative = relativeTo(releases, candidate);
+  if (relative === null || relative === '' || relative.startsWith('..') || isAbsolute(relative)) return null;
+  return candidate;
+}
+
+function realpathOr(path) {
+  try { return realpathSync(path); } catch { return path; }
+}
+
+/** `path` expressed relative to `from`, or null when they are on different roots. */
+function relativeTo(from, path) {
+  return relative(from, path);
 }
 
-function validJournalRelease(value) {
+function validJournalRelease({ home, 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);
+    && managedReleasePath({ home, value: value.path }) !== null;
 }
 
-function validJournalCandidate(value) {
+function validJournalCandidate({ home, 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);
+    && managedReleasePath({ home, value: value.stageDir }) !== null;
 }
 
 function writeFileAtomic(file, content) {
@@ -359,13 +400,23 @@ function readUpdateJournal({ home = homedir() } = {}) {
     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)) {
+  // incomplete prior) must fail closed, never enter recovery. The paths are
+  // checked for containment too, because recovery deletes and moves them, and
+  // they are replaced with the canonical value that was checked so that every
+  // later use acts on the path that was validated rather than the string that
+  // happened to be written.
+  const canonicalCandidate = managedReleasePath({ home, value: raw.candidate?.stageDir });
+  if (!validJournalCandidate({ home, value: raw.candidate }) || canonicalCandidate === null) {
     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' };
+  if (raw.prior !== null && raw.prior !== undefined) {
+    const canonicalPrior = managedReleasePath({ home, value: raw.prior?.path });
+    if (!validJournalRelease({ home, value: raw.prior }) || canonicalPrior === null) {
+      return { malformed: true, file, code: 'JOURNAL_PRIOR_SCHEMA_INVALID' };
+    }
+    raw = { ...raw, prior: { ...raw.prior, path: canonicalPrior } };
   }
+  raw = { ...raw, candidate: { ...raw.candidate, stageDir: canonicalCandidate } };
   return raw;
 }
 
@@ -536,12 +587,90 @@ function validateJournalRuntimeSegment({ home, rt }) {
   return { ok: true };
 }
 
+/**
+ * The runtime window a coordinated update left open, or null.
+ *
+ * The durable maintenance session is the source of truth, not the journal. The
+ * supervisor persists the session as part of stopping 3210, so it exists from the
+ * instant the stop lands — whereas the journal is written a few instructions
+ * later. Reading the session closes that gap: whatever stop happened, recovery
+ * finds it. The journal's copy is kept as a fallback for a session that has since
+ * been cleared.
+ */
+async function openMaintenanceWindow({ home, journal }) {
+  const appRoot = join(home, '.config', 'dsh-crew');
+  try {
+    const { readMaintenanceSession } = await import('../supervisor/restart-request.mjs');
+    const durable = readMaintenanceSession(appRoot);
+    if (durable.ok && durable.state === 'present') {
+      return { lease: durable.session.lease, runtime_id: durable.session.runtime_id, source: 'session' };
+    }
+    // A session that exists but cannot be read is not "no session": recovery
+    // must not clear the journal and report success while a stopped runtime it
+    // cannot account for is sitting there.
+    if (!durable.ok && durable.state === 'malformed') {
+      return { malformed: true, error: durable.code ?? 'MAINTENANCE_SESSION_MALFORMED' };
+    }
+  } catch { /* fall through to the journal's copy */ }
+  const recorded = journal?.runtime?.maintenance ?? null;
+  if (recorded?.lease && recorded?.runtime_id) return { lease: recorded.lease, runtime_id: recorded.runtime_id, source: 'journal' };
+  return null;
+}
+
+/**
+ * Restart a runtime that a coordinated update left deliberately stopped.
+ *
+ * The window is the lease and runtime id the supervisor issued when it stopped
+ * 3210. Passing them back resumes that exact stopped window rather than asking
+ * for a new stop, which is the only thing the durable maintenance session
+ * accepts — a second independent stop is refused while the first is in force.
+ */
+async function closeMaintenanceWindow({ home, window, supervisorFactory = crewSupervisor, log = () => {} }) {
+  try {
+    const supervisor = supervisorFactory({ home });
+    const started = await supervisor.startOwnedBackend({ lease: window.lease, runtimeId: window.runtime_id });
+    if (started?.ok !== true) {
+      return { ok: false, code: started?.code ?? 'MAINTENANCE_START_FAILED', error: started?.error ?? null };
+    }
+    log('- recovery restarted the runtime that the interrupted update had stopped');
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, code: 'MAINTENANCE_START_FAILED', error: String(error?.message ?? error) };
+  }
+}
+
+/**
+ * Attempt to stop the owned runtime, and report whether the stop actually
+ * happened.
+ *
+ * Only a successful stop counts. `MAINTENANCE_IDENTITY_UNAVAILABLE` means the
+ * supervisor could not obtain the live runtime's identity over its HTTP endpoint,
+ * which is equally consistent with a live runtime whose request timed out — so it
+ * is not evidence that nothing is running and must never be read as any. An
+ * earlier revision of this helper did read it that way and would have replaced a
+ * live runtime's tree, which is the exact hazard it exists to prevent.
+ */
+async function ensureRuntimeStopped({ home, supervisorFactory = crewSupervisor, log = () => {} }) {
+  try {
+    const supervisor = supervisorFactory({ home });
+    if (typeof supervisor?.stopOwnedBackend !== 'function') return { ok: false, code: 'MAINTENANCE_UNAVAILABLE' };
+    const stopped = await supervisor.stopOwnedBackend();
+    if (stopped?.ok === true) {
+      log('- recovery stopped the runtime before replacing its tree');
+      return { ok: true, stopped: true };
+    }
+    return { ok: false, code: stopped?.code ?? 'MAINTENANCE_STOP_FAILED', error: stopped?.error ?? null };
+  } catch (error) {
+    return { ok: false, code: 'MAINTENANCE_STOP_FAILED', error: String(error?.message ?? error) };
+  }
+}
+
 // 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 } = {}) {
+export async function reconcileUpdateJournal({ home = homedir(), log = () => {}, installer = realInstaller, supervisorFactory = crewSupervisor } = {}) {
   const journal = readUpdateJournal({ home });
   if (!journal) return { ok: true, reconciled: false };
   if (journal.malformed) {
@@ -554,7 +683,9 @@ export function reconcileUpdateJournal({ home = homedir(), log = () => {}, insta
     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;
+  // Act on the canonical path that was validated, not the raw string that was
+  // written: the delete below is only as safe as the path it is handed.
+  const candidateDir = managedReleasePath({ home, value: journal.candidate?.stageDir ?? null });
   const candidateManifest = candidateDir && existsSync(candidateDir) ? readManifest(candidateDir) : null;
 
   // A coordinated-update journal MUST carry a runtime segment; recovery may
@@ -633,6 +764,36 @@ export function reconcileUpdateJournal({ home = homedir(), log = () => {}, insta
     return { ok: false, code: 'JOURNAL_POINTER_DIVERGED', stage: journal.stage, error: `pointer references unexpected release ${pointer?.path ?? 'unknown'}; refusing recovery` };
   }
 
+  // A verified coordinated journal means the candidate runtime was started and
+  // its identity checked, and the pointer write happens after that — so this
+  // state means the pointer write was lost and the candidate is what is running.
+  // Completing the commit is the recovery; rolling back would swap the tree and
+  // the payload out from under a live process. This runs only after the
+  // divergence check above, so "the pointer has not moved" means it still names
+  // the prior release or nothing at all — a third release has already failed
+  // closed, and its release identity can never be overwritten by a stale journal.
+  if (journal.stage === 'coordinated-update' && journal.verified === true && !pointerMatchesCandidate) {
+    if (!candidateIdent?.name || !candidateIdent?.version || !candidateDir) {
+      return { ok: false, code: 'JOURNAL_CANDIDATE_INVALID', stage: journal.stage };
+    }
+    const rt = journal.runtime ?? null;
+    if (rt?.candidateVersion && rt?.liveRoot && readRuntimeTreeVersionSync(rt.liveRoot) !== rt.candidateVersion) {
+      return { ok: false, code: 'JOURNAL_COORDINATED_RUNTIME_MISMATCH', stage: journal.stage, error: 'a verified coordinated journal expects the candidate runtime to be live; refusing to commit' };
+    }
+    // The same check the committed path applies, so a roll-forward cannot install
+    // a pointer to a payload that would have been rejected had it arrived the
+    // ordinary way.
+    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('; ') };
+    }
+    writeCurrentPointer({ home, name: candidateIdent.name, version: candidateIdent.version, path: candidateDir });
+    clearUpdateJournal({ home });
+    gcOldReleases({ home, protect: journal.prior?.path ?? null });
+    log(`- recovered update journal at stage ${journal.stage}: candidate ${candidateIdent.version} was verified and started, so the commit was completed`);
+    return { ok: true, reconciled: true, stage: journal.stage, committed: true };
+  }
+
   // 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
@@ -650,6 +811,29 @@ export function reconcileUpdateJournal({ home = homedir(), log = () => {}, insta
     if (rt?.priorVersion && rt?.liveRoot) {
       const liveVersion = readRuntimeTreeVersionSync(rt.liveRoot);
       if (liveVersion !== rt.priorVersion) {
+        // The tree has to be replaced, and replacing it under a running process is
+        // the damage. The journal says whether a start can have happened: it is
+        // set to `starting` before the candidate is started and to `verified`
+        // after it checks out, so anything else means no runtime was ever started
+        // from the candidate cohort and the swap is safe.
+        //
+        // `starting` cannot be resolved from the journal alone — the candidate may
+        // be live and unverified. It must not be a dead end either, so recovery
+        // stops the runtime and rolls back on a stop that actually happened, or on
+        // a durable STOPPED session that already proves one did. Anything less is
+        // not proof: a runtime that cannot be shown to be stopped keeps its tree.
+        if (rt.state === 'starting') {
+          const window = await openMaintenanceWindow({ home, journal });
+          if (window?.malformed) {
+            return { ok: false, code: 'JOURNAL_MAINTENANCE_SESSION_MALFORMED', stage: journal.stage, error: `${window.error}; refusing to replace a runtime tree while a stopped runtime cannot be accounted for` };
+          }
+          if (!window) {
+            const stopped = await ensureRuntimeStopped({ home, supervisorFactory, log });
+            if (!stopped.ok) {
+              return { ok: false, code: 'JOURNAL_RUNTIME_STOP_UNPROVEN', stage: journal.stage, error: `an interrupted update may have started the candidate runtime and could not be shown to be stopped (${stopped.code ?? 'unknown'}), so its tree was left alone; stop the owned runtime through the Crew supervisor, then re-run` };
+            }
+          }
+        }
         // 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;
@@ -694,29 +878,46 @@ export function reconcileUpdateJournal({ home = homedir(), log = () => {}, insta
       // and may be removed. (rollback candidates are retained releases.)
       try { rmSync(candidateDir, { recursive: true, force: true }); } catch {}
     }
+    // The prior release is back in place, so a runtime the interrupted update
+    // stopped has to be started again — otherwise recovery reports success and
+    // leaves 3210 down. The journal is kept until the window is closed, so a
+    // crash between the two retries with the same recorded window instead of
+    // losing track of a stopped runtime.
+    const openWindow = journal.stage === 'coordinated-update'
+      ? await openMaintenanceWindow({ home, journal })
+      : null;
+    if (openWindow?.malformed) {
+      return { ok: false, code: 'JOURNAL_MAINTENANCE_SESSION_MALFORMED', stage: journal.stage, error: `${openWindow.error}; refusing to report recovery while a stopped runtime cannot be accounted for` };
+    }
+    if (openWindow) {
+      const closed = await closeMaintenanceWindow({ home, window: openWindow, supervisorFactory, log });
+      if (!closed.ok) {
+        return { ok: false, code: 'JOURNAL_MAINTENANCE_WINDOW_OPEN', stage: journal.stage, error: `the runtime was left stopped and could not be restarted (${closed.code ?? 'unknown'}); journal retained` };
+      }
+    }
     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 };
+  // First-install pre-commit: no prior release exists, and there is nothing this
+  // branch can undo that it can prove is its own. Removing the loader link would
+  // break every host integration that names it; removing the integration records
+  // would mean deleting files in the operator's home on the strength of a
+  // filename, because those uninstallers take only `home` and cannot tell this
+  // failed install's records from ones the operator wrote, or from a manual
+  // installation that predates Crew. So nothing is changed: the candidate stays,
+  // the link still resolves to it, whatever names the link still resolves, and
+  // the journal is retained so an operator decides. A recovery that cannot
+  // attribute what it would delete does not delete it.
+  return {
+    ok: false,
+    code: 'JOURNAL_FIRST_INSTALL_NEEDS_OPERATOR',
+    stage: journal.stage,
+    candidate: candidateDir,
+    journal: updateJournalFile({ home }),
+    error: `a first install did not complete; nothing was changed, because Crew cannot prove which host records are its own. To finish by hand: repoint or remove the Crew profile registration first (its loader link is ${join(crewProfileDir({ home }), 'node_modules', ...'@ran-sh/dsh-crew'.split('/'))}), remove the host integrations that name it, then delete ${updateJournalFile({ home })} and ${candidateDir ?? 'the staged candidate'}`,
+  };
 }
 
 // ---- dependency tree materialization ----------------------------------------
@@ -1797,7 +1998,7 @@ async function npxRollbackInner({ home, version: targetVersion, log, installer,
   // 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 });
+  const pending = await reconcileUpdateJournal({ home, log, supervisorFactory });
   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' };
@@ -2125,7 +2326,7 @@ export async function performCoordinatedCohortUpdate({
   // 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({
+  const journalBase = {
     home,
     stage: 'coordinated-update',
     prior: { name: prior.name, version: prior.version, path: prior.path, dshVersion: priorDshVersion },
@@ -2138,7 +2339,8 @@ export async function performCoordinatedCohortUpdate({
       candidateVersion: candidateDshVersion,
       retainedRoot,
     },
-  });
+  };
+  writeUpdateJournal(journalBase);
 
   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 };
@@ -2193,6 +2395,16 @@ export async function performCoordinatedCohortUpdate({
       clearUpdateJournal({ home });
       return { ok: false, code: stopped.code ?? 'COORDINATED_STOP_FAILED', error: stopped.error ?? 'could not stop owned 3210' };
     }
+    // The runtime is now deliberately stopped inside a durable maintenance
+    // window, and everything from here on mutates its tree. Record the window in
+    // the journal before that mutation: a crash in the next few steps used to
+    // leave 3210 down with no record of how to resume it, and the surviving
+    // session then refused the next ordinary stop, so the machine could not
+    // recover on its own. `startOwnedBackend` accepts this exact lease and
+    // runtime id, which is what recovery needs to close the window.
+    if (stopped.lease && stopped.runtime_id) {
+      writeUpdateJournal({ ...journalBase, runtime: { ...journalBase.runtime, maintenance: { lease: stopped.lease, runtime_id: stopped.runtime_id } } });
+    }
     let liveMoved = false;
     try {
       // Move live runtime aside, retaining its tree for offline rollback.
@@ -2229,6 +2441,12 @@ export async function performCoordinatedCohortUpdate({
       const comp = await compensate();
       return finalizeCompensationFailure({ home, code: null, error: 'candidate activation failed', comp });
     }
+    // Record that a start may be about to happen BEFORE it happens. Recovery
+    // decides whether the runtime tree can be replaced by reading this, and a
+    // crash between the start and the verification would otherwise look exactly
+    // like "the candidate was never started" — which is how a rollback ends up
+    // swapping the tree out from under a running process.
+    writeUpdateJournal({ ...journalBase, runtime: { ...journalBase.runtime, state: 'starting' } });
     const started = await startFn();
     if (started?.ok !== true) {
       const comp = await compensate();
@@ -2254,9 +2472,12 @@ export async function performCoordinatedCohortUpdate({
       }
     }
 
-    // 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.
+    // Mark the journal verified BEFORE the pointer write, which makes a crash
+    // between the two distinguishable — but note what "verified" means here: the
+    // candidate runtime has already been started and its identity checked, so the
+    // candidate is what is running. A pointer still naming prior with a verified
+    // journal therefore means the pointer write was lost, and recovery completes
+    // the commit rather than rolling the tree out from under the live process.
     const marked = markJournalVerified({
       home,
       stage: 'coordinated-update',
@@ -2360,7 +2581,16 @@ async function activateRelease({ home, releaseDir, manifest, log, installer, sup
   }
   log(`✓ Harness plugin registered (dedicated dsh-crew profile → ${releaseDir})`);
 
-  const codex = installer.installCodex({ home, root: releaseDir });
+  // The host integrations are pointed at the profile's loader link, not at the
+  // release directory. That link is what registration just re-pointed, so it
+  // always resolves to whichever release is live: an upgrade re-points it and
+  // the integrations keep working, and removing an old release can no longer
+  // leave four configurations naming a directory that is gone. Writing the
+  // release path directly is what made crash recovery unable to delete a
+  // candidate without breaking Codex, ZCode and Claude Code.
+  const integrationRoot = registration.linkPath ?? releaseDir;
+
+  const codex = installer.installCodex({ home, root: integrationRoot });
   if (codex.ok === false) {
     log(`✗ Codex Desktop integration failed: ${(codex.actions ?? []).join('; ')}`);
     return false;
@@ -2368,7 +2598,7 @@ async function activateRelease({ home, releaseDir, manifest, log, installer, sup
   log('✓ Codex Desktop integration');
 
   if (installer.installZCode) {
-    const zcode = installer.installZCode({ home, root: releaseDir });
+    const zcode = installer.installZCode({ home, root: integrationRoot });
     if (zcode.ok === false) {
       log(`✗ ZCode integration failed (${zcode.code ?? 'unknown'})`);
       return false;
@@ -2383,7 +2613,7 @@ async function activateRelease({ home, releaseDir, manifest, log, installer, sup
   }
   if (startup?.supported) log('✓ Windows login startup');
 
-  const claude = await installer.installClaudeCode({ home, root: releaseDir });
+  const claude = await installer.installClaudeCode({ home, root: integrationRoot });
   if (claude.ok === false) {
     log(`✗ Claude Code integration failed`);
     return false;
@@ -2449,7 +2679,7 @@ export async function npxInstall({
 }
 
 async function npxInstallInner({ home, log, sourceRoot, installer, ensureRuntime, npmInstaller }) {
-  const reconciled = reconcileUpdateJournal({ home, log });
+  const reconciled = await 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);
@@ -2666,7 +2896,7 @@ export async function npxUpdate({
 }
 
 async function npxUpdateInner({ home, log, sourceRoot, candidate, spec, installer, ensureRuntime, npmInstaller, runner = spawnSync }) {
-  const journalRecovery = reconcileUpdateJournal({ home, log });
+  const journalRecovery = await 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

package/src/install/payload-content.mjs

@@ -74,12 +74,23 @@ export function capturePayloadContent(root, suppliedManifest) {
   } catch { return null; }
 }
 
-/** This digest covers first-party shipped files, not dependency tamper attestation. */
+/**
+ * This digest covers first-party shipped files, not dependency tamper attestation.
+ *
+ * The permission bits are part of it: the copy below writes each file with the
+ * mode captured from the source, so a payload whose `0644` became `0755` with
+ * identical bytes is not the same payload — it is the case where an intended
+ * permission repair would otherwise be skipped as already done.
+ */
 export function payloadContentDigest(root) {
   const snapshot = capturePayloadContent(root);
   if (!snapshot) return null;
-  const hashes = [...snapshot.files].map(([name, bytes]) => [name, createHash('sha256').update(bytes).digest('hex')]);
-  return createHash('sha256').update(JSON.stringify(hashes.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))).digest('hex');
+  const entries = [...snapshot.files].map(([name, bytes]) => [
+    name,
+    snapshot.modes.get(name) ?? null,
+    createHash('sha256').update(bytes).digest('hex'),
+  ]);
+  return createHash('sha256').update(JSON.stringify(entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))).digest('hex');
 }
 
 export function samePayloadContent(sourceRoot, installedRoot) {

package/src/runtime-identity.mjs

@@ -36,7 +36,7 @@ export {
 // included in the identity contract.
 const RUNTIME_ID = randomUUID();
 
-export const RUNTIME_VERSION = '1.10.1';
+export const RUNTIME_VERSION = '1.10.3';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([