@outcomeeng/spx 0.5.4 → 0.5.5

package/dist/cli.js

@@ -1046,6 +1046,7 @@ var STATE_STORE_PATH = {
   BRANCH_SCOPE: "branch",
   WORKTREE_SCOPE: "worktree",
   SESSIONS_SCOPE: "sessions",
+  WORKTREES_SCOPE: "worktrees",
   RUNS_DIR: "runs",
   RUN_FILE_PREFIX: "run-",
   JSONL_EXTENSION: ".jsonl"
@@ -1109,6 +1110,16 @@ function worktreeScopeDir(productDir) {
 function sessionsScopeDir(productDir) {
   return join2(productDir, STATE_STORE_PATH.SPX_DIR, STATE_STORE_PATH.SESSIONS_SCOPE);
 }
+async function resolveWorktreesScopeDir(options = {}) {
+  const gitResult = await detectGitCommonDirProductRoot(options.cwd, options.deps);
+  return {
+    worktreesDir: worktreesScopeDir(gitResult.productDir),
+    warning: gitResult.warning
+  };
+}
+function worktreesScopeDir(productDir) {
+  return join2(productDir, STATE_STORE_PATH.SPX_DIR, STATE_STORE_PATH.WORKTREES_SCOPE);
+}
 function composeScopeDir(baseScopeDir, ...tokens) {
   const segments = [];
   for (const token of tokens) {
@@ -2516,8 +2527,8 @@ var HIDDEN_PREFIX_LAYER = "hidden-prefix";
 var LAYER2 = HIDDEN_PREFIX_LAYER;
 function hiddenPrefixPredicate(path6, config) {
   const segments = path6.split("/");
-  const basename4 = segments[segments.length - 1] ?? "";
-  const matched = basename4.startsWith(config.hiddenPrefix);
+  const basename5 = segments[segments.length - 1] ?? "";
+  const matched = basename5.startsWith(config.hiddenPrefix);
   return { matched, layer: LAYER2 };
 }
 
@@ -4865,17 +4876,17 @@ async function readStdin() {
   if (process.stdin.isTTY) {
     return void 0;
   }
-  return new Promise((resolve5) => {
+  return new Promise((resolve6) => {
     let data = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
     process.stdin.on("end", () => {
-      resolve5(data.length === 0 ? void 0 : data);
+      resolve6(data.length === 0 ? void 0 : data);
     });
     process.stdin.on("error", () => {
-      resolve5(void 0);
+      resolve6(void 0);
     });
   });
 }
@@ -7813,39 +7824,39 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
       const token = _scanner.scan();
       switch (_scanner.getTokenError()) {
         case 4:
-          handleError2(
+          handleError3(
             14
             /* ParseErrorCode.InvalidUnicode */
           );
           break;
         case 5:
-          handleError2(
+          handleError3(
             15
             /* ParseErrorCode.InvalidEscapeCharacter */
           );
           break;
         case 3:
-          handleError2(
+          handleError3(
             13
             /* ParseErrorCode.UnexpectedEndOfNumber */
           );
           break;
         case 1:
           if (!disallowComments) {
-            handleError2(
+            handleError3(
               11
               /* ParseErrorCode.UnexpectedEndOfComment */
             );
           }
           break;
         case 2:
-          handleError2(
+          handleError3(
             12
             /* ParseErrorCode.UnexpectedEndOfString */
           );
           break;
         case 6:
-          handleError2(
+          handleError3(
             16
             /* ParseErrorCode.InvalidCharacter */
           );
@@ -7855,7 +7866,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
         case 12:
         case 13:
           if (disallowComments) {
-            handleError2(
+            handleError3(
               10
               /* ParseErrorCode.InvalidCommentToken */
             );
@@ -7864,7 +7875,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
           }
           break;
         case 16:
-          handleError2(
+          handleError3(
             1
             /* ParseErrorCode.InvalidSymbol */
           );
@@ -7877,7 +7888,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
       }
     }
   }
-  function handleError2(error, skipUntilAfter = [], skipUntil = []) {
+  function handleError3(error, skipUntilAfter = [], skipUntil = []) {
     onError(error);
     if (skipUntilAfter.length + skipUntil.length > 0) {
       let token = _scanner.getToken();
@@ -7909,7 +7920,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
         const tokenValue = _scanner.getTokenValue();
         let value = Number(tokenValue);
         if (isNaN(value)) {
-          handleError2(
+          handleError3(
             2
             /* ParseErrorCode.InvalidNumberFormat */
           );
@@ -7934,7 +7945,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
   }
   function parseProperty() {
     if (_scanner.getToken() !== 10) {
-      handleError2(3, [], [
+      handleError3(3, [], [
         2,
         5
         /* SyntaxKind.CommaToken */
@@ -7946,14 +7957,14 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
       onSeparator(":");
       scanNext();
       if (!parseValue()) {
-        handleError2(4, [], [
+        handleError3(4, [], [
           2,
           5
           /* SyntaxKind.CommaToken */
         ]);
       }
     } else {
-      handleError2(5, [], [
+      handleError3(5, [], [
         2,
         5
         /* SyntaxKind.CommaToken */
@@ -7969,7 +7980,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
     while (_scanner.getToken() !== 2 && _scanner.getToken() !== 17) {
       if (_scanner.getToken() === 5) {
         if (!needsComma) {
-          handleError2(4, [], []);
+          handleError3(4, [], []);
         }
         onSeparator(",");
         scanNext();
@@ -7977,10 +7988,10 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
           break;
         }
       } else if (needsComma) {
-        handleError2(6, [], []);
+        handleError3(6, [], []);
       }
       if (!parseProperty()) {
-        handleError2(4, [], [
+        handleError3(4, [], [
           2,
           5
           /* SyntaxKind.CommaToken */
@@ -7990,7 +8001,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
     }
     onObjectEnd();
     if (_scanner.getToken() !== 2) {
-      handleError2(7, [
+      handleError3(7, [
         2
         /* SyntaxKind.CloseBraceToken */
       ], []);
@@ -8007,7 +8018,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
     while (_scanner.getToken() !== 4 && _scanner.getToken() !== 17) {
       if (_scanner.getToken() === 5) {
         if (!needsComma) {
-          handleError2(4, [], []);
+          handleError3(4, [], []);
         }
         onSeparator(",");
         scanNext();
@@ -8015,7 +8026,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
           break;
         }
       } else if (needsComma) {
-        handleError2(6, [], []);
+        handleError3(6, [], []);
       }
       if (isFirstElement) {
         _jsonPath.push(0);
@@ -8024,7 +8035,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
         _jsonPath[_jsonPath.length - 1]++;
       }
       if (!parseValue()) {
-        handleError2(4, [], [
+        handleError3(4, [], [
           4,
           5
           /* SyntaxKind.CommaToken */
@@ -8037,7 +8048,7 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
       _jsonPath.pop();
     }
     if (_scanner.getToken() !== 4) {
-      handleError2(8, [
+      handleError3(8, [
         4
         /* SyntaxKind.CloseBracketToken */
       ], []);
@@ -8063,15 +8074,15 @@ function visit(text, visitor, options = ParseOptions.DEFAULT) {
     if (options.allowEmptyContent) {
       return true;
     }
-    handleError2(4, [], []);
+    handleError3(4, [], []);
     return false;
   }
   if (!parseValue()) {
-    handleError2(4, [], []);
+    handleError3(4, [], []);
     return false;
   }
   if (_scanner.getToken() !== 17) {
-    handleError2(9, [], []);
+    handleError3(9, [], []);
   }
   return true;
 }
@@ -8526,13 +8537,13 @@ async function runKnipSubprocess(projectRoot, typescriptScope, runner, deps) {
   knipProcess.stderr?.on("data", (data) => {
     knipError += data.toString();
   });
-  return new Promise((resolve5) => {
+  return new Promise((resolve6) => {
     const resolveAfterCleanup = (result) => {
       if (resultResolved) {
         return;
       }
       resultResolved = true;
-      void cleanupOnce().finally(() => resolve5(result));
+      void cleanupOnce().finally(() => resolve6(result));
     };
     knipProcess.on("close", (code) => {
       if (code === 0) {
@@ -8970,7 +8981,7 @@ async function validateESLint(context, runner = defaultEslintProcessRunner, outp
     scope,
     scopeConfig: context.scopeConfig
   });
-  return new Promise((resolve5) => {
+  return new Promise((resolve6) => {
     const localBin = join26(projectRoot, ...ESLINT_LOCAL_BIN_SEGMENTS);
     const binary = existsSync5(localBin) ? localBin : "npx";
     const spawnArgs = binary === "npx" ? eslintArgs : eslintArgs.slice(1);
@@ -8980,13 +8991,13 @@ async function validateESLint(context, runner = defaultEslintProcessRunner, outp
     forwardValidationSubprocessOutput(eslintProcess, outputStreams);
     eslintProcess.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
       if (code === 0) {
-        resolve5({ success: true });
+        resolve6({ success: true });
       } else {
-        resolve5({ success: false, error: `ESLint exited with code ${code}` });
+        resolve6({ success: false, error: `ESLint exited with code ${code}` });
       }
     });
     eslintProcess.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
-      resolve5({ success: false, error: error.message });
+      resolve6({ success: false, error: error.message });
     });
   });
 }
@@ -9864,7 +9875,7 @@ async function validateTypeScript(context, options = {}) {
   if (files && files.length > 0) {
     const { configPath, cleanup } = await createFileSpecificTsconfig(scope, files, projectRoot, deps);
     try {
-      return await new Promise((resolve5) => {
+      return await new Promise((resolve6) => {
         const tscBin = join28(projectRoot, "node_modules", ".bin", "tsc");
         const tscBinary = deps.existsSync(tscBin) ? tscBin : "npx";
         const tscArgs2 = tscBinary === "npx" ? ["tsc", "--project", configPath] : ["--project", configPath];
@@ -9875,14 +9886,14 @@ async function validateTypeScript(context, options = {}) {
         tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
           cleanup();
           if (code === 0) {
-            resolve5({ success: true, skipped: false });
+            resolve6({ success: true, skipped: false });
           } else {
-            resolve5({ success: false, error: `TypeScript exited with code ${code}` });
+            resolve6({ success: false, error: `TypeScript exited with code ${code}` });
           }
         });
         tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
           cleanup();
-          resolve5({ success: false, error: error.message });
+          resolve6({ success: false, error: error.message });
         });
       });
     } catch (error) {
@@ -9901,7 +9912,7 @@ async function validateTypeScript(context, options = {}) {
     const tscBin = join28(projectRoot, "node_modules", ".bin", "tsc");
     tool = deps.existsSync(tscBin) ? tscBin : "npx";
     tscArgs = tool === "npx" ? ["tsc", "--project", configPath] : ["--project", configPath];
-    return new Promise((resolve5) => {
+    return new Promise((resolve6) => {
       const tscProcess = spawnManagedSubprocess(runner, tool, tscArgs, {
         cwd: projectRoot
       });
@@ -9909,14 +9920,14 @@ async function validateTypeScript(context, options = {}) {
       tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
         cleanup();
         if (code === 0) {
-          resolve5({ success: true, skipped: false });
+          resolve6({ success: true, skipped: false });
         } else {
-          resolve5({ success: false, error: `TypeScript exited with code ${code}` });
+          resolve6({ success: false, error: `TypeScript exited with code ${code}` });
         }
       });
       tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
         cleanup();
-        resolve5({ success: false, error: error.message });
+        resolve6({ success: false, error: error.message });
       });
     });
   } else {
@@ -9925,20 +9936,20 @@ async function validateTypeScript(context, options = {}) {
     const rawArgs = buildTypeScriptArgs({ scope, configFile });
     tscArgs = tool === "npx" ? rawArgs : rawArgs.slice(1);
   }
-  return new Promise((resolve5) => {
+  return new Promise((resolve6) => {
     const tscProcess = spawnManagedSubprocess(runner, tool, tscArgs, {
       cwd: projectRoot
     });
     forwardValidationSubprocessOutput(tscProcess, outputStreams);
     tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
       if (code === 0) {
-        resolve5({ success: true, skipped: false });
+        resolve6({ success: true, skipped: false });
       } else {
-        resolve5({ success: false, error: `TypeScript exited with code ${code}` });
+        resolve6({ success: false, error: `TypeScript exited with code ${code}` });
       }
     });
     tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
-      resolve5({ success: false, error: error.message });
+      resolve6({ success: false, error: error.message });
     });
   });
 }
@@ -10523,6 +10534,393 @@ 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 }
+  );
+}
+
+// src/commands/worktree/release.ts
+async function releaseCommand2(options) {
+  const worktreesDir = await resolveWorktreesDir(options);
+  const name = await resolveCurrentWorktreeName(options);
+  return removeClaim(worktreesDir, name, { fs: options.fs });
+}
+
+// src/commands/worktree/status.ts
+var WORKTREE_STATUS_FORMAT = {
+  JSON: "json",
+  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 });
+    if (!occupancy.ok) return occupancy;
+    records.push({ worktree: target.name, status: occupancy.value });
+  }
+  return { ok: true, value: renderStatus(records, options.format, multiTargetRequest) };
+}
+async function resolveStatusTargets(options) {
+  const requested = options.worktrees;
+  if (requested === void 0 || requested.length === 0) {
+    const target = await resolveTargetWorktree(options);
+    if (!target.ok) return target;
+    return { ok: true, value: [target.value] };
+  }
+  const targets = [];
+  let firstError;
+  for (const worktree of requested) {
+    const target = await resolveTargetWorktree({ ...options, worktree });
+    if (target.ok) {
+      targets.push(target.value);
+    } else {
+      firstError ??= target.error;
+    }
+  }
+  if (targets.length === 0) {
+    return { ok: false, error: firstError ?? "no worktree status targets resolved" };
+  }
+  return { ok: true, value: targets };
+}
+function renderStatus(records, format2, multiTargetRequest) {
+  if (format2 === WORKTREE_STATUS_FORMAT.JSON) {
+    return JSON.stringify(multiTargetRequest ? records : records[0]);
+  }
+  return records.map(renderTextStatus).join("\n");
+}
+function renderTextStatus(record) {
+  return `${record.worktree} ${record.status}`;
+}
+
+// src/interfaces/cli/worktree.ts
+var WORKTREE_CLI = {
+  COMMAND: "worktree",
+  CLAIM: "claim",
+  STATUS: "status",
+  RELEASE: "release",
+  WORKTREE_ARGUMENT: "[worktrees...]",
+  SESSION_ID_FLAG: "--session-id",
+  FORMAT_FLAG: "--format",
+  WORKTREES_DIR_FLAG: "--worktrees-dir"
+};
+var WORKTREE_DOMAIN_DESCRIPTION = "Coordinate worktree occupancy across a bare-repository pool";
+function handleError2(error) {
+  console.error("Error:", error);
+  process.exit(1);
+}
+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({
+      sessionId: options.sessionId,
+      worktreesDir: options.worktreesDir,
+      onWarning: writeWarning
+    });
+    if (!result.ok) handleError2(result.error);
+  });
+  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({
+      worktrees,
+      format: options.format,
+      worktreesDir: options.worktreesDir,
+      onWarning: writeWarning
+    });
+    if (!result.ok) handleError2(result.error);
+    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 });
+    if (!result.ok) handleError2(result.error);
+  });
+}
+var worktreeDomain = {
+  name: WORKTREE_CLI.COMMAND,
+  description: WORKTREE_DOMAIN_DESCRIPTION,
+  register: (program2) => {
+    const worktreeCmd = program2.command(WORKTREE_CLI.COMMAND).description(WORKTREE_DOMAIN_DESCRIPTION);
+    registerWorktreeCommands(worktreeCmd);
+  }
+};
+
 // src/interfaces/cli/registry.ts
 var CLI_DOMAINS = [
   claudeDomain,
@@ -10531,7 +10929,8 @@ var CLI_DOMAINS = [
   sessionDomain,
   specDomain,
   testingDomain,
-  validationDomain
+  validationDomain,
+  worktreeDomain
 ];
 
 // src/cli.ts