@ran-sh/dsh-crew 2.1.1 → 2.1.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"
@@ -8,7 +8,9 @@
   "mcpServers": {
     "dsh-crew": {
       "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/src/server.mjs"]
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/src/server.mjs"
+      ]
     }
   }
 }

package/package.json

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

package/src/history/archive-store.mjs

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 
 const WORKSPACE = 'harness/storages/workspace.json';
@@ -121,16 +121,52 @@ async function requireStopped(assertStopped) {
   if (typeof assertStopped !== 'function' || await assertStopped() !== true) fail('BACKEND_NOT_STOPPED');
 }
 
+/**
+ * Every session id that still has an artifact under `harness/sessions`.
+ *
+ * A request may name sessions as "already gone" so that a workspace they belong
+ * to stops being unreachable. That claim decides whether a record is deleted, so
+ * it is proven here rather than trusted: a live session named as absent would
+ * drop its workspace while leaving the artifact behind.
+ */
+function presentSessionIds(root) {
+  const sessionsRoot = pathInside(root, 'harness/sessions');
+  let projects;
+  try { projects = readdirSync(sessionsRoot, { withFileTypes: true }); } catch { return new Set(); }
+  if (projects.length > 20000) fail('INVALID_FILE');
+  const present = new Set();
+  for (const project of projects) {
+    if (!project.isDirectory() || project.isSymbolicLink()) continue;
+    let entries;
+    try { entries = readdirSync(join(sessionsRoot, project.name), { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !validId(entry.name)) continue;
+      const directory = join(sessionsRoot, project.name, entry.name);
+      if (entry.isSymbolicLink()) { present.add(entry.name); continue; }
+      let files = [];
+      try { files = readdirSync(directory); } catch { present.add(entry.name); continue; }
+      if (files.some(name => /^session(?:\.v[1-9][0-9]*)?\.jsonl(?:\.zstd)?$/.test(name))) present.add(entry.name);
+    }
+  }
+  return present;
+}
+
 /** Internal offline primitive: caller must own the maintenance lease + update lock. */
 export async function archiveHistory({ crewRoot, request, assertStopped, archiveId = randomUUID() }) {
   await requireStopped(assertStopped);
   if (!request || !['archive', 'delete'].includes(request.operation) || !Array.isArray(request.artifacts)
     || !Array.isArray(request.sessionIds) || !Array.isArray(request.workspaceIds)
-    || request.artifacts.length > 10000 || request.workspaceIds.length > 10000) fail('INVALID_REQUEST');
+    || !Array.isArray(request.absentSessionIds ?? [])
+    || request.artifacts.length > 10000 || request.workspaceIds.length > 10000
+    || (request.absentSessionIds ?? []).length > 10000) fail('INVALID_REQUEST');
   const selectedSessions = new Set(request.sessionIds);
   const selectedWorkspaces = new Set(request.workspaceIds);
-  if ([...selectedSessions, ...selectedWorkspaces].some(id => !validId(id))
+  const absentSessions = new Set(request.absentSessionIds ?? []);
+  const removedSessions = new Set([...selectedSessions, ...absentSessions]);
+  if ([...removedSessions, ...selectedWorkspaces].some(id => !validId(id))
     || selectedSessions.size !== request.sessionIds.length || selectedWorkspaces.size !== request.workspaceIds.length
+    || absentSessions.size !== (request.absentSessionIds ?? []).length
+    || absentSessions.size !== removedSessions.size - selectedSessions.size
     || request.artifacts.length !== selectedSessions.size
     || new Set(request.artifacts.map(f => f.sessionId)).size !== selectedSessions.size
     || request.artifacts.some(f => !selectedSessions.has(f.sessionId))) fail('INVALID_SELECTION');
@@ -140,12 +176,16 @@ export async function archiveHistory({ crewRoot, request, assertStopped, archive
   const after = structuredClone(before);
   for (const id of selectedWorkspaces) {
     const record = before.tables.workspaces[id];
-    if (!record || record.sessionIds.some(sid => !selectedSessions.has(sid))) fail('PREVIEW_CHANGED');
+    if (!record || record.sessionIds.some(sid => !removedSessions.has(sid))) fail('PREVIEW_CHANGED');
     delete after.tables.workspaces[id];
   }
+  if (absentSessions.size > 0) {
+    const live = presentSessionIds(crewRoot);
+    for (const id of absentSessions) if (live.has(id)) fail('PREVIEW_CHANGED');
+  }
   after.global.workspaceIds = after.global.workspaceIds.filter(id => !selectedWorkspaces.has(id));
-  after.global.archivedSessionIds = after.global.archivedSessionIds.filter(id => !selectedSessions.has(id));
-  for (const record of Object.values(after.tables.workspaces)) record.sessionIds = record.sessionIds.filter(id => !selectedSessions.has(id));
+  after.global.archivedSessionIds = after.global.archivedSessionIds.filter(id => !removedSessions.has(id));
+  for (const record of Object.values(after.tables.workspaces)) record.sessionIds = record.sessionIds.filter(id => !removedSessions.has(id));
   let size = 0;
   const files = request.artifacts.map(file => {
     const bytes = readBounded(artifactPath(crewRoot, file));

package/src/history/cleanup-plan.mjs

@@ -53,31 +53,63 @@ export function planHistoryCleanup(snapshot, { operation = 'archive', scope = 'c
   };
   const withinTime = (row) => cutoff === null
     || (instant(row.createdAt) !== null && instant(row.createdAt) < cutoff);
+  const present = new Set(sessions.map(row => row.id));
+  const worktreeSessions = new Set(sessions.filter(row => row.worktree === true).map(row => row.id));
   const selected = new Set(sessions.filter(row => admitted(row) && withinTime(row)).map(row => row.id));
   // A workspace carries no provenance of its own: it follows its sessions, and
   // only when every one of them is selected. Checking `admitted(row)` here would
   // test a workspace id against a session ledger and always fail. A provenance
-  // scope additionally requires at least one selected child — an empty workspace
-  // holds no Crew work, so it is not Crew's to remove; `all` keeps its historical
+  // scope additionally requires at least one child — an empty workspace holds no
+  // Crew work, so it is not Crew's to remove; `all` keeps its historical
   // behaviour of following an empty workspace.
+  //
+  // A child whose artifact is already gone cannot be "selected": there is
+  // nothing left to select. Such a child still counts as covered when the ledger
+  // recorded Crew creating it, the same evidence that makes a live one Crew's.
+  // Without that, a workspace whose sessions were removed by an earlier cleanup
+  // became permanently unreachable — every scope demanded its children, and its
+  // children no longer existed — which is exactly how 48 dead rows stayed in the
+  // store while the operator could only see them.
   const requiresOwnedChild = scope === 'crew' || scope === 'worktree';
-  const workspaceIds = workspaces.filter(row => {
+  // One decision per workspace, from that row alone: what a row is allowed to
+  // remove must never depend on which rows were visited before it.
+  const decideWorkspace = (row) => {
     const children = ids(row.sessionIds);
-    return withinTime(row) && (!requiresOwnedChild || children.length > 0)
-      && children.every(id => selected.has(id));
+    if (children.length === 0) return { ok: !requiresOwnedChild, absent: [] };
+    // Worktree scope marks a live child by its session header. A gone child has
+    // no header left, so the workspace's own path under the worktree root is the
+    // only marker there is.
+    if (scope === 'worktree' && row.worktree !== true && !children.every(id => worktreeSessions.has(id))) return { ok: false, absent: [] };
+    const gone = [];
+    for (const id of children) {
+      if (selected.has(id)) continue;
+      // Kept back by the scope, or gone with no record that Crew made it.
+      if (present.has(id) || !origin.has(id)) return { ok: false, absent: [] };
+      gone.push(id);
+    }
+    return { ok: true, absent: gone };
+  };
+  const absent = new Set();
+  const workspaceIds = workspaces.filter(row => {
+    if (!withinTime(row)) return false;
+    const decision = decideWorkspace(row);
+    if (!decision.ok) return false;
+    for (const id of decision.absent) absent.add(id);
+    return true;
   }).map(row => row.id).sort();
+  const absentSessionIds = [...absent].sort();
   const sessionIds = [...selected].sort();
   const signature = {
     operation, scope, cutoff,
-    workspaces: workspaces.map(row => ({ id: row.id, createdAt: row.createdAt, updatedAt: row.updatedAt, sessionIds: ids(row.sessionIds) })),
-    sessions: sessions.map(row => ({ id: row.id, createdAt: row.createdAt, revision: row.revision })),
+    workspaces: workspaces.map(row => ({ id: row.id, createdAt: row.createdAt, updatedAt: row.updatedAt, sessionIds: ids(row.sessionIds), worktree: row.worktree === true })),
+    sessions: sessions.map(row => ({ id: row.id, createdAt: row.createdAt, revision: row.revision, worktree: row.worktree === true })),
     active,
     crewSessionIds: [...origin].sort(),
   };
   return {
     schemaVersion: 1, operation, scope,
     before: cutoff === null ? null : new Date(cutoff).toISOString(),
-    timeBasis: 'createdAt', workspaceIds, sessionIds,
+    timeBasis: 'createdAt', workspaceIds, sessionIds, absentSessionIds,
     counts: { workspaces: workspaceIds.length, sessions: sessionIds.length },
     protectedCounts: { workspaces: workspaces.length - workspaceIds.length, sessions: sessions.length - sessionIds.length },
     executable: active.length === 0 && (workspaceIds.length > 0 || sessionIds.length > 0),

package/src/history/operation.mjs

@@ -19,6 +19,17 @@ function verifyDisk(root, manifest) {
   }
 }
 
+function removedWorkspaceIds(root, archiveId) {
+  const manifest = readHistoryManifest(root, archiveId);
+  return Object.keys(manifest.before.tables.workspaces).filter(id => !Object.hasOwn(manifest.after.tables.workspaces, id));
+}
+
+function workspacesStillPresent(root, ids) {
+  if (ids.length === 0) return [];
+  const current = decodeWorkspaceStore(readHistoryBytes(historyPath(root, 'harness/storages/workspace.json')));
+  return ids.filter(id => Object.hasOwn(current.tables.workspaces, id));
+}
+
 /** Detached executor core; injected boundaries make the real transaction testable. */
 export async function runHistoryOperation({ crewRoot, id, acquire, release, supervisor, checkFence,
   assertStopped, verifyRunning, recover = false }) {
@@ -46,7 +57,11 @@ export async function runHistoryOperation({ crewRoot, id, acquire, release, supe
     if (!alreadyStarted) {
       if (!recover || await assertStopped(state) !== true) await checkFence(state);
       save('STOPPING');
-      const stopped = await supervisor.stopOwnedBackend({ lease: state.lease, runtimeId: state.runtimeId });
+      // `refresh_frontend`: this operation rewrites `storages/workspace.json`,
+      // which the Crew-managed frontend on 3080 shares, so the launcher stops
+      // that server for the same window and starts it again afterwards. The npx
+      // lifecycle stops only 3210, because a tree swap leaves that file alone.
+      const stopped = await supervisor.stopOwnedBackend({ lease: state.lease, runtimeId: state.runtimeId, refresh_frontend: true });
       if (!stopped?.ok || await assertStopped(state) !== true) throw Error('HISTORY_STOP_NOT_VERIFIED');
       const archiveId = state.operation === 'restore' ? state.archiveId : state.id;
       const manifestFile = historyPath(crewRoot, `history/transactions/${archiveId}/manifest.json`);
@@ -73,6 +88,21 @@ export async function runHistoryOperation({ crewRoot, id, acquire, release, supe
     }
     save('VERIFYING');
     if (await verifyRunning(state) !== true) throw Error('HISTORY_RESTART_NOT_VERIFIED');
+    // The store this operation rewrote is shared with every other DSH server on
+    // the same home, and each of them writes the whole file back from memory. A
+    // process that stayed live across the window puts back exactly what was
+    // removed, and from here that is indistinguishable from success: the
+    // manifest is applied and the runtime is up. Ask the disk instead, and say
+    // so rather than report a cleanup that did not happen.
+    if (!state.rolledBack && state.operation !== 'restore') {
+      const returned = workspacesStillPresent(crewRoot, removedWorkspaceIds(crewRoot, state.archiveId ?? state.id));
+      if (returned.length > 0) {
+        state = { ...state, phase: 'FAILED', code: 'HISTORY_STORE_CHANGED_AFTER_APPLY',
+          counts: { ...(state.counts ?? {}), returned: returned.length } };
+        writeHistoryState(crewRoot, state);
+        return state;
+      }
+    }
     if (state.operation === 'delete' && !state.rolledBack) {
       await finalizeHistoryDeletion({ crewRoot, archiveId: state.archiveId ?? state.id, assertRestarted: () => verifyRunning(state) });
     }

package/src/history/runner.mjs

@@ -8,9 +8,9 @@ import { runHistoryOperation } from './operation.mjs';
 import { readHistoryState } from './state.mjs';
 import { TARGET_DSH_VERSION } from '../dsh-cohort.mjs';
 
-async function portFree() {
+async function portFree(port = 3210) {
   return new Promise(resolve => {
-    const socket = createConnection({ host: '127.0.0.1', port: 3210 });
+    const socket = createConnection({ host: '127.0.0.1', port });
     socket.setTimeout(2000);
     socket.once('connect', () => { socket.destroy(); resolve(false); });
     socket.once('timeout', () => { socket.destroy(); resolve(false); });
@@ -18,6 +18,23 @@ async function portFree() {
   });
 }
 
+/**
+ * The stopped window, proven from outside the launcher that reported it.
+ *
+ * `storages/workspace.json` is rewritten by this operation and is held in memory
+ * by every DSH server on the home, so the window has to cover more than the hub:
+ * the Crew-managed frontend on 3080 shares that home and is stopped for the same
+ * window (`refresh_frontend`). Both ports are re-probed here rather than taken
+ * on the launcher's word, and the session must be the one this transaction
+ * stopped — a lease alone never means the servers are gone.
+ */
+export async function stoppedWindowIsClean({ session, lease, runtimeId, probe = portFree }) {
+  if (!session?.ok || session.state !== 'present') return false;
+  if (session.session?.lease !== lease || session.session?.runtime_id !== runtimeId) return false;
+  if (!await probe(3210)) return false;
+  return session.session?.frontend_stopped === true ? await probe(3080) : true;
+}
+
 export async function runProductionHistory({ id, recover = false } = {}) {
   if (process.platform !== 'win32') throw Error('HISTORY_PLATFORM_UNSUPPORTED');
   const home = homedir(); const crewRoot = join(home, '.config', 'dsh-crew');
@@ -31,10 +48,9 @@ export async function runProductionHistory({ id, recover = false } = {}) {
       const response = await fetch('http://127.0.0.1:3210/_dsh/dsh-crew/history/fenced-check', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}', signal: AbortSignal.timeout(30000) });
       if (!response.ok || (await response.json()).ok !== true) throw Error('HISTORY_FENCE_NOT_IDLE');
     },
-    assertStopped: async s => {
-      const lease = readMaintenanceSession(crewRoot);
-      return lease.ok && lease.state === 'present' && lease.session.lease === s.lease && lease.session.runtime_id === s.runtimeId && await portFree();
-    },
+    assertStopped: async s => stoppedWindowIsClean({
+      session: readMaintenanceSession(crewRoot), lease: s.lease, runtimeId: s.runtimeId,
+    }),
     verifyRunning: async s => {
       try {
         const response = await fetch('http://127.0.0.1:3210/_dsh/dsh-crew/runtime', { signal: AbortSignal.timeout(3000) });

package/src/history/service.mjs

@@ -77,12 +77,15 @@ export function createHistoryService({ crewRoot, agents, persistence, runtimeId,
     for (const row of sessions) if (crewSet.has(row.id)) row.crew = true;
     // The isolated-workspace marker: the hub stamps every worktree session with a
     // cwd under the Crew worktree root, so that subset is scopeable on its own.
+    // A workspace carries the same marker from its own path, which is all that is
+    // left of a workspace whose sessions were already removed.
     const worktreeRoot = defaultWorktreeRoot().replaceAll('\\', '/').toLowerCase();
-    for (const row of sessions) {
-      if (row.crew === true && typeof row.cwd === 'string' && row.cwd.replaceAll('\\', '/').toLowerCase().startsWith(worktreeRoot)) row.worktree = true;
-    }
+    const underWorktreeRoot = value => typeof value === 'string' && value.replaceAll('\\', '/').toLowerCase().startsWith(worktreeRoot);
+    for (const row of sessions) if (row.crew === true && underWorktreeRoot(row.cwd)) row.worktree = true;
+    for (const row of workspaces) if (underWorktreeRoot(row.path)) row.worktree = true;
     const plan = planHistoryCleanup({ workspaces, sessions, crewSessionIds, activeSessionIds: gate.idle() ? [] : ['active-agent'] }, options);
     const selected = new Set(plan.sessionIds);
+    const alreadyGone = new Set(plan.absentSessionIds ?? []);
     const byId = new Map(sessions.map(row => [row.id, row]));
     const queue = sessions.filter(row => !selected.has(row.id));
     for (let i = 0; i < queue.length; i++) {
@@ -90,12 +93,16 @@ export function createHistoryService({ crewRoot, agents, persistence, runtimeId,
       if (parent && selected.delete(parent.id)) queue.push(parent);
     }
     plan.sessionIds = plan.sessionIds.filter(id => selected.has(id));
-    plan.workspaceIds = plan.workspaceIds.filter(id => store.tables.workspaces[id].sessionIds.every(sid => selected.has(sid)));
+    // Same rule the plan used, re-applied after the ancestor closure dropped
+    // sessions from the selection: a workspace follows its children, and a child
+    // the plan proved Crew's own but already removed still counts.
+    plan.workspaceIds = plan.workspaceIds.filter(id => store.tables.workspaces[id].sessionIds.every(sid => selected.has(sid) || alreadyGone.has(sid)));
     plan.counts = { workspaces: plan.workspaceIds.length, sessions: plan.sessionIds.length };
     plan.executable = gate.idle() && plan.counts.workspaces + plan.counts.sessions > 0;
     if (!plan.executable && !plan.blockedReason) plan.blockedReason = 'EMPTY_SELECTION';
     const request = { operation: plan.operation, workspaceHash: historyHash(bytes), workspaceIds: plan.workspaceIds,
-      sessionIds: plan.sessionIds, artifacts: sessions.filter(row => selected.has(row.id)).map(row => row.artifact) };
+      sessionIds: plan.sessionIds, absentSessionIds: plan.absentSessionIds ?? [],
+      artifacts: sessions.filter(row => selected.has(row.id)).map(row => row.artifact) };
     const revision = historyHash(JSON.stringify([runtimeId, plan.revision, request]));
     return { plan: { ...plan, revision, items: workspaces.filter(row => plan.workspaceIds.includes(row.id)).slice(0, 100).map(row => ({ id: row.id, title: row.title })) }, request };
   }

package/src/install/npx-lifecycle.mjs

@@ -1639,7 +1639,7 @@ export function createCrewSupervisor({
     }
   }
   return {
-    stopOwnedBackend: async ({ lease = null, runtimeId = null } = {}) => {
+    stopOwnedBackend: async ({ lease = null, runtimeId = null, refreshFrontend = false } = {}) => {
       const { readMaintenanceSession } = await import('../supervisor/restart-request.mjs');
       const durable = readMaintenanceSession(appRoot);
       if (!durable.ok) {
@@ -1675,7 +1675,11 @@ export function createCrewSupervisor({
         lease: lease ?? `txn-${now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
         runtime_id: identity.runtime_id,
       };
-      const result = await writeMaintenance({ operation: 'maintenance-stop', lease: transaction.lease, identity });
+      const result = await writeMaintenance({ operation: 'maintenance-stop', lease: transaction.lease, identity,
+        // A history maintenance rewrites the workspace store the managed 3080
+        // frontend shares, so it asks for that server too. A runtime-tree swap
+        // does not, and leaves the flag unset.
+        extra: refreshFrontend ? { refresh_frontend: true } : null });
       if (!result.ok) {
         // A failed stop must not leave a usable lease behind: clear it so a
         // later startOwnedBackend() fails closed instead of presenting a

package/src/install/windows-supervisor-adapter.mjs

@@ -281,8 +281,11 @@ export function createWindowsSupervisorHandoffHooks({
     verifyExactWatcher: async ({ expected, role }) => inspect(expected, {
       allowHelperDrift: role === 'old' && !sameHash(expected?.helper_hash, target.helper_hash),
     }),
-    maintenanceStop: async ({ lease, runtime_id: runtimeId }) => maintenanceClient?.stopOwnedBackend?.({ lease, runtimeId })
-      ?? { ok: false, code: 'SUPERVISOR_MAINTENANCE_UNAVAILABLE' },
+    maintenanceStop: async ({ lease, runtime_id: runtimeId, refresh_frontend: refreshFrontend = false }) => maintenanceClient?.stopOwnedBackend?.({
+      lease,
+      runtimeId,
+      ...(refreshFrontend ? { refreshFrontend: true } : {}),
+    }) ?? { ok: false, code: 'SUPERVISOR_MAINTENANCE_UNAVAILABLE' },
     maintenanceStatus: async ({ lease, runtime_id: runtimeId }) => {
       const durable = readMaintenanceSession(appRoot);
       if (!durable.ok) return durable;

package/src/runtime-identity.mjs

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

package/windows/start-dsh-crew.cmd

@@ -35,13 +35,15 @@ if not exist "%LAUNCH_HELPER%" (
   >>"%LAUNCH_LOG%" echo [%date% %time%] ERROR Managed launcher helper is missing: %LAUNCH_HELPER%
   echo ERROR: DSH Crew launcher helper is missing.
   echo Repair it with: dsh-crew update
-  if /i "%LAUNCH_MODE%"=="open" pause
+  if /i "%LAUNCH_MODE%"=="open" if not "%DSH_CREW_LAUNCHER_NO_PAUSE%"=="1" pause
   exit /b 1
 )
 
 powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "%LAUNCH_HELPER%" -Mode "%LAUNCH_MODE%"
 set "LAUNCH_EXIT=%ERRORLEVEL%"
-if not "%LAUNCH_EXIT%"=="0" if /i "%LAUNCH_MODE%"=="open" pause
+rem DSH_CREW_LAUNCHER_NO_PAUSE: a wrapper that reports the failure itself asks
+rem for the pause to be skipped here, so the operator presses a key once.
+if not "%LAUNCH_EXIT%"=="0" if /i "%LAUNCH_MODE%"=="open" if not "%DSH_CREW_LAUNCHER_NO_PAUSE%"=="1" pause
 exit /b %LAUNCH_EXIT%
 
 :invalid_argument
@@ -51,7 +53,8 @@ exit /b 64
 
 :help
 echo Usage: %~nx0 [--open ^| --background ^| --watch]
-echo   --open        Open official Harness on 3080, then start Crew silently on 3210.
+echo   --open        Open official Harness on 3080 and return once Crew is supervised;
+echo                 3210 keeps starting in the background.
 echo   --background  Start the Crew-owned 3210 service silently.
 echo   --watch       Keep the Crew-owned 3210 service healthy.
 exit /b 0

package/windows/start-dsh-crew.ps1

@@ -227,7 +227,7 @@ function Test-CrewWebSessionUrl {
 }
 
 function Open-CrewManagedFrontend {
-  param([int] $TimeoutSeconds = 90)
+  param([int] $TimeoutSeconds = 90, [switch] $Quiet)
   # The 3080 frontend boots from the same Crew-managed Harness entry as 3210,
   # against that entry's own DSH_HOME (npm runtime -> Crew home, source cohort
   # -> its own tree). No official ~/.dsh state is read or written here.
@@ -253,7 +253,7 @@ function Open-CrewManagedFrontend {
       if (-not (Test-OfficialWebReady)) { throw 'The Crew-managed 3080 frontend is not ready; its process was left running.' }
       $existingUrl = Get-CrewWebSessionUrl
       if ($existingUrl -and (Test-CrewWebSessionUrl -Url $existingUrl)) {
-        Open-CrewBrowserUrl -Url $existingUrl
+        if (-not $Quiet) { Open-CrewBrowserUrl -Url $existingUrl }
         Write-LaunchLog 'Opened the existing Crew-managed Harness frontend on 3080 with its session URL.'
         return $true
       }
@@ -289,7 +289,10 @@ function Open-CrewManagedFrontend {
         }
         if (Test-OfficialWebReady) {
           $startedUrl = Get-CrewWebSessionUrl -OutputLog $stdout
-          if ($startedUrl) { Open-CrewBrowserUrl -Url $startedUrl; return $true }
+          if ($startedUrl) {
+            if (-not $Quiet) { Open-CrewBrowserUrl -Url $startedUrl }
+            return $true
+          }
         }
       }
       if ($process.HasExited) { throw ('Crew-managed Harness exited before readiness. Diagnostic log: {0}' -f $stderr) }
@@ -302,8 +305,7 @@ function Open-CrewManagedFrontend {
   }
 }
 
-function Test-OfficialWebReady {
-  try {
+function Test-OfficialWebReady {  try {
     $response = Invoke-WebRequest -UseBasicParsing -Uri 'http://127.0.0.1:3080/' -TimeoutSec 2
     return $response.StatusCode -ge 200 -and $response.StatusCode -lt 300
   } catch {
@@ -313,6 +315,63 @@ function Test-OfficialWebReady {
   }
 }
 
+# ---- The other server on this DSH home -------------------------------------
+# The Crew-managed frontend on 3080 boots from the same Crew-managed entry as the
+# hub, so it runs on the same DSH home: same sessions, same settings, and the
+# same `storages/workspace.json`. DSH's JSON storage replaces that whole file and
+# lets the last writer win, so an external rewrite of it only sticks while no
+# server holds the file in memory. A history maintenance is exactly such an
+# external rewrite, which is why it asks for this server to be stopped too —
+# stopping the hub alone is what let a cleanup be undone minutes later.
+function Stop-CrewManagedFrontend {
+  param([int] $TimeoutSeconds = 15)
+  $port = Get-PortState -Port 3080
+  if ($port.State -eq 'free') { return $true }
+  # An unenumerable listener is not provably free: fail closed rather than write
+  # under a server that might hold the very file being rewritten.
+  if ($port.State -ne 'occupied' -or -not $port.Pid) { return $false }
+  $ours = $false
+  if ($dshCliIsNodeEntry) {
+    $official = [pscustomobject]@{ NodePath = $dshCommand; Entry = $dshCli; Profile = 'web' }
+    $ours = Test-OfficialHarnessListener -OwnerPid ([int] $port.Pid) -Official $official -Profile 'web'
+  }
+  if (-not $ours) {
+    # Crew did not start this listener, so it cannot be proven to share the
+    # workspace store. A Crew-patched one is on a Crew home either way and is
+    # refused; the legacy official frontend and anything unrelated keep running,
+    # exactly as the start path leaves a foreign 3080 alone.
+    $patched = $false
+    try {
+      $probe = Invoke-RestMethod -Uri 'http://127.0.0.1:3080/_dsh/dsh-crew/bridge-status' -TimeoutSec 2
+      $patched = $probe.surface -eq 'official-bridge'
+    } catch { $patched = $false }
+    if ($patched) { return $false }
+    Write-LaunchLog 'A 3080 listener that is not the Crew-managed frontend was left running; it does not serve this DSH home.' 'WARN'
+    return $true
+  }
+  try { Stop-Process -Id ([int] $port.Pid) -Force -ErrorAction Stop } catch { return $false }
+  $deadline = (Get-Date).AddSeconds($TimeoutSeconds)
+  do {
+    $port = Get-PortState -Port 3080
+    if ($port.State -eq 'free') { return $true }
+    Start-Sleep -Milliseconds 250
+  } while ((Get-Date) -lt $deadline)
+  Write-LaunchLog ('The Crew-managed frontend on 3080 did not release the port within {0}s.' -f $TimeoutSeconds) 'WARN'
+  return $false
+}
+
+function Start-CrewManagedFrontendQuietly {
+  # Give back what a maintenance window took. Never fatal: the next desktop
+  # launch starts the frontend anyway, and that is where the operator reloads
+  # from, because a restarted frontend answers on a new session URL.
+  try {
+    if (Open-CrewManagedFrontend -Quiet) { Write-LaunchLog 'Crew-managed frontend on 3080 is serving again after maintenance.' }
+    else { Write-LaunchLog 'Crew-managed frontend on 3080 was not restarted after maintenance; the next desktop launch will start it.' 'WARN' }
+  } catch {
+    Write-LaunchLog ('Crew-managed frontend on 3080 could not be restarted after maintenance: {0}' -f $_.Exception.Message) 'WARN'
+  }
+}
+
 function Get-OfficialFrontendOverlay {
   $frontendRoot = Join-Path $env:USERPROFILE '.config\dsh-crew\frontend'
   $path = Join-Path $frontendRoot 'official-web.patch.json'
@@ -645,18 +704,50 @@ function Restore-OwnedServiceRecord {
   return $true
 }
 
-function Ensure-CrewSupervisorRunning {
-  param([int] $TimeoutSeconds = 90)
-  $watcher = $null
+# Spawns the persistent watcher when no live one is present, and returns its
+# heartbeat record when one already is. Shared so that the interactive and the
+# blocking entries agree on what counts as "a supervisor is already running" —
+# two answers to that question would let one entry spawn a duplicate that the
+# mutex immediately kills.
+function Start-CrewSupervisorProcess {
   $observed = Get-SupervisorHeartbeatRecord
   if ($observed -and $observed.State -eq 'legacy-v1') {
     throw 'CREW_SUPERVISOR_UPGRADE_REQUIRED: a legacy watcher is active and must be handed off before interactive launch.'
   }
-  if (-not $observed) {
-    $arguments = @(Get-SupervisorLaunchArguments -ScriptPath $PSCommandPath)
-    $watcher = Start-Process -FilePath 'powershell.exe' -ArgumentList $arguments -WindowStyle Hidden -PassThru
-    Write-LaunchLog ('Started persistent Crew supervisor; PID={0}.' -f $watcher.Id)
+  if ($observed) { return $observed }
+  $arguments = @(Get-SupervisorLaunchArguments -ScriptPath $PSCommandPath)
+  $watcher = Start-Process -FilePath 'powershell.exe' -ArgumentList $arguments -WindowStyle Hidden -PassThru
+  Write-LaunchLog ('Started persistent Crew supervisor; PID={0}.' -f $watcher.Id)
+  return $null
+}
+
+# Waits only for the watcher to exist, not for 3210 to answer. The watcher
+# publishes its heartbeat before it first touches the port, so this returns as
+# soon as Crew is being supervised. Used by the interactive entry: 3080 is
+# already serving by then, and making the operator's window wait for a first
+# 3210 boot (measured 18-78s on this machine, longer under load) delays nothing
+# they can see — the watcher performs that same wait either way.
+function Wait-CrewSupervisorStarted {
+  param([int] $TimeoutSeconds = 30)
+  $observed = Start-CrewSupervisorProcess
+  if ($observed) {
+    Write-LaunchLog ('Persistent Crew supervisor already running; PID={0}.' -f $observed.Record.pid)
+    return $true
   }
+  $deadline = (Get-Date).AddSeconds($TimeoutSeconds)
+  do {
+    $record = Get-SupervisorHeartbeatRecord
+    if ($record) {
+      Write-LaunchLog ('Persistent Crew supervisor started; PID={0}; state={1}.' -f $record.Record.pid, $record.State)
+      return $true
+    }
+    Start-Sleep -Milliseconds 250
+  } while ((Get-Date) -lt $deadline)
+  return $false
+}
+
+function Ensure-CrewSupervisorRunning {  param([int] $TimeoutSeconds = 90)
+  $null = Start-CrewSupervisorProcess
 
   $crew = $services | Where-Object { $_.CrewOwned } | Select-Object -First 1
   if (-not $crew) { throw 'Crew-owned 3210 service definition is missing.' }
@@ -792,7 +883,7 @@ function Test-MaintenanceSessionActive {
 }
 
 function Set-MaintenanceSession {
-  param([object] $Request)
+  param([object] $Request, [bool] $FrontendStopped = $false)
   # Strong-failure semantics: the STOPPED result may only be published after
   # the session is durably written AND read back with exact identity. Any
   # failure returns $false and the caller must NOT claim the stopped window.
@@ -804,6 +895,9 @@ function Set-MaintenanceSession {
       runtime_id = $Request.runtime_id
       stopped_at = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
       request_id = $Request.request_id
+      # Recorded so the matching start restores what this window stopped: the
+      # 3080 frontend shares the workspace store the maintenance is rewriting.
+      frontend_stopped = $FrontendStopped
     } | ConvertTo-Json -Compress
     $temp = Join-Path $crewSupervisorRoot ("maintenance-session.{0}.tmp" -f $PID)
     Write-Utf8NoBom -Path $temp -Content $session
@@ -909,8 +1003,30 @@ function Invoke-CrewMaintenanceRequests {
         Write-LaunchLog ('Maintenance-stop {0} rejected: live runtime_id mismatch.' -f $request.request_id) 'WARN'
         continue
       }
+      # `refresh_frontend` is how a history maintenance asks for the whole DSH
+      # home to be quiet, not just 3210: the managed frontend shares the
+      # workspace store this operation rewrites. The npx lifecycle does not ask,
+      # because a runtime-tree swap does not touch that store.
+      $refreshFrontend = $false
+      if ($request.extra) {
+        $refreshFlag = $request.extra.PSObject.Properties['refresh_frontend']
+        $refreshFrontend = $null -ne $refreshFlag -and $refreshFlag.Value -eq $true
+      }
+      $frontendStopped = $false
+      if ($refreshFrontend) {
+        # Stopped BEFORE the backend: a failure here must abort with everything
+        # still running. Aborting after 3210 is down would leave no session
+        # published, and ordinary supervision would restart it mid-transaction.
+        if (-not (Stop-CrewManagedFrontend)) {
+          Write-MaintenanceResult $request 'SUPERVISOR_FRONTEND_STOP_FAILED'
+          Write-LaunchLog ('Maintenance-stop {0} could not stop the Crew-managed frontend on 3080; nothing was stopped.' -f $request.request_id) 'ERROR'
+          continue
+        }
+        $frontendStopped = $true
+      }
       $port = Get-PortState $crew.Port
       if ($port.State -ne 'occupied' -or -not $port.Pid) {
+        if ($frontendStopped) { Start-CrewManagedFrontendQuietly }
         Write-MaintenanceResult $request 'SUPERVISOR_STOP_FAILED'
         continue
       }
@@ -923,15 +1039,16 @@ function Invoke-CrewMaintenanceRequests {
         # durably written AND read back with exact identity. A session write
         # failure must never tell npx it owns a stopped window it cannot
         # later prove (that race auto-restarts 3210 mid tree-swap).
-        $sessionDurable = Set-MaintenanceSession $request
+        $sessionDurable = Set-MaintenanceSession $request $frontendStopped
         if ($sessionDurable) {
-          Write-MaintenanceResult $request 'STOPPED' @{ lease = $request.lease; stopped_runtime_id = $request.runtime_id }
+          Write-MaintenanceResult $request 'STOPPED' @{ lease = $request.lease; stopped_runtime_id = $request.runtime_id; frontend_stopped = $frontendStopped }
           Write-LaunchLog ('Maintenance-stop {0} executed; lease issued.' -f $request.request_id)
         } else {
           Write-MaintenanceResult $request 'SUPERVISOR_SESSION_PERSIST_FAILED'
           Write-LaunchLog ('Maintenance-stop {0} stopped the process but the STOPPED session could not be persisted; NOT publishing STOPPED.' -f $request.request_id) 'ERROR'
         }
       } else {
+        if ($frontendStopped) { Start-CrewManagedFrontendQuietly }
         Write-MaintenanceResult $request 'SUPERVISOR_STOP_FAILED'
       }
     } elseif ($request.operation -eq 'maintenance-start') {
@@ -953,6 +1070,8 @@ function Invoke-CrewMaintenanceRequests {
         Write-LaunchLog ('Maintenance-start {0} rejected: no matching STOPPED session (lease/identity mismatch).' -f $request.request_id) 'WARN'
         continue
       }
+      $frontendProperty = $session.PSObject.Properties['frontend_stopped']
+      $restoreFrontend = $null -ne $frontendProperty -and $frontendProperty.Value -eq $true
       $livePort = Get-PortState $crew.Port
       if ($livePort.State -ne 'free') {
         # occupied AND unknown both fail closed: the stopped window is not
@@ -994,6 +1113,9 @@ function Invoke-CrewMaintenanceRequests {
         Write-MaintenanceResult $request 'VERIFY_FAILED' @{ lease = $lease; runtime_id = $failedRuntimeId }
         Write-LaunchLog ('Maintenance-start {0} verification failed.' -f $request.request_id) 'ERROR'
       }
+      # After the result, so a slow frontend boot never delays the transaction
+      # this start is here to close.
+      if ($restoreFrontend) { Start-CrewManagedFrontendQuietly }
     } else {
       # Unknown maintenance op: remove and report.
       Write-MaintenanceResult $request 'MAINTENANCE_UNKNOWN_OP'
@@ -1211,7 +1333,10 @@ function Ensure-CrewServices {
     # matching maintenance-start owns the launch right.
     if ($service.CrewOwned -and (Test-MaintenanceSessionActive)) {
       $service.State = 'maintenance'
-      $service.LastError = $null
+      # Say why, rather than clearing the field: an empty reason reaches the
+      # startup wait as "deadline exceeded: dsh-crew:3210 ()", which reads like a
+      # fault when the fence is the supervisor doing exactly as it was told.
+      $service.LastError = 'a maintenance session holds the launch right (an update is mid-handoff); auto-start deferred'
       continue
     }
     $health = Get-HealthState $service
@@ -1393,10 +1518,35 @@ try {
     exit 0
   }
 
-  Ensure-CrewSupervisorRunning
-
   if ($Mode -eq 'open') {
-    Write-LaunchLog 'Official frontend is on 3080; Crew is running silently on 3210.'
+    # A desktop launch promises the frontend on 3080, and that is up in about a
+    # second. The supervisor owns 3210 from the moment it starts — it publishes
+    # its heartbeat before it first touches the port — so this waits for the
+    # watcher to be running, reports where 3210 actually is, and returns. Holding
+    # the operator's window for 3210 readiness bought nothing: the watcher is
+    # doing that wait anyway, and under load a first boot here has taken 78s.
+    if (-not (Wait-CrewSupervisorStarted)) {
+      throw 'No Crew supervisor started within 30s; 3210 has nothing watching it.'
+    }
+    $crew = $services | Where-Object { $_.CrewOwned } | Select-Object -First 1
+    $health = if ($crew) { Get-HealthState $crew } else { $null }
+    if ($health -and $health.Ready) {
+      Write-LaunchLog 'Official frontend is on 3080; Crew is ready on 3210.'
+    } else {
+      Write-LaunchLog ('Official frontend is on 3080; the supervisor is bringing 3210 up in the background. Last health: {0}' -f $health.Error) 'WARN'
+    }
+    # Operator-facing summary rather than a log line: clicking Crew before 3210
+    # answers looks like a broken feature, so say that it is still coming up.
+    Write-Host ''
+    Write-Host 'DSH Crew: the frontend is on http://127.0.0.1:3080.' -ForegroundColor Green
+    if ($health -and $health.Ready) {
+      Write-Host 'Backend 3210 is ready.' -ForegroundColor Green
+    } else {
+      Write-Host 'Backend 3210 is still starting; Crew features appear once it answers.' -ForegroundColor Yellow
+    }
+    Write-Host ("Diagnostic log: {0}" -f $launcherLog) -ForegroundColor DarkGray
+  } else {
+    Ensure-CrewSupervisorRunning
   }
   Write-LaunchLog ('Launcher completed successfully in {0:n1}s.' -f ((Get-Date) - $startedAt).TotalSeconds)
   exit 0