@webpieces/repo-workflow-core 0.0.1

package/src/branch-mutation-log.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BranchMutationLog = exports.BranchMutationEvent = void 0;
+exports.branchMutationLogPath = branchMutationLogPath;
+exports.logBranchMutation = logBranchMutation;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const inversify_1 = require("inversify");
+const tooling_common_1 = require("@webpieces/tooling-common");
+const to_error_1 = require("@webpieces/tooling-common/to-error");
+// The BRANCH-MUTATION log — an audit trail for every workflow verb that RENAMES or MOVES branches.
+// Records START / each phase boundary / END-with-outcome so the next agent (or a human) can
+// reconstruct what the tooling did to the branches. Writes to `.webpieces/logs/branch-mutations.log`
+// (in a linked worktree: `.webpieces/worktrees/<name>/logs/`) — see LOGS_STATE_DIR for why every
+// webpieces log lives under `logs/` and no longer beside the non-log state in `hooks/`.
+// Lives in repo-workflow-core (shared by guards and pr-gate) so the pr-gate scripts can call it directly.
+const LOG_FILE = 'branch-mutations.log';
+const LOG_FILE_PREV = 'branch-mutations.1.log';
+const MAX_LOG_BYTES = 512 * 1024; // 512 KB — rotate when exceeded (mirrors the other webpieces logs)
+const MAX_DETAIL_LEN = 400;
+// Data-only record of one branch-mutation event (per CLAUDE.md: classes for data, explicit construction).
+class BranchMutationEvent {
+    verb;
+    phase;
+    fromBranch = '';
+    toBranch = '';
+    oldMain = '';
+    newMain = '';
+    conflict = false;
+    conflictFiles = [];
+    outcome = '';
+    artifacts = [];
+    // The commit a DELETED branch pointed at, captured immediately before the delete. This is what
+    // makes a reap auditable AND reversible: the work is already in main, and the pre-delete tip is
+    // still addressable by hash (the reflog holds it ~90 days), so formatDetail renders a literal
+    // `recover=git branch <name> <sha>` next to it. Empty for mutations that delete nothing.
+    sha = '';
+    // The `archive/<date>/<branch>` tag written immediately BEFORE a REAP deleted the branch. When set,
+    // formatDetail renders `recover=` against the TAG instead of the sha: a tag is a permanent ref that
+    // survives `gc` and reflog expiry and can be pushed, whereas a bare sha is only recoverable while
+    // this clone's reflog still holds it. Empty when nothing was tagged (retention policy 'delete').
+    archiveTag = '';
+    // The directory a REAP_WORKTREE removed. When set, `recover=` becomes the WORKTREE form
+    // (`git worktree add -b <branch> <path> <ref>`) rather than the bare `git branch` form: putting the
+    // ref back does not put the directory back, and a recover line that restores half of what was
+    // destroyed is worse than none — it reads as done. Empty for every mutation that removes no directory.
+    worktreePath = '';
+    constructor(verb, phase) {
+        this.verb = verb;
+        this.phase = phase;
+    }
+}
+exports.BranchMutationEvent = BranchMutationEvent;
+/** Appends branch-mutation audit lines. `@injectable(bindingScopeValues.Singleton)` so it's injectable + drawn in the design. */
+let BranchMutationLog = class BranchMutationLog {
+    dotDir;
+    constructor(dotDir = tooling_common_1.dotWebpieces) {
+        this.dotDir = dotDir;
+    }
+    /**
+     * LOCAL scope, deliberately — one log per worktree, not one per repo.
+     *
+     * A SHARED append-only log would genuinely corrupt. `O_APPEND` makes a write indivisible only up to
+     * PIPE_BUF, which is 512 bytes on macOS, and a REAP_WORKTREE line carrying
+     * `recover=git worktree add -b <branch> <absolute-path> <tag>` exceeds that — concurrent appenders
+     * from seven worktrees would interleave into an unrecoverable audit trail, which is the one thing
+     * this file exists not to be. Per-worktree, THIS log has one writer and cannot tear.
+     *
+     * That last claim is narrower than it looks, so do not generalise it (2026-08-06). It holds here
+     * because the wp-* bins write this file one command at a time. It does NOT hold for the ai-hook
+     * logs in the same directory: Claude Code runs every matching PreToolUse hook IN PARALLEL, and
+     * several agents and sessions can share one tree, so a per-worktree name there had several
+     * concurrent writers. Those names now carry a `<sessionId>-<agentId|coordinator>-<hook>-` prefix
+     * (ai-hook-rules' LogStream), and the rejection DETAIL files sit in a directory of that same name.
+     *
+     * This file keeps a bare name deliberately, for TWO independent reasons, and neither has gone away
+     * (re-checked 2026-08-07). First, LogStream lives in ai-hook-rules, which DEPENDS on rules-config,
+     * so the import direction forbids reusing it here. Second — and this is the one that would still
+     * bite after moving the class down — the `wp-*` bins that write this file have NO session or agent
+     * identity to prefix with: those ids reach a PreToolUse hook on its JSON payload and a plain Bash
+     * tool call never sees them. Routing this through LogStream today would therefore produce
+     * `unknown-coordinator-hook-branch-mutations.log`: one shared file, exactly as now, under a longer
+     * name, plus a rename of a log people already grep. If this log ever gains a second concurrent
+     * writer, it needs a real stream identity FIRST — the prefix is only worth having when it
+     * discriminates.
+     *
+     * Nothing is lost by keeping it local: under the `worktrees/<name>/` layout the log lives in the
+     * PRIMARY clone, so it survives `git worktree remove`, and the whole history is one glob —
+     * `<primary>/.webpieces/worktrees/＊/logs/branch-mutations.log`.
+     */
+    branchMutationLogPath(root) {
+        return this.dotDir.logsFile(root, LOG_FILE);
+    }
+    /**
+     * Append one tab-separated line per branch-mutation event to
+     * `.webpieces/logs/branch-mutations.log`. Swallows all errors — logging must NEVER block or fail
+     * the workflow it is observing.
+     */
+    logBranchMutation(root, event) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const timestamp = new Date().toISOString();
+            const logsDir = this.dotDir.logs(root);
+            fs.mkdirSync(logsDir, { recursive: true });
+            const logPath = path.join(logsDir, LOG_FILE);
+            this.rotateLogFile(logPath, path.join(logsDir, LOG_FILE_PREV));
+            const line = [
+                `[${timestamp}]`,
+                event.verb,
+                event.phase,
+                this.oneLine(this.formatDetail(event)),
+            ].join('\t') + '\n';
+            fs.appendFileSync(logPath, line);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+    // Render only the fields this event actually set, as `key=value` tokens — greppable on one line.
+    formatDetail(event) {
+        const parts = [];
+        // A rename/move has both ends; a REAP has only the branch it destroyed. Printing `to=?` for
+        // the latter reads like a lost destination rather than "there was never one".
+        if (event.fromBranch !== '' && event.toBranch !== '')
+            parts.push(`from=${event.fromBranch} to=${event.toBranch}`);
+        else if (event.fromBranch !== '')
+            parts.push(`branch=${event.fromBranch}`);
+        else if (event.toBranch !== '')
+            parts.push(`from=? to=${event.toBranch}`);
+        if (event.oldMain !== '' || event.newMain !== '')
+            parts.push(`oldMain=${event.oldMain || '?'} newMain=${event.newMain || '?'}`);
+        if (event.conflict)
+            parts.push('conflict=true');
+        if (event.conflictFiles.length > 0)
+            parts.push(`conflictFiles=${event.conflictFiles.length}(${event.conflictFiles.join(',')})`);
+        // Emitted as one unit so the hash is never separated from the command that undoes the delete.
+        // Prefer the archive TAG as the recover ref when there is one — it does not expire.
+        //
+        // AHEAD OF `outcome=` DELIBERATELY. The line is capped at MAX_DETAIL_LEN, and the two absolute
+        // worktree paths a REAP_WORKTREE carries already put a real reap within a few characters of
+        // that cap — so whichever token comes last is the one that silently loses its tail. Prose
+        // describing what happened is the affordable loss; the command that undoes it is not.
+        if (event.worktreePath !== '') {
+            parts.push(this.worktreeDetail(event));
+        }
+        else if (event.sha !== '' && event.archiveTag !== '') {
+            parts.push(`sha=${event.sha} archiveTag=${event.archiveTag} ` +
+                `recover=git checkout -b ${event.fromBranch || '?'} ${event.archiveTag}`);
+        }
+        else if (event.sha !== '') {
+            parts.push(`sha=${event.sha} recover=git branch ${event.fromBranch || '?'} ${event.sha}`);
+        }
+        if (event.outcome !== '')
+            parts.push(`outcome=${event.outcome}`);
+        for (const artifact of event.artifacts)
+            parts.push(`artifact=${artifact}`);
+        return parts.join(' ');
+    }
+    /**
+     * The worktree flavour of the sha/recover token: path, tip, archive tag and the ONE command that
+     * puts the directory AND the branch back together.
+     *
+     * `git worktree add -b <branch> <path> <ref>` is verified by hand and in worktree-reaper.spec.ts —
+     * plain `git worktree add <path> <tag>` would restore the files at a DETACHED HEAD, silently losing
+     * the branch name the reap destroyed. Falls back to the sha when nothing was archived (retention
+     * 'delete'), and to a bare `git worktree add <path>` when there was no branch at all (detached).
+     */
+    worktreeDetail(event) {
+        const ref = event.archiveTag !== '' ? event.archiveTag : event.sha;
+        const tokens = [`worktree=${event.worktreePath}`];
+        if (event.sha !== '')
+            tokens.push(`sha=${event.sha}`);
+        if (event.archiveTag !== '')
+            tokens.push(`archiveTag=${event.archiveTag}`);
+        if (ref === '')
+            return tokens.join(' ');
+        const recover = event.fromBranch !== ''
+            ? `git worktree add -b ${event.fromBranch} ${event.worktreePath} ${ref}`
+            : `git worktree add ${event.worktreePath} ${ref}`;
+        tokens.push(`recover=${recover}`);
+        return tokens.join(' ');
+    }
+    // Collapse newlines/tabs and cap length so one event is always exactly one log line.
+    oneLine(value) {
+        const flat = value.replace(/[\t\r\n]+/g, ' ').trim();
+        return flat.length <= MAX_DETAIL_LEN ? flat : flat.slice(0, MAX_DETAIL_LEN) + '…';
+    }
+    rotateLogFile(logPath, prevPath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const stat = fs.statSync(logPath);
+            if (stat.size > MAX_LOG_BYTES) {
+                if (fs.existsSync(prevPath))
+                    fs.unlinkSync(prevPath);
+                fs.renameSync(logPath, prevPath);
+            }
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+};
+exports.BranchMutationLog = BranchMutationLog;
+exports.BranchMutationLog = BranchMutationLog = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [tooling_common_1.DotWebpieces])
+], BranchMutationLog);
+// Temporary migration delegators to BranchMutationLog — removed once consumers inject it.
+const branchMutationLogSvc = new BranchMutationLog();
+// webpieces-disable no-function-outside-class -- temporary back-compat delegator to BranchMutationLog; removed once consumers inject it
+function branchMutationLogPath(root) {
+    return branchMutationLogSvc.branchMutationLogPath(root);
+}
+// webpieces-disable no-function-outside-class -- temporary back-compat delegator to BranchMutationLog; removed once consumers inject it
+function logBranchMutation(root, event) {
+    branchMutationLogSvc.logBranchMutation(root, event);
+}
+//# sourceMappingURL=branch-mutation-log.js.map

