@ran-sh/dsh-crew 1.10.0 → 1.10.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"

package/package.json

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

package/src/dsh-cli-runtime.mjs

@@ -11,6 +11,7 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   realpathSync,
   renameSync,
@@ -528,9 +529,21 @@ async function rollbackRuntimeSwap({ liveRoot, prevRoot, stopOwned, startOwned,
       return recovery;
     }
   }
-  try { rmSync(liveRoot, { recursive: true, force: true }); } catch {}
   try {
-    if (existsSync(prevRoot)) { rename(prevRoot, liveRoot); recovery.restore = true; }
+    rmSync(liveRoot, { recursive: true, force: true });
+  } catch (error) {
+    // A failed removal must stop the recovery. Swallowing it left the window
+    // open: the restore was attempted over whatever remained, and
+    // `startOwned()` ran regardless — so a tree that could not be removed was
+    // then asked to start again, which on Windows is exactly the case where
+    // live handles blocked the removal.
+    recovery.removeError = String(error?.message ?? error);
+    recovery.ok = false;
+    return recovery;
+  }
+  try {
+    if (!existsSync(prevRoot)) recovery.restoreError = `previous runtime is missing at ${prevRoot}`;
+    else { rename(prevRoot, liveRoot); recovery.restore = true; }
   } catch (error) {
     recovery.restoreError = String(error?.message ?? error);
   }
