/** * Record of `mcbd-*` sessions stopped through CommandMate's kill (Issue #3993). * * The `env-clean` gate counts every vanished session of a sibling worktree as a * violation, because a worker killing its neighbour is the #1624 failure. The * orchestrator stops sibling sessions too — `commandmate instances kill` * when it cleans a worktree up (worktree-cleanup Phase 3), the UI's kill * button, the server's cleanup after sync or a repository removal — and the two * snapshots cannot tell that apart from a worker's kill: on 2026-10-29 four * verification runs of #3957 failed on `- mcbd-…- [other]` * for a cleanup nobody in the worker's transcript had run. * * This ledger is the missing fact: one line per kill, naming the API, the * tmux sessions it actually stopped, the worktree it was for and who asked * (the caller's working directory and tmux session). The gate excuses as little * as it can prove is not the worker's (`env-clean-gate.ts`, `findExternalKill`): * a vanished sibling session is `external` only when a line inside the task's * window names that exact session, was written by the CLI, and its caller is * known to be someone else — a cwd in a sibling directory of the task's * worktree (the primary checkout, another worktree) or a tmux session of * another worktree. Everything else stays a violation, exactly as before: * a worker's own kill, a caller that is nowhere in particular (`/tmp`, `$HOME`), * the route's and the server's lines (a worker can reach the UI and trigger * sync too), and any kill that bypassed CommandMate (`tmux kill-session`), which * records nothing. Those lines are still shown next to the violation. * * Written by the CLI (with its caller), by the kill-session route and by * `session-cleanup.ts`. A CLI kill is therefore recorded twice — the CLI's line * and the route's `http` line — which changes no verdict: only the CLI's line * can excuse anything. * * Machine-wide, like the gate mutex (`machine-lock.ts`): the CLI and the server * write it and the server's gate reads it, so the path is derived from `$HOME` alone — * `~/.commandmate/session-kills/.jsonl` — with an override for tests. * The `commandmate-entries` probe ignores the directory, like `locks`. * * Node built-ins only: the CLI imports this module. * * @module lib/verification/session-kill-ledger */ /** Directory under `~/.commandmate`; exported for the `commandmate-entries` probe. */ export declare const SESSION_KILL_LEDGER_DIR_NAME = "session-kills"; /** Overrides the ledger directory (tests, isolated environments). */ export declare const SESSION_KILL_LEDGER_ROOT_ENV = "CM_SESSION_KILL_LEDGER_ROOT"; /** Bumped only when a line stops being readable by this module. */ export declare const SESSION_KILL_LEDGER_VERSION = 1; /** Day files older than this are removed when a new line is written (same as env snapshots). */ export declare const SESSION_KILL_LEDGER_RETENTION_MS: number; /** * What stopped the session: the kill-session API (`POST /api/worktrees/:id/kill-session`, * also behind `instances kill`), or the server's own cleanup of worktrees * that sync or a repository removal dropped (`lib/session-cleanup.ts`). */ export type SessionKillApi = 'kill-session' | 'session-cleanup'; /** * Who wrote the record, which decides how much it says about the caller: * * - `cli` — `commandmate instances … kill`; callerCwd / callerSession are the CLI's own. * - `browser` — the kill-session route, for a same-origin browser request (the UI). * - `http` — the kill-session route, for any other request (the CLI's own POST, * curl). The caller is unknown, so callerCwd / callerSession are null. * - `server` — the server's cleanup; no request is behind it. * * Only `cli` lines can excuse a removal. `browser` is judged from * `Sec-Fetch-Site` alone, which a header names and a UI-driving worker sends; * `server` cleanup runs after a `commandmate sync` a worker can issue. Both are * kept so the report can say a kill was recorded, not to excuse it. */ export type SessionKillOrigin = 'cli' | 'browser' | 'http' | 'server'; export interface SessionKillRecord { version: number; /** Epoch ms of the successful kill. */ at: number; api: SessionKillApi; origin: SessionKillOrigin; /** Worktree whose session(s) were stopped. */ worktreeId: string; /** Instance the kill was scoped to; null for a whole-worktree kill. */ instanceId: string | null; /** * tmux session names the kill actually stopped — the route's `killedSessions`. * The gate matches a vanished session against these exactly, never by the * worktree id (whose prefix another worktree's id can share). Empty when the * writer could not tell, which excuses nothing. */ sessionNames: string[]; /** Working directory of the process that asked; null when unreadable. */ callerCwd: string | null; /** tmux session the caller ran inside; null outside tmux. */ callerSession: string | null; } export declare function defaultSessionKillLedgerRoot(): string; export declare function resolveSessionKillLedgerRoot(env?: Record): string; /** * Append one kill. Never throws: the kill already happened, and failing the * command over its bookkeeping would only hide that. * * @returns true when the line was written */ export declare function appendSessionKillRecord(record: SessionKillRecord, root?: string): boolean; /** Whether a parsed line is a record this module can use; anything else is skipped. */ export declare function isSessionKillRecord(value: unknown): value is SessionKillRecord; /** * The kills recorded in `[since, until]` (epoch ms, inclusive). * * A missing directory, an unreadable day file and a malformed line all read as * "no record", which only ever excuses less. */ export declare function readSessionKillRecords(since: number, until: number, root?: string): SessionKillRecord[]; //# sourceMappingURL=session-kill-ledger.d.ts.map