@outcomeeng/spx 0.6.10 → 0.6.11

package/dist/cli.js

@@ -289,9 +289,6 @@ async function resolveAgentResumeScopeContext(options) {
     return { match: (core) => core.branch === target, claudeDirAccepts: () => true };
   }
   const invocationRoot = await options.resolveWorktreeRoot(options.invocationDir);
-  if (invocationRoot === null) {
-    return null;
-  }
   const projectPrefix = claudeProjectDirName(invocationRoot);
   return {
     match: (core) => isPathInsideOrEqual(invocationRoot, core.cwd),
@@ -326,11 +323,11 @@ function renderAgentResumeJson(candidates) {
 }
 async function recentStoreFiles(paths, fs8, nowMs) {
   const stats = await mapWithConcurrency(paths, AGENT_RESUME_LIMITS.READ_CONCURRENCY, async (path7) => {
-    const stat8 = await fs8.stat(path7).catch(() => null);
-    if (stat8 === null || !isRecentAgentSessionMtime(stat8.mtimeMs, nowMs)) {
+    const stat9 = await fs8.stat(path7).catch(() => null);
+    if (stat9 === null || !isRecentAgentSessionMtime(stat9.mtimeMs, nowMs)) {
       return null;
     }
-    return { path: path7, modifiedAtMs: stat8.mtimeMs };
+    return { path: path7, modifiedAtMs: stat9.mtimeMs };
   });
   return stats.filter((file) => file !== null).sort((left, right) => right.modifiedAtMs - left.modifiedAtMs || left.path.localeCompare(right.path));
 }
@@ -529,6 +526,195 @@ async function mapWithConcurrency(items, concurrency, mapper) {
   return results;
 }
 
+// src/domains/session/types.ts
+var SESSION_PRIORITY = {
+  HIGH: "high",
+  MEDIUM: "medium",
+  LOW: "low"
+};
+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,
+  [SESSION_PRIORITY.MEDIUM]: 1,
+  [SESSION_PRIORITY.LOW]: 2
+};
+var DEFAULT_PRIORITY = SESSION_PRIORITY.MEDIUM;
+var SESSION_FRONT_MATTER = {
+  PRIORITY: "priority",
+  GIT_REF: "git_ref",
+  GOAL: "goal",
+  NEXT_STEP: "next_step",
+  CREATED_AT: "created_at",
+  AGENT_SESSION_ID: "agent_session_id",
+  SPECS: "specs",
+  FILES: "files"
+};
+
+// src/domains/agent/search.ts
+var AGENT_SEARCH_DEFAULT_LIMIT = 20;
+var AGENT_SEARCH_MATCH_REASON = {
+  ALL: "all",
+  PICKUP_ID: "pickup-id",
+  CONTAINS: "contains",
+  SESSION_ID: "session-id",
+  AGENT: "agent",
+  BRANCH: "branch"
+};
+function pickupIdSearchLiteral(pickupId) {
+  return formatSessionOutputMarker(SESSION_OUTPUT_MARKER.PICKUP_ID, pickupId);
+}
+function agentSearchQueryFromOptions(options) {
+  const contentNeedles = [];
+  if (options.pickupId !== void 0) {
+    contentNeedles.push({
+      reason: AGENT_SEARCH_MATCH_REASON.PICKUP_ID,
+      value: pickupIdSearchLiteral(options.pickupId)
+    });
+  }
+  if (options.contains !== void 0) {
+    contentNeedles.push({ reason: AGENT_SEARCH_MATCH_REASON.CONTAINS, value: options.contains });
+  }
+  return {
+    contentNeedles,
+    sessionId: options.sessionId ?? null,
+    branch: options.branch ?? null,
+    agent: options.agent ?? null,
+    includeAll: options.all === true,
+    limit: options.limit ?? AGENT_SEARCH_DEFAULT_LIMIT
+  };
+}
+async function searchAgentSessions(options) {
+  const selectedAgents = options.query.agent === null ? [AGENT_SESSION_KIND.CODEX, AGENT_SESSION_KIND.CLAUDE_CODE] : [options.query.agent];
+  const perAgent = await Promise.all(
+    selectedAgents.map((agent) => searchAgentStore(agent, options))
+  );
+  return perAgent.flat().sort(compareSearchResults).slice(0, Math.max(0, options.query.limit));
+}
+function renderAgentSearchJson(results) {
+  return JSON.stringify(results, null, 2);
+}
+function renderAgentSearchList(results) {
+  if (results.length === 0) {
+    return "No matching agent sessions found.";
+  }
+  return results.map((result) => {
+    const updatedAt = result.updatedAt ?? new Date(result.modifiedAtMs).toISOString();
+    return `${updatedAt} ${AGENT_SESSION_LABEL[result.agent]} ${result.sessionId} ${result.cwd}`;
+  }).join("\n");
+}
+async function searchAgentStore(agent, options) {
+  const paths = agent === AGENT_SESSION_KIND.CODEX ? await collectJsonlFiles(codexSessionStoreDir(options.homeDir), options.fs) : await claudeTranscriptFiles(
+    claudeCodeSessionStoreDir(options.homeDir),
+    options.fs,
+    claudeDirAcceptsProductScope(options.productScopeRoot)
+  );
+  const files = await storeFiles(paths, options.fs, options.nowMs, options.query.includeAll);
+  const parser = agent === AGENT_SESSION_KIND.CODEX ? parseCodexHead : parseClaudeHead;
+  return collectMatchingSessions(agent, files, options, parser);
+}
+function claudeDirAcceptsProductScope(productScopeRoot) {
+  const projectPrefix = claudeProjectDirName(productScopeRoot);
+  return (dirName) => dirName === projectPrefix || dirName.startsWith(`${projectPrefix}${CLAUDE_PROJECT_ENCODED_SEPARATOR}`);
+}
+async function collectMatchingSessions(agent, files, options, parseHead) {
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const head = await options.fs.readHead(file.path, AGENT_RESUME_LIMITS.METADATA_HEAD_BYTES).catch(() => null);
+    if (head === null) continue;
+    const core = parseHead(head);
+    if (core === null || !core.interactive || seen.has(core.sessionId)) continue;
+    if (!coreMatchesProductScope(core, options.productScopeRoot)) continue;
+    const matches = await matchReasons(agent, core, file.path, options);
+    if (matches.length === 0) continue;
+    seen.add(core.sessionId);
+    results.push({
+      agent,
+      sessionId: core.sessionId,
+      cwd: core.cwd,
+      sourcePath: file.path,
+      modifiedAtMs: file.modifiedAtMs,
+      updatedAt: core.updatedAt,
+      branch: core.branch,
+      matches
+    });
+  }
+  return results;
+}
+async function matchReasons(agent, core, path7, options) {
+  if (!hasSearchSelector(options.query)) {
+    return [AGENT_SEARCH_MATCH_REASON.ALL];
+  }
+  const metadataMatches = metadataMatchReasons(agent, core, options.query);
+  const contentMatches = await contentMatchReasons(path7, options);
+  if (metadataMatches === null || contentMatches === null) {
+    return [];
+  }
+  return [...metadataMatches, ...contentMatches];
+}
+function hasSearchSelector(query) {
+  return query.contentNeedles.length > 0 || query.sessionId !== null || query.branch !== null || query.agent !== null;
+}
+function metadataMatchReasons(agent, core, query) {
+  const matches = [];
+  if (query.agent !== null) {
+    if (agent !== query.agent) return null;
+    matches.push(AGENT_SEARCH_MATCH_REASON.AGENT);
+  }
+  if (query.sessionId !== null && core.sessionId === query.sessionId) {
+    matches.push(AGENT_SEARCH_MATCH_REASON.SESSION_ID);
+  } else if (query.sessionId !== null) {
+    return null;
+  }
+  if (query.branch !== null) {
+    if (core.branch !== query.branch) return null;
+    matches.push(AGENT_SEARCH_MATCH_REASON.BRANCH);
+  }
+  return matches;
+}
+async function contentMatchReasons(path7, options) {
+  if (options.query.contentNeedles.length === 0) {
+    return [];
+  }
+  const content = await options.fs.readText(path7).catch(() => null);
+  return content === null ? null : matchingContentNeedles(content, options.query.contentNeedles);
+}
+function matchingContentNeedles(content, needles) {
+  const matches = needles.filter((needle) => content.includes(needle.value)).map((needle) => needle.reason);
+  return matches.length === needles.length ? matches : null;
+}
+function coreMatchesProductScope(core, productScopeRoot) {
+  return isPathInsideOrEqual(productScopeRoot, core.cwd);
+}
+async function storeFiles(paths, fs8, nowMs, includeAll) {
+  const files = await mapWithConcurrency(paths, AGENT_RESUME_LIMITS.READ_CONCURRENCY, async (path7) => {
+    const stat9 = await fs8.stat(path7).catch(() => null);
+    if (stat9 === null) return null;
+    if (!includeAll && !isRecentAgentSessionMtime(stat9.mtimeMs, nowMs)) return null;
+    return { path: path7, modifiedAtMs: stat9.mtimeMs };
+  });
+  return files.filter((file) => file !== null).sort((left, right) => right.modifiedAtMs - left.modifiedAtMs || left.path.localeCompare(right.path));
+}
+function compareSearchResults(left, right) {
+  const modifiedDiff = right.modifiedAtMs - left.modifiedAtMs;
+  if (modifiedDiff !== 0) return modifiedDiff;
+  return `${left.agent}:${left.sessionId}`.localeCompare(`${right.agent}:${right.sessionId}`);
+}
+
 // src/git/root.ts
 import { execa } from "execa";
 import { basename, dirname, isAbsolute as isAbsolute2, join, resolve as resolve4 } from "path";
