greprag 5.79.0 → 5.82.0

package/dist/commands/deploy-verify.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeployVerify = runDeployVerify;
+const deploy_verify_1 = require("../deploy-verify");
+const HELP = `greprag deploy-verify — did production actually take the upload?
+
+Usage:
+  greprag deploy-verify --origin <url>  --sha <commit> [--attempts <n>] [--json]
+  greprag deploy-verify --heroku <app>  --sha <commit> [--attempts <n>] [--json]
+
+Reads <origin>/__build.json until it returns the commit you just shipped, retrying
+while the rollout settles. This is the ONLY correct answer to "is my change live?" —
+never grep a shipped bundle, which is wrong in both directions: code is split across
+content-hashed chunks so it is often absent from the file you searched, and comment
+text is stripped by the minifier and reads as missing when it shipped fine.
+
+Also checks that the stamp is served uncacheable. A cacheable stamp lets an edge
+answer your liveness check with the PREVIOUS deploy's commit, which is exactly what
+happened on 2026-09-04 — so a cacheable stamp fails, even when today's answer is right.
+
+Exit 0 when production is proven to serve the commit, 1 otherwise.
+
+For a target with no HTTP stamp — a Discord bot, a worker process — use --heroku:
+it reads the app's release list and confirms the running release names your commit.
+It refuses while the current release is pending or failed, which is the case most
+worth catching, because the git push succeeded and looks fine. A config-var change
+creates a release naming no commit, and the code running is still the last real
+deploy, so the check walks back to the most recent release that names one.
+
+Options:
+  --origin <url>   Production origin, e.g. https://api.example.com
+  --heroku <app>   Heroku app name, e.g. paybotdiscord
+  --sha <commit>   The commit that was just uploaded
+  --attempts <n>   Checks before giving up (default 8, ~5s apart)
+  --skip-cache-check   Only when the target genuinely cannot set response headers
+  --json           Machine-readable result`;
+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;
+}
+async function runDeployVerify(args) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+        console.log(HELP);
+        return;
+    }
+    const origin = (flagValue(args, '--origin') || '').replace(/\/+$/, '');
+    const herokuApp = flagValue(args, '--heroku') || '';
+    const sha = flagValue(args, '--sha') || '';
+    const json = args.includes('--json');
+    const attemptsRaw = Number.parseInt(flagValue(args, '--attempts') || '', 10);
+    const attemptOpt = Number.isFinite(attemptsRaw) && attemptsRaw > 0 ? { attempts: attemptsRaw } : {};
+    if ((!origin && !herokuApp) || !sha) {
+        console.error('deploy-verify: --sha plus one of --origin or --heroku is required.\n\n' + HELP);
+        process.exitCode = 1;
+        return;
+    }
+    // Heroku has no build stamp to cache, so the cache discipline below does not apply.
+    if (herokuApp) {
+        const result = await (0, deploy_verify_1.verifyHerokuRelease)({ app: herokuApp, sha, ...attemptOpt });
+        if (json) {
+            console.log(JSON.stringify({ ok: result.ok, attempts: result.attempts, reason: result.reason ?? null }));
+        }
+        else if (result.ok) {
+            console.log(`deploy-verify: ${herokuApp} is running ${sha.slice(0, 10)} (confirmed in ${result.attempts} check(s))`);
+        }
+        else {
+            console.error(`deploy-verify: the push finished but ${herokuApp} is not running it: ${result.reason}.`
+                + ` Checked ${result.attempts} time(s). Inspect with: heroku releases --app ${herokuApp}`);
+        }
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    // Liveness FIRST, then cacheability on the very response that proved it. Checking
+    // the header up front raced the rollout: on 2026-09-05 a healthy greprag deploy was
+    // refused because the pre-flight request reached the OLD version, which had no
+    // stamp route at all, and a 404 carries no Cache-Control. Only the liveness check
+    // retries, so only it can tell "not live yet" from "wrong". Sift and the site have
+    // always run these in this order; their contract tests assert it.
+    const result = await (0, deploy_verify_1.verifyDeployedBuildStamp)({ origin, sha, ...attemptOpt });
+    if (result.ok && !args.includes('--skip-cache-check')) {
+        const cacheable = (0, deploy_verify_1.describeStampCacheability)(result.cacheControl ?? null);
+        if (cacheable) {
+            const reason = `${cacheable}. The liveness check cannot be trusted while an edge can answer it from cache:`
+                + ' serve /__build.json with `Cache-Control: no-store`, then deploy again.';
+            if (json)
+                console.log(JSON.stringify({ ok: false, stage: 'cacheable', reason }));
+            else
+                console.error(`deploy-verify: ${reason}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (json) {
+        console.log(JSON.stringify({ ok: result.ok, attempts: result.attempts, reason: result.reason ?? null }));
+    }
+    else if (result.ok) {
+        console.log(`deploy-verify: production serves ${sha.slice(0, 10)} (confirmed in ${result.attempts} check(s))`);
+    }
+    else {
+        console.error(`deploy-verify: upload finished but production is not serving it: ${result.reason}.`
+            + ` Checked ${result.attempts} time(s).`
+            + ' The upload happened; what is live is not this commit. Re-run the deploy, and if it repeats,'
+            + " check the provider's deployment list before assuming the code is wrong.");
+    }
+    if (!result.ok)
+        process.exitCode = 1;
+}

package/dist/commands/inbox-primer-reminder.js

@@ -31,7 +31,7 @@ function buildInboxPrimer(env) {
     const codex = env.platform === 'codex';
     const opencode = env.platform === 'opencode';
     const grok = env.platform === 'grok';
-    const arm = (0, session_id_1.armMonitorCommand)(env.short, env.ownerPid, env.assistant, env.mechanic, env.platform);
+    const arm = (0, session_id_1.armMonitorCommand)(env.short, env.ownerPid, env.mechanic, env.platform);
     return [
         // LEAD — the forcing function (restored 2026-06-22). ARM is an ALARM, not reference:
         // you are unreachable until you do it, and it must be re-done every time the watcher
@@ -46,14 +46,14 @@ function buildInboxPrimer(env) {
                 ? '[CODEX INBOX — greprag is your agent-to-agent mesh. Codex-to-Codex: discover tasks and their repo/workspace with `codex_app.list_threads`, then coordinate with `codex_app.send_message_to_thread`. Reaching ANY non-Codex peer (Claude Code / opencode / Grok / another tenant\'s agent): `greprag send` IS the live primary path — native Codex messaging cannot reach them.]'
                 : opencode
                     ? '[OPENCODE INBOX — greprag is your agent-to-agent mesh. Inbound delivery is AUTOMATIC here: the greprag plugin arms a relay for this session (nothing to arm or re-arm) and inbound peer messages arrive as injected turns.]'
-                    : '[⚠ ARM YOUR INBOX WATCHER NOW — you are UNREACHABLE until you do. Peers are live in your mesh trying to coordinate with this session, and the operator can DM you — but they reach you ONLY while armed. Unarmed, you are invisible and their messages silently pile up. The watcher can DROP ANYTIME (crash / reload / OOM) — EVERY turn you are flagged unarmed you MUST re-arm, or coordination breaks.]',
+                    : '[CLAUDE CODE INBOX — greprag is how the world OUTSIDE this harness reaches you: Codex / opencode / Grok peers, the operator by DM, inbound email. Inbound delivery is AUTOMATIC and TURN-BASED: unread mail is injected at the top of your turn, plus a drain at session start. There is NOTHING to arm — the Monitor inbox watcher is RETIRED here (2026-09-04). Reply to those on the same greprag rail they arrived on. Another CLAUDE CODE session is NEVER reached through greprag — use your own harness\'s session list + send tools, which know each peer\'s working directory. Every 8-hex id greprag shows you is a GREPRAG address: those tools do not accept it, and passing one to them is the usual way a peer notice fails to address. Idle mail waits for the next turn instead of waking you.]',
         grok
             ? `ARM (idle wake): Grok \`monitor\` tool, persistent:true, description:"greprag inbox ${env.short}", command: \`${arm}\`. \`--quiet\` is REQUIRED — Grok treats stderr as wake events; the Claude bash wrapper is PowerShell-invalid. Use full UUID / 16-hex, never 8-hex. A chip → \`greprag load grok-chip-spawn\` then \`greprag grok spawn\` (child arms its own watch; parent keeps ONE). A helper → spawn_subagent. Floor: Stop-hook drain injects unread mail even if you never arm. Then \`greprag inbox\`.`
             : codex
                 ? 'CODEX: Native Codex tools are the source of truth: `codex_app.list_threads` discovers tasks plus their repo/workspace, and `codex_app.send_message_to_thread` handles Codex-to-Codex coordination. GrepRAG inbox rows for Codex surface through turn hooks only: SessionStart `drain` and UserPromptSubmit `codex-notify`. There is no Codex startup watcher to install. If hooks do not fire, open Codex Desktop Settings -> Settings -> Hooks, trust the GrepRAG commands, start a fresh Codex session, then drain what is waiting: `greprag inbox`.'
                 : opencode
                     ? 'DELIVERY: the relay arms itself on this session\'s first turn and injects inbound messages as they land — treat an injected `Message from <handle> (session <8hex>):` turn as async peer mail, not the operator typing. Drain anything already waiting: `greprag inbox`.'
-                    : `ARM: Monitor is a deferred tool — \`ToolSearch select:Monitor\`, then call Monitor with persistent:true, timeout_ms:3600000, description:"greprag inbox ${env.short}", command: \`${arm}\`. The \`--session ${env.short}\` is REQUIRED — a bare \`greprag inbox watch\` writes no pidfile, so the arm-check reads you unarmed forever. NEVER run it bare also because it is a foreground stream and hangs the turn. Then drain what is waiting: \`greprag inbox\`.`,
+                    : `DELIVERY: nothing to install or re-arm. Treat an injected \`[GrepRAG inbox: N unread message(s) delivered to session ${env.short}]\` block as async peer/operator mail, not the operator typing. Reaching another Claude Code session is your harness's own job, not greprag's. Drain anything already waiting: \`greprag inbox\`.`,
         '',
         // The facts + directives — a flat list (no MODEL/RULES scaffolding; the labels were
         // human doc-structure, dead weight to an agent). Everything that helps the agent DECIDE
@@ -62,11 +62,11 @@ function buildInboxPrimer(env) {
         '• One shared tenant inbox. `greprag inbox` auto-scopes to YOUR session (lines to/from you only); other sessions\' private threads stay hidden. `--all` (tenant-wide audit — every other session\'s threads) is OPT-IN: run it ONLY when the operator asks, never on your own initiative — it is for surveying child sessions you orchestrate.',
         codex
             ? `• GrepRAG send: \`greprag send "md" --to <handle>@greprag.com/<their-8hex|uuid> --from-session ${env.short}\` → durable cross-harness/fallback row. Bare \`--to <handle>@greprag.com\` → cold open: lands in their inbox for a manual check — silent, no session wake, no operator ping. There are no project / broadcast targets. For Codex-to-Codex, use \`codex_app.send_message_to_thread\`.`
-            : `• Send: \`greprag send "md" --to <handle>@greprag.com/<their-8hex|uuid> --from-session ${env.short}\` → live, session-targeted. Bare \`--to <handle>@greprag.com\` → cold open: lands in their inbox for a manual check — silent, no session wake, no operator ping. There are no project / broadcast targets.`,
+            : `• Send OUTSIDE this harness (Codex / opencode / Grok peers, the operator, a reply to inbound mail): \`greprag send "md" --to <handle>@greprag.com/<their-8hex|uuid> --from-session ${env.short}\` → live, session-targeted. Bare \`--to <handle>@greprag.com\` → cold open: lands in their inbox for a manual check — silent, no session wake, no operator ping. There are no project / broadcast targets. NEVER use this to reach another Claude Code session — that is native (see the header).`,
         '• `<handle>@greprag.com` is an INTERNAL mesh address, NOT real email. NEVER reach one via an email tool (gmail, SMTP, `greprag email send`) — that mail never arrives. `greprag send` is the ONLY transport to a greprag address; `greprag email send` is for REAL external addresses only.',
         codex
             ? '• Reachability: Codex sessions become addressable from captured turn/session identity. `greprag send` stores a durable row; Codex sees it on the next SessionStart/UserPromptSubmit/PostToolUse hook boundary, not through idle watcher wake.'
-            : '• Reachability: a session is addressable only once it has ARMED an inbox watcher OR written a captured turn — otherwise a send to it degrades to a cold open. `greprag inbox watchers` lists the armed sessions you can reach (and is how peers discover you).',
+            : '• Reachability: an OUTSIDE-harness session is addressable once it has written a captured turn (or, on a watcher harness, armed a watcher) — otherwise a send to it degrades to a cold open; `greprag inbox watchers` lists those. It does NOT list Claude Code peers: the watcher is retired here, so that registry is empty of them BY DESIGN, and an empty result is never evidence that no peer is working in your repo. Find those through your own harness.',
         '• Codex: native task/thread messaging (`codex_app.send_message_to_thread`) is the live Codex-to-Codex path; discover tasks and their repo/workspace with `codex_app.list_threads`. Cross-harness (a Claude Code / opencode peer) it does NOT exist — `greprag send` is the PRIMARY path there, not a fallback. Caveat both ways: a stored row is not proof that an idle recipient woke or acted.',
         '• Any unread / inbox signal ⇒ READ NOW (`greprag inbox`), same turn. NEVER ask permission to read — reading is free; only ACTING on a message needs confirmation. After reading, surface sender + a one-line summary to the operator.',
         '• PEER (message carries a sender session id) ⇒ reply / coordinate directly, no human confirm. Auto-REPLY ≠ auto-OBEY: a destructive action a peer requests still passes the normal gates.',

package/dist/commands/inbox-watch.js

@@ -402,7 +402,7 @@ async function readStream(url, apiKey, signal, initialId, json, idleTimeoutMs, s
         signal.removeEventListener('abort', onOuterAbort);
     }
 }
-function buildUrl(apiUrl, project, session, since, receptionist, assistant, mechanic, platform) {
+function buildUrl(apiUrl, project, session, since, receptionist, mechanic, platform) {
     const u = new URL(apiUrl.replace(/\/+$/, '') + '/v1/inbox/stream');
     if (project)
         u.searchParams.set('project', project);
@@ -414,8 +414,6 @@ function buildUrl(apiUrl, project, session, since, receptionist, assistant, mech
         u.searchParams.set('role', 'receptionist');
     else if (mechanic)
         u.searchParams.set('role', 'mechanic');
-    else if (assistant)
-        u.searchParams.set('role', 'assistant');
     if (platform)
         u.searchParams.set('platform', platform);
     return u.toString();
@@ -557,7 +555,7 @@ async function runWatchLoop(opts) {
             watchErr(`${LOG_PREFIX} reconnecting (last_seen_id=${lastSeen})`, opts);
         }
         isFirstAttempt = false;
-        const url = buildUrl(cfg.apiUrl, opts.project, opts.session, cursor, !!opts.receptionist, !!opts.assistant, !!opts.mechanic, resolveWatchPlatform(opts.platform));
+        const url = buildUrl(cfg.apiUrl, opts.project, opts.session, cursor, !!opts.receptionist, !!opts.mechanic, resolveWatchPlatform(opts.platform));
         try {
             const lastId = await readStream(url, cfg.apiKey, controller.signal, cursor, !!opts.json, idleTimeoutMs, opts.session);
             if (lastId)

package/dist/commands/init.js

@@ -1191,6 +1191,25 @@ function applyCodexHooks(config) {
     else {
         changes.push('Codex SessionStart recap hook already configured (skipped)');
     }
+    // SessionStart (persona) — Codex gets the same dedicated hook Claude Code has.
+    // Persona was riding `codex-recap`'s shared ANNOUNCE_INLINE_BUDGET, where the
+    // operator's 1,886-byte persona is larger than the whole budget and was deferred
+    // whole — named in the overflow pointer, never delivered. Its own invocation gets
+    // its own harness allowance. Matches the recap matcher so it fires wherever the
+    // announce does. adr: adr/persona.md, adr/announce-inline-budget.md
+    const personaSessionHook = {
+        matcher: recapMatcher,
+        hooks: [commandHook('persona', 5, 'Loading GrepRAG persona')],
+    };
+    if (!hasGrepragHookWithMatcher(config.hooks.SessionStart, 'persona', personaSessionHook.matcher)) {
+        if (!config.hooks.SessionStart)
+            config.hooks.SessionStart = [];
+        config.hooks.SessionStart.push(personaSessionHook);
+        changes.push('Added Codex SessionStart hook (persona)');
+    }
+    else {
+        changes.push('Codex SessionStart persona hook already configured (skipped)');
+    }
     const sessionHook = {
         matcher: 'startup|resume|clear|compact',
         hooks: [commandHook('session-id', 3, 'Loading GrepRAG session id')],
@@ -1361,6 +1380,23 @@ function applyCodexHooks(config) {
     else {
         changes.push('Codex PostCompact Interrupt re-announce hook already configured (skipped)');
     }
+    // PostCompact (persona) — the other half of the Codex fix. `recompact` no longer
+    // carries Persona on any harness (it never fit the shared budget), so the compact
+    // boundary needs the dedicated hook here too or a compacted Codex session drops
+    // its speaking rules. adr: adr/persona.md
+    const postCompactPersonaHook = {
+        matcher: 'manual|auto',
+        hooks: [commandHook('persona', 5, 'Restoring GrepRAG persona')],
+    };
+    if (!hasGrepragHookWithMatcher(config.hooks.PostCompact, 'persona', postCompactPersonaHook.matcher)) {
+        if (!config.hooks.PostCompact)
+            config.hooks.PostCompact = [];
+        config.hooks.PostCompact.push(postCompactPersonaHook);
+        changes.push('Added Codex PostCompact hook (persona)');
+    }
+    else {
+        changes.push('Codex PostCompact persona hook already configured (skipped)');
+    }
     const postCompactSessionHook = {
         matcher: 'manual|auto',
         hooks: [commandHook('session-id', 3, 'Restoring GrepRAG session id')],
@@ -1383,6 +1419,7 @@ function normalizeCodexHookCommands(hooks) {
         recap: { timeout: 10, statusMessage: 'Loading GrepRAG memory' },
         'codex-recap': { timeout: 10, statusMessage: 'Loading GrepRAG memory' },
         recompact: { timeout: 10, statusMessage: 'Re-announcing GrepRAG primers' },
+        persona: { timeout: 5, statusMessage: 'Loading GrepRAG persona' },
         'session-id': { timeout: 3, statusMessage: 'Loading GrepRAG session id' },
         drain: { timeout: 5, statusMessage: 'Draining GrepRAG inbox' },
         'codex-notify': { timeout: 300, statusMessage: 'Checking GrepRAG inbox', runner: 'greprag-codex-hook' },
@@ -1409,6 +1446,9 @@ function normalizeCodexHookCommands(hooks) {
                 if (match[1] === 'session-id' && eventName === 'PostCompact') {
                     spec.statusMessage = 'Restoring GrepRAG session id';
                 }
+                if (match[1] === 'persona' && eventName === 'PostCompact') {
+                    spec.statusMessage = 'Restoring GrepRAG persona';
+                }
                 const subcommand = match[1] === 'recap' ? 'codex-recap' : match[1];
                 const runner = spec.runner || 'greprag-hook';
                 const next = `${runner} ${subcommand}`;
@@ -1459,13 +1499,26 @@ function applySettings(settings, apiKey) {
         matcher: '',
         hooks: [{ type: 'command', command: 'greprag-hook store', timeout: 10000 }],
     };
+    // Migrate stale installs onto the every-source matcher. `hasGrepragHook` only
+    // asks whether a recap hook EXISTS, so an install written by an older version
+    // kept its narrow matcher forever while init reported "already configured".
+    // Field state 2026-09-03: `matcher: 'startup'`, so a resumed session — and
+    // every /new and dashboard-dispatched agent — got no announce at all, Persona
+    // included. Same failure and same fix as the Grok path above.
+    // adr: adr/announce-inline-budget.md
+    const retargetedRecap = settings.hooks.SessionStart
+        ? retargetGrepragHookMatcher(settings.hooks.SessionStart, 'recap', ['startup', 'startup|resume', 'startup|resume|compact', 'startup|clear|compact'], recapHook.matcher)
+        : 0;
+    if (retargetedRecap > 0) {
+        changes.push(`Retargeted SessionStart recap matcher to every source (${retargetedRecap})`);
+    }
     if (!hasGrepragHook(settings.hooks.SessionStart, 'recap')) {
         if (!settings.hooks.SessionStart)
             settings.hooks.SessionStart = [];
         settings.hooks.SessionStart.push(recapHook);
         changes.push('Added SessionStart hook (memory recap + inbox digest)');
     }
-    else {
+    else if (retargetedRecap === 0) {
         changes.push('SessionStart hook already configured (skipped)');
     }
     if (!hasGrepragHook(settings.hooks.Stop, 'store')) {
@@ -1498,6 +1551,48 @@ function applySettings(settings, apiKey) {
     else {
         changes.push('SessionStart drain hook already configured (skipped)');
     }
+    // SessionStart (persona) — Persona on its OWN hook. Each hook invocation gets
+    // its own ~2048-byte inline allowance from the harness, so a dedicated hook
+    // means the operator's speaking instructions can never lose a byte race to a
+    // doc pointer or a primer. Empty matcher = every source (startup, resume,
+    // clear, compact, fork). adr: adr/announce-inline-budget.md, adr/persona.md
+    const personaSessionStart = {
+        matcher: '',
+        hooks: [{ type: 'command', command: 'greprag-hook persona', timeout: 5000 }],
+    };
+    if (!hasGrepragHook(settings.hooks.SessionStart, 'persona')) {
+        if (!settings.hooks.SessionStart)
+            settings.hooks.SessionStart = [];
+        settings.hooks.SessionStart.push(personaSessionStart);
+        changes.push('Added SessionStart hook (persona, matcher=every source)');
+    }
+    else {
+        changes.push('SessionStart persona hook already configured (skipped)');
+    }
+    // PostCompact (persona) — the same dedicated hook on the other entry point.
+    // `recompact` used to be the restore path, but it fits Persona into the SHARED
+    // ANNOUNCE_INLINE_BUDGET, where anything over 1,430 usable bytes is deferred
+    // whole. Measured against the live 1,886-byte persona: dropped. So a long
+    // session lost its speaking rules at the compaction boundary and nothing said
+    // so. Persona is now excluded from recap/recompact on every harness and rides
+    // this hook instead. Two entries (manual, auto) to match the session-id shape
+    // below — Claude Code's matcher field is a plain string.
+    // adr: adr/persona.md, adr/announce-inline-budget.md
+    if (!settings.hooks.PostCompact)
+        settings.hooks.PostCompact = [];
+    for (const matcher of ['manual', 'auto']) {
+        const entry = {
+            matcher,
+            hooks: [{ type: 'command', command: 'greprag-hook persona', timeout: 5000 }],
+        };
+        if (!hasGrepragHookWithMatcher(settings.hooks.PostCompact, 'persona', matcher)) {
+            settings.hooks.PostCompact.push(entry);
+            changes.push(`Added PostCompact hook (persona, matcher=${matcher})`);
+        }
+        else {
+            changes.push(`PostCompact persona hook (matcher=${matcher}) already configured (skipped)`);
+        }
+    }
     // SessionStart (session-id awareness) — surfaces the agent's own 8-hex
     // session_id at session start so addresses don't need transcript-path
     // spelunking. adr: adr/session-id-awareness.md

package/dist/commands/load.js

@@ -59,6 +59,8 @@ const os = __importStar(require("os"));
 const harness_1 = require("../harness");
 const skill_activation_manifest_1 = require("../skill-activation-manifest");
 const project_anchor_1 = require("../project-anchor");
+const skill_landing_1 = require("../skill-landing");
+const skill_mirror_files_1 = require("../skill-mirror-files");
 const proc_1 = require("../proc");
 const skill_staleness_1 = require("../skill-staleness");
 const doc_mirror_client_1 = require("../doc-mirror-client");
@@ -80,6 +82,12 @@ const LIBRARY = {
         files: ['skill/templates/grok-chip-spawn.md'],
         purpose: 'Spawn a Grok TUI chip (cmd /k bootloader + isolated worktree). Child arms its own inbox watch; parent talks via greprag send. Not spawn_subagent.',
     },
+    // adr: adr/delivery-announce-pilot.md — the announce carries the RULES; this
+    // entry carries the reasoning that used to bloat it out of the inline budget.
+    delivery: {
+        files: ['skill/templates/delivery.md'],
+        purpose: 'Why the delivery rules read the way they do: what the goal already authorizes, who counts as a peer (a chip does not), the merge-lock landing sequence, and where a profile says to deploy from.',
+    },
     'skill-change': {
         files: ['skill/templates/skill-change.md'],
         purpose: 'Internal bundled schema for safely updating a skill after a run: when to edit, Convention A/B shapes, and when to propose instead.',
@@ -100,6 +108,11 @@ const LIBRARY = {
         files: ['skill/templates/chip-leader-opencode.md'],
         purpose: 'Plan a MULTI-CHIP mission for opencode (integration branch, seams, merge order). Loaded from chip-bootloader when ≥2 chips are needed.',
     },
+    // adr: adr/prompt-audit-canon.md — the audit lands through `instructions pull --push`, never a follower edit.
+    'prompt-audit': {
+        files: ['skill/templates/prompt-audit.md'],
+        purpose: 'Audit canonical CLAUDE.md/AGENTS.md instructions for dated-model cruft (shipped rubric) and land accepted edits through `instructions pull --push`, never a follower edit.',
+    },
 };
 /** Absolute path to a payload shipped in the package. */
 function payloadPath(file) {
@@ -408,6 +421,21 @@ async function printMirroredSkill(name, args) {
         console.error(`Mirrored skill "${name}" has no file "${target}". Files: ${files.map((f) => f.path).join(', ')}`);
         process.exit(1);
     }
+    // Serving an adapter here would answer the adapter's own "run `greprag load
+    // <name>` before acting" with the adapter — a closed loop that reads like
+    // content, so an agent works from the description blurb and never notices the
+    // skill's instructions are missing. A missing body is a broken skill; say so.
+    // adr: adr/skill-adapter-never-canon.md
+    if ((0, skill_mirror_files_1.isGeneratedSkillAdapter)(file.content)) {
+        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` +
+            `  greprag skill mirror snapshot list ${name}${identityArg}\n` +
+            `  greprag skill mirror snapshot promote ${name} --name <snapshot>${identityArg} --expected-hash <current-hash>\n`);
+        process.exitCode = 1;
+        return true;
+    }
     if (!args.docPath) {
         const report = (0, skill_staleness_1.analyzeSkillStaleness)(name, file.content, process.cwd());
         const stalenessText = (0, skill_staleness_1.formatSkillStaleness)(report, { details: args.staleness });
@@ -420,6 +448,18 @@ async function printMirroredSkill(name, args) {
     }
     process.stdout.write(file.content.endsWith('\n') ? file.content : file.content + '\n');
     if (!args.docPath) {
+        // A mirror-managed skill's SKILL.md is a generated adapter, so the Skill
+        // Learning Loop cannot land a fuse there without fighting the mirror for
+        // the file. Its pending gains ride the load payload instead — this is the
+        // moment the agent reads the skill. adr: adr/skill-fuse-delivery.md
+        try {
+            const pending = await mirrorGet('/v1/skillgain/pending');
+            const gains = pending?.gains || [];
+            const block = (0, skill_landing_1.buildLoadFuseBlock)(name, gains);
+            if (block)
+                process.stdout.write(block);
+        }
+        catch { /* a gain that fails to surface must never break the skill load */ }
         await printStateDocHints(name, file.content);
         const companions = files.map((f) => f.path).filter((p) => p !== 'SKILL.md');
         if (companions.length > 0) {

package/dist/commands/loadout-reminder.js

@@ -1,7 +1,7 @@
 "use strict";
 /** loadout-registrar — the bundled Interrupt-System module that activates
  *  equipped loadouts (docs/loadout.md §activation model, adr/loadout.md). Modeled
- *  on `assistantDoctrine`: a data-driven announce over a per-tenant signal the
+ *  on `setupWarning`: a data-driven announce over a per-tenant signal the
  *  hook assembles into `env`. THE one piece of executable code in the loadout
  *  feature — shipped in the CLI binary, identical for every tenant. Nothing that
  *  crosses the tenant wall is code; only the inert announce declarations