mandrel 1.57.0

package/.agents/scripts/lib/workspace-provisioner.js

@@ -0,0 +1,189 @@
+/**
+ * workspace-provisioner.js
+ *
+ * Central authority for populating a fresh worktree (or remote-runner checkout)
+ * with gitignored workspace files — by default `.env`, `.mcp.json`, and the
+ * operator's local-override files (`.agentrc.local.json`,
+ * `.agents/instructions.local.md`) — plus any other files declared in
+ * `.agentrc.json orchestration.workspaceFiles`. The local-override files are
+ * provisioned so a worktree-isolated agent honors the §1.E local-override
+ * contract (e.g. `github.operatorHandle`) rather than silently falling back to
+ * the committed `.agentrc.json` placeholders. Every caller that needs these
+ * files in a non-main checkout should go through this module; ad-hoc copy
+ * logic elsewhere in the codebase is a bug.
+ *
+ * Public API:
+ *   - `provision({ sourceRoot, targetWorktree, files?, logger? })` — copies
+ *     each listed file from source to target, skipping any that already exist
+ *     at the target. Returns `{ copied, skipped, missing }`.
+ *   - `verify({ worktree, files?, sourceRoot? })` — throws when a required
+ *     file is missing. When `sourceRoot` is passed, the error carries a
+ *     copy-ready remediation command the operator can run verbatim.
+ *   - `resolveWorkspaceFiles(orchestrationConfig)` — resolves the list honoring
+ *     the new `orchestration.workspaceFiles` key, the legacy
+ *     `orchestration.worktreeIsolation.bootstrapFiles`, and the default.
+ *   - `DEFAULT_WORKSPACE_FILES` — `['.env', '.mcp.json', '.agentrc.local.json',
+ *     '.agents/instructions.local.md']`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { NOOP_LOGGER } from './Logger.js';
+
+// Keep in sync with `WORKTREE_ISOLATION_DEFAULTS.bootstrapFiles` in
+// `./config/worktree-isolation.js`. The local-override files are listed even
+// though they are frequently absent — `provision()` skips missing sources and
+// `verify()` callers filter to files present at the source first, so a missing
+// override never fails a worktree create.
+export const DEFAULT_WORKSPACE_FILES = [
+  '.env',
+  '.mcp.json',
+  '.agentrc.local.json',
+  '.agents/instructions.local.md',
+];
+
+/**
+ * Resolve the list of workspace files to provision.
+ *
+ * Precedence: explicit `orchestration.workspaceFiles` → legacy
+ * `orchestration.worktreeIsolation.bootstrapFiles` → `DEFAULT_WORKSPACE_FILES`.
+ *
+ * @param {object} [orchestrationConfig]
+ * @returns {string[]}
+ */
+export function resolveWorkspaceFiles(orchestrationConfig) {
+  const cfg = orchestrationConfig ?? {};
+  if (Array.isArray(cfg.workspaceFiles)) return cfg.workspaceFiles.slice();
+  // Legacy `worktreeIsolation.bootstrapFiles` fallback — surviving callers:
+  // tests/lib/workspace-provisioner.test.js, tests/lib/worktree/bootstrapper.test.js,
+  // and consumer projects' `.agentrc.json` (config-schema still accepts it).
+  const legacy = cfg.worktreeIsolation?.bootstrapFiles;
+  if (Array.isArray(legacy)) return legacy.slice();
+  return DEFAULT_WORKSPACE_FILES.slice();
+}
+
+/**
+ * Validate a workspace-file name — must be relative, no `..`, no NULs, no
+ * absolute paths.
+ *
+ * @param {string} name
+ * @returns {string|null}  null on success, reason string on failure.
+ */
+function invalidNameReason(name) {
+  if (typeof name !== 'string' || name.length === 0) return 'empty';
+  const rel = path.normalize(name);
+  if (rel.startsWith('..') || path.isAbsolute(rel) || rel.includes('\0')) {
+    return 'traversal-or-absolute';
+  }
+  return null;
+}
+
+/**
+ * Copy configured workspace files from `sourceRoot` into `targetWorktree`.
+ * Existing target files are preserved (never overwritten). Missing sources are
+ * silently skipped and reported in the `missing` array.
+ *
+ * @param {object} opts
+ * @param {string} opts.sourceRoot     Absolute path to the main repo.
+ * @param {string} opts.targetWorktree Absolute path to the target worktree.
+ * @param {string[]} [opts.files]      File list; defaults to DEFAULT_WORKSPACE_FILES.
+ * @param {object} [opts.logger]       `{ info, warn, error }`.
+ * @returns {{ copied: string[], skipped: string[], missing: string[] }}
+ */
+export function provision({
+  sourceRoot,
+  targetWorktree,
+  files = DEFAULT_WORKSPACE_FILES,
+  logger = NOOP_LOGGER,
+}) {
+  if (!sourceRoot || typeof sourceRoot !== 'string') {
+    throw new Error('workspace-provisioner: sourceRoot is required');
+  }
+  if (!targetWorktree || typeof targetWorktree !== 'string') {
+    throw new Error('workspace-provisioner: targetWorktree is required');
+  }
+
+  const result = { copied: [], skipped: [], missing: [] };
+  if (!Array.isArray(files) || files.length === 0) return result;
+
+  for (const name of files) {
+    const reason = invalidNameReason(name);
+    if (reason) {
+      logger.warn(
+        `workspace-provisioner: skipped invalid name='${name}' (${reason})`,
+      );
+      continue;
+    }
+    const rel = path.normalize(name);
+    const src = path.join(sourceRoot, rel);
+    if (!fs.existsSync(src)) {
+      result.missing.push(rel);
+      continue;
+    }
+    const dst = path.join(targetWorktree, rel);
+    if (fs.existsSync(dst)) {
+      logger.info(
+        `workspace-provisioner: skipped path=${dst} (already exists)`,
+      );
+      result.skipped.push(rel);
+      continue;
+    }
+    try {
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.copyFileSync(src, dst);
+      logger.info(`workspace-provisioner: copied source=${src} target=${dst}`);
+      result.copied.push(rel);
+    } catch (err) {
+      logger.warn(
+        `workspace-provisioner: copy failed name=${name}: ${err.message}`,
+      );
+    }
+  }
+  return result;
+}
+
+/**
+ * Throw if any required workspace file is missing from `worktree`. Used as a
+ * runtime guard (called right after every worktree create in
+ * `story-init.js`) and as a test oracle.
+ *
+ * When `sourceRoot` is supplied, the thrown error carries the missing target
+ * path and an exact `cp`/`copy` command the operator can paste to remediate.
+ *
+ * @param {object} opts
+ * @param {string} opts.worktree
+ * @param {string[]} [opts.files]
+ * @param {string} [opts.sourceRoot] Main repo path; enables remediation hint.
+ */
+export function verify({
+  worktree,
+  files = DEFAULT_WORKSPACE_FILES,
+  sourceRoot,
+}) {
+  if (!worktree || typeof worktree !== 'string') {
+    throw new Error('workspace-provisioner: worktree is required');
+  }
+  const missing = [];
+  for (const name of files) {
+    if (invalidNameReason(name)) continue;
+    const rel = path.normalize(name);
+    const abs = path.join(worktree, rel);
+    if (!fs.existsSync(abs)) missing.push({ name, rel, abs });
+  }
+  if (missing.length === 0) return;
+
+  const namesList = missing.map((m) => m.name).join(', ');
+  const pathsList = missing.map((m) => m.abs).join(', ');
+  const lines = [
+    `workspace-provisioner: required workspace file(s) missing from ${worktree}: ${namesList}`,
+    `  missing path(s): ${pathsList}`,
+  ];
+  if (sourceRoot && typeof sourceRoot === 'string') {
+    const copyCmd = process.platform === 'win32' ? 'copy /Y' : 'cp';
+    for (const m of missing) {
+      const src = path.join(sourceRoot, m.rel);
+      lines.push(`  remediation: ${copyCmd} "${src}" "${m.abs}"`);
+    }
+  }
+  throw new Error(lines.join('\n'));
+}