@@ -917,9 +1103,9 @@ var defaultAgentResumeCommandDeps = {
   fs: nodeAgentSessionFileSystem,
   homeDir: homedir,
   nowMs: Date.now,
-  resolveWorktreeRoot: async (cwd) => {
+  resolveWorktreeRoot: async (cwd, fallbackWorktreeRoot) => {
     const result = await detectWorktreeProductRoot(cwd);
-    return result.isGitRepo ? result.productDir : null;
+    return result.isGitRepo ? result.productDir : fallbackWorktreeRoot;
   }
 };
 async function loadAgentResumeCandidates(options) {
@@ -930,7 +1116,7 @@ async function loadAgentResumeCandidates(options) {
     nowMs: deps.nowMs(),
     scope: options.scope,
     fs: deps.fs,
-    resolveWorktreeRoot: deps.resolveWorktreeRoot
+    resolveWorktreeRoot: (cwd) => deps.resolveWorktreeRoot(cwd, options.fallbackWorktreeRoot)
   });
 }
 async function listAgentResumeSessions(options) {
@@ -940,6 +1126,63 @@ async function jsonAgentResumeSessions(options) {
   return renderAgentResumeJson(await loadAgentResumeCandidates(options));
 }
 
+// src/commands/agent/search.ts
+import { open as open2, readdir as readdir2, readFile, stat as stat2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+var nodeAgentSearchFileSystem = {
+  async readDir(path7) {
+    const entries = await readdir2(path7, { withFileTypes: true });
+    return entries.map((entry) => ({
+      name: entry.name,
+      isDirectory: entry.isDirectory(),
+      isFile: entry.isFile()
+    }));
+  },
+  async readHead(path7, maxBytes) {
+    const handle = await open2(path7, "r");
+    try {
+      const buffer = Buffer.alloc(maxBytes);
+      const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+      return buffer.toString(AGENT_SESSION_STORE.TEXT_ENCODING, 0, bytesRead);
+    } finally {
+      await handle.close();
+    }
+  },
+  async readText(path7) {
+    return readFile(path7, AGENT_SESSION_STORE.TEXT_ENCODING);
+  },
+  async stat(path7) {
+    const result = await stat2(path7);
+    return { mtimeMs: result.mtimeMs };
+  }
+};
+var defaultAgentSearchCommandDeps = {
+  fs: nodeAgentSearchFileSystem,
+  homeDir: homedir2,
+  nowMs: Date.now,
+  resolveProductScopeRoot: resolveAgentSearchProductScopeRoot
+};
+async function resolveAgentSearchProductScopeRoot(cwd, fallbackProductScopeRoot, gitDeps = defaultGitDependencies) {
+  const result = await detectWorktreeProductRoot(cwd, gitDeps);
+  return result.isGitRepo ? result.productDir : fallbackProductScopeRoot;
+}
+async function loadAgentSearchResults(options) {
+  const deps = options.deps ?? defaultAgentSearchCommandDeps;
+  return searchAgentSessions({
+    homeDir: deps.homeDir(),
+    nowMs: deps.nowMs(),
+    productScopeRoot: await deps.resolveProductScopeRoot(options.cwd, options.fallbackProductScopeRoot),
+    fs: deps.fs,
+    query: options.query
+  });
+}
+async function listAgentSearchSessions(options) {
+  return renderAgentSearchList(await loadAgentSearchResults(options));
+}
+async function jsonAgentSearchSessions(options) {
+  return renderAgentSearchJson(await loadAgentSearchResults(options));
+}
+
 // src/lib/process-lifecycle/exit-codes.ts
 var SIGINT_EXIT_CODE = 130;
 var SIGTERM_EXIT_CODE = 143;
@@ -1118,6 +1361,50 @@ function spawnManagedSubprocess(runner, command, args, options) {
   });
 }
 
