@ran-sh/dsh-crew 2.2.0 → 2.2.2

package/src/install/npx-lifecycle.mjs

@@ -42,11 +42,15 @@ import { homedir } from 'node:os';
 import * as realInstaller from './install.mjs';
 import { samePayloadContent, capturePayloadContent } from './payload-content.mjs';
 import { crewDshHome, crewProfileDir, claudeIntegrationLine } from './install.mjs';
+import { integrationRoot } from './crew-paths.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, ensureCrewWebProfile, removeCrewPluginRegistration, migrateCrewDshRuntime, installDshInto, restoreRetainedRuntime, crewDshRuntimeRoot, payloadDshVersion, gcRetainedRuntimes, TARGET_DSH_VERSION } from '../dsh-cli-runtime.mjs';
+import { desktopAttach, desktopDetach, desktopStatus } from './desktop-profile.mjs';
+import { mirrorOfficialHarnessConfig, officialConfigMirrorStatus } from './harness-config-import.mjs';
 import {
   ensureOfficialWebIntegration,
   officialWebIntegrationStatus,
@@ -61,15 +65,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 +246,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 +457,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 +485,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 +688,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 +732,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 };
   }
@@ -1043,6 +973,28 @@ function defaultNpmInstaller(stageRoot, log) {
   return true;
 }
 
