@ran-sh/dsh-crew 2.1.8 → 2.2.1

package/src/dsh-cli-runtime.mjs

@@ -35,7 +35,7 @@ import {
 // Re-exported so existing importers keep working while the cohort value now
 // lives in exactly one place (src/dsh-cohort.mjs).
 export { DSH_CLI_PACKAGE, TARGET_DSH_VERSION, TARGET_DSH_SPEC };
-export const CREW_DSH_RUNTIME_DIRNAME = 'runtime';
+const CREW_DSH_RUNTIME_DIRNAME = 'runtime';
 const CREW_PROFILE_DEFAULT_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'];
 const PROFILE_PATCH_TEMPLATE = '[]\n';
 const PROFILE_PNPM_WORKSPACE = 'packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\n';
@@ -73,11 +73,6 @@ export function crewDshRuntimeVersionDir({ home = homedir(), version = TARGET_DS
   return join(crewDshHome({ home }), `runtime-${version}`);
 }
 
-export function crewDshRuntimeEntry({ home = homedir(), platform = process.platform } = {}) {
-  const suffix = platform === 'win32' ? '.cmd' : '';
-  return join(crewDshRuntimeRoot({ home }), 'node_modules', '.bin', `dsh${suffix}`);
-}
-
 export function crewDshRuntimeModule({ home = homedir() } = {}) {
   return join(crewDshRuntimeRoot({ home }), 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js');
 }
@@ -736,35 +731,36 @@ export async function restoreRetainedRuntime({
 }
 
 // GC retained runtimes that no release pins. A retained cohort is needed only
-// while some managed release (current or retained) declares it as its exact
-// @deepseek-ai/dsh dependency. Best-effort; never throws.
-export function gcRetainedRuntimes({ home = homedir(), releases = [], log = () => {} } = {}) {
+// while some managed release resolves to it, so the caller passes the resolved
+// cohort versions (see resolveReleaseCohort: manifest pin, then the
+// release-cohort.json sidecar). Best-effort; never throws — a root that is
+// missing, unreadable or not a directory prunes nothing rather than failing
+// the update that just committed.
+export function gcRetainedRuntimes({ home = homedir(), cohorts = [], log = () => {} } = {}) {
   const root = retainedRuntimesRoot({ home });
-  if (!existsSync(root)) return [];
-  const needed = new Set();
-  for (const release of releases) {
-    const spec = payloadDshSpec(release);
-    if (spec && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(spec)) needed.add(spec);
-  }
+  const needed = new Set(cohorts.filter((spec) => typeof spec === 'string' && EXACT_COHORT_RE.test(spec)));
+  let names;
+  try { names = readdirSync(root); } catch { return []; }
   const removed = [];
-  for (const name of readdirSync(root)) {
+  for (const name of names) {
+    if (needed.has(name)) continue;
     const dir = join(root, name);
-    if (!needed.has(name)) {
-      try { rmSync(dir, { recursive: true, force: true }); removed.push(name); } catch { /* best effort */ }
-    }
+    try { rmSync(dir, { recursive: true, force: true }); removed.push(name); } catch { /* best effort */ }
   }
   return removed;
 }
 
+const EXACT_COHORT_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
 // Read the exact @deepseek-ai/dsh pin from a payload manifest (dependencies
 // first, then peerDependencies). Exact pins only: a range or absence yields
 // null so callers fail closed instead of guessing a cohort.
 function payloadDshSpec(manifest) {
   if (!manifest || typeof manifest !== 'object') return null;
   const direct = manifest.dependencies?.['@deepseek-ai/dsh'];
-  if (typeof direct === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(direct)) return direct;
+  if (typeof direct === 'string' && EXACT_COHORT_RE.test(direct)) return direct;
   const peer = manifest.peerDependencies?.['@deepseek-ai/dsh'];
-  if (typeof peer === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(peer)) return peer;
+  if (typeof peer === 'string' && EXACT_COHORT_RE.test(peer)) return peer;
   return null;
 }
 
@@ -964,7 +960,7 @@ function ensureDirectoryLink(linkPath, targetRoot) {
  * command. The profile manifest and one loader-visible directory link are the
  * only state changed; no dependency resolution or policy bypass is attempted.
  */
-export function ensurePluginRegistration({
+function ensurePluginRegistration({
   profileRoot,
   root,
   name,

package/src/extension-contract.mjs

@@ -4,7 +4,7 @@
 
 import { validateModelCallabilityV2 } from './model-callability-contract.mjs';
 
-export const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
+const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
 
 function row(matrix, id) {
   return Array.isArray(matrix?.rows) ? matrix.rows.find((entry) => entry?.id === id) : undefined;

package/src/failure-classification.mjs

@@ -3,16 +3,6 @@
 // Classification consumes structured status/codes/outcomes only. It never
 // parses raw exception text, provider responses, credentials, quotas or logs.
 
-export const FAILURE_CATEGORIES = Object.freeze([
-  'none',
-  'policy',
-  'compatibility',
-  'provider',
-  'runtime',
-  'verification',
-  'cancelled',
-]);
-
 export const FAILURE_REASON_CODES = Object.freeze({
   NONE: 'NONE',
   CANCELLED: 'CANCELLED',

package/src/history/cleanup-plan.mjs

@@ -31,14 +31,24 @@ function records(values) {
 /**
  * Pure preview only. No filesystem or project-path operations are performed.
  *
- * `scope` defaults to `crew`: a caller that forgets to narrow the range gets the
- * one range that cannot remove sessions the operator opened themselves. Widening
- * to `all` is always an explicit choice.
+ * `scope` defaults to `worktree` — Crew's own workspaces — because that is the
+ * range an operator is actually asking for when they clear a Crew project out,
+ * and it still cannot remove a session the operator opened themselves or one
+ * Crew ran in someone else's directory. Widening to `all` is always explicit.
+ *
+ * The value is named `worktree` for compatibility and now means workspaces: the
+ * pair a project's jobs run in, plus the per-job trees earlier releases left
+ * behind, so those stay cleanable instead of being stranded by the change.
  */
-export function planHistoryCleanup(snapshot, { operation = 'archive', scope = 'crew', before } = {}) {
+export function planHistoryCleanup(snapshot, { operation = 'archive', scope = 'worktree', before } = {}) {
   if (!['archive', 'delete'].includes(operation) || !['all', 'crew', 'worktree', 'before'].includes(scope)) throw new Error('HISTORY_INVALID_OPTIONS');
-  const cutoff = scope === 'before' ? instant(before) : null;
+  // `worktree` takes the same time window as `before`, but optionally: the panel
+  // supplies one when the operator picks a date, and its absence means "everything
+  // in these workspaces" rather than an error. A date that was supplied and is
+  // malformed still fails, so a typo cannot silently widen the range.
+  const cutoff = (scope === 'before' || scope === 'worktree') ? instant(before) : null;
   if (scope === 'before' && (typeof before !== 'string' || cutoff === null)) throw new Error('HISTORY_INVALID_CUTOFF');
+  if (scope === 'worktree' && before !== undefined && cutoff === null) throw new Error('HISTORY_INVALID_CUTOFF');
   const workspaces = records(snapshot.workspaces);
   const sessions = records(snapshot.sessions);
   const active = ids(snapshot.activeSessionIds);

package/src/hub/entry.mjs

@@ -68,7 +68,7 @@ export function recordAdaptiveJobOutcome(job, store = getProcessAdaptiveHealthSt
  * a chained promise preserves all legacy completion/waiter behavior and runs
  * this observer only after the Hub's own finalizer populated endedAt/status.
  */
-export function installAdaptiveHealthObserver() {
+function installAdaptiveHealthObserver() {
   if (WorkerRegistry.prototype[ADAPTIVE_OBSERVER_INSTALLED] === true) return false;
   const originalSpawn = WorkerRegistry.prototype.spawn;
   Object.defineProperty(WorkerRegistry.prototype, ADAPTIVE_OBSERVER_INSTALLED, {

package/src/hub/index.mjs

@@ -27,10 +27,11 @@ import { boundedMachineCodeFromError } from '../structured-error-code.mjs';
 import { createCanonicalJobEvent, projectWorkflowView } from '../job-contracts.mjs';
 import { getHubRuntimeIdentity } from '../runtime-identity.mjs';
 import { loadCiEvidence } from '../ci-evidence.mjs';
+import { ensureCrewWorkspace, releaseCrewWorkspace } from '../crew-workspaces.mjs';
 import { loadRoleProfiles, resolveRoleProfile, saveRoleProfiles } from '../role-profiles.mjs';
 import { addContextReferences, buildWorkspaceTask, isSafeBranchName, loadWorkspaceContexts, resolveWorkspaceContext, saveWorkspaceContexts } from '../workspace-context.mjs';
 import { buildExtensionContract } from '../extension-contract.mjs';
-import { cleanupIsolatedWorkspace, createIsolatedWorkspace, isCrewWorktreeName } from '../workspace-isolation.mjs';
+import { cleanupIsolatedWorkspace, isCrewWorktreeName } from '../workspace-isolation.mjs';
 import { jobDisplayName } from '../job-identity.mjs';
 import { assessWorkspaceReadiness } from '../workspace-readiness.mjs';
 import { buildConfigReadinessMatrix } from '../config-readiness.mjs';
@@ -118,7 +119,6 @@ export const QUICK_CONFIG_KEYS = Object.freeze([
 const LEGACY_TIER_MODELS = { flash: 'deepseek-v4-flash', pro: 'deepseek-v4-pro' };
 // Local copy (the hub must not import jobs.mjs, which pulls the DSH SDK into
 // the profile realm): a valid dispatch role set.
-const ROLES = { worker: true, reviewer: true };
 const CONFIG_DIR = join(homedir(), '.config', 'dsh-crew');
 const CREDENTIAL_PURGE_STATE_FILE = join(CONFIG_DIR, 'credential-purge-lifecycle.json');
 const RECOVERY_ACTION_PATTERN = /^[a-f0-9]{32}$/u;
@@ -861,26 +861,45 @@ export class WorkerRegistry {  constructor(ctx) {
     let executionCwd = cwd;
     let isolatedWorkspace = null;
     if ((requested_isolation === 'worktree' && jobRole === 'worker') || requested_isolation === 'readonly') {
-      const created = await createIsolatedWorkspace({ cwd, jobId: id, purpose: jobRole, baseRevision: workspace_branch });
+      // This project's stable worker/reviewer workspace, reset to the job's base
+      // revision and held for the job's duration, so the Harness groups these
+      // sessions into two entries instead of one per job.
+      const created = await ensureCrewWorkspace({ cwd, role: jobRole, baseRevision: workspace_branch });
       if (!created.ok) throw Object.assign(new Error(created.error ?? created.reason), { code: created.reason });
       executionCwd = created.worktreePath;
-      isolatedWorkspace = { worktreePath: created.worktreePath, repoRoot: created.repoRoot };
+      isolatedWorkspace = { worktreePath: created.worktreePath, repoRoot: created.repoRoot, stable: true, release: created.release };
     }
     // The Harness titles the session from the opening words of the prompt the
-    // agent receives, so the prompt opens with the job's Crew name: that makes the
-    // conversation, the worktree directory and the name an operator types the same
-    // string. An allocated worktree's name wins, so a collision suffix stays
-    // consistent between the two.
-    const jobName = isCrewWorktreeName(basename(executionCwd))
-      ? basename(executionCwd)
-      : jobDisplayName({ purpose: jobRole });
-    const workerPrompt = appendDeliveryInstructions(prependJobIdentity(task, { name: jobName, role: jobRole }), { tier: effTier, role: jobRole, isReview: delivery === 'review' || jobRole === 'reviewer' });
-
-    const sessionId = `session-${randomUUID()}`;
-    // Record provenance while it is still knowable: a session header carries no
-    // field naming who asked for the session, so a later Crew-scoped cleanup can
-    // only tell Crew's own work apart from the operator's by this ledger.
-    appendSessionOrigin({ sessionId, role: jobRole, jobId: id });
+    // agent receives, so the prompt opens with the job's Crew name. An allocated
+    // worktree's name wins, so a collision suffix stays consistent between the
+    // two. A stable workspace deliberately does *not* win: its directory name is
+    // shared by every job that uses it, so naming jobs after it would give them
+    // all one title and leave an operator unable to tell them apart. The
+    // workspace groups; the job name distinguishes.
+    let jobName;
+    let workerPrompt;
+    let sessionId;
+    try {
+      jobName = isCrewWorktreeName(basename(executionCwd))
+        ? basename(executionCwd)
+        : jobDisplayName({ purpose: jobRole });
+      workerPrompt = appendDeliveryInstructions(prependJobIdentity(task, { name: jobName, role: jobRole }), { tier: effTier, role: jobRole, isReview: delivery === 'review' || jobRole === 'reviewer' });
+
+      sessionId = `session-${randomUUID()}`;
+      // Record provenance while it is still knowable: a session header carries no
+      // field naming who asked for the session, so a later Crew-scoped cleanup can
+      // only tell Crew's own work apart from the operator's by this ledger.
+      appendSessionOrigin({ sessionId, role: jobRole, jobId: id });
+    } catch (error) {
+      // Everything below this point runs inside the job's own lifecycle, whose
+      // `finally` releases the workspace lock. A throw here happens before that
+      // job exists, so nothing would release a lock already taken — and it would
+      // then block the workspace until the age backstop, which is hours. The
+      // window is small (`appendSessionOrigin` writes a file) but the cost of
+      // missing it is a workspace no job can use.
+      releaseCrewWorkspace(isolatedWorkspace);
+      throw error;
+    }
     const job = {
       id, client_job_id: client_job_id ?? null, sessionId, role: jobRole, attempt, tier: effTier, provider: selection.provider, model: selection.model,
       selection_source: selection.source, selection_trace: selection.selection_trace ?? null,
@@ -1158,7 +1177,14 @@ export class WorkerRegistry {  constructor(ctx) {
           review: job.review,
           workspaceDiff: job.workspaceDiff,
         });
-        if (job.isolatedWorkspace) {
+        if (job.isolatedWorkspace?.stable === true) {
+          // A stable workspace is not disposed of — it is the directory the next
+          // job and every session it produced belong to. Only the lock is dropped.
+          const released = releaseCrewWorkspace(job.isolatedWorkspace);
+          job.workspace_retained = false;
+          const workspaceCleanupWarning = released ? null : 'workspace lock was not held at release';
+          job.cleanup_warning = [handleCleanupWarning, workspaceCleanupWarning].filter(Boolean).join('; ') || null;
+        } else if (job.isolatedWorkspace) {
           const cleanup = await cleanupIsolatedWorkspace(job.isolatedWorkspace).catch((error) => ({ ok: false, error: error?.message ?? String(error) }));
           job.workspace_retained = cleanup.ok !== true;
           const workspaceCleanupWarning = cleanup.ok === true ? null : cleanup.error ?? 'worktree cleanup failed';

package/src/i18n.mjs

@@ -13,7 +13,5 @@ export function setLang(lang) {
   return LANG;
 }
 
-export function getLang() { return LANG; }
-
 /** Pick the string for the active locale. Both branches are cheap literals. */
 export function tr(zh, en) { return LANG === 'zh' ? zh : en; }

package/src/install/crew-skill.mjs

@@ -42,7 +42,7 @@ export function crewSkillFiles({ home = homedir(), env = process.env } = {}) {
 }
 
 /** The skill template shipped in the payload. */
-export function crewSkillSource({ root }) {
+function crewSkillSource({ root }) {
   return join(root, 'skills', CREW_SKILL_NAME, 'SKILL.md');
 }
 

package/src/install/install-legacy.mjs

@@ -57,7 +57,7 @@ const REGEX_MAY_FOLLOW = new Set([
  * from the raw text, so a keyword inside a comment or a string is not a
  * declaration and a quote inside a regex is not a string.
  */
-export function tokenizeModuleSource(source) {
+function tokenizeModuleSource(source) {
   const tokens = [];
   const text = String(source ?? '');
   let i = 0;
@@ -748,7 +748,7 @@ export function pickClaudeCommand(candidates, { platform = process.platform } =
     ?? list[0];
 }
 
-export function resolveClaudeCommand({ platform = process.platform } = {}) {
+function resolveClaudeCommand({ platform = process.platform } = {}) {
   const probe = spawnSync(platform === 'win32' ? 'where' : 'which', ['claude'], {
     encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
   });
@@ -1019,7 +1019,7 @@ export async function installClaudeCode({ home = homedir(), statusline = false,
 }
 
 // Keep CLI transaction ordering testable without changing the operator's home.
-export async function refreshClaudePlugin({ home, root, actions = [], claudeCommand, runStep = runClaudeStep }) {
+async function refreshClaudePlugin({ home, root, actions = [], claudeCommand, runStep = runClaudeStep }) {
   // Each step runs to completion — including ending the whole process tree on a
   // timeout — before the next one starts, and the settle window is the widest any
   // step asks for. Two things this replaces: an `uninstall` left running past its

package/src/install/npx-lifecycle.mjs

@@ -44,9 +44,10 @@ import { samePayloadContent, capturePayloadContent } from './payload-content.mjs
 import { crewDshHome, crewProfileDir, claudeIntegrationLine } from './install.mjs';
 import { releaseClaimsState } from '../release-in-use.mjs';
 import { compareProcessToken, processStartToken } from '../process-identity.mjs';
+import { RELEASE_COHORT_FILENAME } from '../dsh-cohort.mjs';
 import { renameTree } from './tree-move.mjs';
 import { checkRuntimeAdvance, normalizeRuntimeState, runtimeStateMayHaveStarted } from './runtime-lifecycle.mjs';
-import { ensureCrewDshRuntime, ensureCrewPluginRegistration, removeCrewPluginRegistration, migrateCrewDshRuntime, installDshInto, restoreRetainedRuntime, crewDshRuntimeRoot, payloadDshVersion, TARGET_DSH_VERSION } from '../dsh-cli-runtime.mjs';
+import { ensureCrewDshRuntime, ensureCrewPluginRegistration, removeCrewPluginRegistration, migrateCrewDshRuntime, installDshInto, restoreRetainedRuntime, crewDshRuntimeRoot, payloadDshVersion, gcRetainedRuntimes, TARGET_DSH_VERSION } from '../dsh-cli-runtime.mjs';
 import {
   ensureOfficialWebIntegration,
   officialWebIntegrationStatus,
@@ -61,15 +62,15 @@ import {
 } from './windows-supervisor-adapter.mjs';
 
 export const CREW_APP_DIRNAME = 'app';
-export const RELEASES_DIRNAME = 'releases';
-export const CURRENT_POINTER_FILENAME = 'current.json';
-export const KEEP_RELEASES = 2;
+const RELEASES_DIRNAME = 'releases';
+const CURRENT_POINTER_FILENAME = 'current.json';
+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.-]+)?$/;
+const EXACT_DSH_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 
 export function npmCliInvocation(args, {
   platform = process.platform,
@@ -242,8 +243,8 @@ function writeCurrentPointer({ home, name, version, path }) {
   return pointer;
 }
 
-export const UPDATE_JOURNAL_FILENAME = 'update-journal.json';
-export const UPDATE_LOCK_FILENAME = 'update-in-progress.lock';
+const UPDATE_JOURNAL_FILENAME = 'update-journal.json';
+const UPDATE_LOCK_FILENAME = 'update-in-progress.lock';
 
 export function updateJournalFile({ home = homedir() } = {}) {
   return join(crewAppRoot({ home }), UPDATE_JOURNAL_FILENAME);
@@ -453,7 +454,7 @@ function writeUpdateJournal({ home, stage, prior = null, candidate = null, verif
 // 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 } = {}) {
+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);
@@ -481,82 +482,6 @@ function compensateActivationSync({ home, prior, manifest, log, installer }) {
   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
@@ -760,6 +685,7 @@ export async function reconcileUpdateJournal({ home = homedir(), log = () => {},
     }
     clearUpdateJournal({ home });
     gcOldReleases({ home, protect: journal.prior?.path ?? null });
+    gcRetainedCohorts({ home });
     log(`- recovered update journal at stage ${journal.stage}: candidate ${candidateIdent.version} already committed, finalized`);
     return { ok: true, reconciled: true, stage: journal.stage, committed: true };
   }
@@ -803,6 +729,7 @@ export async function reconcileUpdateJournal({ home = homedir(), log = () => {},
     writeCurrentPointer({ home, name: candidateIdent.name, version: candidateIdent.version, path: candidateDir });
     clearUpdateJournal({ home });
     gcOldReleases({ home, protect: journal.prior?.path ?? null });
+    gcRetainedCohorts({ home });
     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 };
   }
@@ -1304,15 +1231,48 @@ export function commitActivatedRelease({ stageDir, manifest, home, prior = null
   writeCurrentPointer({ home, name: manifest.name, version: manifest.version, path: stageDir });
   clearUpdateJournal({ home });
   gcOldReleases({ home, protect: prior?.path ?? null });
+  gcRetainedCohorts({ home });
   return stageDir;
 }
 
-function commitStagedRelease({ stageDir, manifest, home, prior = null }) {
-  return commitActivatedRelease({ stageDir, manifest, home, prior });
-}
-
 const STALE_INCOMPLETE_MS = 24 * 60 * 60 * 1000;
 
+// A retained runtime cohort is needed only while some surviving release
+// resolves to it, so this runs next to release pruning at the commit points
+// that call gcOldReleases: dropping a release is what stops its cohort being
+// pinned. Resolution goes through resolveReleaseCohort, the same chain every
+// other caller uses (manifest pin, then the release-cohort.json sidecar), so a
+// release that names its cohort only in the sidecar keeps its runtime.
+//
+// Fail closed: the cohort set is trusted only when EVERY directory under
+// releases/ resolved, because "nothing pins it" and "could not tell" must not
+// prune the same way. Pruning is best-effort on top of that — it must never
+// turn an update that already committed its pointer into a failed one.
+//
+// performCoordinatedCohortUpdate commits without gcOldReleases and is
+// deliberately not covered here either; its prior tree is still the rollback
+// target at that point.
+function gcRetainedCohorts({ home }) {
+  try {
+    const releasesDir = crewReleasesDir({ home });
+    if (!existsSync(releasesDir)) return [];
+    const entries = readdirSync(releasesDir, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+    const cohorts = [];
+    for (const entry of entries) {
+      const resolved = resolveReleaseCohort({ releaseDir: join(releasesDir, entry.name) });
+      if (!resolved.ok) {
+        process.emitWarning(`dsh-crew: release "${entry.name}" does not resolve to an exact cohort (${resolved.code ?? 'unknown'}); skipping retained-runtime pruning this pass`);
+        return [];
+      }
+      cohorts.push(resolved.dshVersion);
+    }
+    return gcRetainedRuntimes({ home, cohorts });
+  } catch (error) {
+    process.emitWarning(`dsh-crew: retained-runtime pruning skipped: ${error?.message ?? error}`);
+    return [];
+  }
+}
+
 function gcOldReleases({ home, keep = KEEP_RELEASES, protect = null }) {
   const pointer = readCurrentPointer({ home });
   const releasesDir = crewReleasesDir({ home });
@@ -1362,7 +1322,7 @@ function gcOldReleases({ home, keep = KEEP_RELEASES, protect = null }) {
   return removed;
 }
 
-export function listManagedReleases({ home = homedir() } = {}) {
+function listManagedReleases({ home = homedir() } = {}) {
   const pointer = readCurrentPointer({ home });
   const root = crewReleasesDir({ home });
   if (!existsSync(root)) return [];
@@ -1390,7 +1350,7 @@ export function listManagedReleases({ home = homedir() } = {}) {
 // 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({
+async function requestCrewRuntimeRestart({
   reason = null,
   fetchImpl = globalThis.fetch,
   pollIntervalMs = 1_000,
@@ -1442,18 +1402,6 @@ export async function requestCrewRuntimeRestart({
   }
 }
 
-async function restartOwnedRuntime(fetchImpl = globalThis.fetch) {
-  return requestCrewRuntimeRestart({ fetchImpl, reason: 'lifecycle restart' });
-}
-
-async function verifyRuntimeVersion(version, fetchImpl = globalThis.fetch) {
-  const response = await fetchImpl('http://127.0.0.1:3210/_dsh/dsh-crew/runtime', { headers: { accept: 'application/json' } });
-  const body = await response.json();
-  return response.ok && body?.ok === true && body.runtime_version === version
-    ? { ok: true, runtime_version: body.runtime_version }
-    : { 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
@@ -1509,7 +1457,7 @@ export async function verifyCrewRuntimeIdentity(version, fetchImpl = globalThis.
 // 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 } = {}) {
+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' } });
@@ -1910,10 +1858,10 @@ async function finishLifecycleAfterUpdateLock({
 // 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');
+const cohortFile = (releaseDir) => join(releaseDir, RELEASE_COHORT_FILENAME);
 
 // Exact DSH cohort version helper: delegates to the module-level regex.
-export function isExactDshVersion(value) {
+function isExactDshVersion(value) {
   return typeof value === 'string' && EXACT_DSH_VERSION_RE.test(value);
 }
 
@@ -2242,7 +2190,7 @@ function registrationHealthy({ home, name, releaseDir }) {
  * config resolution. Package-manager children must see the user's real
  * environment, not our execution context.
  */
-export function sanitizedPackageManagerEnv(baseEnv = process.env) {
+function sanitizedPackageManagerEnv(baseEnv = process.env) {
   const env = {};
   for (const [key, value] of Object.entries(baseEnv)) {
     if (/^npm_(config_|lifecycle|package_|execpath$|node_execpath$)/i.test(key)) continue;
@@ -2818,15 +2766,15 @@ async function npxInstallInner({ home, log, sourceRoot, installer, ensureRuntime
   return { ok: true, version: manifest.version, path: releaseDir };
 }
 
-export const UPDATE_PACKAGE_NAME = '@ran-sh/dsh-crew';
-export const UPDATE_DEFAULT_SPEC = `${UPDATE_PACKAGE_NAME}@latest`;
+const UPDATE_PACKAGE_NAME = '@ran-sh/dsh-crew';
+const UPDATE_DEFAULT_SPEC = `${UPDATE_PACKAGE_NAME}@latest`;
 
 /**
  * Extract a packed npm tarball with the platform `tar` binary (bsdtar ships
  * with Windows 10+, macOS, and Linux) into destDir; npm tarballs always root
  * at `package/`.
  */
-export function extractPackageTarball(tgzPath, destDir, { runner = spawnSync } = {}) {
+function extractPackageTarball(tgzPath, destDir, { runner = spawnSync } = {}) {
   mkdirSync(destDir, { recursive: true });
   // GNU tar interprets a `C:\...` argument as a remote rsh host ("Cannot
   // connect to C:"), so anchor the invocation inside destDir and pass the
@@ -3449,9 +3397,9 @@ const CREDENTIAL_CAPABILITY_REQUIREMENTS = Object.freeze({
   'purge-plan': Object.freeze(['credential-reference-inventory-v1', 'credential-purge-v1']),
   purge: Object.freeze(['credential-reference-inventory-v1', 'credential-purge-v1']),
 });
-export const PRODUCTION_HUB_URL = 'http://127.0.0.1:3210';
+const PRODUCTION_HUB_URL = 'http://127.0.0.1:3210';
 
-export async function assertProductionHub({ hubUrl, requiredCapabilities = [], purpose = 'command', fetchImpl = globalThis.fetch } = {}) {
+async function assertProductionHub({ hubUrl, requiredCapabilities = [], purpose = 'command', fetchImpl = globalThis.fetch } = {}) {
   if (hubUrl !== PRODUCTION_HUB_URL) throw new Error(`${purpose} requires the isolated 3210 Crew Hub`);
   const response = await fetchImpl(`${hubUrl}${CREW_ROUTE_BASE}/runtime`, { headers: { accept: 'application/json' } });
   let body;
@@ -3474,7 +3422,7 @@ export async function assertProductionHub({ hubUrl, requiredCapabilities = [], p
  * surface before sending a provider request. This prevents a same-port stale
  * Hub from turning a later 404 into an ambiguous destructive failure.
  */
-export async function assertProviderHubCapabilities({ hubUrl, action, fetchImpl = globalThis.fetch } = {}) {
+async function assertProviderHubCapabilities({ hubUrl, action, fetchImpl = globalThis.fetch } = {}) {
   return assertProductionHub({
     hubUrl,
     requiredCapabilities: PROVIDER_CAPABILITY_REQUIREMENTS[action] ?? PROVIDER_CAPABILITY_REQUIREMENTS.list,

package/src/install/official-web.mjs

@@ -10,7 +10,7 @@ import { join } from 'node:path';
 export const OFFICIAL_BRIDGE_PACKAGE = '@ran-sh/dsh-crew-web-bridge';
 const STATE_FILENAME = 'official-web.json';
 
-export function officialWebProfileDir({ home = homedir() } = {}) {
+function officialWebProfileDir({ home = homedir() } = {}) {
   return join(home, '.dsh', 'profiles', 'web');
 }
 

package/src/install/windows-startup.mjs

@@ -12,11 +12,11 @@ import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { installOfficialFrontendAssets, officialFrontendAssetsReady } from './official-frontend-assets.mjs';
 
-export const WINDOWS_STARTUP_FILENAME = 'DSH Crew.vbs';
-export const WINDOWS_LAUNCHER_FILENAME = 'start-dsh-crew.cmd';
-export const WINDOWS_HELPER_FILENAME = 'start-dsh-crew.ps1';
-export const WINDOWS_CONTROL_FILENAME = 'supervisor-control.ps1';
-export const WINDOWS_SUPERVISOR_ASSET_MANIFEST = 'supervisor-assets.json';
+const WINDOWS_STARTUP_FILENAME = 'DSH Crew.vbs';
+const WINDOWS_LAUNCHER_FILENAME = 'start-dsh-crew.cmd';
+const WINDOWS_HELPER_FILENAME = 'start-dsh-crew.ps1';
+const WINDOWS_CONTROL_FILENAME = 'supervisor-control.ps1';
+const WINDOWS_SUPERVISOR_ASSET_MANIFEST = 'supervisor-assets.json';
 
 function defaultStartupDir({ home, env }) {
   if (home === homedir() && env.APPDATA) {