package/.agents/scripts/lib/worktree/bootstrapper.js

@@ -0,0 +1,48 @@
+/**
+ * worktree/bootstrapper.js
+ *
+ * File-copy helpers that prepare a freshly added worktree for the agent
+ * (bootstrap files like `.env`). Under the npm-package distribution model
+ * `.agents/` is a materialized, tracked directory in every checkout, so there
+ * is no gitlink to scrub and no submodule snapshot to copy at create/reap time.
+ *
+ * All helpers receive an explicit `ctx` bag so they can be unit-tested without
+ * instantiating `WorktreeManager`.
+ */
+
+import { provision } from '../workspace-provisioner.js';
+
+/**
+ * Copy untracked bootstrap files (default `.env`) from the repo
+ * root into a freshly created worktree. Delegates to the central
+ * `WorkspaceProvisioner`; kept as a named export so existing call sites keep
+ * working.
+ *
+ * @param {{ repoRoot: string, config: { bootstrapFiles?: string[] }, logger: object }} ctx
+ * @param {string} wtPath
+ */
+export function copyBootstrapFiles(ctx, wtPath) {
+  const files = ctx.config?.bootstrapFiles;
+  if (!Array.isArray(files) || files.length === 0) return;
+  const logger = wrapBootstrapLogger(ctx.logger);
+  provision({
+    sourceRoot: ctx.repoRoot,
+    targetWorktree: wtPath,
+    files,
+    logger,
+  });
+}
+
+/**
+ * Translate provisioner log lines into the `worktree.bootstrap …` prefix that
+ * existing operators and log scrapers rely on.
+ */
+function wrapBootstrapLogger(inner) {
+  const rewrite = (msg) =>
+    String(msg).replace(/^workspace-provisioner:/, 'worktree.bootstrap');
+  return {
+    info: (m) => inner.info(rewrite(m)),
+    warn: (m) => inner.warn(rewrite(m)),
+    error: (m) => inner.error(rewrite(m)),
+  };
+}