package/src/branch-mutation-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-mutation-log.js","sourceRoot":"","sources":["../../../../../packages/tooling/repo-workflow-core/src/branch-mutation-log.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { DotWebpieces, dotWebpieces } from '@webpieces/tooling-common';\nimport { toError } from '@webpieces/tooling-common/to-error';\n\n// The BRANCH-MUTATION log — an audit trail for every workflow verb that RENAMES or MOVES branches.\n// Records START / each phase boundary / END-with-outcome so the next agent (or a human) can\n// reconstruct what the tooling did to the branches. Writes to `.webpieces/logs/branch-mutations.log`\n// (in a linked worktree: `.webpieces/worktrees/<name>/logs/`) — see LOGS_STATE_DIR for why every\n// webpieces log lives under `logs/` and no longer beside the non-log state in `hooks/`.\n// Lives in repo-workflow-core (shared by guards and pr-gate) so the pr-gate scripts can call it directly.\n\nconst LOG_FILE = 'branch-mutations.log';\nconst LOG_FILE_PREV = 'branch-mutations.1.log';\nconst MAX_LOG_BYTES = 512 * 1024; // 512 KB — rotate when exceeded (mirrors the other webpieces logs)\nconst MAX_DETAIL_LEN = 400;\n\n// The workflow verb whose branch mutation is being logged (the bin the AI/human invoked).\n// `auto-reap` is the odd one out: no human invoked it — it is the detached background refresher\n// (sync-main.ts) deleting dead branches on its own. It gets a verb precisely BECAUSE it is\n// unattended: a deletion nobody watched happen is the one that most needs an audit line.\nexport type MutationVerb =\n    | 'wp-start-update' | 'wp-finish-update' | 'wp-start-upsert-pr' | 'wp-review-upsert-pr'\n    | 'wp-finish-upsert-pr' | 'wp-cleanup' | 'wp-land-pr' | 'auto-reap';\n\n// A boundary within a verb's execution. START/END bracket the whole run; the middle phases mark each\n// irreversible git step so an interrupt leaves a breadcrumb at the last phase reached.\n// REAP is a whole mutation in one line (a branch delete has no phases) — see BranchReaper.\n// REAP_WORKTREE is its worktree twin: archive → `git worktree remove` → `git branch -D`, all three of\n// which succeed or fail as one act. It is a SEPARATE phase, not just a REAP with a path, so that\n// `grep REAP_WORKTREE` answers \"what directories did the tooling delete?\" — a strictly scarier\n// question than \"what refs did it delete?\", since a worktree removal takes real files with it.\nexport type MutationPhase =\n    | 'START' | 'BACKUP' | 'CHECKOUT_MAIN' | 'PULL' | 'SQUASH' | 'RENAME'\n    | 'FINALIZE' | 'CONFLICT' | 'INTERRUPTED' | 'END' | 'REAP' | 'REAP_WORKTREE';\n\n// Data-only record of one branch-mutation event (per CLAUDE.md: classes for data, explicit construction).\nexport class BranchMutationEvent {\n    verb: MutationVerb;\n    phase: MutationPhase;\n    fromBranch: string = '';\n    toBranch: string = '';\n    oldMain: string = '';\n    newMain: string = '';\n    conflict: boolean = false;\n    conflictFiles: string[] = [];\n    outcome: string = '';\n    artifacts: string[] = [];\n    // The commit a DELETED branch pointed at, captured immediately before the delete. This is what\n    // makes a reap auditable AND reversible: the work is already in main, and the pre-delete tip is\n    // still addressable by hash (the reflog holds it ~90 days), so formatDetail renders a literal\n    // `recover=git branch <name> <sha>` next to it. Empty for mutations that delete nothing.\n    sha: string = '';\n    // The `archive/<date>/<branch>` tag written immediately BEFORE a REAP deleted the branch. When set,\n    // formatDetail renders `recover=` against the TAG instead of the sha: a tag is a permanent ref that\n    // survives `gc` and reflog expiry and can be pushed, whereas a bare sha is only recoverable while\n    // this clone's reflog still holds it. Empty when nothing was tagged (retention policy 'delete').\n    archiveTag: string = '';\n    // The directory a REAP_WORKTREE removed. When set, `recover=` becomes the WORKTREE form\n    // (`git worktree add -b <branch> <path> <ref>`) rather than the bare `git branch` form: putting the\n    // ref back does not put the directory back, and a recover line that restores half of what was\n    // destroyed is worse than none — it reads as done. Empty for every mutation that removes no directory.\n    worktreePath: string = '';\n\n    constructor(verb: MutationVerb, phase: MutationPhase) {\n        this.verb = verb;\n        this.phase = phase;\n    }\n}\n\n/** Appends branch-mutation audit lines. `@injectable(bindingScopeValues.Singleton)` so it's injectable + drawn in the design. */\n@injectable(bindingScopeValues.Singleton)\nexport class BranchMutationLog {\n    constructor(private readonly dotDir: DotWebpieces = dotWebpieces) {}\n\n    /**\n     * LOCAL scope, deliberately — one log per worktree, not one per repo.\n     *\n     * A SHARED append-only log would genuinely corrupt. `O_APPEND` makes a write indivisible only up to\n     * PIPE_BUF, which is 512 bytes on macOS, and a REAP_WORKTREE line carrying\n     * `recover=git worktree add -b <branch> <absolute-path> <tag>` exceeds that — concurrent appenders\n     * from seven worktrees would interleave into an unrecoverable audit trail, which is the one thing\n     * this file exists not to be. Per-worktree, THIS log has one writer and cannot tear.\n     *\n     * That last claim is narrower than it looks, so do not generalise it (2026-08-06). It holds here\n     * because the wp-* bins write this file one command at a time. It does NOT hold for the ai-hook\n     * logs in the same directory: Claude Code runs every matching PreToolUse hook IN PARALLEL, and\n     * several agents and sessions can share one tree, so a per-worktree name there had several\n     * concurrent writers. Those names now carry a `<sessionId>-<agentId|coordinator>-<hook>-` prefix\n     * (ai-hook-rules' LogStream), and the rejection DETAIL files sit in a directory of that same name.\n     *\n     * This file keeps a bare name deliberately, for TWO independent reasons, and neither has gone away\n     * (re-checked 2026-08-07). First, LogStream lives in ai-hook-rules, which DEPENDS on rules-config,\n     * so the import direction forbids reusing it here. Second — and this is the one that would still\n     * bite after moving the class down — the `wp-*` bins that write this file have NO session or agent\n     * identity to prefix with: those ids reach a PreToolUse hook on its JSON payload and a plain Bash\n     * tool call never sees them. Routing this through LogStream today would therefore produce\n     * `unknown-coordinator-hook-branch-mutations.log`: one shared file, exactly as now, under a longer\n     * name, plus a rename of a log people already grep. If this log ever gains a second concurrent\n     * writer, it needs a real stream identity FIRST — the prefix is only worth having when it\n     * discriminates.\n     *\n     * Nothing is lost by keeping it local: under the `worktrees/<name>/` layout the log lives in the\n     * PRIMARY clone, so it survives `git worktree remove`, and the whole history is one glob —\n     * `<primary>/.webpieces/worktrees/＊/logs/branch-mutations.log`.\n     */\n    branchMutationLogPath(root: string): string {\n        return this.dotDir.logsFile(root, LOG_FILE);\n    }\n\n    /**\n     * Append one tab-separated line per branch-mutation event to\n     * `.webpieces/logs/branch-mutations.log`. Swallows all errors — logging must NEVER block or fail\n     * the workflow it is observing.\n     */\n    logBranchMutation(root: string, event: BranchMutationEvent): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const timestamp = new Date().toISOString();\n            const logsDir = this.dotDir.logs(root);\n            fs.mkdirSync(logsDir, { recursive: true });\n\n            const logPath = path.join(logsDir, LOG_FILE);\n            this.rotateLogFile(logPath, path.join(logsDir, LOG_FILE_PREV));\n\n            const line = [\n                `[${timestamp}]`,\n                event.verb,\n                event.phase,\n                this.oneLine(this.formatDetail(event)),\n            ].join('\\t') + '\\n';\n            fs.appendFileSync(logPath, line);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n\n    // Render only the fields this event actually set, as `key=value` tokens — greppable on one line.\n    private formatDetail(event: BranchMutationEvent): string {\n        const parts: string[] = [];\n        // A rename/move has both ends; a REAP has only the branch it destroyed. Printing `to=?` for\n        // the latter reads like a lost destination rather than \"there was never one\".\n        if (event.fromBranch !== '' && event.toBranch !== '') parts.push(`from=${event.fromBranch} to=${event.toBranch}`);\n        else if (event.fromBranch !== '') parts.push(`branch=${event.fromBranch}`);\n        else if (event.toBranch !== '') parts.push(`from=? to=${event.toBranch}`);\n        if (event.oldMain !== '' || event.newMain !== '') parts.push(`oldMain=${event.oldMain || '?'} newMain=${event.newMain || '?'}`);\n        if (event.conflict) parts.push('conflict=true');\n        if (event.conflictFiles.length > 0) parts.push(`conflictFiles=${event.conflictFiles.length}(${event.conflictFiles.join(',')})`);\n        // Emitted as one unit so the hash is never separated from the command that undoes the delete.\n        // Prefer the archive TAG as the recover ref when there is one — it does not expire.\n        //\n        // AHEAD OF `outcome=` DELIBERATELY. The line is capped at MAX_DETAIL_LEN, and the two absolute\n        // worktree paths a REAP_WORKTREE carries already put a real reap within a few characters of\n        // that cap — so whichever token comes last is the one that silently loses its tail. Prose\n        // describing what happened is the affordable loss; the command that undoes it is not.\n        if (event.worktreePath !== '') {\n            parts.push(this.worktreeDetail(event));\n        } else if (event.sha !== '' && event.archiveTag !== '') {\n            parts.push(\n                `sha=${event.sha} archiveTag=${event.archiveTag} ` +\n                `recover=git checkout -b ${event.fromBranch || '?'} ${event.archiveTag}`,\n            );\n        } else if (event.sha !== '') {\n            parts.push(`sha=${event.sha} recover=git branch ${event.fromBranch || '?'} ${event.sha}`);\n        }\n        if (event.outcome !== '') parts.push(`outcome=${event.outcome}`);\n        for (const artifact of event.artifacts) parts.push(`artifact=${artifact}`);\n        return parts.join(' ');\n    }\n\n    /**\n     * The worktree flavour of the sha/recover token: path, tip, archive tag and the ONE command that\n     * puts the directory AND the branch back together.\n     *\n     * `git worktree add -b <branch> <path> <ref>` is verified by hand and in worktree-reaper.spec.ts —\n     * plain `git worktree add <path> <tag>` would restore the files at a DETACHED HEAD, silently losing\n     * the branch name the reap destroyed. Falls back to the sha when nothing was archived (retention\n     * 'delete'), and to a bare `git worktree add <path>` when there was no branch at all (detached).\n     */\n    private worktreeDetail(event: BranchMutationEvent): string {\n        const ref = event.archiveTag !== '' ? event.archiveTag : event.sha;\n        const tokens = [`worktree=${event.worktreePath}`];\n        if (event.sha !== '') tokens.push(`sha=${event.sha}`);\n        if (event.archiveTag !== '') tokens.push(`archiveTag=${event.archiveTag}`);\n        if (ref === '') return tokens.join(' ');\n        const recover = event.fromBranch !== ''\n            ? `git worktree add -b ${event.fromBranch} ${event.worktreePath} ${ref}`\n            : `git worktree add ${event.worktreePath} ${ref}`;\n        tokens.push(`recover=${recover}`);\n        return tokens.join(' ');\n    }\n\n    // Collapse newlines/tabs and cap length so one event is always exactly one log line.\n    private oneLine(value: string): string {\n        const flat = value.replace(/[\\t\\r\\n]+/g, ' ').trim();\n        return flat.length <= MAX_DETAIL_LEN ? flat : flat.slice(0, MAX_DETAIL_LEN) + '…';\n    }\n\n    private rotateLogFile(logPath: string, prevPath: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const stat = fs.statSync(logPath);\n            if (stat.size > MAX_LOG_BYTES) {\n                if (fs.existsSync(prevPath)) fs.unlinkSync(prevPath);\n                fs.renameSync(logPath, prevPath);\n            }\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n}\n\n// Temporary migration delegators to BranchMutationLog — removed once consumers inject it.\nconst branchMutationLogSvc = new BranchMutationLog();\n\n// webpieces-disable no-function-outside-class -- temporary back-compat delegator to BranchMutationLog; removed once consumers inject it\nexport function branchMutationLogPath(root: string): string {\n    return branchMutationLogSvc.branchMutationLogPath(root);\n}\n\n// webpieces-disable no-function-outside-class -- temporary back-compat delegator to BranchMutationLog; removed once consumers inject it\nexport function logBranchMutation(root: string, event: BranchMutationEvent): void {\n    branchMutationLogSvc.logBranchMutation(root, event);\n}\n"]}