+// Exact-version specs only (the pinned-cohort shape). Ranges stay with normal
+// resolution: a range override would both fight the resolver and violate the
+// verbatim-spec rule npm applies when a direct dependency shares the name.
+const EXACT_SPEC_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+/**
+ * Lock every exact-pinned dependency to its own version across the whole
+ * staged tree. The npm fallback install has no flag channel (sanitized env,
+ * fixed args), so a drifting transitive peer — e.g. a projection package
+ * peer-requiring a newer cohort than the payload's pin — otherwise aborts
+ * staging with ERESOLVE. npm v11 rejects an override whose spec differs from
+ * the direct dependency, so each override reuses the dependency's exact spec
+ * verbatim.
+ */
+export function exactSpecOverrides(dependencies) {
+  const overrides = {};
+  for (const [name, spec] of Object.entries(dependencies ?? {})) {
+    if (typeof spec === 'string' && EXACT_SPEC_RE.test(spec)) overrides[name] = spec;
+  }
+  return Object.keys(overrides).length > 0 ? overrides : null;
+}
+
 // ---- payload staging ---------------------------------------------------------
 
 /**
@@ -1102,6 +1054,8 @@ export function stageCandidatePayload({
     ...(manifest.peerDependencies ?? {}),
     ...(manifest.dependencies ?? {}),
   };
+  const overrides = exactSpecOverrides(stagedManifest.dependencies);
+  if (overrides) stagedManifest.overrides = overrides;
   writeFileSync(join(stageDir, 'package.json'), JSON.stringify(stagedManifest, null, 2) + '\n');
 
   // Materialize dependencies: prefer replicating the exact bits the candidate
@@ -1304,15 +1258,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 +1349,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 +1377,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 +1429,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 +1484,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 +1885,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 +2217,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;
@@ -2269,7 +2244,7 @@ export function buildProductionMigration({ home, log = () => {}, stopOwned, star
   });
 }
 
-async function ensureRuntimeStep({ home, log, ensureRuntime, migrateRuntime, stopOwned, startOwned, verifyOwned, supervisorFactory = crewSupervisor }) {  const ensure = ensureRuntime ?? ((opts) => {
+async function ensureRuntimeStep({ home, log, ensureRuntime, migrateRuntime, ensureWebProfile, stopOwned, startOwned, verifyOwned, supervisorFactory = crewSupervisor }) {  const ensure = ensureRuntime ?? ((opts) => {
     const r = ensureCrewDshRuntime({ ...opts, env: sanitizedPackageManagerEnv() });
     if (!r.ok && r.stderrTail) {
       log(`  (runtime installer said: ${r.stderrTail})`);
@@ -2277,17 +2252,37 @@ async function ensureRuntimeStep({ home, log, ensureRuntime, migrateRuntime, sto
     if (!r.ok && r.code === 'DSH_RUNTIME_COHORT_MISMATCH') {
       return { ok: false, code: r.code, error: r.error, installed: r.installed, target: r.target, needsMigration: true };
     }
-    return r.ok ? { ok: true, version: r.cli?.version ?? null } : { ok: false, error: r.error ?? r.code ?? 'runtime bootstrap failed' };
+    return r.ok
+      ? { ok: true, version: r.cli?.version ?? null, cohortRepaired: r.cohortRepaired === true }
+      : { ok: false, error: r.error ?? r.code ?? 'runtime bootstrap failed' };
   });
   // Production migration wiring: ONE supervisor instance per migration,
   // reused by stop/start/verify/rollback so child identity stays coherent.
   // No legacy bridge involved. Missing callbacks fail closed inside
   // migrateCrewDshRuntime.
   const migrate = migrateRuntime ?? buildProductionMigration({ home, log, stopOwned, startOwned, verifyOwned, supervisorFactory });
+  // The runtime alone cannot boot a managed 3210/3080: the launcher preflight
+  // and the supervisor require <DSH_HOME>/profiles/web. Materialize it here —
+  // before any supervisor convergence, on every path that ends in "runtime
+  // ready" — so a fresh install cannot deadlock on a heartbeat that a
+  // profile-less service can never publish.
+  const convergeWebProfile = () => {
+    const profile = (ensureWebProfile ?? ensureCrewWebProfile)({ home });
+    if (!profile.ok) {
+      log(`✗ Crew web profile bootstrap failed (${profile.code ?? 'unknown error'})`);
+      return false;
+    }
+    if (profile.created) log(`✓ Crew web profile scaffold created (${profile.profileRoot})`);
+    return true;
+  };
   const r = await ensure({ home });
   if (r?.ok) {
     log(`✓ reusable Crew DSH runtime${r.version ? ` (@${r.version})` : ''}`);
-    return true;
+    // The install locks the whole family when the registry had published a newer
+    // prerelease than the pinned cohort; say so, because a silent repair is
+    // indistinguishable from a registry that never drifted.
+    if (r.cohortRepaired) log('  the DSH family had drifted from the pinned cohort; installed the pinned family instead');
+    return convergeWebProfile();
   }
   if (r?.needsMigration === true) {
     log(`- runtime cohort stale (${r.installed} -> ${r.target}); migrating via staged transaction`);
@@ -2297,7 +2292,7 @@ async function ensureRuntimeStep({ home, log, ensureRuntime, migrateRuntime, sto
       return false;
     }
     log(`✓ runtime cohort migrated (@${m.version})`);
-    return true;
+    return convergeWebProfile();
   }
   log(`✗ reusable Crew DSH runtime unavailable: ${r?.error ?? 'unknown error'}`);
   return false;
@@ -2676,9 +2671,18 @@ async function activateRelease({ home, releaseDir, manifest, log, installer, sup
   // 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 });
+  //
+  // The root is derived through the SAME integrationRoot() the readiness
+  // checks use, not blindly from registration.linkPath: write and validate
+  // must be one function of (home, releaseDir, name). In the healthy case the
+  // gate passes right after registration re-pointed the link, so this is
+  // still the link path; when the gate fails, both sides fall back to the
+  // release directory together instead of the writer using the link while the
+  // validator reports the release — the disagreement that made every clean
+  // install read back as "needs repair".
+  const integrationWriteRoot = integrationRoot({ home, root: releaseDir, name: manifest.name });
+
+  const codex = installer.installCodex({ home, root: integrationWriteRoot });
   if (codex.ok === false) {
     log(`✗ Codex Desktop integration failed: ${(codex.actions ?? []).join('; ')}`);
     return false;
@@ -2686,7 +2690,7 @@ async function activateRelease({ home, releaseDir, manifest, log, installer, sup
   log('✓ Codex Desktop integration');
 
   if (installer.installZCode) {
-    const zcode = installer.installZCode({ home, root: integrationRoot });
+    const zcode = installer.installZCode({ home, root: integrationWriteRoot });
     if (zcode.ok === false) {
       log(`✗ ZCode integration failed (${zcode.code ?? 'unknown'})`);
       return false;
@@ -2701,7 +2705,7 @@ async function activateRelease({ home, releaseDir, manifest, log, installer, sup
   }
   if (startup?.supported) log('✓ Windows login startup');
 
-  const claude = await installer.installClaudeCode({ home, root: integrationRoot });
+  const claude = await installer.installClaudeCode({ home, root: integrationWriteRoot });
   if (claude.ok === false) {
     log(claudeIntegrationLine(claude));
     return false;
@@ -2740,6 +2744,59 @@ export async function npxDetach({ home = homedir(), log = console.log } = {}) {
   return { ok: false, error: 'OFFICIAL_WEB_PROFILE_READ_ONLY' };
 }
 
+// Desktop-client integration. The official desktop app boots its Harness with the
+// app-exclusive `desktop` profile, so the Crew panel can only reach it through
+// that profile's own patch layer — the one official-home write Crew performs, and
+// only because an operator asked for it by name. It never runs during install,
+// update or supervision.
+export async function npxDesktop({ home = homedir(), args = [], dryRun = false, log = console.log } = {}) {
+  const action = args[0] ?? 'status';
+  if (!['attach', 'detach', 'status'].includes(action)) {
+    log(`✗ unknown desktop action: ${action}`);
+    return { ok: false, error: 'usage: dsh-crew desktop <attach|detach|status> [--dry-run]' };
+  }
+  if (action === 'status') {
+    const status = desktopStatus({ home });
+    if (!status.file_present) log(`- desktop patch layer: absent (${status.path})`);
+    else if (!status.attached) log(`- desktop patch layer: present, no Crew bridge (${status.path})`);
+    else if (status.current) log(`✓ desktop patch layer carries the current Crew bridge (revision ${status.bridge?.revision})`);
+    else log(`! desktop patch layer carries a stale Crew bridge (current revision ${status.bridge?.revision ?? 'unavailable'})`);
+    if (!status.bridge) log(`  (${status.bridge_error})`);
+    log(JSON.stringify(status, null, 2));
+    return { ok: true, status };
+  }
+  const result = action === 'attach'
+    ? desktopAttach({ home, dryRun, log })
+    : desktopDetach({ home, dryRun, log });
+  if (!result.ok) log(`✗ desktop ${action} failed: ${result.error ?? result.code}`);
+  return result;
+}
+
+// Bring the operator's user-level DSH configuration across from the official home
+// into Crew's home: the Crew hub then runs the same models, providers, policy and
+// MCP servers as the desktop app. Read-only on ~/.dsh, no secrets copied (provider
+// entries keep their apiKeyEnv references, and those variables are inherited).
+export async function npxConfig({ home = homedir(), args = [], dryRun = false, log = console.log } = {}) {
+  const action = args[0] ?? 'status';
+  if (!['import', 'status'].includes(action)) {
+    log(`✗ unknown config action: ${action}`);
+    return { ok: false, error: 'usage: dsh-crew config <import|status> [--dry-run]' };
+  }
+  if (action === 'status') {
+    const status = officialConfigMirrorStatus({ home });
+    for (const layer of [status.home_layer, status.profile_layer]) {
+      log(`- ${layer.label}: ${!layer.source_present ? `no official source (${layer.source})` : layer.mirrored ? 'mirrored' : 'not imported yet (run: dsh-crew config import)'}`);
+    }
+    log(JSON.stringify(status, null, 2));
+    return { ok: true, status };
+  }
+  const result = mirrorOfficialHarnessConfig({ home, dryRun, log });
+  if (result.ok && result.changed && !dryRun) {
+    log('  the Crew harness hot-watches its patch layers; the hub picks the imported configuration up without a restart');
+  }
+  return result;
+}
+
 export async function npxInstall({
   home = homedir(),
   log = console.log,
@@ -2818,15 +2875,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
@@ -3248,6 +3305,16 @@ export function npxStatus({
   }
   log(`DSH plugin: ${dshPlugin} (dedicated dsh-crew profile on 3210)`);
   log(`Official 3080 UI bridge: ${officialWeb}`);
+  // The desktop app carries its own bridge entry, which pins a revision: after a
+  // payload update that entry is stale until it is re-pointed, so say which of the
+  // three states the machine is in instead of leaving the panel silently old.
+  const desktop = desktopStatus({ home });
+  log(`Desktop app integration: ${
+    !desktop.file_present ? 'not attached (run: dsh-crew desktop attach)'
+      : desktop.attached && desktop.current ? 'attached'
+        : desktop.attached ? 'attached to a stale bridge revision (run: dsh-crew desktop attach)'
+          : 'not attached (run: dsh-crew desktop attach)'
+  }`);
   log(`Codex Desktop integration: ${codex}`);
   log(`ZCode integration: ${zcode}`);
   log(`Claude Code integration: ${claude}`);
@@ -3343,6 +3410,16 @@ Commands:
   install     persist the candidate package into Crew-owned state and register it
   integrate   disabled: the official web profile is read-only (legacy bridge retired)
   detach      disabled: the official web profile is read-only (legacy bridge retired)
+  desktop     the official DSH desktop app: attach|detach|status the Crew panel in its
+              own patch layer (~/.dsh/profiles/desktop/cordis.patch.yml, hot-watched
+              by the Harness). The only official-home write Crew performs, and only
+              when this command is run; attach is idempotent and follows the current
+              bridge revision, detach removes exactly the block it wrote
+  config      import|status the operator's user-level DSH configuration (models,
+              providers, policy, MCP servers) from the official home into Crew's own
+              home, so the Crew hub matches the desktop app. Read-only on ~/.dsh; no
+              secrets are copied (provider entries keep their apiKeyEnv references);
+              entries naming packages absent from Crew's runtime cohort are skipped
   status      read-only report of launcher/installed versions and integrations
   inspect     print the machine-readable extension capability/readiness contract
   jobs        machine-first job API: list|get|watch|cancel|submit
@@ -3364,6 +3441,7 @@ Options:
   --replacement-default <id>   with providers delete-plan: replacement Harness Default provider
   --confirm           with providers delete: confirm the destructive mutation
   --purge             with uninstall: also remove ~/.config/dsh-crew config/backups (destructive)
+  --dry-run           with desktop attach|detach: report the change without writing
   --help              show this help
 
 Primary install: npm install -g @ran-sh/dsh-crew   (then run: dsh-crew install)
@@ -3449,9 +3527,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 +3552,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,
@@ -3674,6 +3752,7 @@ function normalizeCommand(argv) {
   let expectedRevision;
   let replacementDefault;
   let confirm = false;
+  let dryRun = false;
   let purgeOrphanCredentials = false;
   for (let index = 0; index < flags.length; index += 1) {
     if (flags[index] === '--candidate') {
@@ -3713,16 +3792,18 @@ function normalizeCommand(argv) {
       replacementDefault = flags[index].slice('--replacement-default='.length); flags.splice(index, 1); index -= 1;
     } else if (flags[index] === '--confirm') {
       confirm = true; flags.splice(index, 1); index -= 1;
+    } else if (flags[index] === '--dry-run') {
+      dryRun = true; flags.splice(index, 1); index -= 1;
     } else if (flags[index] === '--purge-orphan-credentials') {
       purgeOrphanCredentials = true; flags.splice(index, 1); index -= 1;
     }
   }
-  const knownFlags = new Set(['--purge']);
+  const knownFlags = new Set(['--purge', '--dry-run']);
   const unknown = flags.filter((f) => f.startsWith('--') && !knownFlags.has(f));
   const args = flags.filter((f) => !f.startsWith('--'));
   if (!Number.isInteger(after) || after < 0) unknown.push('--after');
   if (!['compact', 'full'].includes(detail)) unknown.push('--detail');
-  return { command: argv[0], purge: flags.includes('--purge'), candidate, after, detail, request, planId, expectedRevision, replacementDefault, confirm, purgeOrphanCredentials, args, unknown };
+  return { command: argv[0], purge: flags.includes('--purge'), candidate, after, detail, request, planId, expectedRevision, replacementDefault, confirm, dryRun, purgeOrphanCredentials, args, unknown };
 }
 
 /**
@@ -3734,7 +3815,7 @@ export async function runNpxCli({
   error = console.error,
   commands = {},
 } = {}) {
-  const { command, purge, candidate, after, detail, request, planId, expectedRevision, replacementDefault, confirm, purgeOrphanCredentials, args, unknown } = normalizeCommand(argv);
+  const { command, purge, candidate, after, detail, request, planId, expectedRevision, replacementDefault, confirm, dryRun, purgeOrphanCredentials, args, unknown } = normalizeCommand(argv);
   if (command === '--help' || command === '-h' || command === 'help') {
     log(USAGE);
     return 0;
@@ -3743,7 +3824,7 @@ export async function runNpxCli({
     error(USAGE);
     return 1;
   }
-  if (unknown.length > 0 || !['install', 'integrate', 'detach', 'status', 'inspect', 'jobs', 'providers', 'credentials', 'releases', 'rollback', 'update', 'uninstall'].includes(command)) {
+  if (unknown.length > 0 || !['install', 'integrate', 'detach', 'desktop', 'config', 'status', 'inspect', 'jobs', 'providers', 'credentials', 'releases', 'rollback', 'update', 'uninstall'].includes(command)) {
     error(`unknown command: ${command ?? '<none>'}\n\n${USAGE}`);
     return 1;
   }
@@ -3752,6 +3833,8 @@ export async function runNpxCli({
       install: commands.install ?? npxInstall,
       integrate: commands.integrate ?? npxIntegrate,
       detach: commands.detach ?? npxDetach,
+      desktop: commands.desktop ?? npxDesktop,
+      config: commands.config ?? npxConfig,
       status: commands.status ?? npxStatus,
       inspect: commands.inspect ?? npxInspect,
       jobs: commands.jobs ?? npxJobs,
@@ -3765,6 +3848,8 @@ export async function runNpxCli({
     let result;
     if (command === 'uninstall') result = await actions.uninstall({ purge, log });
     else if (command === 'update') result = await actions.update({ candidate, log });
+    else if (command === 'desktop') result = await actions.desktop({ args, dryRun, log });
+    else if (command === 'config') result = await actions.config({ args, dryRun, log });
     else if (command === 'jobs') result = await actions.jobs({ args, after, detail, request, log });
     else if (command === 'providers') result = await actions.providers({ args, planId, expectedRevision, replacementDefault, confirm, purgeOrphanCredentials, log });
     else if (command === 'credentials') result = await actions.credentials({ args, planId, expectedRevision, confirm, log });

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) {