greprag 5.80.0 → 5.82.0

package/dist/commands/merge-guard.js

@@ -0,0 +1,419 @@
+"use strict";
+/** merge-guard.ts — PreToolUse[Bash]: no `git merge` into a shared canonical
+ *  checkout without holding the merge lock.
+ *
+ *  WHY A GUARD AND NOT A REMINDER. The merge lock and the provenance claim both
+ *  work, and both are advisory: a session that simply runs `git merge` skips them
+ *  and nothing notices. That is not hypothetical. On 2026-09-04 two sessions
+ *  merged into the same Sift checkout at once, one resolved the other's conflicts
+ *  and completed the merge under a new sha, and the first session's merge commit
+ *  ended up on no branch — it found out only because its deploy shipped a
+ *  different commit than it had merged. `merge-state` catches the aftermath;
+ *  nothing was stopping the collision.
+ *
+ *  SCOPE — deliberately narrow, because an over-broad guard gets bypassed for
+ *  being wrong:
+ *    · only the canonical primary checkout named by `.greprag/delivery.json`.
+ *      A merge inside an isolated worktree affects nobody else and is untouched.
+ *    · only a merge that STARTS one. `--abort`, `--continue` and `--quit` finish
+ *      or abandon a merge already in progress and must never be blocked — that
+ *      would strand exactly the conflicted checkout this whole effort is about.
+ *    · never `git merge-base`, `merge-file` or `merge-tree`. Those are read-only
+ *      plumbing that happens to share a prefix, and `merge-base` is used BY the
+ *      provenance check — blocking it would break the gate with the guard.
+ *    · only a merge nothing already serialises. A command that takes the lock
+ *      itself, ahead of the merge and `&&`-joined to it, is already serialised.
+ *
+ *  Holding the lock yourself is a pass. A peer holding it is the refusal that
+ *  matters: it is the exact collision, caught before the merge instead of after.
+ *
+ *  TWO FALSE REJECTIONS, both on 2026-09-06 in C:/sift, both fixed here.
+ *
+ *  1. THE SHELL'S CWD IS NOT THE MERGE TARGET. The guard compared the hook's
+ *     `cwd` against `canonicalRoot`, so `git -C <worktree> merge master` run from
+ *     C:/sift was refused — a merge inside a worktree, which this file's own
+ *     refusal promises is never blocked. The same string compare was wrong in the
+ *     other direction too: a plain `git merge` from any SUBDIRECTORY of the
+ *     canonical checkout did not match the root and sailed through unguarded.
+ *     One check, two opposite errors, because it asked the wrong question. The
+ *     question is not "where is the shell" but "which worktree does this merge
+ *     land in", and only git can answer that — so the guard now asks it, running
+ *     `rev-parse --show-toplevel` with the same `-C`/`--git-dir` options and from
+ *     the same directory the merge itself will use. (The worktree WRITE guard hit
+ *     this same defect on 2026-09-05 and was repaired the same way: stop reading
+ *     the payload cwd as if it named the thing being acted on.)
+ *
+ *  2. AN ACQUIRE IN THE SAME COMMAND IS AN ACQUIRE. The guard saw `git merge` and
+ *     read the lock file, which the `greprag merge-lock acquire` two tokens to its
+ *     left had not yet written, and refused. `acquire` exits 1 when anyone else
+ *     holds the lock, so `acquire && merge && release` cannot merge past a peer —
+ *     `&&` stops it. Refusing that chain protected nothing and cost three round
+ *     trips. Only `&&` earns this: after `;` or `||` the merge still runs when the
+ *     acquire failed, so those are refused, and the refusal now says so.
+ *
+ *  # adr: adr/deploy-gate-cli.md
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startsAMerge = startsAMerge;
+exports.mergeTakesItsOwnLock = mergeTakesItsOwnLock;
+exports.buildMergeGuardReason = buildMergeGuardReason;
+exports.runMergeGuard = runMergeGuard;
+const deploy_locks_1 = require("../deploy-locks");
+const delivery_config_1 = require("../delivery-config");
+const deploy_gate_1 = require("../deploy-gate");
+const proc_1 = require("../proc");
+const path = __importStar(require("path"));
+/** Git's global options that take their value as a SEPARATE token. `git -c k=v merge`
+ *  is the one that matters in practice — a regex that skips only `-*` tokens reads
+ *  `k=v` as the subcommand and waves the merge through. */
+const GLOBAL_OPTS_WITH_VALUE = new Set(['-c', '-C', '--git-dir', '--work-tree', '--namespace', '--exec-path']);
+/** Blank out the CONTENTS of quoted spans, keeping the string's length and its
+ *  quote characters. Two things depend on this:
+ *
+ *  · splitting. Without it a script that merely QUOTES a command —
+ *    `node -e "... 'cd X && git merge Y' ..."` — splits on the `&&` inside the
+ *    quotes and yields a segment that really does begin `git merge`. That false
+ *    positive blocked this guard's own test suite the first time it ran.
+ *  · offsets. The mask is only used to FIND separators; every segment is then cut
+ *    from the original string, so `git -C "C:/some path" merge` still carries its
+ *    real path. The earlier mask collapsed a quoted span to two characters, which
+ *    is why a quoted `-C` value could not be read at all. */
+function maskQuoted(command) {
+    return command
+        .replace(/'[^']*'/g, m => `'${' '.repeat(m.length - 2)}'`)
+        .replace(/"[^"]*"/g, m => `"${' '.repeat(m.length - 2)}"`);
+}
+/** Split a command on the shell separators a caller might chain with, keeping
+ *  each segment's original text and whether `&&` joined it to what came before. */
+function shellSegments(command) {
+    const source = String(command || '');
+    const masked = maskQuoted(source);
+    const separator = /&&|\|\||[;\n|]/g;
+    const segments = [];
+    let start = 0;
+    let afterAnd = true;
+    for (let match = separator.exec(masked); match; match = separator.exec(masked)) {
+        segments.push({ text: source.slice(start, match.index), afterAnd });
+        afterAnd = match[0] === '&&';
+        start = match.index + match[0].length;
+    }
+    segments.push({ text: source.slice(start), afterAnd });
+    return segments;
+}
+/** Quote-aware tokens. A quoted run is one token with its quotes removed, so
+ *  `-C "C:/a path"` reads as the directory it names. */
+function tokenize(segment) {
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    let open = false;
+    for (const ch of segment) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            open = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (current || open)
+                tokens.push(current);
+            current = '';
+            open = false;
+            continue;
+        }
+        current += ch;
+    }
+    if (current || open)
+        tokens.push(current);
+    return tokens;
+}
+/** The git global options a merge command carries (everything between `git` and
+ *  `merge`), or null when this segment does not start a merge in this repository. */
+function mergeGlobalOpts(segment) {
+    const tokens = tokenize(segment);
+    if (!/^(?:git|git\.exe)$/i.test(tokens[0] || ''))
+        return null;
+    // Walk past git's own global options to find the subcommand.
+    let i = 1;
+    while (i < tokens.length && tokens[i].startsWith('-')) {
+        if (GLOBAL_OPTS_WITH_VALUE.has(tokens[i]))
+            i += 2;
+        else
+            i += 1;
+    }
+    // `merge` exactly: never merge-base / merge-file / merge-tree.
+    if (tokens[i] !== 'merge')
+        return null;
+    // Finishing or abandoning an in-progress merge is always allowed.
+    if (tokens.slice(i + 1).some(t => t === '--abort' || t === '--continue' || t === '--quit'))
+        return null;
+    return tokens.slice(1, i);
+}
+/** Pure. True only for a command that STARTS a merge in this repository. */
+function startsAMerge(command) {
+    return shellSegments(command).some(s => mergeGlobalOpts(s.text) !== null);
+}
+/** True for a `greprag merge-lock acquire` — the command whose exit code is what
+ *  makes an `&&` chain serialised. `status` and `release` are not it. */
+function isMergeLockAcquire(segment) {
+    const tokens = tokenize(segment);
+    const start = tokens[0] === '&' ? 1 : 0;
+    return /(^|[\\/])greprag(\.[a-z]+)?$/i.test(tokens[start] || '')
+        && tokens[start + 1] === 'merge-lock' && tokens[start + 2] === 'acquire';
+}
+/** True when the command takes the merge lock itself, ahead of the merge, with
+ *  nothing but `&&` between them.
+ *
+ *  `acquire` exits 1 when someone else holds the lock, so `&&` refuses to run the
+ *  merge — the chain is already serialised and the guard has nothing to add. After
+ *  a `;` or `||` the merge runs even though the acquire failed, which is precisely
+ *  the collision this guard exists to prevent. */
+function mergeTakesItsOwnLock(command) {
+    const segments = shellSegments(command);
+    const mergeAt = segments.findIndex(s => mergeGlobalOpts(s.text) !== null);
+    if (mergeAt <= 0)
+        return false;
+    for (let i = mergeAt; i > 0; i--) {
+        if (!segments[i].afterAnd)
+            return false; // a `;` or `||` broke the chain
+        if (isMergeLockAcquire(segments[i - 1].text))
+            return true;
+    }
+    return false;
+}
+/** The directory the merge command will actually run in: the shell's cwd, moved by
+ *  any `cd` that precedes the merge in the same chain. */
+function mergeCwd(segments, mergeAt, cwd) {
+    let dir = cwd;
+    for (let i = 0; i < mergeAt; i++) {
+        const tokens = tokenize(segments[i].text);
+        if (!/^(cd|Set-Location)$/i.test(tokens[0] || ''))
+            continue;
+        const dest = /^-(LiteralPath|Path)$/i.test(tokens[1] || '') ? tokens[2] : tokens[1];
+        if (!dest || dest === '-')
+            continue;
+        dir = path.resolve(dir, dest);
+    }
+    return dir;
+}
+/** The worktree this merge lands in, asked of git rather than guessed from a path.
+ *
+ *  Returns null when git cannot answer — no repository, git missing, options it
+ *  rejects. The caller falls back to the directory itself, which is the pre-2026-09-06
+ *  behaviour and still refuses a bare merge run at the canonical root. */
+function mergeWorktreeRoot(globalOpts, dir) {
+    try {
+        const result = (0, proc_1.safeSpawnSync)('git', [...globalOpts, 'rev-parse', '--show-toplevel'], {
+            encoding: 'utf8', cwd: dir, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.status !== 0)
+            return null;
+        const top = String(result.stdout).trim();
+        return top || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Merge location is Git topology, not deploy policy. Ref-push repos such as
+ *  PayBot omit deploy.canonicalRoot but still share a primary checkout. */
+function canonicalRoot(cwd) {
+    const resolved = (0, delivery_config_1.resolveDeliveryProfile)(cwd);
+    if (resolved.mode !== 'profile')
+        return null;
+    if (resolved.profile?.deploy?.canonicalRoot)
+        return resolved.profile.deploy.canonicalRoot;
+    const common = (0, proc_1.safeSpawnSync)('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+        cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (common.status !== 0)
+        return null;
+    const gitDir = String(common.stdout).trim();
+    return path.basename(gitDir) === '.git' ? path.dirname(gitDir) : null;
+}
+function buildMergeGuardReason(held, ownership) {
+    if (ownership === 'peer' && held) {
+        return [
+            'MERGE BLOCKED: another session is already merging into this canonical checkout',
+            `(session ${(0, deploy_locks_1.describeLockOwner)(held.record)}, since ${held.record.startedAt}).`,
+            'Two merges at once is how one gets orphaned onto no branch — it happened here on 2026-09-04.',
+            'Wait for it to finish, then merge. If you know that session is gone: greprag merge-lock release',
+        ].join(' ');
+    }
+    // The lock is real but nobody can be shown to hold it — either it was written without
+    // a session id, or this harness exports none. Saying "another session" here is a lie
+    // that shuts the holder out of its own merge with no stated way back in; this says what
+    // is actually known and names the one command that resolves it.
+    if (ownership === 'unattributable' && held) {
+        return [
+            'MERGE BLOCKED: this checkout holds a merge lock that names no owner',
+            `(pid ${held.record.pid}, since ${held.record.startedAt}), so it cannot be told from yours.`,
+            'It is most likely YOUR OWN lock, taken before this session had an id.',
+            'If you took it, or nobody else is merging here: greprag merge-lock release — then acquire and merge again.',
+        ].join(' ');
+    }
+    return [
+        'MERGE BLOCKED: take the merge lock first — this is the shared canonical checkout, and',
+        'merges into it are serialised the way deploys already are.',
+        '  greprag merge-lock acquire --label "<what you are merging>"',
+        '  git merge --ff-only <rebased branch>',
+        '  greprag merge-lock release --landed <the merge sha> --label "<what it was>"',
+        'One call works too, as long as the acquire comes first and every step is joined by',
+        '`&&` — that is what stops the merge when someone else holds the lock. A `;` or `||`',
+        'between them runs the merge anyway, so those are refused.',
+        '`--landed` is what lets the deploy prove YOUR work is in what ships, rather than only',
+        'that production serves HEAD. Merging in a worktree instead? That is never blocked.',
+    ].join(' ');
+}
+function runMergeGuard(input) {
+    const tool = String(input.tool_name || '').toLowerCase().split('.').pop();
+    if (!['bash', 'shell', 'exec_command', 'shell_command'].includes(tool || ''))
+        return null;
+    const command = input.tool_input?.command ?? input.tool_input?.cmd;
+    if (typeof command !== 'string')
+        return null;
+    const segments = shellSegments(command);
+    for (let mergeAt = 0; mergeAt < segments.length; mergeAt++) {
+        if (mergeGlobalOpts(segments[mergeAt].text) === null)
+            continue;
+        const out = guardMergeAt(input, segments, mergeAt);
+        if (out)
+            return out;
+    }
+    return null;
+}
+function guardMergeAt(input, segments, mergeAt) {
+    const cwd = input.tool_input?.workdir || input.cwd || process.cwd();
+    const globalOpts = mergeGlobalOpts(segments[mergeAt].text) || [];
+    const dir = mergeCwd(segments, mergeAt, cwd);
+    const target = mergeWorktreeRoot(globalOpts, dir) ?? dir;
+    let root;
+    try {
+        root = canonicalRoot(target);
+    }
+    catch {
+        return null;
+    }
+    if (!root)
+        return null;
+    // Which worktree does this merge land in? Not "where is the shell" — the two differ
+    // whenever the command carries a `cd` or a `-C`, and that difference is the whole bug.
+    // Not the shared checkout (a worktree, a clone, an unprofiled repo) — not our business.
+    if ((0, deploy_gate_1.normalizePath)(target) !== (0, deploy_gate_1.normalizePath)(root))
+        return null;
+    let held = null;
+    try {
+        held = (0, deploy_locks_1.readMergeLock)(target);
+        // Explicit --continue/--abort/--quit already bypass the start matcher. A new
+        // merge must never adopt another session's unfinished integration.
+        if ((0, deploy_locks_1.readMergeState)(target).inProgress)
+            return denyMerge(input, 'MERGE BLOCKED: an integration is already in progress here. Resolve its ownership and finish or abort it before starting another merge.');
+    }
+    catch {
+        // Cannot read the lock — say nothing rather than block a merge on our own fault.
+        return null;
+    }
+    // Both sides go through the shared session helpers rather than a hand-rolled
+    // `slice(0, 8)`. A UUIDv7 harness (Codex, Grok) is addressed by 16 hex digits, and
+    // truncating it locally to 8 was a second copy of identity logic waiting to disagree
+    // with the one in session-id.ts.
+    const ownership = (0, deploy_locks_1.lockOwnership)(held, input.session_id);
+    const chainedLock = takesLockForTarget(segments, mergeAt, cwd, target);
+    if (ownership !== 'mine' && !chainedLock)
+        return denyMerge(input, buildMergeGuardReason(held, ownership));
+    // Git owns the final freshness check AT mutation time. Even if master changes
+    // after this hook (or after a chained acquire), --ff-only cannot integrate a
+    // divergent branch. Rebase and tests stay in the isolated source worktree.
+    const words = tokenize(segments[mergeAt].text);
+    const args = words.slice(1 + globalOpts.length + 1);
+    if (!requestsFastForwardOnly(args)) {
+        return denyMerge(input, 'MERGE BLOCKED: shared-checkout integration requires git merge --ff-only <branch>. '
+            + 'Fetch the configured remote, update the default branch, rebase your worktree onto its current tip, '
+            + 'resolve conflicts and rerun the affected checks there. Take the merge lock, recheck the tip, '
+            + 'then fast-forward. If the default branch moved again, free your lock and repeat the rebase/checks. '
+            + 'Record the landed commit when freeing the lock; never rebase the shared default branch.');
+    }
+    return null;
+}
+/** Only an option counts, not a message, strategy option, or revision after --. */
+function requestsFastForwardOnly(args) {
+    let ffOnly = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--')
+            break;
+        if (['-m', '--message', '-s', '--strategy', '-X', '--strategy-option', '-F', '--file'].includes(arg)) {
+            i++;
+            continue;
+        }
+        if (arg === '--ff-only')
+            ffOnly = true;
+        if (['--ff', '--no-ff', '--squash', '--no-commit'].includes(arg))
+            return false;
+    }
+    return ffOnly;
+}
+/** An acquire only serialises THIS merge when it runs in this checkout, and
+ *  nothing frees the lock before the merge. Inspect every merge in a batch. */
+function takesLockForTarget(segments, mergeAt, cwd, target) {
+    for (let i = mergeAt; i > 0; i--) {
+        if (!segments[i].afterAnd)
+            return false;
+        const words = tokenize(segments[i - 1].text);
+        if (words.includes('merge-lock') && words.includes('release'))
+            return false;
+        if (!isMergeLockAcquire(segments[i - 1].text))
+            continue;
+        const lockDir = mergeCwd(segments, i - 1, cwd);
+        return (0, deploy_gate_1.normalizePath)(mergeWorktreeRoot([], lockDir) ?? lockDir) === (0, deploy_gate_1.normalizePath)(target);
+    }
+    return false;
+}
+function denyMerge(input, reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: input.hook_event_name || 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    };
+}

package/dist/commands/merge-lock.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMergeLock = runMergeLock;
+const deploy_locks_1 = require("../deploy-locks");
+const proc_1 = require("../proc");
+const HELP = `greprag merge-lock — serialise merges into a shared canonical checkout
+
+Usage:
+  greprag merge-lock acquire [--label <text>] [--json]
+  greprag merge-lock release [--landed <sha>] [--label <text>] [--json]
+  greprag merge-lock status [--json]
+  greprag merge-lock claim [--drop <sha>] [--json]
+
+Deploys have been serialised for a while; merges have not. On 2026-09-04 two
+sessions merged into the same checkout at once, one resolved the other's
+conflicts, and the first session's merge commit was orphaned onto no branch — it
+found out only because its deploy shipped a different commit than it merged.
+
+Take this before you merge into a shared checkout and release it after. The
+deploy gate refuses while it is held, and reports an open merge that nobody holds
+as abandoned — which is the state a dead session leaves behind.
+
+Exit 0 when the lock is yours, 1 when someone else holds it.
+
+\`--landed <sha>\` records what you just merged. The deploy gate then refuses until
+that commit is actually in what ships. Without it a deploy can only prove production
+serves HEAD — never that HEAD contains your work. On 2026-09-04 a session's merge was
+redone by a peer under a new sha, its deploy exited 0 honestly, and it reported
+shipping work that was on no branch.
+
+Options:
+  --label <text>  What this merge is, shown to whoever is blocked by it
+  --landed <sha>  Record this commit as merged, to be verified at deploy time
+  --drop <sha>    (claim) Forget a claim you have confirmed by hand
+  --json          Machine-readable result`;
+/** Resolve to a full sha, so a claim never depends on an abbreviation staying unique. */
+function resolveCommit(rev, cwd) {
+    const result = (0, proc_1.safeSpawnSync)('git', ['rev-parse', '--verify', `${rev}^{commit}`], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0 ? String(result.stdout).trim() : null;
+}
+function flagValue(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    return value && !value.startsWith('--') ? value : undefined;
+}
+function runMergeLock(args) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+        console.log(HELP);
+        return;
+    }
+    const sub = args[0] || 'status';
+    const json = args.includes('--json');
+    const cwd = process.cwd();
+    let file;
+    try {
+        file = (0, deploy_locks_1.mergeLockPath)(cwd);
+    }
+    catch (error) {
+        console.error(`merge-lock: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (sub === 'acquire') {
+        // Session-held, so never pid-checked: the process running this command exits
+        // immediately and a pid check would mark the lock stale the moment it is taken.
+        const result = (0, deploy_locks_1.acquireLock)(file, flagValue(args, '--label') || 'merge', deploy_locks_1.MERGE_STALE_MS, { checkPid: false });
+        if (json)
+            console.log(JSON.stringify(result));
+        else if (result.ok) {
+            const session = (0, deploy_locks_1.lockSession)();
+            console.log(`merge-lock: held by session ${session || 'UNIDENTIFIED'} (pid ${process.pid})`);
+            if (result.held)
+                console.log(`  reclaimed a stale lock from pid ${result.held.record.pid}`);
+            // Say it HERE, not six round trips later when the merge guard refuses a lock it
+            // cannot attribute. Silence at this point is what made the failure undiagnosable.
+            if (!session) {
+                console.log('  WARNING: no harness session id is set, so this lock records no owner');
+                console.log('  and the merge guard cannot recognise it as yours. Export GREPRAG_SESSION_ID');
+                console.log('  before acquiring, or release and re-acquire once the id is set.');
+            }
+        }
+        else {
+            console.error(`merge-lock: another merge is running in this checkout (pid ${result.held?.record.pid},`
+                + ` session ${result.held ? (0, deploy_locks_1.describeLockOwner)(result.held.record) : 'unidentified'}, started ${result.held?.record.startedAt}).`
+                + '\n  Wait for it. Merge conflicts are the coordination point; two merges at once is how one gets orphaned.');
+        }
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === 'release') {
+        // `--landed <sha>` is how a merge becomes checkable at deploy time. Without it the
+        // deploy can only prove production serves HEAD, never that HEAD contains your work.
+        const landed = flagValue(args, '--landed');
+        if (landed) {
+            const resolved = resolveCommit(landed, cwd);
+            if (!resolved) {
+                console.error(`merge-lock: ${landed} is not a commit in this repository — nothing claimed.`);
+                (0, deploy_locks_1.releaseLock)(file);
+                process.exitCode = 1;
+                return;
+            }
+            try {
+                const claim = (0, deploy_locks_1.recordLandedClaim)(cwd, resolved, flagValue(args, '--label') || 'merged work');
+                console.log(`merge-lock: released; claimed ${claim.sha.slice(0, 10)} as landed`);
+                console.log('  The deploy gate will refuse until that commit is in what ships.');
+            }
+            catch (error) {
+                console.error(`merge-lock: released, but the claim was NOT recorded: ${error instanceof Error ? error.message : String(error)}`);
+                process.exitCode = 1;
+            }
+            (0, deploy_locks_1.releaseLock)(file);
+            return;
+        }
+        (0, deploy_locks_1.releaseLock)(file);
+        if (json)
+            console.log(JSON.stringify({ released: true, path: file }));
+        else
+            console.log('merge-lock: released');
+        return;
+    }
+    if (sub === 'claim') {
+        const drop = flagValue(args, '--drop');
+        if (drop) {
+            console.log((0, deploy_locks_1.dropLandedClaim)(cwd, drop) ? `merge-lock: dropped the claim for ${drop}` : `merge-lock: no claim matching ${drop}`);
+            return;
+        }
+        const all = (0, deploy_locks_1.readLandedClaims)(cwd);
+        const open = (0, deploy_locks_1.openClaims)(cwd, all);
+        if (json) {
+            console.log(JSON.stringify({ all, open }));
+            return;
+        }
+        if (all.length === 0) {
+            console.log('merge-lock: no landed claims recorded');
+            return;
+        }
+        console.log(`merge-lock: ${all.length} claim(s), ${open.length} still unshipped:`);
+        for (const c of all) {
+            const state = open.some(o => o.sha === c.sha)
+                ? ((0, deploy_locks_1.commitExists)(cwd, c.sha) ? 'UNSHIPPED (exists, on no branch — rewritten or redone)' : 'UNSHIPPED (not in this repository)')
+                : 'shipped';
+            console.log(`  ${c.sha.slice(0, 10)}  ${state}  ${c.label}  (${c.at})`);
+        }
+        return;
+    }
+    if (sub === 'status') {
+        const held = (0, deploy_locks_1.readMergeLock)(cwd);
+        const merge = (0, deploy_locks_1.readMergeState)(cwd);
+        if (json) {
+            console.log(JSON.stringify({ held, merge }));
+        }
+        else {
+            if (!held)
+                console.log('merge-lock: not held');
+            else if (held.stale)
+                console.log(`merge-lock: stale (pid ${held.record.pid}, started ${held.record.startedAt}) — would be reclaimed`);
+            else
+                console.log(`merge-lock: held by pid ${held.record.pid}, session ${(0, deploy_locks_1.describeLockOwner)(held.record)}, since ${held.record.startedAt}`);
+            if (merge.inProgress) {
+                console.log(`  a ${merge.kind} is in progress, ${merge.unresolved.length} unresolved path(s)`);
+                for (const p of merge.unresolved.slice(0, 10))
+                    console.log(`    ${p}`);
+                if (!held || held.stale)
+                    console.log('  NOBODY HOLDS THE LOCK — this merge looks abandoned.');
+            }
+        }
+        return;
+    }
+    console.error(`Unknown merge-lock command: ${sub}\n\n${HELP}`);
+    process.exitCode = 1;
+}

package/dist/commands/parity-reminder.js

@@ -0,0 +1,53 @@
+"use strict";
+/** Parity pending — tell a harness what IT still has to port.
+ *
+ *  The Parity System already knows which copies are stale when a unit advances.
+ *  Until now that knowledge only surfaced two ways: an operator running
+ *  `greprag parity`, or a STALE directive fired at whoever happened to open the
+ *  file. Neither reaches the harness that actually owes the work, so drift sat
+ *  until someone went looking.
+ *
+ *  This module inverts the audience. The deficiency is "I am a stale follower on
+ *  N units", evaluated for the CURRENT harness only:
+ *    - the LEAD sees nothing — it is the copy that advanced, it owes nothing;
+ *    - a stale harness sees what it owes and the command that ports it;
+ *    - zero pending is silent, so the signal auto-stops the moment it is cleared.
+ *
+ *  Diverged units are deliberately excluded. Two-sided advancement needs
+ *  arbitration by the operator, never an unattended port that picks a winner by
+ *  recency.
+ *
+ *  adr: adr/parity-system.md */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parityPendingModule = void 0;
+exports.parityPendingDetect = parityPendingDetect;
+exports.buildParityPending = buildParityPending;
+function parityPendingDetect(env) {
+    const pending = env.parityPending || [];
+    if (!pending.length)
+        return { tier: 'silent' };
+    return { tier: 'nudge', detail: { count: pending.length } };
+}
+/** Announce-only. This is work to schedule, not an interrupt to obey mid-turn —
+ *  a porting job belongs at session start, next to the other orientation. */
+function buildParityPending(env) {
+    const pending = env.parityPending || [];
+    if (!pending.length)
+        return null;
+    const harness = env.platform || 'this harness';
+    const lines = pending.slice(0, 5).map((p) => `• ${p.unit} — ${p.summary} (led by ${p.leadHarness}; your copy: ${p.path})`);
+    const more = pending.length > lines.length
+        ? `\n• …and ${pending.length - lines.length} more — \`greprag parity\` for the full table.`
+        : '';
+    return `[greprag parity — ${pending.length} advancement(s) landed elsewhere that ${harness} `
+        + `has not taken yet:]\n${lines.join('\n')}${more}\n`
+        + `PORT THE RESULT, NEVER THE MECHANISM: read what the lead actually achieved `
+        + `(\`greprag memory search\` its unit name), then build the equivalent for this `
+        + `harness's own shape. A diff is the wrong artifact — the files differ.`;
+}
+exports.parityPendingModule = {
+    id: 'parity-pending',
+    detect: parityPendingDetect,
+    announce: buildParityPending,
+    reminder: () => null,
+};

package/dist/commands/persona-reminder.js

@@ -3,6 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.personaAnnounceModule = void 0;
 exports.personaAnnounceModule = {
     id: 'persona-announce',
+    // Stays registered for EVERY harness — and a `harnesses:` tag here would still
+    // be wrong, because `recompact` cannot tell which harness invoked it.
+    //
+    // The HOOK path (recap/recompact, Claude Code + Codex + Grok) drops this module
+    // at its own call site: Persona rides a dedicated `greprag-hook persona` hook
+    // there, with its own full ~2048-byte allowance, because a real persona is
+    // larger than the whole shared announce budget and was being deferred WHOLE.
+    //
+    // OpenCode is why the module stays registered: its plugin renders this straight
+    // into the system prompt on every model call, with no inline cap to fit.
+    // adr: adr/persona.md, adr/announce-inline-budget.md
     detect: () => ({ tier: 'silent' }),
     announce: (env) => env.personaAnnounce || null,
     reminder: () => null,