@polymorphism-tech/morph-spec 8.42.0 → 8.44.0

package/framework/hooks/claude-code/core/worktree-context.js

@@ -51,34 +51,35 @@ import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registr
 import { rotateActivityLogIfLarge } from '../../shared/activity-logger.js';
 import { rotateEventsLogIfLarge } from '../../shared/telemetry-logger.js';
 import { kickGraphRefresh, seedFromPrimary } from '../../shared/graph-refresh.js';
+import { kickAgentReap } from '../../shared/agent-reap.js';
+import { isInContainer } from '../../shared/worktree-root.js';
+import { isSecondaryWorktree, resolveGitCommonDir } from '../../shared/git-paths.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
-function gitRevParse(arg, dir) {
-  return execSync(`git rev-parse ${arg}`, { cwd: dir, stdio: ['pipe', 'pipe', 'pipe'] })
-    .toString()
-    .trim();
-}
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
 
-/**
- * A secondary git worktree has a `--git-dir` (worktree-private, under
- * `.../.git/worktrees/{name}`) distinct from its `--git-common-dir` (the
- * primary repo's shared `.git`). In the primary root both resolve to the
- * same path. Any git error (not a repo at all) is treated as "not a
- * worktree" — fail-open.
- */
-function isSecondaryWorktree(dir) {
+// Inside a worktree Claude Code keeps CLAUDE_PROJECT_DIR at the project root and moves only the payload `cwd`.
+function sessionDir(payload) {
+  const base = projectDir();
+  const cwd = typeof payload?.cwd === 'string' ? payload.cwd : '';
+  if (!cwd || samePath(resolve(cwd), resolve(base))) return base;
   try {
-    const gitDir = gitRevParse('--git-dir', dir);
-    const commonDir = gitRevParse('--git-common-dir', dir);
-    return gitDir !== commonDir;
+    const common = resolveGitCommonDir(cwd);
+    return common && samePath(resolve(common), resolve(resolveGitCommonDir(base) ?? '')) && isSecondaryWorktree(cwd) ? cwd : base;
   } catch {
-    return false;
+    return base;
   }
 }
 
+function gitRevParse(arg, dir) {
+  return execSync(`git rev-parse ${arg}`, { cwd: dir, stdio: ['pipe', 'pipe', 'pipe'] })
+    .toString()
+    .trim();
+}
+
 /** Feature name from the current branch, if it matches `morph/{feature}`. */
 function featureFromBranch(dir) {
   try {
@@ -118,8 +119,7 @@ function isOutsideContainer(dir) {
   try {
     const common = resolve(dir, gitRevParse('--git-common-dir', dir)).replace(/\\/g, '/');
     const root = common.replace(/\/\.git$/, '');
-    const norm = resolve(dir).replace(/\\/g, '/');
-    return !['worktrees', '.worktrees'].some((d) => norm.startsWith(`${root}/${d}/`));
+    return !isInContainer(root, dir);
   } catch {
     return false;
   }
@@ -280,7 +280,7 @@ function claimBlock(dir, feature, sessionId) {
  */
 export async function run(payload) {
   try {
-    const dir = projectDir();
+    const dir = sessionDir(payload);
     // The SessionStart payload carries session_id — the identity the claim
     // registry uses to tell "me" from "another session".
     const sessionId = payload?.session_id || `pid-${process.pid}`;
@@ -303,6 +303,7 @@ export async function run(payload) {
     // Returns immediately — nothing here waits on graphify.
     try { seedFromPrimary(dir); } catch { /* non-blocking — a no-op on the root */ }
     try { kickGraphRefresh(dir); } catch { /* non-blocking */ }
+    try { kickAgentReap(dir); } catch { /* non-blocking */ }
 
     if (isSecondaryWorktree(dir)) {
       const task = taskFromBranch(dir);

package/framework/hooks/claude-code/core/worktree-create.js

@@ -43,8 +43,7 @@ import { homedir } from 'os';
 import { stateExists } from '../../shared/state-reader.js';
 import { resolveGitCommonDir } from '../../shared/git-paths.js';
 import { runMorphSpec } from '../../shared/morph-cli.js';
-
-const WORKTREES_DIR = 'worktrees';
+import { newWorktreesDir } from '../../shared/worktree-root.js';
 
 const fwd = (p) => String(p).replace(/\\/g, '/');
 
@@ -152,14 +151,15 @@ function defaultBranch(root) {
  */
 function gitFallback(root, name, base) {
   const branch = `morph-task/${name}`;
-  const path = `${root}/${WORKTREES_DIR}/${name}`;
+  const container = newWorktreesDir(root);
+  const path = `${container}/${name}`;
   if (existsSync(path)) return { path };
   try { git(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], root); }
   catch {
     const from = base || defaultBranch(root);
     git(from ? ['branch', branch, from] : ['branch', branch], root);
   }
-  mkdirSync(join(root, WORKTREES_DIR), { recursive: true });
+  mkdirSync(container, { recursive: true });
   git(['worktree', 'add', path, branch], root);
   return { path };
 }

package/framework/hooks/claude-code/core/worktree-env-inject.js

@@ -42,9 +42,6 @@ const LAUNCHER_RE = /\b(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start)\b|nex
 /** The command already chose its own port/project — respect it. */
 const SELF_CONFIGURED_RE = /(?:^|[\s;&|])(?:PORT|API_PORT|POSTGRES_PORT|COMPOSE_PROJECT_NAME|ASPNETCORE_URLS)=|--port\b|(?:^|\s)-p\s+\d|compose\b[^|;&]*\s-p\s/;
 
-/** Keys the layout owns; anything else in the manifest is left alone. */
-const LAYOUT_KEYS = ['COMPOSE_PROJECT_NAME', 'MORPH_PORT_BASE', 'MORPH_PORT_RANGE', 'PORT', 'API_PORT', 'POSTGRES_PORT', 'REDIS_PORT', 'ASPNETCORE_URLS', 'PLAYWRIGHT_BASE_URL'];
-
 /** POSIX single-quote, safe for Git Bash on Windows too. */
 function shq(v) {
   return `'${String(v).replace(/'/g, "'\\''")}'`;
@@ -59,7 +56,7 @@ function shq(v) {
 export function rewriteCommand(command, env) {
   if (!command || !LAUNCHER_RE.test(command)) return null;
   if (SELF_CONFIGURED_RE.test(command)) return null;
-  const pairs = LAYOUT_KEYS.filter((k) => env[k]).map((k) => [k, env[k]]);
+  const pairs = Object.keys(env).filter((k) => k !== 'MORPH_FEATURE' && env[k]).map((k) => [k, env[k]]);
   if (!pairs.some(([k]) => k === 'PORT')) return null;
   // The web tier's URL is what the spec suite needs; derive it once here.
   if (!env.PLAYWRIGHT_BASE_URL) pairs.push(['PLAYWRIGHT_BASE_URL', `http://localhost:${env.PORT}`]);

package/framework/hooks/shared/agent-reap.js

@@ -0,0 +1,89 @@
+/**
+ * agent-reap.js — dispara `morph-spec worktree reap` em background no SessionStart.
+ *
+ * O hook de SessionStart tem 5 s de timeout e o reaper mede git por árvore: por isso o
+ * disparo só olha o disco (nenhum subprocesso) e solta este arquivo como worker DESTACADO
+ * (`--run <raiz>`), que chama o CLI. Só a raiz: o worker nasce com `cwd` no git common dir
+ * e nunca segura o diretório de uma worktree.
+ *
+ * Fail-open em tudo. `MORPH_WORKTREE_REAP=0` desliga.
+ *
+ * @module agent-reap
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { isSecondaryWorktree, resolveGitCommonDir } from './git-paths.js';
+import { primaryTree } from './graph-freshness.js';
+import { runMorphSpec } from './morph-cli.js';
+
+const WORKER = fileURLToPath(import.meta.url);
+const THROTTLE_MS = 10 * 60_000;
+const WORKER_TIMEOUT_MS = 15 * 60_000;
+const ADMIN_DIR = /^agent-[0-9a-f]+\d*$/;
+const AGENT_BRANCH_FILE = /^agent-[0-9a-f]+$/;
+
+function anyEntry(dir, pattern) {
+  try { return readdirSync(dir).some((name) => pattern.test(name)); } catch { return false; }
+}
+
+/** Uma worktree de agent registrada, ou uma branch `morph-task/agent-*` (solta ou empacotada). */
+export function hasAgentLeftovers(common) {
+  if (anyEntry(join(common, 'worktrees'), ADMIN_DIR)) return true;
+  if (anyEntry(join(common, 'refs', 'heads', 'morph-task'), AGENT_BRANCH_FILE)) return true;
+  try {
+    return /refs\/heads\/morph-task\/agent-[0-9a-f]+/.test(readFileSync(join(common, 'packed-refs'), 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function recentlyKicked(marker, now) {
+  try {
+    const age = now - Number(readFileSync(marker, 'utf8'));
+    return age >= 0 && age < THROTTLE_MS;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} dir - diretório do projeto da sessão
+ * @returns {{ kicked: boolean, reason?: string, pid?: number }}
+ */
+export function kickAgentReap(dir, { spawnFn = spawn, env = process.env, now = Date.now } = {}) {
+  if (env.MORPH_WORKTREE_REAP === '0') return { kicked: false, reason: 'disabled' };
+  const common = resolveGitCommonDir(dir);
+  const root = common && primaryTree(dir);
+  if (!root) return { kicked: false, reason: 'not-a-repo' };
+  if (isSecondaryWorktree(dir)) return { kicked: false, reason: 'secondary-worktree' };
+  if (!hasAgentLeftovers(common)) return { kicked: false, reason: 'nothing-to-reap' };
+
+  const marker = join(common, 'morph-spec', 'agent-reap.kick');
+  if (recentlyKicked(marker, now())) return { kicked: false, reason: 'throttled' };
+  try {
+    mkdirSync(join(common, 'morph-spec'), { recursive: true });
+    writeFileSync(marker, String(now()));
+    const child = spawnFn(process.execPath, [WORKER, '--run', root], {
+      cwd: common, env, detached: true, stdio: 'ignore', windowsHide: true,
+    });
+    child.on?.('error', () => {});
+    child.unref?.();
+    return { kicked: true, pid: child.pid };
+  } catch {
+    return { kicked: false, reason: 'spawn-failed' };
+  }
+}
+
+const isMain = (() => {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  const norm = (p) => (process.platform === 'win32' ? resolve(p).toLowerCase() : resolve(p));
+  return norm(argv1) === norm(WORKER);
+})();
+
+if (isMain && process.argv[2] === '--run' && process.argv[3] && existsSync(process.argv[3])) {
+  try { runMorphSpec(['worktree', 'reap', '--json'], { cwd: process.argv[3], timeoutMs: WORKER_TIMEOUT_MS }); } catch { /* fail-open */ }
+}

package/framework/hooks/shared/e2e-check.js

@@ -675,7 +675,7 @@ function sleep(ms) {
 
 /** Tear the stack down. Best-effort: teardown failure never fails a check. */
 export function tearDownStack(cwd, { composeFile, projectName, env, volumes = false } = {}, exec = defaultExec) {
-  const args = [...composeArgs(composeFile, projectName), 'down'];
+  const args = [...composeArgs(composeFile, projectName), 'down', '--remove-orphans'];
   if (volumes) args.push('-v');
   const result = exec('docker', args, { cwd, env });
   return { status: result.code === 0 ? 'pass' : 'fail', output: result.output };
@@ -863,6 +863,7 @@ export function runE2eCheck(cwd, options = {}) {
     insideWorktree = isSecondaryWorktree(cwd),
     healthTimeout = DEFAULT_HEALTH_TIMEOUT,
     specTimeout = DEFAULT_SPEC_TIMEOUT,
+    beforeHeavy = null,
     _exec: exec = defaultExec,
   } = options;
 
@@ -910,6 +911,7 @@ export function runE2eCheck(cwd, options = {}) {
     : {};
   const composeEnv = { COMPOSE_PROJECT_NAME: projectName, ...authEnv, ...(env || {}) };
 
+  if (typeof beforeHeavy === 'function') beforeHeavy();
   const up = bringUpStack(
     cwd,
     { composeFile, projectName, gitCommonDir, env: composeEnv, forceFresh, healthTimeout },

package/framework/hooks/shared/graph-refresh.js

@@ -50,6 +50,7 @@ import { fileURLToPath } from 'url';
 import { readPrimaryHead, resolveGitCommonDir, workTreeTop } from './git-paths.js';
 import { findFirstOnPath, quoteForCmd } from './morph-cli.js';
 import { ensureCommonExclude } from './git-exclude.js';
+import { pidAlive } from './process-alive.js';
 import {
   GRAPH_DIR, graphFile, graphFreshness, ignoreRulesHash, primaryTree, readRefreshRecord,
   recordRefreshRun, refreshPending, treeKey, writeRefreshRecord,
@@ -110,15 +111,6 @@ function mtimeOf(path) {
   }
 }
 
-function pidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err?.code === 'EPERM';
-  }
-}
-
 /**
  * Estado do lock do repositório — o que `graph status` mostra como "refresh em
  * andamento". A idade conta da última renovação: um lock de processo morto,

package/framework/hooks/shared/heavy-command.js

@@ -0,0 +1,128 @@
+import { tokenize } from './command-tokens.js';
+
+const DOTNET_HEAVY = new Set(['build', 'test', 'publish', 'pack', 'msbuild', 'vstest']);
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+const HEAVY_SCRIPT = /^(test|build)(:.+)?$/;
+const WRAPPERS = new Set(['time', 'nohup', 'nice', 'command', 'exec', 'env']);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const INFO_FLAGS = new Set(['--help', '-h', '--version', '-?']);
+
+function splitSegments(command) {
+  const segments = [];
+  let current = '';
+  let quote = null;
+  const s = String(command || '');
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (quote) {
+      current += ch;
+      if (ch === quote) quote = null;
+      else if (ch === '\\' && quote === '"') current += s[++i] ?? '';
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; current += ch; continue; }
+    if (ch === '\\') { current += ch + (s[++i] ?? ''); continue; }
+    if (';|&\n'.includes(ch)) { segments.push(current); current = ''; continue; }
+    current += ch;
+  }
+  segments.push(current);
+  return segments;
+}
+
+function executable(token) {
+  return token.replace(/^.*[\\/]/, '').replace(/\.(exe|cmd|bat|ps1)$/i, '').toLowerCase();
+}
+
+function skipWrappers(tokens) {
+  let i = 0;
+  for (;;) {
+    const t = tokens[i];
+    if (t === undefined) return [];
+    if (ASSIGNMENT.test(t)) { i++; continue; }
+    if (t === 'timeout') { i += 2; continue; }
+    if (WRAPPERS.has(executable(t))) { i++; continue; }
+    return tokens.slice(i);
+  }
+}
+
+const DOCKER_VALUE_FLAGS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-file', '--project-directory', '-H', '--host', '--context']);
+
+function firstArg(args, valueFlags = new Set()) {
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].startsWith('-')) return args[i];
+    if (valueFlags.has(args[i])) i++;
+  }
+  return undefined;
+}
+
+function kindOfTokens(tokens) {
+  const [head, ...args] = tokens;
+  if (!head || args.some((a) => INFO_FLAGS.has(a))) return null;
+  const exe = executable(head);
+  const sub = firstArg(args, exe === 'docker' || exe === 'docker-compose' ? DOCKER_VALUE_FLAGS : undefined);
+
+  if (exe === 'dotnet') return DOTNET_HEAVY.has(sub) ? `dotnet ${sub}` : null;
+  if (exe === 'msbuild') return 'msbuild';
+  if (exe === 'vitest' || exe === 'jest') return exe;
+  if (exe === 'playwright') return sub === 'test' ? 'playwright test' : null;
+  if (exe === 'next' || exe === 'vite') return sub === 'build' ? `${exe} build` : null;
+
+  if (PACKAGE_MANAGERS.has(exe)) {
+    if (sub === 'test' || sub === 'build') return `${exe} ${sub}`;
+    if (sub === 'run' || sub === 'run-script') {
+      const script = args.slice(args.indexOf(sub) + 1).find((t) => !t.startsWith('-'));
+      return script && HEAVY_SCRIPT.test(script) ? `${exe} run ${script}` : null;
+    }
+    return null;
+  }
+
+  if (exe === 'npx' || exe === 'bunx') {
+    if (sub === 'vitest' || sub === 'jest') return `npx ${sub}`;
+    const rest = args.slice(args.indexOf(sub) + 1).find((t) => !t.startsWith('-'));
+    if (sub === 'playwright') return rest === 'test' ? 'npx playwright test' : null;
+    if (sub === 'next') return rest === 'build' ? 'npx next build' : null;
+    return null;
+  }
+
+  if (exe === 'docker-compose') return sub === 'up' || sub === 'build' ? `docker-compose ${sub}` : null;
+  if (exe === 'docker') {
+    if (sub === 'build' || sub === 'buildx') return `docker ${sub}`;
+    if (sub === 'compose') {
+      const action = firstArg(args.slice(args.indexOf(sub) + 1), DOCKER_VALUE_FLAGS);
+      return action === 'up' || action === 'build' ? `docker compose ${action}` : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The first heavy command of a Bash command line, as a label, or null. Looks at the executable of
+ * each `;`/`&&`/`||`/`|`/newline segment, so `morph-spec heavy run -- dotnet test` and `echo "dotnet build"`
+ * are not heavy: the first runs under its own slot, the second runs nothing.
+ * @param {string} command
+ * @returns {string|null}
+ */
+export function heavyKind(command) {
+  for (const segment of splitSegments(command)) {
+    const tokens = skipWrappers(tokenize(segment.replace(/^[\s({]+/, '').replace(/[\s)}]+$/, '')));
+    const kind = kindOfTokens(tokens);
+    if (kind) return kind;
+  }
+  return null;
+}
+
+/**
+ * How long a foreground Bash call can run: its own `timeout` (capped at the platform maximum) plus slack.
+ * The lease has no live process to watch, so this is the only thing that frees it after a denied or
+ * interrupted call.
+ */
+const BASH_DEFAULT_TIMEOUT_MS = 2 * 60_000;
+const BASH_MAX_TIMEOUT_MS = 10 * 60_000;
+const LEASE_SLACK_MS = 30_000;
+
+export function leaseTtlMs(toolInput, env = process.env) {
+  const fallback = Number(env.BASH_DEFAULT_TIMEOUT_MS) || BASH_DEFAULT_TIMEOUT_MS;
+  const max = Math.max(Number(env.BASH_MAX_TIMEOUT_MS) || BASH_MAX_TIMEOUT_MS, fallback);
+  const asked = Number(toolInput?.timeout);
+  return Math.min(Number.isFinite(asked) && asked > 0 ? asked : fallback, max) + LEASE_SLACK_MS;
+}

package/framework/hooks/shared/heavy-config.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CONFIG_FILE = join('.morph', 'config', 'config.json');
+
+export const HEAVY_DEFAULTS = Object.freeze({
+  enabled: true,
+  slots: 2,
+  minFreeMemGb: 4,
+  waitTimeoutSec: 600,
+  maxHoldMinutes: 90,
+  shutdownBuildServer: true,
+  disableNodeReuse: false,
+  gateBash: false,
+});
+
+const isBool = (v) => typeof v === 'boolean';
+const VALID = {
+  enabled: isBool,
+  slots: (v) => Number.isInteger(v) && v >= 1,
+  minFreeMemGb: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
+  waitTimeoutSec: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
+  maxHoldMinutes: (v) => typeof v === 'number' && Number.isFinite(v) && v > 0,
+  shutdownBuildServer: isBool,
+  disableNodeReuse: isBool,
+  gateBash: isBool,
+};
+
+export function readProjectConfig(projectPath) {
+  const file = join(projectPath, CONFIG_FILE);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+export function resolveHeavyConfig(config, env = process.env) {
+  const out = { ...HEAVY_DEFAULTS };
+  const warnings = [];
+  const raw = config?.heavy;
+
+  if (raw !== undefined) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      warnings.push('`heavy` no config.json não é um objeto; usando os padrões');
+    } else {
+      for (const [key, value] of Object.entries(raw)) {
+        if (!(key in VALID)) warnings.push(`heavy.${key} não existe; ignorada`);
+        else if (VALID[key](value)) out[key] = value;
+        else warnings.push(`heavy.${key} inválida (${JSON.stringify(value)}); usando ${JSON.stringify(HEAVY_DEFAULTS[key])}`);
+      }
+    }
+  }
+
+  if (/^(off|0|false)$/i.test(env.MORPH_HEAVY ?? '')) out.enabled = false;
+  const envSlots = Number(env.MORPH_HEAVY_SLOTS);
+  if (env.MORPH_HEAVY_SLOTS !== undefined && VALID.slots(envSlots)) out.slots = envSlots;
+
+  return { ...out, warnings };
+}
+
+export function readHeavyConfig(projectPath, env = process.env) {
+  return resolveHeavyConfig(readProjectConfig(projectPath), env);
+}

package/framework/hooks/shared/heavy-holders.js

@@ -0,0 +1,85 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { freemem, homedir } from 'node:os';
+import { join } from 'node:path';
+import { pidAlive } from './process-alive.js';
+
+export const GB = 1024 ** 3;
+export const WRITE_GRACE_MS = 5000;
+export const EXCLUSIVE_MAX_AGE_MS = 2 * 60 * 1000;
+export const SLOT_FILE = /^slot-\d+\.lock$/;
+
+export function heavyDir(env = process.env, { platform = process.platform, home = homedir() } = {}) {
+  if (env.MORPH_HEAVY_DIR) return env.MORPH_HEAVY_DIR;
+  if (platform === 'win32') return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'morph-spec', 'heavy');
+  return join(env.XDG_STATE_HOME || join(home, '.local', 'state'), 'morph-spec', 'heavy');
+}
+
+export const mtimeOf = (path) => {
+  try { return statSync(path).mtimeMs; } catch { return null; }
+};
+
+const leaseTtlMs = (meta) => (Number.isFinite(meta.ttlMs) && meta.ttlMs > 0 ? meta.ttlMs : Infinity);
+
+export function readLockFile(path, { now, isAlive, maxHoldMs }) {
+  const t = now();
+  let meta;
+  try {
+    meta = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    const mtime = mtimeOf(path);
+    if (mtime === null) return null;
+    const writing = t - mtime < WRITE_GRACE_MS;
+    return { path, pid: null, since: null, label: '(gravando)', live: writing, unreadable: true };
+  }
+  const age = t - Date.parse(meta.since);
+  const inWindow = age >= 0 && age < maxHoldMs;
+  // A per-call lease belongs to a hook process that is long gone: only its TTL says when it lapses.
+  const live = meta.leaseId ? inWindow && age < leaseTtlMs(meta) : inWindow && Boolean(isAlive(meta.pid));
+  return { ...meta, path, live };
+}
+
+export function scanHolders(dir, ctx) {
+  let names = [];
+  try { names = readdirSync(dir).filter((n) => SLOT_FILE.test(n)); } catch { return { live: [], stale: [] }; }
+  const live = [];
+  const stale = [];
+  for (const name of names) {
+    const holder = readLockFile(join(dir, name), ctx);
+    if (!holder) continue;
+    (holder.live ? live : stale).push(holder);
+  }
+  return { live, stale };
+}
+
+export function readHolders(dir, ctx) {
+  return scanHolders(dir, ctx).live;
+}
+
+export function readExclusive(dir, ctx) {
+  const holder = readLockFile(join(dir, 'exclusive.lock'), { ...ctx, maxHoldMs: EXCLUSIVE_MAX_AGE_MS });
+  return holder?.live ? holder : null;
+}
+
+const ageText = (ms) => {
+  const min = Math.floor(ms / 60000);
+  return min < 1 ? `${Math.max(0, Math.floor(ms / 1000))}s` : `${min}m`;
+};
+
+export function describeHolder(h, now = Date.now()) {
+  const what = [h.label, [h.feature, h.node].filter(Boolean).join('/')].filter(Boolean).join(' ');
+  const age = h.since ? `, há ${ageText(now - Date.parse(h.since))}` : '';
+  const who = h.leaseId ? 'chamada Bash' : `pid ${h.pid ?? '?'}`;
+  return `${what || 'processo'}, ${who}${age}`;
+}
+
+export function heavyStatus({
+  dir, maxHoldMs, now = Date.now, isAlive = pidAlive, freeMem = freemem,
+}) {
+  const ctx = { now, isAlive, maxHoldMs };
+  return {
+    dir,
+    holders: readHolders(dir, ctx),
+    exclusive: readExclusive(dir, ctx),
+    freeGb: freeMem() / GB,
+  };
+}