commandmate 0.22.1 → 0.23.0

package/dist/server/src/lib/cli-tools/codex.js

@@ -5,12 +5,15 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodexTool = void 0;
+exports.isCodexHooksReviewDialog = isCodexHooksReviewDialog;
 const base_1 = require("./base");
 const tmux_1 = require("../tmux/tmux");
 const submit_verified_sender_1 = require("./submit-verified-sender");
 const tmux_capture_cache_1 = require("../tmux/tmux-capture-cache");
 const cli_patterns_1 = require("../detection/cli-patterns");
 const logger_1 = require("../../lib/logger");
+const sources_1 = require("../../lib/hooks/sources");
+const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
 const logger = (0, logger_1.createLogger)('cli-tools/codex');
 /**
@@ -28,6 +31,63 @@ const CODEX_POLL_INTERVAL_MS = 1000;
 const CODEX_INIT_MAX_ATTEMPTS = 30;
 /** Timeout for waiting for prompt before sending a message */
 const CODEX_PROMPT_WAIT_TIMEOUT_MS = 15000;
+/**
+ * Anchors of codex's "Hooks need review" dialog (Issue #1760, measured on
+ * codex-cli 0.147.0):
+ *
+ * ```
+ *  Hooks need review
+ *  5 hooks are new or changed.
+ *  Hooks can run outside the sandbox after you trust them.
+ *
+ * > 1. Review hooks
+ *   2. Trust all and continue
+ *   3. Continue without trusting (hooks won't run)
+ * ```
+ *
+ * It has to be handled here rather than in `getCodexActiveDialog`, which
+ * classifies it as `null`: its wording matches none of that function's three
+ * anchors (`Skip until next version` / `Do you trust` / `Press enter to
+ * continue`). Measured consequence of leaving it alone, on a pane with the
+ * generated `hooks.json` present: `isCodexPromptReady` stays false for the full
+ * 30-attempt window and the session is then handed to `sendMessage` still
+ * sitting on the dialog. Every launch, because "continue without trusting" is
+ * not remembered — verified by relaunching and getting the same screen.
+ *
+ * Both strings are required so a "hooks" mention elsewhere cannot select an
+ * option on a live prompt.
+ */
+const CODEX_HOOKS_REVIEW_ANCHORS = ['Hooks need review', 'Continue without trusting'];
+/**
+ * Option 3, "Continue without trusting (hooks won't run)".
+ *
+ * Not option 2. Trusting writes `[hooks.state."<file>:<event>:0:0"]` entries
+ * into the operator's own `~/.codex/config.toml` — the file that carries, among
+ * other things, the `notify` command a Computer Use integration runs — and
+ * granting that on someone's behalf is not this server's call. So a session
+ * starts with the hooks inert and the screen scraper doing exactly what it did
+ * before Issue #1760; the human enables them once through codex's own review
+ * screen, or an operator sets `CM_CODEX_HOOK_TRUST=bypass`.
+ *
+ * Sent alone, like the other numbered dialogs (Issue #890): codex confirms a
+ * numbered selection instantly, and a trailing Enter would land on the next
+ * screen. Verified live — the prompt was ready on the following poll.
+ */
+const CODEX_HOOKS_REVIEW_DECLINE_KEY = '3';
+/**
+ * Whether the pane is sitting on the hooks review dialog.
+ *
+ * Position-independent on purpose, unlike `getCodexActiveDialog`: the only
+ * caller checks `isCodexPromptReady` first and returns when a genuine prompt
+ * exists, so residual dialog text above a live prompt is never reached, and a
+ * one-shot guard stops the key being sent twice.
+ *
+ * @param output - ANSI-stripped pane capture
+ * @returns True when both anchors of the dialog are present
+ */
+function isCodexHooksReviewDialog(output) {
+    return CODEX_HOOKS_REVIEW_ANCHORS.every((anchor) => output.includes(anchor));
+}
 /**
  * Codex CLI tool implementation
  * Manages Codex sessions using tmux
@@ -66,6 +126,18 @@ class CodexTool extends base_1.BaseCLITool {
             logger.info('codex-session-sessionname');
             return;
         }
+        // Issue #1760: everything the previous codex process reported through this
+        // (worktreeId, instanceId) belongs to a session that no longer exists, and
+        // the key is reused verbatim by the one about to be created. Without this
+        // fence the old process's last `user_prompt_submit` reads as the new one's
+        // and a brand-new session publishes `running` before anyone has typed into
+        // it (#1723).
+        //
+        // Creation path only — the reuse branch above has already returned — and
+        // before `createSession`, so no live pane is ever matched against a stale
+        // generation. Bumped even when the launch then fails: falling back to the
+        // scraper is always safe, trusting a dead session's events is not.
+        (0, agent_session_lifecycle_1.beginAgentSession)({ worktreeId, cliToolId: sources_1.CODEX_CLI_TOOL_ID, instanceId });
         try {
             // Create tmux session. Codex is inline-rendered, so its transcript lives in
             // the pane scrollback — depth comes from the shared TMUX_HISTORY_LIMIT
@@ -76,8 +148,18 @@ class CodexTool extends base_1.BaseCLITool {
             });
             // Wait a moment for the session to be created
             await new Promise((resolve) => setTimeout(resolve, cli_tool_timing_config_1.TUI_SESSION_CREATE_WAIT_MS));
+            // Issue #1760: hand this session its correlation keys, writing codex's
+            // hooks config first if it is not already there. codex has no
+            // `--settings`, so the keys ride in environment assignments on the launch
+            // line and the hook commands read them back — which is what tells `codex`
+            // from `codex-2` in one worktree, since `cwd` is identical for both.
+            //
+            // Falls back to the bare command on any failure and when
+            // `CM_AGENT_HOOKS_INJECT=0`; a session that starts without hooks is the
+            // pre-#1760 status quo, and a session that fails to start is not.
+            const launchCommand = (0, agent_session_lifecycle_1.prepareAgentLaunch)({ worktreeId, cliToolId: sources_1.CODEX_CLI_TOOL_ID, instanceId }, this.command).command;
             // Start Codex CLI in interactive mode
-            await (0, tmux_1.sendKeys)(sessionName, 'codex', true);
+            await (0, tmux_1.sendKeys)(sessionName, launchCommand, true);
             // Wait for Codex to initialize
             await new Promise((resolve) => setTimeout(resolve, CODEX_INIT_WAIT_MS));
             // Poll until Codex interactive prompt is ready
@@ -102,6 +184,7 @@ class CodexTool extends base_1.BaseCLITool {
         // update branch re-sends "2" every poll and the live prompt gets "222...".
         let updateDialogHandled = false;
         let trustDialogHandled = false;
+        let hooksReviewHandled = false;
         for (let i = 0; i < CODEX_INIT_MAX_ATTEMPTS; i++) {
             try {
                 const rawOutput = await (0, tmux_1.capturePane)(sessionName, 50);
@@ -114,6 +197,17 @@ class CodexTool extends base_1.BaseCLITool {
                     logger.info('codex-prompt-detected');
                     return;
                 }
+                // Issue #1760: "Hooks need review". Reached only when no genuine prompt
+                // exists (the check above returned), so this cannot fire on a live
+                // prompt, and the one-shot guard stops a second key on a re-render.
+                // Declines: granting trust would write the operator's config.toml.
+                if (!hooksReviewHandled && isCodexHooksReviewDialog(output)) {
+                    await (0, tmux_1.sendKeys)(sessionName, CODEX_HOOKS_REVIEW_DECLINE_KEY, false);
+                    hooksReviewHandled = true;
+                    logger.info('codex-hooks-review-declined');
+                    await new Promise((resolve) => setTimeout(resolve, cli_tool_timing_config_1.CODEX_DIALOG_SETTLE_MS));
+                    continue;
+                }
                 // Issue #892: classify the bottom-most ACTIVE dialog by position. A dialog
                 // whose text is only residual scrollback above a genuine prompt returns
                 // null here, so no stray key is sent after it has been dismissed.

package/dist/server/src/lib/cli-tools/copilot.js

@@ -17,6 +17,9 @@ const tmux_capture_cache_1 = require("../tmux/tmux-capture-cache");
 const cli_patterns_1 = require("../detection/cli-patterns");
 const copilot_constants_1 = require("../../config/copilot-constants");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
+const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
+const hook_settings_1 = require("../../lib/hooks/sources/copilot/hook-settings");
+const tool_id_1 = require("../../lib/hooks/sources/copilot/tool-id");
 const errors_1 = require("../../lib/errors");
 const logger_1 = require("../../lib/logger");
 const logger = (0, logger_1.createLogger)('cli-tools/copilot');
@@ -112,6 +115,18 @@ class CopilotTool extends base_1.BaseCLITool {
             logger.info('copilot-session-exists');
             return;
         }
+        // Issue #1761: fence this session off from the previous copilot process's
+        // events. The state is keyed by (worktree, tool, instance), a key the new
+        // session reuses verbatim, so without this the old process's last
+        // `user_prompt_submit` reads as the new one's and a session publishes
+        // `running` before anybody has typed into it (#1723).
+        //
+        // Creation path only — the reuse branch above has already returned — and
+        // before the pane exists, so no live pane is ever judged against a stale
+        // generation. Outside the try, so a launch that then fails is still fenced:
+        // falling back to the scraper is always safe, trusting a dead session's
+        // events is not.
+        (0, agent_session_lifecycle_1.beginAgentSession)({ worktreeId, cliToolId: tool_id_1.COPILOT_CLI_TOOL_ID, instanceId });
         try {
             // Create tmux session. Scrollback depth comes from the shared
             // TMUX_HISTORY_LIMIT default (Issue #1624) — do not re-hardcode it here.
@@ -121,8 +136,22 @@ class CopilotTool extends base_1.BaseCLITool {
             });
             // Wait a moment for the session to be created
             await new Promise((resolve) => setTimeout(resolve, cli_tool_timing_config_1.TUI_SESSION_CREATE_WAIT_MS));
+            // Issue #1761: hand this session its hook configuration, so structured
+            // lifecycle events and Auto-Yes adjudication exist without the operator
+            // having edited ~/.copilot/settings.json by hand.
+            //
+            // The returned command is `gh copilot` with two environment assignments
+            // in front of it. Copilot's config is one file for the whole machine, so
+            // unlike Claude's `--settings` it cannot carry the correlation keys —
+            // they ride in the environment and the hook reads them when it fires.
+            // See `lib/hooks/sources/copilot/hook-settings`.
+            //
+            // Fails open in every branch: with `CM_AGENT_HOOKS_INJECT=0`, or with a
+            // settings file that cannot be read or written, this is byte-for-byte the
+            // `gh copilot` this line has always sent.
+            const launchCommand = (0, agent_session_lifecycle_1.prepareAgentLaunch)({ worktreeId, cliToolId: tool_id_1.COPILOT_CLI_TOOL_ID, instanceId }, hook_settings_1.COPILOT_LAUNCH_COMMAND).command;
             // Start Copilot CLI in interactive mode
-            await (0, tmux_1.sendKeys)(sessionName, 'gh copilot', true);
+            await (0, tmux_1.sendKeys)(sessionName, launchCommand, true);
             // Wait for Copilot to initialize
             await new Promise((resolve) => setTimeout(resolve, COPILOT_INIT_WAIT_MS));
             // Poll until Copilot interactive prompt is ready

package/dist/server/src/lib/cli-tools/gemini.js

@@ -15,6 +15,9 @@ const tmux_1 = require("../tmux/tmux");
 const submit_verified_sender_1 = require("./submit-verified-sender");
 const tmux_capture_cache_1 = require("../tmux/tmux-capture-cache");
 const cli_patterns_1 = require("../detection/cli-patterns");
+const sources_1 = require("../../lib/hooks/sources");
+const source_1 = require("../../lib/hooks/sources/gemini/source");
+const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
 const logger_1 = require("../../lib/logger");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
 const logger = (0, logger_1.createLogger)('cli-tools/gemini');
@@ -73,6 +76,13 @@ class GeminiTool extends base_1.BaseCLITool {
             logger.info('gemini-session-sessionname');
             return;
         }
+        // Issue #1762: fence this instance's structured events off from the process
+        // that used to hold the same (worktree, tool, instance) key. On the creation
+        // path only — the reuse branch above has already returned — and before the
+        // pane exists, so no live pane is ever judged against a stale generation.
+        // Bumped even if the launch below then fails: falling back to the screen
+        // scraper is always safe, trusting a dead session's events is not.
+        (0, agent_session_lifecycle_1.beginAgentSession)({ worktreeId, cliToolId: sources_1.GEMINI_CLI_TOOL_ID, instanceId });
         try {
             // Create tmux session. Scrollback depth comes from the shared
             // TMUX_HISTORY_LIMIT default (Issue #1624) — do not re-hardcode it here.
@@ -82,8 +92,24 @@ class GeminiTool extends base_1.BaseCLITool {
             });
             // Wait a moment for the session to be created
             await new Promise((resolve) => setTimeout(resolve, cli_tool_timing_config_1.TUI_SESSION_CREATE_WAIT_MS));
-            // Start Gemini CLI in interactive mode (no flags = interactive REPL)
-            await (0, tmux_1.sendKeys)(sessionName, 'gemini', true);
+            // Issue #1762: hand this worktree its own hooks config, merged into any
+            // `.gemini/settings.json` that is already there. Written from here rather
+            // than from the source's `prepareLaunch` because the worktree path is the
+            // one input `AgentInstanceRef` does not carry, and gemini is the only tool
+            // whose config is scoped to a worktree. Fail-open: a config that cannot be
+            // written costs the events and nothing else.
+            (0, source_1.injectGeminiHookSettings)(worktreePath, {
+                worktreeId,
+                cliToolId: sources_1.GEMINI_CLI_TOOL_ID,
+                instanceId,
+            });
+            // Start Gemini CLI in interactive mode (no flags = interactive REPL).
+            // `prepareAgentLaunch` prefixes `CM_HOOK_URL`, which is what tells the
+            // receiver which instance an event came from — `.gemini/settings.json` is
+            // per worktree and cannot. `CM_AGENT_HOOKS_INJECT=0` returns the bare
+            // command, unchanged from before this Issue.
+            const launchCommand = (0, agent_session_lifecycle_1.prepareAgentLaunch)({ worktreeId, cliToolId: sources_1.GEMINI_CLI_TOOL_ID, instanceId }, this.command).command;
+            await (0, tmux_1.sendKeys)(sessionName, launchCommand, true);
             // Wait for Gemini to initialize (minimum wait for banner/auth)
             await new Promise((resolve) => setTimeout(resolve, GEMINI_INIT_WAIT_MS));
             // Poll until Gemini interactive prompt is ready

package/dist/server/src/lib/cli-tools/opencode.js

@@ -8,6 +8,22 @@
  * - sendMessage: sends text via tmux send-keys + Enter
  * - killSession: sends `/exit` command then falls back to tmux kill-session
  * - interrupt(): inherits BaseCLITool default (Escape key) [D2-008]
+ *
+ * ## Structured events (Issue #1763, Epic #1720 Phase 4-5)
+ *
+ * opencode is the one supported agent that does not push lifecycle events at
+ * CommandMate: it is *subscribed to*. #1758 §5.1.2 measured that the plain TUI
+ * serves the same HTTP API `opencode serve` does once it is given `--port`, so
+ * the whole of the launch change is that flag — no second process, no pid to
+ * track, no orphan to reap, and `killSession`'s `/exit`, the init wait and
+ * `reconcileExistingSession` are all untouched.
+ *
+ * What is added around it is three calls into
+ * `@/lib/hooks/sources/opencode/runtime`: reserve a port before the launch
+ * command is built, attach the event stream once the TUI is up, and release
+ * both when the pane is killed. Every one of them is fail-open — a session that
+ * starts without structured events is the pre-#1763 status quo, and the screen
+ * scraper keeps deciding for it exactly as before.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenCodeTool = exports.OPENCODE_INIT_WAIT_MS = exports.OPENCODE_PANE_HEIGHT = exports.OPENCODE_EXIT_COMMAND = void 0;
@@ -19,6 +35,8 @@ const opencode_config_1 = require("./opencode-config");
 const child_process_1 = require("child_process");
 const util_1 = require("util");
 const logger_1 = require("../../lib/logger");
+const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
+const runtime_1 = require("../../lib/hooks/sources/opencode/runtime");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
 const logger = (0, logger_1.createLogger)('cli-tools/opencode');
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
@@ -77,15 +95,29 @@ class OpenCodeTool extends base_1.BaseCLITool {
             throw new Error('OpenCode is not installed or not in PATH');
         }
         const sessionName = this.getSessionName(worktreeId, instanceId);
+        const target = (0, runtime_1.opencodeTarget)(worktreeId, instanceId);
         const exists = await (0, tmux_1.hasSession)(sessionName);
         if (exists) {
             await this.reconcileExistingSession(sessionName, {
                 windowWidth: 80,
                 windowHeight: exports.OPENCODE_PANE_HEIGHT,
             });
+            // Issue #1763: the pane outlived this process (a CommandMate restart), so
+            // the subscription that used to watch it is gone while its server is
+            // still listening. Recovered from the recorded port, health-checked, and
+            // skipped silently when there is nothing there. NOT a new generation —
+            // the pane is the same one, and fencing here would discard a still-valid
+            // verdict on every reconnect.
+            await (0, runtime_1.resumeOpencodeEventStream)(target, worktreePath);
             logger.info('opencode-session-sessionname');
             return;
         }
+        // Issue #1759 (S8) / #1763: everything the previous opencode process
+        // reported through this (worktreeId, instanceId) belongs to a session that
+        // no longer exists, and the key is reused verbatim by the one about to be
+        // created. On the creation path only, before the pane exists, and even if
+        // the launch then fails — falling back to the scraper is always safe.
+        (0, agent_session_lifecycle_1.beginAgentSession)(target);
         try {
             // Generate opencode.json if not present (non-fatal on failure)
             await (0, opencode_config_1.ensureOpencodeConfig)(worktreePath);
@@ -109,10 +141,23 @@ class OpenCodeTool extends base_1.BaseCLITool {
             catch {
                 // Non-fatal: resize may fail in some environments
             }
-            // Start OpenCode TUI
-            await (0, tmux_1.sendKeys)(sessionName, 'opencode', true);
+            // Issue #1763: pick the port before the command is built. The TUI is its
+            // own HTTP server once `--port` is passed (#1758 §5.1.2), and CommandMate
+            // assigns the number because opencode's `--port 0` is not an OS-assigned
+            // port — it tries 4096 first and only then falls back to an ephemeral one
+            // that nothing can read back (§5.9). Null means "no structured events",
+            // and the launch below is then the pre-#1763 bare command.
+            await (0, runtime_1.reserveOpencodeServerPort)(target, worktreePath);
+            // Start OpenCode TUI. `prepareAgentLaunch` asks the tool's own
+            // `AgentEventSource` for the command line (S3/S4/S5) and never throws.
+            const launchCommand = (0, agent_session_lifecycle_1.prepareAgentLaunch)(target, this.command).command;
+            await (0, tmux_1.sendKeys)(sessionName, launchCommand, true);
             // Wait for OpenCode to initialize (GPU model loading via Ollama)
             await new Promise((resolve) => setTimeout(resolve, exports.OPENCODE_INIT_WAIT_MS));
+            // Issue #1763: subscribe once the server has had the same time to come up
+            // that the TUI has. Health-checked first, so an opencode too old to know
+            // `--port` costs one probe and nothing else.
+            await (0, runtime_1.attachOpencodeEventStream)(target);
             logger.info('started-opencode-session:sessionname');
         }
         catch (error) {
@@ -164,6 +209,10 @@ class OpenCodeTool extends base_1.BaseCLITool {
      */
     async killSession(worktreeId, instanceId) {
         const sessionName = this.getSessionName(worktreeId, instanceId);
+        // Issue #1763: stop watching before the pane goes, so the stream is not
+        // reconnecting to a server that is being shut down. Also gives the port
+        // back — the pane is what held it. Never throws.
+        await (0, runtime_1.releaseOpencodeEventStream)((0, runtime_1.opencodeTarget)(worktreeId, instanceId));
         try {
             // Step 1: Check if the tmux session currently exists
             const exists = await (0, tmux_1.hasSession)(sessionName);

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 };
+}