package/src/branch-reaper.d.ts

@@ -0,0 +1,122 @@
+import { BranchArchiver } from './branch-archiver';
+import { BranchMutationLog, MutationVerb } from './branch-mutation-log';
+import { DeletableBranch, MergedBranchesCache } from './merged-branch-verdicts';
+import { MergedBranchesService } from './merged-branches';
+/**
+ * The EXECUTOR for the dead-branch verdicts that merged-branches.ts computes.
+ *
+ * WHY this exists: for a long time nothing in the tooling ever deleted a branch. The reap was only
+ * ever a `git branch -D a b c` STRING embedded in a guard's fix hint, handed to an AI agent — which
+ * reads a raw `-D` as destructive, asks "may I clean this up?", and stops. So the verdicts were
+ * computed correctly on every hook call and then acted on by nobody, and local branches grew without
+ * bound. The fix is not better wording; it is a thing that does the deleting.
+ *
+ * WHY deleting here is safe: every entry in `deletable` earned its place by one of exactly three
+ * proofs — a MERGED PR (the work is in main), a squash-merge BACKUP of a merged branch, or ZERO
+ * commits of its own (there is no work). merged-branches.ts also guarantees `main` is never in the
+ * list and that a branch checked out in ANY worktree lands in `keep` instead, so we can never delete
+ * the branch someone is standing on. On top of that, every delete is logged with the branch's
+ * pre-delete SHA and a literal recover command, so no reap is unrecoverable.
+ */
+export declare class ReapedBranch {
+    branch: string;
+    sha: string;
+    reason: string;
+    pr: number;
+    ok: boolean;
+    error: string;
+    /**
+     * The `archive/<date>/<branch>` tag written immediately BEFORE the delete, or '' when the retention
+     * policy is 'delete'. Non-empty means the branch is restorable by NAME rather than by remembering a
+     * sha — `git checkout -b <branch> <tag>` restores the exact objects, and the tag survives `gc` and
+     * reflog expiry. Field-with-default so every existing `new ReapedBranch(...)` call site still builds.
+     */
+    archiveTag: string;
+    /**
+     * The branch was ALREADY GONE when we reached it — someone else reaped it first.
+     *
+     * Not a failure, and the distinction is not cosmetic. `wp-cleanup` and the detached refresher's
+     * `auto-reap` both act on their own fresh verdicts, and the hooks kick off the refresher on the
+     * same commands a human runs wp-cleanup from, so the two race by design. Observed 2026-08-04:
+     * auto-reap deleted both dead branches at 14:30:58.207 and 14:30:59.035, wp-cleanup reached them
+     * 300ms later and reported "⚠️ 2 branch(es) could not be deleted — could not archive it first:
+     * unknown revision", i.e. it announced a failure for the exact outcome it wanted. Whoever wins,
+     * the branch is gone, archived and logged by the winner.
+     *
+     * Field-with-default so every existing `new ReapedBranch(...)` call site still builds.
+     */
+    alreadyGone: boolean;
+    constructor(branch: string, sha: string, reason: string, pr: number, ok: boolean, error: string);
+}
+/**
+ * The outcome of one reap. `spared` is carried alongside deliberately: a cleanup that silently says
+ * nothing about the branches it did NOT touch reads as "there was nothing else", when in fact those
+ * are exactly the branches only a human can rule on.
+ */
+export declare class ReapResult {
+    reaped: ReapedBranch[];
+    failed: ReapedBranch[];
+    spared: DeletableBranch[];
+    /**
+     * Branches a CONCURRENT reaper got to first (see ReapedBranch.alreadyGone). A separate bucket
+     * because they belong in neither of the other two: counting them as `reaped` would credit this
+     * run with a delete and an archive tag it did not write, and counting them as `failed` is the bug
+     * this fixes — a red warning about branches that are, in fact, gone.
+     *
+     * Optional so every existing `new ReapResult(...)` call site still builds.
+     */
+    alreadyGone: ReapedBranch[];
+    constructor(reaped: ReapedBranch[], failed: ReapedBranch[], spared: DeletableBranch[], alreadyGone?: ReapedBranch[]);
+}
+export declare class BranchReaper {
+    private readonly mergedBranches;
+    private readonly mutationLog;
+    private readonly archiver;
+    constructor(mergedBranches?: MergedBranchesService, mutationLog?: BranchMutationLog, archiver?: BranchArchiver);
+    /**
+     * Delete every branch the verdicts call dead, one command at a time.
+     *
+     * `cache` is an ALREADY-FRESH set of verdicts (the refresher just computed them, so re-running
+     * the `gh` lookup would be pure waste). Pass nothing — as `wp-cleanup` does — and we recompute
+     * from scratch. That distinction is load-bearing: the cache file on disk is DELIBERATELY allowed
+     * to go stale, which is fine for blocking a branch creation but is not fine for deleting, since a
+     * branch may have gained commits since it was written. Deleting never reads the stale file.
+     */
+    reap(repoRoot: string, verb: MutationVerb, cache?: MergedBranchesCache | null, retention?: string): ReapResult;
+    /**
+     * Delete a CALLER-SUPPLIED list of branches — the branches a human just said yes to at wp-cleanup's
+     * classification prompt. Separate from `reap` because these are NOT provably dead: they earned their
+     * deletion from an explicit human answer, not from a verdict, so nothing here may ever run unattended.
+     * Archiving still happens first, which is precisely what makes that yes low-stakes.
+     */
+    reapApproved(repoRoot: string, verb: MutationVerb, approved: DeletableBranch[], retention?: string): ReapResult;
+    private reapBranches;
+    /**
+     * One branch: ARCHIVE the tip as a tag, then one `git branch -D`. Never the multi-name form the old
+     * fix hint used: git aborts the whole command on the first branch it refuses, which would strand
+     * every branch after it in the list. One invocation each means one failure costs exactly one branch.
+     *
+     * The archive comes FIRST and, when it fails, the delete does NOT happen. A branch we could not
+     * archive is a branch whose only remaining copy is the reflog, and the entire point of this change is
+     * to stop relying on the reflog. Refusing to delete is the fail-safe direction: the worst case is a
+     * branch that survives one more cleanup cycle.
+     */
+    private deleteOne;
+    /**
+     * The branch vanished between the verdict and the reap — a concurrent reaper got it.
+     *
+     * Logged like every other outcome (a mutation nobody logs is a mutation nobody can audit), but
+     * as ALREADY_GONE rather than SKIPPED/FAILED, and carried in its own bucket so the report can
+     * say "already gone" instead of warning about a branch that is exactly as dead as intended.
+     */
+    private alreadyGone;
+    private archiveFailed;
+    /**
+     * Write the verdicts back with the reaped branches removed, so the branch-creation-guard's cap
+     * sees the post-reap truth on its very next call instead of continuing to block against branches
+     * that no longer exist. Anything that FAILED to delete stays in `deletable` — it is still there,
+     * and still dead.
+     */
+    private rewriteCache;
+    private capture;
+}