package/.agents/scripts/lib/worktree/inspector.js

@@ -0,0 +1,140 @@
+/**
+ * worktree/inspector.js
+ *
+ * Read-only parsing and path helpers for the worktree subsystem. Pure-ish:
+ * callers inject `platform` and pass absolute paths explicitly. No fs
+ * mutation; no git invocation (parsing only). One log side-effect in
+ * `maybeWarnWindowsPath` via the injected logger.
+ */
+
+import path from 'node:path';
+import { parseStoryBranch } from '../git-utils.js';
+
+/**
+ * Parse `git worktree list --porcelain` output into records.
+ *
+ * Porcelain format: blank-line-separated blocks where each line is
+ * `key value` or a bare key (e.g. `bare`, `detached`).
+ *
+ * @param {string} raw
+ * @returns {Array<{ path: string, head: string|null, branch: string|null, bare: boolean, detached: boolean }>}
+ */
+export function parseWorktreePorcelain(raw) {
+  const out = [];
+  const blocks = raw.split(/\r?\n\r?\n/);
+  for (const block of blocks) {
+    const lines = block.split(/\r?\n/).filter(Boolean);
+    if (lines.length === 0) continue;
+    const rec = {
+      path: '',
+      head: null,
+      branch: null,
+      bare: false,
+      detached: false,
+    };
+    for (const line of lines) {
+      const sp = line.indexOf(' ');
+      const key = sp === -1 ? line : line.slice(0, sp);
+      const value = sp === -1 ? '' : line.slice(sp + 1);
+      switch (key) {
+        case 'worktree':
+          rec.path = value;
+          break;
+        case 'HEAD':
+          rec.head = value;
+          break;
+        case 'branch':
+          rec.branch = value.replace(/^refs\/heads\//, '');
+          break;
+        case 'bare':
+          rec.bare = true;
+          break;
+        case 'detached':
+          rec.detached = true;
+          break;
+      }
+    }
+    if (rec.path) out.push(rec);
+  }
+  return out;
+}
+
+/**
+ * Path equality that handles Windows case-insensitivity and path
+ * normalization differences.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @param {NodeJS.Platform} platform
+ * @returns {boolean}
+ */
+export function samePath(a, b, platform) {
+  const na = path.resolve(a);
+  const nb = path.resolve(b);
+  if (platform === 'win32') {
+    return na.toLowerCase() === nb.toLowerCase();
+  }
+  return na === nb;
+}
+
+/**
+ * Extract `<id>` from a `<worktreeRoot>/story-<id>` path, or `null` if the
+ * path is not a managed story worktree.
+ *
+ * @param {string} wtPath
+ * @param {string} worktreeRoot
+ * @returns {number|null}
+ */
+export function storyIdFromPath(wtPath, worktreeRoot) {
+  const resolved = path.resolve(wtPath);
+  const rel = path.relative(worktreeRoot, resolved);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return parseStoryBranch(rel);
+}
+
+/**
+ * True if `candidate` is the same path as `wtPath` or nested beneath it.
+ *
+ * @param {string} candidate
+ * @param {string} wtPath
+ * @param {NodeJS.Platform} platform
+ * @returns {boolean}
+ */
+export function isInsideWorktree(candidate, wtPath, platform) {
+  const resolvedCandidate = path.resolve(candidate);
+  const resolvedWt = path.resolve(wtPath);
+  if (samePath(resolvedCandidate, resolvedWt, platform)) return true;
+  const rel = path.relative(resolvedWt, resolvedCandidate);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+  return true;
+}
+
+/**
+ * Warn when the anticipated deepest path under a fresh worktree crosses the
+ * configured threshold on Windows. Returns the warning payload when a warning
+ * was emitted, or `null` otherwise.
+ *
+ * @param {{ platform: NodeJS.Platform, threshold?: number, logger: { warn: (m: string) => void } }} ctx
+ * @param {string} wtPath
+ * @returns {{ path: string, length: number, threshold: number } | null}
+ */
+export function maybeWarnWindowsPath(ctx, wtPath) {
+  if (ctx.platform !== 'win32') return null;
+  // Defense-in-depth: callers on the worktree-off branch never compute a
+  // worktree path, so this should never be invoked with a falsy `wtPath`.
+  // Guard anyway so a future refactor that drops the gating can't trigger
+  // an `undefined.length` crash here.
+  if (typeof wtPath !== 'string' || wtPath.length === 0) return null;
+  const threshold = ctx.threshold ?? 240;
+  // Approximate the deepest path an agent is likely to touch: worktree
+  // root + a conservative project-depth allowance. 80 chars covers the
+  // common case of `apps/<name>/src/<module>/<file>.ts` and similar
+  // monorepo layouts without requiring tech-stack config wiring.
+  const deepestAllowance = 80;
+  const estimated = wtPath.length + deepestAllowance;
+  if (estimated <= threshold) return null;
+  ctx.logger.warn(
+    `windows-long-path path=${wtPath} length=${wtPath.length} estimated=${estimated} threshold=${threshold}`,
+  );
+  return { path: wtPath, length: estimated, threshold };
+}

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

@@ -0,0 +1,118 @@
+/**
+ * worktree/lifecycle/creation.js
+ *
+ * `ensure` — idempotently provision `.worktrees/story-<id>/` on `branch`.
+ * Threads the `ctx` bag built by `WorktreeManager`; cross-cutting work
+ * (workspace bootstrap, Windows long-path warning) is supplied via callbacks
+ * on `ctx` so this submodule never reaches into `WorktreeManager` instance
+ * state directly.
+ */
+
+import fs from 'node:fs';
+import {
+  applyNodeModulesStrategy,
+  installDependencies,
+} from '../node-modules-strategy.js';
+import {
+  findByPath,
+  invalidateWorktreeCache,
+  pathFor,
+} from './registry-sync.js';
+import { validateBranch, validateStoryId } from './shared.js';
+
+export async function ensure(ctx, storyId, branch) {
+  const id = validateStoryId(storyId);
+  const br = validateBranch(branch);
+  if (br !== `story-${id}`) {
+    throw new Error(
+      `WorktreeManager: branch ${br} does not match storyId ${id}`,
+    );
+  }
+
+  const wtPath = pathFor(ctx, id);
+  const existing = findByPath(ctx, wtPath);
+
+  // Phase-boundary callback — invoked even on reuse so story-init's
+  // phase timer records non-null `worktree-create`/`bootstrap`/`install`
+  // entries regardless of whether provisioning actually ran. The timer
+  // reports the elapsed wall-clock between marks, so reuse paths yield
+  // near-zero rows, which is the correct observability signal.
+  const phase = (name) => {
+    if (typeof ctx.onPhase === 'function') ctx.onPhase(name);
+  };
+
+  if (existing) {
+    if (existing.branch && existing.branch !== br) {
+      throw new Error(
+        `WorktreeManager: worktree at ${wtPath} is on branch ${existing.branch}, expected ${br}`,
+      );
+    }
+    phase('worktree-create');
+    phase('bootstrap');
+    phase('install');
+    return {
+      path: wtPath,
+      created: false,
+      installStatus: { status: 'skipped', reason: 'worktree-reused' },
+    };
+  }
+
+  fs.mkdirSync(ctx.worktreeRoot, { recursive: true });
+
+  const windowsPathWarning = ctx.maybeWarnWindowsPath(wtPath);
+
+  const branchExists =
+    ctx.git.gitSpawn(
+      ctx.repoRoot,
+      'show-ref',
+      '--verify',
+      '--quiet',
+      `refs/heads/${br}`,
+    ).status === 0;
+
+  const addArgs = branchExists
+    ? ['worktree', 'add', wtPath, br]
+    : ['worktree', 'add', '-b', br, wtPath];
+
+  phase('worktree-create');
+  const res = ctx.git.gitSpawn(ctx.repoRoot, ...addArgs);
+  if (res.status !== 0) {
+    const stderr = res.stderr || res.stdout || '';
+    if (/already (exists|checked out)/.test(stderr)) {
+      const raceExisting = findByPath(ctx, wtPath);
+      if (raceExisting) {
+        ctx.logger.info(
+          `worktree.ensure race: worktree appeared concurrently for story-${id}, reusing`,
+        );
+        return {
+          path: wtPath,
+          created: false,
+          installStatus: { status: 'skipped', reason: 'worktree-reused' },
+        };
+      }
+    }
+    throw new Error(
+      `WorktreeManager: git worktree add failed for story-${id}: ${stderr}`,
+    );
+  }
+
+  invalidateWorktreeCache(ctx);
+
+  if (ctx.platform === 'win32') {
+    ctx.git.gitSpawn(wtPath, 'config', '--local', 'core.longpaths', 'true');
+  }
+
+  applyNodeModulesStrategy(ctx, wtPath);
+  phase('bootstrap');
+  ctx.copyBootstrapFiles(wtPath);
+  phase('install');
+  const installStatus = installDependencies(ctx, wtPath);
+
+  ctx.logger.info(`worktree.created storyId=${id} path=${wtPath}`);
+  return {
+    path: wtPath,
+    created: true,
+    installStatus,
+    ...(windowsPathWarning ? { windowsPathWarning } : {}),
+  };
+}

package/.agents/scripts/lib/worktree/lifecycle/drift-detection.js

@@ -0,0 +1,62 @@
+/**
+ * worktree/lifecycle/drift-detection.js
+ *
+ * Sweep stale `*.lock` files left behind under `.git/` and per-worktree admin
+ * directories after crashed git processes — a frequent residue from AV /
+ * search-indexer scans on Windows that blocks subsequent git operations with
+ * an `unable to lock` error.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export async function sweepStaleLocks(ctx, opts = {}) {
+  const maxAgeMs = opts.maxAgeMs ?? 300_000;
+  const now = Date.now();
+  const removed = [];
+  const skipped = [];
+
+  const gitDir = path.join(ctx.repoRoot, '.git');
+  const candidates = [
+    path.join(gitDir, 'index.lock'),
+    path.join(gitDir, 'HEAD.lock'),
+    path.join(gitDir, 'packed-refs.lock'),
+    path.join(gitDir, 'config.lock'),
+    path.join(gitDir, 'shallow.lock'),
+  ];
+
+  const worktreesDir = path.join(gitDir, 'worktrees');
+  if (fs.existsSync(worktreesDir)) {
+    for (const name of fs.readdirSync(worktreesDir)) {
+      candidates.push(path.join(worktreesDir, name, 'index.lock'));
+      candidates.push(path.join(worktreesDir, name, 'HEAD.lock'));
+    }
+  }
+
+  for (const lockPath of candidates) {
+    let stat;
+    try {
+      stat = fs.statSync(lockPath);
+    } catch {
+      continue;
+    }
+    const ageMs = now - stat.mtimeMs;
+    if (ageMs < maxAgeMs) {
+      skipped.push({ path: lockPath, ageMs });
+      continue;
+    }
+    try {
+      fs.unlinkSync(lockPath);
+      removed.push({ path: lockPath, ageMs });
+      ctx.logger.warn(
+        `stale-lock removed path=${lockPath} ageMs=${Math.round(ageMs)}`,
+      );
+    } catch (err) {
+      ctx.logger.warn(
+        `stale-lock unlink failed path=${lockPath}: ${err.message}`,
+      );
+    }
+  }
+
+  return { removed, skipped };
+}