greprag 5.79.0 → 5.82.0

package/dist/capture-manifest.js

@@ -44,7 +44,8 @@ exports.CAPTURE_MANIFEST = [
         distill: 'greprag-flash',
         register: 'local episode journal + inline-atom-schemas-${projectId}.json registry',
         inject: 'UserPromptSubmit',
-        statuses: ['seeded', 'learned', 'confirmed', 'stale'],
+        // No `confirmed`: replay outcomes demote only. Legacy rows may still carry it.
+        statuses: ['seeded', 'learned', 'stale'],
     },
     {
         id: 'parity-drift',

package/dist/codex-fast-hook.js

@@ -95,6 +95,12 @@ async function main() {
         return;
     }
     let result = chipResult;
+    // adr: adr/deploy-gate-cli.md — same merge contract as Claude, on Codex's
+    // actual pre-tool path. A refusal must precede command rewrites.
+    if (!result?.hookSpecificOutput.permissionDecision) {
+        const { runMergeGuard } = await Promise.resolve().then(() => __importStar(require('./commands/merge-guard')));
+        result = mergeOutputs(result, runMergeGuard(input));
+    }
     if (!result?.hookSpecificOutput.permissionDecision && input.tool_name === 'Bash') {
         const { runSearchGuard } = await Promise.resolve().then(() => __importStar(require('./commands/search-guard')));
         result = mergeOutputs(result, runSearchGuard(input));

package/dist/codex-steering.js

@@ -138,7 +138,7 @@ function formatCodexInboxSteering(messages, session8, excludedIds = new Set()) {
     if (unread.length === 0)
         return null;
     const parts = [
-        `[GrepRAG inbox: ${unread.length} unread message(s) delivered to Codex session ${session8}]`,
+        `[GrepRAG inbox: ${unread.length} unread message(s) delivered to session ${session8}]`,
         `Treat these as live operator/agent messages. Act on them in this turn when relevant.`,
     ];
     unread.slice(0, 10).forEach((message, idx) => {

package/dist/commands/announce.js

@@ -0,0 +1,97 @@
+"use strict";
+/** `greprag announce` — print the full SessionStart announce.
+ *
+ *  The Claude Code harness inlines only ~2KB of hook context (measured; see
+ *  ANNOUNCE_INLINE_BUDGET). The recap hook therefore parks the complete announce
+ *  under ~/.greprag/announce/<session>.md and inlines a pointer naming this
+ *  command. Without it the overflow is unreachable — which is exactly the
+ *  failure this exists to end.
+ *
+ *  adr: adr/announce-inline-budget.md
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAnnounce = runAnnounce;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const session_id_1 = require("../session-id");
+function announceDir() {
+    return path.join(os.homedir(), '.greprag', 'announce');
+}
+/** Newest cached announce, by mtime. Used when no session id is given — the
+ *  common case, since an agent asking for its own announce rarely wants to
+ *  first go find its session id. */
+function newestCached() {
+    try {
+        const dir = announceDir();
+        const files = fs.readdirSync(dir)
+            .filter(f => f.endsWith('.md'))
+            .map(f => ({ f, t: fs.statSync(path.join(dir, f)).mtimeMs }))
+            .sort((a, b) => b.t - a.t);
+        return files.length ? path.join(dir, files[0].f) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function runAnnounce(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write('greprag announce — print the full SessionStart announce\n\n'
+            + 'USAGE\n'
+            + '  greprag announce [--session <8hex>] [--path]\n\n'
+            + '  The harness inlines only ~2KB of session-start context. The rest is\n'
+            + '  parked on disk; this prints all of it.\n\n'
+            + '  --session <8hex>  a specific session (default: most recent)\n'
+            + '  --path            print the cache file path instead of its contents\n');
+        return;
+    }
+    const i = args.indexOf('--session');
+    const wanted = i !== -1 ? args[i + 1] : undefined;
+    const file = wanted
+        ? path.join(announceDir(), `${(0, session_id_1.truncateSessionId)(wanted) || wanted}.md`)
+        : newestCached();
+    if (!file || !fs.existsSync(file)) {
+        process.stderr.write('No cached announce found. It is written at SessionStart, so a session '
+            + 'must have started since this greprag version was installed.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (args.includes('--path')) {
+        process.stdout.write(file + '\n');
+        return;
+    }
+    process.stdout.write(fs.readFileSync(file, 'utf-8').trimEnd() + '\n');
+}

package/dist/commands/app-model.js

@@ -69,7 +69,6 @@ const INTERRUPT_COPY = {
     'setup-warning': { label: 'Setup warnings', description: 'Calls out missing configuration that prevents GrepRAG from working.', group: 'Health' },
     'version-upgrade': { label: 'Update notices', description: 'Warns when the installed CLI is behind the current release.', group: 'Health' },
     'enrichment-health': { label: 'Knowledge health', description: 'Warns when knowledge enrichment is unavailable.', group: 'Health' },
-    'assistant-doctrine': { label: 'Assistant role', description: 'Loads the executive-assistant behavior for its assigned project.', group: 'Roles' },
     'memory-primer': { label: 'Memory guidance', description: 'Teaches agents how and when to retrieve project memory.', group: 'Memory' },
     'watcher-arm': { label: 'Live inbox checks', description: 'Reminds Claude Code to keep live message delivery connected.', group: 'Communication' },
     'mechanic-friction': { label: 'Automatic repair prompts', description: 'Surfaces repeated harness friction for durable repair.', group: 'Automation' },

package/dist/commands/arm-reminder.js

@@ -41,8 +41,8 @@ function buildArmReminder(d, env) {
     const unread = Number((d.detail && d.detail.unread) || 0);
     const arm = env
         ? (env.platform === 'grok'
-            ? `Grok \`monitor\` tool persistent:true command: \`${(0, session_id_1.armMonitorCommand)(env.short, env.ownerPid, env.assistant, env.mechanic, 'grok')}\``
-            : `ToolSearch select:Monitor → persistent Monitor (timeout_ms:3600000) command: \`${(0, session_id_1.armMonitorCommand)(env.short, env.ownerPid, env.assistant, env.mechanic)}\``)
+            ? `Grok \`monitor\` tool persistent:true command: \`${(0, session_id_1.armMonitorCommand)(env.short, env.ownerPid, env.mechanic, 'grok')}\``
+            : `ToolSearch select:Monitor → persistent Monitor (timeout_ms:3600000) command: \`${(0, session_id_1.armMonitorCommand)(env.short, env.ownerPid, env.mechanic)}\``)
         : `arm your Monitor inbox watcher`;
     const grounded = `greprag reads your watcher as DOWN (isLocallyArmed=false — a real pidfile check on your session, NOT a timer; the hook CAN see your watcher)`;
     if (unread > 0) {
@@ -65,11 +65,13 @@ function buildArmAnnounce(short, ownerPid, alias) {
  *  fires while unarmed and auto-silences when armed. Wired into reminder-registry.ts. */
 exports.watcherArmModule = {
     id: 'watcher-arm',
-    // The arm poke rides Claude Code's Monitor tool (ToolSearch select:Monitor); codex
-    // keeps its historical full-registry behavior. opencode is EXCLUDED: its inbox
-    // delivery is the plugin-armed relay (startSessionRelay), so "arm your Monitor"
-    // is unactionable noise there.
-    harnesses: ['claude-code', 'codex', 'grok'],
+    // The arm poke rides the harness's own persistent-watch tool. claude-code is
+    // EXCLUDED (2026-09-04): Claude Code now delivers inbox mail turn-based, through the
+    // same UserPromptSubmit steering Codex uses, plus its own native session messaging —
+    // so the Monitor watcher is retired there and "arm your Monitor" is unactionable
+    // noise. opencode is EXCLUDED for the same reason: its inbox delivery is the
+    // plugin-armed relay (startSessionRelay).
+    harnesses: ['codex', 'grok'],
     detect: armDetect,
     announce: () => null,
     reminder: (d, env) => buildArmReminder(d, env),

package/dist/commands/collision-check.js

@@ -13,7 +13,7 @@
  *  wide}`. A collision is any row with MY project (by project_id — the git-root-
  *  commit UUID, identical across worktrees of one repo — with a project_name
  *  fallback) and a DIFFERENT session id. Project matching IS the discriminator:
- *  service watchers (receptionist / desk-line / the Assistant) carry a different
+ *  service watchers (receptionist / desk-line) carry a different
  *  project_id (or none), so they never match a working session's repo and are
  *  excluded for free. (`wide` is NOT a usable filter — observed true on ordinary
  *  session-scoped watchers, not just tenant-wide ones.) Liveness here depends on
@@ -79,8 +79,8 @@ const session_id_1 = require("../session-id");
  *   · self is excluded by the 8-hex compare (both sides truncated).
  *   · match on project_id (the stable git-root-commit UUID, identical across
  *     worktrees of the same repo) with a project_name fallback for rows whose
- *     id the cloud could not resolve. Service watchers (receptionist / desk-line
- *     / Assistant) carry a different project_id (or none), so they fail the match
+ *     id the cloud could not resolve. Service watchers (receptionist / desk-line)
+ *     carry a different project_id (or none), so they fail the match
  *     and are excluded without any role/`wide` special-case. */
 function isCollision(myShort, myProjectId, myProjectName, w) {
     const peerShort = (0, session_id_1.truncateSessionId)(w.session_id);
@@ -124,16 +124,17 @@ function buildCollisionDirective(peers, myShort, alias) {
         + lines.join('\n') + '\n'
         + `Coordinate BEFORE touching shared files: (1) message each peer now with a contextual heads-up — `
         + `Codex peers: use \`codex_app.list_threads\` to find the task and its repo/workspace, then \`codex_app.send_message_to_thread\` to send the heads-up; `
-        + `GrepRAG watcher/cross-harness peers: \`greprag send "…what you're about to touch…" --to ${handle}@greprag.com/<their-8hex> --from-session ${myShort}\` `
+        + `Claude Code peers: use your harness's own session list + send tools — the 8-hex ids above are GREPRAG addresses and are not accepted by them; `
+        + `peers OUTSIDE this harness (opencode / Grok / another tenant): \`greprag send "…what you're about to touch…" --to ${handle}@greprag.com/<their-8hex> --from-session ${myShort}\` `
         + `(YOU compose and send it — this is a notice, not an auto-send; recipients reply only for a concrete conflict, silence is approval, and you never poll or wait; watcher rows are not the Codex peer source of truth); `
         + `(2) do your code work in a worktree on its own branch (\`git worktree add .claude/worktrees/<slug> -b <branch>\`); `
-        + `(3) at completion resolve \`.greprag/delivery.json\`, send one fire-and-forget delivery notice, then continue immediately without polling, waiting, status reads, or follow-ups; `
+        + `(3) at completion resolve \`.greprag/delivery.json\`, send one fire-and-forget delivery notice to PEER sessions only — never to a chip (title \`Chip: \` / \`Chip <Label>: \`), which reports to its own parent and has no business with merge, deploy or master — then continue immediately without polling, waiting, status reads, or follow-ups; `
         + `sweep every ready same-repo commit, ignore all uncommitted and untracked work, resolve conflicts directly, and finish the declared push/deploy/release path. Never edit the shared default checkout concurrently.`);
 }
 /** Reduce the watcher list to OTHER live sessions that are NOT in my repo
  *  (cross-repo). Excludes self, same-repo collisions (those get the LOUD
  *  directive), and rows with no session id or no project_name (service watchers
- *  — receptionist / desk-line / Assistant — are unnamed or differently-anchored,
+ *  — receptionist / desk-line — are unnamed or differently-anchored,
  *  so they fall out without a role special-case). PURE. */
 function detectOtherSessions(myShort, myProjectId, myProjectName, watchers) {
     const seen = new Set();

package/dist/commands/corpus/client.js

@@ -130,9 +130,19 @@ async function apiDelete(url, apiKey, body) {
         throw new Error(`API ${res.status}: ${await res.text()}`);
     return res.json();
 }
-/** Internal store kinds — engine plumbing, NOT user corpora. Hidden from the
- *  default `corpus list`; shown with --all or an explicit --kind. adr: adr/corpus-tags.md */
-exports.INTERNAL_KINDS = ['memory', 'fix', 'inbox'];
+/** Kinds hidden from the default `corpus list` — shown with --all or an
+ *  explicit --kind. This is the queues-and-registries set from
+ *  SEARCHABLE_KINDS/BOOKKEEPING_KINDS in @greprag/core, mirrored here because
+ *  the CLI ships as a zero-dependency artifact and cannot import core.
+ *
+ *  It used to be ['memory','fix','inbox'], which was wrong in both directions:
+ *  it hid memory (76 stores of real searchable text that the unscoped search
+ *  was returning hits from anyway) while listing 97 skill-gain and doc-pointer
+ *  registries that hold almost nothing. What you could list and what you
+ *  actually searched were two different sets, with nothing saying so.
+ *  Listing and search now answer from the same classification.
+ *  adr: adr/searchable-store-kinds.md, adr: adr/corpus-tags.md */
+exports.INTERNAL_KINDS = ['inbox', 'fix', 'docptr', 'skillgain', 'parity', 'doctrine'];
 // -- Arg helpers -----------------------------------------------------------
 function getFlag(args, flag) {
     const idx = args.indexOf(flag);

package/dist/commands/delivery-reminder.js

@@ -5,22 +5,38 @@
  * verbs run shadow-only. It contains no provider commands: those remain
  * repo/target configuration. I/O (Git repo detection) stays in each harness
  * adapter and arrives as env.deliveryRepo.
+ *
+ * RULES ONLY. This block is `mustInline` — it is worthless parked on disk,
+ * because a session that never reads it asks the operator for permission it
+ * already has. Every correction to delivery behavior is therefore written as a
+ * RULE here and its reasoning goes to `greprag load delivery`. Twice the block
+ * grew a paragraph of explanation instead (2026-09-04 peer tools, 2026-09-07
+ * merge preparation), crossed the inline budget, and was dropped whole for nine
+ * days: the harness went back to asking before every merge and deploy.
  * docs/delivery-system.md, docs/delivery-migration-ledger.md */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deliveryControlModule = void 0;
 exports.buildDeliveryAnnounce = buildDeliveryAnnounce;
 // adr: adr/delivery-announce-pilot.md
+/** How THIS harness finds same-repo peers — the one line that legitimately
+ *  differs per platform. Everything else about notifying (once, fire-and-forget,
+ *  chips excluded, why greprag is not the address book) is shared prose that
+ *  belongs in `greprag load delivery`, not in nine duplicated sentences here. */
 function coordinationLine(platform) {
-    if (platform === 'codex') {
-        return 'Codex: send one fire-and-forget delivery notice to same-repo peers with codex_app.send_message_to_thread, then continue immediately. Recipients reply only for a concrete conflict; silence is approval. Never poll, call wait_threads, re-read peers, ask for status, or send delivery follow-ups.';
-    }
-    if (platform === 'claude-code') {
-        return 'Claude Code: send one fire-and-forget delivery notice to same-repo peers, then continue immediately. Recipients reply only for a concrete conflict; silence is approval. Never poll, wait, ask for status, or send delivery follow-ups.';
-    }
-    if (platform === 'opencode') {
-        return 'OpenCode: send one fire-and-forget delivery notice to same-repo peers through the GrepRAG registry, then continue immediately. Recipients reply only for a concrete conflict; silence is approval. Never poll, wait, ask for status, or send delivery follow-ups.';
-    }
-    return 'Send one fire-and-forget delivery notice to same-repo peers, then continue immediately. Recipients reply only for a concrete conflict; silence is approval. Never poll, wait, ask for status, or send delivery follow-ups.';
+    const how = platform === 'codex'
+        ? 'codex_app.list_threads + codex_app.send_message_to_thread'
+        : platform === 'claude-code'
+            ? "this harness's own session-list + send tools (never a greprag id)"
+            : platform === 'opencode'
+                ? 'the GrepRAG registry'
+                : 'your harness\'s own peer tools';
+    // Codex keeps its one extra word: `wait_threads` is the specific tool a Codex
+    // session reaches for when it decides to wait for a reply it was told not to
+    // wait for. A named tool is a rule; "do not wait" alone was not enough.
+    const never = platform === 'codex'
+        ? 'never poll, call wait_threads, ask for status, or follow up'
+        : 'never poll, wait, ask for status, or follow up';
+    return `Notify same-repo peer sessions ONCE via ${how}, then continue. A \`Chip: \` session is not a peer. Silence is approval: ${never}.`;
 }
 function buildDeliveryAnnounce(env) {
     if (!env.deliveryRepo)
@@ -28,15 +44,20 @@ function buildDeliveryAnnounce(env) {
     const project = env.projectName?.trim() || 'current repo';
     return [
         `[DELIVERY — ${project}]`,
-        'Commit useful, passing work.',
-        'Only committed Git state participates in delivery. Ignore all uncommitted and untracked work in every checkout.',
+        'Commit useful, passing work. Only committed state delivers; ignore uncommitted and untracked work in every checkout.',
         coordinationLine(env.platform),
-        'Sweep every ready same-repo commit into the integration train, resolve conflicts directly, and merge to the default branch. Worktrees build; they do not deploy. Deploy only from the repo canonical primary checkout on that branch. Leave dirt; do not classify it. Merge conflicts are the only coordination.',
-        'Use this repo\'s delivery profile and verify production.',
+        '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.',
+        '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`.',
     ].join('\n');
 }
 exports.deliveryControlModule = {
     id: 'delivery-control',
+    // Parked on disk this block does nothing: a session that never runs `greprag
+    // announce` asks the operator to authorize work the goal already authorized.
+    // tests/test-announce-budget.cjs fails the build if it outgrows the budget.
+    mustInline: true,
     detect: (_env) => ({ tier: 'silent' }),
     announce: buildDeliveryAnnounce,
     reminder: () => null,

package/dist/commands/deploy-gate.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeployGate = runDeployGate;
+const deploy_gate_1 = require("../deploy-gate");
+const HELP = `greprag deploy-gate — the repo-independent half of a deploy gate
+
+Usage:
+  greprag deploy-gate [--target <id>] [--json] [--ignore-lock] [--cwd <path>]
+
+Answers the questions that do not depend on how a target's artifact is built:
+may a deploy run from here, is one already running, and what is shipping. Reads
+.greprag/delivery.json for the canonical root and default branch.
+
+Read-only: acquires no lock, writes no ledger, mutates no checkout. The artifact
+proof stays with the repo and is reported as a skipped, repo-owned check.
+
+Exit 0 when every check passes, 1 when any refuses.
+
+Options:
+  --target <id>   Deploy target, used for the lock and ledger names (default: default)
+  --ignore-lock   Skip the lock check because the caller already holds it
+  --cwd <path>    Evaluate this checkout instead of the working directory
+  --json          Machine-readable verdict`;
+function flagValue(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    return value && !value.startsWith('--') ? value : undefined;
+}
+function runDeployGate(args) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+        console.log(HELP);
+        return;
+    }
+    const verdict = (0, deploy_gate_1.evaluateDeployGate)({
+        cwd: flagValue(args, '--cwd'),
+        target: flagValue(args, '--target'),
+        ignoreLock: args.includes('--ignore-lock'),
+    });
+    if (args.includes('--json')) {
+        console.log(JSON.stringify(verdict));
+    }
+    else {
+        console.log(`deploy-gate v${deploy_gate_1.DEPLOY_GATE_VERSION}: ${verdict.verdict.toUpperCase()} (target ${verdict.target})`);
+        for (const check of verdict.checks) {
+            const mark = check.status === 'pass' ? '✓' : check.status === 'fail' ? '✗' : '–';
+            console.log(`  ${mark} ${check.id}: ${check.detail}`);
+        }
+        for (const line of verdict.shipping)
+            console.log(`  ${line}`);
+    }
+    if (verdict.verdict === 'refuse')
+        process.exitCode = 1;
+}

package/dist/commands/deploy-lock.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeployLock = runDeployLock;
+const deploy_locks_1 = require("../deploy-locks");
+const HELP = `greprag deploy-lock — one deploy at a time per target
+
+Usage:
+  greprag deploy-lock acquire --target <id> [--pid <n>] [--label <text>] [--json]
+  greprag deploy-lock release --target <id> [--json]
+  greprag deploy-lock status  --target <id> [--json]
+
+The deploy gate refuses while this is held. Sift and the site have had it since
+their gate was local; a repo onboarded without it has a lock check that can never
+fire, which reads as a pass and is not one.
+
+Unlike the merge lock this one is PROCESS-held: it is stale as soon as its owner
+dies, so a crashed deploy does not block the next one for an hour. That only works
+if the recorded pid is the process actually deploying. A script that shells out to
+this command must pass its own pid with \`--pid\`, because this command exits
+immediately and its own pid would be dead before the deploy started.
+
+Exit 0 when the lock is yours, 1 when someone else holds it.
+
+Options:
+  --target <id>   Deploy target, e.g. worker, api-production, paybot-production
+  --pid <n>       The deploying process (default: this command's parent)
+  --label <text>  What this deploy is, shown to whoever is blocked by it
+  --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;
+}
+function runDeployLock(args) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+        console.log(HELP);
+        return;
+    }
+    const sub = args[0] || 'status';
+    const json = args.includes('--json');
+    const target = flagValue(args, '--target') || 'default';
+    const cwd = process.cwd();
+    let file;
+    try {
+        file = (0, deploy_locks_1.deployLockPath)(cwd, target);
+    }
+    catch (error) {
+        console.error(`deploy-lock: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (sub === 'acquire') {
+        const explicit = Number.parseInt(flagValue(args, '--pid') || '', 10);
+        // Falling back to the parent covers a shell caller that did not pass one. Our own
+        // pid is never right here: this process is gone before the deploy begins.
+        const pid = Number.isInteger(explicit) && explicit > 0 ? explicit : process.ppid;
+        const result = (0, deploy_locks_1.acquireLock)(file, flagValue(args, '--label') || `deploy ${target}`, deploy_locks_1.DEPLOY_STALE_MS, { pid });
+        if (json)
+            console.log(JSON.stringify({ ...result, pid }));
+        else if (result.ok) {
+            console.log(`deploy-lock: ${target} held by pid ${pid}`);
+            if (result.held)
+                console.log(`  reclaimed a stale lock from pid ${result.held.record.pid}`);
+        }
+        else {
+            console.error(`deploy-lock: another deploy of ${target} is running (pid ${result.held?.record.pid},`
+                + ` session ${result.held ? (0, deploy_locks_1.describeLockOwner)(result.held.record) : 'unidentified'}, started ${result.held?.record.startedAt}).`
+                + '\n  Wait for it. Two deploys of one target race to decide what production runs.');
+        }
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === 'release') {
+        (0, deploy_locks_1.releaseLock)(file);
+        if (json)
+            console.log(JSON.stringify({ released: true, path: file }));
+        else
+            console.log(`deploy-lock: ${target} released`);
+        return;
+    }
+    if (sub === 'status') {
+        const held = (0, deploy_locks_1.readLock)(file);
+        if (json) {
+            console.log(JSON.stringify({ target, held }));
+            return;
+        }
+        if (!held)
+            console.log(`deploy-lock: ${target} not held`);
+        else if (held.stale)
+            console.log(`deploy-lock: ${target} stale (pid ${held.record.pid}, started ${held.record.startedAt}) — would be reclaimed`);
+        else
+            console.log(`deploy-lock: ${target} held by pid ${held.record.pid}, session ${(0, deploy_locks_1.describeLockOwner)(held.record)}, since ${held.record.startedAt}`);
+        return;
+    }
+    console.error(`Unknown deploy-lock command: ${sub}\n\n${HELP}`);
+    process.exitCode = 1;
+}

package/dist/commands/deploy-record.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lastDeployPath = lastDeployPath;
+exports.runDeployRecord = runDeployRecord;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const deploy_locks_1 = require("../deploy-locks");
+const proc_1 = require("../proc");
+const HELP = `greprag deploy-record — remember what this checkout last shipped
+
+Usage:
+  greprag deploy-record --target <id> [--sha <commit>] [--json]
+  greprag deploy-record show --target <id> [--json]
+
+Write this AFTER a deploy is verified live, never before. The gate reads it to
+answer "what is shipping" — the commits between the last deploy and HEAD, with
+late-arriving ones called out. A repo that never records is told "no record of a
+previous deploy", which is honest but useless, and that was the state of every
+repo onboarded without a local deploy script.
+
+It is also the only baseline a deploy script has for "what changed since last
+time" — which files, which migrations. Without it those questions can only be
+answered against history, which is not the same question and produces a list
+long enough that nobody reads it.
+
+Lives inside .git beside the locks, so it is never tree dirt and cannot be
+committed. It is per-checkout by design: what THIS checkout last shipped.
+
+Options:
+  --target <id>   Deploy target, e.g. web-production, paybot-production
+  --sha <commit>  What was shipped (default: HEAD)
+  --json          Machine-readable result`;
+/** The basename already on disk in sift and the site. The CLI writes the real
+ *  ledger the gate reads, never a parallel one. */
+const LOCK_PREFIX = process.env.GREPRAG_DEPLOY_LOCK_PREFIX || 'sift';
+function lastDeployPath(cwd, target) {
+    return path.join((0, deploy_locks_1.gitDir)(cwd), `${LOCK_PREFIX}-last-deploy-${target}.json`);
+}
+function flagValue(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    return value && !value.startsWith('--') ? value : undefined;
+}
+function resolveCommit(rev, cwd) {
+    const result = (0, proc_1.safeSpawnSync)('git', ['rev-parse', '--verify', `${rev}^{commit}`], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0 ? String(result.stdout).trim() : null;
+}
+function runDeployRecord(args) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+        console.log(HELP);
+        return;
+    }
+    const json = args.includes('--json');
+    const target = flagValue(args, '--target');
+    const cwd = process.cwd();
+    if (!target) {
+        console.error(`deploy-record: --target is required.\n\n${HELP}`);
+        process.exitCode = 1;
+        return;
+    }
+    let file;
+    try {
+        file = lastDeployPath(cwd, target);
+    }
+    catch (error) {
+        console.error(`deploy-record: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (args[0] === 'show') {
+        let record = null;
+        try {
+            record = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            record = null;
+        }
+        if (json)
+            console.log(JSON.stringify({ target, record }));
+        else if (!record)
+            console.log(`deploy-record: no record of a previous ${target} deploy from this checkout`);
+        else {
+            const value = record;
+            console.log(`deploy-record: ${target} last shipped ${String(value.sha).slice(0, 10)} at ${value.at}`);
+        }
+        return;
+    }
+    const sha = resolveCommit(flagValue(args, '--sha') || 'HEAD', cwd);
+    if (!sha) {
+        console.error('deploy-record: that is not a commit in this repository — nothing recorded.');
+        process.exitCode = 1;
+        return;
+    }
+    const record = { sha, at: new Date().toISOString(), target };
+    try {
+        fs.writeFileSync(file, JSON.stringify(record));
+    }
+    catch (error) {
+        // A deploy that shipped and verified is done. Failing it here would report a
+        // successful deploy as a failure, which is the worse of the two wrong answers.
+        console.error(`deploy-record: WARNING — the deploy is live but was not recorded: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    if (json)
+        console.log(JSON.stringify(record));
+    else
+        console.log(`deploy-record: ${target} now recorded at ${sha.slice(0, 10)}`);
+}