@ran-sh/dsh-crew 0.3.4 → 0.3.5

package/README.md

@@ -59,7 +59,14 @@ The globally installed package is only the launcher/manager. The actual Crew run
 
 > Known compatibility issue: transient `npx @ran-sh/dsh-crew …` execution is currently unreliable on some npm versions (npm/cli#9870: the npx cache bin is not put on the spawned command PATH). Until that upstream fix reaches your npm, use the global-launcher flow above instead.
 
-An update of the managed payload does not require a clone or rebuild; `dsh-crew update` resolves the newest permitted package from your configured npm registry (or an explicit `--candidate <path>` override), validates it under Crew-owned state, and switches only after validation succeeds. The global launcher intentionally does not self-replace; after an update the CLI prints the exact one-line command to refresh it.
+An update of the managed payload does not require a clone or rebuild. When the launcher and payload versions match, `dsh-crew update` resolves the newest permitted package from your configured npm registry (or an explicit `--candidate <path>` override). When the running launcher is newer, its validated package payload is used first to converge the older managed payload. Every path stages and validates before switching. If the managed payload is newer than the launcher, it is never downgraded and the CLI prints the exact launcher-refresh command.
+
+> Migration boundary for legacy `<= 0.3.3`: those immutable launchers cannot discover newer registry versions, so their old update behavior cannot be retroactively fixed. Refresh the launcher first, then converge the managed payload—no source checkout is required:
+>
+> ```bash
+> npm install -g @ran-sh/dsh-crew@latest
+> dsh-crew update
+> ```
 
 Developer / source setup (alternative path):
 

package/README.zh.md

@@ -59,7 +59,14 @@ dsh-crew uninstall        # 加 --purge 才会同时删除配置/备份
 
 > 已知兼容性问题：部分 npm 版本下，临时 `npx @ran-sh/dsh-crew …` 执行不可靠（npm/cli#9870：npx 缓存中的 bin 未加入子进程 PATH）。在该上游修复可用之前，请使用上面的全局启动器方式。
 
-托管载荷的更新无需克隆或构建：`dsh-crew update` 会从你配置的 npm registry 解析最新允许版本（或用 `--candidate <path>` 显式指定），在 Crew 自有状态下校验后再切换。全局启动器不会自我替换；更新完成后 CLI 会打印刷新启动器的准确命令。
+托管载荷的更新无需克隆或构建。启动器与载荷版本相同时，`dsh-crew update` 会从你配置的 npm registry 解析最新允许版本（或用 `--candidate <path>` 显式指定）；当前启动器较新时，会优先用这个已校验的启动器包收敛旧载荷。所有路径都会先暂存、校验，再切换。托管载荷较新时绝不降级，CLI 会打印刷新启动器的准确命令。
+
+> 旧版 `<= 0.3.3` 的迁移边界：这些不可变的旧启动器无法发现更新的 registry 版本，其旧 update 行为无法被追溯修复。受支持的迁移方式是先刷新启动器，再收敛托管载荷；无需源码检出：
+>
+> ```bash
+> npm install -g @ran-sh/dsh-crew@latest
+> dsh-crew update
+> ```
 
 开发者 / 源码安装（备选路径）：
 

package/package.json

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

package/src/install/npx-lifecycle.mjs

@@ -1,10 +1,11 @@
-// v0.3.3 npx-managed lifecycle: install / status / update / uninstall.
+// Packaged global-launcher lifecycle: install / status / update / uninstall.
 //
 // Public UX:
-//   npx @ran-sh/dsh-crew@latest install|status|update|uninstall
+//   npm install -g @ran-sh/dsh-crew@latest
+//   dsh-crew install|status|update|uninstall
 //
-// An npx invocation runs from a transient package-manager extraction/cache
-// path. This module therefore persists the already-built package payload into
+// A package-manager launcher may run from a replaceable global/cache path.
+// This module therefore persists the already-built package payload into
 // Crew-owned state BEFORE registering it with the Harness profile, so the
 // registration never depends on the cache, tarball, or temp extraction dir:
 //
@@ -587,16 +588,16 @@ export function extractPackageTarball(tgzPath, destDir, { runner = spawnSync } =
 
 /**
  * The globally installed launcher intentionally does not self-replace. When
- * it diverges from the freshly activated managed payload, say so explicitly
- * and give the exact refresh command instead of pretending both updated.
+ * the payload is newer, keep it authoritative and give the exact launcher
+ * refresh command. A newer launcher is handled by npxUpdate before this point.
  */
 function noteLauncherDivergence({ log, home = homedir() }) {
   const launcherVersion = readManifest(runningPackageRoot())?.version ?? null;
   let installedVersion = null;
   try { installedVersion = readCurrentPointer({ home }).version ?? null; } catch { installedVersion = null; }
-  if (launcherVersion && installedVersion && launcherVersion !== installedVersion) {
+  if (launcherVersion && installedVersion && compareVersions(installedVersion, launcherVersion) > 0) {
     log('');
-    log(`- note: the global launcher is still ${launcherVersion}; the managed Crew payload is now ${installedVersion}.`);
+    log(`- note: managed payload ${installedVersion} is newer than the global launcher ${launcherVersion}; the payload remains authoritative.`);
     log(`  Refresh the launcher when convenient: npm install -g ${UPDATE_PACKAGE_NAME}@${installedVersion}`);
   }
 }
@@ -705,10 +706,26 @@ export async function npxUpdate({
   runner = spawnSync,
 } = {}) {
   log('DSH Crew updater');
-  // Candidate resolution: explicit path/dir override > legacy sourceRoot >
-  // configured npm registry (@latest). Registry mode is a real update
-  // operation and never downgrades an already-newer managed payload.
-  const resolved = resolveUpdateCandidate({ candidate: candidate ?? sourceRoot, spec, home, log, runner });
+  // Candidate resolution: explicit path/dir override > a newer validated
+  // running launcher > configured npm registry (@latest). This makes the
+  // supported legacy bootstrap (`npm install -g ...@latest`, then `update`)
+  // independent of registry propagation after the launcher refresh.
+  const explicitCandidate = candidate ?? sourceRoot;
+  const initialHealth = currentInstallationHealth({ home });
+  const launcherRoot = runningPackageRoot();
+  const launcherManifest = readManifest(launcherRoot);
+  const launcherCanConverge = explicitCandidate === undefined
+    && initialHealth.pointer?.version
+    && launcherManifest?.name === UPDATE_PACKAGE_NAME
+    && launcherManifest?.version
+    && compareVersions(launcherManifest.version, initialHealth.pointer.version) > 0;
+  let resolved;
+  if (launcherCanConverge) {
+    log(`- newer launcher ${launcherManifest.version}; converging managed payload ${initialHealth.pointer.version} before registry resolution`);
+    resolved = { ok: true, sourceRoot: launcherRoot, version: launcherManifest.version, cleanup: null };
+  } else {
+    resolved = resolveUpdateCandidate({ candidate: explicitCandidate, spec, home, log, runner });
+  }
   if (!resolved.ok) {
     log(`✗ candidate resolution failed (${resolved.code})${resolved.detail ? `: ${resolved.detail}` : ''}`);
     return { ok: false, error: `candidate resolution failed (${resolved.code})` };
@@ -729,8 +746,9 @@ export async function npxUpdate({
       return { ok: true, idempotent: true, version: manifest.version, path: health.pointer.path };
     }
 
-    if (health.installed && health.healthy && compareVersions(manifest.version, health.pointer.version) < 0 && (candidate ?? sourceRoot) === undefined) {
-      log(`- registry latest (${manifest.version}) is not newer than the installed payload (${health.pointer.version}); nothing to update`);
+    if (health.installed && health.healthy && compareVersions(manifest.version, health.pointer.version) < 0) {
+      const source = explicitCandidate === undefined && !launcherCanConverge ? 'registry latest' : 'candidate';
+      log(`- ${source} (${manifest.version}) is not newer than the installed payload (${health.pointer.version}); nothing to update`);
       const activated = await activateRelease({ home, releaseDir: health.pointer.path, manifest: readManifest(health.pointer.path), log, installer });
       if (!activated) return { ok: false, error: 'activation failed' };
       return { ok: true, idempotent: true, version: health.pointer.version, path: health.pointer.path };
@@ -845,8 +863,14 @@ export function npxStatus({
   log(`DSH Crew launcher/candidate: ${candidateVersion ?? 'unknown'}`);
   log(`Installed DSH Crew payload: ${installedLine}`);
   if (candidateVersion && installedVersion && candidateVersion !== installedVersion) {
-    log(`- launcher and managed payload differ; the payload is authoritative for runtime behavior.`);
-    log(`  Refresh the launcher with: npm install -g ${UPDATE_PACKAGE_NAME}@${installedVersion}`);
+    const direction = compareVersions(candidateVersion, installedVersion);
+    if (direction > 0) {
+      log(`- launcher ${candidateVersion} is newer than the managed payload ${installedVersion}.`);
+      log('  Run: dsh-crew update');
+    } else {
+      log(`- managed payload ${installedVersion} is newer than the launcher ${candidateVersion}; the payload remains authoritative.`);
+      log(`  Refresh the launcher with: npm install -g ${UPDATE_PACKAGE_NAME}@${installedVersion}`);
+    }
   }
   log(`DSH plugin: ${dshPlugin} (dedicated dsh-crew profile; official web profile ignored)`);
   log(`Codex Desktop integration: ${codex}`);

package/src/runtime-identity.mjs

@@ -8,7 +8,7 @@
 // Keep this module pure and dependency-free so Hub, MCP and tests all use the
 // exact same compatibility rules.
 
-export const RUNTIME_VERSION = '0.3.4';
+export const RUNTIME_VERSION = '0.3.5';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([