+// src/lib/sanitize-cli-argument.ts
+var MAX_CLI_ARGUMENT_DISPLAY_LENGTH = 120;
+var ELLIPSIS_TOKEN = "...";
+var SENTINEL_UNDEFINED = "<undefined>";
+var SENTINEL_NULL = "<null>";
+var SENTINEL_EMPTY = "<empty>";
+var CONTROL_CHAR_UPPER_BOUND = 31;
+var DEL_CHAR_CODE = 127;
+var HEX_RADIX = 16;
+var HEX_PAD = 2;
+function formatHexEscape(code) {
+  return String.raw`\x${code.toString(HEX_RADIX).padStart(HEX_PAD, "0")}`;
+}
+function nonStringSentinel(type) {
+  return `<non-string:${type}>`;
+}
+function sanitizeCliArgument(input) {
+  return truncate(escapeCliArgument(input));
+}
+function escapeCliArgument(input) {
+  if (input === void 0) return SENTINEL_UNDEFINED;
+  if (input === null) return SENTINEL_NULL;
+  if (typeof input !== "string") return nonStringSentinel(typeof input);
+  if (input.length === 0) return SENTINEL_EMPTY;
+  return escapeControlCharacters(input);
+}
+function escapeControlCharacters(value) {
+  let out = "";
+  for (const char of value) {
+    const code = char.codePointAt(0);
+    if (code === void 0) continue;
+    if (code <= CONTROL_CHAR_UPPER_BOUND || code === DEL_CHAR_CODE) {
+      out += formatHexEscape(code);
+    } else {
+      out += char;
+    }
+  }
+  return out;
+}
+function truncate(value) {
+  if (value.length <= MAX_CLI_ARGUMENT_DISPLAY_LENGTH) return value;
+  return value.slice(0, MAX_CLI_ARGUMENT_DISPLAY_LENGTH - ELLIPSIS_TOKEN.length) + ELLIPSIS_TOKEN;
+}
+
 // src/interfaces/cli/foreground-launch.ts
 var FOREGROUND_LAUNCH_STDIO = "inherit";
 var LAUNCH_FAILURE_STATUS = 1;
@@ -1240,14 +1527,26 @@ async function runAgentResumePicker(candidates, renderPicker = render) {
 var AGENT_CLI = {
   commandName: "agent",
   resumeCommandName: "resume",
+  searchCommandName: "search",
   flags: {
     latest: "--latest",
     list: "--list",
     json: "--json",
-    branch: "--branch"
+    branch: "--branch",
+    all: "--all",
+    pickupId: "--pickup-id",
+    contains: "--contains",
+    sessionId: "--session-id",
+    agent: "--agent",
+    limit: "--limit"
   },
   optionArgs: {
-    branch: "--branch <name>"
+    branch: "--branch <name>",
+    pickupId: "--pickup-id <id>",
+    contains: "--contains <literal>",
+    sessionId: "--session-id <id>",
+    agent: "--agent <kind>",
+    limit: "--limit <count>"
   }
 };
 var AGENT_CLI_EXIT = {
@@ -1265,6 +1564,7 @@ var DEFAULT_AGENT_CLI_DEPENDENCIES = {
     );
   }
 };
