greprag 5.83.2 → 5.84.0

package/dist/commands/app-model.js

@@ -292,7 +292,7 @@ async function buildAppModel(cwd, requestedProjectId, homeDir = os.homedir()) {
                     group: 'Other',
                 }),
                 enabled: !disabled.has(module.id),
-                surface: module.source === 'command' ? 'Before sensitive actions' : 'Agent guidance',
+                surface: 'Agent guidance',
                 harnesses: module.harnesses || ['claude-code', 'codex', 'opencode', 'grok'],
             })),
         },

package/dist/commands/delivery-reminder.js

@@ -50,7 +50,7 @@ function buildDeliveryAnnounce(env) {
         `[DELIVERY — ${project}]`,
         'Commit useful, passing work. Only committed state delivers; ignore uncommitted and untracked work in every checkout.',
         coordinationLine(env.platform),
-        'Land every ready same-repo commit: update the default branch, rebase your worktree onto its tip, retest there, take greprag merge-lock in the canonical checkout, recheck the tip, merge --ff-only, release --landed. Tip moved? Free the lock and prepare again. Never rebase a shared default branch.',
+        'Land every ready same-repo commit: update the default branch, rebase your worktree onto its tip, retest there, take greprag merge-lock in the canonical checkout, recheck the tip, merge --ff-only, release --landed. Tip moved? Free the lock and prepare again. A chip\'s branch arrives rebased by the chip: only fast-forward it; refused, free the lock and send it back. Never rebase in another session\'s worktree or a shared default branch.',
         'Deploy through this repo\'s delivery profile, from its canonical primary checkout unless the profile says otherwise. Worktrees build; they do not deploy. Then verify production serves the commit you shipped.',
         'THE GOAL ALREADY AUTHORIZES ALL OF THIS. Do not stop to ask permission to commit, merge, or deploy. Separate approval is for effects outside code delivery: destructive data, secrets, money, customer-facing messages.',
         'Why each rule, and the details: `greprag load delivery`.',

package/dist/commands/discord.js

@@ -1,21 +1,21 @@
 "use strict";
-/** greprag discord <pair|unpair|me|handoff|unhandoff> — Discord bot CLI.
+/** greprag discord <pair|unpair|me|typing> — Discord bot CLI.
  *
  *  pair        POSTs /v1/discord/pair with the current project anchor; prints
  *              the 6-char code + DM-the-bot instructions.
  *  unpair      DELETEs /v1/discord/pair.
- *  me          GETs /v1/discord/me — pairing + handoff state.
- *  handoff     POSTs /v1/discord/handoff — pins DMs to (current project,
- *              current session) for a TTL window. Bot DMs a confirmation.
- *  unhandoff   DELETEs /v1/discord/handoff.
+ *  me          GETs /v1/discord/me — pairing state.
+ *  typing      POSTs /v1/discord/typing — refreshes the typing indicator.
+ *
+ *  Sessions DM the operator with `greprag send --to discord:<snowflake>`.
+ *  Nothing reads DMs sent to the bot: the Front Desk and the handoff pin were
+ *  retired 2026-10-06, so the bot answers each one with a fixed line.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DISCORD_HELP = void 0;
 exports.callDiscordPair = callDiscordPair;
 exports.callDiscordUnpair = callDiscordUnpair;
 exports.callDiscordMe = callDiscordMe;
-exports.callDiscordHandoff = callDiscordHandoff;
-exports.callDiscordUnhandoff = callDiscordUnhandoff;
 exports.callDiscordTyping = callDiscordTyping;
 async function callDiscordPair(deps, projectId) {
     const f = deps.fetchImpl ?? fetch;
@@ -45,30 +45,6 @@ async function callDiscordMe(deps) {
     });
     return (await res.json());
 }
-async function callDiscordHandoff(deps, args) {
-    const f = deps.fetchImpl ?? fetch;
-    const res = await f(`${deps.apiUrl}/v1/discord/handoff`, {
-        method: 'POST',
-        headers: {
-            'Authorization': `Bearer ${deps.apiKey}`,
-            'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({
-            project_id: args.projectId,
-            session_id: args.sessionId,
-            ttl_minutes: args.ttlMinutes,
-        }),
-    });
-    return (await res.json());
-}
-async function callDiscordUnhandoff(deps) {
-    const f = deps.fetchImpl ?? fetch;
-    const res = await f(`${deps.apiUrl}/v1/discord/handoff`, {
-        method: 'DELETE',
-        headers: { 'Authorization': `Bearer ${deps.apiKey}` },
-    });
-    return (await res.json());
-}
 async function callDiscordTyping(deps) {
     const f = deps.fetchImpl ?? fetch;
     const res = await f(`${deps.apiUrl}/v1/discord/typing`, {
@@ -78,44 +54,19 @@ async function callDiscordTyping(deps) {
     return (await res.json());
 }
 exports.DISCORD_HELP = `
-greprag discord — Discord DM bridge to your greprag inbox.
+greprag discord — let your sessions DM you on Discord.
 
-Pair once, then DM the bot to talk to the agents listening in your project.
-Handoff temporarily redirects DMs to a specific session (e.g. while you step
-away from the desk and want to keep the same thread alive on your phone).
+Pair once; then any session can message you (see Outbound below). The bot does
+not read DMs you send it: the Front Desk was retired 2026-10-06.
 
 Subcommands:
   greprag discord pair                  Generate a 15-min code; DM @greprag-bot
                                         /pair <code> to link this Discord account
                                         to the current project.
   greprag discord unpair                Remove the pairing.
-  greprag discord me                    Show current pairing + handoff state.
-  greprag discord handoff [--ttl N]     Pin DMs to (current project, current
-                                        session) for N minutes (default 60,
-                                        max 1440). Bot DMs you a confirmation,
-                                        then this command BLOCKS and streams
-                                        inbound DMs to stdout (one per line)
-                                        until killed. Run it under Claude's
-                                        Monitor tool: each line = one
-                                        notification right back into the
-                                        agent's turn. Sliding TTL: each
-                                        inbound DM extends the pin by >=30 min.
-    [--session <8-hex>]                 Override session id (default: CLAUDE_SESSION_ID).
-    [--project <name>]                  Override project (default: cwd anchor).
-    [--orchestrator]                    Tenant-wide watcher — sees inbox traffic
-                                        from any project under this tenant. The
-                                        DM pin still routes here, but the agent
-                                        has portfolio-wide eyes. Use when this
-                                        session is the user's orchestrator
-                                        (/business-advisor loaded, etc.).
-    [--json]                            Emit raw JSON per line (for Monitor).
-    [--no-watch]                        Pin and exit — skip the inline watcher.
-                                        For scripted use; loses the live DM stream.
-  greprag discord unhandoff             Clear the active handoff — DMs revert
-                                        to default project.
+  greprag discord me                    Show current pairing state.
   greprag discord typing                Refresh the "typing..." indicator on
-                                        Discord for ~10s. Auto-fires on every
-                                        inbound DM; call manually during long
+                                        Discord for ~10s. Call it during long
                                         agent turns so the user sees activity
                                         instead of silence.
 

package/dist/commands/inbox-watch.js

@@ -251,19 +251,6 @@ function printMessage(msg) {
 function emitDmReplyDirective(msg, session) {
     if (!session)
         return;
-    // Front Desk Switchboard relay: the operator reached THIS session through the
-    // receptionist and `references.reply_to` is the rail to answer on. Fires for
-    // ANY message_type (the relay uses plain 'message'), and takes precedence over
-    // the legacy Discord-DM path. Without this the session falls back to the bare
-    // sender handle (travis@greprag.com) — the reply lands in MAIN, never reaching
-    // the operator on Discord/SMS. Live failure 2026-06-08. spec:
-    // docs/front-desk-switchboard.md §4 (return leg).
-    const replyTo = msg.references?.reply_to;
-    if (replyTo) {
-        console.log(`[greprag] Operator via front desk — answer now, even mid-task: greprag send --to ${replyTo} "…" ` +
-            `(exact addr; bare handle is lost). If they reply inline here, don't echo to Discord/SMS.`);
-        return;
-    }
     if (msg.message_type !== 'discord_dm')
         return;
     const snowflake = msg.references?.discord?.snowflake ?? '<snowflake>';

package/dist/commands/load.js

@@ -453,9 +453,11 @@ async function printMirroredSkill(name, args) {
         const identityArg = args.skillId ? ` --skill-id ${args.skillId}` : '';
         console.error(`Mirrored skill "${name}" has no canonical body — the mirror is holding the generated adapter.\n` +
             `Refusing to serve it: the adapter is the launcher that sent you here, not the skill.\n\n` +
-            `Restore the real body from the pre-adoption snapshot:\n` +
+            `Restore the real body from an earlier revision or the pre-adoption snapshot:\n` +
+            `  greprag skill history ${name}${identityArg}\n` +
+            `  greprag skill revert ${name} --to <rev>${identityArg} --reason "<why>" --expected-hash <current-hash>\n` +
             `  greprag skill mirror snapshot list ${name}${identityArg}\n` +
-            `  greprag skill mirror snapshot promote ${name} --name <snapshot>${identityArg} --expected-hash <current-hash>\n`);
+            `  greprag skill mirror snapshot promote ${name} --name <snapshot>${identityArg} --expected-hash <current-hash> --reason "<why>"\n`);
         process.exitCode = 1;
         return true;
     }

package/dist/commands/reminder-registry.js

@@ -5,7 +5,7 @@
  *  PURE over ReminderEnv — the hook assembles env (i/o) and emits the returned lines;
  *  a broken module never blocks a turn (fail-open per module). */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ANNOUNCE_POINTER_RESERVE = exports.ANNOUNCE_HARNESS_CAP = exports.ANNOUNCE_INLINE_BUDGET = exports.compactReannounceModules = exports.commandModules = exports.promptModules = exports.harnessModules = exports.REGISTRY = void 0;
+exports.ANNOUNCE_POINTER_RESERVE = exports.ANNOUNCE_HARNESS_CAP = exports.ANNOUNCE_INLINE_BUDGET = exports.compactReannounceModules = exports.harnessModules = exports.REGISTRY = void 0;
 exports.collectReminders = collectReminders;
 exports.bootOrder = bootOrder;
 exports.collectAnnounces = collectAnnounces;
@@ -66,13 +66,6 @@ exports.REGISTRY = [
  *  update a parallel id list. (Root-cause repair, chip/opencode-fix-chip-system-parity.) */
 const harnessModules = (harness, registry = exports.REGISTRY) => registry.filter((m) => !m.harnesses || m.harnesses.includes(harness));
 exports.harnessModules = harnessModules;
-/** Split the registry by READ surface (docs/reminder-interrupt.md). UserPromptSubmit
- *  evaluates `prompt`-source modules (the default); PreToolUse evaluates `command`-source
- *  modules (they read env.toolCommand). Announces are always prompt-side (SessionStart). */
-const promptModules = (registry = exports.REGISTRY) => registry.filter((m) => (m.source ?? 'prompt') === 'prompt');
-exports.promptModules = promptModules;
-const commandModules = (registry = exports.REGISTRY) => registry.filter((m) => m.source === 'command');
-exports.commandModules = commandModules;
 /** PostCompact re-announce set (docs/reminder-interrupt.md). A compaction wipes the
  *  SessionStart announces from context, so the announce modules re-present afterward —
  *  by DEFAULT all of them; a module opts out with `reannounceOnCompact: false`. The

package/dist/commands/session.js

@@ -4,8 +4,8 @@
  *  retitle <session-8hex> "<title>" — force-set a session's registry title,
  *  overriding the gpt-5.4-nano auto-title. Used by the multi-chip /chip-leader
  *  convention: a chip stamps its own label-aligned title ("Chip A — …") in
- *  Block 1 so the FleetView watcher list / Discord /switch line up with the
- *  leader's chip labels. Thin HTTP client over POST /v1/memory/title. */
+ *  Block 1 so the FleetView watcher list lines up with the leader's chip
+ *  labels. Thin HTTP client over POST /v1/memory/title. */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);

package/dist/commands/skill-mirror-reminder.js

@@ -90,7 +90,6 @@ function buildSkillMirrorAnnounce(m, platform) {
 }
 exports.skillMirrorAnnounceModule = {
     id: 'skill-mirror-announce',
-    source: 'prompt',
     dependsOn: ['load-primer'], // references `greprag load` — the primer establishes it
     detect: (_env) => ({ tier: 'silent' }), // announce-only
     announce: (env) => buildSkillMirrorAnnounce(env.mirroredSkills, env.platform),

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/hook.js

@@ -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 {