greprag 5.83.1 → 5.84.0

package/dist/commands/skill.js

@@ -83,21 +83,30 @@ USAGE
   greprag skill list                  Show bundled skills and install status
   greprag skill install <name>        Install a bundled advisor skill
   greprag skill uninstall <name>      Remove a previously-installed advisor
-  greprag skill edit <name> [--skill-id <id>] [--scope project --project-id <id>]
+  greprag skill edit <name> --reason "<why>" [--skill-id <id>] [--scope project --project-id <id>]
                                       Export/edit/apply helper; opens $EDITOR unless --no-open or Codex
+  greprag skill history <name> [--skill-id <id>] [--limit <n>]
+                                      Every canon revision: date, author, reason, changes
+  greprag skill diff <name> <revA> [<revB>]
+                                      Unified diff between two revisions (revB defaults to current)
+  greprag skill revert <name> --to <rev> --reason "<why>" --expected-hash <current-hash>
+                                      Make an old revision current again as a new revision
   greprag skill mirror sync [harness] Install native GrepRAG skill adapters
     claude-code --cutover-lifecycle    Cut over commit/deploy/release only
     claude-code --only <a,b>           Install adapters for named mirrored skills
                                        (closes the gaps greprag load marks with *)
   greprag skill mirror export <name> --to <dir>
                                       Export canonical skill bytes for editing
-  greprag skill mirror apply <dir> --skill <name> --expected-hash <hash>
-                                      Promote edited bytes with stale-write guard
+  greprag skill mirror apply <dir> --skill <name> --expected-hash <hash> --reason "<why>" [--allow-remove]
+                                      Promote edited bytes with stale-write guard;
+                                      the folder must come from export (it records
+                                      the revision it holds), and a missing file
+                                      is refused unless --allow-remove
   greprag skill mirror snapshot create <name> --name <snapshot>
   greprag skill mirror snapshot list <name>
   greprag skill mirror snapshot show <name> --name <snapshot>
   greprag skill mirror snapshot restore <name> --name <snapshot> --to <dir>
-  greprag skill mirror snapshot promote <name> --name <snapshot> --expected-hash <hash>
+  greprag skill mirror snapshot promote <name> --name <snapshot> --expected-hash <hash> --reason "<why>"
                                       Promote snapshot bytes as the newest revision
                                       Named package rollback points
   greprag skill source stamp <name> --project <p> --path <rel> [--path <rel>...]