package/src/branch-reaper.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BranchReaper = exports.ReapResult = exports.ReapedBranch = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const inversify_1 = require("inversify");
+const branch_archiver_1 = require("./branch-archiver");
+const branch_mutation_log_1 = require("./branch-mutation-log");
+const merged_branch_verdicts_1 = require("./merged-branch-verdicts");
+const merged_branches_1 = require("./merged-branches");
+/**
+ * The EXECUTOR for the dead-branch verdicts that merged-branches.ts computes.
+ *
+ * WHY this exists: for a long time nothing in the tooling ever deleted a branch. The reap was only
+ * ever a `git branch -D a b c` STRING embedded in a guard's fix hint, handed to an AI agent — which
+ * reads a raw `-D` as destructive, asks "may I clean this up?", and stops. So the verdicts were
+ * computed correctly on every hook call and then acted on by nobody, and local branches grew without
+ * bound. The fix is not better wording; it is a thing that does the deleting.
+ *
+ * WHY deleting here is safe: every entry in `deletable` earned its place by one of exactly three
+ * proofs — a MERGED PR (the work is in main), a squash-merge BACKUP of a merged branch, or ZERO
+ * commits of its own (there is no work). merged-branches.ts also guarantees `main` is never in the
+ * list and that a branch checked out in ANY worktree lands in `keep` instead, so we can never delete
+ * the branch someone is standing on. On top of that, every delete is logged with the branch's
+ * pre-delete SHA and a literal recover command, so no reap is unrecoverable.
+ */
+// Data-only (per CLAUDE.md, classes for data). One branch and what happened to it.
+class ReapedBranch {
+    branch;
+    // The commit the branch pointed at BEFORE deletion — captured first, precisely so a delete is
+    // always undoable via `git branch <branch> <sha>`. Empty only if rev-parse itself failed.
+    sha;
+    reason;
+    pr;
+    ok;
+    // git's own stderr when ok=false. Kept verbatim: a failed delete is a thing a human must read.
+    error;
+    /**
+     * The `archive/<date>/<branch>` tag written immediately BEFORE the delete, or '' when the retention
+     * policy is 'delete'. Non-empty means the branch is restorable by NAME rather than by remembering a
+     * sha — `git checkout -b <branch> <tag>` restores the exact objects, and the tag survives `gc` and
+     * reflog expiry. Field-with-default so every existing `new ReapedBranch(...)` call site still builds.
+     */
+    archiveTag = '';
+    /**
+     * The branch was ALREADY GONE when we reached it — someone else reaped it first.
+     *
+     * Not a failure, and the distinction is not cosmetic. `wp-cleanup` and the detached refresher's
+     * `auto-reap` both act on their own fresh verdicts, and the hooks kick off the refresher on the
+     * same commands a human runs wp-cleanup from, so the two race by design. Observed 2026-08-04:
+     * auto-reap deleted both dead branches at 14:30:58.207 and 14:30:59.035, wp-cleanup reached them
+     * 300ms later and reported "⚠️ 2 branch(es) could not be deleted — could not archive it first:
+     * unknown revision", i.e. it announced a failure for the exact outcome it wanted. Whoever wins,
+     * the branch is gone, archived and logged by the winner.
+     *
+     * Field-with-default so every existing `new ReapedBranch(...)` call site still builds.
+     */
+    alreadyGone = false;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(branch, sha, reason, pr, ok, error) {
+        this.branch = branch;
+        this.sha = sha;
+        this.reason = reason;
+        this.pr = pr;
+        this.ok = ok;
+        this.error = error;
+    }
+}
+exports.ReapedBranch = ReapedBranch;
+/**
+ * The outcome of one reap. `spared` is carried alongside deliberately: a cleanup that silently says
+ * nothing about the branches it did NOT touch reads as "there was nothing else", when in fact those
+ * are exactly the branches only a human can rule on.
+ */
+class ReapResult {
+    reaped;
+    failed;
+    spared;
+    /**
+     * Branches a CONCURRENT reaper got to first (see ReapedBranch.alreadyGone). A separate bucket
+     * because they belong in neither of the other two: counting them as `reaped` would credit this
+     * run with a delete and an archive tag it did not write, and counting them as `failed` is the bug
+     * this fixes — a red warning about branches that are, in fact, gone.
+     *
+     * Optional so every existing `new ReapResult(...)` call site still builds.
+     */
+    alreadyGone;
+    constructor(reaped, failed, spared, alreadyGone = []) {
+        this.reaped = reaped;
+        this.failed = failed;
+        this.spared = spared;
+        this.alreadyGone = alreadyGone;
+    }
+}
+exports.ReapResult = ReapResult;
+let BranchReaper = class BranchReaper {
+    mergedBranches;
+    mutationLog;
+    archiver;
+    // Defaulted so the non-DI call sites (the detached refresher in sync-main.ts) can just
+    // `new BranchReaper()`, while inversify still injects the singletons when resolved from a
+    // container. Mirrors how MergedBranchesService defaults its WorktreeService.
+    constructor(mergedBranches = new merged_branches_1.MergedBranchesService(), mutationLog = new branch_mutation_log_1.BranchMutationLog(), archiver = new branch_archiver_1.BranchArchiver()) {
+        this.mergedBranches = mergedBranches;
+        this.mutationLog = mutationLog;
+        this.archiver = archiver;
+    }
+    /**
+     * Delete every branch the verdicts call dead, one command at a time.
+     *
+     * `cache` is an ALREADY-FRESH set of verdicts (the refresher just computed them, so re-running
+     * the `gh` lookup would be pure waste). Pass nothing — as `wp-cleanup` does — and we recompute
+     * from scratch. That distinction is load-bearing: the cache file on disk is DELIBERATELY allowed
+     * to go stale, which is fine for blocking a branch creation but is not fine for deleting, since a
+     * branch may have gained commits since it was written. Deleting never reads the stale file.
+     */
+    reap(repoRoot, verb, cache = null, retention = branch_archiver_1.BRANCH_RETENTION_ARCHIVE_TAG) {
+        // `false`: this is the BRANCH reap, and worktree locks are none of its business. Ignoring one
+        // would only widen the WORKTREE verdicts it never reads.
+        const verdicts = cache ?? this.mergedBranches.computeMergedBranches(repoRoot, false);
+        // 'keep' means "never delete anything" — the reap becomes a pure report. Everything still lands
+        // in `spared` so the human sees exactly what WOULD have been reaped under the other policies.
+        if (retention === branch_archiver_1.BRANCH_RETENTION_KEEP) {
+            return new ReapResult([], [], [...verdicts.deletable, ...verdicts.keep]);
+        }
+        return this.reapBranches(repoRoot, verb, verdicts.deletable, retention, verdicts);
+    }
+    /**
+     * Delete a CALLER-SUPPLIED list of branches — the branches a human just said yes to at wp-cleanup's
+     * classification prompt. Separate from `reap` because these are NOT provably dead: they earned their
+     * deletion from an explicit human answer, not from a verdict, so nothing here may ever run unattended.
+     * Archiving still happens first, which is precisely what makes that yes low-stakes.
+     */
+    reapApproved(repoRoot, verb, approved, retention = branch_archiver_1.BRANCH_RETENTION_ARCHIVE_TAG) {
+        if (retention === branch_archiver_1.BRANCH_RETENTION_KEEP)
+            return new ReapResult([], [], approved);
+        const reaped = [];
+        const failed = [];
+        const alreadyGone = [];
+        for (const entry of approved) {
+            const outcome = this.deleteOne(repoRoot, verb, entry, retention);
+            if (outcome.ok)
+                reaped.push(outcome);
+            else if (outcome.alreadyGone)
+                alreadyGone.push(outcome);
+            else
+                failed.push(outcome);
+        }
+        return new ReapResult(reaped, failed, [], alreadyGone);
+    }
+    reapBranches(repoRoot, verb, targets, retention, verdicts) {
+        const reaped = [];
+        const failed = [];
+        const alreadyGone = [];
+        for (const entry of targets) {
+            const outcome = this.deleteOne(repoRoot, verb, entry, retention);
+            if (outcome.ok)
+                reaped.push(outcome);
+            else if (outcome.alreadyGone)
+                alreadyGone.push(outcome);
+            else
+                failed.push(outcome);
+        }
+        // Only genuine failures stay in the cache's `deletable`. An already-gone branch is not there
+        // to delete on the next pass, and leaving it in would make the cap keep counting a ghost.
+        this.rewriteCache(repoRoot, verdicts, failed);
+        return new ReapResult(reaped, failed, verdicts.keep, alreadyGone);
+    }
+    /**
+     * One branch: ARCHIVE the tip as a tag, then one `git branch -D`. Never the multi-name form the old
+     * fix hint used: git aborts the whole command on the first branch it refuses, which would strand
+     * every branch after it in the list. One invocation each means one failure costs exactly one branch.
+     *
+     * The archive comes FIRST and, when it fails, the delete does NOT happen. A branch we could not
+     * archive is a branch whose only remaining copy is the reflog, and the entire point of this change is
+     * to stop relying on the reflog. Refusing to delete is the fail-safe direction: the worst case is a
+     * branch that survives one more cleanup cycle.
+     */
+    deleteOne(repoRoot, verb, entry, retention) {
+        // SHA first — after the delete there is no branch left to resolve, and the whole point of the
+        // audit line is that it records what was destroyed while it still exists.
+        const resolved = this.capture(repoRoot, ['rev-parse', entry.branch]);
+        const sha = resolved.ok ? resolved.out : '';
+        // It does not resolve ⇒ it is already gone, reaped by whoever won the race (see
+        // ReapedBranch.alreadyGone). Report that outcome honestly instead of letting it fall through
+        // to the archive, which fails on the same missing ref and calls a successful cleanup a
+        // failure. Nothing to archive and nothing to delete: the winner did both, and logged them.
+        if (!resolved.ok)
+            return this.alreadyGone(repoRoot, verb, entry);
+        const archive = retention === branch_archiver_1.BRANCH_RETENTION_ARCHIVE_TAG
+            ? this.archiver.archive(repoRoot, entry.branch)
+            : new branch_archiver_1.ArchiveResult('', sha, true, '');
+        if (!archive.ok)
+            return this.archiveFailed(repoRoot, verb, entry, sha, archive);
+        const deleted = this.capture(repoRoot, ['branch', '-D', entry.branch]);
+        const result = new ReapedBranch(entry.branch, sha, entry.reason, entry.pr, deleted.ok, deleted.ok ? '' : deleted.err);
+        result.archiveTag = archive.tag;
+        const event = new branch_mutation_log_1.BranchMutationEvent(verb, 'REAP');
+        event.fromBranch = entry.branch;
+        event.sha = sha;
+        event.archiveTag = archive.tag;
+        event.outcome = deleted.ok ? `deleted (${entry.reason})` : `FAILED (${deleted.err})`;
+        this.mutationLog.logBranchMutation(repoRoot, event);
+        return result;
+    }
+    /**
+     * The branch vanished between the verdict and the reap — a concurrent reaper got it.
+     *
+     * Logged like every other outcome (a mutation nobody logs is a mutation nobody can audit), but
+     * as ALREADY_GONE rather than SKIPPED/FAILED, and carried in its own bucket so the report can
+     * say "already gone" instead of warning about a branch that is exactly as dead as intended.
+     */
+    alreadyGone(repoRoot, verb, entry) {
+        const event = new branch_mutation_log_1.BranchMutationEvent(verb, 'REAP');
+        event.fromBranch = entry.branch;
+        event.outcome = 'ALREADY GONE (a concurrent reap deleted and archived it first)';
+        this.mutationLog.logBranchMutation(repoRoot, event);
+        const result = new ReapedBranch(entry.branch, '', entry.reason, entry.pr, false, 'already gone — a concurrent reap deleted and archived it first');
+        result.alreadyGone = true;
+        return result;
+    }
+    // Archiving failed ⇒ the branch is NOT deleted. Reported as a failure with git's own words, so the
+    // human sees a branch that survived and why, rather than a silent skip.
+    archiveFailed(repoRoot, verb, entry, sha, archive) {
+        const error = `not deleted — could not archive it first: ${archive.error}`;
+        const event = new branch_mutation_log_1.BranchMutationEvent(verb, 'REAP');
+        event.fromBranch = entry.branch;
+        event.sha = sha;
+        event.outcome = `SKIPPED (${error})`;
+        this.mutationLog.logBranchMutation(repoRoot, event);
+        return new ReapedBranch(entry.branch, sha, entry.reason, entry.pr, false, error);
+    }
+    /**
+     * Write the verdicts back with the reaped branches removed, so the branch-creation-guard's cap
+     * sees the post-reap truth on its very next call instead of continuing to block against branches
+     * that no longer exist. Anything that FAILED to delete stays in `deletable` — it is still there,
+     * and still dead.
+     */
+    rewriteCache(repoRoot, verdicts, failed) {
+        const stillDead = new Set(failed.map((entry) => entry.branch));
+        const remaining = verdicts.deletable.filter((entry) => stillDead.has(entry.branch));
+        this.mergedBranches.writeMergedBranches(repoRoot, new merged_branch_verdicts_1.MergedBranchesCache(verdicts.timestamp, remaining, verdicts.keep, verdicts.worktrees));
+    }
+    // Run a git command capturing trimmed stdout/stderr; ok=false on spawn failure or non-zero exit.
+    capture(repoRoot, args) {
+        const result = (0, child_process_1.spawnSync)('git', args, { cwd: repoRoot, encoding: 'utf8' });
+        const err = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+        if (result.status !== 0 || typeof result.stdout !== 'string') {
+            return { ok: false, out: '', err: err !== '' ? err : 'git command failed' };
+        }
+        return { ok: true, out: result.stdout.trim(), err };
+    }
+};
+exports.BranchReaper = BranchReaper;
+exports.BranchReaper = BranchReaper = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [merged_branches_1.MergedBranchesService,
+        branch_mutation_log_1.BranchMutationLog,
+        branch_archiver_1.BranchArchiver])
+], BranchReaper);
+//# sourceMappingURL=branch-reaper.js.map