@ran-sh/dsh-crew 1.10.2 → 1.10.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "1.10.2",
+  "version": "1.10.4",
   "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.2",
+  "version": "1.10.4",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {

package/src/install/npx-lifecycle.mjs

@@ -587,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) {
@@ -686,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
@@ -703,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;
@@ -747,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 ----------------------------------------
@@ -1850,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' };
@@ -2178,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 },
@@ -2191,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 };
@@ -2246,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.
@@ -2282,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();
@@ -2307,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',
@@ -2413,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;
@@ -2421,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;
@@ -2436,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;
@@ -2502,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);
@@ -2719,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/runtime-identity.mjs

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

package/src/workspace-isolation.mjs

@@ -25,6 +25,8 @@ export const NOT_GIT_REPOSITORY = 'NOT_GIT_REPOSITORY';
 export const GIT_NOT_FOUND = 'GIT_NOT_FOUND';
 export const GIT_TIMEOUT = 'GIT_TIMEOUT';
 export const GIT_ERROR = 'GIT_ERROR';
+/** A valid repository whose HEAD does not resolve because nothing is committed. */
+export const REPOSITORY_HAS_NO_COMMITS = 'REPOSITORY_HAS_NO_COMMITS';
 export const WORKTREE_LOCKED = 'WORKTREE_LOCKED';
 export const WORKTREE_RESERVE_FAILED = 'WORKTREE_RESERVE_FAILED';
 export const CANDIDATE_CAPTURE_FAILED = 'CANDIDATE_CAPTURE_FAILED';
@@ -269,7 +271,22 @@ export async function inspectRepository({ cwd, git, runner } = {}) {
     runGit(run, ['status', '--porcelain', '-uall'], { cwd }),
   ]);
   if (!root.ok) return { ok: false, reason: root.reason, error: root.error };
-  if (!head.ok) return { ok: false, reason: head.reason, error: head.error };
+  if (!head.ok) {
+    // A repository with no commits yet is a valid repository whose HEAD simply
+    // does not resolve, and it cannot be told apart from a broken one by that
+    // command alone. It is worth telling apart: `git init && <ask Crew to do
+    // something>` is how a new project starts, and reporting it as a generic git
+    // error leaves the operator with nothing to act on.
+    const verified = await runGit(run, ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd });
+    if (verified.ok === false && (verified.code === 1 || verified.code === 128) && !verified.stdout?.trim()) {
+      return {
+        ok: false,
+        reason: REPOSITORY_HAS_NO_COMMITS,
+        error: 'this repository has no commits yet, so there is no revision for an isolated job to start from; make an initial commit, or set execution.isolation to "shared" to run in the working tree',
+      };
+    }
+    return { ok: false, reason: head.reason, error: head.error };
+  }
   return {
     ok: true,
     repoRoot: resolve(root.stdout.trim()),