@@ -114,6 +123,9 @@ NOTES
   • Mirrored skill edits use export/apply semantics. \`skill edit\` only wraps
     that flow: export current bytes, open an editor, show a diff summary, then
     apply with the exported content hash.
+  • Every canon write needs --reason "<one line>". GrepRAG keeps each
+    revision's bytes with its reason, author and date; read them with
+    \`skill history\`, compare with \`skill diff\`, undo with \`skill revert\`.
   • Codex agents must use a non-interactive path: \`skill mirror export\`, patch
     files, then \`skill mirror apply\`. In Codex, \`skill edit\` skips the editor
     and prints the guarded apply command; \`--no-open\` does the same explicitly.
@@ -368,10 +380,50 @@ function writeSkillPackage(targetDir, files, opts) {
     for (const file of files) {
         const destination = safePackagePath(target, file.path);
         fs.mkdirSync(path.dirname(destination), { recursive: true });
-        fs.writeFileSync(destination, file.content.endsWith('\n') ? file.content : file.content + '\n', 'utf8');
+        fs.writeFileSync(destination, file.content, 'utf8');
     }
     return true;
 }
+/** The record an export leaves beside the files it wrote: which revision the
+ *  folder holds and the bytes of every file in it. Apply takes its base from
+ *  here, never from a hash the caller fetched separately, so an old folder
+ *  cannot be paired with a newer revision's hash and written over it.
+ *  adr: adr/skill-bundle-shape.md */
+const MIRROR_BASE_FILE = '.greprag-mirror-base.json';
+function fileDigest(content) {
+    return (0, skill_mirror_client_1.computeMirrorHash)([{ path: '', content }]);
+}
+function writeMirrorBase(targetDir, base) {
+    const record = {
+        skill: base.skill,
+        revision: base.revision,
+        contentHash: base.contentHash,
+        files: Object.fromEntries(base.files.map(file => [file.path, fileDigest(file.content)])),
+    };
+    fs.writeFileSync(path.join(path.resolve(targetDir), MIRROR_BASE_FILE), JSON.stringify(record, null, 2) + '\n', 'utf8');
+}
+function readMirrorBase(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(path.resolve(dir), MIRROR_BASE_FILE), 'utf8'));
+        if (typeof raw.skill !== 'string' || typeof raw.contentHash !== 'string' || !raw.files || typeof raw.files !== 'object')
+            return null;
+        return { skill: raw.skill, revision: Number(raw.revision || 0), contentHash: raw.contentHash, files: raw.files };
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the folder back and fail unless it holds exactly the files the mirror
+ *  sent, byte for byte. Catches a partial write and any file the package
+ *  reader would skip (size or count limits) before the user edits on top. */
+function verifyWrittenPackage(targetDir, files) {
+    const written = (0, skill_mirror_client_1.collectSkillFiles)(path.resolve(targetDir)) || [];
+    const diff = diffSkillPackages(files, written);
+    if (!diff.length)
+        return;
+    const detail = diff.map(item => `  ${item.status === 'removed' ? 'missing' : item.status} ${item.path}`).join('\n');
+    throw new Error(`export did not write the revision it fetched to ${path.resolve(targetDir)}:\n${detail}`);
+}
 function printSkillMirrorConflict(params) {
     const local = new Map(params.localFiles.map(file => [file.path, file.content]));
     const remote = new Map(params.remoteFiles.map(file => [file.path, file.content]));
@@ -394,14 +446,12 @@ async function runSkillMirrorExport(args) {
     const to = getArg(args, '--to');
     if (!name || !to)
         throw new Error('Usage: greprag skill mirror export <name> --to <dir> [--force] [--check]');
-    const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(name)}${mirrorLookupQuery(args)}`);
-    const files = (data.files || [])
-        .filter((file) => typeof file.path === 'string' && typeof file.content === 'string');
-    if (!files.length)
-        throw new Error(`No mirrored files returned for ${name}.`);
-    if (!writeSkillPackage(to, files, { force: args.includes('--force'), check: args.includes('--check'), exact: true }))
+    const loaded = await loadMirrorPackage(name, args);
+    if (!writeSkillPackage(to, loaded.files, { force: args.includes('--force'), check: args.includes('--check'), exact: true }))
         return;