@@ -538,6 +551,14 @@ async function rollbackRuntimeSwap({ liveRoot, prevRoot, stopOwned, startOwned,
     recovery.ok = recovery.restore === true;
     return recovery;
   }
+  // Restart only on positive proof that the prior runtime is the tree now at the
+  // live root. Starting without it would run the failed candidate again, or
+  // nothing at all, and report it as a recovery.
+  if (recovery.restore !== true || !existsSync(liveRoot)) {
+    recovery.restartSkipped = 'the previous runtime was not restored';
+    recovery.ok = false;
+    return recovery;
+  }
   try {
     const restarted = await startOwned();
     recovery.restart = restarted?.ok === true;
@@ -551,6 +572,8 @@ async function rollbackRuntimeSwap({ liveRoot, prevRoot, stopOwned, startOwned,
 
 // ---- retained runtime cohorts -------------------------------------------------
 
+const DISPLACED_RUNTIME_PREFIX = 'runtime-displaced-';
+
 function retainedRuntimesRoot({ home }) {
   return join(crewDshHome({ home }), RETAINED_RUNTIMES_DIRNAME);
 }
@@ -572,12 +595,22 @@ function runtimeTreeVersion(root, read = readFileSync) {
 // Best-effort retention of the swapped-out prior runtime tree. Never throws
 // and never fails the caller: retention is an optimization for offline
 // rollback, not a correctness requirement of the migration itself.
-function retainPriorRuntime({ home, prevRoot, rename = renameSync }) {
+/**
+ * Retain a parked runtime tree under the version it ships.
+ *
+ * `removeUnreadable` exists for one caller: the rollback rotation, where the
+ * parked tree is the ONLY copy of the cohort just displaced. There, failing to
+ * read its version is not a reason to delete it — that would destroy the very
+ * copy the rotation exists to keep — so it stays parked and is found later by
+ * `findRetainedRuntime`. The forward migration path keeps the default, where an
+ * unreadable tree really is junk.
+ */
+function retainPriorRuntime({ home, prevRoot, rename = renameSync, removeUnreadable = true }) {
   try {
     if (!existsSync(prevRoot)) return { ok: true, retained: false };
     const version = runtimeTreeVersion(prevRoot);
     if (!version) {
-      // No version to key retention on; the tree is unreadable junk.
+      if (!removeUnreadable) return { ok: false, retained: false, prevRoot, error: 'parked cohort version unreadable; left in place' };
       try { rmSync(prevRoot, { recursive: true, force: true }); } catch {}
       return { ok: true, retained: false, reason: 'prior tree version unreadable; removed' };
     }
@@ -601,9 +634,24 @@ function retainPriorRuntime({ home, prevRoot, rename = renameSync }) {
 export function findRetainedRuntime({ home = homedir(), version, exists = existsSync, read = readFileSync } = {}) {
   if (typeof version !== 'string' || version.length === 0) return null;
   const dir = retainedRuntimeDir({ home, version });
-  if (!exists(dir)) return null;
-  if (runtimeTreeVersion(dir, read) !== version) return null;
-  return dir;
+  if (exists(dir) && runtimeTreeVersion(dir, read) === version) return dir;
+  // A rotation whose retain step failed leaves the displaced cohort parked in the
+  // harness home. It is a complete, valid copy of that cohort, so it is found
+  // here rather than being written off: otherwise a later offline rollback to
+  // that version reports RETAINED_MISSING while the tree sits on disk.
+  return findDisplacedRuntime({ home, version, exists, read });
+}
+
+function findDisplacedRuntime({ home, version, exists = existsSync, read = readFileSync }) {
+  let names;
+  try { names = readdirSync(crewDshHome({ home })); } catch { return null; }
+  for (const name of names) {
+    if (!name.startsWith(DISPLACED_RUNTIME_PREFIX)) continue;
+    const dir = join(crewDshHome({ home }), name);
+    if (!exists(dir)) continue;
+    if (runtimeTreeVersion(dir, read) === version) return dir;
+  }
+  return null;
 }
 
 // Offline cohort restore for cross-cohort rollback: move the retained tree
@@ -642,14 +690,34 @@ export async function restoreRetainedRuntime({
   if (!stop.ok) {
     return { ok: false, code: stop.code ?? 'DSH_RUNTIME_STOP_FAILED', error: stop.error ?? 'could not stop owned 3210' };
   }
+  // Park the displaced cohort instead of deleting it. Deleting it was what made a
+  // second rollback impossible: after B→A the B tree was gone, so a later A→B
+  // found no retained B. Retention has to rotate, like the forward path does.
+  const parked = join(crewDshHome({ home }), `${DISPLACED_RUNTIME_PREFIX}${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`);
+  let parkedLive = false;
+  try {
+    if (existsSync(liveRoot)) { rename(liveRoot, parked); parkedLive = true; }
+  } catch (error) {
+    return { ok: false, code: 'DSH_RUNTIME_PARK_FAILED', error: String(error?.message ?? error) };
+  }
   try {
-    if (existsSync(liveRoot)) rmSync(liveRoot, { recursive: true, force: true });
     rename(retained, liveRoot);
   } catch (error) {
-    // Restore the pre-existing live tree is impossible (it was replaced only
-    // on success above); report and let the caller reconcile.
+    // Put the displaced tree back: leaving the live root empty because a rename
+    // failed would take a working runtime down for nothing.
+    try { if (parkedLive && !existsSync(liveRoot)) rename(parked, liveRoot); } catch { /* reported below */ }
     return { ok: false, code: 'DSH_RUNTIME_RESTORE_SWAP_FAILED', error: String(error?.message ?? error) };
   }
+  // The cohort just displaced becomes the retained one, so the version this
+  // restore moved away from can still be rolled back to. This parked tree is the
+  // only copy of that cohort, so an unreadable version keeps it rather than
+  // deleting it, and a failure is surfaced instead of passing as a clean restore.
+  const rotated = parkedLive
+    ? retainPriorRuntime({ home, prevRoot: parked, rename, removeUnreadable: false })
+    : { ok: true, retained: false };
+  if (parkedLive && rotated.ok === false) {
+    log(`! could not retain the displaced runtime cohort; it remains at ${parked}: ${rotated.error ?? ''}`);
+  }
   if (prepareOnly) {
     log(`- runtime tree prepared offline from retained tree (@${version}); process not started`);
     return { ok: true, version, liveRoot, prepared: true };

package/src/history/service.mjs

@@ -8,7 +8,12 @@ import { readHistoryState, writeHistoryState, historyPending, publicHistoryState
 import { readSessionOrigins } from '../session-origins.mjs';
 import { defaultWorktreeRoot } from '../workspace-isolation.mjs';
 
-export function createHistoryService({ crewRoot, agents, persistence, runtimeId, launch, now = Date.now }) {
+// `readOrigins` is injectable because the provenance ledger it reads by default
+// is machine-global, and the plan revision hashes the whole set: anything that
+// appends to that file between a preview and its execute invalidates the plan.
+// That is correct in production, where the ledger is this machine's own record,
+// but a caller that cannot control the ledger cannot control its own revisions.
+export function createHistoryService({ crewRoot, agents, persistence, runtimeId, launch, now = Date.now, readOrigins = readSessionOrigins }) {
   const gate = installHistoryAdmissionGate(agents, () => historyPending(crewRoot));
   const plans = new Map();
   let entering = false;
@@ -67,7 +72,7 @@ export function createHistoryService({ crewRoot, agents, persistence, runtimeId,
     });
     // A retained child keeps its ancestor chain; do not leave a newer fork orphaned.
     const workspaces = Object.entries(store.tables.workspaces).map(([id, row]) => ({ id, ...row }));
-    const crewSessionIds = [...readSessionOrigins()];
+    const crewSessionIds = [...readOrigins()];
     const crewSet = new Set(crewSessionIds);
     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

package/src/hub/entry.mjs

@@ -10,7 +10,7 @@
 import { apply as applyHub, inject, name, WorkerRegistry } from './index.mjs';
 import { getHubRuntimeIdentity } from '../runtime-identity.mjs';
 import { getProcessAdaptiveHealthStore } from '../adaptive-routing.mjs';
-import { claimReleaseInUse } from '../release-in-use.mjs';
+import { claimReleaseInUse, clearReleaseClaim } from '../release-in-use.mjs';
 
 const RUNTIME_PATH = '/_dsh/dsh-crew/runtime';
 const ADAPTIVE_OBSERVER_INSTALLED = Symbol.for('@ran-sh/dsh-crew/adaptive-observer-installed');
@@ -97,8 +97,37 @@ export async function apply(ctx) {
   // modules lazily with a cache-busting query, so deleting the release under a
   // running process would break those routes with no way to recover but a
   // restart. Retention reads these claims and leaves a live release alone.
-  claimReleaseInUse();
-  registerRuntimeEndpoint(ctx);
-  installAdaptiveHealthObserver();
-  return applyHub(ctx);
+  //
+  // A claim that could not be written is worth saying out loud: retention cannot
+  // see an unclaimed release, so this process is then the one that a later update
+  // may delete from under itself.
+  const claimFile = claimReleaseInUse();
+  if (!claimFile) {
+    ctx.logger?.warn?.('dsh-crew: could not record this release as in use; a later update may prune it while this Hub is running');
+  }
+  try {
+    registerRuntimeEndpoint(ctx);
+    installAdaptiveHealthObserver();
+    const disposeHub = await applyHub(ctx);
+    // Release the claim on disposal, and only once teardown has actually
+    // finished: clearing it first would say "this release is unused" while the
+    // Hub is still running. Nothing else may remove a claim file — the reader
+    // deliberately never unlinks one, because it cannot tell its object from a
+    // successor published at the same name — but the process that owns a claim
+    // may remove its own, and it removes *this* claim rather than any other this
+    // process happens to hold.
+    return async () => {
+      try { if (typeof disposeHub === 'function') await disposeHub(); }
+      // Only a claim this mount actually holds. A null handle means the claim was
+      // never acquired, and clearing something anyway could remove a sibling
+      // mount's protection.
+      finally { if (claimFile) { try { clearReleaseClaim({ file: claimFile }); } catch { /* best effort */ } } }
+    };
+  } catch (error) {
+    // No disposer will ever be returned for a failed mount, so the claim has to
+    // be released here or the release stays pinned by a process that never
+    // provided anything.
+    if (claimFile) { try { clearReleaseClaim({ file: claimFile }); } catch { /* best effort */ } }
+    throw error;
+  }
 }

package/src/install/npx-lifecycle.mjs

@@ -42,7 +42,7 @@ import { homedir } from 'node:os';
 import * as realInstaller from './install.mjs';
 import { samePayloadContent, capturePayloadContent } from './payload-content.mjs';
 import { crewDshHome, crewProfileDir } from './install.mjs';
-import { liveReleaseClaims } from '../release-in-use.mjs';
+import { releaseClaimsState } from '../release-in-use.mjs';
 import { ensureCrewDshRuntime, ensureCrewPluginRegistration, removeCrewPluginRegistration, migrateCrewDshRuntime, installDshInto, restoreRetainedRuntime, crewDshRuntimeRoot, payloadDshVersion, TARGET_DSH_VERSION } from '../dsh-cli-runtime.mjs';
 import {
   ensureOfficialWebIntegration,
@@ -161,21 +161,62 @@ export function readCurrentPointerState({ home = homedir() } = {}) {
     return { status: 'malformed', file, code: 'POINTER_FIELDS_INVALID' };
   }
   if (!isAbsolute(raw.path)) return { status: 'malformed', file, code: 'POINTER_PATH_NOT_ABSOLUTE' };
-  return { status: 'valid', file, pointer: raw };
+  // The pointer names the release that is live, and recovery acts on it. A path
+  // outside the managed releases directory is a corrupt or tampered pointer, not
+  // a release, so it fails closed exactly like the other malformed cases — and
+  // the canonical value is what the caller gets, so every later use acts on the
+  // path that was checked.
+  const canonical = managedReleasePath({ home, value: raw.path });
+  if (canonical === null) {
+    return { status: 'malformed', file, code: 'POINTER_PATH_OUTSIDE_RELEASES' };
+  }
+  return { status: 'valid', file, pointer: { ...raw, path: canonical } };
+}
+
+/**
+ * Resolve a path that a journal, the pointer, or recovery is about to act on, and
+ * refuse it unless it is inside the Crew-owned releases directory.
+ *
+ * An absolute path is not enough. Recovery recursively deletes the journal's
+ * candidate stage directory and moves the pointer's release, so a syntactically
+ * valid but corrupt or tampered journal naming any absolute path would grant
+ * delete authority over it — including the official `~/.dsh` tree this plugin is
+ * required never to touch. Containment is therefore checked before any read,
+ * write, delete or activation, and a path that fails it is treated exactly like
+ * a malformed journal: nothing is touched and the state is retained.
+ */
+export function managedReleasePath({ home = homedir(), value } = {}) {
+  if (typeof value !== 'string' || value.length === 0 || !isAbsolute(value)) return null;
+  const releases = realpathOr(resolve(crewReleasesDir({ home })));
+  const candidate = realpathOr(resolve(value));
+  // Resolve both sides before comparing: `..` segments and symlinks must not be
+  // able to leave the managed directory after the check.
+  const relative = relativeTo(releases, candidate);
+  if (relative === null || relative === '' || relative.startsWith('..') || isAbsolute(relative)) return null;
+  return candidate;
 }
 
-function validJournalRelease(value) {
+function realpathOr(path) {
+  try { return realpathSync(path); } catch { return path; }
+}
+
+/** `path` expressed relative to `from`, or null when they are on different roots. */
+function relativeTo(from, path) {
+  return relative(from, path);
+}
+
+function validJournalRelease({ home, value }) {
   return !!value && typeof value === 'object'
     && typeof value.name === 'string' && value.name.length > 0
     && typeof value.version === 'string' && value.version.length > 0
-    && typeof value.path === 'string' && isAbsolute(value.path);
+    && managedReleasePath({ home, value: value.path }) !== null;
 }
 
-function validJournalCandidate(value) {
+function validJournalCandidate({ home, value }) {
   return !!value && typeof value === 'object'
     && typeof value.name === 'string' && value.name.length > 0
     && typeof value.version === 'string' && value.version.length > 0
-    && typeof value.stageDir === 'string' && isAbsolute(value.stageDir);
+    && managedReleasePath({ home, value: value.stageDir }) !== null;
 }
 
 function writeFileAtomic(file, content) {
@@ -359,13 +400,23 @@ function readUpdateJournal({ home = homedir() } = {}) {
     return { malformed: true, file };
   }
   // Full schema check: a semantically broken journal (null candidate,
-  // incomplete prior) must fail closed, never enter recovery.
-  if (!validJournalCandidate(raw.candidate)) {
+  // incomplete prior) must fail closed, never enter recovery. The paths are
+  // checked for containment too, because recovery deletes and moves them, and
+  // they are replaced with the canonical value that was checked so that every
+  // later use acts on the path that was validated rather than the string that
+  // happened to be written.
+  const canonicalCandidate = managedReleasePath({ home, value: raw.candidate?.stageDir });
+  if (!validJournalCandidate({ home, value: raw.candidate }) || canonicalCandidate === null) {
     return { malformed: true, file, code: 'JOURNAL_CANDIDATE_SCHEMA_INVALID' };
   }
-  if (raw.prior !== null && raw.prior !== undefined && !validJournalRelease(raw.prior)) {
-    return { malformed: true, file, code: 'JOURNAL_PRIOR_SCHEMA_INVALID' };
+  if (raw.prior !== null && raw.prior !== undefined) {
+    const canonicalPrior = managedReleasePath({ home, value: raw.prior?.path });
+    if (!validJournalRelease({ home, value: raw.prior }) || canonicalPrior === null) {
+      return { malformed: true, file, code: 'JOURNAL_PRIOR_SCHEMA_INVALID' };
+    }
+    raw = { ...raw, prior: { ...raw.prior, path: canonicalPrior } };
   }
+  raw = { ...raw, candidate: { ...raw.candidate, stageDir: canonicalCandidate } };
   return raw;
 }
 
@@ -554,7 +605,9 @@ export function reconcileUpdateJournal({ home = homedir(), log = () => {}, insta
     return { ok: false, code: 'POINTER_MALFORMED', file: pointerState.file, error: pointerState.code ?? 'pointer unreadable; refusing recovery' };
   }
   const pointer = pointerState.status === 'valid' ? pointerState.pointer : null;
-  const candidateDir = journal.candidate?.stageDir ?? null;
+  // Act on the canonical path that was validated, not the raw string that was
+  // written: the delete below is only as safe as the path it is handed.
+  const candidateDir = managedReleasePath({ home, value: journal.candidate?.stageDir ?? null });
   const candidateManifest = candidateDir && existsSync(candidateDir) ? readManifest(candidateDir) : null;
 
   // A coordinated-update journal MUST carry a runtime segment; recovery may
@@ -1084,14 +1137,26 @@ const STALE_INCOMPLETE_MS = 24 * 60 * 60 * 1000;
 function gcOldReleases({ home, keep = KEEP_RELEASES, protect = null }) {
   const pointer = readCurrentPointer({ home });
   const releasesDir = crewReleasesDir({ home });
-  if (!existsSync(releasesDir)) return;
+  if (!existsSync(releasesDir)) return [];
   const removed = [];
   // A running Hub keeps executing the release it started from and re-reads
   // several modules from disk on every request, so removing that release breaks
   // those routes with no recovery but a restart. Protect what live processes
   // claim, not just what the pointer names.
-  const claimed = liveReleaseClaims({ home }).map((dir) => resolve(dir));
-  const live = new Set([...(protect ? [resolve(protect)] : []), ...claimed]);
+  //
+  // Liveness has to be known, not merely unrefuted: if the claim directory
+  // cannot be read, "no live claims" is an absence of evidence, and deleting on
+  // it reproduces the outage this protection exists to prevent. Pruning is
+  // optional and a skipped pass costs disk; guessing wrong costs a broken Hub.
+  const claims = releaseClaimsState({ home });
+  if (!claims.reliable) {
+    // Say so rather than passing over it in silence: nothing is pruned until the
+    // claim directory can be read again, and an operator who never hears about
+    // that finds out when the disk fills.
+    process.emitWarning(`dsh-crew: release liveness could not be read (${claims.error ?? 'unknown cause'}); skipping release pruning this pass`);
+    return removed;
+  }
+  const live = new Set([...(protect ? [resolve(protect)] : []), ...claims.live.map((dir) => resolve(dir))]);
   const dirs = readdirSync(releasesDir)
     .map((name) => join(releasesDir, name))
     .filter((dir) => (!pointer || dir !== pointer.path) && !live.has(resolve(dir)));

package/src/install/payload-content.mjs

@@ -74,12 +74,23 @@ export function capturePayloadContent(root, suppliedManifest) {
   } catch { return null; }
 }
 
-/** This digest covers first-party shipped files, not dependency tamper attestation. */
+/**
+ * This digest covers first-party shipped files, not dependency tamper attestation.
+ *
+ * The permission bits are part of it: the copy below writes each file with the
+ * mode captured from the source, so a payload whose `0644` became `0755` with
+ * identical bytes is not the same payload — it is the case where an intended
+ * permission repair would otherwise be skipped as already done.
+ */
 export function payloadContentDigest(root) {
   const snapshot = capturePayloadContent(root);
   if (!snapshot) return null;
-  const hashes = [...snapshot.files].map(([name, bytes]) => [name, createHash('sha256').update(bytes).digest('hex')]);
-  return createHash('sha256').update(JSON.stringify(hashes.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))).digest('hex');
+  const entries = [...snapshot.files].map(([name, bytes]) => [
+    name,
+    snapshot.modes.get(name) ?? null,
+    createHash('sha256').update(bytes).digest('hex'),
+  ]);
+  return createHash('sha256').update(JSON.stringify(entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))).digest('hex');
 }
 
 export function samePayloadContent(sourceRoot, installedRoot) {

package/src/release-in-use.mjs

@@ -16,13 +16,21 @@
 // release with a live claim. Liveness is decided by the pid, not by the file, so
 // a process that dies without cleaning up cannot pin a release forever.
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const IN_USE_DIRNAME = 'in-use';
 
+// A claim file is `<pid>.json` or `<pid>-<nonce>.json`. The PID alone is not
+// enough to identify a claim: two mounts inside one process would publish to the
+// same pathname, and whichever disposed first would remove the other's
+// protection. A claim is owned by the mount that wrote it, so it needs a name
+// that says which one that was.
+const CLAIM_NAME_RE = /^(\d+)(?:-[0-9a-f]+)?\.json$/;
+
 export function releaseInUseDir({ home = homedir() } = {}) {
   return join(home, '.config', 'dsh-crew', 'app', IN_USE_DIRNAME);
 }
@@ -55,8 +63,13 @@ function isAlive(pid) {
 
 /**
  * Record that this process is running `releasePath`. Best effort: failing to
- * claim must never stop the Hub from starting, because the cost of a missed
- * claim is a possible retention of one extra release.
+ * claim must never stop the Hub from starting.
+ *
+ * A null return is a real degradation, not a footnote. Retention cannot see a
+ * release that was never claimed, so an unclaimable release is one that a later
+ * update may delete from under this process — the 500-answering routes this
+ * module exists to prevent. Callers should surface it; `releaseClaimsState`
+ * gives retention the matching fail-closed signal.
  */
 export function claimReleaseInUse({ moduleUrl = import.meta.url, releasePath, home = homedir(), pid = process.pid, now = Date.now() } = {}) {
   try {
@@ -64,47 +77,122 @@ export function claimReleaseInUse({ moduleUrl = import.meta.url, releasePath, ho
     if (!target) return null;
     const dir = releaseInUseDir({ home });
     mkdirSync(dir, { recursive: true });
-    const file = join(dir, `${pid}.json`);
-    writeFileSync(file, JSON.stringify({ pid, release: resolve(target), claimed_at: now }) + '\n');
+    // The nonce makes this claim the property of this call. Clearing by PID would
+    // let one mount remove a sibling mount's only protection.
+    const nonce = randomBytes(8).toString('hex');
+    const file = join(dir, `${pid}-${nonce}.json`);
+    // Write then rename: a reader that lists the directory can otherwise see this
+    // filename while its JSON is still empty or half-written, and an unparseable
+    // claim is indistinguishable from a dead one.
+    const pending = `${file}.tmp`;
+    writeFileSync(pending, JSON.stringify({ pid, nonce, release: resolve(target), claimed_at: now }) + '\n');
+    renameSync(pending, file);
     return file;
   } catch { return null; }
 }
 
+/** The unbranded per-PID claim path, as written by releases before claims were per-mount. */
 export function releaseClaimFile({ home = homedir(), pid = process.pid } = {}) {
   return join(releaseInUseDir({ home }), `${pid}.json`);
 }
 
 export function releaseClaimInUse({ home = homedir(), pid = process.pid } = {}) {
-  const file = releaseClaimFile({ home, pid });
-  return existsSync(file) || false;
+  let names;
+  try { names = readdirSync(releaseInUseDir({ home })); } catch { return false; }
+  return names.some((name) => CLAIM_NAME_RE.exec(name)?.[1] === String(pid));
+}
+
+/**
+ * Remove the claim whose handle `claimReleaseInUse` returned.
+ *
+ * A missing handle is not permission to remove something: without one there is
+ * no way to know which claim this caller owns, and guessing by PID can remove a
+ * sibling mount's protection. Legacy unbranded claims are removed by
+ * `clearLegacyReleaseClaim`, which says so in its name.
+ */
+export function clearReleaseClaim({ file = null } = {}) {
+  if (!file) return false;
+  try { rmSync(file, { force: true }); return true; } catch { return false; }
 }
 
-export function clearReleaseClaim({ home = homedir(), pid = process.pid } = {}) {
+/**
+ * Remove the unbranded `<pid>.json` claim written by releases before claims were
+ * per-mount. Separate from `clearReleaseClaim` because it can take a claim this
+ * caller did not write, and that should never happen by falling through a
+ * missing argument.
+ */
+export function clearLegacyReleaseClaim({ home = homedir(), pid = process.pid } = {}) {
   try { rmSync(releaseClaimFile({ home, pid }), { force: true }); return true; } catch { return false; }
 }
 
 /**
- * Releases currently held by a live process. Dead claims are removed as they are
- * encountered, so the directory cannot accumulate stale files.
+ * Releases currently held by a live process, plus whether that answer is
+ * trustworthy.
+ *
+ * `reliable: false` means liveness could not be determined, so an empty `live`
+ * list is not evidence that nothing is running. A caller that deletes releases
+ * must treat unknown as "do not delete": reading an unreadable claim directory
+ * as "no claims" is exactly how a release disappears from under a running Hub,
+ * and the damage is to the process, not to the files.
+ *
+ * Nothing is deleted here. A claim is only ever a protection, so a reaper that
+ * unlinks one has to be certain the object it inspected is still the object it
+ * is removing — and it cannot be, because the pathname outlives the claim and a
+ * process restarting with a reused PID publishes a new file at the same one.
+ * Checking liveness and then unlinking is a check-then-act over a name, and
+ * losing that race deletes a live process's protection. Stale files therefore
+ * stay; a Hub clears its own claim on a clean shutdown, and one file per
+ * hard-killed process is not worth a race over a safety mechanism.
  */
-export function liveReleaseClaims({ home = homedir(), alive = isAlive } = {}) {
+export function releaseClaimsState({ home = homedir(), alive = isAlive } = {}) {
   const dir = releaseInUseDir({ home });
   let names;
-  // A state directory that is unreadable — or replaced by a file — must read as
-  // "no claims" rather than throwing: this runs inside install, and failing it
-  // would block an update over a problem that only affects pruning.
-  try { names = readdirSync(dir); } catch { return []; }
+  try { names = readdirSync(dir); } catch (error) {
+    // A directory that does not exist yet reliably holds no claims; any other
+    // failure — permissions, a file where the directory should be — does not.
+    if (error?.code === 'ENOENT') return { live: [], reliable: true };
+    return { live: [], reliable: false, error: String(error?.message ?? error) };
+  }
   const live = [];
+  let unknown = null;
   for (const name of names) {
     if (!name.endsWith('.json')) continue;
     const file = join(dir, name);
-    let record;
-    try { record = JSON.parse(readFileSync(file, 'utf8')); } catch { record = null; }
-    if (record && Number.isInteger(record.pid) && typeof record.release === 'string' && alive(record.pid)) {
-      live.push(resolve(record.release));
+    // The filename carries the PID, and the name is complete before any content
+    // exists — so a torn write still says whose claim it was, which is what
+    // keeps one old unusable file from disabling pruning forever.
+    const pidFromName = CLAIM_NAME_RE.exec(name) ? Number.parseInt(name, 10) : null;
+
+    let parsed = null;
+    try { parsed = JSON.parse(readFileSync(file, 'utf8')); } catch { parsed = null; }
+
+    const wellFormed = parsed && typeof parsed === 'object'
+      && Number.isInteger(parsed.pid) && parsed.pid > 0
+      && typeof parsed.release === 'string' && parsed.release !== ''
+      && parsed.pid === pidFromName;
+
+    if (wellFormed) {
+      // A well-formed claim for a process that is gone simply protects nothing;
+      // it is inert, not a reason to distrust the rest.
+      if (alive(parsed.pid)) live.push(resolve(parsed.release));
       continue;
     }
-    try { rmSync(file, { force: true }); } catch { /* best effort */ }
+
+    // Anything else is not evidence of a dead process. Syntax that happens to
+    // parse is not a schema: `{}` and `{"pid":123}` say nothing about liveness.
+    // The filename is the only identity left, and a claim whose named process is
+    // positively gone is inert for the same reason.
+    if (pidFromName !== null && !alive(pidFromName)) continue;
+    // No usable PID, or the PID may still be running. A reused PID is
+    // indistinguishable from the original here, so this stays unknown rather
+    // than guessing; that is a fail-closed condition, not a resolved one.
+    unknown ??= `unusable claim: ${file}`;
   }
-  return [...new Set(live)];
+  if (unknown) return { live: [...new Set(live)], reliable: false, error: unknown };
+  return { live: [...new Set(live)], reliable: true };
+}
+
+/** Releases currently held by a live process. See `releaseClaimsState`. */
+export function liveReleaseClaims(opts = {}) {
+  return releaseClaimsState(opts).live;
 }

package/src/runtime-identity.mjs

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