commandmate 0.22.2 → 0.23.0

package/dist/server/src/lib/git/git-default-branch.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Repository default-branch resolution (origin/HEAD).
+ * Issue #921: extracted from git-utils.ts (god-module split, P1-a).
+ *
+ * Shared by reset / deleteBranch / push protection (Issue #783, DR1-001).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BRANCH_UNRESOLVED = void 0;
+exports.getDefaultBranch = getDefaultBranch;
+exports.resolveDefaultBranchName = resolveDefaultBranchName;
+const git_exec_1 = require("./git-exec");
+/**
+ * Sentinel returned by getDefaultBranch when origin/HEAD is UNRESOLVED (the
+ * `symbolic-ref` read returned null). DISTINCT from `null` (which means
+ * symbolic-ref resolved to a value that is NOT an `origin/` ref). Issue #783,
+ * DR1-002: callers must distinguish "unresolved" from "resolved-but-non-origin/"
+ * so the reset fallback only fires on TRUE unresolution.
+ */
+exports.DEFAULT_BRANCH_UNRESOLVED = Symbol('default-branch-unresolved');
+/**
+ * Resolve the repository default branch name via origin/HEAD (Issue #783,
+ * shared by reset / deleteBranch / push protection — DR1-001).
+ *
+ * Returns THREE distinguishable outcomes (DR1-002 — required for reset's
+ * byte-invariance):
+ *   - string                    : origin/<name> resolved; returns <name> (e.g. "main")
+ *   - DEFAULT_BRANCH_UNRESOLVED : symbolic-ref returned null (origin/HEAD unresolved)
+ *   - null                      : symbolic-ref returned a value that is NOT an
+ *                                 `origin/` ref (unexpected value)
+ *
+ * Keeping "unresolved" and "resolved-but-non-origin/" separate lets
+ * isDefaultBranchForReset's main/master fallback fire ONLY when truly unresolved,
+ * preserving the original behavior (a naive `startsWith ? slice : null` would
+ * collapse the non-origin/ case into null and wrongly trigger the fallback).
+ */
+async function getDefaultBranch(worktreePath) {
+    // DR2-006: execGitCommand returns an already-trimmed string on success / null
+    // on failure, so out is trimmed; the out.trim() below is an idempotent (harmless)
+    // double-trim. The "trimmed string / null" pair maps cleanly onto the 3 values:
+    //   UNRESOLVED (out===null) / resolved name (startsWith 'origin/') / non-origin/ (else -> null).
+    // Empty-string edge: if symbolic-ref returned '' (non-null), v='' -> startsWith
+    // false -> null, matching the original isDefaultBranchForReset behavior.
+    const out = await (0, git_exec_1.execGitCommand)(['symbolic-ref', 'refs/remotes/origin/HEAD', '--short'], worktreePath);
+    if (out === null)
+        return exports.DEFAULT_BRANCH_UNRESOLVED;
+    const v = out.trim();
+    return v.startsWith('origin/') ? v.slice('origin/'.length) : null;
+}
+/**
+ * Thin wrapper for callers that only want "the resolved default name, or null
+ * when unknown" (Issue #783, DR1-001). Collapses both DEFAULT_BRANCH_UNRESOLVED
+ * and the non-origin/ `null` into `null` (= default name unknown). Used by
+ * deleteBranch (no fallback) and push protection (null = unprotected).
+ */
+async function resolveDefaultBranchName(worktreePath) {
+    const r = await getDefaultBranch(worktreePath);
+    return typeof r === 'string' ? r : null;
+}

package/dist/server/src/lib/hooks/agent-event-service.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Effects of a structured agent event (Issue #1549, Phase 3-2).
+ *
+ * The agent CLI is the only party that knows for certain that it finished a
+ * turn. Everything else in this codebase infers it by reading the terminal
+ * frame. This module is the first-class path: an event the agent itself sent,
+ * turned into a `task_events` row and — when the contract asks for it — a
+ * verification run.
+ *
+ * It does not replace the string analysis. `detectSessionStatus` keeps running
+ * and keeps deciding, because a hook only exists when a human wired one up and
+ * a completion mechanism that silently does nothing on an unconfigured machine
+ * is worse than one that is merely imprecise everywhere.
+ *
+ * Server-only: touches the filesystem (realpath) and the database.
+ *
+ * @module lib/hooks/agent-event-service
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CWD_LENGTH = exports.isAgentEventType = exports.AGENT_EVENT_TYPES = void 0;
+exports.validateHookCwd = validateHookCwd;
+exports.resolveWorktreeByCwd = resolveWorktreeByCwd;
+exports.applyAgentStopEvent = applyAgentStopEvent;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const db_1 = require("../../lib/db");
+const tasks_db_1 = require("../../lib/db/tasks-db");
+const path_validator_1 = require("../../lib/security/path-validator");
+const task_transition_service_1 = require("../../lib/tasks/task-transition-service");
+const gate_runner_1 = require("../../lib/verification/gate-runner");
+const agent_event_state_1 = require("../../lib/session/agent-event-state");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/hooks/agent-event-service');
+/**
+ * The event vocabulary lives in `agent-event-types` (Issue #1722) so the
+ * settings generator and the in-memory state can use it without importing this
+ * module's database and verification dependencies. Re-exported here because
+ * this is where callers have always found it.
+ *
+ * The Claude-specific mapping helpers that used to be re-exported alongside
+ * them are gone (Issue #1759): a tool's spellings now belong to that tool's
+ * `AgentEventSource`, and re-exporting one tool's from the generic service
+ * would have made this module the next place a Phase 4-x implementer reached
+ * for. Ask `getAgentEventSource(cliToolId).normalizeEvent()` instead.
+ *
+ * Every kind but `stop` is accepted, recorded and exposed without changing any
+ * state: the receiver has to exist before agents can be told to send them, and
+ * rejecting them would make every hook config a two-step rollout.
+ */
+var agent_event_types_1 = require("../../lib/hooks/agent-event-types");
+Object.defineProperty(exports, "AGENT_EVENT_TYPES", { enumerable: true, get: function () { return agent_event_types_1.AGENT_EVENT_TYPES; } });
+Object.defineProperty(exports, "isAgentEventType", { enumerable: true, get: function () { return agent_event_types_1.isAgentEventType; } });
+/** Bound on the accepted `cwd`, comfortably above PATH_MAX on every supported platform. */
+exports.MAX_CWD_LENGTH = 4096;
+/**
+ * Reject a `cwd` that cannot be a legitimate agent working directory.
+ *
+ * A hook posts the directory the agent is running in, so the only shapes worth
+ * accepting are absolute, traversal-free paths. `..` is refused rather than
+ * normalised away: `resolve()` would happily turn `/repos/a/../../etc` into a
+ * path that looks nothing like what the caller sent, and a value that changes
+ * meaning between validation and use is exactly how traversal checks get
+ * defeated. Percent-encoding is decoded first, so `%2e%2e%2f` cannot smuggle a
+ * `..` past a raw string scan.
+ */
+function validateHookCwd(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        return { ok: false, reason: 'empty' };
+    }
+    if (raw.length > exports.MAX_CWD_LENGTH) {
+        return { ok: false, reason: 'too_long' };
+    }
+    let decoded = raw;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        // Not valid percent-encoding; the raw string is the only interpretation.
+        decoded = raw;
+    }
+    if (raw.includes('\0') || decoded.includes('\0')) {
+        return { ok: false, reason: 'nul_byte' };
+    }
+    if (!(0, path_1.isAbsolute)(raw)) {
+        return { ok: false, reason: 'not_absolute' };
+    }
+    if (hasTraversalSegment(raw) || hasTraversalSegment(decoded)) {
+        return { ok: false, reason: 'traversal' };
+    }
+    return { ok: true, cwd: raw };
+}
+/** True when any path segment is `..`, under either separator convention. */
+function hasTraversalSegment(value) {
+    return value
+        .split(path_1.sep === '\\' ? /[\\/]/ : '/')
+        .some((segment) => segment === '..');
+}
+/**
+ * The registered worktree an agent's `cwd` belongs to, or null.
+ *
+ * Both sides are resolved through `realpath` before comparison because the two
+ * ends disagree routinely and harmlessly: macOS hands agents `/var/...` for a
+ * worktree stored as `/private/var/...`, and worktree roots are often symlinked.
+ *
+ * A descendant matches its worktree — agents commonly run from a subdirectory —
+ * and the longest match wins, so a worktree nested inside another resolves to
+ * the inner one rather than to whichever row the database returned first.
+ *
+ * @param cwd - Already through {@link validateHookCwd}
+ * @returns null when the path does not exist or belongs to no worktree; the
+ *   caller must not distinguish those two cases to the client
+ */
+function resolveWorktreeByCwd(db, cwd) {
+    const resolvedCwd = safeRealpath(cwd);
+    if (resolvedCwd === null) {
+        return null;
+    }
+    let best = null;
+    let bestLength = -1;
+    for (const worktree of (0, db_1.getWorktrees)(db)) {
+        const resolvedWorktree = safeRealpath(worktree.path);
+        if (resolvedWorktree === null)
+            continue;
+        if (!(0, path_validator_1.isWithinRoot)(resolvedCwd, resolvedWorktree))
+            continue;
+        if (resolvedWorktree.length > bestLength) {
+            best = worktree;
+            bestLength = resolvedWorktree.length;
+        }
+    }
+    return best;
+}
+/** realpath, or null when the path does not exist / is unreadable. */
+function safeRealpath(target) {
+    try {
+        return (0, fs_1.realpathSync)(target);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Apply a `stop` event to whatever the worktree is currently doing.
+ *
+ * The no-op is the load-bearing case. Sessions with no contract, and therefore
+ * no task, are the overwhelming majority; for them this records the timestamp
+ * and returns. Nothing about the existing completion path changes.
+ *
+ * Never throws. A hook is fire-and-forget from a CLI's stop handler, and a
+ * failure here must not become the agent's problem.
+ */
+async function applyAgentStopEvent(db, worktree, cliToolId, instanceId) {
+    (0, agent_event_state_1.recordAgentStopEvent)(worktree.id, cliToolId, instanceId);
+    let task;
+    try {
+        task = (0, tasks_db_1.getActiveTaskForInstance)(db, worktree.id, cliToolId, instanceId);
+    }
+    catch (error) {
+        logger.warn('agent-stop-task-lookup-failed', {
+            worktreeId: worktree.id,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { taskId: null, taskEventApplied: false, verificationRunId: null };
+    }
+    if (!task) {
+        return { taskId: null, taskEventApplied: false, verificationRunId: null };
+    }
+    let taskEventApplied = false;
+    try {
+        const result = (0, task_transition_service_1.applyTaskEvent)(db, task.id, 'agent_idle', { source: 'hook' });
+        taskEventApplied = result !== null && result.toStatus !== null;
+    }
+    catch (error) {
+        logger.warn('agent-stop-event-failed', {
+            taskId: task.id,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!task.contract.success.autoVerifyOnStop) {
+        return { taskId: task.id, taskEventApplied, verificationRunId: null };
+    }
+    let verificationRunId = null;
+    try {
+        const { runId } = await (0, gate_runner_1.startVerification)({
+            worktreeId: worktree.id,
+            worktreePath: worktree.path,
+            instanceId,
+            taskId: task.id,
+            trigger: 'task',
+        });
+        verificationRunId = runId;
+    }
+    catch (error) {
+        // A run already in flight is the expected collision, not a fault: the agent
+        // stopping twice while gates execute is ordinary.
+        if (!(error instanceof gate_runner_1.VerificationConflictError)) {
+            logger.error('agent-stop-auto-verify-failed', {
+                taskId: task.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { taskId: task.id, taskEventApplied, verificationRunId };
+}

package/dist/server/src/lib/hooks/agent-event-types.js

@@ -9,19 +9,18 @@
  * runner. `agent-event-service` re-exports everything here, so existing
  * importers are unaffected.
  *
- * The mapping below is not derived from Claude Code's documentation. It is
- * derived from the payloads in `tests/fixtures/hooks/claude/`, captured from a
- * live v2.1.223 session in Issue #1721 and written up in
- * `docs/design/agent-hooks-live-verification.md`. Where the two disagree, the
- * fixtures win.
+ * **Nothing here names a tool.** It used to: `CLAUDE_HOOK_EVENT_NAMES` and
+ * `extractClaudeEventDetail` lived beside the words until Issue #1759 moved
+ * them to `lib/hooks/sources/hook-event-vocabulary`, where a source *selects*
+ * them. One tool's spellings sitting in the module every tool-agnostic consumer
+ * imports is how the next tool ends up appended to the same table instead of
+ * bringing its own — the copy-paste Epic #1720 exists to stop.
  *
  * @module lib/hooks/agent-event-types
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_EVENT_DETAIL_LENGTH = exports.CLAUDE_HOOK_EVENT_NAMES = exports.AGENT_EVENT_TYPES = void 0;
+exports.MAX_EVENT_DETAIL_LENGTH = exports.AGENT_EVENT_TYPES = void 0;
 exports.isAgentEventType = isAgentEventType;
-exports.mapClaudeHookEventName = mapClaudeHookEventName;
-exports.extractClaudeEventDetail = extractClaudeEventDetail;
 /**
  * Event kinds accepted by `POST /api/hooks/agent-event`.
  *
@@ -49,83 +48,5 @@ exports.AGENT_EVENT_TYPES = [
 function isAgentEventType(value) {
     return typeof value === 'string' && exports.AGENT_EVENT_TYPES.includes(value);
 }
-/**
- * Claude Code's own `hook_event_name` values, mapped onto the vocabulary above.
- *
- * An injected `type: "http"` hook posts Claude's payload verbatim — there is no
- * way to shape the body — so the receiver has to read Claude's spelling. Only
- * the events CommandMate injects are listed, and an unmapped name is refused
- * rather than silently filed under something else.
- *
- * `PermissionRequest` is absent because it has its own receiver: its response
- * body is a decision the agent obeys, which is the opposite contract to this
- * fire-and-forget route (#1724).
- *
- * `PostToolUse` **is** mapped, on the strength of a measurement taken for Issue
- * #1726 rather than of the #1721 spike, which recorded it as unobserved. Driving
- * a live v2.1.223 session on 2026-08-06 with a `PostToolUse` hook registered:
- *
- * ```
- * 15:36:04.112  PreToolUse   AskUserQuestion   (picker drawn)
- * 15:36:10.127  Notification permission_prompt (picker still up)
- * 15:36:28.643  PostToolUse  AskUserQuestion   (the human answered)
- * 15:36:29.992  Stop
- * ```
- *
- * It fires, and it is the precise signal — "this tool call is over" — where
- * `Stop` is "the turn is over" and can be minutes later if the agent keeps
- * working after the answer. Both are wired up; see `agent-event-state`.
- */
-exports.CLAUDE_HOOK_EVENT_NAMES = {
-    Stop: 'stop',
-    SubagentStop: 'stop',
-    Notification: 'notification',
-    SessionStart: 'session_start',
-    SessionEnd: 'session_end',
-    UserPromptSubmit: 'user_prompt_submit',
-    // Issue #1726. Injected with matcher `AskUserQuestion`, so in practice these
-    // only ever arrive for that tool — but the receiver re-reads `tool_name`
-    // rather than trusting the matcher, because a user's own settings.json is
-    // concatenated with the injected one and may register a wider matcher.
-    PreToolUse: 'pre_tool_use',
-    PostToolUse: 'post_tool_use',
-};
-/** @returns The event this `hook_event_name` maps to, or null when unmapped. */
-function mapClaudeHookEventName(value) {
-    if (typeof value !== 'string')
-        return null;
-    return exports.CLAUDE_HOOK_EVENT_NAMES[value] ?? null;
-}
 /** Bound on the stored `detail`; every observed value is a short enum-ish word. */
 exports.MAX_EVENT_DETAIL_LENGTH = 128;
-/**
- * The event's subtype, as a single short string, or null when it has none.
- *
- * Each event spells this differently and none of them share a field:
- *
- * - `Notification` → `notification_type` (`permission_prompt` / `idle_prompt`).
- *   This is also what a `Notification` matcher is tested against — **not**
- *   `message`, which is English prose for a human (D3).
- * - `SessionEnd` → `reason` (`clear` / `prompt_input_exit` / …)
- * - `SessionStart` → `source` (`startup` / `clear` / …)
- * - `PreToolUse` / `PostToolUse` → `tool_name` (`AskUserQuestion`), Issue #1726
- *
- * `Stop` and `UserPromptSubmit` have no subtype, so they answer null.
- */
-function extractClaudeEventDetail(event, payload) {
-    const field = event === 'notification'
-        ? 'notification_type'
-        : event === 'session_end'
-            ? 'reason'
-            : event === 'session_start'
-                ? 'source'
-                : event === 'pre_tool_use' || event === 'post_tool_use'
-                    ? 'tool_name'
-                    : null;
-    if (field === null)
-        return null;
-    const value = payload[field];
-    if (typeof value !== 'string' || value === '')
-        return null;
-    return value.slice(0, exports.MAX_EVENT_DETAIL_LENGTH);
-}

package/dist/server/src/lib/hooks/hook-settings-generator.js

@@ -28,6 +28,12 @@
  *  - **Every hook failure is fail-open.** A refused connection or a timeout
  *    costs the event, never the session.
  *
+ * Issue #1759 made this module *Claude's* config serialiser rather than *the*
+ * config serialiser: it is reached through `claudeAgentEventSource.prepareLaunch`
+ * (seams S3/S4/S5), and the four other hook tools each bring their own — their
+ * files live in different places, nest differently, and cannot use `type:"http"`
+ * at all. Nothing here changed; only who calls it did.
+ *
  * The generated file is written rather than passed inline. `--settings` does
  * accept a JSON string (D2), but the launch command travels to the CLI through
  * `tmux send-keys` as a single line, and a ~1 KB argument of braces, quotes and
@@ -55,8 +61,10 @@ const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+const safe_directory_1 = require("../../config/safe-directory");
 const env_1 = require("../../lib/env");
 const types_1 = require("../../lib/cli-tools/types");
+const tool_id_1 = require("../../lib/hooks/sources/claude/tool-id");
 const permission_request_payload_1 = require("../../lib/hooks/permission-request-payload");
 const logger_1 = require("../../lib/logger");
 const logger = (0, logger_1.createLogger)('lib/hooks/hook-settings-generator');
@@ -178,18 +186,25 @@ function isHookInjectionEnabled() {
 function isAuthTokenExpected() {
     return Boolean(process.env[exports.AUTH_TOKEN_ENV_VAR] || process.env.CM_AUTH_TOKEN_HASH);
 }
-/** Directory the generated settings files live in. */
+/**
+ * Directory the generated settings files live in.
+ *
+ * Issue #1774: `writeAgentHookSettings` calls `mkdirSync(…, {recursive:true})`
+ * on the result, so a value inside `/proc`, `/sys` or `/dev` would spin the
+ * event loop forever rather than throw — the fail-open `try/catch` below is
+ * never reached, because the call never returns. Such a value is refused here
+ * and the default is used.
+ */
 function getHookSettingsDirectory(options = {}) {
-    if (options.directory)
-        return options.directory;
-    const override = process.env.CM_AGENT_HOOKS_DIR;
-    if (override)
-        return override;
-    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'hooks');
+    const fallback = (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'hooks');
+    if (options.directory) {
+        return (0, safe_directory_1.resolveSafeDirectory)(options.directory, fallback, 'HookSettingsOptions.directory');
+    }
+    return (0, safe_directory_1.resolveSafeDirectory)(process.env.CM_AGENT_HOOKS_DIR, fallback, 'CM_AGENT_HOOKS_DIR');
 }
 /** The instance this settings file speaks for; primary when unspecified. */
 function resolveTargetInstanceId(target) {
-    const cliToolId = target.cliToolId ?? 'claude';
+    const cliToolId = target.cliToolId ?? tool_id_1.CLAUDE_CLI_TOOL_ID;
     const instanceId = target.instanceId ?? cliToolId;
     return instanceId;
 }
@@ -202,7 +217,7 @@ function resolveTargetInstanceId(target) {
  * restart overwrites rather than accumulates.
  */
 function getHookSettingsPath(target, options = {}) {
-    const cliToolId = target.cliToolId ?? 'claude';
+    const cliToolId = target.cliToolId ?? tool_id_1.CLAUDE_CLI_TOOL_ID;
     const instanceId = resolveTargetInstanceId(target);
     const slug = `${cliToolId}-${target.worktreeId}-${instanceId}`.replace(/[^a-zA-Z0-9_-]/g, '_');
     const digest = (0, crypto_1.createHash)('sha256')
@@ -236,7 +251,7 @@ function buildPermissionRequestUrl(target, options = {}) {
     return buildReceiverUrl(exports.PERMISSION_REQUEST_PATH, target, options);
 }
 function buildReceiverUrl(path, target, options) {
-    const cliToolId = target.cliToolId ?? 'claude';
+    const cliToolId = target.cliToolId ?? tool_id_1.CLAUDE_CLI_TOOL_ID;
     const port = options.port ?? (0, env_1.getServerPort)();
     const params = new URLSearchParams({
         tool: cliToolId,
@@ -285,7 +300,7 @@ function buildSessionStartCommand(target, options = {}) {
         return [
             shellQuote(relay),
             '--tool',
-            shellQuote(target.cliToolId ?? 'claude'),
+            shellQuote(target.cliToolId ?? tool_id_1.CLAUDE_CLI_TOOL_ID),
             '--event',
             'session_start',
             '--worktree-id',