-    console.log(`Exported ${name} revision ${Number(data.revision || 0)} (${String(data.contentHash || '')})`);
+    verifyWrittenPackage(to, loaded.files);
+    writeMirrorBase(to, { skill: name, ...loaded });
+    console.log(`Exported ${name} revision ${loaded.revision} (${loaded.contentHash})`);
 }
 async function loadMirrorPackage(skill, args) {
     const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}${mirrorLookupQuery(args)}`);
@@ -441,6 +491,16 @@ function refuseBundledSkillWrite(skill) {
         return;
     throw new Error(`${skill} ships with the greprag CLI, so its canon is the bundle, not the skill mirror. Edit packages/cli/skill/${skill}/ in the greprag repo.`);
 }
+/** Every canon write carries a one-line reason into the skill's revision
+ *  history; the server refuses a write without one, so refuse it here first,
+ *  naming the flag. adr: adr/skill-revision-history.md */
+function requireReason(args, usage) {
+    const reason = (getArg(args, '--reason') || '').trim();
+    if (!reason || reason.startsWith('--')) {
+        throw new Error(`Refusing: --reason "<one line>" is required. GrepRAG records it in the skill's revision history.\nUsage: ${usage}`);
+    }
+    return reason;
+}
 async function applySkillPackage(params) {
     refuseBundledSkillWrite(params.skill);
     const hash = (0, skill_mirror_client_1.computeMirrorHash)(params.files);
@@ -448,6 +508,8 @@ async function applySkillPackage(params) {
         files: params.files,
         contentHash: hash,
         ...mirrorBodyScope(params.args),
+        reason: params.reason,
+        author: (0, skill_mirror_client_1.skillRevisionAuthor)(params.via),
         expectedHash: params.expectedHash,
         ...(typeof params.expectedRevision === 'number' ? { expectedRevision: params.expectedRevision } : {}),
     };
@@ -477,11 +539,16 @@ async function assertCurrentMirrorHash(params) {
 }
 async function runSkillEdit(args) {
     const skill = args[0];
+    const usage = 'greprag skill edit <name> --reason "<why>" [--dir <dir>] [--no-open] [--force] [--keep]';
     if (!skill)
-        throw new Error('Usage: greprag skill edit <name> [--dir <dir>] [--no-open] [--force] [--keep]');
+        throw new Error(`Usage: ${usage}`);
     refuseBundledSkillWrite(skill);
     const explicitDir = getArg(args, '--dir') || getArg(args, '--to');
     const noOpen = args.includes('--no-open');
+    const skipEditor = noOpen || codexHarnessDetected();
+    // The editor path applies in this run, so it needs its reason before export;
+    // --no-open only prints the apply command, which carries the reason instead.
+    const reason = skipEditor ? (getArg(args, '--reason') || '').trim() : requireReason(args, usage);
     const keep = args.includes('--keep') || Boolean(explicitDir);
     const workDir = explicitDir
         ? path.resolve(explicitDir)
@@ -491,15 +558,16 @@ async function runSkillEdit(args) {
         force: args.includes('--force') || !explicitDir,
         exact: true,
     });
+    verifyWrittenPackage(workDir, loaded.files);
+    writeMirrorBase(workDir, { skill, ...loaded });
     console.log(`Editing ${skill} revision ${loaded.revision} (${loaded.contentHash})`);
     console.log(`Work dir: ${workDir}`);
-    const skipEditor = noOpen || codexHarnessDetected();
     if (skipEditor) {
         console.log(noOpen
             ? 'Editor skipped.'
             : 'Codex harness detected; editor skipped to avoid launching an interactive editor.');
         const forward = forwardedMirrorArgs(args);
-        console.log(`Apply after editing: greprag skill mirror apply ${shellArg(workDir)} --skill ${skill}${forward ? ` ${forward}` : ''} --expected-hash ${loaded.contentHash}`);
+        console.log(`Apply after editing: greprag skill mirror apply ${shellArg(workDir)} --skill ${skill}${forward ? ` ${forward}` : ''} --expected-hash ${loaded.contentHash} --reason ${reason ? shellArg(reason) : '"<why>"'}`);
         return;
     }
     runEditor(path.join(workDir, 'SKILL.md'));
@@ -512,7 +580,7 @@ async function runSkillEdit(args) {
         return;
     }
     await assertCurrentMirrorHash({ skill, expectedHash: loaded.contentHash, localFiles: edited, args });
-    const data = await applySkillPackage({ skill, files: edited, expectedHash: loaded.contentHash, args });
+    const data = await applySkillPackage({ skill, files: edited, expectedHash: loaded.contentHash, reason, via: 'skill-edit', args });
     console.log(`Applied ${skill}: revision ${Number(data.revision || 0)} (${String(data.contentHash || (0, skill_mirror_client_1.computeMirrorHash)(edited))})`);
     if (!keep)
         fs.rmSync(workDir, { recursive: true, force: true });
@@ -520,20 +588,38 @@ async function runSkillEdit(args) {
 async function runSkillMirrorApply(args) {
     const dir = args[0];
     const skill = getArg(args, '--skill') || (dir ? path.basename(path.resolve(dir)) : '');
+    const usage = 'greprag skill mirror apply <dir> --skill <name> --expected-hash <hash> --reason "<why>"';
     if (!dir || !skill)
-        throw new Error('Usage: greprag skill mirror apply <dir> --skill <name> --expected-hash <hash>');
+        throw new Error(`Usage: ${usage}`);
+    refuseBundledSkillWrite(skill);
+    const reason = requireReason(args, usage);
     const expectedRevisionRaw = getArg(args, '--expected-revision') || getArg(args, '--expectedRevision');
-    const expectedHash = getArg(args, '--expected-hash') || getArg(args, '--expectedHash');
-    if (!expectedHash) {
-        throw new Error('Refusing unguarded apply; export first, then pass the exported --expected-hash <hash>.');
+    const passedHash = getArg(args, '--expected-hash') || getArg(args, '--expectedHash');
+    const base = readMirrorBase(dir);
+    if (!base) {
+        throw new Error(`Refusing apply: ${path.resolve(dir)} has no export record (${MIRROR_BASE_FILE}). Run greprag skill mirror export ${skill} --to <dir>, edit that folder, then apply it.`);
     }
+    if (base.skill !== skill) {
+        throw new Error(`Refusing apply: ${path.resolve(dir)} was exported from ${base.skill}, not ${skill}.`);
+    }
+    if (passedHash && passedHash !== base.contentHash) {
+        throw new Error(`Refusing apply: this folder was exported at ${base.contentHash} (revision ${base.revision}), but --expected-hash is ${passedHash}. A hash from a different export does not describe these files; export again and redo the edits there.`);
+    }
+    const expectedHash = base.contentHash;
     const files = collectSkillPackageOrThrow(dir);
+    const present = new Set(files.map(file => file.path));
+    const missing = Object.keys(base.files).filter(relative => !present.has(relative));
+    if (missing.length && !args.includes('--allow-remove')) {
+        throw new Error(`Refusing apply: files from the export are missing in ${path.resolve(dir)}:\n${missing.map(relative => `  missing ${relative}`).join('\n')}\nRestore them, or pass --allow-remove if deleting them is intended.`);
+    }
     await assertCurrentMirrorHash({ skill, expectedHash, localFiles: files, args });
     const data = await applySkillPackage({
         skill,
         files,
         expectedHash,
         expectedRevision: expectedRevisionRaw ? Number(expectedRevisionRaw) : undefined,
+        reason,
+        via: 'mirror-apply',
         args,
     });
     console.log(`Applied ${skill}: revision ${Number(data.revision || 0)} (${String(data.contentHash || (0, skill_mirror_client_1.computeMirrorHash)(files))})`);
@@ -590,6 +676,8 @@ async function runSkillMirrorSnapshot(args) {
         console.log(`Snapshot ${String(snap.snapshotName || name)} stored for ${skill}: revision ${Number(snap.revision || 0)}`);
         return;
     }
+    const promoteUsage = 'greprag skill mirror snapshot promote <skill> --name <snapshot> --expected-hash <current-live-hash> --reason "<why>"';
+    const promoteReason = verb === 'promote' && !rest.includes('--check') ? requireReason(rest, promoteUsage) : '';
     const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}/snapshots/${encodeURIComponent(name)}${mirrorLookupQuery(rest)}`);
     const snapshot = data.snapshot;
     if (verb === 'show') {
@@ -610,13 +698,13 @@ async function runSkillMirrorSnapshot(args) {
         const files = snapshotPresentFiles(snapshot);
         if (!writeSkillPackage(to, files, { force: rest.includes('--force'), check: rest.includes('--check'), exact: true }))
             return;
-        console.log(`Restored snapshot ${name} for ${skill} to ${path.resolve(to)}. Run apply with the expected revision if this should become canon.`);
+        console.log(`Restored snapshot ${name} for ${skill} to ${path.resolve(to)}. To make it canon, run greprag skill mirror snapshot promote ${skill} --name ${name} --expected-hash <current-live-hash> --reason "<why>".`);
         return;
     }
     if (verb === 'promote') {
         const expectedHash = getArg(rest, '--expected-hash') || getArg(rest, '--expectedHash');
         if (!expectedHash) {
-            throw new Error('Usage: greprag skill mirror snapshot promote <skill> --name <snapshot> --expected-hash <current-live-hash>');
+            throw new Error(`Usage: ${promoteUsage}`);
         }
         const files = snapshotPresentFiles(snapshot);
         if (!files.some(file => file.path === 'SKILL.md')) {
@@ -629,12 +717,129 @@ async function runSkillMirrorSnapshot(args) {
             return;
         }
         await assertCurrentMirrorHash({ skill, expectedHash, localFiles: files, args: rest });
-        const data = await applySkillPackage({ skill, files, expectedHash, args: rest });
+        const data = await applySkillPackage({
+            skill, files, expectedHash, reason: `promote snapshot "${name}": ${promoteReason}`, via: 'snapshot-promote', args: rest,
+        });
         console.log(`Promoted snapshot ${name} for ${skill}: revision ${Number(data.revision || 0)} (${String(data.contentHash || (0, skill_mirror_client_1.computeMirrorHash)(files))})`);
         return;
     }
     throw new Error('Usage: greprag skill mirror snapshot create|list|show|restore|promote <skill> [--name <snapshot>]');
 }
+// ---------- Revision history: history / diff / revert ------------------------
+// adr: adr/skill-revision-history.md
+function revisionArg(raw, label) {
+    const value = Number(String(raw || '').replace(/^r/i, ''));
+    if (!raw || !Number.isInteger(value) || value < 0)
+        throw new Error(`${label} must be a revision number such as 12 or r12`);
+    return value;
+}
+function positionals(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith('--')) {
+            if (args[i + 1] && !args[i + 1].startsWith('--'))
+                i++;
+            continue;
+        }
+        out.push(args[i]);
+    }
+    return out;
+}
+function authorLabel(author) {
+    if (!author)
+        return '';
+    const parts = [
+        typeof author.harness === 'string' ? author.harness : '',
+        typeof author.sessionId === 'string' ? author.sessionId.slice(0, 8) : '',
+        typeof author.chip === 'string' ? author.chip : '',
+    ].filter(Boolean);
+    const via = typeof author.via === 'string' ? author.via : '';
+    return [via, parts.join(' ')].filter(Boolean).join(' · ');
+}
+async function runSkillHistory(args) {
+    const skill = args[0];
+    if (!skill)
+        throw new Error('Usage: greprag skill history <name> [--skill-id <id>] [--limit <n>]');
+    const limit = getArg(args, '--limit');
+    const qs = mirrorLookupQuery(args);
+    const sep = qs ? '&' : '?';
+    const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}/history${qs}${limit ? `${sep}limit=${encodeURIComponent(limit)}` : ''}`);
+    const revisions = data.revisions || [];
+    if (!revisions.length) {
+        console.log(`No recorded revisions for ${skill}.`);
+        return;
+    }
+    console.log(`${skill} (${String(data.skillId || '')}) — newest first`);
+    console.log(`current: r${String(revisions[0].revision)} ${String(revisions[0].contentHash || '')}`);
+    for (const r of revisions) {
+        const date = String(r.createdAt || '').replace('T', ' ').slice(0, 16);
+        console.log('');
+        console.log(`r${String(r.revision).padEnd(4)} ${date}  ${String(r.kind).padEnd(8)} ${authorLabel(r.author)}`);
+        console.log(`      ${String(r.reason || '')}`);
+        const labels = r.labels || [];
+        if (labels.length)
+            console.log(`      snapshots: ${labels.join(', ')}`);
+        if (typeof r.revertedFrom === 'number')
+            console.log(`      bytes of r${r.revertedFrom}`);
+        const changes = r.changes || [];
+        if (r.comparedTo === null || r.comparedTo === undefined) {
+            console.log(`      first recorded revision (${Number(r.fileCount || 0)} files)`);
+        }
+        else if (!changes.length) {
+            console.log(`      no file changes vs r${String(r.comparedTo)}`);
+        }
+        else {
+            const files = changes.map(c => `${String(c.status)} ${String(c.path)}`).join(', ');
+            console.log(`      +${Number(r.added || 0)} -${Number(r.removed || 0)} vs r${String(r.comparedTo)}: ${files}`);
+        }
+    }
+}
+async function runSkillDiff(args) {
+    const [skill, revA, revB] = positionals(args);
+    if (!skill || !revA)
+        throw new Error('Usage: greprag skill diff <name> <revA> [<revB>] [--skill-id <id>]');
+    const from = revisionArg(revA, 'revA');
+    const to = revB === undefined ? undefined : revisionArg(revB, 'revB');
+    const qs = mirrorLookupQuery(args);
+    const params = `${qs ? `${qs}&` : '?'}from=${from}${to === undefined ? '' : `&to=${to}`}`;
+    const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}/diff${params}`);
+    const files = data.files || [];
+    console.log(`${skill}: r${String(data.from)} → r${String(data.to)}`);
+    if (!files.length) {
+        console.log('No differences.');
+        return;
+    }
+    for (const file of files) {
+        console.log('');
+        console.log(String(file.patch || `${String(file.status)} ${String(file.path)}`));
+    }
+}
+async function runSkillRevert(args) {
+    const usage = 'greprag skill revert <name> --to <rev> --reason "<why>" --expected-hash <current-hash> [--skill-id <id>]';
+    const skill = args[0];
+    if (!skill || skill.startsWith('--'))
+        throw new Error(`Usage: ${usage}`);
+    refuseBundledSkillWrite(skill);
+    const to = revisionArg(getArg(args, '--to'), '--to');
+    const reason = requireReason(args, usage);
+    const expectedHash = getArg(args, '--expected-hash') || getArg(args, '--expectedHash');
+    if (!expectedHash) {
+        throw new Error(`Refusing: --expected-hash <current-hash> is required (the hash \`greprag skill history ${skill}\` or the adapter shows for the current revision).\nUsage: ${usage}`);
+    }
+    const skillId = getArg(args, '--skill-id') || getArg(args, '--skillId');
+    const scope = getArg(args, '--scope');
+    const projectId = getArg(args, '--project-id') || getArg(args, '--projectId');
+    const data = await mirrorApiJson('POST', `/v1/skillmirror/${encodeURIComponent(skill)}/revert`, {
+        to,
+        reason,
+        expectedHash,
+        author: (0, skill_mirror_client_1.skillRevisionAuthor)('revert'),
+        ...(skillId ? { skillId } : {}),
+        ...(scope ? { scope } : {}),
+        ...(projectId ? { projectId } : {}),
+    });
+    console.log(`Reverted ${skill} to the bytes of r${to}: new revision ${Number(data.revision || 0)} (${String(data.contentHash || '')})`);
+}
 async function runSkill(args) {
     const sub = args[0];
     if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
@@ -646,6 +851,15 @@ async function runSkill(args) {
         case 'edit':
             await runSkillEdit(args.slice(1));
             return;
+        case 'history':
+            await runSkillHistory(args.slice(1));
+            return;
+        case 'diff':
+            await runSkillDiff(args.slice(1));
+            return;
+        case 'revert':
+            await runSkillRevert(args.slice(1));
+            return;
         case 'mirror': {
             const mirrorVerb = args[1] || 'sync';
             if (mirrorVerb === 'export') {
@@ -780,7 +994,10 @@ async function runSkill(args) {
             const apiKey = process.env.GREPRAG_API_KEY || '';
             if (apiKey) {
                 const apiUrl = process.env.GREPRAG_API_URL || 'https://api.greprag.com';
-                const outcome = await (0, skill_mirror_client_1.maybeMirrorSkill)({ skill: name, cwd: process.cwd(), apiUrl, apiKey });
+                const outcome = await (0, skill_mirror_client_1.maybeMirrorSkill)({
+                    skill: name, cwd: process.cwd(), apiUrl, apiKey,
+                    reason: `source stamp ${project} @ ${stamped.binding.baselineCommit.slice(0, 8)}`,
+                });
                 console.log(`Mirror: ${outcome}`);
             }
             else {

package/dist/deploy-locks.js

@@ -59,6 +59,9 @@ exports.releaseLock = releaseLock;
 exports.landedClaimsPath = landedClaimsPath;
 exports.isAncestorOfHead = isAncestorOfHead;
 exports.commitExists = commitExists;
+exports.integrationRef = integrationRef;
+exports.refTip = refTip;
+exports.landedVerdict = landedVerdict;
 exports.readLandedClaims = readLandedClaims;
 exports.openClaims = openClaims;
 exports.recordLandedClaim = recordLandedClaim;
@@ -66,6 +69,7 @@ exports.dropLandedClaim = dropLandedClaim;
 exports.readMergeState = readMergeState;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const delivery_config_1 = require("./delivery-config");
 const proc_1 = require("./proc");
 const session_id_1 = require("./session-id");
 /** The basename already on disk in the repos that have a deploy lock today. The
@@ -210,6 +214,7 @@ function readMergeLock(cwd) {
 function acquireLock(file, label, staleMs = exports.DEPLOY_STALE_MS, options = {}) {
     const session = lockSession();
     const record = {
+        ...(options.base ? { base: options.base } : {}),
         // A process-held lock must record the process that is actually DEPLOYING, which for
         // a script that shells out to this CLI is the caller, not this short-lived command.
         // Recording our own pid there would make the lock read as stale the moment it exists.
@@ -267,6 +272,49 @@ function commitExists(cwd, sha) {
     });
     return result.status === 0;
 }
+/** The branch merges land on: the profile's default branch, else this checkout's HEAD.
+ *  A ref, not HEAD, because the lock is shared across worktrees and a linked worktree's
+ *  HEAD is the very branch being merged. */
+function integrationRef(cwd) {
+    const branch = (0, delivery_config_1.resolveDeliveryProfile)(cwd).profile?.git?.defaultBranch;
+    if (branch) {
+        const ref = `refs/heads/${branch}`;
+        const probe = (0, proc_1.safeSpawnSync)('git', ['rev-parse', '--verify', '--quiet', ref], {
+            encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (probe.status === 0)
+            return ref;
+    }
+    return 'HEAD';
+}
+function refTip(cwd, ref) {
+    const result = (0, proc_1.safeSpawnSync)('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0 ? String(result.stdout).trim() || null : null;
+}
+/**
+ * Is `sha` a merge that landed under this lock?
+ *
+ * Release used to take any commit on trust, and the commit agents passed was
+ * `$(git rev-parse HEAD)`, which is on HEAD by definition. On 2026-10-06 in C:/sift a
+ * fast-forward was refused, a pipe to `tail` hid the refusal, and release recorded the
+ * peer commit already at the tip as this session's landed work; the deploy then shipped
+ * master without the branch. The claim must be checked against what the merge changed:
+ * it has to be on the integration branch now, and it cannot be the tip that was there
+ * before the lock was taken.
+ */
+function landedVerdict(cwd, sha, base) {
+    const ref = integrationRef(cwd);
+    const ancestor = (0, proc_1.safeSpawnSync)('git', ['merge-base', '--is-ancestor', sha, ref], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (ancestor.status !== 0)
+        return 'not-landed';
+    if (base && sha === base)
+        return 'nothing-new';
+    return 'landed';
+}
 function readLandedClaims(cwd) {
     try {
         const raw = JSON.parse(fs.readFileSync(landedClaimsPath(cwd), 'utf8'));

package/dist/hook.js

@@ -115,9 +115,9 @@ const merge_guard_1 = require("./commands/merge-guard");
 // injects the pointer so the post-compact model can Read the verbatim record.
 // All real logic lives in ./commands/archive. adr: adr/governed-compact.md
 const archive_1 = require("./commands/archive");
-// Collision schematic (SessionStart) — detect another live session in the same
-// repo (cloud watcher registry) and inject a coordinate-now directive. All real
-// logic lives in ./commands/collision-check. docs/schematic-triggers.md
+// Collision schematic (SessionStart) — detect another greprag watcher session
+// (OpenCode, Grok) in the same repo and inject a coordinate-now directive. All
+// real logic lives in ./commands/collision-check. docs/collision-schematic.md
 const collision_check_1 = require("./commands/collision-check");
 // (The asyncRewake idle-wake poll was REVERTED 2026-06-23 — falsified: a detached
 // process's exit-2 has no harness event to attach to in true deep idle, so it never
@@ -1165,6 +1165,7 @@ async function store(input, source = 'claude-code') {
         if (mirrorSkill) {
             await (0, skill_mirror_client_1.maybeMirrorSkill)({
                 skill: mirrorSkill, cwd, apiUrl: cfg.apiUrl, apiKey: cfg.apiKey,
+                sessionId: input.session_id,
             });
         }
     }
@@ -1525,7 +1526,7 @@ async function recap(input, mode = 'plain', opts = {}) {
         return;
     // Ensure the machine's desk-line is up (idempotent singleton). One per machine,
     // not per session — it long-polls the cloud and answers "what's truly live?"
-    // from local pidfile truth, so the Front Desk never reads a stale registry.
+    // from local pidfile truth, so the live-session list never comes from a stale registry.
     // The lock makes this a no-op on every SessionStart after the first.
     // adr: adr/desk-line-relay.md
     try {
@@ -2114,13 +2115,13 @@ async function armCheck(input) {
     }) + '\n');
 }
 /** Collision schematic (SessionStart) — `greprag-hook collision-check`. Detects
- *  another live session working in THIS repo via the cloud watcher registry and
- *  injects a directive telling the agent to message the peer + work in a
- *  worktree. The hook NEVER sends — AI never auto-acts. Dedup is per-session so a
- *  resume/compact re-fire pings each peer at most once. All detection/dedup/
- *  directive logic lives in ./commands/collision-check (pure + tested). Reads
- *  only the watcher registry (no inbox content) — no eavesdrop surface.
- *  Fail-quiet: any miss → silent. docs/schematic-triggers.md */
+ *  another greprag watcher session (OpenCode, Grok) working in THIS repo via the
+ *  cloud watcher registry and injects a directive telling the agent to message
+ *  the peer + work in a worktree. The hook NEVER sends — AI never auto-acts.
+ *  Dedup is per-session so a resume/compact re-fire pings each peer at most
+ *  once. All detection/dedup/directive logic lives in ./commands/collision-check
+ *  (pure + tested). Reads only the watcher registry (no inbox content) — no
+ *  eavesdrop surface. Fail-quiet: any miss → silent. docs/collision-schematic.md */
 async function collisionCheck(input) {
     const cwd = input.cwd || process.cwd();
     const cfg = (0, hook_runtime_1.getHookConfig)(cwd);
@@ -2353,11 +2354,8 @@ async function main() {
     }
     const harness = (0, harness_1.inferCurrentHarness)();
     if (subcommand === 'recap') {
-        // ALWAYS additionalContext. Raw stdout is treated by the Claude Code harness
-        // like command output: past ~2KB it spills to a file and injects a preview,
-        // which silently ate ~89% of an 18.7KB announce (Persona sits at byte 10,841).
-        // additionalContext is the documented injection channel. Grok keeps its
-        // sidecar via the platform arg. adr: adr/announce-delivery-channel.md
+        // ALWAYS additionalContext, the documented injection channel. Grok keeps its
+        // sidecar via the platform arg. adr: adr/announce-inline-budget.md
         await recap(input, 'additionalContext', {
             platform: harness === 'grok' ? 'grok' : undefined,
         });