@outcomeeng/spx 0.6.3 → 0.6.4

package/dist/cli.js

@@ -1,11 +1,100 @@
 // src/cli.ts
-import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";
 
+// src/interfaces/cli/program.ts
+import { Command } from "commander";
+
+// src/domains/config/cwd.ts
+var CONFIG_PROCESS_CWD = {
+  read: () => process.cwd()
+};
+
+// src/domains/config/root.ts
+import { execFileSync } from "child_process";
+import { resolve } from "path";
+var GIT_EXECUTABLE = "git";
+var GIT_TOPLEVEL_ARGS = ["rev-parse", "--show-toplevel"];
+var GIT_NOT_REPO_MARKER = "not a git repository";
+function resolveProductDir(cwd, deps = DEFAULT_PRODUCT_DIR_RESOLVER_DEPS) {
+  const resolvedCwd = resolve(cwd);
+  const toplevel = deps.readGitToplevel(resolvedCwd);
+  if (toplevel !== void 0 && toplevel.length > 0) {
+    return { productDir: resolve(toplevel) };
+  }
+  return {
+    productDir: resolvedCwd,
+    warning: `warning: ${resolvedCwd} is not inside a git worktree \u2014 falling back to the current working directory. ${GIT_NOT_REPO_MARKER}.`
+  };
+}
+var DEFAULT_PRODUCT_DIR_RESOLVER_DEPS = {
+  readGitToplevel: (cwd) => {
+    try {
+      return execFileSync(GIT_EXECUTABLE, [...GIT_TOPLEVEL_ARGS], {
+        // NOSONAR - spx intentionally uses the caller's git executable.
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf8"
+      }).trim();
+    } catch {
+      return void 0;
+    }
+  }
+};
+
+// src/interfaces/cli/product-context.ts
+import { resolve as resolve2 } from "path";
+var SPX_GLOBAL_OPTIONS = {
+  directory: {
+    short: "-C",
+    long: "--directory",
+    operand: "<path>",
+    flags: "-C, --directory <path>",
+    description: "Run as if spx was started in <path>"
+  }
+};
+function createCliInvocation(options) {
+  let cachedEffectiveInvocationDir;
+  let cachedContext;
+  const resolveEffectiveInvocationDir = () => {
+    cachedEffectiveInvocationDir ??= resolve2(options.processCwd(), options.readDirectoryOption() ?? "");
+    return cachedEffectiveInvocationDir;
+  };
+  return {
+    io: options.io,
+    resolveEffectiveInvocationDir,
+    resolveProductContext: () => {
+      if (cachedContext !== void 0) {
+        return cachedContext;
+      }
+      const effectiveInvocationDir = resolveEffectiveInvocationDir();
+      const resolved = (options.resolveProductDir ?? resolveProductDir)(effectiveInvocationDir);
+      cachedContext = {
+        effectiveInvocationDir,
+        productDir: resolved.productDir,
+        ...resolved.warning === void 0 ? {} : { warning: resolved.warning }
+      };
+      options.writeWarning(cachedContext.warning);
+      return cachedContext;
+    }
+  };
+}
+var DEFAULT_CLI_IO = {
+  writeStdout: (output) => {
+    process.stdout.write(output);
+  },
+  writeStderr: (output) => {
+    process.stderr.write(output);
+  },
+  setExitCode: (exitCode) => {
+    process.exitCode = exitCode;
+  },
+  exit: (exitCode) => process.exit(exitCode)
+};
+
 // src/commands/claude/init.ts
 import { execa } from "execa";
 async function initCommand(options = {}) {
-  const cwd = options.cwd || process.cwd();
+  const cwd = options.cwd || CONFIG_PROCESS_CWD.read();
   try {
     const { stdout: listOutput } = await execa(
       "claude",
@@ -115,7 +204,7 @@ import { dirname as dirname2, join as join2 } from "path";
 
 // src/git/root.ts
 import { execa as execa2 } from "execa";
-import { basename, dirname, isAbsolute, join, resolve } from "path";
+import { basename, dirname, isAbsolute, join, resolve as resolve3 } from "path";
 
 // src/git/environment.ts
 function withoutGitEnvironment(env) {
@@ -223,7 +312,7 @@ var GIT_WORKTREE_PORCELAIN_BARE_LINE = "bare";
 var GIT_WORKTREE_PORCELAIN_PRUNABLE_LINE = "prunable";
 var GIT_WORKTREE_PORCELAIN_PRUNABLE_PREFIX = `${GIT_WORKTREE_PORCELAIN_PRUNABLE_LINE} `;
 var TRAILING_PATH_SEPARATORS_PATTERN = /[\\/]+$/;
-async function detectWorktreeProductRoot(cwd = process.cwd(), deps = defaultGitDependencies) {
+async function detectWorktreeProductRoot(cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   try {
     const result = await deps.execa(
       GIT_ROOT_COMMAND.EXECUTABLE,
@@ -259,7 +348,7 @@ function trimStdout(stdout) {
   const str = typeof stdout === "string" ? stdout : String(stdout);
   return str.trim();
 }
-async function detectGitCommonDirProductRoot(cwd = process.cwd(), deps = defaultGitDependencies) {
+async function detectGitCommonDirProductRoot(cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   try {
     const toplevelResult = await deps.execa(
       GIT_ROOT_COMMAND.EXECUTABLE,
@@ -288,7 +377,7 @@ async function detectGitCommonDirProductRoot(cwd = process.cwd(), deps = default
       };
     }
     const commonDir = extractStdout(commonDirResult.stdout);
-    const absoluteCommonDir = isAbsolute(commonDir) ? commonDir : resolve(toplevel, commonDir);
+    const absoluteCommonDir = isAbsolute(commonDir) ? commonDir : resolve3(toplevel, commonDir);
     const gitCommonDirProductRoot = dirname(absoluteCommonDir);
     return {
       productDir: gitCommonDirProductRoot,
@@ -304,7 +393,7 @@ async function detectGitCommonDirProductRoot(cwd = process.cwd(), deps = default
     };
   }
 }
-async function resolveDefaultBranch(cwd = process.cwd(), deps = defaultGitDependencies) {
+async function resolveDefaultBranch(cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   const result = await deps.execa(
     GIT_ROOT_COMMAND.EXECUTABLE,
     [...GIT_ORIGIN_HEAD_REF_ARGS],
@@ -316,7 +405,7 @@ async function resolveDefaultBranch(cwd = process.cwd(), deps = defaultGitDepend
   const branch = ref.slice(ORIGIN_REF_PREFIX.length);
   return branch.length === 0 ? null : branch;
 }
-async function getCurrentBranch(cwd = process.cwd(), deps = defaultGitDependencies) {
+async function getCurrentBranch(cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   const result = await deps.execa(
     GIT_ROOT_COMMAND.EXECUTABLE,
     [...GIT_CURRENT_BRANCH_ARGS],
@@ -327,7 +416,7 @@ async function getCurrentBranch(cwd = process.cwd(), deps = defaultGitDependenci
   if (branch.length === 0 || branch === GIT_ROOT_COMMAND.HEAD) return null;
   return branch;
 }
-async function getHeadSha(cwd = process.cwd(), deps = defaultGitDependencies) {
+async function getHeadSha(cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   const result = await deps.execa(
     GIT_ROOT_COMMAND.EXECUTABLE,
     [...GIT_HEAD_SHA_ARGS],
@@ -337,7 +426,7 @@ async function getHeadSha(cwd = process.cwd(), deps = defaultGitDependencies) {
   const sha = extractStdout(result.stdout);
   return sha.length === 0 ? null : sha;
 }
-async function resolveRefSha(ref, cwd = process.cwd(), deps = defaultGitDependencies) {
+async function resolveRefSha(ref, cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   const result = await deps.execa(
     GIT_ROOT_COMMAND.EXECUTABLE,
     [GIT_ROOT_COMMAND.REV_PARSE, ref],
@@ -347,7 +436,7 @@ async function resolveRefSha(ref, cwd = process.cwd(), deps = defaultGitDependen
   const sha = extractStdout(result.stdout);
   return sha.length === 0 ? null : sha;
 }
-async function originBranchExists(branch, cwd = process.cwd(), deps = defaultGitDependencies) {
+async function originBranchExists(branch, cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   if (branch === GIT_ROOT_COMMAND.HEAD) return false;
   const result = await deps.execa(
     GIT_ROOT_COMMAND.EXECUTABLE,
@@ -361,7 +450,7 @@ async function originBranchExists(branch, cwd = process.cwd(), deps = defaultGit
   );
   return result.exitCode === 0;
 }
-async function isWorkingTreeClean(cwd = process.cwd(), deps = defaultGitDependencies) {
+async function isWorkingTreeClean(cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   const result = await deps.execa(
     GIT_ROOT_COMMAND.EXECUTABLE,
     [...GIT_STATUS_PORCELAIN_ARGS],
@@ -427,7 +516,7 @@ function mainCheckoutPath(facts) {
   const candidate = join(commonDirParent, name);
   return isObservedWorktreeRoot(facts.worktreeRoots, candidate) ? candidate : null;
 }
-async function gatherGitFacts(cwd = process.cwd(), deps = defaultGitDependencies) {
+async function gatherGitFacts(cwd = CONFIG_PROCESS_CWD.read(), deps = defaultGitDependencies) {
   try {
     const [toplevelResult, commonDirResult, originResult, worktreeListResult] = await Promise.all([
       deps.execa(GIT_ROOT_COMMAND.EXECUTABLE, [...GIT_SHOW_TOPLEVEL_ARGS], { cwd, reject: false }),
@@ -451,7 +540,7 @@ async function gatherGitFacts(cwd = process.cwd(), deps = defaultGitDependencies
       };
     }
     const rawCommonDir = extractStdout(commonDirResult.stdout);
-    const commonDir = isAbsolute(rawCommonDir) ? rawCommonDir : resolve(worktreeRoot, rawCommonDir);
+    const commonDir = isAbsolute(rawCommonDir) ? rawCommonDir : resolve3(worktreeRoot, rawCommonDir);
     const bareResult = await deps.execa(
       GIT_ROOT_COMMAND.EXECUTABLE,
       [...GIT_CORE_BARE_ARGS],
@@ -1307,17 +1396,35 @@ Searched for: **/.claude/settings.local.json`;
 }
 
 // src/interfaces/cli/claude.ts
-function registerClaudeCommands(claudeCmd) {
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return "Unknown error";
+}
+function writeOutput(io, output) {
+  io.writeStdout(`${output}
+`);
+}
+function writeError(io, output) {
+  io.writeStderr(`${output}
+`);
+}
+function exitWithError(io, error) {
+  writeError(io, `Error: ${formatError(error)}`);
+  return io.exit(1);
+}
+function registerClaudeCommands(claudeCmd, invocation) {
+  const productDir = () => invocation.resolveProductContext().productDir;
   claudeCmd.command("init").description("Initialize or update outcomeeng marketplace plugin").action(async () => {
     try {
-      const output = await initCommand({ cwd: process.cwd() });
-      console.log(output);
+      const output = await initCommand({ cwd: productDir() });
+      writeOutput(invocation.io, output);
     } catch (error) {
-      console.error(
-        "Error:",
-        error instanceof Error ? error.message : String(error)
-      );
-      process.exit(1);
+      exitWithError(invocation.io, error);
     }
   });
   const settingsCmd = claudeCmd.command("settings").description("Manage Claude Code settings");
@@ -1336,10 +1443,11 @@ function registerClaudeCommands(claudeCmd) {
     async (options) => {
       try {
         if (options.write && options.outputFile) {
-          console.error(
+          writeError(
+            invocation.io,
             "Error: --write and --output-file are mutually exclusive\nUse --write to modify global settings, or --output-file to write to a different location"
           );
-          process.exit(1);
+          return invocation.io.exit(1);
         }
         const output = await consolidateCommand({
           write: options.write,
@@ -1347,13 +1455,9 @@ function registerClaudeCommands(claudeCmd) {
           root: options.root,
           globalSettings: options.globalSettings
         });
-        console.log(output);
+        writeOutput(invocation.io, output);
       } catch (error) {
-        console.error(
-          "Error:",
-          error instanceof Error ? error.message : String(error)
-        );
-        process.exit(1);
+        exitWithError(invocation.io, error);
       }
     }
   );
@@ -1361,9 +1465,9 @@ function registerClaudeCommands(claudeCmd) {
 var claudeDomain = {
   name: "claude",
   description: "Manage Claude Code settings and plugins",
-  register: (program2) => {
-    const claudeCmd = program2.command("claude").description("Manage Claude Code settings and plugins");
-    registerClaudeCommands(claudeCmd);
+  register: (program, invocation) => {
+    const claudeCmd = program.command("claude").description("Manage Claude Code settings and plugins");
+    registerClaudeCommands(claudeCmd, invocation);
   }
 };
 
@@ -1520,8 +1624,8 @@ function readTargetPath(value, startIndex) {
   return value.slice(startIndex, endIndex);
 }
 function isTargetPathCharacter(character) {
-  const code = character.codePointAt(0);
-  return code !== void 0 && (code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122 || character === "." || character === "_" || character === "-" || character === "/");
+  const code = character.codePointAt(0) ?? 0;
+  return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122 || character === "." || character === "_" || character === "-" || character === "/";
 }
 
 // src/commands/compact/retrieve.ts
@@ -1576,14 +1680,15 @@ var COMPACT_CLI = {
 var compactDomain = {
   name: COMPACT_CLI.commandName,
   description: COMPACT_CLI.description,
-  register: (program2) => {
-    const compactCmd = program2.command(COMPACT_CLI.commandName).description(COMPACT_CLI.description);
+  register: (program, invocation) => {
+    const effectiveInvocationDir = () => invocation.resolveEffectiveInvocationDir();
+    const compactCmd = program.command(COMPACT_CLI.commandName).description(COMPACT_CLI.description);
     compactCmd.command(COMPACT_CLI.storeCommandName).description("Store compact resume state").requiredOption(COMPACT_CLI.transcriptOption, "Transcript JSONL path").option(COMPACT_CLI.sessionIdOption, COMPACT_CLI.sessionIdDescription).action(async (options) => {
-      process.exit(
+      invocation.io.exit(
         await compactStoreCommand({
           transcript: options.transcript,
           sessionId: options.sessionId,
-          cwd: process.cwd(),
+          cwd: effectiveInvocationDir(),
           env: process.env
         })
       );
@@ -1591,13 +1696,13 @@ var compactDomain = {
     compactCmd.command(COMPACT_CLI.retrieveCommandName).description("Retrieve compact resume state").option(COMPACT_CLI.sessionIdOption, COMPACT_CLI.sessionIdDescription).action(async (options) => {
       const result = await compactRetrieveCommand({
         sessionId: options.sessionId,
-        cwd: process.cwd(),
+        cwd: effectiveInvocationDir(),
         env: process.env
       });
       if (result.output.length > 0) {
-        process.stdout.write(result.output);
+        invocation.io.writeStdout(result.output);
       }
-      process.exitCode = result.exitCode;
+      invocation.io.setExitCode(result.exitCode);
     });
   }
 };
@@ -1614,7 +1719,8 @@ function toMessage(error) {
   if (typeof error === "string") return error;
   const fallback = `[${typeof error}]`;
   try {
-    return JSON.stringify(error) ?? fallback;
+    const serialized = JSON.stringify(error);
+    return typeof serialized === "string" ? serialized : fallback;
   } catch {
     return fallback;
   }
@@ -2290,11 +2396,11 @@ function compareNamingSchemaVersions(left, right) {
   return compareNumericVersionIdentifiers(left.version, right.version);
 }
 function canonicalNamingSchemaVersion(versions) {
-  const [first, ...rest] = versions;
+  const first = versions.at(0);
   if (first === void 0) {
     throw new Error("Naming-schema version tuple must declare at least one version");
   }
-  return rest.reduce(
+  return versions.slice(1).reduce(
     (max, version2) => compareNamingSchemaVersions(version2, max) > VERSION_ORDER_EQUAL ? version2 : max,
     first
   );
@@ -3475,9 +3581,6 @@ function defaultsCommand(options, deps) {
 function formatConfig(config, asJson) {
   const format2 = asJson ? CONFIG_FILE_FORMAT.JSON : DEFAULT_CONFIG_FILE_FORMAT;
   const serialized = serializeConfigFileSections(format2, config);
-  if (!serialized.ok) {
-    throw new Error(serialized.error);
-  }
   return serialized.value;
 }
 
@@ -3503,9 +3606,6 @@ async function showCommand(options, deps) {
 function formatConfig2(config, asJson) {
   const format2 = asJson ? CONFIG_FILE_FORMAT.JSON : DEFAULT_CONFIG_FILE_FORMAT;
   const serialized = serializeConfigFileSections(format2, config);
-  if (!serialized.ok) {
-    throw new Error(serialized.error);
-  }
   return serialized.value;
 }
 
@@ -3549,82 +3649,55 @@ async function validateCommand(_options, deps) {
   return { stdout, stderr: "", exitCode: 0 };
 }
 
-// src/domains/config/root.ts
-import { execSync } from "child_process";
-import { resolve as resolve2 } from "path";
-var GIT_TOPLEVEL_CMD = "git rev-parse --show-toplevel";
-var GIT_NOT_REPO_MARKER = "not a git repository";
-function resolveProductDir(cwd = process.cwd()) {
-  const resolvedCwd = resolve2(cwd);
-  try {
-    const stdout = execSync(GIT_TOPLEVEL_CMD, {
-      cwd: resolvedCwd,
-      stdio: ["ignore", "pipe", "pipe"],
-      encoding: "utf8"
-    });
-    const toplevel = stdout.trim();
-    if (toplevel.length > 0) {
-      return { productDir: resolve2(toplevel) };
-    }
-  } catch {
-  }
-  return {
-    productDir: resolvedCwd,
-    warning: `warning: ${resolvedCwd} is not inside a git worktree \u2014 falling back to the current working directory. ${GIT_NOT_REPO_MARKER}.`
-  };
-}
-
-// src/interfaces/cli/write-warning.ts
-function writeWarning(warning) {
-  if (warning === void 0) {
-    return;
-  }
-  process.stderr.write(`${warning}
-`);
-}
-
 // src/interfaces/cli/config.ts
-function buildDefaultDeps() {
+var CONFIG_CLI = {
+  commandName: "config",
+  commands: {
+    defaults: "defaults",
+    show: "show",
+    validate: "validate"
+  },
+  flags: {
+    json: "--json"
+  }
+};
+function buildDefaultDeps(invocation) {
   return {
     resolveConfig,
     readProductConfigFile,
     resolveConfigFromReadResult,
-    resolveProductDir: () => {
-      const resolved = resolveProductDir();
-      writeWarning(resolved.warning);
-      return resolved.productDir;
-    },
+    resolveProductDir: () => invocation.resolveProductContext().productDir,
     descriptors: productionRegistry
   };
 }
-async function emit(result) {
+async function emit(result, io) {
   if (result.stdout.length > 0) {
-    process.stdout.write(result.stdout);
+    io.writeStdout(result.stdout);
   }
   if (result.stderr.length > 0) {
-    process.stderr.write(result.stderr);
+    io.writeStderr(result.stderr);
   }
-  return process.exit(result.exitCode);
+  return io.exit(result.exitCode);
 }
-function registerConfigCommands(configCmd) {
-  configCmd.command("show").description(
-    `Print the resolved configuration as ${DEFAULT_CONFIG_FILE_FORMAT.toUpperCase()} (or ${CONFIG_FILE_FORMAT.JSON.toUpperCase()} with --json)`
-  ).option("--json", `Output as ${CONFIG_FILE_FORMAT.JSON.toUpperCase()}`).action(async (options) => {
-    await emit(await showCommand(options, buildDefaultDeps()));
+function registerConfigCommands(configCmd, invocation) {
+  configCmd.command(CONFIG_CLI.commands.show).description(
+    `Print the resolved configuration as ${DEFAULT_CONFIG_FILE_FORMAT.toUpperCase()} (or ${CONFIG_FILE_FORMAT.JSON.toUpperCase()} with ${CONFIG_CLI.flags.json})`
+  ).option(CONFIG_CLI.flags.json, `Output as ${CONFIG_FILE_FORMAT.JSON.toUpperCase()}`).action(async (options) => {
+    await emit(await showCommand(options, buildDefaultDeps(invocation)), invocation.io);
   });
-  configCmd.command("validate").description(`Verify that ${DEFAULT_CONFIG_FILENAME} passes every registered descriptor's validator`).action(async (options) => {
-    await emit(await validateCommand(options, buildDefaultDeps()));
+  configCmd.command(CONFIG_CLI.commands.validate).description(`Verify that ${DEFAULT_CONFIG_FILENAME} passes every registered descriptor's validator`).action(async (options) => {
+    await emit(await validateCommand(options, buildDefaultDeps(invocation)), invocation.io);
   });
-  configCmd.command("defaults").description(`Print each registered descriptor's defaults; ignores ${DEFAULT_CONFIG_FILENAME}`).option("--json", `Output as ${CONFIG_FILE_FORMAT.JSON.toUpperCase()}`).action(async (options) => {
-    await emit(await defaultsCommand(options, buildDefaultDeps()));
+  configCmd.command(CONFIG_CLI.commands.defaults).description(`Print each registered descriptor's defaults; ignores ${DEFAULT_CONFIG_FILENAME}`).option(CONFIG_CLI.flags.json, `Output as ${CONFIG_FILE_FORMAT.JSON.toUpperCase()}`).action(async (options) => {
+    await emit(await defaultsCommand(options, buildDefaultDeps(invocation)), invocation.io);
   });
 }
 var configDomain = {
   name: "config",
   description: "Inspect and validate the resolved spx configuration",
-  register: (program2) => {
-    const configCmd = program2.command("config").description("Inspect and validate the resolved spx configuration");
-    registerConfigCommands(configCmd);
+  register: (program, invocation) => {
+    const configCmd = program.command(CONFIG_CLI.commandName).description("Inspect and validate the resolved spx configuration");
+    registerConfigCommands(configCmd, invocation);
   }
 };
 
@@ -3918,8 +3991,48 @@ async function diagnoseCommand(options) {
 }
 
 // src/commands/diagnose/probes.ts
+import { dirname as dirname3 } from "path";
 import { execa as execa3 } from "execa";
 
+// src/domains/diagnose/checks/session-store.ts
+var SESSION_STORE_VERDICT = {
+  CONSISTENT: "consistent",
+  ORPHANED_CLAIMS: "orphaned-claims",
+  UNKNOWN: "unknown"
+};
+function doingSessionBackedByClaim(session, claimedSessionIds2) {
+  if (claimedSessionIds2.has(normalizeAgentSessionToken(session.id))) return true;
+  return session.agent_session_id !== void 0 && claimedSessionIds2.has(normalizeAgentSessionToken(session.agent_session_id));
+}
+var REMEDIATION = {
+  [SESSION_STORE_VERDICT.CONSISTENT]: "Session store is consistent; no action needed.",
+  [SESSION_STORE_VERDICT.ORPHANED_CLAIMS]: "Release or reclaim doing sessions whose backing worktree reads free or is absent (spx session release).",
+  [SESSION_STORE_VERDICT.UNKNOWN]: "Re-run diagnose; if it persists, inspect spx session list and spx worktree status."
+};
+function record(verdict, bucket, reading) {
+  return {
+    name: CHECK_NAME.SESSION_STORE,
+    verdict,
+    bucket,
+    readings: {
+      orphaned: String(reading.orphanedClaims)
+    },
+    remediation: REMEDIATION[verdict]
+  };
+}
+function classifySessionStore(reading) {
+  if (reading.errored) {
+    return record(SESSION_STORE_VERDICT.UNKNOWN, VERDICT_BUCKET.UNKNOWN, reading);
+  }
+  if (reading.orphanedClaims > 0) {
+    return record(SESSION_STORE_VERDICT.ORPHANED_CLAIMS, VERDICT_BUCKET.DEGRADED, reading);
+  }
+  return record(SESSION_STORE_VERDICT.CONSISTENT, VERDICT_BUCKET.HEALTHY, reading);
+}
+function sessionStoreRunner(probe) {
+  return async () => classifySessionStore(await probe.probe());
+}
+
 // src/domains/hooks/session-start.ts
 var HOOK_SESSION_START_PAYLOAD = {
   CWD: "cwd",
@@ -4117,10 +4230,7 @@ function formatOccupancyError(code, detail) {
   return `${code}${ERROR_DETAIL_SEPARATOR2}${detail}`;
 }
 function toErrorMessage2(error) {
-  if (error instanceof Error) return error.message;
-  if (typeof error === "string") return error;
-  if (typeof error === "number" || typeof error === "bigint" || typeof error === "boolean") return error.toString();
-  return JSON.stringify(error) ?? "unknown error";
+  return toMessage(error);
 }
 
 // src/domains/worktree/worktree-name.ts
@@ -4273,13 +4383,12 @@ var defaultWorktreePoolProbe = {
       running: 0,
       free: 0
     };
-    const root = await detectGitCommonDirProductRoot();
     const facts = await gatherGitFacts();
-    if (!root.isGitRepo || !facts?.worktreeListRead) return errored;
+    if (!facts?.worktreeListRead) return errored;
     const bareRepository = facts.commonDirIsBare;
     const paths = facts.worktreeRoots;
     const linkedWorktrees = !bareRepository && paths.length > 1;
-    const worktreesDir = worktreesScopeDir(root.productDir);
+    const worktreesDir = worktreesScopeDir(dirname3(facts.commonDir));
     let running = 0;
     let free = 0;
     for (const path7 of paths) {
@@ -4316,11 +4425,9 @@ var defaultSessionEnvironmentProbe = {
   }
 };
 async function claimedSessionIds() {
-  const root = await detectGitCommonDirProductRoot();
-  if (!root.isGitRepo) return null;
-  const worktreesDir = worktreesScopeDir(root.productDir);
   const facts = await gatherGitFacts();
   if (!facts?.worktreeListRead) return null;
+  const worktreesDir = worktreesScopeDir(dirname3(facts.commonDir));
   const sessionIds = /* @__PURE__ */ new Set();
   for (const path7 of facts.worktreeRoots) {
     const claim = await readClaim(worktreesDir, worktreeClaimName(path7), { fs: defaultOccupancyFileSystem });
@@ -4347,8 +4454,7 @@ var defaultSessionStoreProbe = {
     }
     let orphanedClaims = 0;
     for (const session of doing) {
-      const sessionId = session.agent_session_id;
-      if (sessionId !== void 0 && !claimed.has(sessionId)) orphanedClaims += 1;
+      if (!doingSessionBackedByClaim(session, claimed)) orphanedClaims += 1;
     }
     return { errored: false, orphanedClaims };
   }
@@ -4473,14 +4579,14 @@ var MARKETPLACE_INSTALL_VERDICT = {
   NOT_APPLICABLE: "not-applicable",
   UNKNOWN: "unknown"
 };
-var REMEDIATION = {
+var REMEDIATION2 = {
   [MARKETPLACE_INSTALL_VERDICT.INSTALLED]: "Marketplace and expected plugins are installed and enabled; no action needed.",
   [MARKETPLACE_INSTALL_VERDICT.DRIFTED]: "Install or enable the expected plugins on the drifted surface.",
   [MARKETPLACE_INSTALL_VERDICT.UNREGISTERED]: "Register the methodology marketplace on the present plugin surface.",
   [MARKETPLACE_INSTALL_VERDICT.NOT_APPLICABLE]: "No plugin CLI surface present; no action needed.",
   [MARKETPLACE_INSTALL_VERDICT.UNKNOWN]: "Re-run diagnose; if it persists, inspect the claude/codex plugin CLI output."
 };
-function record(verdict, bucket, reading) {
+function record2(verdict, bucket, reading) {
   return {
     name: CHECK_NAME.MARKETPLACE_INSTALL,
     verdict,
@@ -4490,23 +4596,23 @@ function record(verdict, bucket, reading) {
       unregistered: String(reading.unregistered),
       drifted: String(reading.drifted)
     },
-    remediation: REMEDIATION[verdict]
+    remediation: REMEDIATION2[verdict]
   };
 }
 function classifyMarketplaceInstall(reading) {
   if (reading.errored) {
-    return record(MARKETPLACE_INSTALL_VERDICT.UNKNOWN, VERDICT_BUCKET.UNKNOWN, reading);
+    return record2(MARKETPLACE_INSTALL_VERDICT.UNKNOWN, VERDICT_BUCKET.UNKNOWN, reading);
   }
   if (!reading.surfacePresent) {
-    return record(MARKETPLACE_INSTALL_VERDICT.NOT_APPLICABLE, VERDICT_BUCKET.NOT_APPLICABLE, reading);
+    return record2(MARKETPLACE_INSTALL_VERDICT.NOT_APPLICABLE, VERDICT_BUCKET.NOT_APPLICABLE, reading);
   }
   if (reading.unregistered) {
-    return record(MARKETPLACE_INSTALL_VERDICT.UNREGISTERED, VERDICT_BUCKET.BROKEN, reading);
+    return record2(MARKETPLACE_INSTALL_VERDICT.UNREGISTERED, VERDICT_BUCKET.BROKEN, reading);
   }
   if (reading.drifted) {
-    return record(MARKETPLACE_INSTALL_VERDICT.DRIFTED, VERDICT_BUCKET.DEGRADED, reading);
+    return record2(MARKETPLACE_INSTALL_VERDICT.DRIFTED, VERDICT_BUCKET.DEGRADED, reading);
   }
-  return record(MARKETPLACE_INSTALL_VERDICT.INSTALLED, VERDICT_BUCKET.HEALTHY, reading);
+  return record2(MARKETPLACE_INSTALL_VERDICT.INSTALLED, VERDICT_BUCKET.HEALTHY, reading);
 }
 function marketplaceInstallRunner(probe) {
   return async (manifest) => {
@@ -4525,14 +4631,14 @@ var SESSION_ENVIRONMENT_VERDICT = {
   NOT_APPLICABLE: "not-applicable",
   UNKNOWN: "unknown"
 };
-var REMEDIATION2 = {
+var REMEDIATION3 = {
   [SESSION_ENVIRONMENT_VERDICT.WORKING]: "Session environment is established; no action needed.",
   [SESSION_ENVIRONMENT_VERDICT.IDENTITY_ONLY]: "The SessionStart hook set the session identity but did not claim the worktree; check the worktree-claim step.",
   [SESSION_ENVIRONMENT_VERDICT.SILENT_NO_OP]: "The SessionStart hook ran without effect; verify the hook resolves spx and the agent session id.",
-  [SESSION_ENVIRONMENT_VERDICT.NOT_APPLICABLE]: "No spec-tree SessionStart hook on this runtime; no action needed.",
+  [SESSION_ENVIRONMENT_VERDICT.NOT_APPLICABLE]: "No SessionStart hook signal or agent session identity was observed; confirm a spec-tree SessionStart hook is configured and enabled.",
   [SESSION_ENVIRONMENT_VERDICT.UNKNOWN]: "Re-run diagnose; if it persists, inspect the agent session id and spx worktree status."
 };
-function record2(verdict, bucket, reading) {
+function record3(verdict, bucket, reading) {
   return {
     name: CHECK_NAME.SESSION_ENVIRONMENT,
     verdict,
@@ -4542,66 +4648,31 @@ function record2(verdict, bucket, reading) {
       identity: String(reading.sessionIdentity),
       claimed: String(reading.worktreeClaimed)
     },
-    remediation: REMEDIATION2[verdict]
+    remediation: REMEDIATION3[verdict]
   };
 }
 function classifySessionEnvironment(reading) {
-  if (!reading.hookPresent) {
-    return record2(SESSION_ENVIRONMENT_VERDICT.NOT_APPLICABLE, VERDICT_BUCKET.NOT_APPLICABLE, reading);
-  }
   if (reading.errored) {
-    return record2(SESSION_ENVIRONMENT_VERDICT.UNKNOWN, VERDICT_BUCKET.UNKNOWN, reading);
+    return record3(SESSION_ENVIRONMENT_VERDICT.UNKNOWN, VERDICT_BUCKET.UNKNOWN, reading);
   }
   if (reading.sessionIdentity && reading.worktreeClaimed) {
-    return record2(SESSION_ENVIRONMENT_VERDICT.WORKING, VERDICT_BUCKET.HEALTHY, reading);
+    return record3(SESSION_ENVIRONMENT_VERDICT.WORKING, VERDICT_BUCKET.HEALTHY, reading);
   }
   if (reading.sessionIdentity) {
-    return record2(SESSION_ENVIRONMENT_VERDICT.IDENTITY_ONLY, VERDICT_BUCKET.DEGRADED, reading);
+    return record3(SESSION_ENVIRONMENT_VERDICT.IDENTITY_ONLY, VERDICT_BUCKET.DEGRADED, reading);
   }
-  if (!reading.worktreeClaimed) {
-    return record2(SESSION_ENVIRONMENT_VERDICT.SILENT_NO_OP, VERDICT_BUCKET.BROKEN, reading);
+  if (reading.hookPresent && !reading.worktreeClaimed) {
+    return record3(SESSION_ENVIRONMENT_VERDICT.SILENT_NO_OP, VERDICT_BUCKET.BROKEN, reading);
   }
-  return record2(SESSION_ENVIRONMENT_VERDICT.UNKNOWN, VERDICT_BUCKET.UNKNOWN, reading);
+  if (!reading.hookPresent && !reading.worktreeClaimed) {
+    return record3(SESSION_ENVIRONMENT_VERDICT.NOT_APPLICABLE, VERDICT_BUCKET.NOT_APPLICABLE, reading);
+  }
+  return record3(SESSION_ENVIRONMENT_VERDICT.UNKNOWN, VERDICT_BUCKET.UNKNOWN, reading);
 }
 function sessionEnvironmentRunner(probe) {
   return async () => classifySessionEnvironment(await probe.probe());
 }
 
-// src/domains/diagnose/checks/session-store.ts
-var SESSION_STORE_VERDICT = {
-  CONSISTENT: "consistent",
-  ORPHANED_CLAIMS: "orphaned-claims",
-  UNKNOWN: "unknown"
-};
-var REMEDIATION3 = {
-  [SESSION_STORE_VERDICT.CONSISTENT]: "Session store is consistent; no action needed.",
-  [SESSION_STORE_VERDICT.ORPHANED_CLAIMS]: "Release or reclaim doing sessions whose backing worktree reads free or is absent (spx session release).",
-  [SESSION_STORE_VERDICT.UNKNOWN]: "Re-run diagnose; if it persists, inspect spx session list and spx worktree status."
-};
-function record3(verdict, bucket, reading) {
-  return {
-    name: CHECK_NAME.SESSION_STORE,
-    verdict,
-    bucket,
-    readings: {
-      orphaned: String(reading.orphanedClaims)
-    },
-    remediation: REMEDIATION3[verdict]
-  };
-}
-function classifySessionStore(reading) {
-  if (reading.errored) {
-    return record3(SESSION_STORE_VERDICT.UNKNOWN, VERDICT_BUCKET.UNKNOWN, reading);
-  }
-  if (reading.orphanedClaims > 0) {
-    return record3(SESSION_STORE_VERDICT.ORPHANED_CLAIMS, VERDICT_BUCKET.DEGRADED, reading);
-  }
-  return record3(SESSION_STORE_VERDICT.CONSISTENT, VERDICT_BUCKET.HEALTHY, reading);
-}
-function sessionStoreRunner(probe) {
-  return async () => classifySessionStore(await probe.probe());
-}
-
 // src/domains/diagnose/checks/spx-reachability.ts
 var SPX_REACHABILITY_VERDICT = {
   REACHABLE: "reachable",
@@ -4617,7 +4688,7 @@ function parseSemver(value) {
     major: Number(match[1]),
     minor: Number(match[2]),
     patch: Number(match[3]),
-    prerelease: match[4] === void 0 ? null : match[4].slice(1)
+    prerelease: match.at(4) === void 0 ? null : match.at(4)?.slice(1) ?? null
   };
 }
 function isNumericIdentifier(identifier) {
@@ -4795,15 +4866,16 @@ var DEFAULT_REGISTRY = {
   [CHECK_NAME.SESSION_STORE]: sessionStoreRunner(defaultSessionStoreProbe),
   [CHECK_NAME.MARKETPLACE_INSTALL]: marketplaceInstallRunner(defaultMarketplaceInstallProbe)
 };
-function handleError(error) {
-  console.error("Error:", sanitizeCliArgument(error));
-  process.exit(1);
+function handleError(error, io) {
+  io.writeStderr(`Error: ${sanitizeCliArgument(error)}
+`);
+  return io.exit(1);
 }
 var diagnoseDomain = {
   name: DIAGNOSE_CLI.COMMAND,
   description: DIAGNOSE_DOMAIN_DESCRIPTION,
-  register: (program2) => {
-    program2.command(DIAGNOSE_CLI.COMMAND).description(DIAGNOSE_DOMAIN_DESCRIPTION).option(
+  register: (program, invocation) => {
+    program.command(DIAGNOSE_CLI.COMMAND).description(DIAGNOSE_DOMAIN_DESCRIPTION).option(
       `${DIAGNOSE_CLI.MANIFEST_FLAG} <path>`,
       "Path to a declarative diagnose manifest that fully instruments the diagnosis"
     ).addOption(
@@ -4811,7 +4883,7 @@ var diagnoseDomain = {
     ).addOption(new Option(`${DIAGNOSE_CLI.COLOR_FLAG}`, "Force colored output")).addOption(new Option(`${DIAGNOSE_CLI.NO_COLOR_FLAG}`, "Disable colored output")).action(async (options) => {
       const result = await diagnoseCommand({
         manifestPath: options.manifest,
-        productDir: process.cwd(),
+        productDir: invocation.resolveProductContext().productDir,
         format: options.format,
         color: resolveColorChoice({
           flag: options.color,
@@ -4821,9 +4893,12 @@ var diagnoseDomain = {
         registry: DEFAULT_REGISTRY,
         fs: { readFile: (path7) => readFile3(path7, "utf8") }
       });
-      if (!result.ok) handleError(result.error);
-      console.log(result.value.output);
-      process.exit(result.value.exitCode);
+      if (!result.ok) {
+        handleError(result.error, invocation.io);
+      }
+      invocation.io.writeStdout(`${result.value.output}
+`);
+      invocation.io.setExitCode(result.value.exitCode);
     });
   }
 };
@@ -4877,7 +4952,7 @@ function isValidPid(pid) {
 }
 
 // src/domains/worktree/resolve.ts
-import { dirname as dirname3, resolve as resolve3 } from "path";
+import { dirname as dirname4, resolve as resolve4 } from "path";
 var WORKTREE_RESOLVE_ERROR = {
   NOT_A_WORKTREE: "path resolves to no worktree"
 };
@@ -4893,8 +4968,8 @@ async function resolveCurrentWorktreeName(options) {
 }
 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 targetPath = options.worktree === void 0 ? base : resolve4(base, options.worktree);
+  const targetGitPath = await options.pathInfo.isExistingNonDirectory(targetPath) ? dirname4(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}` };
@@ -5060,17 +5135,17 @@ function createProcessHookIo(streams) {
   return {
     readStdin: async () => {
       if (streams.stdin.isTTY) return { ok: true, value: void 0 };
-      return new Promise((resolve8) => {
+      return new Promise((resolve10) => {
         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, () => {
-          resolve8({ ok: true, value: data.length === 0 ? void 0 : data });
+          resolve10({ ok: true, value: data.length === 0 ? void 0 : data });
         });
         streams.stdin.on(HOOK_PROCESS_IO_EVENT.ERROR, (error) => {
-          resolve8({ ok: false, error: formatStdinReadError(error) });
+          resolve10({ ok: false, error: formatStdinReadError(error) });
         });
       });
     },
@@ -5089,7 +5164,8 @@ function describeStdinReadError(error) {
   if (error instanceof Error) return error.message;
   if (typeof error === "string") return error;
   try {
-    return JSON.stringify(error) ?? `${typeof error}`;
+    const serialized = JSON.stringify(error);
+    return typeof serialized === "string" ? serialized : `${typeof error}`;
   } catch {
     return `${typeof error}`;
   }
@@ -5116,31 +5192,41 @@ var HOOK_CLI = {
   WORKTREES_DIR_FLAG: "--worktrees-dir"
 };
 var HOOK_DOMAIN_DESCRIPTION = "Run host lifecycle hook events";
-function registerHookCommands(hookCmd) {
+function writeError2(invocation, output) {
+  invocation.io.writeStderr(`${output}
+`);
+}
+function writeInvocationWarning(invocation, warning) {
+  if (warning !== void 0) {
+    writeError2(invocation, warning);
+  }
+}
+function registerHookCommands(hookCmd, invocation) {
+  const effectiveInvocationDir = () => invocation.resolveEffectiveInvocationDir();
   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(),
+      cwd: effectiveInvocationDir(),
       env: process.env,
       envFile: options.hookEnvFile,
       event,
       fs: defaultOccupancyFileSystem,
       gitDeps: defaultGitDependencies,
       io: processHookIo,
-      onWarning: writeWarning,
+      onWarning: (warning) => writeInvocationWarning(invocation, warning),
       processTable: defaultProcessTable,
       selfPid: process.pid,
       worktreesDir: options.worktreesDir
     });
-    if (!result.ok) process.exit(1);
+    if (!result.ok) invocation.io.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);
+  register: (program, invocation) => {
+    const hookCmd = program.command(HOOK_CLI.COMMAND).description(HOOK_DOMAIN_DESCRIPTION);
+    registerHookCommands(hookCmd, invocation);
   }
 };
 
@@ -5175,6 +5261,14 @@ function resolveJournalBackend(env) {
   return { ok: true, value: JOURNAL_BACKEND.LOCAL };
 }
 
+// src/lib/verification-env.ts
+var SPX_VERIFY_ENV = {
+  BRANCH: "SPX_VERIFY_BRANCH"
+};
+var SPX_VERIFY_HEAD_SHA = {
+  MISSING: "unknown"
+};
+
 // src/lib/agent-run-journal/index.ts
 var CLOUDEVENTS_SPECVERSION = "1.0";
 var JOURNAL_SEQ_BASE = 1;
@@ -5462,7 +5556,7 @@ function journalRunFilePath(scope2) {
 }
 
 // src/lib/appendable-journal-store/index.ts
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 var SEAL_MARKER_SUFFIX = ".sealed";
 var LINE_SEPARATOR3 = "\n";
 function appendableJournalSealMarkerPath(runFilePath) {
@@ -5502,7 +5596,7 @@ function createAppendableJournalStore(options) {
     },
     readAll,
     async seal() {
-      await fs8.mkdir(dirname4(sealMarkerPath), { recursive: true });
+      await fs8.mkdir(dirname5(sealMarkerPath), { recursive: true });
       await fs8.writeFile(sealMarkerPath, "");
     },
     async isSealed() {
@@ -5643,7 +5737,7 @@ var JOURNAL_CLI_EXIT_CODE = {
 };
 var JOURNAL_CLI_ENV = {
   BACKEND: "SPX_VERIFY_BACKEND",
-  BRANCH: "SPX_VERIFY_BRANCH",
+  BRANCH: SPX_VERIFY_ENV.BRANCH,
   CONTINUOUS_INTEGRATION: "CI",
   GITHUB_EVENT_NAME: "GITHUB_EVENT_NAME",
   GITHUB_REF: "GITHUB_REF",
@@ -5656,7 +5750,6 @@ var JOURNAL_CLI_ERROR = {
   INVALID_EVENT_INPUT: "journal append event input is missing a required CloudEvents field",
   INVALID_CURSOR: "journal read cursor must be a whole non-negative integer"
 };
-var MISSING_HEAD_SHA_FALLBACK = "unknown";
 var CURSOR_PATTERN = /^\d+$/;
 var JOURNAL_EVENT_INPUT_STRING_FIELDS = ["id", "source", "type", "time"];
 var JOURNAL_COMMENT_MARKER_PREFIX = "spx-journal-run:";
@@ -5684,7 +5777,7 @@ function readJournalCliEnvironment(processEnv) {
   };
 }
 async function resolveJournalRunContext(scope2, deps) {
-  const cwd = deps.cwd ?? process.cwd();
+  const cwd = deps.cwd ?? CONFIG_PROCESS_CWD.read();
   const git = deps.git ?? defaultGitDependencies;
   const cliEnvironment = readJournalCliEnvironment(deps.processEnv ?? process.env);
   const environment = deps.env ?? cliEnvironment.backend;
@@ -5693,7 +5786,7 @@ async function resolveJournalRunContext(scope2, deps) {
   const product = await detectGitCommonDirProductRoot(cwd, git);
   const probedBranch = product.isGitRepo ? await getCurrentBranch(cwd, git) ?? void 0 : void 0;
   const branchName = deps.branch ?? cliEnvironment.branch ?? probedBranch;
-  const headSha = (product.isGitRepo ? await getHeadSha(cwd, git) : null) ?? MISSING_HEAD_SHA_FALLBACK;
+  const headSha = (product.isGitRepo ? await getHeadSha(cwd, git) : null) ?? SPX_VERIFY_HEAD_SHA.MISSING;
   const branchIdentity = resolveBranchIdentity({ ...branchName === void 0 ? {} : { branchName }, headSha });
   return {
     ok: true,
@@ -5827,284 +5920,269 @@ async function journalRenderCommand(scope2, deps = {}) {
   return okResult(JSON.stringify(rendered.value));
 }
 
-// src/lib/process-lifecycle/exit-codes.ts
-var SIGINT_EXIT_CODE = 130;
-var SIGTERM_EXIT_CODE = 143;
-var EPIPE_EXIT_CODE = 0;
-var UNCAUGHT_EXIT_CODE = 1;
-
-// src/lib/process-lifecycle/foreground-handoff.ts
-var FOREGROUND_SIGNALS = ["SIGINT", "SIGTERM"];
-function createSignalSuspender(target) {
+// src/interfaces/cli/journal.ts
+var JOURNAL_CLI = {
+  commandName: "journal",
+  description: "Record and stream an agentic verification run journal",
+  openCommandName: "open",
+  appendCommandName: "append",
+  readCommandName: "read",
+  sealCommandName: "seal",
+  renderCommandName: "render",
+  typeOption: "--type <type>",
+  runOption: "--run <token>",
+  fromOption: "--from <cursor>"
+};
+var STREAM_LINE_SEPARATOR = "\n";
+var MALFORMED_EVENT_INPUT_ERROR = "journal append event input is not valid JSON";
+function scope(options) {
+  return { type: options.type };
+}
+function runScope(options) {
+  return { ...scope(options), runToken: options.run };
+}
+var journalDomain = {
+  name: JOURNAL_CLI.commandName,
+  description: JOURNAL_CLI.description,
+  register: (program, invocation) => {
+    const journalDeps = () => ({ cwd: invocation.resolveEffectiveInvocationDir() });
+    const journalCmd = program.command(JOURNAL_CLI.commandName).description(JOURNAL_CLI.description);
+    journalCmd.command(JOURNAL_CLI.openCommandName).description("Open a new run journal and report its run token").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").action(async (options) => {
+      report(await journalOpenCommand(scope(options), journalDeps()), invocation.io);
+    });
+    journalCmd.command(JOURNAL_CLI.appendCommandName).description("Append a JSON event read from standard input and stream it").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").requiredOption(JOURNAL_CLI.runOption, "Run token reported by open").action(async (options) => {
+      const input = await readStdinEventInput();
+      if (!input.ok) {
+        report({ exitCode: JOURNAL_CLI_EXIT_CODE.ERROR, output: input.error }, invocation.io);
+        return;
+      }
+      const result = await journalAppendCommand(
+        runScope(options),
+        input.value,
+        streamBinding(invocation.io),
+        journalDeps()
+      );
+      if (result.exitCode === JOURNAL_CLI_EXIT_CODE.OK) invocation.io.setExitCode(JOURNAL_CLI_EXIT_CODE.OK);
+      else report(result, invocation.io);
+    });
+    journalCmd.command(JOURNAL_CLI.readCommandName).description("Read the run's events at or after a cursor").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").requiredOption(JOURNAL_CLI.runOption, "Run token reported by open").requiredOption(JOURNAL_CLI.fromOption, "Sequence cursor; events at or after it are returned").action(async (options) => {
+      report(await journalReadCommand(runScope(options), options.from, journalDeps()), invocation.io);
+    });
+    journalCmd.command(JOURNAL_CLI.sealCommandName).description("Seal the run journal so further appends are rejected").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").requiredOption(JOURNAL_CLI.runOption, "Run token reported by open").action(async (options) => {
+      report(await journalSealCommand(runScope(options), journalDeps()), invocation.io);
+    });
+    journalCmd.command(JOURNAL_CLI.renderCommandName).description("Render the run's event-prefix projection").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").requiredOption(JOURNAL_CLI.runOption, "Run token reported by open").action(async (options) => {
+      report(await journalRenderCommand(runScope(options), journalDeps()), invocation.io);
+    });
+  }
+};
+function stdoutStreamSink(io) {
   return {
-    suspend() {
-      const ignore = () => {
-      };
-      const restorers = FOREGROUND_SIGNALS.map((signal) => {
-        const originals = target.listeners(signal);
-        for (const listener of originals) target.removeListener(signal, listener);
-        target.on(signal, ignore);
-        return () => {
-          target.removeListener(signal, ignore);
-          for (const listener of originals) target.on(signal, listener);
-        };
-      });
-      return () => {
-        for (const restore of restorers) restore();
-      };
+    async emit(event) {
+      io.writeStdout(`${JSON.stringify(event)}${STREAM_LINE_SEPARATOR}`);
     }
   };
 }
+function streamBinding(io) {
+  const repository = process.env[JOURNAL_CLI_ENV.GITHUB_REPOSITORY] ?? "";
+  return {
+    localSink: stdoutStreamSink(io),
+    githubClient: createGithubPullRequestCommentClient({ repository, run: runGhApi }),
+    githubRepository: repository
+  };
+}
+async function readStdinEventInput() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  try {
+    return { ok: true, value: JSON.parse(Buffer.concat(chunks).toString("utf8")) };
+  } catch {
+    return { ok: false, error: MALFORMED_EVENT_INPUT_ERROR };
+  }
+}
+function report(result, io) {
+  const output = `${result.output}${STREAM_LINE_SEPARATOR}`;
+  if (result.exitCode === JOURNAL_CLI_EXIT_CODE.OK) io.writeStdout(output);
+  else io.writeStderr(output);
+  io.setExitCode(result.exitCode);
+}
 
-// src/lib/process-lifecycle/handlers.ts
-var SIGINT_NAME = "SIGINT";
-var SIGTERM_NAME = "SIGTERM";
-function createHandlers(deps) {
-  let cleanupOnce = false;
-  function killEachChild(signal) {
-    deps.registry.forEach((child) => {
-      if (!child.killed) child.kill(signal);
-    });
-  }
-  function exitOnce(code, killSignal) {
-    if (cleanupOnce) {
-      deps.exitController.exit(code);
-      return;
-    }
-    cleanupOnce = true;
-    if (killSignal !== void 0) killEachChild(killSignal);
-    deps.exitController.exit(code);
-  }
-  return {
-    onSigint() {
-      exitOnce(SIGINT_EXIT_CODE, SIGINT_NAME);
+// src/interfaces/cli/session/definition.ts
+var sessionCliDefinition = {
+  domain: { commandName: "session", description: "Manage session workflow" },
+  subcommands: {
+    list: {
+      commandName: "list",
+      description: "List active sessions (doing + todo by default)"
     },
-    onSigterm() {
-      exitOnce(SIGTERM_EXIT_CODE, SIGTERM_NAME);
+    pick: {
+      commandName: "pick",
+      description: "Interactively pick a session and launch claude or codex to resume it"
     },
-    onEpipe() {
-      exitOnce(EPIPE_EXIT_CODE, SIGTERM_NAME);
+    todo: {
+      commandName: "todo",
+      description: "List todo sessions"
     },
-    onUncaught(_error) {
-      exitOnce(UNCAUGHT_EXIT_CODE, SIGTERM_NAME);
-    }
-  };
-}
-
-// src/lib/process-lifecycle/install.ts
-import { spawn } from "child_process";
-
-// src/lib/process-lifecycle/registry.ts
-function createRegistry() {
-  const tracked = /* @__PURE__ */ new Set();
-  return {
-    add(child) {
-      tracked.add(child);
+    show: {
+      commandName: "show",
+      operand: "<id...>",
+      description: "Show session content"
     },
-    remove(child) {
-      tracked.delete(child);
+    pickup: {
+      commandName: "pickup",
+      operand: "[ids...]",
+      description: "Claim one or more sessions (move from todo to doing)"
     },
-    forEach(fn) {
-      for (const child of tracked) fn(child);
+    release: {
+      commandName: "release",
+      operand: "[ids...]",
+      description: "Release one or more sessions (move from doing to todo)"
     },
-    get size() {
-      return tracked.size;
-    }
-  };
-}
-
-// src/lib/process-lifecycle/runner.ts
-function createLifecycleRunner(deps) {
-  return {
-    spawn(command, args, options) {
-      const child = deps.spawn(command, args, options);
-      deps.registry.add(child);
-      child.on("exit", () => deps.registry.remove(child));
-      return child;
+    handoff: {
+      commandName: "handoff",
+      description: "Create a handoff session (reads JSON header + body from stdin)"
+    },
+    delete: {
+      commandName: "delete",
+      operand: "<id...>",
+      description: "Delete one or more sessions"
+    },
+    prune: {
+      commandName: "prune",
+      description: "Remove old todo sessions, keeping the most recent N"
+    },
+    archive: {
+      commandName: "archive",
+      operand: "<id...>",
+      description: "Move one or more sessions to the archive directory"
     }
-  };
-}
-
-// src/lib/process-lifecycle/install.ts
-var moduleRegistry = createRegistry();
-var moduleExitController = {
-  exit(code) {
-    process.exit(code);
-  }
-};
-var installed = false;
-var lifecycleProcessRunner = createLifecycleRunner({
-  registry: moduleRegistry,
-  spawn
-});
-var foregroundProcessRunner = { spawn };
-var processSignalTarget = {
-  listeners: (signal) => process.listeners(signal),
-  on: (signal, listener) => {
-    process.on(signal, listener);
   },
-  removeListener: (signal, listener) => {
-    process.removeListener(signal, listener);
-  }
-};
-var lifecycleSignalSuspender = createSignalSuspender(processSignalTarget);
-var EPIPE_CODE = "EPIPE";
-var UNCAUGHT_PREFIX = "Uncaught: ";
-var NEWLINE = "\n";
-function formatUncaught(error) {
-  if (error instanceof Error && error.stack !== void 0) {
-    return UNCAUGHT_PREFIX + error.stack + NEWLINE;
-  }
-  return UNCAUGHT_PREFIX + String(error) + NEWLINE;
-}
-function logUncaughtToStderr(error) {
-  try {
-    process.stderr.write(formatUncaught(error));
-  } catch {
-  }
-}
-function installLifecycle() {
-  if (installed) return;
-  installed = true;
-  const handlers = createHandlers({
-    registry: moduleRegistry,
-    exitController: moduleExitController
-  });
-  process.on("uncaughtException", (error) => {
-    logUncaughtToStderr(error);
-    handlers.onUncaught(error);
-  });
-  process.on("unhandledRejection", (reason) => {
-    logUncaughtToStderr(reason);
-    handlers.onUncaught(reason);
-  });
-  process.on("SIGTERM", () => handlers.onSigterm());
-  process.on("SIGINT", () => handlers.onSigint());
-  process.stdout.on("error", (error) => {
-    if (error.code === EPIPE_CODE) {
-      handlers.onEpipe();
-      return;
-    }
-    handlers.onUncaught(error);
-  });
-  process.stderr.on("error", (error) => {
-    if (error.code === EPIPE_CODE) {
-      handlers.onEpipe();
-      return;
-    }
-    handlers.onUncaught(error);
-  });
-}
-
-// src/lib/process-lifecycle/managed-subprocess.ts
-var MANAGED_SUBPROCESS_STDIO = "pipe";
-function spawnManagedSubprocess(runner, command, args, options) {
-  return runner.spawn(command, args, {
-    ...options,
-    stdio: MANAGED_SUBPROCESS_STDIO
-  });
-}
-
-// src/interfaces/cli/journal.ts
-var JOURNAL_CLI = {
-  commandName: "journal",
-  description: "Record and stream an agentic verification run journal",
-  openCommandName: "open",
-  appendCommandName: "append",
-  readCommandName: "read",
-  sealCommandName: "seal",
-  renderCommandName: "render",
-  typeOption: "--type <type>",
-  runOption: "--run <token>",
-  fromOption: "--from <cursor>"
-};
-var STREAM_LINE_SEPARATOR = "\n";
-var MALFORMED_EVENT_INPUT_ERROR = "journal append event input is not valid JSON";
-function scope(options) {
-  return { type: options.type };
-}
-function runScope(options) {
-  return { ...scope(options), runToken: options.run };
-}
-var journalDomain = {
-  name: JOURNAL_CLI.commandName,
-  description: JOURNAL_CLI.description,
-  register: (program2) => {
-    const journalCmd = program2.command(JOURNAL_CLI.commandName).description(JOURNAL_CLI.description);
-    journalCmd.command(JOURNAL_CLI.openCommandName).description("Open a new run journal and report its run token").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").action(async (options) => {
-      await report(await journalOpenCommand(scope(options)));
-    });
-    journalCmd.command(JOURNAL_CLI.appendCommandName).description("Append a JSON event read from standard input and stream it").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").requiredOption(JOURNAL_CLI.runOption, "Run token reported by open").action(async (options) => {
-      const input = await readStdinEventInput();
-      if (!input.ok) {
-        await report({ exitCode: JOURNAL_CLI_EXIT_CODE.ERROR, output: input.error });
-        return;
-      }
-      const result = await journalAppendCommand(runScope(options), input.value, streamBinding());
-      if (result.exitCode === JOURNAL_CLI_EXIT_CODE.OK) process.exit(JOURNAL_CLI_EXIT_CODE.OK);
-      else await report(result);
-    });
-    journalCmd.command(JOURNAL_CLI.readCommandName).description("Read the run's events at or after a cursor").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").requiredOption(JOURNAL_CLI.runOption, "Run token reported by open").requiredOption(JOURNAL_CLI.fromOption, "Sequence cursor; events at or after it are returned").action(async (options) => {
-      await report(await journalReadCommand(runScope(options), options.from));
-    });
-    journalCmd.command(JOURNAL_CLI.sealCommandName).description("Seal the run journal so further appends are rejected").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").requiredOption(JOURNAL_CLI.runOption, "Run token reported by open").action(async (options) => {
-      await report(await journalSealCommand(runScope(options)));
-    });
-    journalCmd.command(JOURNAL_CLI.renderCommandName).description("Render the run's event-prefix projection").requiredOption(JOURNAL_CLI.typeOption, "Opaque verification-type scope segment").requiredOption(JOURNAL_CLI.runOption, "Run token reported by open").action(async (options) => {
-      await report(await journalRenderCommand(runScope(options)));
-    });
-  }
-};
-function stdoutStreamSink() {
-  return {
-    async emit(event) {
-      await writeOutput(process.stdout, `${JSON.stringify(event)}${STREAM_LINE_SEPARATOR}`);
-    }
-  };
-}
-function streamBinding() {
-  const repository = process.env[JOURNAL_CLI_ENV.GITHUB_REPOSITORY] ?? "";
-  return {
-    localSink: stdoutStreamSink(),
-    githubClient: createGithubPullRequestCommentClient({ repository, run: runGhApi }),
-    githubRepository: repository
-  };
-}
-async function readStdinEventInput() {
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-  }
-  try {
-    return { ok: true, value: JSON.parse(Buffer.concat(chunks).toString("utf8")) };
-  } catch {
-    return { ok: false, error: MALFORMED_EVENT_INPUT_ERROR };
+  options: {
+    status: {
+      flag: "--status",
+      placeholder: "<status>",
+      description: "Filter by status (todo|doing|archive); defaults to doing + todo"
+    },
+    json: {
+      flag: "--json",
+      description: "Output as JSON"
+    },
+    fields: {
+      flag: "--fields",
+      placeholder: "<fields>",
+      description: "Comma-separated fields to emit as JSON (implies --json)"
+    },
+    color: {
+      flag: "--color",
+      description: "Force colored text output"
+    },
+    noColor: {
+      flag: "--no-color",
+      description: "Disable colored text output"
+    },
+    sessionsDir: {
+      flag: "--sessions-dir",
+      placeholder: "<path>",
+      description: "Custom sessions directory"
+    },
+    auto: {
+      flag: "--auto",
+      description: "Auto-select highest priority session"
+    },
+    noInject: {
+      flag: "--no-inject",
+      description: "Skip printing files listed in session specs/files metadata"
+    },
+    keep: {
+      flag: "--keep",
+      placeholder: "<count>",
+      description: "Number of sessions to keep (default: 5)",
+      defaultValue: "5"
+    },
+    dryRun: {
+      flag: "--dry-run",
+      description: "Show what would be deleted without deleting"
+    }
+  }
+};
+var sessionSubcommandOptions = [
+  {
+    subcommand: sessionCliDefinition.subcommands.list,
+    options: [
+      sessionCliDefinition.options.status,
+      sessionCliDefinition.options.json,
+      sessionCliDefinition.options.fields,
+      sessionCliDefinition.options.color,
+      sessionCliDefinition.options.noColor,
+      sessionCliDefinition.options.sessionsDir
+    ]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.pick,
+    options: [sessionCliDefinition.options.sessionsDir]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.todo,
+    options: [
+      sessionCliDefinition.options.json,
+      sessionCliDefinition.options.fields,
+      sessionCliDefinition.options.color,
+      sessionCliDefinition.options.noColor,
+      sessionCliDefinition.options.sessionsDir
+    ]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.show,
+    options: [sessionCliDefinition.options.json, sessionCliDefinition.options.sessionsDir]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.pickup,
+    options: [
+      sessionCliDefinition.options.auto,
+      sessionCliDefinition.options.noInject,
+      sessionCliDefinition.options.sessionsDir
+    ]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.release,
+    options: [sessionCliDefinition.options.sessionsDir]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.handoff,
+    options: [sessionCliDefinition.options.sessionsDir]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.delete,
+    options: [sessionCliDefinition.options.sessionsDir]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.prune,
+    options: [
+      sessionCliDefinition.options.keep,
+      sessionCliDefinition.options.dryRun,
+      sessionCliDefinition.options.sessionsDir
+    ]
+  },
+  {
+    subcommand: sessionCliDefinition.subcommands.archive,
+    options: [sessionCliDefinition.options.sessionsDir]
   }
+];
+function sessionOptionsForSubcommand(subcommand) {
+  return sessionSubcommandOptions.find((entry) => entry.subcommand === subcommand)?.options ?? [];
 }
-async function report(result) {
-  const stream = result.exitCode === JOURNAL_CLI_EXIT_CODE.OK ? process.stdout : process.stderr;
-  const completed = await writeOutput(stream, `${result.output}${STREAM_LINE_SEPARATOR}`);
-  if (completed) process.exit(result.exitCode);
+function sessionCommandToken(subcommand) {
+  return subcommand.operand === void 0 ? subcommand.commandName : `${subcommand.commandName} ${subcommand.operand}`;
 }
-function writeOutput(stream, output) {
-  return new Promise((resolve8, reject) => {
-    stream.write(output, (error) => {
-      if (error === void 0 || error === null) {
-        resolve8(true);
-        return;
-      }
-      if (error.code === EPIPE_CODE) {
-        resolve8(false);
-        return;
-      }
-      reject(error);
-    });
-  });
+function sessionOptionToken(option) {
+  return option.placeholder === void 0 ? option.flag : `${option.flag} ${option.placeholder}`;
 }
 
 // src/commands/session/archive.ts
 import { mkdir, rename, stat } from "fs/promises";
-import { dirname as dirname5, join as join9 } from "path";
+import { dirname as dirname6, join as join9 } from "path";
 
 // src/domains/session/archive.ts
 var SESSION_FILE_EXTENSION = ".md";
@@ -6370,8 +6448,8 @@ async function resolveSessionConfig(options = {}) {
     warning
   };
 }
-async function resolveSessionConfigSurfacingWarning(sessionsDir, onWarning) {
-  const { config, warning } = await resolveSessionConfig({ sessionsDir });
+async function resolveSessionConfigSurfacingWarning(sessionsDir, onWarning, cwd) {
+  const { config, warning } = await resolveSessionConfig({ sessionsDir, cwd });
   if (warning !== void 0) {
     onWarning?.(warning);
   }
@@ -6425,13 +6503,13 @@ async function resolveArchivePaths(sessionId, config) {
 }
 async function archiveSingle(sessionId, config) {
   const { source, target } = await resolveArchivePaths(sessionId, config);
-  await mkdir(dirname5(target), { recursive: true });
+  await mkdir(dirname6(target), { recursive: true });
   await rename(source, target);
   return `${SESSION_ARCHIVE_OUTPUT.ARCHIVED}: ${sessionId}
 ${SESSION_ARCHIVE_OUTPUT.ARCHIVE_LOCATION}: ${target}`;
 }
 async function archiveCommand(options) {
-  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning, options.cwd);
   return processBatch(options.sessionIds, (id) => archiveSingle(id, config));
 }
 
@@ -6454,6 +6532,123 @@ import { join as join10 } from "path";
 import { Chalk as Chalk2 } from "chalk";
 import { parse as parseYaml2 } from "yaml";
 
+// src/domains/session/display-width.ts
+var CONTROL_CODE_MAX = 31;
+var DELETE_CODE = 127;
+var C1_CONTROL_MIN = 128;
+var C1_CONTROL_MAX = 159;
+var ZERO_WIDTH_JOINER = 8205;
+var ZERO_WIDTH_RANGES = [
+  { start: 768, end: 879 },
+  { start: 6832, end: 6911 },
+  { start: 7616, end: 7679 },
+  { start: 8400, end: 8447 },
+  { start: 65024, end: 65039 },
+  { start: 65056, end: 65071 },
+  { start: 917760, end: 917999 }
+];
+var WIDE_RANGES = [
+  { start: 4352, end: 4447 },
+  { start: 8986, end: 8987 },
+  { start: 9001, end: 9002 },
+  { start: 9193, end: 9196 },
+  { start: 9200, end: 9200 },
+  { start: 9203, end: 9203 },
+  { start: 9725, end: 9726 },
+  { start: 9748, end: 9749 },
+  { start: 9800, end: 9811 },
+  { start: 9855, end: 9855 },
+  { start: 9875, end: 9875 },
+  { start: 9889, end: 9889 },
+  { start: 9898, end: 9899 },
+  { start: 9917, end: 9918 },
+  { start: 9924, end: 9925 },
+  { start: 9934, end: 9934 },
+  { start: 9940, end: 9940 },
+  { start: 9962, end: 9962 },
+  { start: 9970, end: 9971 },
+  { start: 9973, end: 9973 },
+  { start: 9978, end: 9978 },
+  { start: 9981, end: 9981 },
+  { start: 9989, end: 9989 },
+  { start: 9994, end: 9995 },
+  { start: 10024, end: 10024 },
+  { start: 10060, end: 10060 },
+  { start: 10062, end: 10062 },
+  { start: 10067, end: 10069 },
+  { start: 10071, end: 10071 },
+  { start: 10133, end: 10135 },
+  { start: 10160, end: 10160 },
+  { start: 10175, end: 10175 },
+  { start: 11035, end: 11036 },
+  { start: 11088, end: 11088 },
+  { start: 11093, end: 11093 },
+  { start: 11904, end: 12350 },
+  { start: 12352, end: 42191 },
+  { start: 44032, end: 55203 },
+  { start: 63744, end: 64255 },
+  { start: 65040, end: 65049 },
+  { start: 65072, end: 65135 },
+  { start: 65280, end: 65376 },
+  { start: 65504, end: 65510 },
+  { start: 126980, end: 126980 },
+  { start: 127183, end: 127183 },
+  { start: 127374, end: 127374 },
+  { start: 127377, end: 127386 },
+  { start: 127488, end: 127490 },
+  { start: 127504, end: 127547 },
+  { start: 127552, end: 127560 },
+  { start: 127568, end: 127569 },
+  { start: 127744, end: 128591 },
+  { start: 128640, end: 128767 },
+  { start: 129280, end: 129535 },
+  { start: 131072, end: 262141 }
+];
+var ZERO_WIDTH_COLUMNS = 0;
+var NARROW_COLUMNS = 1;
+var WIDE_COLUMNS = 2;
+function isInRange(codePoint, range) {
+  return codePoint >= range.start && codePoint <= range.end;
+}
+function isControlCode(codePoint) {
+  return codePoint <= CONTROL_CODE_MAX || codePoint === DELETE_CODE || codePoint >= C1_CONTROL_MIN && codePoint <= C1_CONTROL_MAX;
+}
+function codePointWidth(codePoint) {
+  if (isControlCode(codePoint) || codePoint === ZERO_WIDTH_JOINER) {
+    return ZERO_WIDTH_COLUMNS;
+  }
+  if (ZERO_WIDTH_RANGES.some((range) => isInRange(codePoint, range))) {
+    return ZERO_WIDTH_COLUMNS;
+  }
+  if (WIDE_RANGES.some((range) => isInRange(codePoint, range))) {
+    return WIDE_COLUMNS;
+  }
+  return NARROW_COLUMNS;
+}
+function visibleWidth(text) {
+  let width = ZERO_WIDTH_COLUMNS;
+  for (const symbol of Array.from(text)) {
+    width += codePointWidth(symbol.codePointAt(0) ?? ZERO_WIDTH_COLUMNS);
+  }
+  return width;
+}
+function takeVisibleColumns(text, maxColumns) {
+  if (maxColumns <= ZERO_WIDTH_COLUMNS) {
+    return "";
+  }
+  let width = ZERO_WIDTH_COLUMNS;
+  let result = "";
+  for (const symbol of Array.from(text)) {
+    const nextWidth = codePointWidth(symbol.codePointAt(0) ?? ZERO_WIDTH_COLUMNS);
+    if (width + nextWidth > maxColumns) {
+      break;
+    }
+    result += symbol;
+    width += nextWidth;
+  }
+  return result;
+}
+
 // src/domains/session/timestamp.ts
 var SESSION_ID_PATTERN = /^(\d{4})-(\d{2})-(\d{2})_(\d{2})-(\d{2})-(\d{2})$/;
 var SESSION_ID_SEPARATOR = "_";
@@ -6474,12 +6669,12 @@ function parseSessionId(id) {
     return null;
   }
   const [, yearStr, monthStr, dayStr, hoursStr, minutesStr, secondsStr] = match;
-  const year = parseInt(yearStr, 10);
-  const month = parseInt(monthStr, 10) - 1;
-  const day = parseInt(dayStr, 10);
-  const hours = parseInt(hoursStr, 10);
-  const minutes = parseInt(minutesStr, 10);
-  const seconds = parseInt(secondsStr, 10);
+  const year = Number.parseInt(yearStr, 10);
+  const month = Number.parseInt(monthStr, 10) - 1;
+  const day = Number.parseInt(dayStr, 10);
+  const hours = Number.parseInt(hoursStr, 10);
+  const minutes = Number.parseInt(minutesStr, 10);
+  const seconds = Number.parseInt(secondsStr, 10);
   if (month < 0 || month > 11) return null;
   if (day < 1 || day > 31) return null;
   if (hours < 0 || hours > 23) return null;
@@ -6500,6 +6695,18 @@ var SESSION_PRIORITY = {
 };
 var SESSION_STATUSES = ["todo", "doing", "archive"];
 var DEFAULT_LIST_STATUSES = ["doing", "todo"];
+var SESSION_FILE_ENCODING = "utf-8";
+var SESSION_FILE_ERROR_CODE = {
+  NOT_FOUND: "ENOENT"
+};
+var SESSION_OUTPUT_MARKER = {
+  HANDOFF_ID: "HANDOFF_ID",
+  PICKUP_ID: "PICKUP_ID",
+  SESSION_FILE: "SESSION_FILE"
+};
+function formatSessionOutputMarker(marker, value) {
+  return `<${marker}>${value}</${marker}>`;
+}
 var CLAIMABLE_STATUS = SESSION_STATUSES[0];
 var PRIORITY_ORDER = {
   [SESSION_PRIORITY.HIGH]: 0,
@@ -6537,7 +6744,7 @@ function defaultSessionMetadata() {
   };
 }
 function isValidPriority(value) {
-  return typeof value === "string" && SESSION_PRIORITY_VALUES.some((priority) => priority === value);
+  return typeof value === "string" && SESSION_PRIORITY_VALUES.includes(value);
 }
 function parseSessionMetadata(content) {
   const match = FRONT_MATTER_PATTERN.exec(content);
@@ -6545,10 +6752,11 @@ function parseSessionMetadata(content) {
     return defaultSessionMetadata();
   }
   try {
-    const parsed = parseYaml2(match[1]);
-    if (!parsed || typeof parsed !== "object") {
+    const parsedDocument = parseYaml2(match[1]);
+    if (!parsedDocument || typeof parsedDocument !== "object") {
       return defaultSessionMetadata();
     }
+    const parsed = parsedDocument;
     const rawPriority = parsed[SESSION_FRONT_MATTER.PRIORITY];
     const priority = isValidPriority(rawPriority) ? rawPriority : DEFAULT_PRIORITY;
     const metadata = {
@@ -6685,13 +6893,13 @@ function formatSessionLine(session, width, chalk) {
   const { id, metadata } = session;
   const badge = metadata.priority === DEFAULT_PRIORITY ? "" : ` [${metadata.priority}]`;
   const summary = metadata.goal.length > 0 && metadata.next_step.length > 0 ? ` ${metadata.goal}${LIST_SUMMARY_SEPARATOR}${metadata.next_step}` : "";
-  let remaining = Math.max(0, width - LIST_INDENT.length);
-  const idShown = id.slice(0, remaining);
-  remaining -= idShown.length;
-  const badgeShown = badge.slice(0, remaining);
-  remaining -= badgeShown.length;
-  const summaryShown = summary.slice(0, remaining);
-  const styledBadge = badgeShown.length > 0 ? PRIORITY_STYLE[metadata.priority](chalk, badgeShown) : "";
+  let remaining = Math.max(0, width - visibleWidth(LIST_INDENT));
+  const idShown = takeVisibleColumns(id, remaining);
+  remaining -= visibleWidth(idShown);
+  const badgeShown = takeVisibleColumns(badge, remaining);
+  remaining -= visibleWidth(badgeShown);
+  const summaryShown = takeVisibleColumns(summary, remaining);
+  const styledBadge = visibleWidth(badgeShown) > 0 ? PRIORITY_STYLE[metadata.priority](chalk, badgeShown) : "";
   return `${LIST_INDENT}${chalk.dim(idShown)}${styledBadge}${chalk.dim(summaryShown)}`;
 }
 function formatSessionListText(sessions, opts) {
@@ -6772,13 +6980,13 @@ async function deleteSingle(sessionId, config) {
   return `${SESSION_DELETE_OUTPUT.DELETED}: ${sessionId}`;
 }
 async function deleteCommand(options) {
-  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning, options.cwd);
   return processBatch(options.sessionIds, (id) => deleteSingle(id, config));
 }
 
 // src/commands/session/handoff.ts
 import { mkdir as mkdir2, writeFile } from "fs/promises";
-import { join as join11, resolve as resolve4 } from "path";
+import { join as join11, resolve as resolve5 } from "path";
 import { stringify as stringifyYaml3 } from "yaml";
 
 // src/domains/session/create.ts
@@ -6849,12 +7057,12 @@ function resolveWorkBranchGitRef(workBranch, existsOnOrigin) {
 // src/domains/session/parse-handoff-input.ts
 var LEGACY_FRONTMATTER_PREFIX = /^---\r?\n/;
 var JSON_OBJECT_OPEN_CHAR = "{";
-var CARRIAGE_RETURN_CHAR_CODE = "\r".charCodeAt(0);
-var NEWLINE_CHAR_CODE = "\n".charCodeAt(0);
-var BACKSLASH_CHAR_CODE = "\\".charCodeAt(0);
-var DOUBLE_QUOTE_CHAR_CODE = '"'.charCodeAt(0);
-var OPEN_BRACE_CHAR_CODE = "{".charCodeAt(0);
-var CLOSE_BRACE_CHAR_CODE = "}".charCodeAt(0);
+var CARRIAGE_RETURN_CHAR_CODE = "\r".codePointAt(0) ?? 0;
+var NEWLINE_CHAR_CODE = "\n".codePointAt(0) ?? 0;
+var BACKSLASH_CHAR_CODE = "\\".codePointAt(0) ?? 0;
+var DOUBLE_QUOTE_CHAR_CODE = '"'.codePointAt(0) ?? 0;
+var OPEN_BRACE_CHAR_CODE = "{".codePointAt(0) ?? 0;
+var CLOSE_BRACE_CHAR_CODE = "}".codePointAt(0) ?? 0;
 var UNBALANCED_HEADER_END = -1;
 var LF_SEPARATOR_LENGTH = 1;
 var CRLF_SEPARATOR_LENGTH = 2;
@@ -6887,10 +7095,10 @@ function parseHandoffInput(stdin) {
   return { header, body: stdin.slice(bodyStart) };
 }
 function consumeOptionalBodySeparator(stdin, bodyStart) {
-  if (stdin.charCodeAt(bodyStart) === CARRIAGE_RETURN_CHAR_CODE && stdin.charCodeAt(bodyStart + LF_SEPARATOR_LENGTH) === NEWLINE_CHAR_CODE) {
+  if (stdin.codePointAt(bodyStart) === CARRIAGE_RETURN_CHAR_CODE && stdin.codePointAt(bodyStart + LF_SEPARATOR_LENGTH) === NEWLINE_CHAR_CODE) {
     return bodyStart + CRLF_SEPARATOR_LENGTH;
   }
-  if (stdin.charCodeAt(bodyStart) === NEWLINE_CHAR_CODE) {
+  if (stdin.codePointAt(bodyStart) === NEWLINE_CHAR_CODE) {
     return bodyStart + LF_SEPARATOR_LENGTH;
   }
   return bodyStart;
@@ -6899,32 +7107,33 @@ function findJsonObjectEnd(stdin) {
   let depth = 0;
   let inString = false;
   for (let i = 0; i < stdin.length; i++) {
-    const code = stdin.charCodeAt(i);
+    const code = stdin.codePointAt(i);
     if (inString) {
-      if (code === BACKSLASH_CHAR_CODE) {
-        i += 1;
-        continue;
-      }
-      if (code === DOUBLE_QUOTE_CHAR_CODE) {
-        inString = false;
-      }
+      const stringState = scanJsonStringCharacter(code);
+      inString = stringState.inString;
+      if (stringState.skipNext) i += 1;
       continue;
     }
     if (code === DOUBLE_QUOTE_CHAR_CODE) {
       inString = true;
       continue;
     }
-    if (code === OPEN_BRACE_CHAR_CODE) {
-      depth += 1;
-      continue;
-    }
-    if (code === CLOSE_BRACE_CHAR_CODE) {
-      depth -= 1;
-      if (depth === 0) return i;
-    }
+    depth = nextJsonObjectDepth(depth, code);
+    if (depth === 0 && code === CLOSE_BRACE_CHAR_CODE) return i;
   }
   return UNBALANCED_HEADER_END;
 }
+function scanJsonStringCharacter(code) {
+  if (code === BACKSLASH_CHAR_CODE) {
+    return { inString: true, skipNext: true };
+  }
+  return { inString: code !== DOUBLE_QUOTE_CHAR_CODE, skipNext: false };
+}
+function nextJsonObjectDepth(depth, code) {
+  if (code === OPEN_BRACE_CHAR_CODE) return depth + 1;
+  if (code === CLOSE_BRACE_CHAR_CODE) return depth - 1;
+  return depth;
+}
 function validateHandoffHeader(parsed) {
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new SessionInvalidJsonHeaderError("header must be a JSON object");
@@ -6989,13 +7198,16 @@ async function resolveSessionGitRef(cwd, deps) {
     gatherGitFacts(cwd, deps)
   ]);
   const isGitRepo = facts !== null;
-  const currentWorktreePath = facts?.worktreeRoot ?? cwd ?? process.cwd();
+  const currentWorktreePath = facts?.worktreeRoot ?? cwd ?? CONFIG_PROCESS_CWD.read();
   const isMain = facts !== null && isMainCheckout(facts);
-  const designatedMainCheckout = facts !== null ? mainCheckoutPath(facts) : null;
+  let designatedMainCheckout = null;
+  if (facts !== null) {
+    designatedMainCheckout = mainCheckoutPath(facts);
+  }
   let isClean = false;
   let defaultBranch = null;
   let defaultTipSha = null;
-  if (isGitRepo && !isMain) {
+  if (isGitRepo && isMain === false) {
     [isClean, defaultBranch] = await Promise.all([
       isWorkingTreeClean(cwd, deps),
       resolveDefaultBranch(cwd, deps)
@@ -7057,11 +7269,11 @@ async function handoffCommand(options) {
   const fullContent = `${SESSION_FRONT_MATTER_OPEN}${yaml}${SESSION_FRONT_MATTER_CLOSE}${body}`;
   const filename = `${sessionId}.md`;
   const sessionPath = join11(config.todoDir, filename);
-  const absolutePath = resolve4(sessionPath);
+  const absolutePath = resolve5(sessionPath);
   await mkdir2(config.todoDir, { recursive: true });
-  await writeFile(sessionPath, fullContent, "utf-8");
-  const output = `Created handoff session <HANDOFF_ID>${sessionId}</HANDOFF_ID>
-<SESSION_FILE>${absolutePath}</SESSION_FILE>`;
+  await writeFile(sessionPath, fullContent, SESSION_FILE_ENCODING);
+  const output = `Created handoff session ${formatSessionOutputMarker(SESSION_OUTPUT_MARKER.HANDOFF_ID, sessionId)}
+${formatSessionOutputMarker(SESSION_OUTPUT_MARKER.SESSION_FILE, absolutePath)}`;
   return { output };
 }
 
@@ -7081,7 +7293,7 @@ async function loadSessionsFromDir(dir, status) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
       const filePath = join12(dir, file);
-      const content = await readFile4(filePath, "utf-8");
+      const content = await readFile4(filePath, SESSION_FILE_ENCODING);
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
@@ -7092,7 +7304,7 @@ async function loadSessionsFromDir(dir, status) {
     }
     return sessions;
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+    if (error instanceof Error && "code" in error && error.code === SESSION_FILE_ERROR_CODE.NOT_FOUND) {
       return [];
     }
     throw error;
@@ -7112,9 +7324,9 @@ function validateStatus(input) {
   );
 }
 async function listCommand(options) {
-  const fieldSelection = options.fields !== void 0 ? parseFieldSelection(options.fields) : void 0;
-  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
-  const statuses = options.status !== void 0 ? [validateStatus(options.status)] : DEFAULT_LIST_STATUSES;
+  const fieldSelection = options.fields === void 0 ? void 0 : parseFieldSelection(options.fields);
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning, options.cwd);
+  const statuses = options.status === void 0 ? DEFAULT_LIST_STATUSES : [validateStatus(options.status)];
   const sessionsByStatus = {};
   for (const status of statuses) {
     const dirKey = STATUS_DIR_KEY[status];
@@ -7127,7 +7339,7 @@ async function listCommand(options) {
     for (const status of statuses) {
       recordsByStatus[status] = (sessionsByStatus[status] ?? []).map((session) => {
         const record6 = toSessionRecord(session);
-        return fieldSelection !== void 0 ? projectSessionRecord(record6, fieldSelection) : record6;
+        return fieldSelection === void 0 ? record6 : projectSessionRecord(record6, fieldSelection);
       });
     }
     return JSON.stringify(recordsByStatus, null, 2);
@@ -7145,7 +7357,7 @@ async function listCommand(options) {
 
 // src/commands/session/pickup.ts
 import { mkdir as mkdir3, readdir as readdir2, readFile as readFile5, rename as rename2 } from "fs/promises";
-import { join as join13 } from "path";
+import { join as join13, resolve as resolve6 } from "path";
 
 // src/domains/session/pickup.ts
 function buildClaimPaths(sessionId, config) {
@@ -7155,7 +7367,7 @@ function buildClaimPaths(sessionId, config) {
   };
 }
 function classifyClaimError(error, sessionId) {
-  if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+  if (error instanceof Error && "code" in error && error.code === SESSION_FILE_ERROR_CODE.NOT_FOUND) {
     return new SessionNotAvailableError(sessionId);
   }
   throw error;
@@ -7182,15 +7394,24 @@ function selectBestSession(sessions) {
 
 // src/commands/session/pickup.ts
 var PICKUP_TARGET_STATUS = SESSION_STATUSES[1];
+var PICKUP_DEPS = {
+  mkdir: mkdir3,
+  readdir: readdir2,
+  readFile: readFile5,
+  rename: rename2
+};
 async function loadTodoSessions(config) {
+  return loadTodoSessionsWithDeps(config, PICKUP_DEPS);
+}
+async function loadTodoSessionsWithDeps(config, deps) {
   try {
-    const files = await readdir2(config.todoDir);
+    const files = await deps.readdir(config.todoDir);
     const sessions = [];
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
       const filePath = join13(config.todoDir, file);
-      const content = await readFile5(filePath, "utf-8");
+      const content = await deps.readFile(filePath, SESSION_FILE_ENCODING);
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
@@ -7201,51 +7422,84 @@ async function loadTodoSessions(config) {
     }
     return sessions;
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+    if (error instanceof Error && "code" in error && error.code === SESSION_FILE_ERROR_CODE.NOT_FOUND) {
       return [];
     }
     throw error;
   }
 }
-async function pickupSingle(sessionId, config) {
+var SESSION_INJECTION_SECTION_PREFIX = "Injected file";
+var SESSION_INJECTION_MISSING_WARNING_PREFIX = "Warning: missing session injection file";
+function injectionPath(cwd, filePath) {
+  return resolve6(cwd, filePath);
+}
+function formatInjectedFile(listedPath, content) {
+  return `${SESSION_INJECTION_SECTION_PREFIX}: ${listedPath}
+${content}`;
+}
+async function readInjectedFiles(metadata, cwd, deps, onWarning) {
+  const sections = [];
+  for (const listedPath of [...metadata.specs, ...metadata.files]) {
+    try {
+      const content = await deps.readFile(injectionPath(cwd, listedPath), SESSION_FILE_ENCODING);
+      sections.push(formatInjectedFile(listedPath, content));
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === SESSION_FILE_ERROR_CODE.NOT_FOUND) {
+        onWarning?.(`${SESSION_INJECTION_MISSING_WARNING_PREFIX}: ${listedPath}`);
+        continue;
+      }
+      throw error;
+    }
+  }
+  return sections;
+}
+async function pickupSingle(sessionId, config, cwd, deps, noInject, onWarning) {
   const paths = buildClaimPaths(sessionId, config);
-  await mkdir3(config.doingDir, { recursive: true });
+  await deps.mkdir(config.doingDir, { recursive: true });
   try {
-    await rename2(paths.source, paths.target);
+    await deps.rename(paths.source, paths.target);
   } catch (error) {
     throw classifyClaimError(error, sessionId);
   }
-  const content = await readFile5(paths.target, "utf-8");
+  const content = await deps.readFile(paths.target, SESSION_FILE_ENCODING);
+  const metadata = parseSessionMetadata(content);
   const output = formatShowOutput(content, { status: PICKUP_TARGET_STATUS });
-  return `Claimed session <PICKUP_ID>${sessionId}</PICKUP_ID>
+  const injected = noInject ? [] : await readInjectedFiles(metadata, cwd, deps, onWarning);
+  const injectionOutput = injected.length === 0 ? "" : `
 
-${output}`;
+${injected.join("\n\n")}`;
+  return `Claimed session ${formatSessionOutputMarker(SESSION_OUTPUT_MARKER.PICKUP_ID, sessionId)}
+
+${output}${injectionOutput}`;
 }
 async function pickupCommand(options) {
-  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
+  const deps = options.deps ?? PICKUP_DEPS;
+  const cwd = options.cwd ?? CONFIG_PROCESS_CWD.read();
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning, cwd);
+  const noInject = options.noInject === true;
   if (options.auto) {
     if (options.sessionIds.length > 0) {
       throw new Error("Session IDs cannot be combined with --auto");
     }
-    const sessions = await loadTodoSessions(config);
+    const sessions = await loadTodoSessionsWithDeps(config, deps);
     const selected = selectBestSession(sessions);
     if (!selected) {
       throw new NoSessionsAvailableError();
     }
-    return pickupSingle(selected.id, config);
+    return pickupSingle(selected.id, config, cwd, deps, noInject, options.onWarning);
   }
   if (options.sessionIds.length === 0) {
     throw new Error("Either session ID or --auto flag is required");
   }
   if (options.sessionIds.length === 1) {
-    return pickupSingle(options.sessionIds[0], config);
+    return pickupSingle(options.sessionIds[0], config, cwd, deps, noInject, options.onWarning);
   }
-  return processBatch(options.sessionIds, (id) => pickupSingle(id, config));
+  return processBatch(options.sessionIds, (id) => pickupSingle(id, config, cwd, deps, noInject, options.onWarning));
 }
 
 // src/commands/session/pick.ts
 async function loadPickCandidates(options) {
-  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning, options.cwd);
   return loadTodoSessions(config);
 }
 
@@ -7301,7 +7555,7 @@ async function loadArchiveSessions(config) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
       const filePath = join14(config.archiveDir, file);
-      const content = await readFile6(filePath, "utf-8");
+      const content = await readFile6(filePath, SESSION_FILE_ENCODING);
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
@@ -7312,7 +7566,7 @@ async function loadArchiveSessions(config) {
     }
     return sessions;
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+    if (error instanceof Error && "code" in error && error.code === SESSION_FILE_ERROR_CODE.NOT_FOUND) {
       return [];
     }
     throw error;
@@ -7322,7 +7576,7 @@ async function pruneCommand(options) {
   validatePruneOptions(options);
   const keep = options.keep ?? DEFAULT_KEEP_COUNT;
   const dryRun = options.dryRun ?? false;
-  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning, options.cwd);
   const sessions = await loadArchiveSessions(config);
   const toPrune = selectSessionsToDelete(sessions, { keep });
   if (toPrune.length === 0) {
@@ -7384,7 +7638,7 @@ async function loadDoingSessions(config) {
     const files = await readdir4(config.doingDir);
     return files.filter((file) => file.endsWith(".md")).map((file) => ({ id: file.replace(".md", "") }));
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+    if (error instanceof Error && "code" in error && error.code === SESSION_FILE_ERROR_CODE.NOT_FOUND) {
       return [];
     }
     throw error;
@@ -7395,7 +7649,7 @@ async function releaseSingle(sessionId, config) {
   try {
     await rename3(paths.source, paths.target);
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+    if (error instanceof Error && "code" in error && error.code === SESSION_FILE_ERROR_CODE.NOT_FOUND) {
       throw new SessionNotClaimedError(sessionId);
     }
     throw error;
@@ -7404,7 +7658,7 @@ async function releaseSingle(sessionId, config) {
 ${SESSION_RELEASE_OUTPUT.RETURNED_TO_TODO}`;
 }
 async function releaseCommand(options) {
-  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning, options.cwd);
   let ids = options.sessionIds;
   if (ids.length === 0) {
     const sessions = await loadDoingSessions(config);
@@ -7438,7 +7692,7 @@ async function resolveSession(sessionId, config) {
   if (!found) {
     throw new SessionNotFoundError(sessionId);
   }
-  const content = await readFile7(found.path, "utf-8");
+  const content = await readFile7(found.path, SESSION_FILE_ENCODING);
   return { status: found.status, path: found.path, content };
 }
 async function showSingle(sessionId, config) {
@@ -7471,7 +7725,7 @@ ${failureLines}`;
   return JSON.stringify(payload, null, 2);
 }
 async function showCommand2(options) {
-  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning);
+  const config = await resolveSessionConfigSurfacingWarning(options.sessionsDir, options.onWarning, options.cwd);
   if (options.format === SESSION_LIST_FORMAT.JSON) {
     return showJson(options.sessionIds, config);
   }
@@ -7551,7 +7805,7 @@ Output:
 `;
 
 // src/domains/session/pick-model.ts
-import { resolve as resolve5 } from "path";
+import { resolve as resolve7 } from "path";
 var ELLIPSIS = "\u2026";
 var PICKER_RUNTIME = {
   CLAUDE: "claude",
@@ -7561,21 +7815,24 @@ var RUNTIME_SKILL_PREFIX = {
   [PICKER_RUNTIME.CLAUDE]: "/",
   [PICKER_RUNTIME.CODEX]: "$"
 };
+var PICKER_PICKUP_COMMAND_NAME = "pickup";
+var PICKER_AUTO_CONTINUE_FLAG = "--auto-continue";
 function buildPickupCommand(runtime, autoContinue, reference) {
-  const prompt = `${RUNTIME_SKILL_PREFIX[runtime]}pickup ${reference}${autoContinue ? " --auto-continue" : ""}`;
+  const prompt = `${RUNTIME_SKILL_PREFIX[runtime]}${PICKER_PICKUP_COMMAND_NAME} ${reference}${autoContinue ? ` ${PICKER_AUTO_CONTINUE_FLAG}` : ""}`;
   return { command: runtime, args: [prompt] };
 }
 function pickupReference(session, sessionsDir, cwd) {
-  return sessionsDir === void 0 ? session.id : resolve5(cwd, session.path);
+  return sessionsDir === void 0 ? session.id : resolve7(cwd, session.path);
 }
 function toSingleLine(text) {
-  return text.replace(/\s+/g, " ").trim();
+  return text.replaceAll(/\s+/g, " ").trim();
 }
 function truncateToWidth(text, max) {
   if (max <= 0) return "";
-  if (text.length <= max) return text;
-  if (max === 1) return ELLIPSIS;
-  return text.slice(0, max - 1) + ELLIPSIS;
+  if (visibleWidth(text) <= max) return text;
+  const ellipsisWidth = visibleWidth(ELLIPSIS);
+  if (max <= ellipsisWidth) return takeVisibleColumns(ELLIPSIS, max);
+  return `${takeVisibleColumns(text, max - ellipsisWidth)}${ELLIPSIS}`;
 }
 var PICKER_MODE = {
   BROWSE: "browse",
@@ -7680,17 +7937,195 @@ function reducePicker(state, action) {
   }
 }
 
+// src/lib/process-lifecycle/exit-codes.ts
+var SIGINT_EXIT_CODE = 130;
+var SIGTERM_EXIT_CODE = 143;
+var EPIPE_EXIT_CODE = 0;
+var UNCAUGHT_EXIT_CODE = 1;
+
+// src/lib/process-lifecycle/foreground-handoff.ts
+var FOREGROUND_SIGNALS = ["SIGINT", "SIGTERM"];
+function createSignalSuspender(target) {
+  return {
+    suspend() {
+      const ignore = () => {
+      };
+      const restorers = FOREGROUND_SIGNALS.map((signal) => {
+        const originals = target.listeners(signal);
+        for (const listener of originals) target.removeListener(signal, listener);
+        target.on(signal, ignore);
+        return () => {
+          target.removeListener(signal, ignore);
+          for (const listener of originals) target.on(signal, listener);
+        };
+      });
+      return () => {
+        for (const restore of restorers) restore();
+      };
+    }
+  };
+}
+
+// src/lib/process-lifecycle/handlers.ts
+var SIGINT_NAME = "SIGINT";
+var SIGTERM_NAME = "SIGTERM";
+function createHandlers(deps) {
+  let cleanupOnce = false;
+  function killEachChild(signal) {
+    deps.registry.forEach((child) => {
+      if (!child.killed) child.kill(signal);
+    });
+  }
+  function exitOnce(code, killSignal) {
+    if (cleanupOnce) {
+      deps.exitController.exit(code);
+      return;
+    }
+    cleanupOnce = true;
+    if (killSignal !== void 0) killEachChild(killSignal);
+    deps.exitController.exit(code);
+  }
+  return {
+    onSigint() {
+      exitOnce(SIGINT_EXIT_CODE, SIGINT_NAME);
+    },
+    onSigterm() {
+      exitOnce(SIGTERM_EXIT_CODE, SIGTERM_NAME);
+    },
+    onEpipe() {
+      exitOnce(EPIPE_EXIT_CODE, SIGTERM_NAME);
+    },
+    onUncaught(_error) {
+      exitOnce(UNCAUGHT_EXIT_CODE, SIGTERM_NAME);
+    }
+  };
+}
+
+// src/lib/process-lifecycle/install.ts
+import { spawn } from "child_process";
+
+// src/lib/process-lifecycle/registry.ts
+function createRegistry() {
+  const tracked = /* @__PURE__ */ new Set();
+  return {
+    add(child) {
+      tracked.add(child);
+    },
+    remove(child) {
+      tracked.delete(child);
+    },
+    forEach(fn) {
+      for (const child of tracked) fn(child);
+    },
+    get size() {
+      return tracked.size;
+    }
+  };
+}
+
+// src/lib/process-lifecycle/runner.ts
+function createLifecycleRunner(deps) {
+  return {
+    spawn(command, args, options) {
+      const child = deps.spawn(command, args, options);
+      deps.registry.add(child);
+      child.on("exit", () => deps.registry.remove(child));
+      return child;
+    }
+  };
+}
+
+// src/lib/process-lifecycle/install.ts
+var moduleRegistry = createRegistry();
+var moduleExitController = {
+  exit(code) {
+    process.exit(code);
+  }
+};
+var installed = false;
+var lifecycleProcessRunner = createLifecycleRunner({
+  registry: moduleRegistry,
+  spawn
+});
+var foregroundProcessRunner = { spawn };
+var processSignalTarget = {
+  listeners: (signal) => process.listeners(signal),
+  on: (signal, listener) => {
+    process.on(signal, listener);
+  },
+  removeListener: (signal, listener) => {
+    process.removeListener(signal, listener);
+  }
+};
+var lifecycleSignalSuspender = createSignalSuspender(processSignalTarget);
+var EPIPE_CODE = "EPIPE";
+var UNCAUGHT_PREFIX = "Uncaught: ";
+var NEWLINE = "\n";
+function formatUncaught(error) {
+  if (error instanceof Error && error.stack !== void 0) {
+    return UNCAUGHT_PREFIX + error.stack + NEWLINE;
+  }
+  return UNCAUGHT_PREFIX + String(error) + NEWLINE;
+}
+function logUncaughtToStderr(error) {
+  try {
+    process.stderr.write(formatUncaught(error));
+  } catch {
+  }
+}
+function installLifecycle() {
+  if (installed) return;
+  installed = true;
+  const handlers = createHandlers({
+    registry: moduleRegistry,
+    exitController: moduleExitController
+  });
+  process.on("uncaughtException", (error) => {
+    logUncaughtToStderr(error);
+    handlers.onUncaught(error);
+  });
+  process.on("unhandledRejection", (reason) => {
+    logUncaughtToStderr(reason);
+    handlers.onUncaught(reason);
+  });
+  process.on("SIGTERM", () => handlers.onSigterm());
+  process.on("SIGINT", () => handlers.onSigint());
+  process.stdout.on("error", (error) => {
+    if (error.code === EPIPE_CODE) {
+      handlers.onEpipe();
+      return;
+    }
+    handlers.onUncaught(error);
+  });
+  process.stderr.on("error", (error) => {
+    if (error.code === EPIPE_CODE) {
+      handlers.onEpipe();
+      return;
+    }
+    handlers.onUncaught(error);
+  });
+}
+
+// src/lib/process-lifecycle/managed-subprocess.ts
+var MANAGED_SUBPROCESS_STDIO = "pipe";
+function spawnManagedSubprocess(runner, command, args, options) {
+  return runner.spawn(command, args, {
+    ...options,
+    stdio: MANAGED_SUBPROCESS_STDIO
+  });
+}
+
 // src/interfaces/cli/session/pick/launch-agent.ts
 var LAUNCH_FAILURE_STATUS = 1;
 function launchAgent(runner, suspender, command) {
   const restoreSignals = suspender.suspend();
-  return new Promise((resolve8) => {
+  return new Promise((resolve10) => {
     let settled = false;
     const settle = (status) => {
       if (settled) return;
       settled = true;
       restoreSignals();
-      resolve8(status);
+      resolve10(status);
     };
     const child = runner.spawn(command.command, command.args, { stdio: "inherit" });
     child.once("exit", (code) => settle(code ?? LAUNCH_FAILURE_STATUS));
@@ -7735,7 +8170,7 @@ function SessionRow({ session, selected, columns }) {
   const priority = session.metadata.priority;
   const marker = selected ? SESSION_PICKER_SELECTED_MARKER : " ";
   const badge = priority === DEFAULT_PRIORITY ? "" : ` [${priority}]`;
-  const reserved = marker.length + 1 + session.id.length + badge.length + 1;
+  const reserved = visibleWidth(marker) + visibleWidth(" ") + visibleWidth(session.id) + visibleWidth(badge) + visibleWidth(" ");
   const goal = truncateToWidth(toSingleLine(session.metadata.goal), Math.max(MIN_GOAL_WIDTH, columns - reserved));
   return /* @__PURE__ */ jsxs(Text, { wrap: "truncate", color: selected ? "cyan" : void 0, children: [
     marker,
@@ -7760,7 +8195,8 @@ function PreviewPane({ session }) {
 }
 function SessionPicker({ sessions, onLaunch, onQuit, columns: columnsProp }) {
   const { stdout } = useStdout();
-  const columns = columnsProp ?? stdout?.columns ?? FALLBACK_COLUMNS;
+  const stdoutColumns = Reflect.get(stdout, "columns");
+  const columns = columnsProp ?? (typeof stdoutColumns === "number" ? stdoutColumns : FALLBACK_COLUMNS);
   const [state, setState] = useState(() => initialPickerState(sessions));
   useInput((input, key) => {
     const action = keyToAction(toPickerKey(input, key), state.mode);
@@ -7824,23 +8260,42 @@ async function readStdin() {
   if (process.stdin.isTTY) {
     return void 0;
   }
-  return new Promise((resolve8) => {
+  return new Promise((resolve10) => {
     let data = "";
-    process.stdin.setEncoding("utf-8");
+    process.stdin.setEncoding(SESSION_FILE_ENCODING);
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
     process.stdin.on("end", () => {
-      resolve8(data.length === 0 ? void 0 : data);
+      resolve10(data.length === 0 ? void 0 : data);
     });
     process.stdin.on("error", () => {
-      resolve8(void 0);
+      resolve10(void 0);
     });
   });
 }
-function handleError2(error) {
-  console.error("Error:", error instanceof Error ? `${error.name}: ${error.message}` : String(error));
-  process.exit(1);
+function writeOutput2(invocation, output) {
+  invocation.io.writeStdout(`${output}
+`);
+}
+function writeError3(invocation, output) {
+  invocation.io.writeStderr(`${output}
+`);
+}
+function writeInvocationWarning2(invocation, warning) {
+  if (warning !== void 0) {
+    writeError3(invocation, warning);
+  }
+}
+function formatError2(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return toMessage(error);
+}
+function handleError2(invocation, error) {
+  writeError3(invocation, `Error: ${formatError2(error)}`);
+  return invocation.io.exit(1);
 }
 function colorFlagFromOption(colorOption) {
   if (colorOption === true) {
@@ -7860,10 +8315,26 @@ function resolveListColorDecision(colorOption) {
   });
 }
 function resolveListWidth() {
-  return Math.max(LIST_TEXT_MIN_WIDTH, process.stdout.columns ?? DEFAULT_LIST_WIDTH);
+  const columns = Reflect.get(process.stdout, "columns");
+  const resolvedColumns = typeof columns === "number" ? columns : DEFAULT_LIST_WIDTH;
+  return Math.max(LIST_TEXT_MIN_WIDTH, resolvedColumns);
+}
+function addSessionOptions(command, options) {
+  for (const option of options) {
+    if (option.defaultValue === void 0) {
+      command.option(sessionOptionToken(option), option.description);
+    } else {
+      command.option(sessionOptionToken(option), option.description, option.defaultValue);
+    }
+  }
+  return command;
 }
-function registerSessionCommands(sessionCmd) {
-  sessionCmd.command("list").description("List active sessions (doing + todo by default)").option("--status <status>", "Filter by status (todo|doing|archive); defaults to doing + todo").option("--json", "Output as JSON").option("--fields <fields>", "Comma-separated fields to emit as JSON (implies --json)").option("--color", "Force colored text output").option("--no-color", "Disable colored text output").option("--sessions-dir <path>", "Custom sessions directory").action(
+function registerSessionCommands(sessionCmd, invocation) {
+  const effectiveInvocationDir = () => invocation.resolveEffectiveInvocationDir();
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.list)).description(sessionCliDefinition.subcommands.list.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.list)
+  ).action(
     async (options) => {
       try {
         const output = await listCommand({
@@ -7873,36 +8344,44 @@ function registerSessionCommands(sessionCmd) {
           color: resolveListColorDecision(options.color),
           width: resolveListWidth(),
           sessionsDir: options.sessionsDir,
-          onWarning: writeWarning
+          cwd: effectiveInvocationDir(),
+          onWarning: (warning) => writeInvocationWarning2(invocation, warning)
         });
-        console.log(output);
+        writeOutput2(invocation, output);
       } catch (error) {
-        handleError2(error);
+        handleError2(invocation, error);
       }
     }
   );
-  sessionCmd.command("pick").description("Interactively pick a session and launch claude or codex to resume it").option("--sessions-dir <path>", "Custom sessions directory").action(async (options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.pick)).description(sessionCliDefinition.subcommands.pick.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.pick)
+  ).action(async (options) => {
     try {
       if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        console.error(PICK_NON_TTY_MESSAGE);
-        process.exit(1);
+        writeError3(invocation, PICK_NON_TTY_MESSAGE);
+        invocation.io.exit(1);
       }
       const sessions = await loadPickCandidates({
         sessionsDir: options.sessionsDir,
-        onWarning: writeWarning
+        cwd: effectiveInvocationDir(),
+        onWarning: (warning) => writeInvocationWarning2(invocation, warning)
       });
       const choice = await runPicker(sessions);
       if (choice !== null) {
-        const reference = pickupReference(choice.session, options.sessionsDir, process.cwd());
+        const reference = pickupReference(choice.session, options.sessionsDir, effectiveInvocationDir());
         const command = buildPickupCommand(choice.runtime, choice.autoContinue, reference);
         const code = await launchAgent(foregroundProcessRunner, lifecycleSignalSuspender, command);
-        process.exit(code);
+        invocation.io.exit(code);
       }
     } catch (error) {
-      handleError2(error);
+      handleError2(invocation, 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("--color", "Force colored text output").option("--no-color", "Disable colored text output").option("--sessions-dir <path>", "Custom sessions directory").action(async (options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.todo)).description(sessionCliDefinition.subcommands.todo.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.todo)
+  ).action(async (options) => {
     try {
       const output = await listCommand({
         status: SESSION_STATUSES[0],
@@ -7911,129 +8390,159 @@ function registerSessionCommands(sessionCmd) {
         color: resolveListColorDecision(options.color),
         width: resolveListWidth(),
         sessionsDir: options.sessionsDir,
-        onWarning: writeWarning
+        cwd: effectiveInvocationDir(),
+        onWarning: (warning) => writeInvocationWarning2(invocation, warning)
       });
-      console.log(output);
+      writeOutput2(invocation, output);
     } catch (error) {
-      handleError2(error);
+      handleError2(invocation, error);
     }
   });
-  sessionCmd.command("show <id...>").description("Show session content").option("--json", "Output parsed session frontmatter as JSON (a record per id)").option("--sessions-dir <path>", "Custom sessions directory").action(async (ids, options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.show)).description(sessionCliDefinition.subcommands.show.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.show)
+  ).action(async (ids, options) => {
     try {
       const output = await showCommand2({
         sessionIds: ids,
         format: options.json ? SESSION_LIST_FORMAT.JSON : SESSION_LIST_FORMAT.TEXT,
         sessionsDir: options.sessionsDir,
-        onWarning: writeWarning
+        cwd: effectiveInvocationDir(),
+        onWarning: (warning) => writeInvocationWarning2(invocation, warning)
       });
-      console.log(output);
+      writeOutput2(invocation, output);
     } catch (error) {
-      handleError2(error);
+      handleError2(invocation, error);
     }
   });
-  sessionCmd.command("pickup [ids...]").description("Claim one or more sessions (move from todo to doing)").option("--auto", "Auto-select highest priority session").option("--sessions-dir <path>", "Custom sessions directory").addHelpText("after", PICKUP_SELECTION_HELP).action(async (ids, options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.pickup)).description(sessionCliDefinition.subcommands.pickup.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.pickup)
+  ).addHelpText("after", PICKUP_SELECTION_HELP).action(async (ids, options) => {
     try {
       if (ids.length === 0 && !options.auto) {
-        console.error("Error: Either session ID or --auto flag is required");
-        process.exit(1);
+        writeError3(invocation, "Error: Either session ID or --auto flag is required");
+        invocation.io.exit(1);
       }
       const output = await pickupCommand({
         sessionIds: ids,
         auto: options.auto,
+        noInject: options.inject === false,
         sessionsDir: options.sessionsDir,
-        onWarning: writeWarning
+        cwd: effectiveInvocationDir(),
+        onWarning: (warning) => writeInvocationWarning2(invocation, warning)
       });
-      console.log(output);
+      writeOutput2(invocation, output);
     } catch (error) {
-      handleError2(error);
+      handleError2(invocation, error);
     }
   });
-  sessionCmd.command("release [ids...]").description("Release one or more sessions (move from doing to todo)").option("--sessions-dir <path>", "Custom sessions directory").action(async (ids, options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.release)).description(sessionCliDefinition.subcommands.release.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.release)
+  ).action(async (ids, options) => {
     try {
       const output = await releaseCommand({
         sessionIds: ids,
         sessionsDir: options.sessionsDir,
-        onWarning: writeWarning
+        cwd: effectiveInvocationDir(),
+        onWarning: (warning) => writeInvocationWarning2(invocation, warning)
       });
-      console.log(output);
+      writeOutput2(invocation, output);
     } catch (error) {
-      handleError2(error);
+      handleError2(invocation, error);
     }
   });
-  sessionCmd.command("handoff").description("Create a handoff session (reads JSON header + body from stdin)").option("--sessions-dir <path>", "Custom sessions directory").addHelpText("after", HANDOFF_FRONTMATTER_HELP).action(async (options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.handoff)).description(sessionCliDefinition.subcommands.handoff.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.handoff)
+  ).addHelpText("after", HANDOFF_FRONTMATTER_HELP).action(async (options) => {
     try {
       const content = await readStdin();
       const result = await handoffCommand({
         content,
         sessionsDir: options.sessionsDir,
+        cwd: effectiveInvocationDir(),
         env: process.env
       });
-      console.log(result.output);
+      writeOutput2(invocation, result.output);
     } catch (error) {
       if (error instanceof SessionHandoffBaseError) {
         if (error.checklist !== null) {
-          console.error(renderHandoffBaseChecklist(error.checklist));
+          writeError3(invocation, renderHandoffBaseChecklist(error.checklist));
         } else if (!error.silent) {
-          console.error("Error:", `${error.name}: ${error.message}`);
+          writeError3(invocation, `Error: ${error.name}: ${error.message}`);
         }
-        process.exit(1);
+        invocation.io.exit(1);
       }
-      handleError2(error);
+      handleError2(invocation, error);
     }
   });
-  sessionCmd.command("delete <id...>").description("Delete one or more sessions").option("--sessions-dir <path>", "Custom sessions directory").action(async (ids, options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.delete)).description(sessionCliDefinition.subcommands.delete.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.delete)
+  ).action(async (ids, options) => {
     try {
       const output = await deleteCommand({
         sessionIds: ids,
         sessionsDir: options.sessionsDir,
-        onWarning: writeWarning
+        cwd: effectiveInvocationDir(),
+        onWarning: (warning) => writeInvocationWarning2(invocation, warning)
       });
-      console.log(output);
+      writeOutput2(invocation, output);
     } catch (error) {
-      handleError2(error);
+      handleError2(invocation, error);
     }
   });
-  sessionCmd.command("prune").description("Remove old todo sessions, keeping the most recent N").option("--keep <count>", "Number of sessions to keep (default: 5)", "5").option("--dry-run", "Show what would be deleted without deleting").option("--sessions-dir <path>", "Custom sessions directory").action(async (options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.prune)).description(sessionCliDefinition.subcommands.prune.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.prune)
+  ).action(async (options) => {
     try {
       const keep = options.keep ? Number.parseInt(options.keep, 10) : void 0;
       const output = await pruneCommand({
         keep,
         dryRun: options.dryRun,
         sessionsDir: options.sessionsDir,
-        onWarning: writeWarning
+        cwd: effectiveInvocationDir(),
+        onWarning: (warning) => writeInvocationWarning2(invocation, warning)
       });
-      console.log(output);
+      writeOutput2(invocation, output);
     } catch (error) {
       if (error instanceof PruneValidationError) {
-        console.error("Error:", error.message);
-        process.exit(1);
+        writeError3(invocation, `Error: ${error.message}`);
+        invocation.io.exit(1);
       }
-      handleError2(error);
+      handleError2(invocation, error);
     }
   });
-  sessionCmd.command("archive <id...>").description("Move one or more sessions to the archive directory").option("--sessions-dir <path>", "Custom sessions directory").action(async (ids, options) => {
+  addSessionOptions(
+    sessionCmd.command(sessionCommandToken(sessionCliDefinition.subcommands.archive)).description(sessionCliDefinition.subcommands.archive.description),
+    sessionOptionsForSubcommand(sessionCliDefinition.subcommands.archive)
+  ).action(async (ids, options) => {
     try {
       const output = await archiveCommand({
         sessionIds: ids,
         sessionsDir: options.sessionsDir,
-        onWarning: writeWarning
+        cwd: effectiveInvocationDir(),
+        onWarning: (warning) => writeInvocationWarning2(invocation, warning)
       });
-      console.log(output);
+      writeOutput2(invocation, output);
     } catch (error) {
       if (error instanceof SessionAlreadyArchivedError) {
-        console.error("Error:", error.message);
-        process.exit(1);
+        writeError3(invocation, `Error: ${error.message}`);
+        invocation.io.exit(1);
       }
-      handleError2(error);
+      handleError2(invocation, error);
     }
   });
 }
 var sessionDomain = {
-  name: "session",
-  description: "Manage session workflow",
-  register: (program2) => {
-    const sessionCmd = program2.command("session").description("Manage session workflow").addHelpText("after", SESSION_FORMAT_HELP);
-    registerSessionCommands(sessionCmd);
+  name: sessionCliDefinition.domain.commandName,
+  description: sessionCliDefinition.domain.description,
+  register: (program, invocation) => {
+    const sessionCmd = program.command(sessionCliDefinition.domain.commandName).description(sessionCliDefinition.domain.description).addHelpText("after", SESSION_FORMAT_HELP);
+    registerSessionCommands(sessionCmd, invocation);
   }
 };
 
@@ -8142,7 +8651,7 @@ function recognizeSpecTreeFilesystemEntry(record6, options = {}) {
   if (record6.type === SPEC_TREE_FILESYSTEM_RECORD_TYPE.DIRECTORY) {
     return recognizeDirectoryRecord(record6, name, registry, schemaVersions);
   }
-  if (record6.type === SPEC_TREE_FILESYSTEM_RECORD_TYPE.FILE && record6.parentId !== void 0 && isEvidenceFile(record6.relativePath)) {
+  if (record6.parentId !== void 0 && isEvidenceFile(record6.relativePath)) {
     return {
       type: SPEC_TREE_ENTRY_TYPE.EVIDENCE,
       id: record6.relativePath,
@@ -8151,22 +8660,19 @@ function recognizeSpecTreeFilesystemEntry(record6, options = {}) {
       ref: sourceRefForRelativePath(record6.relativePath)
     };
   }
-  if (record6.type === SPEC_TREE_FILESYSTEM_RECORD_TYPE.FILE) {
-    const decisionMatch = matchKindSuffix(name, registry, SPEC_TREE_KIND_CATEGORY.DECISION);
-    if (decisionMatch === null) return null;
-    const parsed = parseOrderedSlug(stripSuffix(name, decisionMatch.definition.suffix));
-    if (parsed === null) return null;
-    return {
-      type: SPEC_TREE_ENTRY_TYPE.DECISION,
-      kind: decisionMatch.kind,
-      id: record6.relativePath,
-      order: parsed.order,
-      slug: parsed.slug,
-      parentId: record6.parentId,
-      ref: sourceRefForRelativePath(record6.relativePath)
-    };
-  }
-  return null;
+  const decisionMatch = matchKindSuffix(name, registry, SPEC_TREE_KIND_CATEGORY.DECISION);
+  if (decisionMatch === null) return null;
+  const parsed = parseOrderedSlug(stripSuffix(name, decisionMatch.definition.suffix));
+  if (parsed === null) return null;
+  return {
+    type: SPEC_TREE_ENTRY_TYPE.DECISION,
+    kind: decisionMatch.kind,
+    id: record6.relativePath,
+    order: parsed.order,
+    slug: parsed.slug,
+    parentId: record6.parentId,
+    ref: sourceRefForRelativePath(record6.relativePath)
+  };
 }
 function recognizeDirectoryRecord(record6, name, registry, schemaVersions) {
   const canonical = canonicalNamingSchemaVersion(schemaVersions);
@@ -8195,6 +8701,7 @@ function recognizeDirectoryRecord(record6, name, registry, schemaVersions) {
       ref: sourceRefForRelativePath(record6.relativePath)
     };
   }
+  if (matchKindSuffix(name, registry, SPEC_TREE_KIND_CATEGORY.DECISION) !== null) return null;
   if (parseOrderedSlug(name) !== null) {
     return {
       type: SPEC_TREE_ENTRY_TYPE.INVALID,
@@ -8355,7 +8862,8 @@ function groupDecisions(entries) {
     if (entry.parentId === void 0) continue;
     const group = grouped.get(entry.parentId) ?? [];
     group.push(entry);
-    grouped.set(entry.parentId, group.sort(compareOrderedEntries));
+    group.sort(compareOrderedEntries);
+    grouped.set(entry.parentId, group);
   }
   return grouped;
 }
@@ -8425,7 +8933,7 @@ async function* walkFilesystemDirectory(context) {
     const relativePath = joinSpecTreePath(context.relativePath, entry.name);
     const refPath = joinSpecTreePath(SPEC_TREE_CONFIG.ROOT_DIRECTORY, relativePath);
     if (!await context.includePath(refPath)) continue;
-    const recordType = entry.isDirectory() ? SPEC_TREE_FILESYSTEM_RECORD_TYPE.DIRECTORY : entry.isFile() ? SPEC_TREE_FILESYSTEM_RECORD_TYPE.FILE : void 0;
+    const recordType = filesystemRecordType(entry);
     if (recordType === void 0) continue;
     const sourceEntry = recognizeSpecTreeFilesystemEntry(
       { type: recordType, relativePath, parentId: context.parentId },
@@ -8439,11 +8947,19 @@ async function* walkFilesystemDirectory(context) {
         registry: context.registry,
         schemaVersions: context.schemaVersions,
         includePath: context.includePath,
-        parentId: sourceEntry?.type === SPEC_TREE_ENTRY_TYPE.NODE ? sourceEntry.id : context.parentId
+        parentId: childParentId(context, sourceEntry)
       });
     }
   }
 }
+function filesystemRecordType(entry) {
+  if (entry.isDirectory()) return SPEC_TREE_FILESYSTEM_RECORD_TYPE.DIRECTORY;
+  if (entry.isFile()) return SPEC_TREE_FILESYSTEM_RECORD_TYPE.FILE;
+  return void 0;
+}
+function childParentId(context, sourceEntry) {
+  return sourceEntry?.type === SPEC_TREE_ENTRY_TYPE.NODE ? sourceEntry.id : context.parentId;
+}
 function matchKindSuffix(name, registry, category) {
   for (const [kind, definition] of Object.entries(registry)) {
     if (definition.category === category && name.endsWith(definition.suffix)) {
@@ -8470,8 +8986,8 @@ function isProductFile(relativePath) {
 function isEvidenceFile(relativePath) {
   const segments = relativePath.split(SPEC_TREE_PATH_SEPARATOR);
   if (segments.length < SPEC_TREE_MIN_EVIDENCE_PATH_SEGMENTS) return false;
-  const filename = segments[segments.length - 1] ?? "";
-  const directoryName = segments[segments.length - SPEC_TREE_PARENT_SEGMENT_OFFSET];
+  const filename = segments.at(-1) ?? "";
+  const directoryName = segments.at(-SPEC_TREE_PARENT_SEGMENT_OFFSET);
   const filenameSegments = filename.split(SPEC_TREE_EVIDENCE_FILE.SEGMENT_SEPARATOR);
   return directoryName === SPEC_TREE_EVIDENCE_FILE.DIRECTORY_NAME && SPEC_TREE_EVIDENCE_FILE_TAILS.some(
     (tail) => SPEC_TREE_EVIDENCE_FILE.MODES.some(
@@ -8510,7 +9026,7 @@ function stripSuffix(value, suffix) {
 }
 function readLastPathSegment(relativePath) {
   const segments = relativePath.split(SPEC_TREE_PATH_SEPARATOR);
-  return segments[segments.length - 1] ?? relativePath;
+  return segments.at(-1) ?? relativePath;
 }
 function joinSpecTreePath(...segments) {
   return segments.filter((segment) => segment.length > 0).join(SPEC_TREE_PATH_SEPARATOR);
@@ -8550,7 +9066,7 @@ async function nextCommand(options = {}) {
     return formatNextSpecTreeNode(snapshot2);
   }
   const productDir = await resolveSpecProductDir(
-    options.cwd ?? process.cwd(),
+    options.cwd ?? CONFIG_PROCESS_CWD.read(),
     options.gitDependencies,
     options.onWarning
   );
@@ -9436,7 +9952,7 @@ function createNodeStatusProvider(productDir) {
 
 // src/lib/node-status/update.ts
 import { mkdir as mkdir4, readdir as readdir7, rm, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname6, join as join21 } from "path";
+import { dirname as dirname7, join as join21 } from "path";
 var NODE_STATUS_TEXT_ENCODING = "utf8";
 async function updateNodeStatus(options) {
   const { productDir, resolveOutcome } = options;
@@ -9498,7 +10014,7 @@ function evidencePath(entry) {
   return entry.ref?.path ?? entry.id;
 }
 async function writeNodeStatus(filePath, verification) {
-  await mkdir4(dirname6(filePath), { recursive: true });
+  await mkdir4(dirname7(filePath), { recursive: true });
   await writeFile2(filePath, serializeNodeStatus(createNodeStatusFile(verification)), NODE_STATUS_TEXT_ENCODING);
 }
 function nodeStatusPath(productDir, nodeId) {
@@ -9634,12 +10150,21 @@ var SPEC_STATUS_TABLE_HEADER = formatTableRow([
   TABLE_HEADER.PATH,
   TABLE_HEADER.STATE
 ]);
+var SpecStatusUpdateRequiresProductDirError = class extends Error {
+  constructor() {
+    super("Cannot update spec status for an injected in-memory source");
+    this.name = "SpecStatusUpdateRequiresProductDirError";
+  }
+};
 async function statusCommand(options = {}) {
   if (options.source !== void 0) {
+    if (options.update === true) {
+      throw new SpecStatusUpdateRequiresProductDirError();
+    }
     return renderSpecStatus(projectSpecTree(await readSpecTree({ source: options.source })), options.format);
   }
   const productDir = await resolveSpecProductDir(
-    options.cwd ?? process.cwd(),
+    options.cwd ?? CONFIG_PROCESS_CWD.read(),
     options.gitDependencies,
     options.onWarning
   );
@@ -9706,7 +10231,8 @@ function flattenProjectionNodes(nodes) {
   return nodes.flatMap((node) => [node, ...flattenProjectionNodes(node.children)]);
 }
 function formatTableRow(values) {
-  return `${TABLE_SEPARATOR} ${values.join(` ${TABLE_SEPARATOR} `)} ${TABLE_SEPARATOR}`;
+  const separator = ` ${TABLE_SEPARATOR} `;
+  return `${TABLE_SEPARATOR} ${values.join(separator)} ${TABLE_SEPARATOR}`;
 }
 function formatNodeLabel(node) {
   return [
@@ -9717,7 +10243,7 @@ function formatNodeLabel(node) {
 }
 
 // src/test/languages/python.ts
-import { basename as basename3, dirname as dirname7, join as join22 } from "path/posix";
+import { basename as basename3, dirname as dirname8, join as join22 } from "path/posix";
 
 // src/validation/discovery/language-finder.ts
 import fs6 from "fs";
@@ -9788,10 +10314,10 @@ function coveredProductInputPaths(coveredTestPaths2) {
   const paths = /* @__PURE__ */ new Set();
   for (const testPath of coveredTestPaths2) {
     if (!matchesTestFile(testPath)) continue;
-    let directory = dirname7(testPath);
+    let directory = dirname8(testPath);
     while (directory !== "." && directory.length > 0) {
       paths.add(join22(directory, PYTHON_PRODUCT_INPUT_PATH.CONFTEST));
-      const parent = dirname7(directory);
+      const parent = dirname8(directory);
       if (parent === directory) break;
       directory = parent;
     }
@@ -10015,7 +10541,17 @@ var VALID_STATUS_FORMATS = [
   OUTPUT_FORMAT.TABLE
 ];
 var UNPRINTABLE_ERROR_MESSAGE = "unprintable error";
-function handleCommandError(error) {
+function writeOutput3(io, output) {
+  io.writeStdout(`${output}
+`);
+}
+function writeInvocationWarning3(io, warning) {
+  if (warning !== void 0) {
+    io.writeStderr(`${warning}
+`);
+  }
+}
+function handleCommandError(io, error) {
   let message;
   if (error instanceof Error) {
     message = error.message;
@@ -10028,8 +10564,9 @@ function handleCommandError(error) {
       message = UNPRINTABLE_ERROR_MESSAGE;
     }
   }
-  console.error("Error:", message);
-  process.exit(1);
+  io.writeStderr(`Error: ${message}
+`);
+  return io.exit(1);
 }
 function resolveStatusFormat(options) {
   if (options.json === true) {
@@ -10045,41 +10582,43 @@ function resolveStatusFormat(options) {
     `${SPEC_STATUS_FORMAT_MESSAGE.INVALID_PREFIX} "${options.format}". Must be one of: ${VALID_STATUS_FORMATS.join(", ")}`
   );
 }
-function registerSpecCommands(specCmd) {
+function registerSpecCommands(specCmd, invocation) {
+  const productDir = () => invocation.resolveProductContext().productDir;
+  const onWarning = (warning) => writeInvocationWarning3(invocation.io, warning);
   specCmd.command(SPEC_DOMAIN_CLI.STATUS_COMMAND).description("Get product status").option(SPEC_DOMAIN_CLI.JSON_OPTION, "Output as JSON").option(SPEC_DOMAIN_CLI.FORMAT_OPTION_DEFINITION, "Output format (text|json|markdown|table)").option(SPEC_DOMAIN_CLI.UPDATE_OPTION, "Refresh each node's spx.status.json before reporting").action(async (options) => {
     try {
       const format2 = resolveStatusFormat(options);
       const output = options.update === true ? await statusCommand({
-        cwd: process.cwd(),
+        cwd: productDir(),
         format: format2,
-        onWarning: writeWarning,
+        onWarning,
         update: true,
-        resolveOutcomeFor: (productDir) => createNodeOutcomeResolver({
-          productDir,
+        resolveOutcomeFor: (productDir2) => createNodeOutcomeResolver({
+          productDir: productDir2,
           registry: testingRegistry,
-          runnerDepsFor: createRunnerDepsFor(productDir, process.stderr)
+          runnerDepsFor: createRunnerDepsFor(productDir2, process.stderr)
         })
-      }) : await statusCommand({ cwd: process.cwd(), format: format2, onWarning: writeWarning });
-      console.log(output);
+      }) : await statusCommand({ cwd: productDir(), format: format2, onWarning });
+      writeOutput3(invocation.io, output);
     } catch (error) {
-      handleCommandError(error);
+      handleCommandError(invocation.io, error);
     }
   });
   specCmd.command(SPEC_DOMAIN_CLI.NEXT_COMMAND).description("Find next spec-tree node to work on").action(async () => {
     try {
-      const output = await nextCommand({ cwd: process.cwd(), onWarning: writeWarning });
-      console.log(output);
+      const output = await nextCommand({ cwd: productDir(), onWarning });
+      writeOutput3(invocation.io, output);
     } catch (error) {
-      handleCommandError(error);
+      handleCommandError(invocation.io, error);
     }
   });
 }
 var specDomain = {
   name: "spec",
   description: "Manage spec workflow",
-  register: (program2) => {
-    const specCmd = program2.command(SPEC_DOMAIN_CLI.COMMAND).description("Manage spec workflow");
-    registerSpecCommands(specCmd);
+  register: (program, invocation) => {
+    const specCmd = program.command(SPEC_DOMAIN_CLI.COMMAND).description("Manage spec workflow");
+    registerSpecCommands(specCmd, invocation);
   }
 };
 
@@ -10193,33 +10732,33 @@ var UNRESOLVED_TARGETS_WARNING = "No tests matched these operands";
 var TESTING_PRODUCT_DIR_WARNING = {
   NOT_GIT_REPOSITORY: `Warning: Not in a git repository. Reading ${SPEC_TREE_CONFIG.ROOT_DIRECTORY} tests relative to the current working directory.`
 };
-async function resolveTestProductDir() {
-  const { productDir, isGitRepo } = await detectWorktreeProductRoot(process.cwd());
+async function resolveTestProductDir(cwd, writeWarning) {
+  const { productDir, isGitRepo } = await detectWorktreeProductRoot(cwd);
   writeWarning(isGitRepo ? void 0 : TESTING_PRODUCT_DIR_WARNING.NOT_GIT_REPOSITORY);
   return productDir;
 }
-async function runTestsThroughCommand(productDir, passing, targets) {
+async function runTestsThroughCommand(productDir, passing, io, targets) {
   try {
     return await runTestsCommand(
       { productDir, passing, targets },
       { registry: testingRegistry, runnerDepsFor: createRunnerDepsFor(productDir) }
     );
   } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+    io.writeStderr(`${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(PROCESS_FAILURE_EXIT_CODE);
+    io.exit(PROCESS_FAILURE_EXIT_CODE);
   }
 }
-async function runAgentTestsThroughCommand(productDir, passing, targets) {
+async function runAgentTestsThroughCommand(productDir, passing, io, targets) {
   try {
     return await runTestsCommand(
       { productDir, passing, targets },
       { registry: testingRegistry, runnerDepsFor: createAgentRunnerDepsFor(productDir) }
     );
   } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+    io.writeStderr(`${error instanceof Error ? error.message : String(error)}
 `);
-    process.exit(PROCESS_FAILURE_EXIT_CODE);
+    io.exit(PROCESS_FAILURE_EXIT_CODE);
   }
 }
 function unreportedGroups2(result) {
@@ -10258,19 +10797,23 @@ function targetSelection(targets, options, command) {
   const parentOptions = command.parent?.opts() ?? {};
   return { operands: targets, recursive: options.recursive === true || parentOptions.recursive === true };
 }
-var defaultTestingCliDependencies = {
-  resolveProductDir: resolveTestProductDir,
-  runTests: runTestsThroughCommand,
-  runAgentTests: runAgentTestsThroughCommand,
-  writeStdout: (output) => {
-    process.stdout.write(output);
-  },
-  writeWarning,
-  setExitCode: (exitCode) => {
-    process.exitCode = exitCode;
-  },
-  exit: (exitCode) => process.exit(exitCode)
-};
+function defaultTestingCliDependencies(invocation) {
+  const writeWarning = (warning) => {
+    if (warning !== void 0) {
+      invocation.io.writeStderr(`${warning}
+`);
+    }
+  };
+  return {
+    resolveProductDir: () => resolveTestProductDir(invocation.resolveEffectiveInvocationDir(), writeWarning),
+    runTests: (productDir, passing, targets) => runTestsThroughCommand(productDir, passing, invocation.io, targets),
+    runAgentTests: (productDir, passing, targets) => runAgentTestsThroughCommand(productDir, passing, invocation.io, targets),
+    writeStdout: (output) => invocation.io.writeStdout(output),
+    writeWarning,
+    setExitCode: (exitCode) => invocation.io.setExitCode(exitCode),
+    exit: (exitCode) => invocation.io.exit(exitCode)
+  };
+}
 async function runTestingAction(deps, passing, options, targets) {
   const productDir = await deps.resolveProductDir();
   if (options.agent === true) {
@@ -10282,12 +10825,13 @@ async function runTestingAction(deps, passing, options, targets) {
   const result = await deps.runTests(productDir, passing, targets);
   reportAndExit(result.dispatch, deps);
 }
-function createTestingDomain(deps = defaultTestingCliDependencies) {
+function createTestingDomain(deps) {
   return {
     name: TESTING_CLI.commandName,
     description: TESTING_CLI.description,
-    register: (program2) => {
-      const testCmd = program2.command(TESTING_CLI.commandName).description(TESTING_CLI.description);
+    register: (program, invocation) => {
+      const actionDeps = deps ?? defaultTestingCliDependencies(invocation);
+      const testCmd = program.command(TESTING_CLI.commandName).description(TESTING_CLI.description);
       testCmd.option(TESTING_CLI.agentOption, TESTING_CLI.agentDescription);
       testCmd.option(
         `${TESTING_CLI.recursiveShortFlag}, ${TESTING_CLI.recursiveLongFlag}`,
@@ -10296,7 +10840,7 @@ function createTestingDomain(deps = defaultTestingCliDependencies) {
       testCmd.argument(TESTING_CLI.targetsArgument, TESTING_CLI.targetsDescription);
       testCmd.action(async (targets, options, command) => {
         await runTestingAction(
-          deps,
+          actionDeps,
           false,
           { agent: requestsAgentMode(options, command) },
           targetSelection(targets, options, command)
@@ -10304,7 +10848,7 @@ function createTestingDomain(deps = defaultTestingCliDependencies) {
       });
       testCmd.command(TESTING_CLI.passingSubcommand).description(TESTING_CLI.passingDescription).option(TESTING_CLI.agentOption, TESTING_CLI.agentDescription).option(`${TESTING_CLI.recursiveShortFlag}, ${TESTING_CLI.recursiveLongFlag}`, TESTING_CLI.recursiveDescription).argument(TESTING_CLI.targetsArgument, TESTING_CLI.targetsDescription).action(async (targets, options, command) => {
         await runTestingAction(
-          deps,
+          actionDeps,
           true,
           { agent: requestsAgentMode(options, command) },
           targetSelection(targets, options, command)
@@ -10454,7 +10998,7 @@ function buildDprintCheckArgs(options) {
 }
 async function validateFormatting(context, runner = defaultFormattingProcessRunner) {
   const args = buildDprintCheckArgs({ files: context.files });
-  return new Promise((resolve8) => {
+  return new Promise((resolve10) => {
     const child = spawnManagedSubprocess(runner, DPRINT_COMMAND, args, { cwd: context.projectRoot });
     const chunks = [];
     const capture = (chunk) => {
@@ -10463,10 +11007,10 @@ async function validateFormatting(context, runner = defaultFormattingProcessRunn
     child.stdout?.on(VALIDATION_SUBPROCESS_EVENTS.DATA, capture);
     child.stderr?.on(VALIDATION_SUBPROCESS_EVENTS.DATA, capture);
     child.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
-      resolve8({ success: code === 0, output: chunks.join("") });
+      resolve10({ success: code === 0, output: chunks.join("") });
     });
     child.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
-      resolve8({ success: false, output: chunks.join(""), error: error.message });
+      resolve10({ success: false, output: chunks.join(""), error: error.message });
     });
   });
 }
@@ -10587,7 +11131,7 @@ import { relative as relative4 } from "path";
 
 // src/validation/steps/markdown.ts
 import { existsSync as existsSync2, statSync } from "fs";
-import { basename as basename4, dirname as dirname8, join as join25, relative as pathRelative } from "path";
+import { basename as basename4, dirname as dirname9, join as join25, 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"];
@@ -10717,7 +11261,7 @@ async function validateTarget(target, config, projectRoot, ignoreGlobs = []) {
   return errors;
 }
 function targetDirectory(target) {
-  return target.kind === MARKDOWN_VALIDATION_TARGET_KIND.FILE ? dirname8(target.path) : target.path;
+  return target.kind === MARKDOWN_VALIDATION_TARGET_KIND.FILE ? dirname9(target.path) : target.path;
 }
 function hasMarkdownExtension(path7) {
   const lastDot = path7.lastIndexOf(".");
@@ -10772,10 +11316,10 @@ async function markdownCommand(options) {
     VALIDATION_PATH_TOOL_SUBSECTIONS.MARKDOWN
   );
   const targetResolutions = files && files.length > 0 ? files.map((filePath) => resolveMarkdownValidationTarget(filePath)) : void 0;
-  const unfilteredTargets = targetResolutions !== void 0 ? targetResolutions.map((resolution) => resolution.target).filter((target) => target !== void 0) : getDefaultDirectories(cwd).map((path7) => ({
+  const unfilteredTargets = targetResolutions === void 0 ? getDefaultDirectories(cwd).map((path7) => ({
     kind: MARKDOWN_VALIDATION_TARGET_KIND.DIRECTORY,
     path: path7
-  }));
+  })) : targetResolutions.map((resolution) => resolution.target).filter((target) => target !== void 0);
   const targets = unfilteredTargets.filter(
     (target) => pathPassesValidationFilter(relative4(cwd, target.path), pathFilter)
   );
@@ -10794,24 +11338,26 @@ async function markdownCommand(options) {
     projectRoot: cwd
   });
   const durationMs = Date.now() - startTime;
-  if (result.success) {
-    const output = quiet ? "" : [...skippedOutput, MARKDOWN_COMMAND_OUTPUT.NO_ISSUES].join("\n");
-    return { exitCode: 0, output, durationMs };
-  } else {
-    const errorLines = result.errors.map(
-      (error) => `  ${error.file}:${error.line} ${error.detail}`
-    );
-    const output = [
-      ...skippedOutput,
-      `Markdown: ${result.errors.length} ${MARKDOWN_COMMAND_OUTPUT.ERROR_SUMMARY_SUFFIX}`,
-      ...errorLines
-    ].join("\n");
-    return { exitCode: 1, output, durationMs };
-  }
+  return formatMarkdownResult(result, skippedOutput, quiet, durationMs);
 }
 function formatSkippedFileScope(target) {
   return `${MARKDOWN_COMMAND_OUTPUT.SKIPPED_FILE_SCOPE_PREFIX}: ${target.path} (${target.reason})`;
 }
+function formatMarkdownResult(result, skippedOutput, quiet, durationMs) {
+  if (result.success) {
+    const output2 = quiet ? "" : [...skippedOutput, MARKDOWN_COMMAND_OUTPUT.NO_ISSUES].join("\n");
+    return { exitCode: 0, output: output2, durationMs };
+  }
+  const errorLines = result.errors.map(
+    (error) => `  ${error.file}:${error.line} ${error.detail}`
+  );
+  const output = [
+    ...skippedOutput,
+    `Markdown: ${result.errors.length} ${MARKDOWN_COMMAND_OUTPUT.ERROR_SUMMARY_SUFFIX}`,
+    ...errorLines
+  ].join("\n");
+  return { exitCode: 1, output, durationMs };
+}
 
 // src/validation/languages/markdown.ts
 var MARKDOWN_LANGUAGE_NAME = "markdown";
@@ -11687,7 +12233,7 @@ var ParseErrorCode;
 
 // src/validation/config/scope.ts
 import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync3 } from "fs";
-import { isAbsolute as isAbsolute4, join as join26, relative as relative5, resolve as resolve6 } from "path";
+import { isAbsolute as isAbsolute4, join as join26, relative as relative5, resolve as resolve8 } from "path";
 var TSCONFIG_FILES = {
   full: "tsconfig.json",
   production: "tsconfig.production.json"
@@ -11913,7 +12459,7 @@ function globPatternCanMatchInsideDirectory(patternSegments, directorySegments,
       );
     } else {
       const directorySegment = directorySegments[directoryIndex];
-      result = directorySegment !== void 0 && globSegmentMatchesPathSegment(patternSegment, directorySegment) && globPatternCanMatchInsideDirectory(
+      result = globSegmentMatchesPathSegment(patternSegment, directorySegment) && globPatternCanMatchInsideDirectory(
         patternSegments,
         directorySegments,
         patternIndex + 1,
@@ -12061,13 +12607,13 @@ function pathPassesTypeScriptScope(path7, scopeConfig) {
   return included && !excluded;
 }
 function pathStaysInsideTypeScriptScopeRoot(projectRoot, path7) {
-  const resolvedPath = isAbsolute4(path7) ? resolve6(path7) : resolve6(projectRoot, path7);
+  const resolvedPath = isAbsolute4(path7) ? resolve8(path7) : resolve8(projectRoot, path7);
   const relativePath = relative5(projectRoot, resolvedPath);
   const segments = normalizeTypeScriptScopePath(relativePath).split(PATH_SEGMENT_SEPARATOR3);
   return relativePath.length === 0 || !segments.includes("..") && !isAbsolute4(relativePath);
 }
 function toProjectRelativeTypeScriptScopePath(projectRoot, path7) {
-  const resolvedPath = isAbsolute4(path7) ? resolve6(path7) : resolve6(projectRoot, path7);
+  const resolvedPath = isAbsolute4(path7) ? resolve8(path7) : resolve8(projectRoot, path7);
   const relativePath = relative5(projectRoot, resolvedPath);
   return relativePath.length === 0 ? TYPESCRIPT_SCOPE_PROJECT_ROOT : normalizeTypeScriptScopePath(relativePath);
 }
@@ -12303,7 +12849,7 @@ function resolvedModulePath(resolvedPath) {
 }
 function nearestPackageRoot(filePath, existsSync8) {
   let currentDirectory = path6.dirname(filePath);
-  while (true) {
+  for (; ; ) {
     if (existsSync8(path6.join(currentDirectory, PACKAGE_MANIFEST_FILENAME))) {
       return currentDirectory;
     }
@@ -12319,7 +12865,7 @@ function bundledToolPath(resolvedPath, existsSync8) {
   return nearestPackageRoot(bundledFilePath, existsSync8) ?? path6.dirname(bundledFilePath);
 }
 async function discoverTool(tool, options = {}) {
-  const { projectRoot = process.cwd(), deps = defaultToolDiscoveryDeps } = options;
+  const { projectRoot = CONFIG_PROCESS_CWD.read(), deps = defaultToolDiscoveryDeps } = options;
   const bundledPath = deps.resolveModule(`${tool}/package.json`) ?? deps.resolveImport?.(tool);
   if (bundledPath) {
     return {
@@ -12488,7 +13034,7 @@ function dependencyCruiserGlobSegmentToRegExpSource(segment) {
     } else if (character === SINGLE_CHARACTER_GLOB_MARKER) {
       source += `[^${DEPENDENCY_CRUISER_PATH_SEGMENT_SEPARATOR}]`;
     } else {
-      source += character?.replaceAll(LITERAL_REGEX_SPECIAL_CHARACTER_PATTERN, REGEX_ESCAPE_REPLACEMENT2) ?? "";
+      source += character.replaceAll(LITERAL_REGEX_SPECIAL_CHARACTER_PATTERN, REGEX_ESCAPE_REPLACEMENT2);
     }
   }
   return source;
@@ -12534,10 +13080,10 @@ function patternIsCoveredByDirectory(pattern, directories) {
   });
 }
 function isCruiseResult(output) {
-  return typeof output === "object" && output !== null && "modules" in output && "summary" in output;
+  return output !== null && typeof output === "object" && "modules" in output && "summary" in output;
 }
 function closeCycle(cycle) {
-  const first = cycle[0];
+  const first = cycle.at(0);
   const last = cycle.at(-1);
   if (first === void 0) {
     return [];
@@ -12798,13 +13344,13 @@ async function runKnipSubprocess(projectRoot, typescriptScope, runner, deps) {
   knipProcess.stderr?.on("data", (data) => {
     knipError += data.toString();
   });
-  return new Promise((resolve8) => {
+  return new Promise((resolve10) => {
     const resolveAfterCleanup = (result) => {
       if (resultResolved) {
         return;
       }
       resultResolved = true;
-      void cleanupOnce().finally(() => resolve8(result));
+      void cleanupOnce().finally(() => resolve10(result));
     };
     knipProcess.on("close", (code) => {
       if (code === 0) {
@@ -12905,7 +13451,7 @@ import { existsSync as existsSync6 } from "fs";
 import { join as join30 } from "path";
 
 // src/validation/lint-policy.ts
-import { execFileSync } from "child_process";
+import { execFileSync as execFileSync2 } from "child_process";
 import { existsSync as existsSync5, readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
 import { join as join29 } from "path";
 
@@ -13020,7 +13566,7 @@ function readBaselineManifest(productDir, file, key) {
   }
   let content;
   try {
-    content = execFileSync("git", ["show", `${baselineRef}:${file}`], {
+    content = execFileSync2("git", ["show", `${baselineRef}:${file}`], {
       cwd: productDir,
       encoding: "utf-8",
       env: withoutGitEnvironment(process.env),
@@ -13060,7 +13606,7 @@ function readMergeBase(productDir, baseBranchRef) {
 }
 function readGitRef(productDir, args) {
   try {
-    const output = execFileSync("git", [...args], {
+    const output = execFileSync2("git", [...args], {
       cwd: productDir,
       encoding: "utf-8",
       env: withoutGitEnvironment(process.env),
@@ -13222,7 +13768,7 @@ async function validateESLint(context, runner = defaultEslintProcessRunner, outp
     scope: scope2,
     scopeConfig: context.scopeConfig
   });
-  return new Promise((resolve8) => {
+  return new Promise((resolve10) => {
     const localBin = join30(projectRoot, ...ESLINT_LOCAL_BIN_SEGMENTS);
     const binary = existsSync6(localBin) ? localBin : "npx";
     const spawnArgs = binary === "npx" ? eslintArgs : eslintArgs.slice(1);
@@ -13232,13 +13778,13 @@ async function validateESLint(context, runner = defaultEslintProcessRunner, outp
     forwardValidationSubprocessOutput(eslintProcess, outputStreams);
     eslintProcess.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
       if (code === 0) {
-        resolve8({ success: true });
+        resolve10({ success: true });
       } else {
-        resolve8({ success: false, error: `ESLint exited with code ${code}` });
+        resolve10({ success: false, error: `ESLint exited with code ${code}` });
       }
     });
     eslintProcess.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
-      resolve8({ success: false, error: error.message });
+      resolve10({ success: false, error: error.message });
     });
   });
 }
@@ -13311,21 +13857,24 @@ async function lintCommand(options) {
   };
   const result = await validateESLint(context, void 0, outputStreams);
   const durationMs = Date.now() - startTime;
+  return formatLintResult(result, quiet, durationMs);
+}
+function formatLintResult(result, quiet, durationMs) {
   if (result.skipped) {
-    const output = quiet ? "" : VALIDATION_PATHS_NO_TARGETS_MESSAGE;
-    return { exitCode: 0, output, durationMs };
-  } else if (result.success) {
-    const output = quiet ? "" : VALIDATION_COMMAND_OUTPUT.ESLINT_SUCCESS;
-    return { exitCode: 0, output, durationMs };
-  } else {
-    const output = result.error ?? VALIDATION_COMMAND_OUTPUT.ESLINT_FAILURE;
-    return { exitCode: 1, output, durationMs };
+    const output2 = quiet ? "" : VALIDATION_PATHS_NO_TARGETS_MESSAGE;
+    return { exitCode: 0, output: output2, durationMs };
   }
+  if (result.success) {
+    const output2 = quiet ? "" : VALIDATION_COMMAND_OUTPUT.ESLINT_SUCCESS;
+    return { exitCode: 0, output: output2, durationMs };
+  }
+  const output = result.error ?? VALIDATION_COMMAND_OUTPUT.ESLINT_FAILURE;
+  return { exitCode: 1, output, durationMs };
 }
 
 // src/validation/literal/index.ts
 import { readFile as readFile9 } from "fs/promises";
-import { isAbsolute as isAbsolute6, relative as relative7, resolve as resolve7 } from "path";
+import { isAbsolute as isAbsolute6, relative as relative7, resolve as resolve9 } from "path";
 
 // src/lib/file-inclusion/predicates/ignore-source.ts
 var IGNORE_SOURCE_LAYER = "ignore-source";
@@ -13409,22 +13958,33 @@ async function runPipeline(sequence, projectRoot, request, config, ignoreReader)
     await collectPaths(request.walkRoot, projectRoot, allPaths, artifactDirs);
     for (const path7 of allPaths) {
       if (explicitPathSet.has(path7)) continue;
-      const trail = [];
-      for (const { entry, layerConfig } of layerPairs) {
-        const decision = entry.predicate(path7, layerConfig);
-        if (decision.matched) {
-          trail.push(decision);
-        }
-      }
-      if (trail.length > 0) {
-        excluded.push({ path: path7, decisionTrail: trail });
+      const classified = classifyPath(path7, layerPairs);
+      if (classified.excluded) {
+        excluded.push(classified.entry);
       } else {
-        included.push({ path: path7, decisionTrail: [] });
+        included.push(classified.entry);
       }
     }
   }
   return { included, excluded };
 }
+function classifyPath(path7, layerPairs) {
+  const trail = decisionTrailForPath(path7, layerPairs);
+  return {
+    excluded: trail.length > 0,
+    entry: { path: path7, decisionTrail: trail }
+  };
+}
+function decisionTrailForPath(path7, layerPairs) {
+  const trail = [];
+  for (const { entry, layerConfig } of layerPairs) {
+    const decision = entry.predicate(path7, layerConfig);
+    if (decision.matched) {
+      trail.push(decision);
+    }
+  }
+  return trail;
+}
 
 // src/validation/literal/detector.ts
 import { parse as parseTypeScript } from "@typescript-eslint/parser";
@@ -13485,7 +14045,12 @@ var FIXTURE_DATA_ROLE_SEGMENTS = /* @__PURE__ */ new Set([
   "source"
 ]);
 var FIXTURE_DATA_CONTEXT_SEGMENTS = /* @__PURE__ */ new Set(["path", "tree"]);
-var IDENTIFIER_SEGMENT_PATTERN = /[A-Z]+(?=[A-Z][a-z]|$)|[A-Z]?[a-z]+|[0-9]+/g;
+var IDENTIFIER_CHAR_KIND = {
+  UPPER: "upper",
+  LOWER: "lower",
+  DIGIT: "digit",
+  OTHER: "other"
+};
 function collectLiterals(source, filename, options) {
   const ast = parseTypeScript(source, {
     loc: true,
@@ -13539,26 +14104,28 @@ function emitLiteral(node, context, ancestors, options, out) {
   }
   const line = node.loc?.start?.line ?? 0;
   if (node.type === LITERAL_TYPE) {
-    if (typeof node.value === "string") {
-      if (node.value.length >= options.minStringLength) {
-        out.push({ kind: "string", value: node.value, loc: { file: context.filename, line } });
-      }
-    } else if (typeof node.value === "number") {
-      const raw = typeof node.raw === "string" ? node.raw : String(node.value);
-      if (isMeaningfulNumber(raw, options.minNumberDigits)) {
-        out.push({ kind: "number", value: String(node.value), loc: { file: context.filename, line } });
-      }
-    }
+    emitEstreeLiteral(node, context, line, options, out);
     return;
   }
-  if (node.type === TEMPLATE_ELEMENT_TYPE) {
-    const value = node.value;
-    const cooked = value?.cooked ?? "";
-    if (cooked.length >= options.minStringLength) {
-      out.push({ kind: "string", value: cooked, loc: { file: context.filename, line } });
+  emitTemplateElementLiteral(node, context, line, options, out);
+}
+function emitEstreeLiteral(node, context, line, options, out) {
+  if (typeof node.value === "string" && node.value.length >= options.minStringLength) {
+    out.push({ kind: "string", value: node.value, loc: { file: context.filename, line } });
+  } else if (typeof node.value === "number") {
+    const raw = typeof node.raw === "string" ? node.raw : String(node.value);
+    if (isMeaningfulNumber(raw, options.minNumberDigits)) {
+      out.push({ kind: "number", value: String(node.value), loc: { file: context.filename, line } });
     }
   }
 }
+function emitTemplateElementLiteral(node, context, line, options, out) {
+  const value = node.value;
+  const cooked = value?.cooked ?? "";
+  if (cooked.length >= options.minStringLength) {
+    out.push({ kind: "string", value: cooked, loc: { file: context.filename, line } });
+  }
+}
 function isTestLikeFile(filename) {
   return filename.includes(TEST_PATH_SEGMENT) || filename.includes(WINDOWS_TEST_PATH_SEGMENT) || filename.includes(TEST_FILE_MARKER);
 }
@@ -13620,7 +14187,7 @@ function getFixtureDataDeclaratorName(node) {
   return getIdentifierName(node.init);
 }
 function isFixtureDataVariableName(variableName) {
-  const segments = splitIdentifierName(variableName);
+  const segments = fixtureClassificationSegments(variableName);
   if (segments.length === 0) {
     return false;
   }
@@ -13633,11 +14200,92 @@ function isFixtureDataVariableName(variableName) {
   if (segments.every((segment) => FIXTURE_DATA_ROLE_SEGMENTS.has(segment))) {
     return true;
   }
-  const finalSegment = segments[segments.length - 1];
+  const finalSegment = segments.at(-1);
   return finalSegment !== void 0 && FIXTURE_DATA_CONTEXT_SEGMENTS.has(finalSegment);
 }
 function splitIdentifierName(variableName) {
-  return variableName.split("_").flatMap((part) => part.match(IDENTIFIER_SEGMENT_PATTERN) ?? []).map((segment) => segment.toLowerCase());
+  return variableName.split("_").flatMap(splitIdentifierPart).map((segment) => segment.toLowerCase());
+}
+function fixtureClassificationSegments(variableName) {
+  const segments = splitIdentifierName(variableName);
+  if (!isScreamingSnakeIdentifier(variableName)) {
+    return segments;
+  }
+  let first = 0;
+  let last = segments.length;
+  while (first < last && isSingleLetterSegment(segments[first])) {
+    first += 1;
+  }
+  while (last > first && isSingleLetterSegment(segments[last - 1])) {
+    last -= 1;
+  }
+  return segments.slice(first, last);
+}
+function isScreamingSnakeIdentifier(variableName) {
+  return variableName.includes("_") && variableName.split("_").every((part) => part !== "" && part === part.toUpperCase() && part !== part.toLowerCase());
+}
+function isSingleLetterSegment(segment) {
+  return segment.length === 1 && classifyIdentifierCharacter(segment) === IDENTIFIER_CHAR_KIND.LOWER;
+}
+function splitIdentifierPart(identifierPart) {
+  const segments = [];
+  let currentSegment = "";
+  for (const character of identifierPart) {
+    const kind = classifyIdentifierCharacter(character);
+    if (kind === IDENTIFIER_CHAR_KIND.OTHER) {
+      pushIdentifierSegment(segments, currentSegment);
+      currentSegment = "";
+      continue;
+    }
+    if (currentSegment === "") {
+      currentSegment = character;
+      continue;
+    }
+    if (startsNewIdentifierSegment(currentSegment, kind)) {
+      currentSegment = startNextIdentifierSegment(segments, currentSegment, character, kind);
+      continue;
+    }
+    currentSegment = `${currentSegment}${character}`;
+  }
+  pushIdentifierSegment(segments, currentSegment);
+  return segments;
+}
+function startNextIdentifierSegment(segments, currentSegment, character, kind) {
+  if (kind === IDENTIFIER_CHAR_KIND.DIGIT && isUppercaseSegment(currentSegment)) {
+    return character;
+  }
+  if (kind === IDENTIFIER_CHAR_KIND.LOWER && isUppercaseRun(currentSegment)) {
+    const prefix = currentSegment.slice(0, -1);
+    pushIdentifierSegment(segments, prefix);
+    return `${currentSegment.at(-1) ?? ""}${character}`;
+  }
+  pushIdentifierSegment(segments, currentSegment);
+  return character;
+}
+function classifyIdentifierCharacter(character) {
+  if (character >= "0" && character <= "9") return IDENTIFIER_CHAR_KIND.DIGIT;
+  const lower = character.toLowerCase();
+  const upper = character.toUpperCase();
+  if (lower === upper) return IDENTIFIER_CHAR_KIND.OTHER;
+  return character === upper ? IDENTIFIER_CHAR_KIND.UPPER : IDENTIFIER_CHAR_KIND.LOWER;
+}
+function startsNewIdentifierSegment(currentSegment, nextKind) {
+  const currentKind = classifyIdentifierCharacter(currentSegment.at(-1) ?? "");
+  if (nextKind === IDENTIFIER_CHAR_KIND.DIGIT) return currentKind !== IDENTIFIER_CHAR_KIND.DIGIT;
+  if (currentKind === IDENTIFIER_CHAR_KIND.DIGIT) return true;
+  if (nextKind === IDENTIFIER_CHAR_KIND.UPPER) return currentKind === IDENTIFIER_CHAR_KIND.LOWER;
+  return currentKind === IDENTIFIER_CHAR_KIND.UPPER && isUppercaseRun(currentSegment);
+}
+function isUppercaseRun(value) {
+  return value.length > 1 && Array.from(value).every((character) => classifyIdentifierCharacter(character) === IDENTIFIER_CHAR_KIND.UPPER);
+}
+function isUppercaseSegment(value) {
+  return Array.from(value).every((character) => classifyIdentifierCharacter(character) === IDENTIFIER_CHAR_KIND.UPPER);
+}
+function pushIdentifierSegment(segments, segment) {
+  if (segment !== "") {
+    segments.push(segment);
+  }
 }
 function getCallName(node) {
   const callee = node.callee;
@@ -13669,7 +14317,7 @@ function getLiteralString(value) {
   return typeof value.value === "string" ? value.value : void 0;
 }
 function isMeaningfulNumber(raw, minDigits) {
-  const digits = raw.replace(/[^0-9]/g, "");
+  const digits = raw.replaceAll(/\D/g, "");
   return digits.length >= minDigits;
 }
 function buildIndex(occurrences) {
@@ -13695,51 +14343,59 @@ function splitKey(key) {
 function detectReuse(input) {
   const srcReuse = [];
   const testDupe = [];
-  const testIndex = /* @__PURE__ */ new Map();
-  for (const [file, occurrences] of input.testOccurrencesByFile) {
-    for (const occ of occurrences) {
-      if (input.allowlist.has(occ.value)) continue;
-      const key = makeKey(occ.kind, occ.value);
-      let byFile = testIndex.get(key);
-      if (!byFile) {
-        byFile = /* @__PURE__ */ new Map();
-        testIndex.set(key, byFile);
-      }
-      const locsInFile = byFile.get(file);
-      if (locsInFile) locsInFile.push(occ.loc);
-      else byFile.set(file, [occ.loc]);
-    }
-  }
+  const testIndex = buildTestOccurrenceIndex(input.testOccurrencesByFile, input.allowlist);
   for (const [key, byFile] of testIndex) {
     const { kind, value } = splitKey(key);
     const srcLocs = input.srcIndex.get(key);
     const allTestLocs = [];
     for (const locs of byFile.values()) allTestLocs.push(...locs);
     if (srcLocs && srcLocs.length > 0) {
-      for (const testLoc of allTestLocs) {
-        srcReuse.push({
-          test: testLoc,
-          kind,
-          value,
-          src: srcLocs,
-          remediation: REMEDIATION6.IMPORT_FROM_SOURCE
-        });
-      }
+      srcReuse.push(...reuseFindings(kind, value, srcLocs, allTestLocs));
     } else if (byFile.size >= 2) {
-      for (let i = 0; i < allTestLocs.length; i += 1) {
-        const otherTests = [...allTestLocs.slice(0, i), ...allTestLocs.slice(i + 1)];
-        testDupe.push({
-          test: allTestLocs[i],
-          kind,
-          value,
-          otherTests,
-          remediation: REMEDIATION6.REFACTOR_TO_SOURCE_OR_GENERATOR
-        });
-      }
+      testDupe.push(...dupeFindings(kind, value, allTestLocs));
     }
   }
   return { srcReuse, testDupe };
 }
+function buildTestOccurrenceIndex(occurrencesByFile, allowlist) {
+  const testIndex = /* @__PURE__ */ new Map();
+  for (const [file, occurrences] of occurrencesByFile) {
+    for (const occ of occurrences) {
+      if (allowlist.has(occ.value)) continue;
+      addTestOccurrence(testIndex, file, occ);
+    }
+  }
+  return testIndex;
+}
+function addTestOccurrence(testIndex, file, occurrence) {
+  const key = makeKey(occurrence.kind, occurrence.value);
+  let byFile = testIndex.get(key);
+  if (!byFile) {
+    byFile = /* @__PURE__ */ new Map();
+    testIndex.set(key, byFile);
+  }
+  const locsInFile = byFile.get(file);
+  if (locsInFile) locsInFile.push(occurrence.loc);
+  else byFile.set(file, [occurrence.loc]);
+}
+function reuseFindings(kind, value, srcLocs, allTestLocs) {
+  return allTestLocs.map((testLoc) => ({
+    test: testLoc,
+    kind,
+    value,
+    src: srcLocs,
+    remediation: REMEDIATION6.IMPORT_FROM_SOURCE
+  }));
+}
+function dupeFindings(kind, value, allTestLocs) {
+  return allTestLocs.map((test, index) => ({
+    test,
+    kind,
+    value,
+    otherTests: [...allTestLocs.slice(0, index), ...allTestLocs.slice(index + 1)],
+    remediation: REMEDIATION6.REFACTOR_TO_SOURCE_OR_GENERATOR
+  }));
+}
 
 // src/validation/literal/walker.ts
 var TYPESCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx"]);
@@ -13788,7 +14444,7 @@ async function validateLiteralReuse(input) {
   const config = input.config ?? literalConfigDescriptor.defaults;
   const request = input.files ? {
     explicit: input.files.map((f) => {
-      const abs = isAbsolute6(f) ? f : resolve7(input.productDir, f);
+      const abs = isAbsolute6(f) ? f : resolve9(input.productDir, f);
       return relative7(input.productDir, abs).split(/[\\/]/g).join("/");
     })
   } : { walkRoot: input.productDir };
@@ -13800,7 +14456,7 @@ async function validateLiteralReuse(input) {
     EMPTY_IGNORE_READER
   );
   const filtered = applyPathFilter2(scope2.included, input.pathConfig);
-  const candidateFiles = filtered.filter((entry) => isTypescriptSource(entry.path)).map((entry) => resolve7(input.productDir, entry.path));
+  const candidateFiles = filtered.filter((entry) => isTypescriptSource(entry.path)).map((entry) => resolve9(input.productDir, entry.path));
   const collectOptions = {
     visitorKeys: defaultVisitorKeys,
     minStringLength: config.minStringLength,
@@ -14083,12 +14739,7 @@ async function createFileSpecificTsconfig(scope2, files, projectRoot, deps = def
     compilerOptions: TEMPORARY_TSCONFIG_COMPILER_OPTIONS
   };
   deps.writeFileSync(configPath, JSON.stringify(tempConfig, null, 2));
-  const cleanup = () => {
-    try {
-      deps.rmSync(tempDir, { recursive: true, force: true });
-    } catch {
-    }
-  };
+  const cleanup = createTemporaryTsconfigCleanup(tempDir, deps);
   return { configPath, tempDir, cleanup };
 }
 async function createScopeFilteredTsconfig(scope2, projectRoot, scopeConfig, deps = defaultTypeScriptDeps) {
@@ -14103,13 +14754,16 @@ async function createScopeFilteredTsconfig(scope2, projectRoot, scopeConfig, dep
     compilerOptions: TEMPORARY_TSCONFIG_COMPILER_OPTIONS
   };
   deps.writeFileSync(configPath, JSON.stringify(tempConfig, null, 2));
-  const cleanup = () => {
+  const cleanup = createTemporaryTsconfigCleanup(tempDir, deps);
+  return { configPath, tempDir, cleanup };
+}
+function createTemporaryTsconfigCleanup(tempDir, deps) {
+  return () => {
     try {
       deps.rmSync(tempDir, { recursive: true, force: true });
     } catch {
     }
   };
-  return { configPath, tempDir, cleanup };
 }
 async function validateTypeScript(context, options = {}) {
   const { scope: scope2, projectRoot, files, scopeConfig } = context;
@@ -14119,32 +14773,16 @@ async function validateTypeScript(context, options = {}) {
     outputStreams = defaultValidationSubprocessOutputStreams
   } = options;
   const configFile = TSCONFIG_FILES[scope2];
-  let tool;
-  let tscArgs;
   if (files && files.length > 0) {
     const { configPath, cleanup } = await createFileSpecificTsconfig(scope2, files, projectRoot, deps);
     try {
-      return await new Promise((resolve8) => {
-        const tscBin = join32(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, {
-          cwd: projectRoot
-        });
-        forwardValidationSubprocessOutput(tscProcess, outputStreams);
-        tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
-          cleanup();
-          if (code === 0) {
-            resolve8({ success: true, skipped: false });
-          } else {
-            resolve8({ success: false, error: `TypeScript exited with code ${code}` });
-          }
-        });
-        tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
-          cleanup();
-          resolve8({ success: false, error: error.message });
-        });
-      });
+      return await runTypeScriptInvocation(
+        projectRoot,
+        resolveProjectTscInvocation(projectRoot, deps, ["--project", configPath]),
+        runner,
+        outputStreams,
+        cleanup
+      );
     } catch (error) {
       cleanup();
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -14158,47 +14796,47 @@ async function validateTypeScript(context, options = {}) {
       return { success: true, skipped: true };
     }
     const { configPath, cleanup } = await createScopeFilteredTsconfig(scope2, projectRoot, scopeConfig, deps);
-    const tscBin = join32(projectRoot, "node_modules", ".bin", "tsc");
-    tool = deps.existsSync(tscBin) ? tscBin : "npx";
-    tscArgs = tool === "npx" ? ["tsc", "--project", configPath] : ["--project", configPath];
-    return new Promise((resolve8) => {
-      const tscProcess = spawnManagedSubprocess(runner, tool, tscArgs, {
-        cwd: projectRoot
-      });
-      forwardValidationSubprocessOutput(tscProcess, outputStreams);
-      tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
-        cleanup();
-        if (code === 0) {
-          resolve8({ success: true, skipped: false });
-        } else {
-          resolve8({ success: false, error: `TypeScript exited with code ${code}` });
-        }
-      });
-      tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
-        cleanup();
-        resolve8({ success: false, error: error.message });
-      });
-    });
-  } else {
-    const tscBin = join32(projectRoot, "node_modules", ".bin", "tsc");
-    tool = deps.existsSync(tscBin) ? tscBin : "npx";
-    const rawArgs = buildTypeScriptArgs({ scope: scope2, configFile });
-    tscArgs = tool === "npx" ? rawArgs : rawArgs.slice(1);
+    return runTypeScriptInvocation(
+      projectRoot,
+      resolveProjectTscInvocation(projectRoot, deps, ["--project", configPath]),
+      runner,
+      outputStreams,
+      cleanup
+    );
   }
-  return new Promise((resolve8) => {
-    const tscProcess = spawnManagedSubprocess(runner, tool, tscArgs, {
+  return runTypeScriptInvocation(
+    projectRoot,
+    resolveProjectTscInvocation(projectRoot, deps, buildTypeScriptArgs({ scope: scope2, configFile }).slice(1)),
+    runner,
+    outputStreams
+  );
+}
+function resolveProjectTscInvocation(projectRoot, deps, tscArgs) {
+  const tscBin = join32(projectRoot, "node_modules", ".bin", "tsc");
+  const tool = deps.existsSync(tscBin) ? tscBin : "npx";
+  return {
+    tool,
+    args: tool === "npx" ? ["tsc", ...tscArgs] : tscArgs
+  };
+}
+function runTypeScriptInvocation(projectRoot, invocation, runner, outputStreams, cleanup = () => {
+}) {
+  return new Promise((resolve10) => {
+    const tscProcess = spawnManagedSubprocess(runner, invocation.tool, invocation.args, {
       cwd: projectRoot
     });
     forwardValidationSubprocessOutput(tscProcess, outputStreams);
     tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.CLOSE, (code) => {
+      cleanup();
       if (code === 0) {
-        resolve8({ success: true, skipped: false });
+        resolve10({ success: true, skipped: false });
       } else {
-        resolve8({ success: false, error: `TypeScript exited with code ${code}` });
+        resolve10({ success: false, error: `TypeScript exited with code ${code}` });
       }
     });
     tscProcess.on(VALIDATION_SUBPROCESS_EVENTS.ERROR, (error) => {
-      resolve8({ success: false, error: error.message });
+      cleanup();
+      resolve10({ success: false, error: error.message });
     });
   });
 }
@@ -14259,16 +14897,19 @@ async function typescriptCommand(options) {
     scopeConfig
   });
   const durationMs = Date.now() - startTime;
+  return formatTypeScriptResult(result, quiet, durationMs);
+}
+function formatTypeScriptResult(result, quiet, durationMs) {
   if (result.skipped) {
-    const output = quiet ? "" : TYPESCRIPT_VALIDATION_MESSAGES.NO_VALIDATION_PATH_TARGETS;
-    return { exitCode: 0, output, durationMs };
-  } else if (result.success) {
-    const output = quiet ? "" : TYPESCRIPT_VALIDATION_MESSAGES.SUCCESS;
-    return { exitCode: 0, output, durationMs };
-  } else {
-    const output = result.error ?? VALIDATION_COMMAND_OUTPUT.TYPESCRIPT_FAILURE;
-    return { exitCode: 1, output, durationMs };
+    const output2 = quiet ? "" : TYPESCRIPT_VALIDATION_MESSAGES.NO_VALIDATION_PATH_TARGETS;
+    return { exitCode: 0, output: output2, durationMs };
+  }
+  if (result.success) {
+    const output2 = quiet ? "" : TYPESCRIPT_VALIDATION_MESSAGES.SUCCESS;
+    return { exitCode: 0, output: output2, durationMs };
   }
+  const output = result.error ?? VALIDATION_COMMAND_OUTPUT.TYPESCRIPT_FAILURE;
+  return { exitCode: 1, output, durationMs };
 }
 
 // src/validation/languages/typescript.ts
@@ -14425,7 +15066,7 @@ async function allCommand(options) {
 // src/validation/literal/allowlist-existing.ts
 import { randomBytes } from "crypto";
 import { rename as rename4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname9, join as join33 } from "path";
+import { dirname as dirname10, join as join33 } from "path";
 var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var INCLUDE_FIELD = "include";
@@ -14443,7 +15084,7 @@ var productionReader = {
 };
 var productionWriter = {
   async write(filePath, content) {
-    const dir = dirname9(filePath);
+    const dir = dirname10(filePath);
     const random = randomBytes(RANDOM_TOKEN_BYTES).toString("hex");
     const tmpPath = join33(dir, `${TEMP_FILE_PREFIX}${random}${TEMP_FILE_SUFFIX}`);
     await writeFile4(tmpPath, content, "utf8");
@@ -14620,6 +15261,13 @@ var validationKnownOperands = /* @__PURE__ */ new Set([
   ...Object.values(validationCliDefinition.commanderHelpOperands)
 ]);
 var validationOptionPrefix = validationCliDefinition.commanderHelpOperands.longFlag.slice(0, 1);
+function emitValidationResult(result, io) {
+  if (result.output.length > 0) {
+    io.writeStdout(`${result.output}
+`);
+  }
+  return io.exit(result.exitCode);
+}
 function addCommonOptions(cmd) {
   return cmd.option("--scope <scope>", "Validation scope (full|production)", "full").option("--files <paths...>", "Specific files/directories to validate").option("--quiet", "Suppress progress output").option("--json", "Output results as JSON");
 }
@@ -14630,55 +15278,52 @@ function addValidationSubcommand(validationCmd, definition) {
   }
   return subcommand;
 }
-function registerValidationCommands(validationCmd) {
+function registerValidationCommands(validationCmd, invocation) {
   const { subcommands } = validationCliDefinition;
+  const productDir = () => invocation.resolveProductContext().productDir;
   const tsCmd = addValidationSubcommand(validationCmd, subcommands.typescript).action(async (options) => {
     const result = await typescriptCommand({
-      cwd: process.cwd(),
+      cwd: productDir(),
       scope: options.scope,
       files: options.files,
       quiet: options.quiet,
       json: options.json
     });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
+    emitValidationResult(result, invocation.io);
   });
   addCommonOptions(tsCmd);
   const lintCmd = addValidationSubcommand(validationCmd, subcommands.lint).option("--fix", "Auto-fix issues").action(async (options) => {
     const result = await lintCommand({
-      cwd: process.cwd(),
+      cwd: productDir(),
       scope: options.scope,
       files: options.files,
       fix: options.fix,
       quiet: options.quiet,
       json: options.json
     });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
+    emitValidationResult(result, invocation.io);
   });
   addCommonOptions(lintCmd);
   const circularCmd = addValidationSubcommand(validationCmd, subcommands.circular).action(async (options) => {
     const result = await circularCommand({
-      cwd: process.cwd(),
+      cwd: productDir(),
       scope: options.scope,
       files: options.files,
       quiet: options.quiet,
       json: options.json
     });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
+    emitValidationResult(result, invocation.io);
   });
   addCommonOptions(circularCmd);
   const knipCmd = addValidationSubcommand(validationCmd, subcommands.knip).action(async (options) => {
     const result = await knipCommand({
-      cwd: process.cwd(),
+      cwd: productDir(),
       scope: options.scope,
       files: options.files,
       quiet: options.quiet,
       json: options.json
     });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
+    emitValidationResult(result, invocation.io);
   });
   addCommonOptions(knipCmd);
   const literalCmd = addValidationSubcommand(validationCmd, subcommands.literal).option(
@@ -14692,24 +15337,23 @@ function registerValidationCommands(validationCmd) {
     "\nEnabled for TypeScript projects by default. Set validation.literal.enabled=false\nin spx.config.* to skip during migration."
   ).action(async (options) => {
     if (options.allowlistExisting) {
-      const result2 = await allowlistExisting({ productDir: process.cwd() });
-      if (result2.output) console.log(result2.output);
-      process.exit(result2.exitCode);
+      const result2 = await allowlistExisting({ productDir: productDir() });
+      emitValidationResult(result2, invocation.io);
     }
     let kind;
     if (options.kind !== void 0) {
       kind = parseLiteralProblemKind(options.kind);
       if (kind === void 0) {
         const { unknownLiteralProblemKind } = validationCliDefinition.diagnostics;
-        process.stderr.write(
+        invocation.io.writeStderr(
           `spx validation literal: ${unknownLiteralProblemKind.messageLabel}: ${sanitizeCliArgument(options.kind)}
 `
         );
-        process.exit(unknownLiteralProblemKind.exitCode);
+        invocation.io.exit(unknownLiteralProblemKind.exitCode);
       }
     }
     const result = await literalCommand({
-      cwd: process.cwd(),
+      cwd: productDir(),
       files: options.files,
       kind,
       filesWithProblems: options.filesWithProblems,
@@ -14718,8 +15362,7 @@ function registerValidationCommands(validationCmd) {
       quiet: options.quiet,
       json: options.json
     });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
+    emitValidationResult(result, invocation.io);
   });
   addCommonOptions(literalCmd);
   const markdownCmd = addValidationSubcommand(validationCmd, subcommands.markdown).addHelpText(
@@ -14727,27 +15370,25 @@ function registerValidationCommands(validationCmd) {
     "\nValidates spx/ and docs/ by default. Nodes listed in spx/EXCLUDE are\nskipped \u2014 use this for declared-state nodes whose [test] links point\nto files that do not exist yet."
   ).action(async (options) => {
     const result = await markdownCommand({
-      cwd: process.cwd(),
+      cwd: productDir(),
       files: options.files,
       quiet: options.quiet
     });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
+    emitValidationResult(result, invocation.io);
   });
   addCommonOptions(markdownCmd);
   const formatCmd = addValidationSubcommand(validationCmd, subcommands.format).action(async (options) => {
     const result = await formattingCommand({
-      cwd: process.cwd(),
+      cwd: productDir(),
       files: options.files,
       quiet: options.quiet
     });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
+    emitValidationResult(result, invocation.io);
   });
   addCommonOptions(formatCmd);
   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(),
+      cwd: productDir(),
       scope: options.scope,
       files: options.files,
       fix: options.fix,
@@ -14756,8 +15397,7 @@ function registerValidationCommands(validationCmd) {
       quiet: options.quiet,
       json: options.json
     });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
+    emitValidationResult(result, invocation.io);
   });
   addCommonOptions(allCmd);
 }
@@ -14767,25 +15407,264 @@ function parseLiteralProblemKind(value) {
   }
   return void 0;
 }
-function handleUnknownSubcommand(operands) {
+function handleUnknownSubcommand(operands, io) {
   const [first] = operands;
   const sanitized = sanitizeCliArgument(first);
   const { domain, diagnostics } = validationCliDefinition;
   const { unknownSubcommand } = diagnostics;
-  process.stderr.write(`spx ${domain.commandName}: ${unknownSubcommand.messageLabel}: ${sanitized}
+  io.writeStderr(`spx ${domain.commandName}: ${unknownSubcommand.messageLabel}: ${sanitized}
 `);
-  process.exit(unknownSubcommand.exitCode);
+  return io.exit(unknownSubcommand.exitCode);
 }
 var validationDomain = {
   name: validationCliDefinition.domain.commandName,
   description: validationCliDefinition.domain.description,
-  register: (program2) => {
+  register: (program, invocation) => {
     const { domain } = validationCliDefinition;
-    const validationCmd = program2.command(domain.commandName).alias(domain.alias).description(domain.description);
+    const validationCmd = program.command(domain.commandName).alias(domain.alias).description(domain.description);
     validationCmd.on("command:*", (operands) => {
-      handleUnknownSubcommand(operands);
+      handleUnknownSubcommand(operands, invocation.io);
+    });
+    registerValidationCommands(validationCmd, invocation);
+  }
+};
+
+// src/commands/verification-context/cli.ts
+import { isAbsolute as isAbsolute8, win32 } from "path";
+
+// src/domains/verification-context/context.ts
+var VERIFICATION_CONTEXT_SCHEMA_VERSION = "verification-context.v1";
+var VERIFICATION_CONTEXT_SUBJECT_KIND = {
+  FILE: "file",
+  CHANGESET: "changeset"
+};
+var VERIFICATION_CONTEXT_PERSISTENCE = {
+  kind: "state-store",
+  scope: "branch",
+  domain: "verification-context",
+  format: "canonical-json"
+};
+var VERIFICATION_CONTEXT_DIGEST_PATH = "verification context";
+function createVerificationContextDocument(payload) {
+  const digest = digestDescriptorSection(payload, VERIFICATION_CONTEXT_DIGEST_PATH);
+  if (!digest.ok) return digest;
+  const document = {
+    digest: digest.value.sha256,
+    context: payload
+  };
+  const canonical = canonicalDescriptorJson(document, VERIFICATION_CONTEXT_DIGEST_PATH);
+  if (!canonical.ok) return canonical;
+  return {
+    ok: true,
+    value: {
+      ...document,
+      canonicalJson: canonical.value
+    }
+  };
+}
+
+// src/commands/verification-context/runtime.ts
+import { dirname as dirname11 } from "path";
+
+// src/domains/verification-context/path.ts
+import { join as join34 } from "path";
+var VERIFICATION_CONTEXT_STATE_DOMAIN = VERIFICATION_CONTEXT_PERSISTENCE.domain;
+var VERIFICATION_CONTEXT_STATE_PATH = {
+  CONTEXTS_DIR: "contexts",
+  FILE_PREFIX: "context-",
+  JSON_EXTENSION: ".json"
+};
+function verificationContextFileName(digest) {
+  return `${VERIFICATION_CONTEXT_STATE_PATH.FILE_PREFIX}${digest}${VERIFICATION_CONTEXT_STATE_PATH.JSON_EXTENSION}`;
+}
+function verificationContextFilePath(scope2) {
+  const branchScope = branchScopeDir(scope2.productDir, scope2.branchSlug);
+  if (!branchScope.ok) return branchScope;
+  const contextsDir = composeScopeDir(
+    branchScope.value,
+    VERIFICATION_CONTEXT_STATE_DOMAIN,
+    VERIFICATION_CONTEXT_STATE_PATH.CONTEXTS_DIR
+  );
+  if (!contextsDir.ok) return contextsDir;
+  const digest = validateScopeToken(scope2.digest);
+  if (!digest.ok) return digest;
+  return { ok: true, value: join34(contextsDir.value, verificationContextFileName(digest.value)) };
+}
+
+// src/commands/verification-context/runtime.ts
+var VERIFICATION_CONTEXT_RUNTIME_ERROR = {
+  READ_FAILED: "verification context read failed",
+  WRITE_FAILED: "verification context write failed",
+  CONTENT_MISMATCH: "verification context already exists with different content"
+};
+async function persistVerificationContext(scope2, document, options = {}) {
+  const contextPath = verificationContextFilePath(scope2);
+  if (!contextPath.ok) return contextPath;
+  const fs8 = options.fs ?? defaultFileSystem;
+  try {
+    await fs8.mkdir(dirname11(contextPath.value), { recursive: true });
+    await fs8.writeFile(contextPath.value, document.canonicalJson, { flag: EXCLUSIVE_CREATE_FLAG });
+  } catch (error) {
+    if (hasErrorCode(error, ERROR_CODE_FILE_EXISTS)) {
+      const existing = await readExistingContext(fs8, contextPath.value);
+      if (!existing.ok) return existing;
+      if (existing.value === document.canonicalJson) {
+        return { ok: true, value: { digest: document.digest, contextPath: contextPath.value } };
+      }
+      return { ok: false, error: VERIFICATION_CONTEXT_RUNTIME_ERROR.CONTENT_MISMATCH };
+    }
+    return { ok: false, error: `${VERIFICATION_CONTEXT_RUNTIME_ERROR.WRITE_FAILED}: ${toMessage(error)}` };
+  }
+  return { ok: true, value: { digest: document.digest, contextPath: contextPath.value } };
+}
+async function readExistingContext(fs8, contextPath) {
+  try {
+    return { ok: true, value: await fs8.readFile(contextPath, STATE_STORE_TEXT_ENCODING) };
+  } catch (error) {
+    return { ok: false, error: `${VERIFICATION_CONTEXT_RUNTIME_ERROR.READ_FAILED}: ${toMessage(error)}` };
+  }
+}
+
+// src/commands/verification-context/cli.ts
+var VERIFICATION_CONTEXT_CLI_EXIT_CODE = {
+  OK: 0,
+  ERROR: 1
+};
+var VERIFICATION_CONTEXT_CLI_ENV = {
+  BRANCH: SPX_VERIFY_ENV.BRANCH
+};
+var VERIFICATION_CONTEXT_CLI_ERROR = {
+  INVALID_SUBJECT: "verification context subject must be file or changeset",
+  FILE_PATH_REQUIRED: "verification context file subject requires --path",
+  FILE_PATH_UNSAFE: "verification context file subject path must be product-relative",
+  CHANGESET_REFS_REQUIRED: "verification context changeset subject requires --base and --head"
+};
+var VERIFICATION_CONTEXT_FILE_SUBJECT_PATH = {
+  PARENT_DIRECTORY: {
+    SEGMENT: "..",
+    PREFIX: "../"
+  },
+  SEPARATOR: {
+    CANONICAL: "/",
+    WINDOWS: "\\"
+  }
+};
+async function resolveCommandScope(deps) {
+  const cwd = deps.cwd ?? CONFIG_PROCESS_CWD.read();
+  const git = deps.git ?? defaultGitDependencies;
+  const product = await detectGitCommonDirProductRoot(cwd, git);
+  const processEnv = deps.processEnv ?? process.env;
+  const probedBranch = product.isGitRepo ? await getCurrentBranch(cwd, git) ?? void 0 : void 0;
+  const headSha = (product.isGitRepo ? await getHeadSha(cwd, git) : null) ?? SPX_VERIFY_HEAD_SHA.MISSING;
+  const branchIdentity = resolveBranchIdentity({
+    branchName: deps.branch ?? processEnv[VERIFICATION_CONTEXT_CLI_ENV.BRANCH] ?? probedBranch,
+    headSha
+  });
+  return {
+    storageProductDir: product.productDir,
+    launchProductDir: product.worktreeRoot,
+    branchSlug: slugBranchIdentity(branchIdentity),
+    branchIdentity,
+    headSha
+  };
+}
+function okResult2(output) {
+  return { exitCode: VERIFICATION_CONTEXT_CLI_EXIT_CODE.OK, output };
+}
+function errorResult2(error) {
+  return { exitCode: VERIFICATION_CONTEXT_CLI_EXIT_CODE.ERROR, output: error };
+}
+function normalizeFileSubjectPath(path7) {
+  const windowsRoot = win32.parse(path7).root;
+  const normalized = win32.normalize(path7).replaceAll(
+    VERIFICATION_CONTEXT_FILE_SUBJECT_PATH.SEPARATOR.WINDOWS,
+    VERIFICATION_CONTEXT_FILE_SUBJECT_PATH.SEPARATOR.CANONICAL
+  );
+  const segments = normalized.split(VERIFICATION_CONTEXT_FILE_SUBJECT_PATH.SEPARATOR.CANONICAL);
+  if (isAbsolute8(path7) || win32.isAbsolute(path7) || windowsRoot.length > 0 || segments.includes(VERIFICATION_CONTEXT_FILE_SUBJECT_PATH.PARENT_DIRECTORY.SEGMENT)) {
+    return void 0;
+  }
+  return normalized;
+}
+function resolveSubject(options) {
+  if (options.subject === VERIFICATION_CONTEXT_SUBJECT_KIND.FILE) {
+    if (options.path === void 0 || options.path.length === 0) {
+      return VERIFICATION_CONTEXT_CLI_ERROR.FILE_PATH_REQUIRED;
+    }
+    const path7 = normalizeFileSubjectPath(options.path);
+    if (path7 === void 0) return VERIFICATION_CONTEXT_CLI_ERROR.FILE_PATH_UNSAFE;
+    return { kind: VERIFICATION_CONTEXT_SUBJECT_KIND.FILE, path: path7 };
+  }
+  if (options.subject === VERIFICATION_CONTEXT_SUBJECT_KIND.CHANGESET) {
+    if (options.base === void 0 || options.base.length === 0 || options.head === void 0 || options.head.length === 0) {
+      return VERIFICATION_CONTEXT_CLI_ERROR.CHANGESET_REFS_REQUIRED;
+    }
+    return { kind: VERIFICATION_CONTEXT_SUBJECT_KIND.CHANGESET, base: options.base, head: options.head };
+  }
+  return VERIFICATION_CONTEXT_CLI_ERROR.INVALID_SUBJECT;
+}
+async function verificationContextCreateCommand(options, deps = {}) {
+  const subject = resolveSubject(options);
+  if (typeof subject === "string") return errorResult2(subject);
+  const scope2 = await resolveCommandScope(deps);
+  const document = createVerificationContextDocument({
+    schemaVersion: VERIFICATION_CONTEXT_SCHEMA_VERSION,
+    subject,
+    predicate: options.predicate,
+    workflow: { name: options.workflow },
+    launch: {
+      productDir: scope2.launchProductDir,
+      branchSlug: scope2.branchSlug,
+      branchIdentity: scope2.branchIdentity,
+      headSha: scope2.headSha,
+      createdAt: (deps.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+    },
+    persistence: VERIFICATION_CONTEXT_PERSISTENCE
+  });
+  if (!document.ok) return errorResult2(document.error);
+  const persisted = await persistVerificationContext(
+    { productDir: scope2.storageProductDir, branchSlug: scope2.branchSlug, digest: document.value.digest },
+    document.value,
+    { ...deps.fs === void 0 ? {} : { fs: deps.fs } }
+  );
+  if (!persisted.ok) return errorResult2(persisted.error);
+  return okResult2(JSON.stringify(persisted.value));
+}
+
+// src/interfaces/cli/lib/stream-report.ts
+var CLI_STREAM_REPORT = {
+  LINE_SEPARATOR: "\n"
+};
+function reportCliResult(result, io) {
+  const output = `${result.output}${CLI_STREAM_REPORT.LINE_SEPARATOR}`;
+  if (result.exitCode === 0) io.writeStdout(output);
+  else io.writeStderr(output);
+  io.setExitCode(result.exitCode);
+}
+
+// src/interfaces/cli/verification-context.ts
+var VERIFICATION_CONTEXT_CLI = {
+  commandName: "verification-context",
+  description: "Create an immutable verification context document",
+  createCommandName: "create",
+  subjectOption: "--subject <subject>",
+  pathOption: "--path <path>",
+  baseOption: "--base <ref>",
+  headOption: "--head <ref>",
+  predicateOption: "--predicate <predicate>",
+  workflowOption: "--workflow <workflow>"
+};
+var verificationContextDomain = {
+  name: VERIFICATION_CONTEXT_CLI.commandName,
+  description: VERIFICATION_CONTEXT_CLI.description,
+  register: (program, invocation) => {
+    const command = program.command(VERIFICATION_CONTEXT_CLI.commandName).description(VERIFICATION_CONTEXT_CLI.description);
+    command.command(VERIFICATION_CONTEXT_CLI.createCommandName).description("Create a canonical verification context and report its path and digest").requiredOption(VERIFICATION_CONTEXT_CLI.subjectOption, "Subject kind: file or changeset").option(VERIFICATION_CONTEXT_CLI.pathOption, "Product-relative file path for a file subject").option(VERIFICATION_CONTEXT_CLI.baseOption, "Base ref for a changeset subject").option(VERIFICATION_CONTEXT_CLI.headOption, "Head ref for a changeset subject").requiredOption(VERIFICATION_CONTEXT_CLI.predicateOption, "Caller-supplied predicate identifier").requiredOption(VERIFICATION_CONTEXT_CLI.workflowOption, "Caller-supplied workflow identifier").action(async (options) => {
+      reportCliResult(
+        await verificationContextCreateCommand(options, { cwd: invocation.resolveEffectiveInvocationDir() }),
+        invocation.io
+      );
     });
-    registerValidationCommands(validationCmd);
   }
 };
 
@@ -14890,15 +15769,29 @@ var WORKTREE_CLI = {
   WORKTREES_DIR_FLAG: "--worktrees-dir"
 };
 var WORKTREE_DOMAIN_DESCRIPTION = "Coordinate worktree occupancy across a bare-repository pool";
-function handleError3(error) {
-  console.error("Error:", error);
-  process.exit(1);
+function writeOutput4(invocation, output) {
+  invocation.io.writeStdout(`${output}
+`);
+}
+function writeError4(invocation, output) {
+  invocation.io.writeStderr(`${output}
+`);
+}
+function writeInvocationWarning4(invocation, warning) {
+  if (warning !== void 0) {
+    writeError4(invocation, warning);
+  }
 }
-function registerWorktreeCommands(worktreeCmd) {
+function handleError3(invocation, error) {
+  writeError4(invocation, `Error: ${error}`);
+  return invocation.io.exit(1);
+}
+function registerWorktreeCommands(worktreeCmd, invocation) {
+  const effectiveInvocationDir = () => invocation.resolveEffectiveInvocationDir();
   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(),
+      cwd: effectiveInvocationDir(),
       env: process.env,
       fs: defaultOccupancyFileSystem,
       gitDeps: defaultGitDependencies,
@@ -14906,13 +15799,13 @@ function registerWorktreeCommands(worktreeCmd) {
       selfPid: process.pid,
       sessionId: options.sessionId,
       worktreesDir: options.worktreesDir,
-      onWarning: writeWarning
+      onWarning: (warning) => writeInvocationWarning4(invocation, warning)
     });
-    if (!result.ok) handleError3(result.error);
+    if (!result.ok) handleError3(invocation, result.error);
   });
   worktreeCmd.command(`${WORKTREE_CLI.STATUS} ${WORKTREE_CLI.WORKTREE_ARGUMENT}`).description("Report a worktree's occupancy (running | free)").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(),
+      cwd: effectiveInvocationDir(),
       fs: defaultOccupancyFileSystem,
       gitDeps: defaultGitDependencies,
       worktrees,
@@ -14920,28 +15813,28 @@ function registerWorktreeCommands(worktreeCmd) {
       pathInfo: defaultWorktreePathInfo,
       processTable: defaultProcessTable,
       worktreesDir: options.worktreesDir,
-      onWarning: writeWarning
+      onWarning: (warning) => writeInvocationWarning4(invocation, warning)
     });
-    if (!result.ok) handleError3(result.error);
-    console.log(result.value);
+    if (!result.ok) handleError3(invocation, result.error);
+    writeOutput4(invocation, 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({
-      cwd: process.cwd(),
+      cwd: effectiveInvocationDir(),
       fs: defaultOccupancyFileSystem,
       gitDeps: defaultGitDependencies,
       worktreesDir: options.worktreesDir,
-      onWarning: writeWarning
+      onWarning: (warning) => writeInvocationWarning4(invocation, warning)
     });
-    if (!result.ok) handleError3(result.error);
+    if (!result.ok) handleError3(invocation, 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);
+  register: (program, invocation) => {
+    const worktreeCmd = program.command(WORKTREE_CLI.COMMAND).description(WORKTREE_DOMAIN_DESCRIPTION);
+    registerWorktreeCommands(worktreeCmd, invocation);
   }
 };
 
@@ -14957,17 +15850,46 @@ var CLI_DOMAINS = [
   specDomain,
   testingDomain,
   validationDomain,
+  verificationContextDomain,
   worktreeDomain
 ];
 
+// src/interfaces/cli/program.ts
+var SPX_PROGRAM_NAME = "spx";
+var SPX_PROGRAM_DESCRIPTION = "Fast, deterministic CLI tool for spec workflow management";
+function createCliProgram(options = {}) {
+  const program = new Command();
+  const io = {
+    writeStdout: options.writeStdout ?? DEFAULT_CLI_IO.writeStdout,
+    writeStderr: options.writeStderr ?? DEFAULT_CLI_IO.writeStderr,
+    setExitCode: options.setExitCode ?? DEFAULT_CLI_IO.setExitCode,
+    exit: options.exit ?? DEFAULT_CLI_IO.exit
+  };
+  program.name(SPX_PROGRAM_NAME).description(SPX_PROGRAM_DESCRIPTION).option(SPX_GLOBAL_OPTIONS.directory.flags, SPX_GLOBAL_OPTIONS.directory.description);
+  if (options.version !== void 0) {
+    program.version(options.version);
+  }
+  const invocation = createCliInvocation({
+    readDirectoryOption: () => program.opts().directory,
+    processCwd: options.processCwd ?? CONFIG_PROCESS_CWD.read,
+    resolveProductDir,
+    writeWarning: (warning) => {
+      if (warning !== void 0) {
+        io.writeStderr(`${warning}
+`);
+      }
+    },
+    io
+  });
+  for (const domain of options.domains ?? CLI_DOMAINS) {
+    domain.register(program, invocation);
+  }
+  return program;
+}
+
 // src/cli.ts
 installLifecycle();
 var require3 = createRequire2(import.meta.url);
 var { version } = require3("../package.json");
-var program = new Command();
-program.name("spx").description("Fast, deterministic CLI tool for spec workflow management").version(version);
-for (const domain of CLI_DOMAINS) {
-  domain.register(program);
-}
-program.parse();
+createCliProgram({ version }).parse();
 //# sourceMappingURL=cli.js.map