@outcomeeng/spx 0.5.5 → 0.5.6

package/dist/cli.js

@@ -1066,11 +1066,13 @@ var STATE_STORE_ERROR = {
   RECORD_WRITE_FAILED: "state-store record write failed",
   RECORD_READ_FAILED: "state-store record read failed"
 };
+var STATE_STORE_RUN_TOKEN = {
+  ID_BYTES: 6,
+  TIMESTAMP_MILLISECOND_DIGITS: 3
+};
 var HEX_ENCODING = "hex";
-var RUN_ID_BYTES = 6;
 var RUN_FILE_CREATE_ATTEMPTS = 10;
 var RUN_TIMESTAMP_SEPARATOR = "_";
-var RUN_TIMESTAMP_MILLISECOND_DIGITS = 3;
 var SLUG_SEPARATOR = "-";
 var EMPTY_STRING = "";
 var RUN_TOKEN_PATTERN = /^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}-\d{3}-[a-f0-9]{12}$/;
@@ -1144,11 +1146,19 @@ function formatRunTimestamp(date) {
   const hours = String(date.getUTCHours()).padStart(2, "0");
   const minutes = String(date.getUTCMinutes()).padStart(2, "0");
   const seconds = String(date.getUTCSeconds()).padStart(2, "0");
-  const milliseconds = String(date.getUTCMilliseconds()).padStart(RUN_TIMESTAMP_MILLISECOND_DIGITS, "0");
+  const milliseconds = String(date.getUTCMilliseconds()).padStart(
+    STATE_STORE_RUN_TOKEN.TIMESTAMP_MILLISECOND_DIGITS,
+    "0"
+  );
   return `${year}-${month}-${day}${RUN_TIMESTAMP_SEPARATOR}${hours}-${minutes}-${seconds}-${milliseconds}`;
 }
 function generateRunId(randomBytes = nodeRandomBytes) {
-  return randomBytes(RUN_ID_BYTES).toString(HEX_ENCODING);
+  return randomBytes(STATE_STORE_RUN_TOKEN.ID_BYTES).toString(HEX_ENCODING);
+}
+function createStateStoreRunToken(options) {
+  const startedAt = formatRunTimestamp(options.date);
+  const runId = generateRunId(options.randomBytes);
+  return { runToken: `${startedAt}${SLUG_SEPARATOR}${runId}`, runId, startedAt };
 }
 function runFileName(runToken) {
   return `${STATE_STORE_PATH.RUN_FILE_PREFIX}${runToken}${STATE_STORE_PATH.JSONL_EXTENSION}`;
@@ -1165,7 +1175,6 @@ async function createJsonlRunFile(scopeDir, domainName, options = {}) {
   if (!domainRunsDir.ok) return domainRunsDir;
   const maxAttempts = options.maxAttempts ?? RUN_FILE_CREATE_ATTEMPTS;
   const startedDate = (options.now ?? (() => /* @__PURE__ */ new Date()))();
-  const startedAt = formatRunTimestamp(startedDate);
   const randomBytes = options.randomBytes ?? nodeRandomBytes;
   try {
     await fs7.mkdir(domainRunsDir.value, { recursive: true });
@@ -1176,15 +1185,14 @@ async function createJsonlRunFile(scopeDir, domainName, options = {}) {
     };
   }
   for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
-    const runId = generateRunId(randomBytes);
-    const runToken = `${startedAt}${SLUG_SEPARATOR}${runId}`;
-    const name = runFileName(runToken);
+    const token = createStateStoreRunToken({ date: startedDate, randomBytes });
+    const name = runFileName(token.runToken);
     const path6 = join2(domainRunsDir.value, name);
     try {
       await fs7.writeFile(path6, EMPTY_STRING, { flag: EXCLUSIVE_CREATE_FLAG });
       return {
         ok: true,
-        value: { runsDir: domainRunsDir.value, runFilePath: path6, runFileName: name, runToken, runId, startedAt }
+        value: { runsDir: domainRunsDir.value, runFilePath: path6, runFileName: name, ...token }
       };
     } catch (error) {
       if (hasErrorCode(error, ERROR_CODE_FILE_EXISTS)) continue;
@@ -2382,11 +2390,6 @@ function knipAdapter(scope, config) {
   return scope.excluded.flatMap((entry) => [config.ignoreFlag, entry.path]);
 }
 
-// src/lib/file-inclusion/adapters/madge.ts
-function madgeAdapter(scope, config) {
-  return scope.excluded.flatMap((entry) => [config.ignoreFlag, entry.path]);
-}
-
 // src/lib/file-inclusion/adapters/markdownlint.ts
 function markdownlintAdapter(scope, config) {
   return scope.excluded.flatMap((entry) => [config.ignoreFlag, entry.path]);
@@ -2411,7 +2414,6 @@ function vitestAdapter(scope, config) {
 var TOOL_DEFAULT_FLAGS = {
   eslint: "--ignore-pattern",
   tsc: "--exclude",
-  madge: "--exclude",
   knip: "--exclude",
   markdownlint: "--ignore",
   pytest: "--ignore",
@@ -2420,7 +2422,6 @@ var TOOL_DEFAULT_FLAGS = {
 var ADAPTER_MAP = {
   eslint: eslintAdapter,
   tsc: tscAdapter,
-  madge: madgeAdapter,
   knip: knipAdapter,
   markdownlint: markdownlintAdapter,
   pytest: pytestAdapter,
@@ -3499,169 +3500,800 @@ var configDomain = {
   }
 };
 
-// src/commands/session/archive.ts
-import { mkdir, rename, stat } from "fs/promises";
-import { dirname as dirname3, join as join7 } from "path";
-
-// src/domains/session/archive.ts
-var SESSION_FILE_EXTENSION = ".md";
-var ARCHIVABLE_DIR_KEYS = {
-  TODO: "todoDir",
-  DOING: "doingDir"
-};
-var ARCHIVABLE_DIR_KEY = {
-  todo: ARCHIVABLE_DIR_KEYS.TODO,
-  doing: ARCHIVABLE_DIR_KEYS.DOING
-};
-function buildArchivePaths(sessionId, currentStatus, config) {
-  const filename = `${sessionId}${SESSION_FILE_EXTENSION}`;
-  const dirKey = ARCHIVABLE_DIR_KEY[currentStatus];
-  const sourceDir = config[dirKey];
-  return {
-    source: `${sourceDir}/${filename}`,
-    target: `${config.archiveDir}/${filename}`
-  };
+// src/lib/sanitize-cli-argument.ts
+var MAX_CLI_ARGUMENT_DISPLAY_LENGTH = 120;
+var ELLIPSIS_TOKEN = "...";
+var SENTINEL_UNDEFINED = "<undefined>";
+var SENTINEL_NULL = "<null>";
+var SENTINEL_EMPTY = "<empty>";
+var CONTROL_CHAR_UPPER_BOUND = 31;
+var DEL_CHAR_CODE = 127;
+var HEX_RADIX = 16;
+var HEX_PAD = 2;
+function formatHexEscape(code) {
+  return `\\x${code.toString(HEX_RADIX).padStart(HEX_PAD, "0")}`;
 }
-var ARCHIVE_SEARCH_ORDER = ["todo", "doing"];
-function findSessionForArchive(existingPaths) {
-  if (existingPaths.archive !== null) {
-    return null;
-  }
-  for (const status of ARCHIVE_SEARCH_ORDER) {
-    if (existingPaths[status] !== null) {
-      return { status, path: existingPaths[status] };
-    }
-  }
-  return null;
+function nonStringSentinel(type) {
+  return `<non-string:${type}>`;
 }
-
-// src/domains/session/batch.ts
-var BatchError = class extends Error {
-  results;
-  constructor(results) {
-    const failures = results.filter((r) => !r.ok);
-    const successes = results.filter((r) => r.ok);
-    super(
-      `${failures.length} of ${results.length} operations failed. ${successes.length} succeeded.`
-    );
-    this.name = "BatchError";
-    this.results = results;
-  }
-};
-async function processBatch(ids, handler) {
-  const results = [];
-  for (const id of ids) {
-    try {
-      const output2 = await handler(id);
-      results.push({ id, ok: true, message: output2 });
-    } catch (error) {
-      const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-      results.push({ id, ok: false, message });
+function sanitizeCliArgument(input) {
+  if (input === void 0) return SENTINEL_UNDEFINED;
+  if (input === null) return SENTINEL_NULL;
+  if (typeof input !== "string") return nonStringSentinel(typeof input);
+  if (input.length === 0) return SENTINEL_EMPTY;
+  const escaped = escapeControlCharacters(input);
+  return truncate(escaped);
+}
+function escapeControlCharacters(value) {
+  let out = "";
+  for (const char of value) {
+    const code = char.codePointAt(0);
+    if (code === void 0) continue;
+    if (code <= CONTROL_CHAR_UPPER_BOUND || code === DEL_CHAR_CODE) {
+      out += formatHexEscape(code);
+    } else {
+      out += char;
     }
   }
-  const output = results.map((r) => r.ok ? r.message : `Error (${r.id}): ${r.message}`).join("\n\n");
-  const hasFailures = results.some((r) => !r.ok);
-  if (hasFailures) {
-    const err = new BatchError(results);
-    err.message = `${err.message}
-
-${output}`;
-    throw err;
-  }
-  return output;
+  return out;
+}
+function truncate(value) {
+  if (value.length <= MAX_CLI_ARGUMENT_DISPLAY_LENGTH) return value;
+  return value.slice(0, MAX_CLI_ARGUMENT_DISPLAY_LENGTH - ELLIPSIS_TOKEN.length) + ELLIPSIS_TOKEN;
 }
 
-// src/domains/session/handoff-base-checklist.ts
-var SESSION_HANDOFF_BASE_ERROR_NAME = "SessionHandoffBaseError";
-var HANDOFF_BASE_MARK = {
-  MET: "\u2713",
-  UNMET: "\u2717"
-};
-var HANDOFF_BASE_PREREQUISITE_LABEL = {
-  CLEAN_WORKING_TREE: "working tree is clean",
-  DETACHED_AT_DEFAULT_TIP: "HEAD is detached at the default-branch tip"
+// src/interfaces/hooks/session-start.ts
+import { appendFile as nodeAppendFile2 } from "fs/promises";
+
+// src/domains/worktree/occupancy-store.ts
+import { join as join6 } from "path";
+var OCCUPANCY_STATUS = {
+  UNCLAIMED: "unclaimed",
+  OCCUPIED: "occupied",
+  STALE: "stale"
 };
-var HANDOFF_BASE_REMEDY = {
-  /** Unclean working tree: commit, or hand off from the main checkout. */
-  COMMIT_OR_MAIN_CHECKOUT: "commit the changes, or run handoff from the main checkout",
-  /** Off the default-branch tip: detach to it, or hand off from the main checkout. */
-  DETACH_TO_TIP_OR_MAIN_CHECKOUT: "detach HEAD to the default-branch tip, or run handoff from the main checkout",
-  /** Default branch unresolved: only the main checkout can anchor the base. */
-  MAIN_CHECKOUT_ONLY: "run handoff from the main checkout"
+var OCCUPANCY_CLAIM = {
+  FILE_EXTENSION: ".claim",
+  TEMP_EXTENSION: ".tmp",
+  UNREADABLE_STARTED_AT_PREFIX: "unreadable:"
 };
-var HANDOFF_BASE_FACT_LABEL = {
-  DEFAULT_BRANCH: "default branch",
-  DEFAULT_TIP: "origin tip",
-  HEAD: "HEAD",
-  CURRENT_WORKTREE: "current worktree",
-  MAIN_CHECKOUT: "main checkout"
+var OCCUPANCY_ERROR = {
+  INVALID_NAME: "worktree occupancy claim name must be a safe path segment",
+  INVALID_WRITE_TOKEN: "worktree occupancy claim write token must be a safe path segment",
+  CLAIM_WRITE_FAILED: "worktree occupancy claim write failed",
+  CLAIM_READ_FAILED: "worktree occupancy claim read failed",
+  CLAIM_REMOVE_FAILED: "worktree occupancy claim remove failed",
+  CLAIM_MALFORMED: "worktree occupancy claim record is malformed"
 };
-var HANDOFF_BASE_UNRESOLVED = "unresolved";
-var CHECKLIST_INDENT = "  ";
-var REMEDY_SEPARATOR = " \u2014 ";
-var CHECKLIST_HEADER = `${SESSION_HANDOFF_BASE_ERROR_NAME}: cannot create a handoff session from this worktree \u2014 it is not the main checkout.`;
-function renderFactLine(label, value) {
-  return `${CHECKLIST_INDENT}${label}: ${value ?? HANDOFF_BASE_UNRESOLVED}`;
+var ERROR_DETAIL_SEPARATOR2 = ": ";
+function claimFileName(name) {
+  return `${name}${OCCUPANCY_CLAIM.FILE_EXTENSION}`;
 }
-function renderPrerequisiteLine(prerequisite) {
-  const mark = prerequisite.met ? HANDOFF_BASE_MARK.MET : HANDOFF_BASE_MARK.UNMET;
-  const base = `${CHECKLIST_INDENT}${mark} ${prerequisite.label}`;
-  return prerequisite.met ? base : `${base}${REMEDY_SEPARATOR}${prerequisite.remedy}`;
+function claimFilePath(worktreesDir, name) {
+  const validated = validateScopeToken(name);
+  if (!validated.ok) return { ok: false, error: OCCUPANCY_ERROR.INVALID_NAME };
+  return { ok: true, value: join6(worktreesDir, claimFileName(validated.value)) };
 }
-function renderHandoffBaseChecklist(checklist) {
-  return [
-    CHECKLIST_HEADER,
-    renderFactLine(HANDOFF_BASE_FACT_LABEL.DEFAULT_BRANCH, checklist.defaultBranch),
-    renderFactLine(HANDOFF_BASE_FACT_LABEL.DEFAULT_TIP, checklist.defaultTipSha),
-    renderFactLine(HANDOFF_BASE_FACT_LABEL.HEAD, checklist.headSha),
-    renderFactLine(HANDOFF_BASE_FACT_LABEL.CURRENT_WORKTREE, checklist.currentWorktreePath),
-    renderFactLine(HANDOFF_BASE_FACT_LABEL.MAIN_CHECKOUT, checklist.mainCheckoutPath),
-    ...checklist.prerequisites.map(renderPrerequisiteLine)
-  ].join("\n");
+function claimTempFilePath(claimPath, writeToken) {
+  const validated = validateScopeToken(writeToken);
+  if (!validated.ok) return { ok: false, error: OCCUPANCY_ERROR.INVALID_WRITE_TOKEN };
+  return { ok: true, value: `${claimPath}.${validated.value}${OCCUPANCY_CLAIM.TEMP_EXTENSION}` };
 }
-
-// src/domains/session/errors.ts
-var SessionError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "SessionError";
-  }
-};
-var SessionNotFoundError = class extends SessionError {
-  /** The session ID that was not found */
-  sessionId;
-  constructor(sessionId) {
-    super(`Session not found: ${sessionId}. Check the session ID and try again.`);
-    this.name = "SessionNotFoundError";
-    this.sessionId = sessionId;
+function classifyOccupancy(claim, probe) {
+  if (claim === void 0) return OCCUPANCY_STATUS.UNCLAIMED;
+  if (claim.host !== probe.currentHost()) return OCCUPANCY_STATUS.STALE;
+  if (!probe.isAlive(claim.pid)) return OCCUPANCY_STATUS.STALE;
+  const liveStartTime = probe.startTimeOf(claim.pid);
+  if (claim.startedAt === unreadableStartedAt(claim.pid)) return OCCUPANCY_STATUS.OCCUPIED;
+  if (liveStartTime !== void 0 && liveStartTime !== claim.startedAt) return OCCUPANCY_STATUS.STALE;
+  return OCCUPANCY_STATUS.OCCUPIED;
+}
+function unreadableStartedAt(pid) {
+  return `${OCCUPANCY_CLAIM.UNREADABLE_STARTED_AT_PREFIX}${pid}`;
+}
+async function writeClaim(worktreesDir, name, record, options) {
+  const pathResult = claimFilePath(worktreesDir, name);
+  if (!pathResult.ok) return pathResult;
+  const claimPath = pathResult.value;
+  const tempPath = claimTempFilePath(claimPath, options.writeToken);
+  if (!tempPath.ok) return tempPath;
+  try {
+    await options.fs.mkdir(worktreesDir, { recursive: true });
+    await options.fs.writeFile(tempPath.value, serializeClaim(record));
+    await options.fs.rename(tempPath.value, claimPath);
+    return { ok: true, value: claimPath };
+  } catch (error) {
+    return { ok: false, error: formatOccupancyError(OCCUPANCY_ERROR.CLAIM_WRITE_FAILED, toErrorMessage2(error)) };
   }
-};
-var SessionNotAvailableError = class extends SessionError {
-  /** The session ID that is not available */
-  sessionId;
-  constructor(sessionId) {
-    super(`Session not available: ${sessionId}. It may have been claimed by another agent.`);
-    this.name = "SessionNotAvailableError";
-    this.sessionId = sessionId;
+}
+async function readClaim(worktreesDir, name, options) {
+  const pathResult = claimFilePath(worktreesDir, name);
+  if (!pathResult.ok) return pathResult;
+  let content;
+  try {
+    content = await options.fs.readFile(pathResult.value, "utf8");
+  } catch (error) {
+    if (hasErrorCode(error, ERROR_CODE_NOT_FOUND)) return { ok: true, value: void 0 };
+    return { ok: false, error: formatOccupancyError(OCCUPANCY_ERROR.CLAIM_READ_FAILED, toErrorMessage2(error)) };
   }
-};
-var SessionInvalidContentError = class extends SessionError {
-  constructor(reason) {
-    super(`Invalid session content: ${reason}`);
-    this.name = "SessionInvalidContentError";
+  return parseClaim(content);
+}
+async function removeClaim(worktreesDir, name, options) {
+  const pathResult = claimFilePath(worktreesDir, name);
+  if (!pathResult.ok) return pathResult;
+  try {
+    await options.fs.rm(pathResult.value, { force: true });
+    return { ok: true, value: void 0 };
+  } catch (error) {
+    return { ok: false, error: formatOccupancyError(OCCUPANCY_ERROR.CLAIM_REMOVE_FAILED, toErrorMessage2(error)) };
   }
-};
-var SessionInvalidGoalError = class extends SessionError {
-  constructor() {
-    super("Invalid session goal: goal must be a non-empty string.");
-    this.name = "SessionInvalidGoalError";
+}
+async function readOccupancy(worktreesDir, name, probe, options) {
+  const claimResult = await readClaim(worktreesDir, name, options);
+  if (!claimResult.ok) return claimResult;
+  return { ok: true, value: classifyOccupancy(claimResult.value, probe) };
+}
+function serializeClaim(record) {
+  return JSON.stringify({
+    sessionId: record.sessionId,
+    host: record.host,
+    pid: record.pid,
+    startedAt: record.startedAt
+  });
+}
+function parseClaim(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return { ok: false, error: OCCUPANCY_ERROR.CLAIM_MALFORMED };
   }
-};
-var SessionInvalidFieldError = class extends SessionError {
-  /** The unknown field token the caller supplied. */
-  field;
-  /** The full set of valid field names. */
-  validFields;
+  if (!isWorktreeClaimRecord(parsed)) return { ok: false, error: OCCUPANCY_ERROR.CLAIM_MALFORMED };
+  return { ok: true, value: parsed };
+}
+function isWorktreeClaimRecord(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate.sessionId === "string" && typeof candidate.host === "string" && typeof candidate.pid === "number" && typeof candidate.startedAt === "string";
+}
+function formatOccupancyError(code, detail) {
+  return `${code}${ERROR_DETAIL_SEPARATOR2}${detail}`;
+}
+function toErrorMessage2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/domains/worktree/controlling-process.ts
+var CONTROLLING_PID_ENV = "SPX_WORKTREE_CONTROLLING_PID";
+var AGENT_RUNTIME_NAMES = ["claude", "codex"];
+var AGENT_COMMAND_PATTERN = new RegExp(`\\b(?:${AGENT_RUNTIME_NAMES.join("|")})\\b`, "i");
+var CONTROLLING_PROCESS_ERROR = {
+  UNRESOLVED: "worktree controlling process could not be resolved"
+};
+var MAX_ANCESTRY_DEPTH = 64;
+var MIN_VALID_PID = 1;
+var PID_RADIX = 10;
+function resolveControllingProcess(selfPid, table, env) {
+  const host = table.currentHost();
+  for (const pid of controllingPidCandidates(selfPid, table, env)) {
+    const startedAt = table.startTimeOf(pid);
+    if (startedAt !== void 0) return { ok: true, value: { pid, startedAt, host } };
+    if (table.isAlive(pid)) return { ok: true, value: { pid, startedAt: unreadableStartedAt(pid), host } };
+  }
+  return { ok: false, error: CONTROLLING_PROCESS_ERROR.UNRESOLVED };
+}
+function* controllingPidCandidates(selfPid, table, env) {
+  const override = parsePid(env[CONTROLLING_PID_ENV]);
+  if (override !== void 0) yield override;
+  const agent = findAgentAncestor(selfPid, table);
+  if (agent !== void 0) yield agent;
+  const parent = table.parentOf(selfPid);
+  if (parent !== void 0 && isValidPid(parent)) yield parent;
+}
+function findAgentAncestor(selfPid, table) {
+  let pid = table.parentOf(selfPid);
+  for (let depth = 0; pid !== void 0 && isValidPid(pid) && depth < MAX_ANCESTRY_DEPTH; depth += 1) {
+    const command = table.commandOf(pid);
+    if (command !== void 0 && AGENT_COMMAND_PATTERN.test(command)) return pid;
+    pid = table.parentOf(pid);
+  }
+  return void 0;
+}
+function parsePid(value) {
+  if (value === void 0 || value.length === 0) return void 0;
+  const parsed = Number.parseInt(value, PID_RADIX);
+  return isValidPid(parsed) ? parsed : void 0;
+}
+function isValidPid(pid) {
+  return Number.isInteger(pid) && pid >= MIN_VALID_PID;
+}
+
+// src/domains/worktree/resolve.ts
+import { dirname as dirname3, resolve as resolve3 } from "path";
+
+// src/domains/worktree/worktree-name.ts
+import { basename as basename2 } from "path";
+var SEPARATOR_CHARACTER = /[^a-z0-9_]/;
+var NAME_SEPARATOR = "-";
+function worktreeClaimName(worktreeRoot) {
+  return basename2(worktreeRoot).toLowerCase().split(SEPARATOR_CHARACTER).filter((segment) => segment.length > 0).join(NAME_SEPARATOR);
+}
+
+// src/domains/worktree/resolve.ts
+var WORKTREE_RESOLVE_ERROR = {
+  NOT_A_WORKTREE: "path resolves to no worktree"
+};
+async function resolveWorktreesDir(options) {
+  if (options.worktreesDir !== void 0) return options.worktreesDir;
+  const resolved = await resolveWorktreesScopeDir({ cwd: options.cwd, deps: options.gitDeps });
+  options.onWarning?.(resolved.warning);
+  return resolved.worktreesDir;
+}
+async function resolveCurrentWorktreeName(options) {
+  const worktree = await detectWorktreeProductRoot(options.cwd, options.gitDeps);
+  return worktreeClaimName(worktree.productDir);
+}
+async function resolveTargetWorktree(options) {
+  const base = options.cwd;
+  const targetPath = options.worktree === void 0 ? base : resolve3(base, options.worktree);
+  const targetGitPath = await options.pathInfo.isExistingNonDirectory(targetPath) ? dirname3(targetPath) : targetPath;
+  const worktree = await detectWorktreeProductRoot(targetGitPath, options.gitDeps);
+  if (!worktree.isGitRepo) {
+    return { ok: false, error: `${WORKTREE_RESOLVE_ERROR.NOT_A_WORKTREE}: ${options.worktree ?? base}` };
+  }
+  return { ok: true, value: { name: worktreeClaimName(worktree.productDir), worktreeRoot: worktree.productDir } };
+}
+
+// src/domains/worktree/claim.ts
+async function claimWorktreeOccupancy(options) {
+  const controlling = resolveControllingProcess(options.selfPid, options.processTable, options.env);
+  if (!controlling.ok) return controlling;
+  const worktreesDir = await resolveWorktreesDir(options);
+  const name = await resolveCurrentWorktreeName(options);
+  return writeClaim(
+    worktreesDir,
+    name,
+    {
+      sessionId: options.sessionId,
+      host: controlling.value.host,
+      pid: controlling.value.pid,
+      startedAt: controlling.value.startedAt
+    },
+    { fs: options.fs, writeToken: options.claimWriteToken }
+  );
+}
+
+// src/domains/hooks/session-start.ts
+var HOOK_SESSION_START_PAYLOAD = {
+  CWD: "cwd",
+  SESSION_ID: "session_id"
+};
+var HOOK_SESSION_START_ENV = {
+  CLAUDE_ENV_FILE: "CLAUDE_ENV_FILE",
+  CLAUDE_PROJECT_DIR: "CLAUDE_PROJECT_DIR",
+  CLAUDE_SESSION_ID: "CLAUDE_SESSION_ID",
+  CLAUDE_WORKTREE_CLAIMED: "CLAUDE_WORKTREE_CLAIMED",
+  CODEX_THREAD_ID: "CODEX_THREAD_ID",
+  PROJECT_DIR: "PROJECT_DIR"
+};
+var HOOK_SESSION_START_CLAIMED = {
+  FALSE: "0",
+  TRUE: "1"
+};
+var HOOK_ENV_FILE = {
+  ENCODING: "utf8",
+  EXPORT_PREFIX: "export "
+};
+var HOOK_SESSION_START_ERROR = {
+  ENV_FILE_WRITE_FAILED: "hook session-start env file write failed",
+  PAYLOAD_MALFORMED: "hook session-start payload must be a JSON object"
+};
+var ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var SAFE_SHELL_VALUE_PATTERN = /^[A-Za-z0-9_@%+=:,.-]+$/;
+var SINGLE_QUOTE = "'";
+var SHELL_SINGLE_QUOTE_ESCAPE = `'"'"'`;
+var ENV_FILE_HEADER = "# Managed by spx hook run session-start";
+var LINE_SEPARATOR = "\n";
+function parseHookSessionStartPayload(content) {
+  if (content === void 0 || content.trim().length === 0) return { ok: true, value: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return { ok: false, error: HOOK_SESSION_START_ERROR.PAYLOAD_MALFORMED };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, error: HOOK_SESSION_START_ERROR.PAYLOAD_MALFORMED };
+  }
+  const record = parsed;
+  return {
+    ok: true,
+    value: {
+      cwd: nonEmptyString(record[HOOK_SESSION_START_PAYLOAD.CWD]),
+      sessionId: nonEmptyString(record[HOOK_SESSION_START_PAYLOAD.SESSION_ID])
+    }
+  };
+}
+function resolveHookSessionStartSessionId(payload, env) {
+  return payload.sessionId ?? nonEmptyString(env[HOOK_SESSION_START_ENV.CLAUDE_SESSION_ID]) ?? nonEmptyString(env[HOOK_SESSION_START_ENV.CODEX_THREAD_ID]);
+}
+function resolveHookSessionStartProductDir(payload, cwd) {
+  return payload.cwd ?? cwd;
+}
+function resolveHookSessionStartEnvFile(env, explicitEnvFile) {
+  return nonEmptyString(explicitEnvFile) ?? nonEmptyString(env[HOOK_SESSION_START_ENV.CLAUDE_ENV_FILE]);
+}
+function renderHookSessionStartEnvFile(input) {
+  return [
+    "",
+    ENV_FILE_HEADER,
+    ...input.sessionId === void 0 ? [] : [renderExportLine(HOOK_SESSION_START_ENV.CLAUDE_SESSION_ID, input.sessionId)],
+    renderExportLine(HOOK_SESSION_START_ENV.CLAUDE_PROJECT_DIR, input.productDir),
+    renderExportLine(HOOK_SESSION_START_ENV.PROJECT_DIR, input.productDir),
+    renderExportLine(
+      HOOK_SESSION_START_ENV.CLAUDE_WORKTREE_CLAIMED,
+      input.claimed ? HOOK_SESSION_START_CLAIMED.TRUE : HOOK_SESSION_START_CLAIMED.FALSE
+    ),
+    ""
+  ].join(LINE_SEPARATOR);
+}
+function renderExportLine(name, value) {
+  if (!ENV_NAME_PATTERN.test(name)) throw new Error(`invalid environment variable name: ${name}`);
+  return `${HOOK_ENV_FILE.EXPORT_PREFIX}${name}=${shellQuote(value)}`;
+}
+function shellQuote(value) {
+  if (SAFE_SHELL_VALUE_PATTERN.test(value)) return value;
+  return `${SINGLE_QUOTE}${value.replaceAll(SINGLE_QUOTE, SHELL_SINGLE_QUOTE_ESCAPE)}${SINGLE_QUOTE}`;
+}
+function nonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? void 0 : trimmed;
+}
+
+// src/interfaces/hooks/session-start.ts
+var defaultHookEnvFileSystem = {
+  appendFile: async (path6, data, encoding) => {
+    await nodeAppendFile2(path6, data, encoding);
+  }
+};
+var ERROR_DETAIL_SEPARATOR3 = ": ";
+var EMPTY_HOOK_STDOUT = "";
+async function runSessionStartHook(options) {
+  const diagnostics = [];
+  const payloadResult = parseHookSessionStartPayload(options.content);
+  if (!payloadResult.ok) {
+    diagnostics.push(payloadResult.error);
+  }
+  const payload = payloadResult.ok ? payloadResult.value : {};
+  const productDir = resolveHookSessionStartProductDir(payload, options.cwd);
+  const sessionId = resolveHookSessionStartSessionId(payload, options.env);
+  let claimed = false;
+  if (sessionId !== void 0) {
+    const claim = await claimWorktreeOccupancy({
+      ...options,
+      cwd: productDir,
+      sessionId
+    });
+    if (claim.ok) {
+      claimed = true;
+    } else {
+      diagnostics.push(claim.error);
+    }
+  }
+  const envFile = resolveHookSessionStartEnvFile(options.env, options.envFile);
+  const envFileWritten = await writeEnvFileIfConfigured({
+    claimed,
+    envFile,
+    productDir,
+    sessionId,
+    envFileSystem: options.envFileSystem ?? defaultHookEnvFileSystem,
+    diagnostics
+  });
+  return {
+    ok: true,
+    value: {
+      claimed,
+      diagnostics,
+      envFileWritten,
+      productDir,
+      stdout: EMPTY_HOOK_STDOUT,
+      ...sessionId === void 0 ? {} : { sessionId }
+    }
+  };
+}
+async function writeEnvFileIfConfigured(options) {
+  if (options.envFile === void 0) return false;
+  try {
+    await options.envFileSystem.appendFile(
+      options.envFile,
+      renderHookSessionStartEnvFile({
+        claimed: options.claimed,
+        productDir: options.productDir,
+        sessionId: options.sessionId
+      }),
+      HOOK_ENV_FILE.ENCODING
+    );
+    return true;
+  } catch (error) {
+    options.diagnostics.push(
+      `${HOOK_SESSION_START_ERROR.ENV_FILE_WRITE_FAILED}${ERROR_DETAIL_SEPARATOR3}${error instanceof Error ? error.message : String(error)}`
+    );
+    return false;
+  }
+}
+
+// src/interfaces/hooks/registry.ts
+var HOOK_EVENT = {
+  SESSION_START: "session-start"
+};
+var HOOK_ERROR = {
+  UNKNOWN_EVENT: "unknown hook event"
+};
+function isHookEvent(event) {
+  return Object.values(HOOK_EVENT).includes(event);
+}
+async function runHookEvent(options) {
+  if (options.event === HOOK_EVENT.SESSION_START) return runSessionStartHook(options);
+  return { ok: false, error: `${HOOK_ERROR.UNKNOWN_EVENT}: ${options.event}` };
+}
+
+// src/interfaces/hooks/cli-runner.ts
+var HOOK_PROCESS_IO_EVENT = {
+  DATA: "data",
+  END: "end",
+  ERROR: "error"
+};
+var LINE_SEPARATOR2 = "\n";
+var ERROR_DETAIL_SEPARATOR4 = ": ";
+var STDIN_READ_ERROR = "hook stdin read failed";
+async function runHookCli(options) {
+  if (!isHookEvent(options.event)) {
+    options.io.writeStderr(`${HOOK_ERROR.UNKNOWN_EVENT}: ${sanitizeCliArgument(options.event)}`);
+    return { ok: false, error: HOOK_ERROR.UNKNOWN_EVENT };
+  }
+  const diagnostics = [];
+  const stdin = await options.io.readStdin();
+  const content = stdin.ok ? stdin.value : void 0;
+  if (!stdin.ok) diagnostics.push(stdin.error);
+  const runEvent = options.runEvent ?? runHookEvent;
+  const result = await runEvent({
+    claimWriteToken: options.claimWriteToken,
+    content,
+    cwd: options.cwd,
+    env: options.env,
+    envFile: options.envFile,
+    event: options.event,
+    fs: options.fs,
+    gitDeps: options.gitDeps,
+    onWarning: options.onWarning,
+    processTable: options.processTable,
+    selfPid: options.selfPid,
+    worktreesDir: options.worktreesDir
+  });
+  for (const diagnostic of diagnostics) {
+    options.io.writeStderr(diagnostic);
+  }
+  if (!result.ok) {
+    options.io.writeStderr(result.error);
+    return result;
+  }
+  for (const diagnostic of result.value.diagnostics) {
+    options.io.writeStderr(diagnostic);
+  }
+  if (result.value.stdout.length > 0) {
+    options.io.writeStdout(result.value.stdout);
+  }
+  return { ok: true, value: void 0 };
+}
+function createProcessHookIo(streams) {
+  return {
+    readStdin: async () => {
+      if (streams.stdin.isTTY) return { ok: true, value: void 0 };
+      return new Promise((resolve6) => {
+        let data = "";
+        streams.stdin.setEncoding("utf-8");
+        streams.stdin.on(HOOK_PROCESS_IO_EVENT.DATA, (chunk) => {
+          data += chunk;
+        });
+        streams.stdin.on(HOOK_PROCESS_IO_EVENT.END, () => {
+          resolve6({ ok: true, value: data.length === 0 ? void 0 : data });
+        });
+        streams.stdin.on(HOOK_PROCESS_IO_EVENT.ERROR, (error) => {
+          resolve6({ ok: false, error: formatStdinReadError(error) });
+        });
+      });
+    },
+    writeStdout: (content) => {
+      streams.stdout.write(`${content}${LINE_SEPARATOR2}`);
+    },
+    writeStderr: (content) => {
+      streams.stderr.write(`${content}${LINE_SEPARATOR2}`);
+    }
+  };
+}
+function formatStdinReadError(error) {
+  return `${STDIN_READ_ERROR}${ERROR_DETAIL_SEPARATOR4}${error instanceof Error ? error.message : String(error)}`;
+}
+var processHookIo = createProcessHookIo({
+  stdin: process.stdin,
+  stdout: process.stdout,
+  stderr: process.stderr
+});
+
+// src/lib/worktree-claim-write-token.ts
+import { randomBytes as nodeRandomBytes2 } from "crypto";
+var CLAIM_WRITE_TOKEN_BYTES = 8;
+function createClaimWriteToken(randomBytes = nodeRandomBytes2) {
+  return randomBytes(CLAIM_WRITE_TOKEN_BYTES).toString("hex");
+}
+
+// src/lib/worktree-occupancy-file-system.ts
+import {
+  mkdir as nodeMkdir2,
+  readFile as nodeReadFile2,
+  rename as nodeRename,
+  rm as nodeRm,
+  writeFile as nodeWriteFile2
+} from "fs/promises";
+var defaultOccupancyFileSystem = {
+  mkdir: async (path6, options) => {
+    await nodeMkdir2(path6, options);
+  },
+  writeFile: async (path6, data) => {
+    await nodeWriteFile2(path6, data);
+  },
+  rename: nodeRename,
+  readFile: nodeReadFile2,
+  rm: async (path6, options) => {
+    await nodeRm(path6, options);
+  }
+};
+
+// src/lib/worktree-process-table.ts
+import { spawnSync } from "child_process";
+import { hostname } from "os";
+var PS_COMMAND = "/bin/ps";
+var PS_FIELD = {
+  START_TIME: "lstart",
+  PARENT_PID: "ppid",
+  // The full command line, not `comm`: interpreted agent runtimes otherwise
+  // report only the interpreter basename and miss the agent-command match.
+  COMMAND: "args"
+};
+var SIGNAL_LIVENESS_PROBE = 0;
+var PROCESS_EXISTS_NO_PERMISSION = "EPERM";
+var PID_RADIX2 = 10;
+var STABLE_PS_ENV = { ...process.env, TZ: "UTC", LC_ALL: "C" };
+function psField(pid, field) {
+  const result = spawnSync(PS_COMMAND, ["-o", `${field}=`, "-p", String(pid)], {
+    encoding: "utf8",
+    env: STABLE_PS_ENV
+  });
+  if (result.status !== 0 || typeof result.stdout !== "string") return void 0;
+  const value = result.stdout.trim();
+  return value.length > 0 ? value : void 0;
+}
+var defaultProcessTable = {
+  currentHost: () => hostname(),
+  isAlive: (pid) => {
+    try {
+      process.kill(pid, SIGNAL_LIVENESS_PROBE);
+      return true;
+    } catch (error) {
+      return hasErrorCode(error, PROCESS_EXISTS_NO_PERMISSION);
+    }
+  },
+  startTimeOf: (pid) => psField(pid, PS_FIELD.START_TIME),
+  parentOf: (pid) => {
+    const value = psField(pid, PS_FIELD.PARENT_PID);
+    if (value === void 0) return void 0;
+    const parsed = Number.parseInt(value, PID_RADIX2);
+    return Number.isInteger(parsed) ? parsed : void 0;
+  },
+  commandOf: (pid) => psField(pid, PS_FIELD.COMMAND)
+};
+
+// src/interfaces/cli/hook.ts
+var HOOK_CLI = {
+  COMMAND: "hook",
+  RUN: "run",
+  EVENT_ARGUMENT: "<event>",
+  ENV_FILE_FLAG: "--hook-env-file",
+  WORKTREES_DIR_FLAG: "--worktrees-dir"
+};
+var HOOK_DOMAIN_DESCRIPTION = "Run host lifecycle hook events";
+function registerHookCommands(hookCmd) {
+  hookCmd.command(`${HOOK_CLI.RUN} ${HOOK_CLI.EVENT_ARGUMENT}`).description("Run a hook lifecycle event").option(`${HOOK_CLI.ENV_FILE_FLAG} <path>`, "Hook env file to append; defaults to $CLAUDE_ENV_FILE").option(`${HOOK_CLI.WORKTREES_DIR_FLAG} <path>`, "Explicit .spx/worktrees directory").action(async (event, options) => {
+    const result = await runHookCli({
+      claimWriteToken: createClaimWriteToken(),
+      cwd: process.cwd(),
+      env: process.env,
+      envFile: options.hookEnvFile,
+      event,
+      fs: defaultOccupancyFileSystem,
+      gitDeps: defaultGitDependencies,
+      io: processHookIo,
+      onWarning: writeWarning,
+      processTable: defaultProcessTable,
+      selfPid: process.pid,
+      worktreesDir: options.worktreesDir
+    });
+    if (!result.ok) process.exit(1);
+  });
+}
+var hookDomain = {
+  name: HOOK_CLI.COMMAND,
+  description: HOOK_DOMAIN_DESCRIPTION,
+  register: (program2) => {
+    const hookCmd = program2.command(HOOK_CLI.COMMAND).description(HOOK_DOMAIN_DESCRIPTION);
+    registerHookCommands(hookCmd);
+  }
+};
+
+// src/commands/session/archive.ts
+import { mkdir, rename, stat } from "fs/promises";
+import { dirname as dirname4, join as join8 } from "path";
+
+// src/domains/session/archive.ts
+var SESSION_FILE_EXTENSION = ".md";
+var ARCHIVABLE_DIR_KEYS = {
+  TODO: "todoDir",
+  DOING: "doingDir"
+};
+var ARCHIVABLE_DIR_KEY = {
+  todo: ARCHIVABLE_DIR_KEYS.TODO,
+  doing: ARCHIVABLE_DIR_KEYS.DOING
+};
+function buildArchivePaths(sessionId, currentStatus, config) {
+  const filename = `${sessionId}${SESSION_FILE_EXTENSION}`;
+  const dirKey = ARCHIVABLE_DIR_KEY[currentStatus];
+  const sourceDir = config[dirKey];
+  return {
+    source: `${sourceDir}/${filename}`,
+    target: `${config.archiveDir}/${filename}`
+  };
+}
+var ARCHIVE_SEARCH_ORDER = ["todo", "doing"];
+function findSessionForArchive(existingPaths) {
+  if (existingPaths.archive !== null) {
+    return null;
+  }
+  for (const status of ARCHIVE_SEARCH_ORDER) {
+    if (existingPaths[status] !== null) {
+      return { status, path: existingPaths[status] };
+    }
+  }
+  return null;
+}
+
+// src/domains/session/batch.ts
+var BatchError = class extends Error {
+  results;
+  constructor(results) {
+    const failures = results.filter((r) => !r.ok);
+    const successes = results.filter((r) => r.ok);
+    super(
+      `${failures.length} of ${results.length} operations failed. ${successes.length} succeeded.`
+    );
+    this.name = "BatchError";
+    this.results = results;
+  }
+};
+async function processBatch(ids, handler) {
+  const results = [];
+  for (const id of ids) {
+    try {
+      const output2 = await handler(id);
+      results.push({ id, ok: true, message: output2 });
+    } catch (error) {
+      const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+      results.push({ id, ok: false, message });
+    }
+  }
+  const output = results.map((r) => r.ok ? r.message : `Error (${r.id}): ${r.message}`).join("\n\n");
+  const hasFailures = results.some((r) => !r.ok);
+  if (hasFailures) {
+    const err = new BatchError(results);
+    err.message = `${err.message}
+
+${output}`;
+    throw err;
+  }
+  return output;
+}
+
+// src/domains/session/handoff-base-checklist.ts
+var SESSION_HANDOFF_BASE_ERROR_NAME = "SessionHandoffBaseError";
+var HANDOFF_BASE_MARK = {
+  MET: "\u2713",
+  UNMET: "\u2717"
+};
+var HANDOFF_BASE_PREREQUISITE_LABEL = {
+  CLEAN_WORKING_TREE: "working tree is clean",
+  DETACHED_AT_DEFAULT_TIP: "HEAD is detached at the default-branch tip"
+};
+var HANDOFF_BASE_REMEDY = {
+  /** Unclean working tree: commit, or hand off from the main checkout. */
+  COMMIT_OR_MAIN_CHECKOUT: "commit the changes, or run handoff from the main checkout",
+  /** Off the default-branch tip: detach to it, or hand off from the main checkout. */
+  DETACH_TO_TIP_OR_MAIN_CHECKOUT: "detach HEAD to the default-branch tip, or run handoff from the main checkout",
+  /** Default branch unresolved: only the main checkout can anchor the base. */
+  MAIN_CHECKOUT_ONLY: "run handoff from the main checkout"
+};
+var HANDOFF_BASE_FACT_LABEL = {
+  DEFAULT_BRANCH: "default branch",
+  DEFAULT_TIP: "origin tip",
+  HEAD: "HEAD",
+  CURRENT_WORKTREE: "current worktree",
+  MAIN_CHECKOUT: "main checkout"
+};
+var HANDOFF_BASE_UNRESOLVED = "unresolved";
+var CHECKLIST_INDENT = "  ";
+var REMEDY_SEPARATOR = " \u2014 ";
+var CHECKLIST_HEADER = `${SESSION_HANDOFF_BASE_ERROR_NAME}: cannot create a handoff session from this worktree \u2014 it is not the main checkout.`;
+function renderFactLine(label, value) {
+  return `${CHECKLIST_INDENT}${label}: ${value ?? HANDOFF_BASE_UNRESOLVED}`;
+}
+function renderPrerequisiteLine(prerequisite) {
+  const mark = prerequisite.met ? HANDOFF_BASE_MARK.MET : HANDOFF_BASE_MARK.UNMET;
+  const base = `${CHECKLIST_INDENT}${mark} ${prerequisite.label}`;
+  return prerequisite.met ? base : `${base}${REMEDY_SEPARATOR}${prerequisite.remedy}`;
+}
+function renderHandoffBaseChecklist(checklist) {
+  return [
+    CHECKLIST_HEADER,
+    renderFactLine(HANDOFF_BASE_FACT_LABEL.DEFAULT_BRANCH, checklist.defaultBranch),
+    renderFactLine(HANDOFF_BASE_FACT_LABEL.DEFAULT_TIP, checklist.defaultTipSha),
+    renderFactLine(HANDOFF_BASE_FACT_LABEL.HEAD, checklist.headSha),
+    renderFactLine(HANDOFF_BASE_FACT_LABEL.CURRENT_WORKTREE, checklist.currentWorktreePath),
+    renderFactLine(HANDOFF_BASE_FACT_LABEL.MAIN_CHECKOUT, checklist.mainCheckoutPath),
+    ...checklist.prerequisites.map(renderPrerequisiteLine)
+  ].join("\n");
+}
+
+// src/domains/session/errors.ts
+var SessionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SessionError";
+  }
+};
+var SessionNotFoundError = class extends SessionError {
+  /** The session ID that was not found */
+  sessionId;
+  constructor(sessionId) {
+    super(`Session not found: ${sessionId}. Check the session ID and try again.`);
+    this.name = "SessionNotFoundError";
+    this.sessionId = sessionId;
+  }
+};
+var SessionNotAvailableError = class extends SessionError {
+  /** The session ID that is not available */
+  sessionId;
+  constructor(sessionId) {
+    super(`Session not available: ${sessionId}. It may have been claimed by another agent.`);
+    this.name = "SessionNotAvailableError";
+    this.sessionId = sessionId;
+  }
+};
+var SessionInvalidContentError = class extends SessionError {
+  constructor(reason) {
+    super(`Invalid session content: ${reason}`);
+    this.name = "SessionInvalidContentError";
+  }
+};
+var SessionInvalidGoalError = class extends SessionError {
+  constructor() {
+    super("Invalid session goal: goal must be a non-empty string.");
+    this.name = "SessionInvalidGoalError";
+  }
+};
+var SessionInvalidFieldError = class extends SessionError {
+  /** The unknown field token the caller supplied. */
+  field;
+  /** The full set of valid field names. */
+  validFields;
   constructor(field, validFields) {
     super(`Invalid field: "${field}". Valid fields: ${validFields.join(", ")}`);
     this.name = "SessionInvalidFieldError";
@@ -3733,7 +4365,7 @@ var SessionInvalidJsonHeaderError = class extends SessionError {
 };
 
 // src/commands/session/resolve-config.ts
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/config/defaults.ts
 var DEFAULT_CONFIG = {
@@ -3753,18 +4385,18 @@ async function resolveSessionConfig(options = {}) {
   if (sessionsDir) {
     return {
       config: {
-        todoDir: join6(sessionsDir, statusDirs2.todo),
-        doingDir: join6(sessionsDir, statusDirs2.doing),
-        archiveDir: join6(sessionsDir, statusDirs2.archive)
+        todoDir: join7(sessionsDir, statusDirs2.todo),
+        doingDir: join7(sessionsDir, statusDirs2.doing),
+        archiveDir: join7(sessionsDir, statusDirs2.archive)
       }
     };
   }
   const { sessionsDir: baseDir, warning } = await resolveSessionsScopeDir({ cwd, deps });
   return {
     config: {
-      todoDir: join6(baseDir, statusDirs2.todo),
-      doingDir: join6(baseDir, statusDirs2.doing),
-      archiveDir: join6(baseDir, statusDirs2.archive)
+      todoDir: join7(baseDir, statusDirs2.todo),
+      doingDir: join7(baseDir, statusDirs2.doing),
+      archiveDir: join7(baseDir, statusDirs2.archive)
     },
     warning
   };
@@ -3801,9 +4433,9 @@ async function fileExists(path6) {
 }
 async function probeSessionPaths(sessionId, config) {
   const filename = `${sessionId}${SESSION_FILE_EXTENSION}`;
-  const todoPath = join7(config.todoDir, filename);
-  const doingPath = join7(config.doingDir, filename);
-  const archivePath = join7(config.archiveDir, filename);
+  const todoPath = join8(config.todoDir, filename);
+  const doingPath = join8(config.doingDir, filename);
+  const archivePath = join8(config.archiveDir, filename);
   return {
     todo: await fileExists(todoPath) ? todoPath : null,
     doing: await fileExists(doingPath) ? doingPath : null,
@@ -3824,7 +4456,7 @@ async function resolveArchivePaths(sessionId, config) {
 }
 async function archiveSingle(sessionId, config) {
   const { source, target } = await resolveArchivePaths(sessionId, config);
-  await mkdir(dirname3(target), { recursive: true });
+  await mkdir(dirname4(target), { recursive: true });
   await rename(source, target);
   return `${SESSION_ARCHIVE_OUTPUT.ARCHIVED}: ${sessionId}
 ${SESSION_ARCHIVE_OUTPUT.ARCHIVE_LOCATION}: ${target}`;
@@ -3847,7 +4479,7 @@ function resolveDeletePath(sessionId, existingPaths) {
 }
 
 // src/domains/session/show.ts
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 
 // src/domains/session/list.ts
 import { parse as parseYaml2 } from "yaml";
@@ -3898,6 +4530,7 @@ var SESSION_PRIORITY = {
 };
 var SESSION_STATUSES = ["todo", "doing", "archive"];
 var DEFAULT_LIST_STATUSES = ["doing", "todo"];
+var CLAIMABLE_STATUS = SESSION_STATUSES[0];
 var PRIORITY_ORDER = {
   [SESSION_PRIORITY.HIGH]: 0,
   [SESSION_PRIORITY.MEDIUM]: 1,
@@ -4064,12 +4697,12 @@ var SESSION_SHOW_LABEL = {
 };
 var SESSION_SHOW_SEPARATOR_CHAR = "\u2500";
 var SESSION_SHOW_SEPARATOR_WIDTH = 40;
-var sessionsBaseDir = join8(STATE_STORE_PATH.SPX_DIR, STATE_STORE_PATH.SESSIONS_SCOPE);
+var sessionsBaseDir = join9(STATE_STORE_PATH.SPX_DIR, STATE_STORE_PATH.SESSIONS_SCOPE);
 var { statusDirs } = DEFAULT_CONFIG.sessions;
 var DEFAULT_SESSION_CONFIG = {
-  todoDir: join8(sessionsBaseDir, statusDirs.todo),
-  doingDir: join8(sessionsBaseDir, statusDirs.doing),
-  archiveDir: join8(sessionsBaseDir, statusDirs.archive)
+  todoDir: join9(sessionsBaseDir, statusDirs.todo),
+  doingDir: join9(sessionsBaseDir, statusDirs.doing),
+  archiveDir: join9(sessionsBaseDir, statusDirs.archive)
 };
 var SEARCH_ORDER = [...SESSION_STATUSES];
 function resolveSessionPaths(id, config = DEFAULT_SESSION_CONFIG) {
@@ -4127,7 +4760,7 @@ async function deleteCommand(options) {
 
 // src/commands/session/handoff.ts
 import { mkdir as mkdir2, writeFile } from "fs/promises";
-import { join as join9, resolve as resolve3 } from "path";
+import { join as join10, resolve as resolve4 } from "path";
 import { stringify as stringifyYaml3 } from "yaml";
 
 // src/domains/session/create.ts
@@ -4405,8 +5038,8 @@ async function handoffCommand(options) {
   const yaml = stringifyYaml3(frontMatterObject, { defaultStringType: "QUOTE_DOUBLE" }).trimEnd();
   const fullContent = `${SESSION_FRONT_MATTER_OPEN}${yaml}${SESSION_FRONT_MATTER_CLOSE}${body}`;
   const filename = `${sessionId}.md`;
-  const sessionPath = join9(config.todoDir, filename);
-  const absolutePath = resolve3(sessionPath);
+  const sessionPath = join10(config.todoDir, filename);
+  const absolutePath = resolve4(sessionPath);
   await mkdir2(config.todoDir, { recursive: true });
   await writeFile(sessionPath, fullContent, "utf-8");
   const output = `Created handoff session <HANDOFF_ID>${sessionId}</HANDOFF_ID>
@@ -4416,7 +5049,7 @@ async function handoffCommand(options) {
 
 // src/commands/session/list.ts
 import { readdir, readFile as readFile3 } from "fs/promises";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 var SESSION_LIST_FORMAT = {
   TEXT: "text",
   JSON: "json"
@@ -4430,7 +5063,7 @@ async function loadSessionsFromDir(dir, status) {
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
-      const filePath = join10(dir, file);
+      const filePath = join11(dir, file);
       const content = await readFile3(filePath, "utf-8");
       const metadata = parseSessionMetadata(content);
       sessions.push({
@@ -4503,7 +5136,7 @@ async function listCommand(options) {
 
 // src/commands/session/pickup.ts
 import { mkdir as mkdir3, readdir as readdir2, readFile as readFile4, rename as rename2 } from "fs/promises";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 
 // src/domains/session/pickup.ts
 function buildClaimPaths(sessionId, config) {
@@ -4539,7 +5172,6 @@ function selectBestSession(sessions) {
 }
 
 // src/commands/session/pickup.ts
-var PICKUP_SOURCE_STATUS = SESSION_STATUSES[0];
 var PICKUP_TARGET_STATUS = SESSION_STATUSES[1];
 async function loadTodoSessions(config) {
   try {
@@ -4548,12 +5180,12 @@ async function loadTodoSessions(config) {
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
-      const filePath = join11(config.todoDir, file);
+      const filePath = join12(config.todoDir, file);
       const content = await readFile4(filePath, "utf-8");
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
-        status: PICKUP_SOURCE_STATUS,
+        status: CLAIMABLE_STATUS,
         path: filePath,
         metadata
       });
@@ -4602,9 +5234,15 @@ async function pickupCommand(options) {
   return processBatch(options.sessionIds, (id) => pickupSingle(id, config));
 }
 
+// src/commands/session/pick.ts
+async function loadPickCandidates(options) {
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
+  return loadTodoSessions(config);
+}
+
 // src/commands/session/prune.ts
 import { readdir as readdir3, readFile as readFile5, unlink as unlink2 } from "fs/promises";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 
 // src/domains/session/prune.ts
 var DEFAULT_KEEP_COUNT = 5;
@@ -4653,7 +5291,7 @@ async function loadArchiveSessions(config) {
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
-      const filePath = join12(config.archiveDir, file);
+      const filePath = join13(config.archiveDir, file);
       const content = await readFile5(filePath, "utf-8");
       const metadata = parseSessionMetadata(content);
       sessions.push({
@@ -4871,6 +5509,190 @@ Output:
   <PICKUP_ID>session-id</PICKUP_ID> tag for each claimed session
 `;
 
+// src/interfaces/cli/session/pick/run-picker.tsx
+import { render } from "ink";
+
+// src/interfaces/cli/session/pick/SessionPicker.tsx
+import { Box, Text, useInput } from "ink";
+import { useState } from "react";
+
+// src/domains/session/pick-model.ts
+var PICKER_ACTION = {
+  MOVE: "move",
+  FILTER_APPEND: "filter-append",
+  FILTER_DELETE: "filter-delete",
+  CLAIM: "claim",
+  CANCEL: "cancel"
+};
+function buildCandidates(sessions) {
+  const claimable = sessions.filter((session) => session.status === CLAIMABLE_STATUS);
+  return sortSessions(claimable);
+}
+function filterCandidates(candidates, query) {
+  const needle = query.trim().toLowerCase();
+  if (needle.length === 0) {
+    return [...candidates];
+  }
+  return candidates.filter((session) => {
+    const haystack = `${session.id}
+${session.metadata.goal}
+${session.metadata.next_step}`.toLowerCase();
+    return haystack.includes(needle);
+  });
+}
+function visibleCandidates(state) {
+  return filterCandidates(state.candidates, state.query);
+}
+function selectedSession(state) {
+  const visible = visibleCandidates(state);
+  return visible[state.selectedIndex] ?? null;
+}
+function initialPickerState(sessions) {
+  return { candidates: buildCandidates(sessions), query: "", selectedIndex: 0 };
+}
+function keyToAction(key) {
+  if (key.downArrow) return { type: PICKER_ACTION.MOVE, delta: 1 };
+  if (key.upArrow) return { type: PICKER_ACTION.MOVE, delta: -1 };
+  if (key.return) return { type: PICKER_ACTION.CLAIM };
+  if (key.escape) return { type: PICKER_ACTION.CANCEL };
+  if (key.backspace || key.delete) return { type: PICKER_ACTION.FILTER_DELETE };
+  if (key.input.length > 0) return { type: PICKER_ACTION.FILTER_APPEND, char: key.input };
+  return null;
+}
+function clampIndex(index, count) {
+  const upper = Math.max(0, count - 1);
+  if (index < 0) return 0;
+  if (index > upper) return upper;
+  return index;
+}
+function reducePicker(state, action) {
+  switch (action.type) {
+    case PICKER_ACTION.MOVE: {
+      const count = visibleCandidates(state).length;
+      return { ...state, selectedIndex: clampIndex(state.selectedIndex + action.delta, count) };
+    }
+    case PICKER_ACTION.FILTER_APPEND: {
+      const query = state.query + action.char;
+      const count = filterCandidates(state.candidates, query).length;
+      return { ...state, query, selectedIndex: clampIndex(state.selectedIndex, count) };
+    }
+    case PICKER_ACTION.FILTER_DELETE: {
+      const query = state.query.slice(0, -1);
+      const count = filterCandidates(state.candidates, query).length;
+      return { ...state, query, selectedIndex: clampIndex(state.selectedIndex, count) };
+    }
+    case PICKER_ACTION.CLAIM:
+    case PICKER_ACTION.CANCEL:
+      return state;
+  }
+}
+
+// src/interfaces/cli/session/pick/SessionPicker.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var SESSION_PICKER_EMPTY_TEXT = "No claimable sessions.";
+var PRIORITY_COLOR = {
+  [SESSION_PRIORITY.HIGH]: "red",
+  [SESSION_PRIORITY.MEDIUM]: "yellow",
+  [SESSION_PRIORITY.LOW]: "gray"
+};
+function toPickerKey(input, key) {
+  return {
+    input,
+    upArrow: key.upArrow,
+    downArrow: key.downArrow,
+    return: key.return,
+    escape: key.escape,
+    backspace: key.backspace,
+    delete: key.delete
+  };
+}
+function SessionRow({ session, selected }) {
+  const priority = session.metadata.priority;
+  const marker = selected ? "\u276F" : " ";
+  const badge = priority === DEFAULT_PRIORITY ? "" : ` [${priority}]`;
+  return /* @__PURE__ */ jsxs(Text, { color: selected ? "cyan" : void 0, children: [
+    marker,
+    " ",
+    session.id,
+    /* @__PURE__ */ jsx(Text, { color: PRIORITY_COLOR[priority], children: badge }),
+    " ",
+    session.metadata.goal
+  ] });
+}
+function PreviewPane({ session }) {
+  if (session === null) {
+    return /* @__PURE__ */ jsx(Box, { flexDirection: "column", marginTop: 1, children: /* @__PURE__ */ jsx(Text, { dimColor: true, children: SESSION_PICKER_EMPTY_TEXT }) });
+  }
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginTop: 1, children: [
+    /* @__PURE__ */ jsxs(Text, { children: [
+      /* @__PURE__ */ jsx(Text, { bold: true, children: "goal:" }),
+      session.metadata.goal
+    ] }),
+    /* @__PURE__ */ jsxs(Text, { children: [
+      /* @__PURE__ */ jsx(Text, { bold: true, children: "next:" }),
+      session.metadata.next_step
+    ] })
+  ] });
+}
+function SessionPicker({ sessions, onClaim, onCancel }) {
+  const [state, setState] = useState(() => initialPickerState(sessions));
+  useInput((input, key) => {
+    const action = keyToAction(toPickerKey(input, key));
+    if (action === null) return;
+    if (action.type === PICKER_ACTION.CLAIM) {
+      const selected2 = selectedSession(state);
+      if (selected2 !== null) onClaim(selected2);
+      return;
+    }
+    if (action.type === PICKER_ACTION.CANCEL) {
+      onCancel();
+      return;
+    }
+    setState((previous) => reducePicker(previous, action));
+  });
+  const visible = visibleCandidates(state);
+  const selected = selectedSession(state);
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsxs(Text, { children: [
+      /* @__PURE__ */ jsx(Text, { bold: true, children: "Pick a session to claim" }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: "(type to filter, \u2191\u2193 to move, \u23CE to claim, esc to cancel)" })
+    ] }),
+    /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+      "filter: ",
+      state.query
+    ] }),
+    visible.length === 0 ? /* @__PURE__ */ jsx(Text, { dimColor: true, children: SESSION_PICKER_EMPTY_TEXT }) : visible.map((session, index) => /* @__PURE__ */ jsx(SessionRow, { session, selected: index === state.selectedIndex }, session.id)),
+    /* @__PURE__ */ jsx(PreviewPane, { session: selected })
+  ] });
+}
+
+// src/interfaces/cli/session/pick/run-picker.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var PICK_NON_TTY_MESSAGE = "session pick requires an interactive terminal. Use `spx session pickup --auto` or `spx session pickup <id>` in a non-interactive context.";
+async function runPicker(sessions) {
+  let claimed = null;
+  let unmount = () => {
+  };
+  const instance = render(
+    /* @__PURE__ */ jsx2(
+      SessionPicker,
+      {
+        sessions,
+        onClaim: (session) => {
+          claimed = session;
+          unmount();
+        },
+        onCancel: () => {
+          unmount();
+        }
+      }
+    )
+  );
+  unmount = instance.unmount;
+  await instance.waitUntilExit();
+  return claimed;
+}
+
 // src/interfaces/cli/session.ts
 async function readStdin() {
   if (process.stdin.isTTY) {
@@ -4909,6 +5731,29 @@ function registerSessionCommands(sessionCmd) {
       handleError(error);
     }
   });
+  sessionCmd.command("pick").description("Interactively pick and claim a session (move from todo to doing)").option("--sessions-dir <path>", "Custom sessions directory").action(async (options) => {
+    try {
+      if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(PICK_NON_TTY_MESSAGE);
+        process.exit(1);
+      }
+      const sessions = await loadPickCandidates({
+        sessionsDir: options.sessionsDir,
+        onWarning: writeWarning
+      });
+      const claimed = await runPicker(sessions);
+      if (claimed !== null) {
+        const output = await pickupCommand({
+          sessionIds: [claimed.id],
+          sessionsDir: options.sessionsDir,
+          onWarning: writeWarning
+        });
+        console.log(output);
+      }
+    } catch (error) {
+      handleError(error);
+    }
+  });
   sessionCmd.command("todo").description("List todo sessions").option("--json", "Output as JSON").option("--fields <fields>", "Comma-separated fields to emit as JSON (implies --json)").option("--sessions-dir <path>", "Custom sessions directory").action(async (options) => {
     try {
       const output = await listCommand({
@@ -5043,7 +5888,7 @@ var sessionDomain = {
 
 // src/lib/spec-tree/index.ts
 import { readdir as readdir5, readFile as readFile7 } from "fs/promises";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 var SPEC_TREE_FIELD_KEY = {
   VERSION: "version",
   PRODUCT: "product",
@@ -5127,7 +5972,7 @@ function createFilesystemSpecTreeSource(options) {
       if (ref.path === void 0) {
         throw new Error("Filesystem source refs require a path");
       }
-      return readFile7(join13(options.productDir, ref.path), SPEC_TREE_TEXT_ENCODING);
+      return readFile7(join14(options.productDir, ref.path), SPEC_TREE_TEXT_ENCODING);
     }
   };
 }
@@ -5409,7 +6254,7 @@ function compareOrderedEntries(left, right) {
 }
 async function* readFilesystemSourceEntries(productDir, registry, schemaVersions, includePath) {
   yield* walkFilesystemDirectory({
-    absolutePath: join13(productDir, SPEC_TREE_CONFIG.ROOT_DIRECTORY),
+    absolutePath: join14(productDir, SPEC_TREE_CONFIG.ROOT_DIRECTORY),
     relativePath: SPEC_TREE_EMPTY_RELATIVE_PATH,
     registry,
     schemaVersions,
@@ -5438,7 +6283,7 @@ async function* walkFilesystemDirectory(context) {
     if (sourceEntry !== null) yield sourceEntry;
     if (entry.isDirectory() && shouldDescendIntoDirectory(sourceEntry)) {
       yield* walkFilesystemDirectory({
-        absolutePath: join13(context.absolutePath, entry.name),
+        absolutePath: join14(context.absolutePath, entry.name),
         relativePath,
         registry: context.registry,
         schemaVersions: context.schemaVersions,
@@ -5584,14 +6429,14 @@ function formatNextNode(node) {
 
 // src/commands/testing/discovery.ts
 import { readdir as readdir6 } from "fs/promises";
-import { join as join14, relative, sep } from "path";
+import { join as join15, relative, sep } from "path";
 var TESTS_DIRECTORY_NAME = SPEC_TREE_EVIDENCE_FILE.DIRECTORY_NAME;
 var SPEC_ROOT_DIRECTORY = SPEC_TREE_CONFIG.ROOT_DIRECTORY;
 var POSIX_SEPARATOR = "/";
 var ERROR_CODE_NOT_FOUND2 = "ENOENT";
 async function discoverTestFiles(productDir) {
   const found = [];
-  await collectTestFiles(join14(productDir, SPEC_ROOT_DIRECTORY), false, found);
+  await collectTestFiles(join15(productDir, SPEC_ROOT_DIRECTORY), false, found);
   return found.map((absolute) => toPosixRelative(productDir, absolute)).sort(compareAscii);
 }
 async function collectTestFiles(directory, insideTestsDir, found) {
@@ -5603,7 +6448,7 @@ async function collectTestFiles(directory, insideTestsDir, found) {
     throw error;
   }
   for (const entry of entries) {
-    const childPath = join14(directory, entry.name);
+    const childPath = join15(directory, entry.name);
     if (entry.isDirectory()) {
       await collectTestFiles(childPath, insideTestsDir || entry.name === TESTS_DIRECTORY_NAME, found);
     } else if (insideTestsDir && entry.isFile()) {
@@ -5685,11 +6530,11 @@ async function runTests(options, deps) {
 }
 
 // src/commands/testing/run-command.ts
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 
 // src/testing/run-state.ts
 import { createHash as createHash4 } from "crypto";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 var TEST_RUN_STATE_STATUS = {
   PASSED: "passed",
   FAILED: "failed",
@@ -5776,12 +6621,12 @@ async function readTestingRuns(productDir, options = {}) {
     if (hasErrorCode(error, TESTING_RUN_STATE_ERROR_CODE.NOT_FOUND)) {
       return { ok: true, value: { terminalRuns: [], incompleteRuns: [] } };
     }
-    return { ok: false, error: toErrorMessage2(error) };
+    return { ok: false, error: toErrorMessage3(error) };
   }
   const terminalRuns = [];
   const incompleteRuns = [];
   for (const entry of entries.filter(isTestRunFileEntry)) {
-    const runFilePath = join15(runsDir2, entry.name);
+    const runFilePath = join16(runsDir2, entry.name);
     const stateResult = await readTestRunStatePath(runFilePath, fs7);
     if (stateResult.ok) {
       terminalRuns.push({ runFileName: entry.name, runFilePath, state: stateResult.value });
@@ -5858,7 +6703,7 @@ async function readTestRunStatePath(runFilePath, fs7) {
     return {
       ok: false,
       reason: hasErrorCode(error, TESTING_RUN_STATE_ERROR_CODE.NOT_FOUND) ? TESTING_RUN_STATE_INCOMPLETE_REASON.MISSING_STATE : TESTING_RUN_STATE_INCOMPLETE_REASON.IO_ERROR,
-      error: toErrorMessage2(error)
+      error: toErrorMessage3(error)
     };
   }
   const latest = latestNonEmptyJsonlLine(content);
@@ -6010,7 +6855,7 @@ function isRecord4(value) {
 function sha256Hex(value) {
   return createHash4(SHA256_ALGORITHM2).update(value).digest(HEX_ENCODING3);
 }
-function toErrorMessage2(error) {
+function toErrorMessage3(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
@@ -6047,7 +6892,7 @@ function coveredTestPaths(dispatch) {
 async function readCoveredContents(productDir, paths, fs7) {
   const entries = [];
   for (const path6 of paths) {
-    entries.push({ path: path6, content: await fs7.readFile(join16(productDir, path6), TEXT_ENCODING) });
+    entries.push({ path: path6, content: await fs7.readFile(join17(productDir, path6), TEXT_ENCODING) });
   }
   return entries;
 }
@@ -6058,7 +6903,7 @@ async function readProductInputEntries(productDir, paths, fs7) {
       entries.push({
         [PRODUCT_INPUT_FIELDS.PATH]: path6,
         [PRODUCT_INPUT_FIELDS.PRESENT]: true,
-        [PRODUCT_INPUT_FIELDS.CONTENT]: await fs7.readFile(join16(productDir, path6), TEXT_ENCODING)
+        [PRODUCT_INPUT_FIELDS.CONTENT]: await fs7.readFile(join17(productDir, path6), TEXT_ENCODING)
       });
     } catch (error) {
       if (!hasErrorCode(error, TESTING_RUN_STATE_ERROR_CODE.NOT_FOUND)) throw error;
@@ -6241,11 +7086,11 @@ function serializeNodeStatus(state) {
 }
 
 // src/lib/node-status/provider.ts
-import { join as join18 } from "path";
+import { join as join19 } from "path";
 
 // src/lib/node-status/read.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 var NODE_STATUS_FILENAME = "spx.status.json";
 var NODE_STATUS_VALUES = new Set(Object.values(SPEC_TREE_NODE_STATE));
 function isNodeError2(error) {
@@ -6255,7 +7100,7 @@ function isSpecTreeNodeState(value) {
   return typeof value === "string" && NODE_STATUS_VALUES.has(value);
 }
 function readNodeStatus(nodeDir) {
-  const filePath = join17(nodeDir, NODE_STATUS_FILENAME);
+  const filePath = join18(nodeDir, NODE_STATUS_FILENAME);
   let content;
   try {
     content = readFileSync2(filePath, "utf8");
@@ -6277,7 +7122,7 @@ function readNodeStatus(nodeDir) {
 
 // src/lib/node-status/provider.ts
 function nodeDirectory(productDir, node) {
-  return join18(productDir, SPEC_TREE_CONFIG.ROOT_DIRECTORY, node.id);
+  return join19(productDir, SPEC_TREE_CONFIG.ROOT_DIRECTORY, node.id);
 }
 function createNodeStatusProvider(productDir) {
   return {
@@ -6289,7 +7134,7 @@ function createNodeStatusProvider(productDir) {
 
 // src/lib/node-status/update.ts
 import { mkdir as mkdir4, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname4, join as join19 } from "path";
+import { dirname as dirname5, join as join20 } from "path";
 var NODE_STATUS_TEXT_ENCODING = "utf8";
 async function updateNodeStatus(options) {
   const { productDir, resolveOutcome } = options;
@@ -6327,8 +7172,8 @@ function isNodeExcluded(ignoreReader, node) {
   return ignoreReader.isUnderIgnoreSource(reference);
 }
 async function writeNodeStatus(productDir, nodeId, state) {
-  const filePath = join19(productDir, SPEC_TREE_CONFIG.ROOT_DIRECTORY, nodeId, NODE_STATUS_FILENAME);
-  await mkdir4(dirname4(filePath), { recursive: true });
+  const filePath = join20(productDir, SPEC_TREE_CONFIG.ROOT_DIRECTORY, nodeId, NODE_STATUS_FILENAME);
+  await mkdir4(dirname5(filePath), { recursive: true });
   await writeFile2(filePath, serializeNodeStatus(state), NODE_STATUS_TEXT_ENCODING);
 }
 
@@ -6442,7 +7287,7 @@ function formatNodeLabel(node) {
 }
 
 // src/testing/languages/python.ts
-import { basename as basename2, dirname as dirname5, join as join20 } from "path/posix";
+import { basename as basename3, dirname as dirname6, join as join21 } from "path/posix";
 
 // src/validation/discovery/language-finder.ts
 import fs5 from "fs";
@@ -6507,16 +7352,16 @@ var PYTHON_TEST_FILE_PREFIX = "test_";
 var PYTHON_TEST_FILE_EXTENSION = ".py";
 var PYTHON_TEST_FILE_PATTERNS = [`${PYTHON_TEST_FILE_PREFIX}*${PYTHON_TEST_FILE_EXTENSION}`];
 function matchesTestFile(filePath) {
-  return basename2(filePath).startsWith(PYTHON_TEST_FILE_PREFIX) && filePath.endsWith(PYTHON_TEST_FILE_EXTENSION);
+  return basename3(filePath).startsWith(PYTHON_TEST_FILE_PREFIX) && filePath.endsWith(PYTHON_TEST_FILE_EXTENSION);
 }
 function coveredProductInputPaths(coveredTestPaths2) {
   const paths = /* @__PURE__ */ new Set();
   for (const testPath of coveredTestPaths2) {
     if (!matchesTestFile(testPath)) continue;
-    let directory = dirname5(testPath);
+    let directory = dirname6(testPath);
     while (directory !== "." && directory.length > 0) {
-      paths.add(join20(directory, PYTHON_PRODUCT_INPUT_PATH.CONFTEST));
-      const parent = dirname5(directory);
+      paths.add(join21(directory, PYTHON_PRODUCT_INPUT_PATH.CONFTEST));
+      const parent = dirname6(directory);
       if (parent === directory) break;
       directory = parent;
     }
@@ -6997,7 +7842,7 @@ function applyValidationPathFilterToScope(scopeConfig, filter) {
 
 // src/validation/steps/markdown.ts
 import { existsSync, statSync } from "fs";
-import { basename as basename3, dirname as dirname6, join as join21, relative as pathRelative } from "path";
+import { basename as basename4, dirname as dirname7, join as join22, relative as pathRelative } from "path";
 import { main as markdownlintMain } from "markdownlint-cli2";
 import relativeLinksRule from "markdownlint-rule-relative-links";
 var MARKDOWN_DEFAULT_DIRECTORY_NAMES = ["spx", "docs"];
@@ -7036,7 +7881,7 @@ function buildMarkdownlintConfig(directoryName) {
   };
 }
 function getDefaultDirectories(projectRoot) {
-  return MARKDOWN_DEFAULT_DIRECTORY_NAMES.map((name) => join21(projectRoot, name)).filter((dir) => existsSync(dir));
+  return MARKDOWN_DEFAULT_DIRECTORY_NAMES.map((name) => join22(projectRoot, name)).filter((dir) => existsSync(dir));
 }
 function resolveMarkdownValidationTarget(path6, deps = defaultMarkdownValidationTargetDeps) {
   if (isExistingDirectory(path6, deps)) {
@@ -7095,7 +7940,7 @@ async function validateMarkdown(options) {
 async function validateTarget(target, config, projectRoot, ignoreGlobs = []) {
   const errors = [];
   const directory = targetDirectory(target);
-  const argv = target.kind === MARKDOWN_VALIDATION_TARGET_KIND.FILE ? [basename3(target.path)] : [MARKDOWN_DIRECTORY_GLOB];
+  const argv = target.kind === MARKDOWN_VALIDATION_TARGET_KIND.FILE ? [basename4(target.path)] : [MARKDOWN_DIRECTORY_GLOB];
   const { customRules, ...markdownlintConfig } = config;
   const optionsOverride = {
     config: {
@@ -7119,7 +7964,7 @@ async function validateTarget(target, config, projectRoot, ignoreGlobs = []) {
       if (parsed) {
         errors.push({
           ...parsed,
-          file: join21(directory, parsed.file)
+          file: join22(directory, parsed.file)
         });
       }
     }
@@ -7127,7 +7972,7 @@ async function validateTarget(target, config, projectRoot, ignoreGlobs = []) {
   return errors;
 }
 function targetDirectory(target) {
-  return target.kind === MARKDOWN_VALIDATION_TARGET_KIND.FILE ? dirname6(target.path) : target.path;
+  return target.kind === MARKDOWN_VALIDATION_TARGET_KIND.FILE ? dirname7(target.path) : target.path;
 }
 function hasMarkdownExtension(path6) {
   const lastDot = path6.lastIndexOf(".");
@@ -7155,7 +8000,7 @@ function markdownlintConfigDirectoryName(directory, projectRoot) {
       return rootSegment;
     }
   }
-  return basename3(directory);
+  return basename4(directory);
 }
 
 // src/commands/validation/messages.ts
@@ -7169,6 +8014,7 @@ var VALIDATION_STAGE_DISPLAY_NAMES = {
 };
 var VALIDATION_SKIP_LABELS = {
   VERB: "Skipping",
+  CIRCULAR_REASON: "skip-circular",
   LITERAL_REASON: "skip-literal",
   TYPESCRIPT_ABSENT_REASON: "TypeScript not detected in project",
   VALIDATION_PATHS_NO_TARGETS_REASON: "validation paths matched no files",
@@ -7190,6 +8036,11 @@ var VALIDATION_COMMAND_OUTPUT = {
   MARKDOWN_NO_ISSUES: `${VALIDATION_STAGE_DISPLAY_NAMES.MARKDOWN}: No issues found`,
   MARKDOWN_ERROR_SUMMARY_SUFFIX: "error(s) found"
 };
+var CIRCULAR_SKIP_OUTPUT = `${VALIDATION_STAGE_DISPLAY_NAMES.CIRCULAR}: skipped (--${VALIDATION_SKIP_LABELS.CIRCULAR_REASON})`;
+var CIRCULAR_SKIP_JSON_OUTPUT = JSON.stringify({
+  skipped: true,
+  reason: VALIDATION_SKIP_LABELS.CIRCULAR_REASON
+});
 var LITERAL_SKIP_OUTPUT = `${VALIDATION_STAGE_DISPLAY_NAMES.LITERAL}: skipped (--${VALIDATION_SKIP_LABELS.LITERAL_REASON})`;
 var LITERAL_SKIP_JSON_OUTPUT = JSON.stringify({
   skipped: true,
@@ -8141,7 +8992,7 @@ var ParseErrorCode;
 
 // src/validation/config/scope.ts
 import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3 } from "fs";
-import { isAbsolute as isAbsolute3, join as join22 } from "path";
+import { isAbsolute as isAbsolute3, join as join23 } from "path";
 var TSCONFIG_FILES = {
   full: "tsconfig.json",
   production: "tsconfig.production.json"
@@ -8155,7 +9006,7 @@ var defaultScopeDeps = {
   readdirSync
 };
 function resolveProjectPath(projectRoot, path6) {
-  return isAbsolute3(path6) ? path6 : join22(projectRoot, path6);
+  return isAbsolute3(path6) ? path6 : join23(projectRoot, path6);
 }
 function parseTypeScriptConfig(configPath, deps = defaultScopeDeps) {
   try {
@@ -8199,7 +9050,7 @@ function hasTypeScriptFilesRecursive(dirPath, maxDepth = 2, deps = defaultScopeD
     if (hasDirectTsFiles) return true;
     const subdirs = items.filter((item) => item.isDirectory() && !item.name.startsWith("."));
     for (const subdir of subdirs.slice(0, 5)) {
-      if (hasTypeScriptFilesRecursive(join22(dirPath, subdir.name), maxDepth - 1, deps)) {
+      if (hasTypeScriptFilesRecursive(join23(dirPath, subdir.name), maxDepth - 1, deps)) {
         return true;
       }
     }
@@ -8222,7 +9073,7 @@ function getTopLevelDirectoriesWithTypeScript(config, projectRoot, deps = defaul
     });
     if (!isExcluded) {
       try {
-        const hasTypeScriptFiles = hasTypeScriptFilesRecursive(join22(projectRoot, dir), 2, deps);
+        const hasTypeScriptFiles = hasTypeScriptFilesRecursive(join23(projectRoot, dir), 2, deps);
         if (hasTypeScriptFiles) {
           directories.add(dir);
         }
@@ -8253,13 +9104,13 @@ function getLiteralTopLevelPatternDirectory(pattern) {
 function filterActiveIncludePatterns(patterns, excludePatterns, projectRoot, deps) {
   return patterns.filter((pattern) => {
     const topLevelDir = getLiteralTopLevelPatternDirectory(pattern);
-    return topLevelDir === null || deps.existsSync(join22(projectRoot, topLevelDir));
+    return topLevelDir === null || deps.existsSync(join23(projectRoot, topLevelDir));
   }).filter((pattern) => pathPassesValidationFilter(pattern, { exclude: excludePatterns }));
 }
 function getValidationDirectories(scope, projectRoot, deps = defaultScopeDeps) {
   const config = resolveTypeScriptConfig(scope, projectRoot, deps);
   const configDirectories = getTopLevelDirectoriesWithTypeScript(config, projectRoot, deps);
-  const existingDirectories = configDirectories.filter((dir) => deps.existsSync(join22(projectRoot, dir)));
+  const existingDirectories = configDirectories.filter((dir) => deps.existsSync(join23(projectRoot, dir)));
   return existingDirectories;
 }
 function getTypeScriptScope(scope, projectRoot, deps = defaultScopeDeps) {
@@ -8273,10 +9124,10 @@ function getTypeScriptScope(scope, projectRoot, deps = defaultScopeDeps) {
 }
 
 // src/validation/discovery/tool-finder.ts
-import { execSync as execSync2 } from "child_process";
 import fs6 from "fs";
 import { createRequire } from "module";
 import path5 from "path";
+import { fileURLToPath } from "url";
 
 // src/validation/discovery/constants.ts
 var TOOL_DISCOVERY = {
@@ -8310,6 +9161,50 @@ var TOOL_DISCOVERY = {
 
 // src/validation/discovery/tool-finder.ts
 var require2 = createRequire(import.meta.url);
+var FILE_URL_PROTOCOL = new URL(import.meta.url).protocol;
+var PACKAGE_MANIFEST_FILENAME = "package.json";
+var PATH_ENVIRONMENT_VARIABLE = "PATH";
+var WINDOWS_EXECUTABLE_EXTENSIONS_VARIABLE = "PATHEXT";
+var WINDOWS_DEFAULT_EXECUTABLE_EXTENSIONS = [".COM", ".EXE", ".BAT", ".CMD"];
+function executableExtensions() {
+  if (process.platform !== "win32") {
+    return [""];
+  }
+  const pathExtensions = process.env[WINDOWS_EXECUTABLE_EXTENSIONS_VARIABLE]?.split(path5.delimiter).filter(Boolean);
+  return pathExtensions && pathExtensions.length > 0 ? pathExtensions : WINDOWS_DEFAULT_EXECUTABLE_EXTENSIONS;
+}
+function executableCandidateNames(tool) {
+  if (process.platform !== "win32" || path5.extname(tool) !== "") {
+    return [tool];
+  }
+  return executableExtensions().map((extension) => `${tool}${extension}`);
+}
+function isExecutableFile(filePath) {
+  try {
+    fs6.accessSync(filePath, fs6.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function findExecutableOnPath(tool) {
+  const pathValue = process.env[PATH_ENVIRONMENT_VARIABLE];
+  if (!pathValue) {
+    return null;
+  }
+  for (const directory of pathValue.split(path5.delimiter)) {
+    if (!directory) {
+      continue;
+    }
+    for (const candidateName of executableCandidateNames(tool)) {
+      const candidatePath = path5.join(directory, candidateName);
+      if (isExecutableFile(candidatePath)) {
+        return candidatePath;
+      }
+    }
+  }
+  return null;
+}
 var defaultToolDiscoveryDeps = {
   resolveModule: (modulePath) => {
     try {
@@ -8318,28 +9213,50 @@ var defaultToolDiscoveryDeps = {
       return null;
     }
   },
-  existsSync: fs6.existsSync,
-  whichSync: (tool) => {
+  resolveImport: (modulePath) => {
     try {
-      const result = execSync2(`which ${tool}`, {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"]
-      });
-      return result.trim() || null;
+      return import.meta.resolve(modulePath);
     } catch {
       return null;
     }
-  }
+  },
+  existsSync: fs6.existsSync,
+  whichSync: findExecutableOnPath
 };
+function resolvedModulePath(resolvedPath) {
+  try {
+    const resolvedUrl = new URL(resolvedPath);
+    return resolvedUrl.protocol === FILE_URL_PROTOCOL ? fileURLToPath(resolvedUrl) : resolvedPath;
+  } catch {
+    return resolvedPath;
+  }
+}
+function nearestPackageRoot(filePath, existsSync7) {
+  let currentDirectory = path5.dirname(filePath);
+  while (true) {
+    if (existsSync7(path5.join(currentDirectory, PACKAGE_MANIFEST_FILENAME))) {
+      return currentDirectory;
+    }
+    const parentDirectory = path5.dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      return null;
+    }
+    currentDirectory = parentDirectory;
+  }
+}
+function bundledToolPath(resolvedPath, existsSync7) {
+  const bundledFilePath = resolvedModulePath(resolvedPath);
+  return nearestPackageRoot(bundledFilePath, existsSync7) ?? path5.dirname(bundledFilePath);
+}
 async function discoverTool(tool, options = {}) {
   const { projectRoot = process.cwd(), deps = defaultToolDiscoveryDeps } = options;
-  const bundledPath = deps.resolveModule(`${tool}/package.json`);
+  const bundledPath = deps.resolveModule(`${tool}/package.json`) ?? deps.resolveImport?.(tool);
   if (bundledPath) {
     return {
       found: true,
       location: {
         tool,
-        path: path5.dirname(bundledPath),
+        path: bundledToolPath(bundledPath, deps.existsSync),
         source: TOOL_DISCOVERY.SOURCES.BUNDLED
       }
     };
@@ -8382,33 +9299,180 @@ function formatSkipMessage(stepName, result) {
 }
 
 // src/validation/steps/circular.ts
-import madge from "madge";
-import { join as join23 } from "path";
+import {
+  cruise as dependencyCruiser
+} from "dependency-cruiser";
+import extractTypeScriptConfig from "dependency-cruiser/config-utl/extract-ts-config";
+import { join as join24 } from "path";
+var DEPENDENCY_CRUISER_MODULE_SYSTEMS = ["es6", "cjs"];
+var DEPENDENCY_CRUISER_TYPESCRIPT_SOURCE_GLOB_SUFFIXES = ["**/*.ts", "**/*.tsx"];
+var DEPENDENCY_CRUISER_TYPESCRIPT_SOURCE_PATTERN = String.raw`\.tsx?$`;
+var DEPENDENCY_CRUISER_TYPESCRIPT_RESOLVE_EXTENSIONS = [".ts", ".tsx", ".d.ts"];
+var TSCONFIG_EXCLUDE_SUFFIX_PATTERN = /\/\*\*?\/\*$/u;
+var REGEX_SPECIAL_CHARACTER_PATTERN = /[.*+?^${}()|[\]\\]/gu;
+var REGEX_ESCAPE_REPLACEMENT = String.raw`\$&`;
+var CYCLE_KEY_SEPARATOR = "\0";
+var DEPENDENCY_CRUISER_PACKAGE_EXCLUDE_PATTERN = "(^|/)node_modules(/|$)";
+var DEPENDENCY_CRUISER_DEPENDENCY_TYPES = {
+  AMD_DEFINE: "amd-define",
+  AMD_EXOTIC_REQUIRE: "amd-exotic-require",
+  AMD_REQUIRE: "amd-require",
+  DYNAMIC_IMPORT: "dynamic-import",
+  EXPORT: "export",
+  EXOTIC_REQUIRE: "exotic-require",
+  IMPORT: "import",
+  IMPORT_EQUALS: "import-equals",
+  LOCAL: "local",
+  PRE_COMPILATION_ONLY: "pre-compilation-only",
+  REQUIRE: "require",
+  TYPE_IMPORT: "type-import",
+  // dependency-cruiser 16.10.4 emits this for TypeScript `import type` edges.
+  TYPE_ONLY: "type-only"
+};
+var DEPENDENCY_CRUISER_TS_PRE_COMPILATION_DEPS = "specify";
+var ERASURE_ONLY_DEPENDENCY_TYPES = /* @__PURE__ */ new Set([
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.PRE_COMPILATION_ONLY,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.TYPE_IMPORT,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.TYPE_ONLY
+]);
+var RUNTIME_DEPENDENCY_TYPES = /* @__PURE__ */ new Set([
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.AMD_DEFINE,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.AMD_EXOTIC_REQUIRE,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.AMD_REQUIRE,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.DYNAMIC_IMPORT,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.EXPORT,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.EXOTIC_REQUIRE,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.IMPORT,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.IMPORT_EQUALS,
+  DEPENDENCY_CRUISER_DEPENDENCY_TYPES.REQUIRE
+]);
 var CIRCULAR_DEPS_KEYS = {
-  MADGE: "madge"
+  DEPENDENCY_CRUISER: "dependencyCruiser",
+  EXTRACT_TYPESCRIPT_CONFIG: "extractTypeScriptConfig"
 };
 var defaultCircularDeps = {
-  [CIRCULAR_DEPS_KEYS.MADGE]: madge
+  [CIRCULAR_DEPS_KEYS.DEPENDENCY_CRUISER]: dependencyCruiser,
+  [CIRCULAR_DEPS_KEYS.EXTRACT_TYPESCRIPT_CONFIG]: extractTypeScriptConfig
 };
+function toDependencyCruiserExcludePatterns(patterns) {
+  return patterns.map((pattern) => {
+    const cleanPattern = pattern.replace(TSCONFIG_EXCLUDE_SUFFIX_PATTERN, "");
+    return cleanPattern.replace(REGEX_SPECIAL_CHARACTER_PATTERN, REGEX_ESCAPE_REPLACEMENT);
+  });
+}
+function buildDependencyCruiserOptions(typescriptScope, projectRoot, tsConfigFile) {
+  const excludePatterns = [
+    DEPENDENCY_CRUISER_PACKAGE_EXCLUDE_PATTERN,
+    ...toDependencyCruiserExcludePatterns(typescriptScope.excludePatterns)
+  ];
+  return {
+    baseDir: projectRoot,
+    enhancedResolveOptions: { extensions: [...DEPENDENCY_CRUISER_TYPESCRIPT_RESOLVE_EXTENSIONS] },
+    exclude: { path: excludePatterns },
+    includeOnly: { path: DEPENDENCY_CRUISER_TYPESCRIPT_SOURCE_PATTERN },
+    moduleSystems: [...DEPENDENCY_CRUISER_MODULE_SYSTEMS],
+    tsConfig: { fileName: tsConfigFile },
+    tsPreCompilationDeps: DEPENDENCY_CRUISER_TS_PRE_COMPILATION_DEPS
+  };
+}
+function toDependencyCruiserSourcePatterns(directories) {
+  return directories.flatMap(
+    (directory) => DEPENDENCY_CRUISER_TYPESCRIPT_SOURCE_GLOB_SUFFIXES.map((suffix) => `${directory}/${suffix}`)
+  );
+}
+function isCruiseResult(output) {
+  return typeof output === "object" && output !== null && "modules" in output && "summary" in output;
+}
+function closeCycle(cycle) {
+  const first = cycle[0];
+  const last = cycle.at(-1);
+  if (first === void 0) {
+    return [];
+  }
+  return last === first ? [...cycle] : [...cycle, first];
+}
+function dependencyTypesSurviveRuntime(dependencyTypes) {
+  if (dependencyTypes.includes(DEPENDENCY_CRUISER_DEPENDENCY_TYPES.PRE_COMPILATION_ONLY)) {
+    return false;
+  }
+  if (dependencyTypes.some((dependencyType) => RUNTIME_DEPENDENCY_TYPES.has(dependencyType))) {
+    return true;
+  }
+  return dependencyTypes.every((dependencyType) => !ERASURE_ONLY_DEPENDENCY_TYPES.has(dependencyType));
+}
+function dependencySurvivesRuntime(dependency) {
+  return !dependency.typeOnly && !dependency.preCompilationOnly;
+}
+function dependencyCycleSurvivesRuntime(dependency) {
+  return dependencySurvivesRuntime(dependency) && (dependency.cycle?.every((cycleDependency) => dependencyTypesSurviveRuntime(cycleDependency.dependencyTypes)) ?? true);
+}
+function dependencyCycleForModule(moduleSource, dependency) {
+  if (!dependency.circular || !dependencyCycleSurvivesRuntime(dependency)) {
+    return null;
+  }
+  const cycleTail = dependency.cycle?.map((cycleDependency) => cycleDependency.name) ?? [dependency.resolved];
+  return closeCycle([moduleSource, ...cycleTail]);
+}
+function openCycle(cycle) {
+  if (cycle.length > 1 && cycle[0] === cycle.at(-1)) {
+    return cycle.slice(0, -1);
+  }
+  return [...cycle];
+}
+function cycleRotations(cycle) {
+  return cycle.map(
+    (_, index) => [
+      ...cycle.slice(index),
+      ...cycle.slice(0, index)
+    ].join(CYCLE_KEY_SEPARATOR)
+  );
+}
+function canonicalCycleKey(cycle) {
+  const opened = openCycle(cycle);
+  const reversed = [...opened].reverse();
+  const keys = [...cycleRotations(opened), ...cycleRotations(reversed)].sort(
+    (left, right) => left.localeCompare(right)
+  );
+  return keys[0] ?? "";
+}
+function uniqueCycles(cycles) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const cycle of cycles) {
+    const key = canonicalCycleKey(cycle);
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(cycle);
+    }
+  }
+  return result;
+}
+function circularDependencyCycles(result) {
+  const cycles = result.modules.flatMap(
+    (module) => module.dependencies.flatMap((dependency) => {
+      const cycle = dependencyCycleForModule(module.source, dependency);
+      return cycle === null ? [] : [cycle];
+    })
+  );
+  return uniqueCycles(cycles);
+}
 async function validateCircularDependencies(scope, typescriptScope, projectRoot, deps = defaultCircularDeps) {
   try {
-    const analyzeDirectories = typescriptScope.directories.map((directory) => join23(projectRoot, directory));
-    if (analyzeDirectories.length === 0) {
+    const analyzeSourcePatterns = toDependencyCruiserSourcePatterns(typescriptScope.directories);
+    if (analyzeSourcePatterns.length === 0) {
       return { success: true };
     }
-    const tsConfigFile = join23(projectRoot, TSCONFIG_FILES[scope]);
-    const excludeRegExps = typescriptScope.excludePatterns.map((pattern) => {
-      const cleanPattern = pattern.replace(/\/\*\*?\/\*$/, "");
-      const escaped = cleanPattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      return new RegExp(escaped);
-    });
-    const result = await deps.madge(analyzeDirectories, {
-      baseDir: projectRoot,
-      fileExtensions: ["ts", "tsx"],
-      tsConfig: tsConfigFile,
-      excludeRegExp: excludeRegExps
-    });
-    const circular = result.circular();
+    const tsConfigFile = join24(projectRoot, TSCONFIG_FILES[scope]);
+    const result = await deps.dependencyCruiser(
+      analyzeSourcePatterns,
+      buildDependencyCruiserOptions(typescriptScope, projectRoot, tsConfigFile),
+      void 0,
+      { tsConfig: deps.extractTypeScriptConfig(tsConfigFile) }
+    );
+    if (!isCruiseResult(result.output)) {
+      return { success: false, error: "dependency-cruiser returned non-structured output" };
+    }
+    const circular = circularDependencyCycles(result.output);
     if (circular.length === 0) {
       return { success: true };
     } else {
@@ -8441,7 +9505,7 @@ async function circularCommand(options) {
       durationMs: Date.now() - startTime
     };
   }
-  const toolResult = await discoverTool("madge", { projectRoot: cwd });
+  const toolResult = await discoverTool("dependency-cruiser", { projectRoot: cwd });
   if (!toolResult.found) {
     const skipMessage = formatSkipMessage("circular dependency check", toolResult);
     return { exitCode: 0, output: skipMessage, durationMs: Date.now() - startTime };
@@ -8479,7 +9543,7 @@ ${cycles}`;
 import { existsSync as existsSync3 } from "fs";
 import { mkdtemp, rm, writeFile as writeFile3 } from "fs/promises";
 import { tmpdir } from "os";
-import { isAbsolute as isAbsolute4, join as join24 } from "path";
+import { isAbsolute as isAbsolute4, join as join25 } from "path";
 var defaultKnipProcessRunner = lifecycleProcessRunner;
 var KNIP_COMMAND_TOKENS = {
   COMMAND: "knip",
@@ -8507,7 +9571,7 @@ async function validateKnip2(context, runner = defaultKnipProcessRunner, deps =
 }
 async function runKnipSubprocess(projectRoot, typescriptScope, runner, deps) {
   const scopedTsconfig = typescriptScope.filteredByValidationPaths ? await createScopedKnipTsconfig(projectRoot, typescriptScope, deps) : void 0;
-  const localBin = join24(projectRoot, "node_modules", ".bin", "knip");
+  const localBin = join25(projectRoot, "node_modules", ".bin", "knip");
   const binary = deps.existsSync(localBin) ? localBin : "npx";
   const baseArgs = scopedTsconfig === void 0 ? [] : [
     KNIP_COMMAND_TOKENS.USE_TSCONFIG_FILES_FLAG,
@@ -8562,12 +9626,12 @@ async function runKnipSubprocess(projectRoot, typescriptScope, runner, deps) {
   });
 }
 async function createScopedKnipTsconfig(projectRoot, typescriptScope, deps) {
-  const tempDir = await deps.mkdtemp(join24(tmpdir(), "validate-knip-"));
-  const configPath = join24(tempDir, TSCONFIG_FILES.full);
-  const toProjectPathPattern = (pattern) => isAbsolute4(pattern) ? pattern : join24(projectRoot, pattern);
+  const tempDir = await deps.mkdtemp(join25(tmpdir(), "validate-knip-"));
+  const configPath = join25(tempDir, TSCONFIG_FILES.full);
+  const toProjectPathPattern = (pattern) => isAbsolute4(pattern) ? pattern : join25(projectRoot, pattern);
   const project = typescriptScope.filePatterns.length > 0 ? typescriptScope.filePatterns : typescriptScope.directories.map((directory) => `${directory}/**/*.{js,ts,tsx}`);
   const config = {
-    extends: join24(projectRoot, TSCONFIG_FILES.full),
+    extends: join25(projectRoot, TSCONFIG_FILES.full),
     include: project.map(toProjectPathPattern),
     exclude: typescriptScope.excludePatterns.map(toProjectPathPattern)
   };
@@ -8617,12 +9681,12 @@ async function knipCommand(options) {
 
 // src/validation/steps/eslint.ts
 import { existsSync as existsSync5 } from "fs";
-import { join as join26 } from "path";
+import { join as join27 } from "path";
 
 // src/validation/lint-policy.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
-import { join as join25 } from "path";
+import { join as join26 } from "path";
 
 // src/validation/lint-policy-constants.ts
 var LINT_POLICY_MANIFESTS = {
@@ -8670,17 +9734,17 @@ function isSpecTreeNodePath(entry) {
 }
 function readManifest(productDir, file, key) {
   return parseLintPolicyManifest(
-    readFileSync4(join25(productDir, file), "utf-8"),
+    readFileSync4(join26(productDir, file), "utf-8"),
     file,
     key
   );
 }
 function manifestExists(productDir, file) {
-  return existsSync4(join25(productDir, file));
+  return existsSync4(join26(productDir, file));
 }
 function findDeprecatedSpecNodePath(productDir) {
   function visit2(relativeDirectory) {
-    const absoluteDirectory = join25(productDir, relativeDirectory);
+    const absoluteDirectory = join26(productDir, relativeDirectory);
     for (const entry of readdirSync2(absoluteDirectory, { withFileTypes: true })) {
       if (!entry.isDirectory()) {
         continue;
@@ -8696,7 +9760,7 @@ function findDeprecatedSpecNodePath(productDir) {
     }
     return void 0;
   }
-  const specTreeRootPath = join25(productDir, SPEC_TREE_ROOT);
+  const specTreeRootPath = join26(productDir, SPEC_TREE_ROOT);
   if (!existsSync4(specTreeRootPath)) {
     return void 0;
   }
@@ -8722,7 +9786,7 @@ function assertManifestEntries(productDir, file, entries, suffixPredicate, suffi
     if (!suffixPredicate(entry)) {
       throw new Error(`${file} entry must ${suffixDescription}: ${entry}`);
     }
-    const absoluteEntry = join25(productDir, entry);
+    const absoluteEntry = join26(productDir, entry);
     if (!existsSync4(absoluteEntry) || !statSync2(absoluteEntry).isDirectory()) {
       throw new Error(`${file} entry does not exist as a directory: ${entry}`);
     }
@@ -8982,7 +10046,7 @@ async function validateESLint(context, runner = defaultEslintProcessRunner, outp
     scopeConfig: context.scopeConfig
   });
   return new Promise((resolve6) => {
-    const localBin = join26(projectRoot, ...ESLINT_LOCAL_BIN_SEGMENTS);
+    const localBin = join27(projectRoot, ...ESLINT_LOCAL_BIN_SEGMENTS);
     const binary = existsSync5(localBin) ? localBin : "npx";
     const spawnArgs = binary === "npx" ? eslintArgs : eslintArgs.slice(1);
     const eslintProcess = spawnManagedSubprocess(runner, binary, spawnArgs, {
@@ -9084,7 +10148,7 @@ async function lintCommand(options) {
 
 // src/validation/literal/index.ts
 import { readFile as readFile8 } from "fs/promises";
-import { isAbsolute as isAbsolute5, relative as relative5, resolve as resolve4 } from "path";
+import { isAbsolute as isAbsolute5, relative as relative5, resolve as resolve5 } from "path";
 
 // src/lib/file-inclusion/predicates/ignore-source.ts
 var IGNORE_SOURCE_LAYER = "ignore-source";
@@ -9119,7 +10183,7 @@ var ignoreSourceLayer = makeLayer(
 
 // src/lib/file-inclusion/pipeline.ts
 import { readdir as readdir7 } from "fs/promises";
-import { join as join27, relative as relative4, sep as sep2 } from "path";
+import { join as join28, relative as relative4, sep as sep2 } from "path";
 var EXPLICIT_OVERRIDE_LAYER = "explicit-override";
 function isNodeError3(err) {
   return err instanceof Error && "code" in err;
@@ -9137,10 +10201,10 @@ async function collectPaths(absoluteDir, projectRoot, result, artifactDirs) {
   for (const entry of dirEntries) {
     if (entry.isDirectory()) {
       if (artifactDirs.has(entry.name)) continue;
-      const absolutePath = join27(absoluteDir, entry.name);
+      const absolutePath = join28(absoluteDir, entry.name);
       await collectPaths(absolutePath, projectRoot, result, artifactDirs);
     } else if (entry.isFile()) {
-      const absolutePath = join27(absoluteDir, entry.name);
+      const absolutePath = join28(absoluteDir, entry.name);
       const rel = relative4(projectRoot, absolutePath);
       result.push(sep2 === "/" ? rel : rel.split(sep2).join("/"));
     }
@@ -9547,7 +10611,7 @@ async function validateLiteralReuse(input) {
   const config = input.config ?? literalConfigDescriptor.defaults;
   const request = input.files ? {
     explicit: input.files.map((f) => {
-      const abs = isAbsolute5(f) ? f : resolve4(input.productDir, f);
+      const abs = isAbsolute5(f) ? f : resolve5(input.productDir, f);
       return relative5(input.productDir, abs).split(/[\\/]/g).join("/");
     })
   } : { walkRoot: input.productDir };
@@ -9559,7 +10623,7 @@ async function validateLiteralReuse(input) {
     EMPTY_IGNORE_READER
   );
   const filtered = applyPathFilter2(scope.included, input.pathConfig);
-  const candidateFiles = filtered.filter((entry) => isTypescriptSource(entry.path)).map((entry) => resolve4(input.productDir, entry.path));
+  const candidateFiles = filtered.filter((entry) => isTypescriptSource(entry.path)).map((entry) => resolve5(input.productDir, entry.path));
   const collectOptions = {
     visitorKeys: defaultVisitorKeys,
     minStringLength: config.minStringLength,
@@ -9800,7 +10864,7 @@ function formatLoc(loc) {
 // src/validation/steps/typescript.ts
 import { existsSync as existsSync6, mkdirSync, rmSync, writeFileSync } from "fs";
 import { mkdtemp as mkdtemp2 } from "fs/promises";
-import { isAbsolute as isAbsolute6, join as join28 } from "path";
+import { isAbsolute as isAbsolute6, join as join29 } from "path";
 var defaultTypeScriptProcessRunner = lifecycleProcessRunner;
 var defaultTypeScriptDeps = {
   mkdtemp: mkdtemp2,
@@ -9813,9 +10877,9 @@ var TEMPORARY_TSCONFIG_COMPILER_OPTIONS = { noEmit: true };
 var TEMPORARY_TSCONFIG_PARENT_SEGMENTS = ["node_modules", ".cache", "spx"];
 var TEMPORARY_TSCONFIG_DIR_PREFIX = "validate-ts-";
 async function createTemporaryTsconfigDir(projectRoot, deps) {
-  const parent = join28(projectRoot, ...TEMPORARY_TSCONFIG_PARENT_SEGMENTS);
+  const parent = join29(projectRoot, ...TEMPORARY_TSCONFIG_PARENT_SEGMENTS);
   deps.mkdirSync(parent, { recursive: true });
-  return deps.mkdtemp(join28(parent, TEMPORARY_TSCONFIG_DIR_PREFIX));
+  return deps.mkdtemp(join29(parent, TEMPORARY_TSCONFIG_DIR_PREFIX));
 }
 function buildTypeScriptArgs(context) {
   const { scope, configFile } = context;
@@ -9823,11 +10887,11 @@ function buildTypeScriptArgs(context) {
 }
 async function createFileSpecificTsconfig(scope, files, projectRoot, deps = defaultTypeScriptDeps) {
   const tempDir = await createTemporaryTsconfigDir(projectRoot, deps);
-  const configPath = join28(tempDir, "tsconfig.json");
+  const configPath = join29(tempDir, "tsconfig.json");
   const baseConfigFile = TSCONFIG_FILES[scope];
-  const absoluteFiles = files.map((file) => isAbsolute6(file) ? file : join28(projectRoot, file));
+  const absoluteFiles = files.map((file) => isAbsolute6(file) ? file : join29(projectRoot, file));
   const tempConfig = {
-    extends: join28(projectRoot, baseConfigFile),
+    extends: join29(projectRoot, baseConfigFile),
     files: absoluteFiles,
     include: [],
     exclude: [],
@@ -9844,11 +10908,11 @@ async function createFileSpecificTsconfig(scope, files, projectRoot, deps = defa
 }
 async function createScopeFilteredTsconfig(scope, projectRoot, scopeConfig, deps = defaultTypeScriptDeps) {
   const tempDir = await createTemporaryTsconfigDir(projectRoot, deps);
-  const configPath = join28(tempDir, "tsconfig.json");
+  const configPath = join29(tempDir, "tsconfig.json");
   const baseConfigFile = TSCONFIG_FILES[scope];
-  const toProjectPathPattern = (pattern) => isAbsolute6(pattern) ? pattern : join28(projectRoot, pattern);
+  const toProjectPathPattern = (pattern) => isAbsolute6(pattern) ? pattern : join29(projectRoot, pattern);
   const tempConfig = {
-    extends: join28(projectRoot, baseConfigFile),
+    extends: join29(projectRoot, baseConfigFile),
     include: scopeConfig.filePatterns.map(toProjectPathPattern),
     exclude: scopeConfig.excludePatterns.map(toProjectPathPattern),
     compilerOptions: TEMPORARY_TSCONFIG_COMPILER_OPTIONS
@@ -9876,7 +10940,7 @@ async function validateTypeScript(context, options = {}) {
     const { configPath, cleanup } = await createFileSpecificTsconfig(scope, files, projectRoot, deps);
     try {
       return await new Promise((resolve6) => {
-        const tscBin = join28(projectRoot, "node_modules", ".bin", "tsc");
+        const tscBin = join29(projectRoot, "node_modules", ".bin", "tsc");
         const tscBinary = deps.existsSync(tscBin) ? tscBin : "npx";
         const tscArgs2 = tscBinary === "npx" ? ["tsc", "--project", configPath] : ["--project", configPath];
         const tscProcess = spawnManagedSubprocess(runner, tscBinary, tscArgs2, {
@@ -9909,7 +10973,7 @@ async function validateTypeScript(context, options = {}) {
       return { success: true, skipped: true };
     }
     const { configPath, cleanup } = await createScopeFilteredTsconfig(scope, projectRoot, scopeConfig, deps);
-    const tscBin = join28(projectRoot, "node_modules", ".bin", "tsc");
+    const tscBin = join29(projectRoot, "node_modules", ".bin", "tsc");
     tool = deps.existsSync(tscBin) ? tscBin : "npx";
     tscArgs = tool === "npx" ? ["tsc", "--project", configPath] : ["--project", configPath];
     return new Promise((resolve6) => {
@@ -9931,7 +10995,7 @@ async function validateTypeScript(context, options = {}) {
       });
     });
   } else {
-    const tscBin = join28(projectRoot, "node_modules", ".bin", "tsc");
+    const tscBin = join29(projectRoot, "node_modules", ".bin", "tsc");
     tool = deps.existsSync(tscBin) ? tscBin : "npx";
     const rawArgs = buildTypeScriptArgs({ scope, configFile });
     tscArgs = tool === "npx" ? rawArgs : rawArgs.slice(1);
@@ -10024,6 +11088,13 @@ async function typescriptCommand(options) {
 
 // src/validation/languages/typescript.ts
 var TYPESCRIPT_LANGUAGE_NAME = "typescript";
+async function runCircularStage(context) {
+  if (context.skipCircular) {
+    const skipOutput = context.json ? CIRCULAR_SKIP_JSON_OUTPUT : CIRCULAR_SKIP_OUTPUT;
+    return { exitCode: 0, output: context.quiet ? "" : skipOutput };
+  }
+  return circularCommand({ cwd: context.cwd, quiet: context.quiet, json: context.json });
+}
 async function runLiteralStage(context) {
   if (context.skipLiteral) {
     const skipOutput = context.json ? LITERAL_SKIP_JSON_OUTPUT : LITERAL_SKIP_OUTPUT;
@@ -10042,7 +11113,7 @@ var typescriptValidationLanguage = {
     {
       name: VALIDATION_STAGE_DISPLAY_NAMES.CIRCULAR,
       failsPipeline: true,
-      run: (context) => circularCommand({ cwd: context.cwd, quiet: context.quiet, json: context.json })
+      run: runCircularStage
     },
     {
       name: VALIDATION_STAGE_DISPLAY_NAMES.KNIP,
@@ -10122,11 +11193,11 @@ function formatStepWithTiming(stepNumber, result, quiet) {
   return `[${stepNumber}/${VALIDATION_PIPELINE_TOTAL_STEPS}] ${result.output}${timing}`;
 }
 async function allCommand(options) {
-  const { cwd, scope, files, fix, quiet = false, json, skipLiteral = false } = options;
+  const { cwd, scope, files, fix, quiet = false, json, skipCircular = false, skipLiteral = false } = options;
   const startTime = Date.now();
   const outputs = [];
   let hasFailure = false;
-  const context = { cwd, scope, files, fix, quiet, json, skipLiteral };
+  const context = { cwd, scope, files, fix, quiet, json, skipCircular, skipLiteral };
   let stepNumber = 0;
   for (const stage of validationPipelineStages) {
     stepNumber += 1;
@@ -10139,59 +11210,17 @@ async function allCommand(options) {
   if (!quiet) {
     const summary = formatSummary({ success: !hasFailure, totalDurationMs });
     outputs.push("", summary);
-  }
-  return {
-    exitCode: hasFailure ? 1 : 0,
-    output: outputs.join("\n"),
-    durationMs: totalDurationMs
-  };
-}
-
-// src/interfaces/cli/sanitize.ts
-var MAX_CLI_ARGUMENT_DISPLAY_LENGTH = 120;
-var ELLIPSIS_TOKEN = "...";
-var SENTINEL_UNDEFINED = "<undefined>";
-var SENTINEL_NULL = "<null>";
-var SENTINEL_EMPTY = "<empty>";
-var CONTROL_CHAR_UPPER_BOUND = 31;
-var DEL_CHAR_CODE = 127;
-var HEX_RADIX = 16;
-var HEX_PAD = 2;
-function formatHexEscape(code) {
-  return `\\x${code.toString(HEX_RADIX).padStart(HEX_PAD, "0")}`;
-}
-function nonStringSentinel(type) {
-  return `<non-string:${type}>`;
-}
-function sanitizeCliArgument(input) {
-  if (input === void 0) return SENTINEL_UNDEFINED;
-  if (input === null) return SENTINEL_NULL;
-  if (typeof input !== "string") return nonStringSentinel(typeof input);
-  if (input.length === 0) return SENTINEL_EMPTY;
-  const escaped = escapeControlCharacters(input);
-  return truncate(escaped);
-}
-function escapeControlCharacters(value) {
-  let out = "";
-  for (const char of value) {
-    const code = char.codePointAt(0);
-    if (code === void 0) continue;
-    if (code <= CONTROL_CHAR_UPPER_BOUND || code === DEL_CHAR_CODE) {
-      out += formatHexEscape(code);
-    } else {
-      out += char;
-    }
-  }
-  return out;
-}
-function truncate(value) {
-  if (value.length <= MAX_CLI_ARGUMENT_DISPLAY_LENGTH) return value;
-  return value.slice(0, MAX_CLI_ARGUMENT_DISPLAY_LENGTH - ELLIPSIS_TOKEN.length) + ELLIPSIS_TOKEN;
+  }
+  return {
+    exitCode: hasFailure ? 1 : 0,
+    output: outputs.join("\n"),
+    durationMs: totalDurationMs
+  };
 }
 
 // src/validation/literal/allowlist-existing.ts
 import { rename as rename4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname7, join as join29 } from "path";
+import { dirname as dirname8, join as join30 } from "path";
 var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var INCLUDE_FIELD = "include";
@@ -10211,9 +11240,9 @@ var productionReader = {
 };
 var productionWriter = {
   async write(filePath, content) {
-    const dir = dirname7(filePath);
+    const dir = dirname8(filePath);
     const random = Math.random().toString(RANDOM_BASE).slice(RANDOM_PREFIX_SLICE, RANDOM_PREFIX_SLICE + RANDOM_TOKEN_LENGTH);
-    const tmpPath = join29(dir, `${TEMP_FILE_PREFIX}${random}${TEMP_FILE_SUFFIX}`);
+    const tmpPath = join30(dir, `${TEMP_FILE_PREFIX}${random}${TEMP_FILE_SUFFIX}`);
     await writeFile4(tmpPath, content, "utf8");
     await rename4(tmpPath, filePath);
   }
@@ -10363,6 +11392,10 @@ var literalValidationCliOptions = {
   }
 };
 var allValidationCliOptions = {
+  skipCircular: {
+    flag: "--skip-circular",
+    description: "Skip circular dependency detection for this validation all run"
+  },
   skipLiteral: {
     flag: "--skip-literal",
     description: "Skip literal reuse detection for this validation all run"
@@ -10491,12 +11524,13 @@ function registerValidationCommands(validationCmd) {
     process.exit(result.exitCode);
   });
   addCommonOptions(markdownCmd);
-  const allCmd = addValidationSubcommand(validationCmd, subcommands.all).option("--fix", "Auto-fix ESLint issues").option(allValidationCliOptions.skipLiteral.flag, allValidationCliOptions.skipLiteral.description).action(async (options) => {
+  const allCmd = addValidationSubcommand(validationCmd, subcommands.all).option("--fix", "Auto-fix ESLint issues").option(allValidationCliOptions.skipCircular.flag, allValidationCliOptions.skipCircular.description).option(allValidationCliOptions.skipLiteral.flag, allValidationCliOptions.skipLiteral.description).action(async (options) => {
     const result = await allCommand({
       cwd: process.cwd(),
       scope: options.scope,
       files: options.files,
       fix: options.fix,
+      skipCircular: options.skipCircular,
       skipLiteral: options.skipLiteral,
       quiet: options.quiet,
       json: options.json
@@ -10534,284 +11568,9 @@ var validationDomain = {
   }
 };
 
-// src/domains/worktree/controlling-process.ts
-var CONTROLLING_PID_ENV = "SPX_WORKTREE_CONTROLLING_PID";
-var AGENT_RUNTIME_NAMES = ["claude", "codex"];
-var AGENT_COMMAND_PATTERN = new RegExp(`\\b(?:${AGENT_RUNTIME_NAMES.join("|")})\\b`, "i");
-var CONTROLLING_PROCESS_ERROR = {
-  UNRESOLVED: "worktree controlling process could not be resolved"
-};
-var MAX_ANCESTRY_DEPTH = 64;
-var PID_RADIX = 10;
-function resolveControllingProcess(selfPid, table, env) {
-  const host = table.currentHost();
-  for (const pid of controllingPidCandidates(selfPid, table, env)) {
-    const startedAt = table.startTimeOf(pid);
-    if (startedAt !== void 0) return { ok: true, value: { pid, startedAt, host } };
-  }
-  return { ok: false, error: CONTROLLING_PROCESS_ERROR.UNRESOLVED };
-}
-function* controllingPidCandidates(selfPid, table, env) {
-  const override = parsePid(env[CONTROLLING_PID_ENV]);
-  if (override !== void 0) yield override;
-  const agent = findAgentAncestor(selfPid, table);
-  if (agent !== void 0) yield agent;
-  const parent = table.parentOf(selfPid);
-  if (parent !== void 0) yield parent;
-}
-function findAgentAncestor(selfPid, table) {
-  let pid = table.parentOf(selfPid);
-  for (let depth = 0; pid !== void 0 && depth < MAX_ANCESTRY_DEPTH; depth += 1) {
-    const command = table.commandOf(pid);
-    if (command !== void 0 && AGENT_COMMAND_PATTERN.test(command)) return pid;
-    pid = table.parentOf(pid);
-  }
-  return void 0;
-}
-function parsePid(value) {
-  if (value === void 0 || value.length === 0) return void 0;
-  const parsed = Number.parseInt(value, PID_RADIX);
-  return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
-}
-
-// src/domains/worktree/occupancy-store.ts
-import {
-  mkdir as nodeMkdir2,
-  readFile as nodeReadFile2,
-  rename as nodeRename,
-  rm as nodeRm,
-  writeFile as nodeWriteFile2
-} from "fs/promises";
-import { join as join30 } from "path";
-var OCCUPANCY_STATUS = {
-  UNCLAIMED: "unclaimed",
-  OCCUPIED: "occupied",
-  STALE: "stale"
-};
-var OCCUPANCY_CLAIM = {
-  FILE_EXTENSION: ".claim",
-  TEMP_EXTENSION: ".tmp"
-};
-var OCCUPANCY_ERROR = {
-  INVALID_NAME: "worktree occupancy claim name must be a safe path segment",
-  CLAIM_WRITE_FAILED: "worktree occupancy claim write failed",
-  CLAIM_READ_FAILED: "worktree occupancy claim read failed",
-  CLAIM_REMOVE_FAILED: "worktree occupancy claim remove failed",
-  CLAIM_MALFORMED: "worktree occupancy claim record is malformed"
-};
-var ERROR_DETAIL_SEPARATOR2 = ": ";
-var defaultOccupancyFileSystem = {
-  mkdir: async (path6, options) => {
-    await nodeMkdir2(path6, options);
-  },
-  writeFile: async (path6, data) => {
-    await nodeWriteFile2(path6, data);
-  },
-  rename: nodeRename,
-  readFile: nodeReadFile2,
-  rm: async (path6, options) => {
-    await nodeRm(path6, options);
-  }
-};
-function claimFileName(name) {
-  return `${name}${OCCUPANCY_CLAIM.FILE_EXTENSION}`;
-}
-function claimFilePath(worktreesDir, name) {
-  const validated = validateScopeToken(name);
-  if (!validated.ok) return { ok: false, error: OCCUPANCY_ERROR.INVALID_NAME };
-  return { ok: true, value: join30(worktreesDir, claimFileName(validated.value)) };
-}
-function classifyOccupancy(claim, probe) {
-  if (claim === void 0) return OCCUPANCY_STATUS.UNCLAIMED;
-  if (claim.host !== probe.currentHost()) return OCCUPANCY_STATUS.STALE;
-  if (!probe.isAlive(claim.pid)) return OCCUPANCY_STATUS.STALE;
-  const liveStartTime = probe.startTimeOf(claim.pid);
-  if (liveStartTime !== void 0 && liveStartTime !== claim.startedAt) return OCCUPANCY_STATUS.STALE;
-  return OCCUPANCY_STATUS.OCCUPIED;
-}
-async function writeClaim(worktreesDir, name, record, options = {}) {
-  const fs7 = options.fs ?? defaultOccupancyFileSystem;
-  const pathResult = claimFilePath(worktreesDir, name);
-  if (!pathResult.ok) return pathResult;
-  const claimPath = pathResult.value;
-  const tempPath = `${claimPath}${OCCUPANCY_CLAIM.TEMP_EXTENSION}`;
-  try {
-    await fs7.mkdir(worktreesDir, { recursive: true });
-    await fs7.writeFile(tempPath, serializeClaim(record));
-    await fs7.rename(tempPath, claimPath);
-    return { ok: true, value: claimPath };
-  } catch (error) {
-    return { ok: false, error: formatOccupancyError(OCCUPANCY_ERROR.CLAIM_WRITE_FAILED, toErrorMessage3(error)) };
-  }
-}
-async function readClaim(worktreesDir, name, options = {}) {
-  const fs7 = options.fs ?? defaultOccupancyFileSystem;
-  const pathResult = claimFilePath(worktreesDir, name);
-  if (!pathResult.ok) return pathResult;
-  let content;
-  try {
-    content = await fs7.readFile(pathResult.value, "utf8");
-  } catch (error) {
-    if (hasErrorCode(error, ERROR_CODE_NOT_FOUND)) return { ok: true, value: void 0 };
-    return { ok: false, error: formatOccupancyError(OCCUPANCY_ERROR.CLAIM_READ_FAILED, toErrorMessage3(error)) };
-  }
-  return parseClaim(content);
-}
-async function removeClaim(worktreesDir, name, options = {}) {
-  const fs7 = options.fs ?? defaultOccupancyFileSystem;
-  const pathResult = claimFilePath(worktreesDir, name);
-  if (!pathResult.ok) return pathResult;
-  try {
-    await fs7.rm(pathResult.value, { force: true });
-    return { ok: true, value: void 0 };
-  } catch (error) {
-    return { ok: false, error: formatOccupancyError(OCCUPANCY_ERROR.CLAIM_REMOVE_FAILED, toErrorMessage3(error)) };
-  }
-}
-async function readOccupancy(worktreesDir, name, probe, options = {}) {
-  const claimResult = await readClaim(worktreesDir, name, options);
-  if (!claimResult.ok) return claimResult;
-  return { ok: true, value: classifyOccupancy(claimResult.value, probe) };
-}
-function serializeClaim(record) {
-  return JSON.stringify({
-    sessionId: record.sessionId,
-    host: record.host,
-    pid: record.pid,
-    startedAt: record.startedAt
-  });
-}
-function parseClaim(content) {
-  let parsed;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    return { ok: false, error: OCCUPANCY_ERROR.CLAIM_MALFORMED };
-  }
-  if (!isWorktreeClaimRecord(parsed)) return { ok: false, error: OCCUPANCY_ERROR.CLAIM_MALFORMED };
-  return { ok: true, value: parsed };
-}
-function isWorktreeClaimRecord(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const candidate = value;
-  return typeof candidate.sessionId === "string" && typeof candidate.host === "string" && typeof candidate.pid === "number" && typeof candidate.startedAt === "string";
-}
-function formatOccupancyError(code, detail) {
-  return `${code}${ERROR_DETAIL_SEPARATOR2}${detail}`;
-}
-function toErrorMessage3(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-
-// src/domains/worktree/process-table.ts
-import { spawnSync } from "child_process";
-import { hostname } from "os";
-var PS_COMMAND = "/bin/ps";
-var PS_FIELD = {
-  START_TIME: "lstart",
-  PARENT_PID: "ppid",
-  // The full command line, not `comm` — `comm` reports only the executable
-  // basename, so a shebang-installed agent run through an interpreter reads as
-  // the interpreter (e.g. `node`) and the agent-runtime match misses it. `args`
-  // carries the script path, so both native and interpreted agents are matched.
-  COMMAND: "args"
-};
-var SIGNAL_LIVENESS_PROBE = 0;
-var PROCESS_EXISTS_NO_PERMISSION = "EPERM";
-var PID_RADIX2 = 10;
-var STABLE_PS_ENV = { ...process.env, TZ: "UTC", LC_ALL: "C" };
-function psField(pid, field) {
-  const result = spawnSync(PS_COMMAND, ["-o", `${field}=`, "-p", String(pid)], {
-    encoding: "utf8",
-    env: STABLE_PS_ENV
-  });
-  if (result.status !== 0 || typeof result.stdout !== "string") return void 0;
-  const value = result.stdout.trim();
-  return value.length > 0 ? value : void 0;
-}
-var defaultProcessTable = {
-  currentHost: () => hostname(),
-  isAlive: (pid) => {
-    try {
-      process.kill(pid, SIGNAL_LIVENESS_PROBE);
-      return true;
-    } catch (error) {
-      return hasErrorCode(error, PROCESS_EXISTS_NO_PERMISSION);
-    }
-  },
-  startTimeOf: (pid) => psField(pid, PS_FIELD.START_TIME),
-  parentOf: (pid) => {
-    const value = psField(pid, PS_FIELD.PARENT_PID);
-    if (value === void 0) return void 0;
-    const parsed = Number.parseInt(value, PID_RADIX2);
-    return Number.isInteger(parsed) ? parsed : void 0;
-  },
-  commandOf: (pid) => psField(pid, PS_FIELD.COMMAND)
-};
-
-// src/commands/worktree/resolve.ts
-import { stat as stat4 } from "fs/promises";
-import { dirname as dirname8, resolve as resolve5 } from "path";
-
-// src/domains/worktree/worktree-name.ts
-import { basename as basename4 } from "path";
-var SEPARATOR_CHARACTER = /[^a-z0-9_]/;
-var NAME_SEPARATOR = "-";
-function worktreeClaimName(worktreeRoot) {
-  return basename4(worktreeRoot).toLowerCase().split(SEPARATOR_CHARACTER).filter((segment) => segment.length > 0).join(NAME_SEPARATOR);
-}
-
-// src/commands/worktree/resolve.ts
-var WORKTREE_RESOLVE_ERROR = {
-  NOT_A_WORKTREE: "path resolves to no worktree"
-};
-async function resolveWorktreesDir(options) {
-  if (options.worktreesDir !== void 0) return options.worktreesDir;
-  const resolved = await resolveWorktreesScopeDir({ cwd: options.cwd, deps: options.gitDeps });
-  options.onWarning?.(resolved.warning);
-  return resolved.worktreesDir;
-}
-async function resolveCurrentWorktreeName(options) {
-  const worktree = await detectWorktreeProductRoot(options.cwd, options.gitDeps);
-  return worktreeClaimName(worktree.productDir);
-}
-async function resolveTargetWorktree(options) {
-  const base = options.cwd ?? process.cwd();
-  const targetPath = options.worktree === void 0 ? base : resolve5(base, options.worktree);
-  const targetGitPath = await isExistingNonDirectory(targetPath) ? dirname8(targetPath) : targetPath;
-  const worktree = await detectWorktreeProductRoot(targetGitPath, options.gitDeps);
-  if (!worktree.isGitRepo) {
-    return { ok: false, error: `${WORKTREE_RESOLVE_ERROR.NOT_A_WORKTREE}: ${options.worktree ?? base}` };
-  }
-  return { ok: true, value: { name: worktreeClaimName(worktree.productDir), worktreeRoot: worktree.productDir } };
-}
-async function isExistingNonDirectory(path6) {
-  try {
-    const pathStats = await stat4(path6);
-    return !pathStats.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 // src/commands/worktree/claim.ts
 async function claimCommand(options) {
-  const table = options.processTable ?? defaultProcessTable;
-  const controlling = resolveControllingProcess(options.selfPid ?? process.pid, table, options.env ?? process.env);
-  if (!controlling.ok) return controlling;
-  const worktreesDir = await resolveWorktreesDir(options);
-  const name = await resolveCurrentWorktreeName(options);
-  return writeClaim(
-    worktreesDir,
-    name,
-    {
-      sessionId: options.sessionId,
-      host: controlling.value.host,
-      pid: controlling.value.pid,
-      startedAt: controlling.value.startedAt
-    },
-    { fs: options.fs }
-  );
+  return claimWorktreeOccupancy(options);
 }
 
 // src/commands/worktree/release.ts
@@ -10827,14 +11586,13 @@ var WORKTREE_STATUS_FORMAT = {
   TEXT: "text"
 };
 async function statusCommand2(options) {
-  const table = options.processTable ?? defaultProcessTable;
   const multiTargetRequest = options.worktrees !== void 0 && options.worktrees.length > 1;
   const targets = await resolveStatusTargets(options);
   if (!targets.ok) return targets;
   const records = [];
   for (const target of targets.value) {
     const worktreesDir = await resolveWorktreesDir({ ...options, cwd: target.worktreeRoot });
-    const occupancy = await readOccupancy(worktreesDir, target.name, table, { fs: options.fs });
+    const occupancy = await readOccupancy(worktreesDir, target.name, options.processTable, { fs: options.fs });
     if (!occupancy.ok) return occupancy;
     records.push({ worktree: target.name, status: occupancy.value });
   }
@@ -10872,6 +11630,19 @@ function renderTextStatus(record) {
   return `${record.worktree} ${record.status}`;
 }
 
+// src/lib/worktree-path-info.ts
+import { stat as stat4 } from "fs/promises";
+var defaultWorktreePathInfo = {
+  isExistingNonDirectory: async (path6) => {
+    try {
+      const pathStats = await stat4(path6);
+      return !pathStats.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+};
+
 // src/interfaces/cli/worktree.ts
 var WORKTREE_CLI = {
   COMMAND: "worktree",
@@ -10891,6 +11662,13 @@ function handleError2(error) {
 function registerWorktreeCommands(worktreeCmd) {
   worktreeCmd.command(WORKTREE_CLI.CLAIM).description("Record a worktree-occupancy claim for the running worktree").requiredOption(`${WORKTREE_CLI.SESSION_ID_FLAG} <id>`, "Claiming agent session id").option(`${WORKTREE_CLI.WORKTREES_DIR_FLAG} <path>`, "Explicit .spx/worktrees directory").action(async (options) => {
     const result = await claimCommand({
+      claimWriteToken: createClaimWriteToken(),
+      cwd: process.cwd(),
+      env: process.env,
+      fs: defaultOccupancyFileSystem,
+      gitDeps: defaultGitDependencies,
+      processTable: defaultProcessTable,
+      selfPid: process.pid,
       sessionId: options.sessionId,
       worktreesDir: options.worktreesDir,
       onWarning: writeWarning
@@ -10899,8 +11677,13 @@ function registerWorktreeCommands(worktreeCmd) {
   });
   worktreeCmd.command(`${WORKTREE_CLI.STATUS} ${WORKTREE_CLI.WORKTREE_ARGUMENT}`).description("Report a worktree's occupancy (occupied | unclaimed | stale)").option(`${WORKTREE_CLI.FORMAT_FLAG} <format>`, "Output format (text|json)", WORKTREE_STATUS_FORMAT.TEXT).option(`${WORKTREE_CLI.WORKTREES_DIR_FLAG} <path>`, "Explicit .spx/worktrees directory").action(async (worktrees, options) => {
     const result = await statusCommand2({
+      cwd: process.cwd(),
+      fs: defaultOccupancyFileSystem,
+      gitDeps: defaultGitDependencies,
       worktrees,
       format: options.format,
+      pathInfo: defaultWorktreePathInfo,
+      processTable: defaultProcessTable,
       worktreesDir: options.worktreesDir,
       onWarning: writeWarning
     });
@@ -10908,7 +11691,13 @@ function registerWorktreeCommands(worktreeCmd) {
     console.log(result.value);
   });
   worktreeCmd.command(WORKTREE_CLI.RELEASE).description("Release the running worktree's occupancy claim").option(`${WORKTREE_CLI.WORKTREES_DIR_FLAG} <path>`, "Explicit .spx/worktrees directory").action(async (options) => {
-    const result = await releaseCommand2({ worktreesDir: options.worktreesDir, onWarning: writeWarning });
+    const result = await releaseCommand2({
+      cwd: process.cwd(),
+      fs: defaultOccupancyFileSystem,
+      gitDeps: defaultGitDependencies,
+      worktreesDir: options.worktreesDir,
+      onWarning: writeWarning
+    });
     if (!result.ok) handleError2(result.error);
   });
 }
@@ -10926,6 +11715,7 @@ var CLI_DOMAINS = [
   claudeDomain,
   compactDomain,
   configDomain,
+  hookDomain,
   sessionDomain,
   specDomain,
   testingDomain,