+var POSITIVE_DECIMAL_INTEGER_PATTERN = /^[1-9][0-9]*$/;
 function writeOutput(invocation, output) {
   invocation.io.writeStdout(`${output}
 `);
@@ -1281,6 +1581,33 @@ function handleError(invocation, error) {
 function resumeScopeFromOptions(options) {
   return options.branch === void 0 ? worktreeResumeScope() : branchResumeScope(options.branch);
 }
+function parseSearchLimit(value) {
+  if (!POSITIVE_DECIMAL_INTEGER_PATTERN.test(value)) {
+    throw new Error(`agent search limit must be a positive integer: ${sanitizeCliArgument(value)}`);
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`agent search limit must be a positive integer: ${sanitizeCliArgument(value)}`);
+  }
+  return parsed;
+}
+function parseSearchAgentKind(value) {
+  if (value === AGENT_SESSION_KIND.CODEX || value === AGENT_SESSION_KIND.CLAUDE_CODE) {
+    return value;
+  }
+  throw new Error(`agent search kind must be codex or claude-code: ${sanitizeCliArgument(value)}`);
+}
+function searchQueryFromOptions(options) {
+  return {
+    pickupId: options.pickupId,
+    contains: options.contains,
+    sessionId: options.sessionId,
+    branch: options.branch,
+    agent: options.agent === void 0 ? void 0 : parseSearchAgentKind(options.agent),
+    all: options.all,
+    limit: options.limit === void 0 ? AGENT_SEARCH_DEFAULT_LIMIT : parseSearchLimit(options.limit)
+  };
+}
 async function dispatchInteractiveResume(mode, commandOptions, deps, invocation) {
   const candidates = await loadAgentResumeCandidates(commandOptions);
   if (candidates.length === 0) {
@@ -1307,12 +1634,14 @@ function createAgentDomain(deps = {}) {
         let requestedExitCode = AGENT_CLI_EXIT.SUCCESS;
         try {
           const mode = resolveAgentResumeMode(options);
+          const productContext = invocation.resolveProductContext();
           if (mode === AGENT_RESUME_MODE.PICK && !resolvedDeps.isInteractiveTerminal()) {
             writeError(invocation, AGENT_RESUME_TEXT.INTERACTIVE_REQUIRED);
             requestedExitCode = AGENT_CLI_EXIT.FAILURE;
           } else {
             const commandOptions = {
-              cwd: invocation.resolveEffectiveInvocationDir(),
+              cwd: productContext.effectiveInvocationDir,
+              fallbackWorktreeRoot: productContext.productDir,
               scope: resumeScopeFromOptions(options),
               deps: resolvedDeps.resumeDeps
             };
@@ -1331,6 +1660,21 @@ function createAgentDomain(deps = {}) {
         }
         return invocation.io.exit(requestedExitCode);
       });
+      agentCmd.command(AGENT_CLI.searchCommandName).description("Search Codex and Claude Code agent session transcripts for this product").option(AGENT_CLI.optionArgs.pickupId, "Search for an exact SPX pickup marker").option(AGENT_CLI.optionArgs.contains, "Search transcript content for a literal string").option(AGENT_CLI.optionArgs.sessionId, "Search for an agent session id").option(AGENT_CLI.optionArgs.branch, "Search for sessions started on the named branch").option(AGENT_CLI.optionArgs.agent, "Search only one agent kind").option(AGENT_CLI.flags.all, "Include sessions outside the recent-session window").option(AGENT_CLI.optionArgs.limit, "Maximum number of results").option(AGENT_CLI.flags.json, "Print matching sessions as JSON").action(async (options) => {
+        try {
+          const productContext = invocation.resolveProductContext();
+          const commandOptions = {
+            cwd: productContext.effectiveInvocationDir,
+            fallbackProductScopeRoot: productContext.productDir,
+            query: agentSearchQueryFromOptions(searchQueryFromOptions(options)),
+            deps: resolvedDeps.searchDeps
+          };
+          const output = options.json === true ? await jsonAgentSearchSessions(commandOptions) : await listAgentSearchSessions(commandOptions);
+          writeOutput(invocation, output);
+        } catch (error) {
+          handleError(invocation, error);
+        }
+      });
     }
   };
 }
@@ -2545,14 +2889,14 @@ async function compactRetrieveCommand(options) {
 }
 
 // src/commands/compact/store.ts
-import { readFile } from "fs/promises";
+import { readFile as readFile2 } from "fs/promises";
 var UTF8_ENCODING = "utf8";
 async function compactStoreCommand(options) {
   const sessionToken = resolveCompactSessionToken(options.sessionId, options.env ?? process.env);
   if (sessionToken === void 0) return 1;
   let transcript;
   try {
-    transcript = await readFile(options.transcript, UTF8_ENCODING);
+    transcript = await readFile2(options.transcript, UTF8_ENCODING);
   } catch {
     return 1;
   }
@@ -2608,7 +2952,7 @@ var compactDomain = {
 };
 
 // src/config/index.ts
-import { readFile as readFile2 } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
 import { join as join4 } from "path";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { parse as parseYaml, parseDocument as parseYamlDocument, stringify as stringifyYaml } from "yaml";
@@ -4269,7 +4613,7 @@ async function readProductConfigFile(productDir) {
     const path7 = join4(productDir, filename);
     let raw;
     try {
-      raw = await readFile2(path7, "utf8");
+      raw = await readFile3(path7, "utf8");
     } catch (error) {
       if (isFileNotFound(error)) continue;
       return { ok: false, error: `failed to read ${filename}: ${toMessage(error)}` };
@@ -4553,7 +4897,7 @@ var configDomain = {
 };
 
 // src/interfaces/cli/diagnose.ts
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 import { Option } from "commander";
 
 // src/domains/diagnose/types.ts
@@ -6251,50 +6595,6 @@ var defaultSpxReachabilityProbe = {
   }
 };
 
-// src/lib/sanitize-cli-argument.ts
-var MAX_CLI_ARGUMENT_DISPLAY_LENGTH = 120;
-var ELLIPSIS_TOKEN = "...";
-var SENTINEL_UNDEFINED = "<undefined>";
-var SENTINEL_NULL = "<null>";
-var SENTINEL_EMPTY = "<empty>";
-var CONTROL_CHAR_UPPER_BOUND = 31;
-var DEL_CHAR_CODE = 127;
-var HEX_RADIX = 16;
-var HEX_PAD = 2;
-function formatHexEscape(code) {
-  return String.raw`\x${code.toString(HEX_RADIX).padStart(HEX_PAD, "0")}`;
-}
-function nonStringSentinel(type) {
-  return `<non-string:${type}>`;
-}
-function sanitizeCliArgument(input) {
-  return truncate(escapeCliArgument(input));
-}
-function escapeCliArgument(input) {
-  if (input === void 0) return SENTINEL_UNDEFINED;
-  if (input === null) return SENTINEL_NULL;
-  if (typeof input !== "string") return nonStringSentinel(typeof input);
-  if (input.length === 0) return SENTINEL_EMPTY;
-  return escapeControlCharacters(input);
-}
-function escapeControlCharacters(value) {
-  let out = "";
-  for (const char of value) {
-    const code = char.codePointAt(0);
-    if (code === void 0) continue;
-    if (code <= CONTROL_CHAR_UPPER_BOUND || code === DEL_CHAR_CODE) {
-      out += formatHexEscape(code);
-    } else {
-      out += char;
-    }
-  }
-  return out;
-}
-function truncate(value) {
-  if (value.length <= MAX_CLI_ARGUMENT_DISPLAY_LENGTH) return value;
-  return value.slice(0, MAX_CLI_ARGUMENT_DISPLAY_LENGTH - ELLIPSIS_TOKEN.length) + ELLIPSIS_TOKEN;
-}
-
 // src/interfaces/cli/diagnose.ts
 var DIAGNOSE_CLI = {
   COMMAND: "diagnose",
@@ -6341,7 +6641,7 @@ var diagnoseDomain = {
           isTty: Boolean(process.stdout.isTTY)
         }),
         registry: defaultRegistry(),
-        fs: { readFile: (path7) => readFile3(path7, "utf8") }
+        fs: { readFile: (path7) => readFile4(path7, "utf8") }
       });
       if (!result.ok) {
         handleError2(result.error, invocation.io);
@@ -7658,6 +7958,18 @@ async function readSealedJournalRunSet(scope2, options = {}) {
     }))
   };
 }
