mandrel 2.66.0 → 2.68.0

package/.agents/scripts/lib/temp-retention.js

@@ -1,6 +1,7 @@
 /**
  * Allowlisted auto-purge of spent temp artifacts: only a declared class's
- * entries are candidates; the rest are reported, never touched. Never throws
+ * entries are candidates; the rest are reported, never touched by the
+ * auto-purge (only `/clean-temp`'s operator-confirmed path). Never throws
  * — a failed purge must not fail a land, boot, or persist.
  */
 
@@ -13,6 +14,14 @@ import {
   tempRootFrom,
 } from './config/temp-paths.js';
 import { Logger } from './Logger.js';
+import {
+  KEEP_BASENAMES,
+  removeSparingKept,
+  safeReaddir,
+  sizeOf,
+} from './temp-removal.js';
+
+export { KEEP_BASENAMES };
 
 /**
  * Defaults for `delivery.tempRetention`; purge is on unless turned off.
@@ -26,6 +35,7 @@ export const TEMP_RETENTION_DEFAULTS = Object.freeze({
     validationEvidence: true,
     auditResults: true,
     planDirs: true,
+    scratch: true,
   }),
 });
 
@@ -33,12 +43,6 @@ export const PURGE_CLASS_NAMES = Object.freeze(
   Object.keys(TEMP_RETENTION_DEFAULTS.classes),
 );
 
-/**
- * Never deleted, re-checked at the deletion site: `signals.ndjson` is read
- * long after merge and its loss is silent and unrecoverable.
- */
-export const KEEP_BASENAMES = Object.freeze(['signals.ndjson']);
-
 /** Explicit allowlist: an untaught file in a Story dir is kept. */
 const STORY_EVIDENCE_BASENAMES = Object.freeze([
   'validation-evidence.json',
@@ -49,6 +53,9 @@ const STORY_EVIDENCE_BASENAMES = Object.freeze([
 /** Framework-owned, never purged (`*.lock` files are also skipped). */
 const RESERVED_TOP_LEVEL = Object.freeze(['qa', 'cache']);
 
+/** Agent-authored scratch: `scratch/story-<id>/` or any other child. */
+const SCRATCH_DIRNAME = 'scratch';
+
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
 const STORY_DIR_PATTERN = /^story-(\d+)$/;
@@ -77,50 +84,6 @@ export function resolveTempRetention(config) {
   };
 }
 
-/**
- * `readdir` yielding `[]` for an absent or unreadable directory.
- *
- * @param {typeof fsPromises} fsp
- * @param {string} dir
- * @returns {Promise<import('node:fs').Dirent[]>}
- */
-async function safeReaddir(fsp, dir) {
-  try {
-    return await fsp.readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Recursive byte total; a vanished child is skipped.
- *
- * @param {typeof fsPromises} fsp
- * @param {string} target
- * @returns {Promise<number>}
- */
-async function sizeOf(fsp, target) {
-  let total = 0;
-  const stack = [target];
-  while (stack.length > 0) {
-    const current = stack.pop();
-    let stats;
-    try {
-      stats = await fsp.stat(current);
-    } catch {
-      continue;
-    }
-    if (!stats.isDirectory()) {
-      total += stats.size;
-      continue;
-    }
-    for (const child of await safeReaddir(fsp, current)) {
-      stack.push(path.join(current, child.name));
-    }
-  }
-  return total;
-}
-
 /**
  * One classified entry. `mtimeMs` is the entry's own mtime, not the newest
  * beneath it; widening it would change when an abandoned dir becomes eligible.
@@ -257,13 +220,44 @@ async function scanPlanDirs(tempRoot, fsp) {
   return entries;
 }
 
+/**
+ * `<tempRoot>/scratch/*`: `story-<id>/` is Story-keyed, anything else is
+ * age-floored — the one place an agent's ad-hoc files are reapable.
+ */
+async function scanScratch(tempRoot, fsp) {
+  const dir = path.join(tempRoot, SCRATCH_DIRNAME);
+  const entries = [];
+  for (const dirent of await safeReaddir(fsp, dir)) {
+    const match = dirent.isDirectory()
+      ? STORY_DIR_PATTERN.exec(dirent.name)
+      : null;
+    const entry = await makeEntry(
+      fsp,
+      path.join(dir, dirent.name),
+      'scratch',
+      match ? Number(match[1]) : null,
+    );
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+
 const SCANNERS = Object.freeze({
   orchestrationLogs: scanOrchestrationLogs,
   validationEvidence: scanValidationEvidence,
   auditResults: scanAuditResults,
   planDirs: scanPlanDirs,
+  scratch: scanScratch,
 });
 
+/** Fixed top-level dirs a class scanner walks. */
+const CLASS_OWNED_DIRNAMES = Object.freeze([
+  ORCHESTRATION_DIRNAME,
+  'standalone',
+  'audits',
+  SCRATCH_DIRNAME,
+]);
+
 /**
  * Keep in lockstep with the scanners: an entry no class walks must surface
  * as unrecognized.
@@ -273,29 +267,49 @@ const SCANNERS = Object.freeze({
  */
 function isClassOwnedTopLevel(name) {
   return (
-    name === ORCHESTRATION_DIRNAME ||
-    name === 'standalone' ||
-    name === 'audits' ||
+    CLASS_OWNED_DIRNAMES.includes(name) ||
     name.startsWith('plan-') ||
     RUN_DIR_PATTERN.test(name)
   );
 }
 
 /**
- * Unclaimed, non-reserved top-level entries: reported with sizes, never deleted.
+ * Top-level names no path may ever delete: the reserved trees, lock files,
+ * and the never-purged basenames.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isReservedTopLevel(name) {
+  return (
+    RESERVED_TOP_LEVEL.includes(name) ||
+    name.endsWith('.lock') ||
+    KEEP_BASENAMES.includes(name)
+  );
+}
+
+/**
+ * Unclaimed, non-reserved top-level entries: reported with sizes and the
+ * entry's own mtime. The auto-purge never deletes one; only an operator-
+ * confirmed `purgeUnrecognizedEntries` call does.
  *
  * @param {string} tempRoot
  * @param {typeof fsPromises} fsp
- * @returns {Promise<Array<{ path: string, bytes: number }>>}
+ * @returns {Promise<Array<{ path: string, bytes: number, mtimeMs: number }>>}
  */
 async function collectUnrecognized(tempRoot, fsp) {
   const found = [];
   for (const dirent of await safeReaddir(fsp, tempRoot)) {
     const { name } = dirent;
-    if (isClassOwnedTopLevel(name)) continue;
-    if (RESERVED_TOP_LEVEL.includes(name) || name.endsWith('.lock')) continue;
-    const target = path.join(tempRoot, name);
-    found.push({ path: target, bytes: await sizeOf(fsp, target) });
+    if (isClassOwnedTopLevel(name) || isReservedTopLevel(name)) continue;
+    const entry = await makeEntry(fsp, path.join(tempRoot, name), null, null);
+    if (entry) {
+      found.push({
+        path: entry.path,
+        bytes: entry.bytes,
+        mtimeMs: entry.mtimeMs,
+      });
+    }
   }
   return found;
 }
@@ -304,7 +318,7 @@ async function collectUnrecognized(tempRoot, fsp) {
  * Classify a temp tree without deleting anything.
  *
  * @param {{ config?: object, tempRoot?: string, fsp?: typeof fsPromises }} [args]
- * @returns {Promise<{ tempRoot: string, entries: object[], unrecognized: Array<{ path: string, bytes: number }> }>}
+ * @returns {Promise<{ tempRoot: string, entries: object[], unrecognized: Array<{ path: string, bytes: number, mtimeMs: number }> }>}
  */
 export async function collectTempEntries({
   config,
@@ -353,6 +367,7 @@ function isPurgeable(entry, ctx) {
  * @param {typeof fsPromises} [args.fsp]
  * @param {{ info: Function }} [args.logger]
  * @param {string} [args.label]
+ * @param {boolean} [args.dryRun] Report what would go; delete nothing.
  * @returns {Promise<object>} Result envelope; never throws.
  */
 async function purgeTempArtifacts({
@@ -366,6 +381,7 @@ async function purgeTempArtifacts({
   fsp = fsPromises,
   logger = Logger,
   label = 'temp-retention',
+  dryRun = false,
 } = {}) {
   const policy = resolveTempRetention(config);
   const base = {
@@ -402,22 +418,55 @@ async function purgeTempArtifacts({
       if (entry.keep) result.kept.push(entry.path);
       continue;
     }
-    try {
-      await fsp.rm(entry.path, { recursive: true, force: true });
-      result.purged.push({ path: entry.path, bytes: entry.bytes });
-      result.bytesReclaimed += entry.bytes;
-    } catch (err) {
-      result.errors.push(`${entry.path}: ${String(err?.message ?? err)}`);
-    }
+    await purgeOne(fsp, entry, result, dryRun);
   }
 
-  if (result.purged.length > 0) {
-    logger?.info?.(
-      `[${label}] purged ${result.purged.length} spent temp artifact(s), ` +
-        `reclaimed ${formatBytes(result.bytesReclaimed)} under ${result.tempRoot}.`,
+  if (!dryRun) reportPurge(logger, label, result);
+  return result;
+}
+
+/**
+ * One summary line for a purge that deleted something.
+ *
+ * @param {{ info?: Function }|undefined} logger
+ * @param {string} label
+ * @param {object} result
+ */
+function reportPurge(logger, label, result) {
+  if (result.purged.length === 0) return;
+  logger?.info?.(
+    `[${label}] purged ${result.purged.length} spent temp artifact(s), ` +
+      `reclaimed ${formatBytes(result.bytesReclaimed)} under ${result.tempRoot}.`,
+  );
+}
+
+/**
+ * Remove (or, on a dry run, only record) one purgeable entry into `result`.
+ *
+ * @param {typeof fsPromises} fsp
+ * @param {{ path: string, bytes: number }} entry
+ * @param {object} result Mutated in place.
+ * @param {boolean} dryRun
+ * @returns {Promise<void>}
+ */
+async function purgeOne(fsp, entry, result, dryRun) {
+  if (dryRun) {
+    result.purged.push({ path: entry.path, bytes: entry.bytes });
+    result.bytesReclaimed += entry.bytes;
+    return;
+  }
+  try {
+    const { bytes, kept } = await removeSparingKept(
+      fsp,
+      entry.path,
+      entry.bytes,
     );
+    result.kept.push(...kept);
+    result.purged.push({ path: entry.path, bytes });
+    result.bytesReclaimed += bytes;
+  } catch (err) {
+    result.errors.push(`${entry.path}: ${String(err?.message ?? err)}`);
   }
-  return result;
 }
 
 /**

package/.agents/scripts/lib/wave-runner/cross-run-overlap.js

@@ -0,0 +1,120 @@
+/**
+ * Advisory report of probed Stories whose declared footprint shares a
+ * concrete path with a Story another session has in flight. Never feeds
+ * selection, ordering or the exit code.
+ *
+ * @module lib/wave-runner/cross-run-overlap
+ */
+
+import { TYPE_LABELS } from '../label-constants.js';
+import { storyFootprintPaths } from '../orchestration/resolve-stories.js';
+import { currentOwner } from '../orchestration/ticket-lease.js';
+import { detectCollision } from './footprint.js';
+import { classifyStory, storyIdOf } from './ready-set.js';
+
+/**
+ * One labelled list query. Never rejects, so a failed read reports
+ * "unavailable" instead of an empty list.
+ *
+ * @param {object} provider
+ * @returns {Promise<{ tickets?: object[], error?: string }>}
+ */
+async function listOpenStories(provider) {
+  if (typeof provider?.listTicketsByLabel !== 'function') {
+    return { error: 'the provider cannot list issues by label' };
+  }
+  try {
+    const tickets = await provider.listTicketsByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.STORY,
+    });
+    return { tickets: Array.isArray(tickets) ? tickets : [] };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+/**
+ * @param {object[]} tickets
+ * @param {Set<number>} inSetIds
+ * @returns {Array<{id: number, files: string[], holder: string|null}>}
+ */
+function outsideInFlight(tickets, inSetIds) {
+  const outside = [];
+  for (const ticket of tickets) {
+    const id = storyIdOf(ticket);
+    if (id === null || inSetIds.has(id)) continue;
+    if (classifyStory(ticket) !== 'executing') continue;
+    outside.push({
+      id,
+      files: storyFootprintPaths(ticket.body, id),
+      holder: currentOwner(ticket.assignees),
+    });
+  }
+  return outside;
+}
+
+/**
+ * The reservation guard's `concreteOnly` rule, so advisory and guard never
+ * disagree: a glob or the UNKNOWN sentinel reports nothing.
+ *
+ * @param {Array<{id: number}>} probed
+ * @param {Array<{id: number, holder: string|null}>} outside
+ * @returns {object[]}
+ */
+function findCrossRunOverlaps(probed, outside) {
+  const overlaps = [];
+  for (const rec of probed) {
+    for (const other of outside) {
+      const hit = detectCollision(rec, other, { concreteOnly: true });
+      if (!hit) continue;
+      overlaps.push({
+        id: rec.id,
+        otherId: other.id,
+        holder: other.holder,
+        paths: hit.paths,
+      });
+    }
+  }
+  return overlaps;
+}
+
+/**
+ * @param {{ tickets?: object[], error?: string }} listing
+ * @param {object[]} nodes
+ * @param {Set<number>} inSetIds
+ * @returns {object}
+ */
+function buildReport(listing, nodes, inSetIds) {
+  if (listing.error) {
+    return {
+      crossRunOverlapProbe: 'unavailable',
+      crossRunOverlapProbeReason: `Could not list in-flight Stories outside this run: ${listing.error}`,
+    };
+  }
+  const candidates = nodes.filter((node) => {
+    const cls = classifyStory(node);
+    return cls === 'ready' || cls === 'executing';
+  });
+  return {
+    crossRunOverlaps: findCrossRunOverlaps(
+      candidates,
+      outsideInFlight(listing.tickets, inSetIds),
+    ),
+  };
+}
+
+/**
+ * Starts the read now so it overlaps the per-Story reads; probed-set Stories
+ * are excluded (their overlap is the ready-set guard's job).
+ *
+ * @param {object} provider
+ * @returns {{ report: (nodes: object[]) => Promise<object> }}
+ */
+export function startCrossRunProbe(provider) {
+  const listing = listOpenStories(provider);
+  return {
+    report: async (nodes) =>
+      buildReport(await listing, nodes, new Set(nodes.map((n) => n.id))),
+  };
+}

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -19,6 +19,7 @@ import {
   currentOwner,
   normalizeOperatorHandle,
 } from '../orchestration/ticket-lease.js';
+import { startCrossRunProbe } from './cross-run-overlap.js';
 import { classifyStory, storyIdOf } from './ready-set.js';
 
 /**
@@ -143,7 +144,8 @@ export function createProbeContext({
  *   inFlight: number,
  *   blockedIds: number[],
  *   stalledDispatch: number[],
- *   foreignHeld: Array<{id: number, holder: string}>
+ *   foreignHeld: Array<{id: number, holder: string}>,
+ *   crossRunOverlaps?: object[]
  * }>}
  */
 export async function probeLiveState({
@@ -156,6 +158,7 @@ export async function probeLiveState({
   self,
   warn,
 }) {
+  const crossRun = startCrossRunProbe(provider);
   // The `agent::*` guard is an admission check; a just-dispatched Story is
   // legitimately unlabelled until init flips it, so a per-beat probe allows it.
   const stories = await fetchStories(provider, ids, { allowUnlabelled: true });
@@ -207,6 +210,7 @@ export async function probeLiveState({
       .filter((id) => !foreignHeld.has(id))
       .sort((a, b) => a - b),
     foreignHeld: [...foreignHeld].map(([id, holder]) => ({ id, holder })),
+    ...(await crossRun.report(nodes)),
   };
 }
 

package/.agents/scripts/lib/worktree/canonical-path.js

@@ -0,0 +1,34 @@
+/**
+ * worktree/canonical-path.js — the on-disk identity of a path, for every
+ * worktree identity and containment comparison.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * `realpathSync.native` resolves symlinks (macOS `/var` ↔ `/private/var`) and
+ * expands Windows 8.3 short names (`RUNNER~1` ↔ `runneradmin`) — `git
+ * worktree list` reports the long form while `os.tmpdir()` / `process.cwd()`
+ * may carry the short one. A path that no longer exists canonicalises its
+ * nearest existing ancestor and re-appends the rest.
+ *
+ * @param {string} p
+ * @param {{ realpath?: (p: string) => string }} [deps]
+ * @returns {string}
+ */
+export function canonicalPath(p, { realpath = fs.realpathSync.native } = {}) {
+  const resolved = path.resolve(p);
+  const tail = [];
+  let current = resolved;
+  for (;;) {
+    try {
+      return path.join(realpath(current), ...tail);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return resolved;
+      tail.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}

package/.agents/scripts/lib/worktree/lifecycle/reap.js

@@ -7,6 +7,7 @@
 import fs from 'node:fs';
 import { rm as fsPromisesRm } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
+import { canonicalPath } from '../canonical-path.js';
 import { isInsideWorktree, samePath } from '../inspector.js';
 import { sleepSync } from '../node-modules-strategy.js';
 import { checkMergeReachability } from './merge-reachability.js';
@@ -441,15 +442,25 @@ function runningCodePaths() {
  * The running-code path inside `wtPath`, or `null`. Reaping the tree the
  * running script was loaded from kills the process later, at its first lazy
  * read or dynamic `import()`; refusing only defers the tree to the next sweep.
+ * Shared by every reaper (close, the boot worktree sweep, `/clean-worktrees`).
+ * Both sides are canonicalised first: a short-name or symlinked spelling of
+ * the same tree must still be recognised.
  *
- * @param {object} ctx
+ * @param {{ platform?: string }} ctx
  * @param {string} wtPath
+ * @param {string[]} [extraPaths] Further paths to guard (e.g. `process.cwd()`).
  * @returns {string|null}
  */
-function findRunningCodeInside(ctx, wtPath) {
+export function findRunningCodeInside(ctx, wtPath, extraPaths = []) {
+  const guarded = [...runningCodePaths(), ...extraPaths];
+  const target = canonicalPath(wtPath);
   return (
-    runningCodePaths().find((p) => isInsideWorktree(p, wtPath, ctx.platform)) ??
-    null
+    guarded.find(
+      (p) =>
+        typeof p === 'string' &&
+        p !== '' &&
+        isInsideWorktree(canonicalPath(p), target, ctx.platform),
+    ) ?? null
   );
 }