commandmate 0.29.0 → 0.29.2

package/dist/server/src/lib/selected-agents-validator.js

@@ -5,12 +5,14 @@
  *
  * Provides:
  * - validateAgentsPair(): Core validation logic (R1-001)
+ * - resolveSelectedAgents(): the ONE place the fallback order lives (Issue #2065)
  * - parseSelectedAgents(): DB read with fallback + console.warn (R4-005 log sanitization)
  * - validateSelectedAgentsInput(): API input validation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SELECTED_AGENTS = exports.MAX_SELECTED_AGENTS = exports.MIN_SELECTED_AGENTS = void 0;
+exports.SELECTED_AGENTS_LAYERS = exports.DEFAULT_SELECTED_AGENTS = exports.MAX_SELECTED_AGENTS = exports.MIN_SELECTED_AGENTS = void 0;
 exports.validateAgentsPair = validateAgentsPair;
+exports.resolveSelectedAgents = resolveSelectedAgents;
 exports.parseSelectedAgents = parseSelectedAgents;
 exports.validateSelectedAgentsInput = validateSelectedAgentsInput;
 const types_1 = require("./cli-tools/types");
@@ -19,14 +21,19 @@ exports.MIN_SELECTED_AGENTS = 2;
 /** Maximum number of selected agents (PC can select up to 6, Issue #989) */
 exports.MAX_SELECTED_AGENTS = 6;
 /**
- * Default selected agents when DB value is missing or invalid.
+ * Compiled-in last resort for a worktree's agent list.
  * Issue #1516: narrowed to the 3 agents in routine use (claude/codex/antigravity).
  * The others stay selectable via CLI_TOOL_IDS — they are just not preselected.
+ *
+ * Issue #2065: this is no longer the only answer. It is the LOWEST layer of
+ * `resolveSelectedAgents()` — the value a fresh install with no `app_settings`
+ * row still gets, which is why the acceptance criterion "an environment with no
+ * setting behaves exactly as before" reduces to "this constant is unchanged".
  */
 exports.DEFAULT_SELECTED_AGENTS = ['claude', 'codex', 'antigravity'];
 /**
  * Core validation function for CLI tool ID arrays (R1-001)
- * Accepts 2-5 unique valid CLI tool IDs (Issue #836).
+ * Accepts 2-6 unique valid CLI tool IDs (Issue #836 raised it to 5, #989 to 6).
  * Shared between parseSelectedAgents() and validateSelectedAgentsInput()
  *
  * @param input - Array of values to validate
@@ -44,36 +51,99 @@ function validateAgentsPair(input) {
     }
     return { valid: true, value: input };
 }
+/**
+ * The layers that can answer "which agents does this worktree show", highest
+ * priority first (Issue #2065).
+ *
+ * This array IS the priority order — `resolveSelectedAgents()` walks it in
+ * sequence and nothing else encodes it. The final shape the Epic is heading for
+ * is `worktree -> repo file -> app_settings -> constant`; #2065 populated the
+ * `worktree` and `appSettings` layers and declared `repo` without ever passing
+ * it a value.
+ *
+ * Issue #2066 filled `repo` in, exactly as that comment foresaw: by supplying a
+ * value at the call sites, and NOT by re-deriving an order. This array is still
+ * the only place the order is written down, and the function below is unchanged.
+ *
+ * There are exactly TWO such call sites, both in `@/lib/db/worktree-db`:
+ * `getWorktrees()` and `getWorktreeById()`, each reading
+ * `getRepoDefaultSelectedAgents()` from `@/lib/repo-config/agents-config`.
+ * `resolveAgentInstances()` is NOT one of them — it receives the already
+ * resolved value as its `selectedAgents` argument, and giving it a second entry
+ * point would have been an argument no production caller passes.
+ *
+ * A layer whose value is absent, malformed, or fails `validateAgentsPair()` is
+ * skipped rather than fatal: a hand-edited `app_settings` row must not be able
+ * to make every worktree in the sidebar render an empty tab strip.
+ */
+exports.SELECTED_AGENTS_LAYERS = ['worktree', 'repo', 'appSettings'];
+/**
+ * Resolve a worktree's agent list from the layers, in priority order.
+ *
+ * The ONE place the fallback order lives (Issue #2065). Every fallback — server
+ * or client, roster seed or tab seed — goes through this function so a new layer
+ * is a change to `SELECTED_AGENTS_LAYERS` plus a value at the call sites, and
+ * never a second copy of the order.
+ *
+ * @param layers - Candidate values keyed by layer; omit a layer you cannot answer for
+ * @returns The first layer that validates, else {@link DEFAULT_SELECTED_AGENTS}
+ */
+function resolveSelectedAgents(layers = {}) {
+    for (const layer of exports.SELECTED_AGENTS_LAYERS) {
+        const candidate = layers[layer];
+        if (candidate == null)
+            continue;
+        const result = validateAgentsPair([...candidate]);
+        if (result.valid)
+            return result.value;
+    }
+    return exports.DEFAULT_SELECTED_AGENTS;
+}
 /**
  * Parse selected_agents JSON from DB with safe fallback
- * Returns default value for any invalid input (never throws)
+ * Returns the resolved default for any invalid input (never throws)
  *
- * Logs a warning when fallback is triggered to help detect DB data issues.
  * Log output is sanitized (R4-005): ANSI stripped, newlines removed, truncated.
  *
+ * Issue #2065: the fallback is no longer the constant but
+ * `resolveSelectedAgents()`, so a row with no `selected_agents` (every worktree
+ * created by scan/sync — `upsertWorktree` never writes the column) picks up the
+ * `app_settings` default. Callers that have a `db` handle pass
+ * `appSettingsDefault`; callers that do not (unit fixtures, pure helpers) omit
+ * it and get exactly the pre-#2065 behaviour.
+ *
+ * Issue #2066 adds `repoDefault`, the repository's own `.commandmate/agents.yaml`
+ * declaration. It is LAST in the parameter list and SECOND in priority — the
+ * order the layers resolve in lives in {@link SELECTED_AGENTS_LAYERS} and
+ * nowhere else, so an argument position is free to be chosen for what it is
+ * good for: every existing two-argument call keeps its meaning unchanged, which
+ * is what makes "an environment with no file behaves exactly as before" a
+ * property of the signature rather than of a review.
+ *
  * @param raw - Raw JSON string from DB (or null)
- * @returns Validated array of 2-5 CLIToolType values
+ * @param appSettingsDefault - Server-wide default from `app_settings`, or null/undefined when unset
+ * @param repoDefault - Repository declaration from `.commandmate/agents.yaml`, or null/undefined when absent/invalid
+ * @returns Validated array of 2-6 CLIToolType values
  */
-function parseSelectedAgents(raw) {
-    if (!raw)
-        return exports.DEFAULT_SELECTED_AGENTS;
-    try {
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed)) {
-            // invalid format - return default silently
-            return exports.DEFAULT_SELECTED_AGENTS;
+function parseSelectedAgents(raw, appSettingsDefault, repoDefault) {
+    let fromRow = null;
+    if (raw) {
+        try {
+            const parsed = JSON.parse(raw);
+            // A non-array (or a JSON parse error) is treated the same as an absent
+            // column: skip the layer silently and let the lower ones answer.
+            if (Array.isArray(parsed))
+                fromRow = parsed;
         }
-        const result = validateAgentsPair(parsed);
-        if (!result.valid) {
-            // validation failed - return default silently
-            return exports.DEFAULT_SELECTED_AGENTS;
+        catch {
+            // JSON parse error - fall through to the lower layers
         }
-        return result.value;
-    }
-    catch {
-        // JSON parse error - return default silently
-        return exports.DEFAULT_SELECTED_AGENTS;
     }
+    return resolveSelectedAgents({
+        worktree: fromRow,
+        repo: repoDefault,
+        appSettings: appSettingsDefault,
+    });
 }
 /**
  * Validate selectedAgents input from API request body

package/dist/server/src/lib/session/claude-session.js

@@ -19,6 +19,9 @@ exports.stopClaudeSession = stopClaudeSession;
 exports.restartClaudeSession = restartClaudeSession;
 const tmux_1 = require("../../lib/tmux/tmux");
 const cli_patterns_1 = require("../../lib/detection/cli-patterns");
+const tool_liveness_1 = require("../../lib/detection/tool-liveness");
+const liveness_spec_1 = require("../../lib/cli-tools/liveness-spec");
+const session_liveness_1 = require("../../lib/cli-tools/session-liveness");
 const session_key_sender_1 = require("../../lib/session-key-sender");
 const child_process_1 = require("child_process");
 const util_1 = require("util");
@@ -45,22 +48,20 @@ function getErrorMessage(error) {
 }
 // ----- Shell Prompt Detection Constants -----
 /**
- * Shell prompt ending characters for detecting shell-only tmux sessions
- * Extensible array to support multiple shell types (MF-002: OCP)
- * Placed in claude-session.ts as private constant (SF-S2-002: ISP - used only by isSessionHealthy())
- * - '$': bash/sh default prompt
- * - '%': zsh default prompt
- * - '#': root prompt (bash/zsh)
- *
- * C-S2-002: False positive risk assessment:
- * These characters are checked only at the END of trimmed output. This limits false
- * positives to cases where Claude CLI output ends with one of these characters
- * (e.g., output containing "$" at end of a code block). The risk is acceptable because:
- * (1) Claude CLI output typically ends with a prompt (❯) or thinking indicator, not shell chars
- * (2) A false positive triggers session recreation, which is a safe recovery action
- * (3) The check is combined with error pattern detection for multiple signals
+ * Issue #2070: the shell-prompt endings, the 40-character gate and the
+ * error-pattern tail this module used to declare privately are now
+ * `SHELL_PROMPT_ENDINGS` / `MAX_SHELL_PROMPT_LENGTH` / `FATAL_PATTERN_TAIL_LINES`
+ * in `lib/detection/tool-liveness`, and claude's use of them is
+ * `resolveLivenessSpec('claude')`.
+ *
+ * They moved because the rule they describe was never claude-specific — only
+ * these values were. A tmux session that outlives its agent looks the same for
+ * codex, copilot, opencode and gemini, and every one of them reported `running`
+ * for a pane that had fallen back to the shell, because the only check for it
+ * sat behind `cliToolId === 'claude'`. The values themselves are unchanged, and
+ * `tests/unit/lib/claude-session.test.ts` still pins every verdict this
+ * function reaches.
  */
-const SHELL_PROMPT_ENDINGS = ['$', '%', '#'];
 // ----- Timeout and Polling Constants (OCP-001) -----
 // These constants are exported to allow configuration and testing.
 // Changing these values affects Claude CLI session startup behavior.
@@ -160,27 +161,12 @@ exports.CLAUDE_SEND_PROMPT_WAIT_TIMEOUT = 10000;
  */
 exports.CLAUDE_PROMPT_POLL_INTERVAL = 200;
 /**
- * Maximum expected length of a shell prompt line (characters)
- *
- * Shell prompts are typically under 40 characters (e.g., "user@host:~/project$" ~30 chars).
- * Lines at or above this threshold are not considered shell prompts, preventing
- * false positives from Claude CLI output that happens to end with $, %, or #.
- *
- * Used by isSessionHealthy() to distinguish shell prompts from CLI output.
- * 40 is an empirical threshold with safety margin.
- */
-const MAX_SHELL_PROMPT_LENGTH = 40;
-/**
- * Number of tail lines used for error pattern detection in isSessionHealthy()
- *
- * Error patterns are only searched within the last N lines of pane output,
- * not the entire buffer. This prevents false negatives where historical
- * (already recovered) errors in the scrollback trigger unhealthy detection.
- *
- * 10 lines provides sufficient window to catch recent errors while ignoring
- * historical ones that have scrolled up.
+ * Issue #2070: `MAX_SHELL_PROMPT_LENGTH` and `HEALTH_CHECK_ERROR_TAIL_LINES`
+ * moved to `lib/detection/tool-liveness` with the rule that reads them. Their
+ * values are unchanged and claude reaches them through
+ * `resolveLivenessSpec('claude')`.
  */
-const HEALTH_CHECK_ERROR_TAIL_LINES = 10;
+const CLAUDE_LIVENESS_SPEC = (0, liveness_spec_1.resolveLivenessSpec)('claude');
 /**
  * Cached Claude CLI path
  */
@@ -294,30 +280,17 @@ async function getCleanPaneOutput(sessionName, lines = 50) {
  * already printed "Claude Code cannot be launched inside another Claude Code
  * session" must not sit there burning the whole budget before saying so.
  *
- * Only the last {@link HEALTH_CHECK_ERROR_TAIL_LINES} lines are searched, so a
- * historical error that has scrolled up cannot condemn a session that recovered.
+ * Only the last `FATAL_PATTERN_TAIL_LINES` lines are searched, so a historical
+ * error that has scrolled up cannot condemn a session that recovered.
+ *
+ * Issue #2070: the search itself is `findFatalPattern`, shared with every other
+ * tool's liveness probe; claude's patterns ride in its `ToolLivenessSpec`.
  *
  * @param cleanOutput - ANSI-stripped pane output
  * @returns The matched pattern (or regex source) for the log, or null
  */
 function findSessionErrorPattern(cleanOutput) {
-    const allLines = cleanOutput
-        .trim()
-        .split('\n')
-        .filter((line) => line.trim() !== '');
-    const tailText = allLines.slice(-HEALTH_CHECK_ERROR_TAIL_LINES).join('\n');
-    // MF-001: Check error patterns from cli-patterns.ts (SRP - pattern management centralized)
-    for (const pattern of cli_patterns_1.CLAUDE_SESSION_ERROR_PATTERNS) {
-        if (tailText.includes(pattern)) {
-            return pattern;
-        }
-    }
-    for (const regex of cli_patterns_1.CLAUDE_SESSION_ERROR_REGEX_PATTERNS) {
-        if (regex.test(tailText)) {
-            return regex.source;
-        }
-    }
-    return null;
+    return (0, tool_liveness_1.findFatalPattern)(cleanOutput, CLAUDE_LIVENESS_SPEC);
 }
 /**
  * Verify that Claude CLI is actually running inside a tmux session
@@ -327,64 +300,22 @@ function findSessionErrorPattern(cleanOutput) {
  * Used by worktrees/route.ts and worktrees/[id]/route.ts for
  * health-aware session status with listSessions() batch optimization.
  *
+ * Issue #2070: the algorithm moved to `judgeToolLiveness`, which is the same
+ * rule read through claude's `ToolLivenessSpec`. Every branch, every reason
+ * string and every ordering decision this function used to spell inline is
+ * preserved there — the empty-output verdict, the whole-frame
+ * `CLAUDE_PROMPT_PATTERN` check BEFORE the error patterns (so a recovered
+ * session is not condemned by scrollback), the 40-character gate, and the
+ * `\d+%$` carve-out that keeps `Context left until auto-compact: 7%` from
+ * reading as a zsh prompt. What changed is that six other tools can now be
+ * asked the same question; see `lib/cli-tools/liveness-spec`.
+ *
  * @param sessionName - tmux session name
  * @returns HealthCheckResult with healthy status and optional reason
  */
 async function isSessionHealthy(sessionName) {
-    try {
-        // SF-001: Use shared helper instead of inline capturePane + stripAnsi
-        const cleanOutput = await getCleanPaneOutput(sessionName);
-        // MF-002: Check shell prompt endings from extensible array (OCP)
-        const trimmed = cleanOutput.trim();
-        // S2-F010: Empty output judgment (HealthCheckResult format)
-        // C-S2-001: Empty output means tmux session exists but Claude CLI has no output.
-        // This is treated as unhealthy because a properly running Claude CLI always
-        // produces output (prompt, spinner, or response). An empty pane indicates
-        // the CLI process has exited or failed to start.
-        if (trimmed === '') {
-            return { healthy: false, reason: 'empty output' };
-        }
-        // Active state detection: check for Claude prompt BEFORE error patterns.
-        // This prevents false negatives where historical (recovered) errors in
-        // the pane scrollback cause a currently-active session to be marked unhealthy.
-        if (cli_patterns_1.CLAUDE_PROMPT_PATTERN.test(trimmed)) {
-            return { healthy: true };
-        }
-        // S2-F010: Error pattern detection - limited to tail lines only.
-        // Only the last HEALTH_CHECK_ERROR_TAIL_LINES lines are searched, so
-        // historical errors that have scrolled up do not trigger false negatives.
-        const allLines = trimmed.split('\n').filter(line => line.trim() !== '');
-        const errorPattern = findSessionErrorPattern(trimmed);
-        if (errorPattern !== null) {
-            return { healthy: false, reason: `error pattern: ${errorPattern}` };
-        }
-        // S2-F002: Extract last line after empty line filtering
-        const lastLine = allLines[allLines.length - 1]?.trim() ?? '';
-        // F006: Line length check BEFORE SHELL_PROMPT_ENDINGS check (early return)
-        if (lastLine.length >= MAX_SHELL_PROMPT_LENGTH) {
-            // Long lines are not shell prompts -> treat as healthy (early return)
-            return { healthy: true };
-        }
-        // F003: Individual pattern exclusions for SHELL_PROMPT_ENDINGS
-        // NOTE(F003): If new false positive patterns are found in the future,
-        // consider refactoring to a structure that associates exclusionPattern
-        // with each SHELL_PROMPT_ENDINGS entry. Currently only % needs exclusion (YAGNI).
-        if (SHELL_PROMPT_ENDINGS.some(ending => {
-            if (!lastLine.endsWith(ending))
-                return false;
-            // Exclude N% pattern (e.g., "Context left until auto-compact: 7%")
-            if (ending === '%' && /\d+%$/.test(lastLine))
-                return false;
-            return true;
-        })) {
-            return { healthy: false, reason: `shell prompt ending detected: ${lastLine}` };
-        }
-        return { healthy: true };
-    }
-    catch {
-        // S3-F001: Catch block also returns HealthCheckResult format
-        return { healthy: false, reason: 'capture error' };
-    }
+    const verdict = await (0, session_liveness_1.probeSessionLiveness)(sessionName, CLAUDE_LIVENESS_SPEC);
+    return verdict.alive ? { healthy: true } : { healthy: false, reason: verdict.reason };
 }
 /**
  * Ensure the existing tmux session has a healthy Claude CLI process

package/dist/server/src/lib/tmux/tmux.js

@@ -9,6 +9,7 @@ exports.exactTarget = exactTarget;
 exports.reconcileSessionGeometry = reconcileSessionGeometry;
 exports.isTmuxAvailable = isTmuxAvailable;
 exports.hasSession = hasSession;
+exports.getSessionWorkingDirectory = getSessionWorkingDirectory;
 exports.listSessions = listSessions;
 exports.createSession = createSession;
 exports.sendKeys = sendKeys;
@@ -155,6 +156,34 @@ async function hasSession(sessionName) {
         return false;
     }
 }
+/**
+ * The directory a session was created in, or null (Issue #2070).
+ *
+ * `#{session_path}` rather than `#{pane_current_path}`: the two differ as soon
+ * as anything types `cd`, and only the first one is still the worktree root the
+ * session was opened on. Measured on tmux 3.5a — a session created with
+ * `-c /private/tmp` whose shell then `cd /usr`'d reported
+ * `session_path=/private/tmp`, `pane_current_path=/usr`.
+ *
+ * Read by `BaseCLITool.relaunchIfToolExited`, which needs the worktree path to
+ * rebuild a launch line for a pane whose agent has died. The pane itself is the
+ * right source for it: a worktree row could have been moved or deleted since,
+ * while the directory the pane is actually sitting in is the directory the
+ * relaunched agent will actually run in.
+ *
+ * @param sessionName - Target session name
+ * @returns The session's working directory, or null when tmux cannot say
+ */
+async function getSessionWorkingDirectory(sessionName) {
+    try {
+        const { stdout } = await execFileAsync('tmux', ['display-message', '-p', '-t', exactTarget(sessionName), '#{session_path}'], { timeout: DEFAULT_TIMEOUT });
+        const dir = stdout.trim();
+        return dir === '' ? null : dir;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * List all tmux sessions
  *