+async function findJournalRunBranchSlugs(scope2, options = {}) {
+  const fs8 = options.fs ?? defaultFileSystem;
+  const branches = await branchSlugs(scope2, fs8);
+  if (!branches.ok) return branches;
+  const matches = [];
+  for (const branchSlug of branches.value) {
+    const runFilePath = bindRunFilePath({ ...scope2, branchSlug });
+    if (!runFilePath.ok) return runFilePath;
+    if (await runFileExists(fs8, runFilePath.value)) matches.push(branchSlug);
+  }
+  return { ok: true, value: matches };
+}
 async function appendJournalEvent(ref, input, sink, options = {}) {
   const bound = await bindJournal(ref, options.fs);
   if (!bound.ok) return bound;
@@ -7736,6 +8048,7 @@ var JOURNAL_CLI_ERROR = {
   INVALID_READ_SET_EVENT_LIMIT: "journal read-set event limit must be a positive whole integer",
   INVALID_SEALED_FILTER: "journal list sealed filter is not registered",
   INVALID_TERMINAL_STATE_FILTER: "journal list terminal-state filter is not registered",
+  RUN_TOKEN_AMBIGUOUS: "journal run token matches multiple branch scopes; rerun with --branch-slug",
   OPEN_HYDRATION_FAILED: "journal open failed to hydrate the pull request's prior runs"
 };
 var CURSOR_PATTERN = /^\d+$/;
@@ -7858,6 +8171,34 @@ function verbOptions(deps) {
 function runRef(context, runToken) {
   return { productDir: context.productDir, branchSlug: context.branchSlug, type: context.type, runToken };
 }
+async function inspectionRunRef(scope2, deps) {
+  const context = await resolveJournalRunContext(scope2, deps);
+  if (!context.ok) return context;
+  if (scope2.branchSlug !== void 0) return { ok: true, value: runRef(context.value, scope2.runToken) };
+  const branches = await findJournalRunBranchSlugs(
+    {
+      productDir: context.value.productDir,
+      type: context.value.type,
+      runToken: scope2.runToken
+    },
+    verbOptions(deps)
+  );
+  if (!branches.ok) return branches;
+  if (branches.value.length === 1) {
+    const branchSlug = branches.value[0];
+    return {
+      ok: true,
+      value: {
+        productDir: context.value.productDir,
+        branchSlug,
+        type: context.value.type,
+        runToken: scope2.runToken
+      }
+    };
+  }
+  if (branches.value.length > 1) return { ok: false, error: JOURNAL_CLI_ERROR.RUN_TOKEN_AMBIGUOUS };
+  return { ok: true, value: runRef(context.value, scope2.runToken) };
+}
 function okResult(output) {
   return { exitCode: JOURNAL_CLI_EXIT_CODE.OK, output };
 }
@@ -7974,9 +8315,9 @@ async function journalAppendCommand(scope2, input, binding, deps = {}) {
 async function journalReadCommand(scope2, fromCursor, deps = {}) {
   const cursor = parseJournalCursor(fromCursor);
   if (!cursor.ok) return errorResult(cursor.error);
-  const context = await resolveJournalRunContext(scope2, deps);
-  if (!context.ok) return errorResult(context.error);
-  const events = await readJournalEvents(runRef(context.value, scope2.runToken), cursor.value, verbOptions(deps));
+  const ref = await inspectionRunRef(scope2, deps);
+  if (!ref.ok) return errorResult(ref.error);
+  const events = await readJournalEvents(ref.value, cursor.value, verbOptions(deps));
   if (!events.ok) return errorResult(events.error);
   return okResult(JSON.stringify(events.value));
 }
@@ -8025,10 +8366,10 @@ async function journalSealCommand(scope2, deps = {}) {
   return okResult(JSON.stringify({ sealed: true }));
 }
 async function journalRenderCommand(scope2, deps = {}) {
-  const context = await resolveJournalRunContext(scope2, deps);
-  if (!context.ok) return errorResult(context.error);
+  const ref = await inspectionRunRef(scope2, deps);
+  if (!ref.ok) return errorResult(ref.error);
   const rendered = await renderJournalRun(
-    runRef(context.value, scope2.runToken),
+    ref.value,
     (events) => [...events],
     verbOptions(deps)
   );
@@ -8354,7 +8695,7 @@ function sessionOptionToken(option) {
 }
 
 // src/commands/session/archive.ts
-import { mkdir, rename, stat as stat2 } from "fs/promises";
+import { mkdir, rename, stat as stat3 } from "fs/promises";
 import { dirname as dirname7, join as join8 } from "path";
 
 // src/domains/session/archive.ts
@@ -8667,7 +9008,7 @@ var SessionAlreadyArchivedError = class extends Error {
 };
 async function fileExists(path7) {
   try {
-    const stats = await stat2(path7);
+    const stats = await stat3(path7);
     return stats.isFile();
   } catch {
     return false;
@@ -8709,7 +9050,7 @@ async function archiveCommand(options) {
 }
 
 // src/commands/session/delete.ts
-import { stat as stat3, unlink } from "fs/promises";
+import { stat as stat4, unlink } from "fs/promises";
 
 // src/domains/session/delete.ts
 function resolveDeletePath(sessionId, existingPaths) {
@@ -8882,44 +9223,6 @@ function parseSessionId(id) {
   return date;
 }
 
-// src/domains/session/types.ts
-var SESSION_PRIORITY = {
-  HIGH: "high",
-  MEDIUM: "medium",
-  LOW: "low"
-};
-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,
-  [SESSION_PRIORITY.MEDIUM]: 1,
-  [SESSION_PRIORITY.LOW]: 2
-};
-var DEFAULT_PRIORITY = SESSION_PRIORITY.MEDIUM;
-var SESSION_FRONT_MATTER = {
-  PRIORITY: "priority",
-  GIT_REF: "git_ref",
-  GOAL: "goal",
-  NEXT_STEP: "next_step",
-  CREATED_AT: "created_at",
-  AGENT_SESSION_ID: "agent_session_id",
-  SPECS: "specs",
-  FILES: "files"
-};
-
 // src/domains/session/list.ts
 var FRONT_MATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)\r?\n?/;
 var SESSION_PRIORITY_VALUES = Object.values(SESSION_PRIORITY);
@@ -9158,7 +9461,7 @@ async function findExistingPaths(paths) {
   const existing = [];
   for (const path7 of paths) {
     try {
-      const stats = await stat3(path7);
+      const stats = await stat4(path7);
       if (stats.isFile()) {
         existing.push(path7);
       }
@@ -9180,7 +9483,7 @@ async function deleteCommand(options) {
 }
 
 // src/commands/session/handoff.ts
-import { mkdir as mkdir2, stat as stat4, writeFile } from "fs/promises";
+import { mkdir as mkdir2, stat as stat5, writeFile } from "fs/promises";
 import { join as join10, resolve as resolve6 } from "path";
 import { stringify as stringifyYaml3 } from "yaml";
 
@@ -9431,7 +9734,7 @@ async function rejectDirectoryInjectionEntries(entries, cwd) {
     if (entry.length === 0) continue;
     let entryIsDirectory = false;
     try {
-      entryIsDirectory = (await stat4(resolve6(cwd, entry))).isDirectory();
+      entryIsDirectory = (await stat5(resolve6(cwd, entry))).isDirectory();
     } catch {
       continue;
     }
@@ -9489,7 +9792,7 @@ ${formatSessionOutputMarker(SESSION_OUTPUT_MARKER.SESSION_FILE, absolutePath)}`;
 }
 
 // src/commands/session/list.ts
-import { readdir as readdir2, readFile as readFile4 } from "fs/promises";
+import { readdir as readdir3, readFile as readFile5 } from "fs/promises";
 import { join as join11 } from "path";
 var SESSION_LIST_FORMAT = {
   TEXT: "text",
@@ -9498,13 +9801,13 @@ var SESSION_LIST_FORMAT = {
 var SESSION_LIST_EMPTY_TEXT = "(no sessions)";
 async function loadSessionsFromDir(dir, status) {
   try {
-    const files = await readdir2(dir);
+    const files = await readdir3(dir);
     const sessions = [];
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
       const filePath = join11(dir, file);
-      const content = await readFile4(filePath, SESSION_FILE_ENCODING);
+      const content = await readFile5(filePath, SESSION_FILE_ENCODING);
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
@@ -9567,7 +9870,7 @@ async function listCommand(options) {
 }
 
 // src/commands/session/pickup.ts
-import { mkdir as mkdir3, readdir as readdir3, readFile as readFile5, rename as rename2 } from "fs/promises";
+import { mkdir as mkdir3, readdir as readdir4, readFile as readFile6, rename as rename2 } from "fs/promises";
 import { join as join12, resolve as resolve7 } from "path";
 
 // src/domains/session/pickup.ts
@@ -9607,8 +9910,8 @@ function selectBestSession(sessions) {
 var PICKUP_TARGET_STATUS = SESSION_STATUSES[1];
 var PICKUP_DEPS = {
   mkdir: mkdir3,
-  readdir: readdir3,
-  readFile: readFile5,
+  readdir: readdir4,
+  readFile: readFile6,
   rename: rename2
 };
 async function loadTodoSessions(config) {
@@ -9717,7 +10020,7 @@ async function loadPickCandidates(options) {
 }
 
 // src/commands/session/prune.ts
-import { readdir as readdir4, readFile as readFile6, unlink as unlink2 } from "fs/promises";
+import { readdir as readdir5, readFile as readFile7, unlink as unlink2 } from "fs/promises";
 import { join as join13 } from "path";
 
 // src/domains/session/prune.ts
@@ -9762,13 +10065,13 @@ function validatePruneOptions(options) {
 }
 async function loadArchiveSessions(config) {
   try {
-    const files = await readdir4(config.archiveDir);
+    const files = await readdir5(config.archiveDir);
     const sessions = [];
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
       const filePath = join13(config.archiveDir, file);
-      const content = await readFile6(filePath, SESSION_FILE_ENCODING);
+      const content = await readFile7(filePath, SESSION_FILE_ENCODING);
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
@@ -9817,7 +10120,7 @@ async function pruneCommand(options) {
 }
 
 // src/commands/session/release.ts
-import { readdir as readdir5, rename as rename3 } from "fs/promises";
+import { readdir as readdir6, rename as rename3 } from "fs/promises";
 
 // src/domains/session/release.ts
 function buildReleasePaths(sessionId, config) {
@@ -9848,7 +10151,7 @@ var SESSION_RELEASE_OUTPUT = {
 };
 async function loadDoingSessions(config) {
   try {
-    const files = await readdir5(config.doingDir);
+    const files = await readdir6(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 === SESSION_FILE_ERROR_CODE.NOT_FOUND) {
@@ -9885,12 +10188,12 @@ async function releaseCommand(options) {
 }
 
 // src/commands/session/show.ts
-import { readFile as readFile7, stat as stat5 } from "fs/promises";
+import { readFile as readFile8, stat as stat6 } from "fs/promises";
 async function findExistingPath(paths, _config) {
   for (let i = 0; i < paths.length; i++) {
     const filePath = paths[i];
     try {
-      const stats = await stat5(filePath);
+      const stats = await stat6(filePath);
       if (stats.isFile()) {
         return { path: filePath, status: SEARCH_ORDER[i] };
       }
@@ -9905,7 +10208,7 @@ async function resolveSession(sessionId, config) {
   if (!found) {
     throw new SessionNotFoundError(sessionId);
   }
-  const content = await readFile7(found.path, SESSION_FILE_ENCODING);
+  const content = await readFile8(found.path, SESSION_FILE_ENCODING);
   return { status: found.status, path: found.path, content };
 }
 async function showSingle(sessionId, config) {
@@ -10569,7 +10872,7 @@ var sessionDomain = {
 };
 
 // src/lib/spec-tree/index.ts
-import { readdir as readdir6, readFile as readFile8 } from "fs/promises";
+import { readdir as readdir7, readFile as readFile9 } from "fs/promises";
 import { join as join14 } from "path";
 var SPEC_TREE_FIELD_KEY = {
   VERSION: "version",
@@ -10654,7 +10957,7 @@ function createFilesystemSpecTreeSource(options) {
       if (ref.path === void 0) {
         throw new Error("Filesystem source refs require a path");
       }
-      return readFile8(join14(options.productDir, ref.path), SPEC_TREE_TEXT_ENCODING);
+      return readFile9(join14(options.productDir, ref.path), SPEC_TREE_TEXT_ENCODING);
     }
   };
 }
@@ -10945,7 +11248,7 @@ async function* readFilesystemSourceEntries(productDir, registry, schemaVersions
 async function* walkFilesystemDirectory(context) {
   let entries;
   try {
-    entries = await readdir6(context.absolutePath, { withFileTypes: true });
+    entries = await readdir7(context.absolutePath, { withFileTypes: true });
   } catch (error) {
     if (isFileNotFound2(error)) return;
     throw error;
@@ -11117,7 +11420,7 @@ function formatNextNode(node) {
 }
 
 // src/commands/test/discovery.ts
-import { readdir as readdir7 } from "fs/promises";
+import { readdir as readdir8 } from "fs/promises";
 import { join as join15, relative as relative2, sep as sep2 } from "path";
 var TESTS_DIRECTORY_NAME = SPEC_TREE_EVIDENCE_FILE.DIRECTORY_NAME;
 var SPEC_ROOT_DIRECTORY = SPEC_TREE_CONFIG.ROOT_DIRECTORY;
@@ -11131,7 +11434,7 @@ async function discoverTestFiles(productDir) {
 async function collectTestFiles(directory, insideTestsDir, found) {
   let entries;
   try {
-    entries = await readdir7(directory, { withFileTypes: true });
+    entries = await readdir8(directory, { withFileTypes: true });
   } catch (error) {
     if (hasErrorCode2(error, ERROR_CODE_NOT_FOUND2)) return;
     throw error;
@@ -12542,7 +12845,7 @@ function createNodeStatusProvider(productDir) {
 }
 
 // src/lib/node-status/update.ts
-import { mkdir as mkdir4, readdir as readdir8, rm, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir4, readdir as readdir9, rm, writeFile as writeFile2 } from "fs/promises";
 import { dirname as dirname8, join as join21 } from "path";
 
 // src/git/tracked-paths.ts
@@ -12666,7 +12969,7 @@ async function collectNodeStatusFiles(directory) {
 }
 async function readDirectoryEntries(directory) {
   try {
-    return await readdir8(directory, { withFileTypes: true });
+    return await readdir9(directory, { withFileTypes: true });
   } catch (error) {
     if (isNodeError3(error) && error.code === "ENOENT") return [];
     throw error;
@@ -13275,7 +13578,7 @@ var testingRegistry = {
 
 // src/interfaces/cli/test-runner-deps.ts
 import { createWriteStream } from "fs";
-import { mkdtemp, readFile as readFile9 } from "fs/promises";
+import { mkdtemp, readFile as readFile10 } from "fs/promises";
 import { tmpdir } from "os";
 import { join as join23 } from "path";
 import { finished } from "stream/promises";
@@ -13325,7 +13628,7 @@ function createRunnerDepsFor(productDir, outStream = process.stdout) {
 }
 function createRelatedDepsFor(productDir) {
   const runCommand = createRelatedCommandRunner(productDir);
-  return () => ({ runCommand, readFile: (path7) => readFile9(join23(productDir, path7), "utf8") });
+  return () => ({ runCommand, readFile: (path7) => readFile10(join23(productDir, path7), "utf8") });
 }
 function artifactFileName(index, suffix) {
   return `${index.toString(ARTIFACT_INDEX_RADIX).padStart(ARTIFACT_INDEX_WIDTH, "0")}-${suffix}`;
@@ -17025,11 +17328,11 @@ function formatLintResult(result, quiet, durationMs) {
 }
 
 // src/validation/literal/index.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 import { isAbsolute as isAbsolute9, relative as relative7, resolve as resolve10 } from "path";
 
 // src/lib/file-inclusion/pipeline.ts
-import { readdir as readdir9, readFile as readFile10, stat as stat6 } from "fs/promises";
+import { readdir as readdir10, readFile as readFile11, stat as stat7 } from "fs/promises";
 import { join as join33, relative as relative6, sep as sep3 } from "path";
 
 // src/lib/file-inclusion/ignore-source.ts
@@ -17335,7 +17638,7 @@ function isNodeError4(err) {
 }
 async function isDirectory(absolutePath) {
   try {
-    return (await stat6(absolutePath)).isDirectory();
+    return (await stat7(absolutePath)).isDirectory();
   } catch (err) {
     if (isNodeError4(err) && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
       return false;
@@ -17345,7 +17648,7 @@ async function isDirectory(absolutePath) {
 }
 async function isGitdirPointerFile(absolutePath) {
   try {
-    const content = await readFile10(absolutePath, "utf8");
+    const content = await readFile11(absolutePath, "utf8");
     return content.startsWith(GITDIR_POINTER_PREFIX);
   } catch (err) {
     if (isNodeError4(err) && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
@@ -17356,7 +17659,7 @@ async function isGitdirPointerFile(absolutePath) {
 }
 async function readDirectoryEntries2(absoluteDir) {
   try {
-    return await readdir9(absoluteDir, { withFileTypes: true });
+    return await readdir10(absoluteDir, { withFileTypes: true });
   } catch (err) {
     if (isNodeError4(err) && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
       return [];
@@ -17969,7 +18272,7 @@ async function validateLiteralReuse(input) {
 }
 async function readSafe(path7) {
   try {
-    return await readFile11(path7, "utf8");
+    return await readFile12(path7, "utf8");
   } catch (err) {
     if (typeof err === "object" && err !== null && "code" in err) {
       const code = err.code;
@@ -19264,7 +19567,7 @@ var verificationContextDomain = {
 };
 
 // src/interfaces/cli/verify.ts
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile13 } from "fs/promises";
 
 // src/commands/verify/cli.ts
 import { dirname as dirname12 } from "path";
@@ -19741,7 +20044,7 @@ async function readStdinText() {
 }
 async function readCliSource(source) {
   if (source === VERIFY_INPUT_SOURCE.STDIN) return readStdinText();
-  return readFile12(source, CLI_SOURCE_ENCODING);
+  return readFile13(source, CLI_SOURCE_ENCODING);
 }
 var verifyDomain = {
   name: VERIFY_CLI.commandName,
@@ -19927,11 +20230,11 @@ function renderTextStatusChild(record6) {
 }
 
 // src/lib/worktree-path-info.ts
-import { stat as stat7 } from "fs/promises";
+import { stat as stat8 } from "fs/promises";
 var defaultWorktreePathInfo = {
   isExistingNonDirectory: async (path7) => {
     try {
-      const pathStats = await stat7(path7);
+      const pathStats = await stat8(path7);
       return !pathStats.isDirectory();
     } catch {
       return false;