@ran-sh/dsh-crew 0.5.6 → 1.0.0

package/src/install/npx-lifecycle.mjs

@@ -31,6 +31,7 @@ import {
   readFileSync,
   realpathSync,
   rmSync,
+  copyFileSync,
   writeFileSync,
 } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -48,24 +49,25 @@ import {
 
 export const CREW_APP_DIRNAME = 'app';
 export const RELEASES_DIRNAME = 'releases';
-export const CURRENT_POINTER_FILENAME = 'current.json';
+export const CURRENT_POINTER_FILENAME = 'current.json';
 export const KEEP_RELEASES = 2;
 export const INCOMPLETE_MARKER = '.dsh-crew-incomplete';
-
-export function npmCliInvocation(args, {
-  platform = process.platform,
-  environment = process.env,
-} = {}) {
-  if (platform !== 'win32') return { command: 'npm', args: [...args] };
-  const unsafe = args.find((arg) => /[\0\r\n"%!^&|<>]/.test(String(arg)));
-  if (unsafe !== undefined) throw new Error(`unsafe npm argument: ${unsafe}`);
-  const commandLine = ['npm.cmd', ...args.map((arg) => `"${String(arg)}"`)].join(' ');
-  return {
-    command: environment.ComSpec || environment.COMSPEC || 'cmd.exe',
-    args: ['/d', '/s', '/c', commandLine],
-    windowsVerbatimArguments: true,
-  };
-}
+const CREW_ROUTE_BASE = '/_dsh/dsh-crew';
+
+export function npmCliInvocation(args, {
+  platform = process.platform,
+  environment = process.env,
+} = {}) {
+  if (platform !== 'win32') return { command: 'npm', args: [...args] };
+  const unsafe = args.find((arg) => /[\0\r\n"%!^&|<>]/.test(String(arg)));
+  if (unsafe !== undefined) throw new Error(`unsafe npm argument: ${unsafe}`);
+  const commandLine = ['npm.cmd', ...args.map((arg) => `"${String(arg)}"`)].join(' ');
+  return {
+    command: environment.ComSpec || environment.COMSPEC || 'cmd.exe',
+    args: ['/d', '/s', '/c', commandLine],
+    windowsVerbatimArguments: true,
+  };
+}
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -232,18 +234,18 @@ export function copyProductionDependencyTree({
   return { copied, missing, missingOptional };
 }
 
-function defaultNpmInstaller(stageRoot, log) {
-  const npmArgs = [
-    'install', '--prefix', stageRoot,
-    '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund',
-    '--no-package-lock', '--loglevel=error',
-  ];
-  const invocation = npmCliInvocation(npmArgs);
-  const result = spawnSync(invocation.command, invocation.args, {
-    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 600_000,
-    windowsHide: true, windowsVerbatimArguments: invocation.windowsVerbatimArguments,
-    env: sanitizedPackageManagerEnv(),
-  });
+function defaultNpmInstaller(stageRoot, log) {
+  const npmArgs = [
+    'install', '--prefix', stageRoot,
+    '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund',
+    '--no-package-lock', '--loglevel=error',
+  ];
+  const invocation = npmCliInvocation(npmArgs);
+  const result = spawnSync(invocation.command, invocation.args, {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 600_000,
+    windowsHide: true, windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    env: sanitizedPackageManagerEnv(),
+  });
   if (result.status !== 0) {
     log(`- npm fallback install failed (${result.status}): ${(result.stderr || result.stdout || '').trim().slice(-300)}`);
     return false;
@@ -476,7 +478,7 @@ function commitStagedRelease({ stageDir, manifest, home }) {
 
 const STALE_INCOMPLETE_MS = 24 * 60 * 60 * 1000;
 
-function gcOldReleases({ home, keep = KEEP_RELEASES }) {
+function gcOldReleases({ home, keep = KEEP_RELEASES }) {
   const pointer = readCurrentPointer({ home });
   const releasesDir = crewReleasesDir({ home });
   if (!existsSync(releasesDir)) return;
@@ -505,9 +507,123 @@ function gcOldReleases({ home, keep = KEEP_RELEASES }) {
     try { rmSync(victim, { recursive: true, force: true }); removed.push(victim); } catch { /* best effort */ }
   }
   return removed;
-}
-
-function registrationLinkPath({ home, name }) {
+}
+
+export function listManagedReleases({ home = homedir() } = {}) {
+  const pointer = readCurrentPointer({ home });
+  const root = crewReleasesDir({ home });
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const path = join(root, entry.name);
+      const manifest = readManifest(path);
+      if (!manifest?.name || !manifest?.version) return null;
+      const validation = validateInstalledPayload(path, { expectedName: manifest.name, expectedVersion: manifest.version });
+      return {
+        name: manifest.name,
+        version: manifest.version,
+        path,
+        current: pointer?.path === path,
+        healthy: validation.ok,
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => compareVersions(b.version, a.version) || b.path.localeCompare(a.path));
+}
+
+async function restartOwnedRuntime(fetchImpl = globalThis.fetch) {
+  const response = await fetchImpl('http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart', {
+    method: 'POST',
+    headers: { accept: 'application/json', 'content-type': 'application/json' },
+    body: JSON.stringify({ confirm: true }),
+  });
+  const body = await response.json();
+  return response.ok && body?.ok === true ? body : { ok: false, code: body?.code ?? 'CREW_3210_RESTART_FAILED' };
+}
+
+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' };
+}
+
+export async function npxReleases({ home = homedir(), log = console.log } = {}) {
+  const releases = listManagedReleases({ home });
+  log(JSON.stringify(releases, null, 2));
+  return { ok: true, releases };
+}
+
+export async function npxRollback({
+  home = homedir(),
+  version,
+  log = console.log,
+  installer = realInstaller,
+  ensureRuntime,
+  validatePayload = validateInstalledPayload,
+  activate,
+  restart = () => restartOwnedRuntime(),
+  verifyRuntime = (targetVersion) => verifyRuntimeVersion(targetVersion),
+} = {}) {
+  const targetVersion = typeof version === 'string' ? version.trim() : '';
+  if (!targetVersion) return { ok: false, error: 'rollback requires a target version' };
+  const current = readCurrentPointer({ home });
+  if (!current?.path || !existsSync(current.path)) return { ok: false, error: 'no active Crew payload to roll back' };
+  const target = listManagedReleases({ home }).find((release) => release.version === targetVersion);
+  if (!target) return { ok: false, error: `retained release ${targetVersion} was not found` };
+  if (target.path === current.path) return { ok: true, idempotent: true, version: target.version, path: target.path };
+  const targetManifest = readManifest(target.path);
+  const validation = validatePayload(target.path, { expectedName: targetManifest?.name, expectedVersion: targetManifest?.version });
+  if (!validation.ok) return { ok: false, error: 'target release failed payload validation' };
+  const previousManifest = readManifest(current.path);
+  const activateReleaseFn = activate ?? (({ releaseDir, manifest }) => activateRelease({ home, releaseDir, manifest, log, installer, ensureRuntime }));
+  const switchPointer = (release) => writeCurrentPointer({ home, name: release.name, version: release.version, path: release.path });
+  try {
+    switchPointer(target);
+    if (!await activateReleaseFn({ releaseDir: target.path, manifest: targetManifest })) throw new Error('target release activation failed');
+    const restarted = await restart(target.version);
+    if (restarted?.ok === false) throw Object.assign(new Error('target runtime restart failed'), { code: restarted.code });
+    const runtime = await verifyRuntime(target.version);
+    if (runtime?.ok !== true) throw Object.assign(new Error('target runtime verification failed'), { code: runtime?.code ?? 'RUNTIME_VERSION_MISMATCH' });
+    log(`✓ rolled back Crew payload to ${target.version}`);
+    return { ok: true, rolled_back: true, version: target.version, path: target.path, restart: restarted, runtime };
+  } catch (error) {
+    const prior = { name: current.name, version: current.version, path: current.path };
+    let recovery;
+    try {
+      switchPointer(prior);
+      if (!previousManifest) throw Object.assign(new Error('previous release manifest unavailable'), { stage: 'activation' });
+      const activated = await activateReleaseFn({ releaseDir: prior.path, manifest: previousManifest });
+      if (activated !== true) throw Object.assign(new Error('previous release activation failed'), { stage: 'activation' });
+      const restarted = await restart(prior.version);
+      if (restarted?.ok !== true) throw Object.assign(new Error('previous runtime restart failed'), { stage: 'restart' });
+      const runtime = await verifyRuntime(prior.version);
+      if (runtime?.ok !== true) throw Object.assign(new Error('previous runtime verification failed'), { stage: 'verification' });
+      const restoredPointer = readCurrentPointer({ home });
+      if (restoredPointer?.path !== prior.path || restoredPointer.version !== prior.version) {
+        throw Object.assign(new Error('previous release pointer was not restored'), { stage: 'pointer' });
+      }
+      recovery = { ok: true, version: prior.version, path: prior.path };
+    } catch (recoveryError) {
+      recovery = {
+        ok: false,
+        code: 'RELEASE_ROLLBACK_RECOVERY_FAILED',
+        stage: ['activation', 'restart', 'verification', 'pointer'].includes(recoveryError?.stage) ? recoveryError.stage : 'unknown',
+      };
+    }
+    return {
+      ok: false,
+      error: error?.message ?? 'release rollback failed',
+      code: error?.code ?? 'RELEASE_ROLLBACK_FAILED',
+      restored: recovery.ok === true,
+      recovery,
+    };
+  }
+}
+
+function registrationLinkPath({ home, name }) {
   return join(crewProfileDir({ home }), 'node_modules', ...name.split('/'));
 }
 
@@ -569,30 +685,30 @@ async function activateRelease({ home, releaseDir, manifest, log, installer }) {
   }
   log(`✓ Harness plugin registered (dedicated dsh-crew profile → ${releaseDir})`);
 
-  const codex = installer.installCodex({ home, root: releaseDir });
+  const codex = installer.installCodex({ home, root: releaseDir });
   if (codex.ok === false) {
     log(`✗ Codex Desktop integration failed: ${(codex.actions ?? []).join('; ')}`);
     return false;
   }
-  log('✓ Codex Desktop integration');
-
-  if (installer.installZCode) {
-    const zcode = installer.installZCode({ home, root: releaseDir });
-    if (zcode.ok === false) {
-      log(`✗ ZCode integration failed (${zcode.code ?? 'unknown'})`);
-      return false;
-    }
-    log('✓ ZCode integration');
-  }
-
-  const startup = installer.installWindowsStartup?.({ home, root: releaseDir });
-  if (startup?.ok === false) {
-    log(`✗ Windows login startup failed (${startup.code ?? 'unknown'})`);
-    return false;
-  }
-  if (startup?.supported) log('✓ Windows login startup');
-
-  const claude = await installer.installClaudeCode({ home, root: releaseDir });
+  log('✓ Codex Desktop integration');
+
+  if (installer.installZCode) {
+    const zcode = installer.installZCode({ home, root: releaseDir });
+    if (zcode.ok === false) {
+      log(`✗ ZCode integration failed (${zcode.code ?? 'unknown'})`);
+      return false;
+    }
+    log('✓ ZCode integration');
+  }
+
+  const startup = installer.installWindowsStartup?.({ home, root: releaseDir });
+  if (startup?.ok === false) {
+    log(`✗ Windows login startup failed (${startup.code ?? 'unknown'})`);
+    return false;
+  }
+  if (startup?.supported) log('✓ Windows login startup');
+
+  const claude = await installer.installClaudeCode({ home, root: releaseDir });
   if (claude.ok === false) {
     log(`✗ Claude Code integration failed`);
     return false;
@@ -700,8 +816,14 @@ export const UPDATE_DEFAULT_SPEC = `${UPDATE_PACKAGE_NAME}@latest`;
  */
 export function extractPackageTarball(tgzPath, destDir, { runner = spawnSync } = {}) {
   mkdirSync(destDir, { recursive: true });
-  const result = runner('tar', ['-xzf', String(tgzPath), '-C', destDir], {
-    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: 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
+  // archive by basename: every argument stays colon-free for both bsdtar
+  // (Windows 10+) and GNU tar, whatever PATH resolves first.
+  const localArchive = join(destDir, 'candidate.tgz');
+  copyFileSync(tgzPath, localArchive);
+  const result = runner('tar', ['-xzf', 'candidate.tgz'], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, cwd: destDir,
   });
   const root = join(destDir, 'package');
   if (result.status !== 0 || !existsSync(join(root, 'package.json'))) {
@@ -779,15 +901,15 @@ export function resolveUpdateCandidate({
   mkdirSync(tmpDir, { recursive: true });
   try {
     const effectiveSpec = process.env.DSH_CREW_UPDATE_SPEC ?? spec;
-    const packArgs = ['pack', effectiveSpec, '--pack-destination', tmpDir, '--json', '--loglevel=error'];
-    log(`- resolving update candidate from the configured npm registry (${effectiveSpec})`);
-    const invocation = npmCliInvocation(packArgs);
-    const packed = runner(invocation.command, invocation.args, {
-      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: 600_000, windowsHide: true,
-      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
-      env: sanitizedPackageManagerEnv(),
-    });
+    const packArgs = ['pack', effectiveSpec, '--pack-destination', tmpDir, '--json', '--loglevel=error'];
+    log(`- resolving update candidate from the configured npm registry (${effectiveSpec})`);
+    const invocation = npmCliInvocation(packArgs);
+    const packed = runner(invocation.command, invocation.args, {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 600_000, windowsHide: true,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+      env: sanitizedPackageManagerEnv(),
+    });
     if (packed.status !== 0) {
       return { ok: false, code: 'REGISTRY_PACK_FAILED', detail: `${effectiveSpec}: ${(packed.stderr || packed.stdout || '').trim().slice(-300)}` };
     }
@@ -982,17 +1104,17 @@ export function npxStatus({
     } catch { dshPlugin = 'unknown'; }
   }
 
-  const st = installer.installStatus
-    ? installer.installStatus({ home, root: pointer?.path ?? runningPackageRoot() })
-    : realInstaller.installStatus({ home, root: pointer?.path ?? runningPackageRoot() });
-  const codex = st?.codex?.installed ? 'installed' : 'not installed';
-  const zcode = st?.zcode?.installed ? 'installed' : 'not installed';
-  const claude = st?.claude?.installed ? 'installed' : 'not installed';
+  const st = installer.installStatus
+    ? installer.installStatus({ home, root: pointer?.path ?? runningPackageRoot() })
+    : realInstaller.installStatus({ home, root: pointer?.path ?? runningPackageRoot() });
+  const codex = st?.codex?.installed ? 'installed' : 'not installed';
+  const zcode = st?.zcode?.installed ? 'installed' : 'not installed';
+  const claude = st?.claude?.installed ? 'installed' : 'not installed';
   const official = officialWebIntegrationStatus({ home, releaseDir: pointer?.path });
-  const officialWeb = !official.enabled ? 'disabled' : official.healthy ? 'installed' : 'needs repair';
-  const startupState = installer.windowsStartupStatus?.({ home });
-  const windowsStartup = !startupState?.supported ? 'not supported'
-    : startupState.ready ? 'installed' : startupState.installed ? 'needs repair' : 'not installed';
+  const officialWeb = !official.enabled ? 'disabled' : official.healthy ? 'installed' : 'needs repair';
+  const startupState = installer.windowsStartupStatus?.({ home });
+  const windowsStartup = !startupState?.supported ? 'not supported'
+    : startupState.ready ? 'installed' : startupState.installed ? 'needs repair' : 'not installed';
 
   log(`DSH Crew launcher/candidate: ${candidateVersion ?? 'unknown'}`);
   log(`Installed DSH Crew payload: ${installedLine}`);
@@ -1008,10 +1130,10 @@ export function npxStatus({
   }
   log(`DSH plugin: ${dshPlugin} (dedicated dsh-crew profile on 3210)`);
   log(`Official 3080 UI bridge: ${officialWeb}`);
-  log(`Codex Desktop integration: ${codex}`);
-  log(`ZCode integration: ${zcode}`);
-  log(`Claude Code integration: ${claude}`);
-  log(`Windows login startup: ${windowsStartup}`);
+  log(`Codex Desktop integration: ${codex}`);
+  log(`ZCode integration: ${zcode}`);
+  log(`Claude Code integration: ${claude}`);
+  log(`Windows login startup: ${windowsStartup}`);
 
   return {
     ok: true,
@@ -1020,11 +1142,11 @@ export function npxStatus({
     installedPath: pointer?.path ?? null,
     dshPlugin,
     officialWeb,
-    codex,
-    zcode,
-    claude,
-    windowsStartup,
-  };
+    codex,
+    zcode,
+    claude,
+    windowsStartup,
+  };
 }
 
 export async function npxUninstall({
@@ -1040,23 +1162,23 @@ export async function npxUninstall({
   const pointer = readCurrentPointer({ home });
   const name = pointer?.name ?? readManifest(runningPackageRoot())?.name;
 
-  const cx = installer.uninstallCodex({ home });
+  const cx = installer.uninstallCodex({ home });
   if (cx.ok !== false) log('✓ Codex Desktop integration removed');
-  else fail('Codex Desktop integration removal failed');
-
-  if (installer.uninstallZCode) {
-    const zc = installer.uninstallZCode({ home });
-    if (zc.ok !== false) log('✓ ZCode integration removed');
-    else fail('ZCode integration removal failed');
-  }
+  else fail('Codex Desktop integration removal failed');
 
-  const cl = installer.uninstallClaudeCode ? await installer.uninstallClaudeCode({ home }) : realInstaller.uninstallClaudeCode({ home });
-  if (cl.ok !== false) log('✓ Claude Code integration removed');
-  else fail('Claude Code integration removal failed');
-
-  const startup = installer.uninstallWindowsStartup?.({ home });
-  if (startup?.ok === false) fail('Windows login startup removal failed');
-  else if (startup?.supported) log('✓ Windows login startup removed');
+  if (installer.uninstallZCode) {
+    const zc = installer.uninstallZCode({ home });
+    if (zc.ok !== false) log('✓ ZCode integration removed');
+    else fail('ZCode integration removal failed');
+  }
+
+  const cl = installer.uninstallClaudeCode ? await installer.uninstallClaudeCode({ home }) : realInstaller.uninstallClaudeCode({ home });
+  if (cl.ok !== false) log('✓ Claude Code integration removed');
+  else fail('Claude Code integration removal failed');
+
+  const startup = installer.uninstallWindowsStartup?.({ home });
+  if (startup?.ok === false) fail('Windows login startup removal failed');
+  else if (startup?.supported) log('✓ Windows login startup removed');
 
   const official = removeOfficialWebIntegration({ home, preserveIntent: !purge, remember: !purge });
   if (!official.ok) fail(`official 3080 bridge removal failed (${official.code ?? 'unknown'})`);
@@ -1103,8 +1225,12 @@ Commands:
   integrate   show Crew inside the official 3080 UI; backend stays isolated on 3210
   detach      remove only the official 3080 bridge; isolated 3210 mode remains available
   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
+  inspect     print the machine-readable extension capability/readiness contract
+  jobs        machine-first job API: list|get|watch|cancel|submit
+  providers   3210 provider lifecycle API: list|delete-plan|delete|rollback|probe
+  credentials 3210 credential references: list|purge-plan|purge (separate confirmation)
+  releases    list retained, validated Crew payload releases
+  rollback    switch to a retained payload version and verify the 3210 runtime
   update      resolve the newest permitted package from the configured npm registry (or
               --candidate), stage and validate it, then activate; idempotent when current
   uninstall   remove the Crew-managed payload, registration, and integrations (config kept)
@@ -1113,20 +1239,25 @@ Options:
   --candidate <path>  update from a local payload directory or packed .tgz instead of the registry
   --after <sequence>  with jobs watch/get: return canonical events after this cursor
   --detail <mode>     with jobs get/watch: compact (default) or full
-  --request <path>    with jobs submit: JSON Job Request document
+  --request <path>    with jobs submit: JSON Job Request document
+  --plan <id>         with providers/credentials destructive actions: approved plan id
+  --expected-revision <sha256>  with providers/credentials actions: revision from plan
+  --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)
   --help              show this help
 
 Primary install: npm install -g @ran-sh/dsh-crew   (then run: dsh-crew install)
 Source checkouts use scripts/setup.mjs instead.`;
 
-export async function npxInspect({
+export async function npxInspect({
   log = console.log,
   fetchImpl = globalThis.fetch,
   readConfig = realInstaller.readGlobalConfig,
-} = {}) {
-  const hubUrl = readConfig()?.hub_url ?? 'http://127.0.0.1:3210';
-  const url = `${String(hubUrl).replace(/\/$/, '')}/_dsh/dsh-crew/extension`;
+} = {}) {
+  const hubUrl = String(readConfig()?.hub_url ?? PRODUCTION_HUB_URL).replace(/\/$/, '');
+  await assertProductionHub({ hubUrl, requiredCapabilities: INSPECT_CAPABILITIES, purpose: 'inspect', fetchImpl });
+  const url = `${String(hubUrl).replace(/\/$/, '')}/_dsh/dsh-crew/extension`;
   const response = await fetchImpl(url, { headers: { accept: 'application/json' } });
   const body = await response.json();
   if (!response.ok || body?.ok !== true || !body.extension) {
@@ -1136,7 +1267,7 @@ export async function npxInspect({
   return { ok: true, extension: body.extension };
 }
 
-export async function npxJobs({
+export async function npxJobs({
   args = [],
   after = 0,
   detail = 'compact',
@@ -1144,12 +1275,15 @@ export async function npxJobs({
   log = console.log,
   fetchImpl = globalThis.fetch,
   readConfig = realInstaller.readGlobalConfig,
-} = {}) {
-  const hubUrl = String(readConfig()?.hub_url ?? 'http://127.0.0.1:3210').replace(/\/$/, '');
-  const base = `${hubUrl}/_dsh/dsh-crew/jobs`;
-  const action = args[0] ?? 'list';
-  const id = args[1];
-  let url = base;
+} = {}) {
+  const hubUrl = String(readConfig()?.hub_url ?? 'http://127.0.0.1:3210').replace(/\/$/, '');
+  const base = `${hubUrl}/_dsh/dsh-crew/jobs`;
+  const action = args[0] ?? 'list';
+  const id = args[1];
+  const requiredCapabilities = JOB_CAPABILITY_REQUIREMENTS[action];
+  if (!requiredCapabilities) throw new Error(`unknown jobs action: ${action}`);
+  await assertProductionHub({ hubUrl, requiredCapabilities, purpose: 'job', fetchImpl });
+  let url = base;
   let init = { headers: { accept: 'application/json' } };
   if (action === 'get' || action === 'watch') {
     if (!id) throw new Error(`jobs ${action} requires a job id`);
@@ -1162,22 +1296,224 @@ export async function npxJobs({
     if (!request) throw new Error('jobs submit requires --request <json-file>');
     const document = JSON.parse(readFileSync(resolve(request), 'utf8'));
     init = { method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify(document) };
-  } else if (action !== 'list') {
-    throw new Error(`unknown jobs action: ${action}`);
-  }
+  }
   const response = await fetchImpl(url, init);
   const body = await response.json();
   if (!response.ok || body?.ok === false) throw new Error(body?.error ?? 'Crew jobs API unavailable');
   log(JSON.stringify(body, null, 2));
-  return { ok: true, body };
-}
-
-function normalizeCommand(argv) {
-  const flags = argv.slice(1);
-  let candidate;
-  let after = 0;
-  let detail = 'compact';
-  let request;
+  return { ok: true, body };
+}
+
+const PROVIDER_CAPABILITY_REQUIREMENTS = Object.freeze({
+  list: Object.freeze(['provider-inventory']),
+  'delete-plan': Object.freeze(['provider-inventory', 'provider-lifecycle-v1']),
+  delete: Object.freeze(['provider-inventory', 'provider-lifecycle-v1']),
+  rollback: Object.freeze(['provider-inventory', 'provider-lifecycle-v1']),
+  probe: Object.freeze(['provider-inventory', 'provider-health-v1', 'provider-probe-stream-v1']),
+});
+const JOB_CAPABILITY_REQUIREMENTS = Object.freeze({
+  list: Object.freeze(['jobs']),
+  get: Object.freeze(['jobs', 'jobs-wait']),
+  watch: Object.freeze(['jobs', 'jobs-wait']),
+  cancel: Object.freeze(['jobs', 'jobs-cancel']),
+  submit: Object.freeze(['jobs', 'roles', 'attempt-index', 'model-policy']),
+});
+const INSPECT_CAPABILITIES = Object.freeze(['extension-contract', 'evidence', 'runtime-provenance-v1']);
+const CREDENTIAL_CAPABILITY_REQUIREMENTS = Object.freeze({
+  list: Object.freeze(['credential-reference-inventory-v1']),
+  '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';
+
+export 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;
+  try { body = await response.json(); } catch { body = null; }
+  const validIdentity = response.ok && body?.ok === true
+    && body?.service === 'dsh-crew-hub'
+    && body?.execution_plane === 'hub-3210'
+    && body?.profile === 'dsh-crew'
+    && Number(body?.listen_port) === 3210
+    && typeof body?.runtime_id === 'string' && body.runtime_id.trim().length > 0;
+  if (!validIdentity) throw new Error(`${purpose} requires a compatible isolated 3210 Crew Hub`);
+  const advertised = new Set(Array.isArray(body.capabilities) ? body.capabilities.filter((value) => typeof value === 'string') : []);
+  const missing = requiredCapabilities.filter((capability) => !advertised.has(capability));
+  if (missing.length > 0) throw new Error(`missing ${purpose} capability: ${missing.join(', ')}`);
+  return { ok: true, runtime: body, capabilities: [...advertised] };
+}
+
+/**
+ * Confirm the target is the live isolated Hub and advertises the lifecycle
+ * 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 } = {}) {
+  return assertProductionHub({
+    hubUrl,
+    requiredCapabilities: PROVIDER_CAPABILITY_REQUIREMENTS[action] ?? PROVIDER_CAPABILITY_REQUIREMENTS.list,
+    purpose: 'provider lifecycle',
+    fetchImpl,
+  });
+}
+
+/**
+ * Call the isolated 3210 provider lifecycle API. The CLI never parses or
+ * edits Harness YAML itself; the Hub remains the sole mutation authority.
+ */
+export async function npxProviders({
+  args = [],
+  planId,
+  expectedRevision,
+  replacementDefault,
+  confirm = false,
+  purgeOrphanCredentials = false,
+  log = console.log,
+  fetchImpl = globalThis.fetch,
+  readConfig = realInstaller.readGlobalConfig,
+} = {}) {
+  const configuredHubUrl = String(readConfig()?.hub_url ?? PRODUCTION_HUB_URL).replace(/\/$/, '');
+  const hubUrl = configuredHubUrl;
+  const base = `${hubUrl}/_dsh/dsh-crew/providers`;
+  const action = args[0] ?? 'list';
+  const id = args[1];
+  const options = new Map();
+  for (let index = 2; index < args.length; index += 1) {
+    const value = args[index];
+    if (!value?.startsWith('--')) continue;
+    const [name, inline] = value.split('=', 2);
+    if (name === '--confirm' || name === '--purge-orphan-credentials') options.set(name === '--confirm' ? 'confirm' : name, true);
+    else if (inline !== undefined) options.set(name, inline);
+    else if (args[index + 1] !== undefined) options.set(name, args[++index]);
+  }
+  const resolvedPlan = planId ?? options.get('--plan');
+  const resolvedRevision = expectedRevision ?? options.get('--expected-revision');
+  const resolvedReplacement = replacementDefault ?? options.get('--replacement-default');
+  const resolvedConfirm = confirm === true || options.get('confirm') === true;
+  if (purgeOrphanCredentials === true || options.get('--purge-orphan-credentials') === true) {
+    throw new Error('credential purge requires a separate explicit confirmation flow');
+  }
+  await assertProviderHubCapabilities({ hubUrl, action, fetchImpl });
+  let url = base;
+  let init = { headers: { accept: 'application/json' } };
+  if (action === 'list') {
+    // keep defaults
+  } else if (action === 'delete-plan') {
+    if (!id) throw new Error('providers delete-plan requires a provider id');
+    url = `${base}/${encodeURIComponent(id)}/delete-plan`;
+    init = { method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ ...(resolvedReplacement ? { replacement_default: resolvedReplacement } : {}) }) };
+  } else if (action === 'delete') {
+    if (!id) throw new Error('providers delete requires a provider id');
+    if (!resolvedPlan || !resolvedRevision || !resolvedConfirm) throw new Error('providers delete requires --plan, --expected-revision and --confirm');
+    url = `${base}/${encodeURIComponent(id)}`;
+    init = {
+      method: 'DELETE',
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify({ plan_id: resolvedPlan, expected_revision: resolvedRevision, confirm: true }),
+    };
+  } else if (action === 'probe') {
+    if (!id) throw new Error('providers probe requires a provider id');
+    url = `${base}/${encodeURIComponent(id)}/probe`;
+    init = { method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: '{}' };
+  } else if (action === 'rollback') {
+    if (!id) throw new Error('providers rollback requires a provider id');
+    if (!resolvedPlan || !resolvedConfirm) throw new Error('providers rollback requires --plan and --confirm');
+    url = `${base}/${encodeURIComponent(id)}/rollback`;
+    init = { method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ transaction_id: resolvedPlan, confirm: true }) };
+  } else {
+    throw new Error(`unknown providers action: ${action}`);
+  }
+  const response = await fetchImpl(url, init);
+  let body = await response.json();
+  if (!response.ok || body?.ok === false) throw new Error(body?.code ?? body?.error ?? 'Crew provider API unavailable');
+  if (action === 'delete' && body?.restart_required === true && body?.result?.state === 'RESTART_PENDING') {
+    const restartResponse = await fetchImpl('http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart', {
+      method: 'POST',
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify({ confirm: true }),
+    });
+    const restartBody = await restartResponse.json();
+    if (!restartResponse.ok || restartBody?.ok !== true) throw new Error(restartBody?.code ?? restartBody?.error ?? 'Crew 3210 restart failed');
+    const verifyUrl = `${base}/${encodeURIComponent(id)}/verify-delete`;
+    const verifyResponse = await fetchImpl(verifyUrl, {
+      method: 'POST',
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify({ transaction_id: resolvedPlan, confirm: true }),
+    });
+    const verifyBody = await verifyResponse.json();
+    if (!verifyResponse.ok || verifyBody?.ok !== true) throw new Error(verifyBody?.code ?? verifyBody?.error ?? 'Crew provider deletion verification failed');
+    body = { ...body, restart: restartBody, verification: verifyBody };
+  }
+  if (action === 'rollback' && body?.restart_required === true && body?.state === 'ROLLBACK_PENDING') {
+    const restartResponse = await fetchImpl('http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart', {
+      method: 'POST',
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify({ confirm: true }),
+    });
+    const restartBody = await restartResponse.json();
+    if (!restartResponse.ok || restartBody?.ok !== true) throw new Error(restartBody?.code ?? restartBody?.error ?? 'Crew 3210 restart failed');
+    const verifyUrl = `${base}/${encodeURIComponent(id)}/verify-rollback`;
+    const verifyResponse = await fetchImpl(verifyUrl, {
+      method: 'POST',
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify({ transaction_id: resolvedPlan, confirm: true }),
+    });
+    const verifyBody = await verifyResponse.json();
+    if (!verifyResponse.ok || verifyBody?.ok !== true) throw new Error(verifyBody?.code ?? verifyBody?.error ?? 'Crew provider rollback verification failed');
+    body = { ...body, restart: restartBody, verification: verifyBody };
+  }
+  log(JSON.stringify(body, null, 2));
+  return { ok: true, body };
+}
+
+/** Independent credential-reference inventory and irreversible purge CLI. */
+export async function npxCredentials({
+  args = [],
+  planId,
+  expectedRevision,
+  confirm = false,
+  log = console.log,
+  fetchImpl = globalThis.fetch,
+  readConfig = realInstaller.readGlobalConfig,
+} = {}) {
+  const hubUrl = String(readConfig()?.hub_url ?? PRODUCTION_HUB_URL).replace(/\/$/, '');
+  const action = args[0] ?? 'list';
+  const id = args[1];
+  const requiredCapabilities = CREDENTIAL_CAPABILITY_REQUIREMENTS[action];
+  if (!requiredCapabilities) throw new Error(`unknown credentials action: ${action}`);
+  await assertProductionHub({ hubUrl, requiredCapabilities, purpose: 'credential', fetchImpl });
+  const base = `${hubUrl}${CREW_ROUTE_BASE}/credential-references`;
+  let url = base;
+  let init = { headers: { accept: 'application/json' } };
+  if (action === 'purge-plan') {
+    if (!id) throw new Error('credentials purge-plan requires a reference id');
+    url = `${base}/${encodeURIComponent(id)}/purge-plan`;
+    init = { method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ ...(expectedRevision ? { expected_revision: expectedRevision } : {}) }) };
+  } else if (action === 'purge') {
+    if (!id) throw new Error('credentials purge requires a reference id');
+    if (!planId || !expectedRevision || confirm !== true) throw new Error('credentials purge requires --plan, --expected-revision and --confirm');
+    url = `${base}/${encodeURIComponent(id)}`;
+    init = { method: 'DELETE', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ plan_id: planId, expected_revision: expectedRevision, confirm: true }) };
+  }
+  const response = await fetchImpl(url, init);
+  const body = await response.json();
+  if (!response.ok || body?.ok === false) throw new Error(body?.code ?? body?.error ?? 'Crew credential API unavailable');
+  log(JSON.stringify(body, null, 2));
+  return { ok: true, body };
+}
+
+function normalizeCommand(argv) {
+  const flags = argv.slice(1);
+  let candidate;
+  let after = 0;
+  let detail = 'compact';
+  let request;
+  let planId;
+  let expectedRevision;
+  let replacementDefault;
+  let confirm = false;
+  let purgeOrphanCredentials = false;
   for (let index = 0; index < flags.length; index += 1) {
     if (flags[index] === '--candidate') {
       candidate = flags[index + 1];
@@ -1199,17 +1535,34 @@ function normalizeCommand(argv) {
       after = Number(flags[index].slice('--after='.length)); flags.splice(index, 1); index -= 1;
     } else if (flags[index]?.startsWith('--detail=')) {
       detail = flags[index].slice('--detail='.length); flags.splice(index, 1); index -= 1;
-    } else if (flags[index]?.startsWith('--request=')) {
-      request = flags[index].slice('--request='.length); flags.splice(index, 1); index -= 1;
-    }
+    } else if (flags[index]?.startsWith('--request=')) {
+      request = flags[index].slice('--request='.length); flags.splice(index, 1); index -= 1;
+    } else if (flags[index] === '--plan' || flags[index] === '--expected-revision' || flags[index] === '--replacement-default') {
+      const name = flags[index];
+      const value = flags[index + 1];
+      if (name === '--plan') planId = value;
+      if (name === '--expected-revision') expectedRevision = value;
+      if (name === '--replacement-default') replacementDefault = value;
+      flags.splice(index, 2); index -= 1;
+    } else if (flags[index]?.startsWith('--plan=')) {
+      planId = flags[index].slice('--plan='.length); flags.splice(index, 1); index -= 1;
+    } else if (flags[index]?.startsWith('--expected-revision=')) {
+      expectedRevision = flags[index].slice('--expected-revision='.length); flags.splice(index, 1); index -= 1;
+    } else if (flags[index]?.startsWith('--replacement-default=')) {
+      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] === '--purge-orphan-credentials') {
+      purgeOrphanCredentials = true; flags.splice(index, 1); index -= 1;
+    }
   }
   const knownFlags = new Set(['--purge']);
   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, args, unknown };
-}
+  return { command: argv[0], purge: flags.includes('--purge'), candidate, after, detail, request, planId, expectedRevision, replacementDefault, confirm, purgeOrphanCredentials, args, unknown };
+}
 
 /**
  * CLI dispatcher used by bin/dsh-crew.mjs. Returns a process exit code.
@@ -1220,7 +1573,7 @@ export async function runNpxCli({
   error = console.error,
   commands = {},
 } = {}) {
-  const { command, purge, candidate, after, detail, request, args, unknown } = normalizeCommand(argv);
+  const { command, purge, candidate, after, detail, request, planId, expectedRevision, replacementDefault, confirm, purgeOrphanCredentials, args, unknown } = normalizeCommand(argv);
   if (command === '--help' || command === '-h' || command === 'help') {
     log(USAGE);
     return 0;
@@ -1229,7 +1582,7 @@ export async function runNpxCli({
     error(USAGE);
     return 1;
   }
-  if (unknown.length > 0 || !['install', 'integrate', 'detach', 'status', 'inspect', 'jobs', 'update', 'uninstall'].includes(command)) {
+  if (unknown.length > 0 || !['install', 'integrate', 'detach', 'status', 'inspect', 'jobs', 'providers', 'credentials', 'releases', 'rollback', 'update', 'uninstall'].includes(command)) {
     error(`unknown command: ${command ?? '<none>'}\n\n${USAGE}`);
     return 1;
   }
@@ -1239,15 +1592,23 @@ export async function runNpxCli({
       integrate: commands.integrate ?? npxIntegrate,
       detach: commands.detach ?? npxDetach,
       status: commands.status ?? npxStatus,
-      inspect: commands.inspect ?? npxInspect,
-      jobs: commands.jobs ?? npxJobs,
+      inspect: commands.inspect ?? npxInspect,
+      jobs: commands.jobs ?? npxJobs,
+      providers: commands.providers ?? npxProviders,
+      credentials: commands.credentials ?? npxCredentials,
+      releases: commands.releases ?? npxReleases,
+      rollback: commands.rollback ?? npxRollback,
       update: commands.update ?? npxUpdate,
       uninstall: commands.uninstall ?? npxUninstall,
     };
     let result;
     if (command === 'uninstall') result = await actions.uninstall({ purge, log });
-    else if (command === 'update') result = await actions.update({ candidate, log });
-    else if (command === 'jobs') result = await actions.jobs({ args, after, detail, request, log });
+    else if (command === 'update') result = await actions.update({ candidate, 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 });
+    else if (command === 'releases') result = await actions.releases({ args, log });
+    else if (command === 'rollback') result = await actions.rollback({ version: args?.[0], args, log });
     else result = await actions[command]({ log });
     return result?.ok === false ? 1 : 0;
   } catch (err) {