greprag 5.74.10 → 5.74.12

package/dist/codex-delivery-coordination.js

@@ -0,0 +1,213 @@
+"use strict";
+/** Codex delivery coordination - interrupt the first delivery action once,
+ * then keep the rest of that delivery run non-blocking.
+ *
+ * The hook cannot call native Codex task tools. It names the exact agent-owned
+ * discovery and messaging actions, persists the open delivery window before
+ * denying, and never waits for peer replies or attestation.
+ *
+ * adr: adr/codex-coordinate-gate.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.DELIVERY_COORDINATION_WINDOW_MS = void 0;
+exports.codexDeliveryTrigger = codexDeliveryTrigger;
+exports.codexDeliveryCoordinationText = codexDeliveryCoordinationText;
+exports.evaluateCodexDeliveryCoordination = evaluateCodexDeliveryCoordination;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const coordinate_gate_1 = require("./commands/coordinate-gate");
+exports.DELIVERY_COORDINATION_WINDOW_MS = 30 * 60 * 1000;
+function homeDir() {
+    return process.env.USERPROFILE || process.env.HOME || '';
+}
+function normalize(value) {
+    return path.resolve(value).replace(/\\/g, '/').toLowerCase();
+}
+function gitRoot(cwd) {
+    try {
+        const root = (0, child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        }).trim();
+        return root ? normalize(root) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function statePath(input, repoRoot) {
+    const home = homeDir();
+    const session = (input.session_id || '').trim();
+    if (!home || !session)
+        return null;
+    const key = crypto.createHash('sha256')
+        .update(`${session}\0${repoRoot}`)
+        .digest('hex')
+        .slice(0, 24);
+    return path.join(home, '.greprag', 'state', `codex-delivery-${key}.json`);
+}
+function readWindow(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeWindow(file, window) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(window, null, 2) + '\n');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isShellCapableTool(input) {
+    const name = (input.tool_name || '').toLowerCase();
+    return /(?:^|[.:/_-])(bash|shell|exec|exec_command)$/.test(name);
+}
+function decodeQuoted(value) {
+    if (value.startsWith('"')) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (value.startsWith("'")) {
+        return value.slice(1, -1).replace(/\\'/g, "'").replace(/\\\\/g, '\\');
+    }
+    return null;
+}
+function embeddedCommands(code) {
+    const commands = [];
+    const re = /(?:command|cmd)\s*:\s*("(?:\\.|[^"])*"|'(?:\\.|[^'])*')/g;
+    for (const match of code.matchAll(re)) {
+        const decoded = decodeQuoted(match[1]);
+        if (decoded)
+            commands.push(decoded);
+    }
+    return commands;
+}
+function commandCandidates(input) {
+    if (!isShellCapableTool(input))
+        return [];
+    const toolInput = input.tool_input;
+    if (typeof toolInput === 'string')
+        return embeddedCommands(toolInput);
+    if (!toolInput || typeof toolInput !== 'object')
+        return [];
+    const candidates = [];
+    const fields = toolInput;
+    for (const key of ['command', 'cmd', 'script']) {
+        const value = fields[key];
+        if (typeof value === 'string')
+            candidates.push(value);
+    }
+    for (const key of ['code', 'input']) {
+        const value = fields[key];
+        if (typeof value === 'string')
+            candidates.push(...embeddedCommands(value));
+    }
+    return candidates;
+}
+function codexDeliveryTrigger(input) {
+    for (const command of commandCandidates(input)) {
+        const trigger = (0, coordinate_gate_1.classifyRiskyCommand)(command);
+        if (trigger)
+            return trigger;
+    }
+    return null;
+}
+function codexDeliveryCoordinationText(trigger) {
+    return `[DELIVERY NOW]
+
+Before ${trigger.label}, call codex_app.list_threads unfiltered and keep only peers in the same repo. Use codex_app.send_message_to_thread once for peers with ready or overlapping work; include your branch/commit and ask only for ready commits or concrete blockers.
+
+Include ready handoffs and clear known blockers, then retry immediately. Do not call wait_threads, wait for replies, or send follow-ups. Missing replies and unfinished peer work do not block delivery.`;
+}
+/** First delivery action opens a 30-minute session/repo window and interrupts
+ * once. Later merge/push/deploy/release actions refresh the same window and
+ * proceed without another coordination round. */
+function evaluateCodexDeliveryCoordination(input, now = Date.now()) {
+    if (input.hook_event_name !== 'PreToolUse')
+        return null;
+    const trigger = codexDeliveryTrigger(input);
+    if (!trigger)
+        return null;
+    const cwd = input.cwd || process.cwd();
+    const repoRoot = gitRoot(cwd);
+    if (!repoRoot)
+        return null;
+    const file = statePath(input, repoRoot);
+    if (!file)
+        return null;
+    const previous = readWindow(file);
+    const previousLastAction = previous ? Date.parse(previous.lastActionAt) : NaN;
+    if (previous
+        && previous.repoRoot === repoRoot
+        && Number.isFinite(previousLastAction)
+        && now - previousLastAction < exports.DELIVERY_COORDINATION_WINDOW_MS) {
+        writeWindow(file, {
+            ...previous,
+            lastActionAt: new Date(now).toISOString(),
+        });
+        return null;
+    }
+    const openedAt = new Date(now).toISOString();
+    if (!writeWindow(file, {
+        sessionId: input.session_id || '',
+        repoRoot,
+        openedAt,
+        lastActionAt: openedAt,
+    })) {
+        return null;
+    }
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            additionalContext: codexDeliveryCoordinationText(trigger),
+            permissionDecision: 'deny',
+            permissionDecisionReason: `Run one same-repo coordination pass, then retry ${trigger.label} immediately; peer replies are not required.`,
+        },
+    };
+}

package/dist/codex-fast-hook.js

@@ -83,10 +83,8 @@ async function main() {
         return;
     }
     if (subcommand === 'codex-posttooluse') {
-        const { evaluateCodexCommitResult } = await Promise.resolve().then(() => __importStar(require('./codex-checkpoint-hook')));
-        const result = evaluateCodexCommitResult(input);
-        if (result)
-            process.stdout.write(JSON.stringify(result) + '\n');
+        // Compatibility no-op for installed configs predating the delivery-boundary
+        // cutover. `greprag init --codex` removes this hook.
         return;
     }
     const { evaluateCodexChipHook } = await Promise.resolve().then(() => __importStar(require('./codex-chip-hooks')));
@@ -97,10 +95,9 @@ async function main() {
         return;
     }
     let result = chipResult;
-    if (subcommand === 'codex-pretooluse') {
-        const { evaluatePendingCodexCheckpoint, recordCodexGitBoundary, } = await Promise.resolve().then(() => __importStar(require('./codex-checkpoint-hook')));
-        result = mergeOutputs(result, evaluatePendingCodexCheckpoint(input));
-        recordCodexGitBoundary(input);
+    if (subcommand === 'codex-pretooluse' && !result?.hookSpecificOutput.permissionDecision) {
+        const { evaluateCodexDeliveryCoordination } = await Promise.resolve().then(() => __importStar(require('./codex-delivery-coordination')));
+        result = mergeOutputs(result, evaluateCodexDeliveryCoordination(input));
     }
     if (!result?.hookSpecificOutput.permissionDecision && input.tool_name === 'Bash') {
         const { runSearchGuard } = await Promise.resolve().then(() => __importStar(require('./commands/search-guard')));

package/dist/commands/coordinate-gate.js

@@ -27,8 +27,8 @@
  *  dedups to stay quiet), the merge gate must reflect live truth each time.
  *
  *  EFFECT is the adapter's choice, not the eval's: Claude/OpenCode inject the
- *  fresh roster as context; Codex denies until artifact-bound conferral evidence
- *  exists because Codex does not support a permission `ask` decision. An
+ *  fresh roster as context. Codex uses the separate local, bounded delivery
+ *  interrupt in codex-delivery-coordination.ts and carries no attestation. An
  *  ingress-source wrapper would inject instead. The eval below only produces
  *  the message.
  *

package/dist/commands/delivery-reminder.js

@@ -12,27 +12,26 @@ exports.buildDeliveryAnnounce = buildDeliveryAnnounce;
 // adr: adr/delivery-announce-pilot.md
 function coordinationLine(platform) {
     if (platform === 'codex') {
-        return 'Codex coordination: call list_threads unfiltered, filter to this repo/worktree, inspect matching tasks, then send_message_to_thread with your branch/commit/status before merge/push/deploy. Use GrepRAG only for cross-harness peers.';
+        return 'Codex: at the merge/deploy gate, call codex_app.list_threads unfiltered, filter to peers in the same repo, then use codex_app.send_message_to_thread once for ready or overlapping work.';
     }
     if (platform === 'claude-code') {
-        return 'Claude Code coordination: discover peers with `greprag inbox watchers --json`, send to the exact session, and keep the Monitor armed for replies.';
+        return 'Claude Code: at the merge/deploy gate, discover peers in the same repo and send one concise delivery notice to peers with ready or overlapping work.';
     }
     if (platform === 'opencode') {
-        return 'OpenCode coordination: use the GrepRAG project/session registry and session-targeted send; the plugin relay delivers replies.';
+        return 'OpenCode: at the merge/deploy gate, use the GrepRAG project/session registry and send one concise delivery notice to peers with ready or overlapping work.';
     }
-    return 'Coordination: discover same-project peers through this harness and use GrepRAG for cross-harness peers.';
+    return 'At the merge/deploy gate, coordinate once with peers in the same repo who have ready or overlapping work.';
 }
 function buildDeliveryAnnounce(env) {
     if (!env.deliveryRepo)
         return null;
     const project = env.projectName?.trim() || 'current repo';
     return [
-        `[DELIVERY CONTROL — ${project}]`,
-        'For full-goal code work, done means checkpointed, coordinated, integrated, pushed, deployed, and production-verified. Checkpoint each passing fix or feature.',
+        `[DELIVERY — ${project}]`,
+        'Commit useful, passing work.',
         coordinationLine(env.platform),
-        'Before merge, push, deploy, or release: elect one delivery owner. That owner includes every ready peer commit, resolves ordinary mission conflicts, and settles unclaimed dirt by adopt, rescue, or discard.',
-        'Use the canonical commit, deploy, and release skills plus this repo\'s delivery configuration. Never borrow a branch, remote, provider command, or verification rule from another repo.',
-        'A full-goal delivery mission already provisions ordinary repo-scoped commit, merge, push, deploy, and verification; do not wait for a second keyword.',
+        'Include ready peer commits and clear known blockers, then merge to the default branch and deploy immediately. Missing replies and unfinished peer work do not block delivery.',
+        'Use this repo\'s delivery profile and verify production.',
     ].join('\n');
 }
 exports.deliveryControlModule = {

package/dist/commands/doctor.js

@@ -275,8 +275,12 @@ async function runShimAudit(opts) {
     console.log('Windows shims:');
     for (const s of shims) {
         const ver = s.version ? `v${s.version}` : '(version unknown)';
-        const missing = s.incomplete ? ` missing ${s.missingFiles.join(', ')}` : '';
-        const flag = s.stale ? `  ⚠ STALE${missing}` : s.incomplete ? `  ⚠ INCOMPLETE${missing}` : s.unresolvable ? '  ? unresolvable' : '';
+        const details = [
+            ...(s.incomplete ? [`missing ${s.missingFiles.join(', ')}`] : []),
+            ...(s.volatileForward ? ['fnm temp forward'] : []),
+        ];
+        const suffix = details.length ? ` ${details.join(', ')}` : '';
+        const flag = s.stale ? `  ⚠ STALE${suffix}` : s.incomplete ? `  ⚠ INCOMPLETE${suffix}` : s.volatileForward ? `  ⚠ VOLATILE${suffix}` : s.unresolvable ? '  ? unresolvable' : '';
         console.log(`  ${s.name}${s.active ? '' : ' (shadowed)'}: ${s.shimPath} → ${ver}${flag}`);
     }
     if (unhealthy.length === 0) {
@@ -291,7 +295,7 @@ async function runShimAudit(opts) {
     if (!opts.yes) {
         const fixable = repairs.filter(r => r.forwardTo);
         for (const r of repairs.filter(x => !x.forwardTo)) {
-            console.log(`  ✗ ${r.shim.shimPath} is unhealthy and no current ${r.shim.name} shim exists on PATH to forward to — run \`npm i -g greprag@latest\` first.`);
+            console.log(`  ✗ ${r.shim.shimPath} is unhealthy and no durable current ${r.shim.name} shim exists on PATH to forward to — run \`${(0, windows_shims_1.shimInstallCommand)()}\` first.`);
         }
         if (fixable.length === 0) {
             console.log('');

package/dist/commands/friction-reminder.js

@@ -5,10 +5,10 @@
  *  live stress level) rather than a binary resolvable deficiency.
  *
  *  A reminder-interrupt MODULE is `{ id, detect, announce, reminder }` (reminder-types.ts):
- *  `detect(env)` reads the live state → a tier (`silent` = nothing to fix); a SessionStart
- *  `announce` loads the schema ONCE; a per-turn `reminder` fires a thin, grounded pointer
- *  back at it. The no-orphan invariant requires the PAIR. The container (reminder-registry.ts)
- *  wires every module; the hook (hook.ts) assembles the env and emits — see `injectReminders`.
+ *  `detect(env)` reads the live state → a tier (`silent` = nothing to fix); the grepragOS
+ *  primer owns the startup schema, and this module contributes only a thin live reminder.
+ *  The container (reminder-registry.ts) wires every module; the hook (hook.ts) assembles
+ *  the env and emits — see `injectReminders`.
  *
  *  PURE: imports only the stress constants; returns strings + a tier + a tally. No fs, no
  *  network, no clock — the hook does ALL I/O. Keeping detect/tier a pure function is what
@@ -19,10 +19,10 @@ exports.frictionReminderTier = frictionReminderTier;
 exports.buildMechanicLiveNotice = buildMechanicLiveNotice;
 exports.buildFrictionReminder = buildFrictionReminder;
 exports.buildBootstrapFrictionReminder = buildBootstrapFrictionReminder;
-exports.buildMechanicAnnounce = buildMechanicAnnounce;
 exports.tallyFrictionFire = tallyFrictionFire;
 exports.tallyMechanicSpawn = tallyMechanicSpawn;
 const state_trigger_1 = require("./state-trigger");
+// adr: adr/friction-memory-first.md
 function quoteForCommand(value) {
     return value.replace(/[\r\n]+/g, ' ').replace(/"/g, '\\"').trim();
 }
@@ -49,21 +49,22 @@ function frictionReminderTier(stress) {
         return 'nudge';
     return 'silent';
 }
-/** The per-turn reminder line — fires only on detected stress, points at the ONE
- *  friction reflex (fix spawn), ends on a forced binary so it converts. null = calm.
+/** The per-turn reminder line — fires only on detected stress, points first at
+ *  Memory for a known overcome, then at fix spawn for unresolved friction.
+ *  Ends on a forced binary so it converts. null = calm.
  *  The queue-route (`mechanic friction`) and log-route (`fix log`) verbs were
- *  RETIRED as reflexes 2026-07-12 (grepragOS): friction is fixed at the moment,
- *  one chip per unit. */
+ *  RETIRED as reflexes 2026-07-12 (grepragOS). */
 const FIX_SPAWN = 'greprag fix spawn --type <harness|doctrine|injection|env|code> "<one unit>"';
+const MEMORY_SEARCH = 'greprag memory search "<exact error/friction + repo/tool>"';
 function buildMechanicLiveNotice(_env) {
-    return `GrepRAG Mechanic is live. Friction reflex: \`${FIX_SPAWN}\` — one fix chip per unit, spawned at the moment; then keep working. Check role only when needed: \`greprag mechanic role\`.`;
+    return `GrepRAG Mechanic is live. Friction order: \`${MEMORY_SEARCH}\` first; apply a clear overcome and continue. No answer, failed overcome, or repeated friction → \`${FIX_SPAWN}\`. Check role only when needed: \`greprag mechanic role\`.`;
 }
 function buildFrictionReminder(tier, env) {
     switch (tier) {
         case 'nag':
-            return `⚠ FRICTION HIGH (live signal: repetition / errors / churn) — STOP pushing through. Name the ONE unit, choose type by repair surface, and spawn now: \`${FIX_SPAWN}\` (chip fixes, verifies, checkpoints, and hands it to the mission delivery owner). No friction? say "clear" + continue.`;
+            return `⚠ FRICTION HIGH (live signal: repetition / errors / churn) — STOP pushing through. MEMORY FIRST: \`${MEMORY_SEARCH}\`. Clear overcome → apply + continue. No answer, remembered overcome fails, or same friction repeats → \`${FIX_SPAWN}\`. No friction? say "clear" + continue.`;
         case 'nudge':
-            return `⚠ Friction detected (live signal) — repeated yourself, fought a tool, or hit a wall? Choose type by repair surface and spawn: \`${FIX_SPAWN}\`, then keep working. Otherwise say "clear" + continue.`;
+            return `⚠ Friction detected (live signal) — repeated yourself, fought a tool, or hit a wall? Search first: \`${MEMORY_SEARCH}\`. Apply a clear overcome + continue; no answer, failed overcome, or repeat → \`${FIX_SPAWN}\`. Otherwise say "clear" + continue.`;
         default:
             return null;
     }
@@ -74,25 +75,8 @@ function buildBootstrapFrictionReminder(env) {
         return null;
     const repeats = b.repeats && b.repeats > 1 ? ` repeated ${b.repeats}x` : '';
     const error = b.error ? ` Last error: ${b.error}` : '';
-    return `⚠ BOOTSTRAP FRICTION detected${repeats}: setup/toolchain failure (${b.signal || 'setup'}) around \`${b.command || 'unknown command'}\`.${error} If this is not caused by the code you just edited, spawn a fix chip now: \`greprag fix spawn --type env "${bootstrapSummary(env)}"\`. The chip owns the root-cause repair, verifies it, and hands it to the mission delivery owner so future sessions stop hitting it.`;
-}
-// ---------- The fix-reflex primer (announce-only) ----------------------------
-/** SessionStart primer — the fix reflex, loaded ONCE. Full doctrine inline
- *  (a PRIMER, not a pointer): it teaches WHEN friction is a spawn-now signal
- *  and the chip's delivery-owner contract. Rewritten 2026-07-12 (grepragOS):
- *  the queue-route (`mechanic friction`), log-route (`fix log`) and the
- *  one-Mechanic-absorbs-all-friction model are RETIRED as reflexes — one unit
- *  of friction ⇒ one fix chip, spawned at the moment. */
-function buildMechanicAnnounce() {
-    return [
-        '[Fix reflex — friction is fixed at the MOMENT it happens, one chip per unit (grepragOS law; full doctrine: `greprag load os`).]',
-        'WHEN friction happens — repeated yourself, fought a tool, got corrected >=2x on the same thing, rediscovered something already known, or hit a setup/toolchain failure not caused by code you just edited — spawn its fix chip NOW, then keep working. Ordinary misunderstanding or misreading user intent is not friction unless it repeats or exposes a durable doctrine/harness/injection/env/code failure. One unit = one chip; adjacent friction gets its own spawn. Never queue friction for later.',
-        'TYPE = durable repair surface: harness=hooks/watchers/task dispatch; doctrine=greprag load/skills/AGENTS; injection=recap/Capture/doc-pointer/stateful injection; env=bootstrap/deps/scripts/worktree setup; code=product/source behavior. Use: `greprag fix spawn --type <type> "<one unit>"`.',
-        'WORKSPACE ROUTING: `fix spawn` detects usable Git history before dispatch — Git uses an isolated worktree; non-Git, unavailable Git, or no commit uses the project-local task with serialized writes. No fail-then-fallback attempt.',
-        'THE CHIP\'S CONTRACT (it self-enforces; you just spawn): identify the exact friction → make the smallest durable root-cause fix → explain and verify it → checkpoint → hand it to the mission delivery owner. With no live parent and a full-goal mission, the chip becomes delivery owner and follows the repo profile. No second lifecycle approval.',
-        'Every repair is ROOT-CAUSE — fix the pattern that makes the friction class possible, never a guard on today\'s trigger.',
-        'A per-turn reminder fires ONLY when live friction is DETECTED (the stress signal — repetition / errors / churn), never on a timer — act on it, or say "clear" and continue.',
-    ].join('\n');
+    const summary = bootstrapSummary(env);
+    return `⚠ BOOTSTRAP FRICTION detected${repeats}: setup/toolchain failure (${b.signal || 'setup'}) around \`${b.command || 'unknown command'}\`.${error} MEMORY FIRST: \`greprag memory search "${summary}"\`. Apply a clear overcome + continue. No answer, remembered overcome fails, or the same failure repeats → \`greprag fix spawn --type env "${summary}"\`.`;
 }
 /** Normalize any prior-stats blob (possibly missing/partial/corrupt) into a fully
  *  populated FrictionStats. Pure, total. */
@@ -136,13 +120,10 @@ function tallyMechanicSpawn(prior) {
     return s;
 }
 // ---------- Registry module --------------------------------------------------
-/** The active Mechanic — a PRIMER-ONLY module (docs/load-system.md): one strong
- *  SessionStart announce, no per-turn reminder (the friction nag was removed
- *  2026-06-22 as wallpaper). `dependsOn` the chip-spawn pointer so the chip concept
- *  it references is already loaded — the boot sequence places it AFTER chips. */
+/** The active Mechanic reminder. The grepragOS primer owns the one startup schema;
+ *  this module is reminder-only and fires only from live stress/bootstrap state. */
 exports.mechanicFrictionModule = {
     id: 'mechanic-friction',
-    dependsOn: ['chip-spawn-pointer'],
     // Stress fires the real friction reminder. A designated Mechanic also creates a
     // one-shot ambient route notice per source session/role epoch (hook-stamped).
     detect: (env) => {
@@ -155,12 +136,7 @@ exports.mechanicFrictionModule = {
             return { tier: 'ambient' };
         return { tier: 'silent' };
     },
-    announce: (env = {}) => {
-        const base = buildMechanicAnnounce();
-        if (env.mechanicLive && !env.mechanic)
-            return `${base}\n\n${buildMechanicLiveNotice(env)}`;
-        return base;
-    },
+    announce: () => null,
     reminder: (d, env) => {
         if (d.detail?.kind === 'bootstrap-friction')
             return buildBootstrapFrictionReminder(env);

package/dist/commands/init.js

@@ -1130,18 +1130,9 @@ function applyCodexHooks(config) {
     if (removedPostToolInbox) {
         changes.push(`Removed ${removedPostToolInbox} Codex PostToolUse inbox hook(s); UserPromptSubmit now owns inbox steering`);
     }
-    const checkpointHook = {
-        matcher: '',
-        hooks: [commandHook('codex-posttooluse', 5, 'Coordinating Codex checkpoint', 'greprag-codex-hook')],
-    };
-    if (!hasGrepragHook(config.hooks.PostToolUse, 'codex-posttooluse')) {
-        if (!config.hooks.PostToolUse)
-            config.hooks.PostToolUse = [];
-        config.hooks.PostToolUse.push(checkpointHook);
-        changes.push('Added Codex PostToolUse hook (successful checkpoint coordination)');
-    }
-    else {
-        changes.push('Codex PostToolUse checkpoint hook already configured (skipped)');
+    const removedPostToolCoord = removeGrepragHook(config.hooks, 'PostToolUse', 'codex-posttooluse');
+    if (removedPostToolCoord) {
+        changes.push(`Removed ${removedPostToolCoord} Codex commit-triggered coordination hook(s); delivery coordination now starts at PreToolUse`);
     }
     const permissionHook = {
         matcher: '',
@@ -1199,8 +1190,8 @@ function applyCodexHooks(config) {
     ];
     // adr: adr/codex-hook-latency.md
     // Collapse the hot PreToolUse safety pair into one fast command process. It
-    // runs the chip/apply_patch guard plus local Bash safety checks. The retired
-    // coordination gate is removed when found so old configs stop blocking.
+    // runs the chip/apply_patch guard, one-shot delivery coordination, and local
+    // Bash safety checks. The legacy split coordination gate is removed.
     const removedPreToolChip = removeGrepragHook(config.hooks, 'PreToolUse', 'codex-chip-hook');
     const removedPreToolCoord = removeGrepragHook(config.hooks, 'PreToolUse', 'codex-coordinate-gate');
     if (removedPreToolChip || removedPreToolCoord) {
@@ -1208,16 +1199,16 @@ function applyCodexHooks(config) {
     }
     const preToolUseHook = {
         matcher: '',
-        hooks: [commandHook('codex-pretooluse', 10, 'Checking GrepRAG Codex safety', 'greprag-codex-hook')],
+        hooks: [commandHook('codex-pretooluse', 10, 'Checking GrepRAG Codex delivery and safety', 'greprag-codex-hook')],
     };
     if (!hasGrepragHookWithMatcher(config.hooks.PreToolUse, 'codex-pretooluse', preToolUseHook.matcher)) {
         if (!config.hooks.PreToolUse)
             config.hooks.PreToolUse = [];
         config.hooks.PreToolUse.push(preToolUseHook);
-        changes.push('Added Codex PreToolUse hook (multiplexed local safety)');
+        changes.push('Added Codex PreToolUse hook (delivery coordination + local safety)');
     }
     else {
-        changes.push('Codex PreToolUse multiplexed safety hook already configured (skipped)');
+        changes.push('Codex PreToolUse delivery/safety hook already configured (skipped)');
     }
     const removedStopChip = removeGrepragHook(config.hooks, 'Stop', 'codex-chip-hook');
     if (removedStopChip) {
@@ -1278,7 +1269,7 @@ function normalizeCodexHookCommands(hooks) {
         'codex-permission-context': { timeout: 3, statusMessage: 'Loading GrepRAG approval context' },
         'codex-subagent-start': { timeout: 3, statusMessage: 'Recording GrepRAG subagent metadata' },
         'codex-chip-hook': { timeout: 3, statusMessage: 'Enforcing Codex chip contract', runner: 'greprag-codex-hook' },
-        'codex-pretooluse': { timeout: 10, statusMessage: 'Checking GrepRAG Codex safety', runner: 'greprag-codex-hook' },
+        'codex-pretooluse': { timeout: 10, statusMessage: 'Checking GrepRAG Codex delivery and safety', runner: 'greprag-codex-hook' },
         'codex-coordinate-gate': { timeout: 10, statusMessage: 'Checking peer coordination' },
         'codex-store': { timeout: 3, statusMessage: 'Storing GrepRAG turn', runner: 'greprag-codex-hook' },
     };

package/dist/commands/load.js

@@ -63,7 +63,7 @@ const doc_mirror_client_1 = require("../doc-mirror-client");
 const LIBRARY = {
     os: {
         files: ['skill/templates/os.md'],
-        purpose: 'grepragOS — the operating laws: doctrine vs state, discoverability, pull-before-derive, friction ⇒ fix spawn, teach the system not the chat.',
+        purpose: 'grepragOS — the operating laws: doctrine vs state, discoverability, pull-before-derive, memory-first friction recovery, unresolved friction ⇒ fix spawn, teach the system not the chat.',
     },
     'chip-spawn': {
         files: ['skill/templates/chip-spawn.md'],

package/dist/commands/opencode-interrupt.js

@@ -29,9 +29,9 @@ function buildOpenCodeEnv(params) {
         // No opencode-native friction detector is wired yet: Claude Code's stress /
         // bootstrap-friction signals come from state-trigger.ts reading the
         // transcript in hook.ts, and opencode has no equivalent source plumbed.
-        // 0 = calm keeps the mechanic-friction REMINDER silent while its ANNOUNCE
-        // (the fix-spawn doctrine) still lands every session. Detector design is
-        // parked with scored options in the chip report
+        // 0 = calm keeps the reminder-only mechanic-friction module silent. The
+        // os-primer still lands the memory-first escalation doctrine every session.
+        // Detector design is parked with scored options in the chip report
         // (chip/opencode-fix-chip-system-parity).
         stress: 0,
         armed: params.armed ?? false,

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

@@ -13,6 +13,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.osPrimerModule = void 0;
 exports.buildOsPrimer = buildOsPrimer;
+// adr: adr/friction-memory-first.md
 function buildOsPrimer(env) {
     // The chip-spawn method is per-harness (Codex never sees the Claude entry —
     // the same wall the codex-chip-spawn pointer module enforces; opencode's
@@ -24,8 +25,8 @@ function buildOsPrimer(env) {
         '[grepragOS — the operating laws. Full doctrine: `greprag load os`.]',
         '• Doctrine vs state: methods ship in the CLI (`greprag load`); live state lives in the repo. A skill that depends on repo state carries a "STATE — read these first" block naming exact paths.',
         '• Discoverability: every durable artifact must be findable next session — docs auto-register, skills auto-mirror, decisions get a dated ADR/decision-log entry, everything else gets its path named in the owning skill/doc. If nothing points at it, you didn\'t finish.',
-        '• Pull before derive: `greprag memory search` / `corpus search` / `load` BEFORE asking the operator or re-deriving what the project already knows. Env/toolchain/worktree/secret bootstrap roadblock → search Memory for the exact error and repo/tool before inventing a workaround. Named person/org/project/repo/customer/handle or unexplained proper noun → search Memory before guessing, unless fully defined in-turn.',
-        `• Friction ⇒ fix NOW: type by durable repair surface (\`harness|doctrine|injection|env|code\`) ⇒ \`greprag fix spawn --type <type> "<unit>"\`. It PRINTS a fix-chip mission — YOU then create the visible child task with that mission as its first message (how: \`greprag load ${spawnEntry}\`, or your harness's native task tool). Repo write = isolated worktree; data-only row/diagnosis = no repo write. One unit per chip; the chip fixes, verifies, checkpoints, and hands it to the mission delivery owner. Never queue friction.`,
+        '• Pull before derive: `greprag memory search` / `corpus search` / `load` BEFORE asking the operator or re-deriving what the project already knows. Friction or an env/toolchain/worktree/secret bootstrap roadblock → search Memory for the exact error/friction + repo/tool before inventing a workaround. Clear overcome → apply it and continue. Named person/org/project/repo/customer/handle or unexplained proper noun → search Memory before guessing, unless fully defined in-turn.',
+        `• Unresolved friction ⇒ fix: only when Memory has no answer, the remembered overcome fails, or the same friction repeats. Then type by durable repair surface (\`harness|doctrine|injection|env|code\`) ⇒ \`greprag fix spawn --type <type> "<unit>"\`. It PRINTS a fix-chip mission — YOU then create the visible child task with that mission as its first message (how: \`greprag load ${spawnEntry}\`, or your harness's native task tool). Repo write = isolated worktree; data-only row/diagnosis = no repo write. One unresolved unit per chip; the chip fixes, verifies, checkpoints, and hands it to the mission delivery owner.`,
         '• Teach the system, not the chat: explained twice by the operator ⇒ it belongs in a skill / load entry / STATE block / ADR, not the conversation.',
     ].join('\n');
 }

package/dist/commands/reminder-registry.js

@@ -30,10 +30,9 @@ const loadout_reminder_1 = require("./loadout-reminder");
 const delivery_reminder_1 = require("./delivery-reminder");
 /** Registry order = display order. THE single agent-facing announce/reminder assembly:
  *  the hook does I/O → fills ReminderEnv → collectAnnounces (SessionStart) / collectReminders
- *  (per turn) render every module here in this order. Order preserves the historical recap
- *  preamble (setup-warning → front-desk → checkpoint → assistant-doctrine) and keeps the two
- *  loud, action-first modules last (watcher-arm → mechanic) so they read most-recent at
- *  SessionStart. Add a module here to wire it into BOTH surfaces at once. */
+ *  (per turn) render every module here in this order. A module may own either surface or both;
+ *  os-primer owns startup friction doctrine and mechanic-friction is reminder-only.
+ *  Add a module here to wire it into the appropriate surfaces at once. */
 exports.REGISTRY = [
     os_primer_reminder_1.osPrimerModule, // grepragOS constitution — the frame every other primer hangs off; boots FIRST
     inbox_primer_reminder_1.inboxPrimerModule,

package/dist/commands/status.js

@@ -327,8 +327,12 @@ function renderShims(w) {
     const lines = ['', 'Windows shims (what each PowerShell/CMD shim on PATH actually executes):'];
     for (const s of w.shims) {
         const ver = s.version ? `v${s.version}` : '(version unknown)';
-        const missing = s.incomplete ? ` missing ${s.missingFiles.join(', ')}` : '';
-        const flag = s.stale ? `  ⚠ STALE${missing}` : s.incomplete ? `  ⚠ INCOMPLETE${missing}` : s.unresolvable ? '  ? unresolvable' : '';
+        const details = [
+            ...(s.incomplete ? [`missing ${s.missingFiles.join(', ')}`] : []),
+            ...(s.volatileForward ? ['fnm temp forward'] : []),
+        ];
+        const suffix = details.length ? ` ${details.join(', ')}` : '';
+        const flag = s.stale ? `  ⚠ STALE${suffix}` : s.incomplete ? `  ⚠ INCOMPLETE${suffix}` : s.volatileForward ? `  ⚠ VOLATILE${suffix}` : s.unresolvable ? '  ? unresolvable' : '';
         lines.push(`  ${s.name}${s.active ? '' : ' (shadowed)'}: ${s.shimPath} → ${ver}${flag}`);
     }
     if (w.mismatch) {

package/dist/opencode-plugin.bundle.js

@@ -1752,8 +1752,8 @@ function buildOsPrimer(env) {
     "[grepragOS \u2014 the operating laws. Full doctrine: `greprag load os`.]",
     '\u2022 Doctrine vs state: methods ship in the CLI (`greprag load`); live state lives in the repo. A skill that depends on repo state carries a "STATE \u2014 read these first" block naming exact paths.',
     "\u2022 Discoverability: every durable artifact must be findable next session \u2014 docs auto-register, skills auto-mirror, decisions get a dated ADR/decision-log entry, everything else gets its path named in the owning skill/doc. If nothing points at it, you didn't finish.",
-    "\u2022 Pull before derive: `greprag memory search` / `corpus search` / `load` BEFORE asking the operator or re-deriving what the project already knows. Env/toolchain/worktree/secret bootstrap roadblock \u2192 search Memory for the exact error and repo/tool before inventing a workaround. Named person/org/project/repo/customer/handle or unexplained proper noun \u2192 search Memory before guessing, unless fully defined in-turn.",
-    `\u2022 Friction \u21D2 fix NOW: type by durable repair surface (\`harness|doctrine|injection|env|code\`) \u21D2 \`greprag fix spawn --type <type> "<unit>"\`. It PRINTS a fix-chip mission \u2014 YOU then create the visible child task with that mission as its first message (how: \`greprag load ${spawnEntry}\`, or your harness's native task tool). Repo write = isolated worktree; data-only row/diagnosis = no repo write. One unit per chip; the chip fixes, verifies, checkpoints, and hands it to the mission delivery owner. Never queue friction.`,
+    "\u2022 Pull before derive: `greprag memory search` / `corpus search` / `load` BEFORE asking the operator or re-deriving what the project already knows. Friction or an env/toolchain/worktree/secret bootstrap roadblock \u2192 search Memory for the exact error/friction + repo/tool before inventing a workaround. Clear overcome \u2192 apply it and continue. Named person/org/project/repo/customer/handle or unexplained proper noun \u2192 search Memory before guessing, unless fully defined in-turn.",
+    `\u2022 Unresolved friction \u21D2 fix: only when Memory has no answer, the remembered overcome fails, or the same friction repeats. Then type by durable repair surface (\`harness|doctrine|injection|env|code\`) \u21D2 \`greprag fix spawn --type <type> "<unit>"\`. It PRINTS a fix-chip mission \u2014 YOU then create the visible child task with that mission as its first message (how: \`greprag load ${spawnEntry}\`, or your harness's native task tool). Repo write = isolated worktree; data-only row/diagnosis = no repo write. One unresolved unit per chip; the chip fixes, verifies, checkpoints, and hands it to the mission delivery owner.`,
     "\u2022 Teach the system, not the chat: explained twice by the operator \u21D2 it belongs in a skill / load entry / STATE block / ADR, not the conversation."
   ].join("\n");
 }
@@ -2022,15 +2022,16 @@ function frictionReminderTier(stress) {
   return "silent";
 }
 var FIX_SPAWN = 'greprag fix spawn --type <harness|doctrine|injection|env|code> "<one unit>"';
+var MEMORY_SEARCH = 'greprag memory search "<exact error/friction + repo/tool>"';
 function buildMechanicLiveNotice(_env) {
-  return `GrepRAG Mechanic is live. Friction reflex: \`${FIX_SPAWN}\` \u2014 one fix chip per unit, spawned at the moment; then keep working. Check role only when needed: \`greprag mechanic role\`.`;
+  return `GrepRAG Mechanic is live. Friction order: \`${MEMORY_SEARCH}\` first; apply a clear overcome and continue. No answer, failed overcome, or repeated friction \u2192 \`${FIX_SPAWN}\`. Check role only when needed: \`greprag mechanic role\`.`;
 }
 function buildFrictionReminder(tier, env) {
   switch (tier) {
     case "nag":
-      return `\u26A0 FRICTION HIGH (live signal: repetition / errors / churn) \u2014 STOP pushing through. Name the ONE unit, choose type by repair surface, and spawn now: \`${FIX_SPAWN}\` (chip fixes, verifies, checkpoints, and hands it to the mission delivery owner). No friction? say "clear" + continue.`;
+      return `\u26A0 FRICTION HIGH (live signal: repetition / errors / churn) \u2014 STOP pushing through. MEMORY FIRST: \`${MEMORY_SEARCH}\`. Clear overcome \u2192 apply + continue. No answer, remembered overcome fails, or same friction repeats \u2192 \`${FIX_SPAWN}\`. No friction? say "clear" + continue.`;
     case "nudge":
-      return `\u26A0 Friction detected (live signal) \u2014 repeated yourself, fought a tool, or hit a wall? Choose type by repair surface and spawn: \`${FIX_SPAWN}\`, then keep working. Otherwise say "clear" + continue.`;
+      return `\u26A0 Friction detected (live signal) \u2014 repeated yourself, fought a tool, or hit a wall? Search first: \`${MEMORY_SEARCH}\`. Apply a clear overcome + continue; no answer, failed overcome, or repeat \u2192 \`${FIX_SPAWN}\`. Otherwise say "clear" + continue.`;
     default:
       return null;
   }
@@ -2041,22 +2042,11 @@ function buildBootstrapFrictionReminder(env) {
     return null;
   const repeats = b.repeats && b.repeats > 1 ? ` repeated ${b.repeats}x` : "";
   const error = b.error ? ` Last error: ${b.error}` : "";
-  return `\u26A0 BOOTSTRAP FRICTION detected${repeats}: setup/toolchain failure (${b.signal || "setup"}) around \`${b.command || "unknown command"}\`.${error} If this is not caused by the code you just edited, spawn a fix chip now: \`greprag fix spawn --type env "${bootstrapSummary(env)}"\`. The chip owns the root-cause repair, verifies it, and hands it to the mission delivery owner so future sessions stop hitting it.`;
-}
-function buildMechanicAnnounce() {
-  return [
-    "[Fix reflex \u2014 friction is fixed at the MOMENT it happens, one chip per unit (grepragOS law; full doctrine: `greprag load os`).]",
-    "WHEN friction happens \u2014 repeated yourself, fought a tool, got corrected >=2x on the same thing, rediscovered something already known, or hit a setup/toolchain failure not caused by code you just edited \u2014 spawn its fix chip NOW, then keep working. Ordinary misunderstanding or misreading user intent is not friction unless it repeats or exposes a durable doctrine/harness/injection/env/code failure. One unit = one chip; adjacent friction gets its own spawn. Never queue friction for later.",
-    'TYPE = durable repair surface: harness=hooks/watchers/task dispatch; doctrine=greprag load/skills/AGENTS; injection=recap/Capture/doc-pointer/stateful injection; env=bootstrap/deps/scripts/worktree setup; code=product/source behavior. Use: `greprag fix spawn --type <type> "<one unit>"`.',
-    "WORKSPACE ROUTING: `fix spawn` detects usable Git history before dispatch \u2014 Git uses an isolated worktree; non-Git, unavailable Git, or no commit uses the project-local task with serialized writes. No fail-then-fallback attempt.",
-    "THE CHIP'S CONTRACT (it self-enforces; you just spawn): identify the exact friction \u2192 make the smallest durable root-cause fix \u2192 explain and verify it \u2192 checkpoint \u2192 hand it to the mission delivery owner. With no live parent and a full-goal mission, the chip becomes delivery owner and follows the repo profile. No second lifecycle approval.",
-    "Every repair is ROOT-CAUSE \u2014 fix the pattern that makes the friction class possible, never a guard on today's trigger.",
-    'A per-turn reminder fires ONLY when live friction is DETECTED (the stress signal \u2014 repetition / errors / churn), never on a timer \u2014 act on it, or say "clear" and continue.'
-  ].join("\n");
+  const summary = bootstrapSummary(env);
+  return `\u26A0 BOOTSTRAP FRICTION detected${repeats}: setup/toolchain failure (${b.signal || "setup"}) around \`${b.command || "unknown command"}\`.${error} MEMORY FIRST: \`greprag memory search "${summary}"\`. Apply a clear overcome + continue. No answer, remembered overcome fails, or the same failure repeats \u2192 \`greprag fix spawn --type env "${summary}"\`.`;
 }
 var mechanicFrictionModule = {
   id: "mechanic-friction",
-  dependsOn: ["chip-spawn-pointer"],
   // Stress fires the real friction reminder. A designated Mechanic also creates a
   // one-shot ambient route notice per source session/role epoch (hook-stamped).
   detect: (env) => {
@@ -2069,14 +2059,7 @@ var mechanicFrictionModule = {
       return { tier: "ambient" };
     return { tier: "silent" };
   },
-  announce: (env = {}) => {
-    const base = buildMechanicAnnounce();
-    if (env.mechanicLive && !env.mechanic)
-      return `${base}
-
-${buildMechanicLiveNotice(env)}`;
-    return base;
-  },
+  announce: () => null,
   reminder: (d, env) => {
     if (d.detail?.kind === "bootstrap-friction")
       return buildBootstrapFrictionReminder(env);
@@ -2418,27 +2401,26 @@ var loadoutRegistrarModule = {
 // src/commands/delivery-reminder.ts
 function coordinationLine(platform) {
   if (platform === "codex") {
-    return "Codex coordination: call list_threads unfiltered, filter to this repo/worktree, inspect matching tasks, then send_message_to_thread with your branch/commit/status before merge/push/deploy. Use GrepRAG only for cross-harness peers.";
+    return "Codex: at the merge/deploy gate, call codex_app.list_threads unfiltered, filter to peers in the same repo, then use codex_app.send_message_to_thread once for ready or overlapping work.";
   }
   if (platform === "claude-code") {
-    return "Claude Code coordination: discover peers with `greprag inbox watchers --json`, send to the exact session, and keep the Monitor armed for replies.";
+    return "Claude Code: at the merge/deploy gate, discover peers in the same repo and send one concise delivery notice to peers with ready or overlapping work.";
   }
   if (platform === "opencode") {
-    return "OpenCode coordination: use the GrepRAG project/session registry and session-targeted send; the plugin relay delivers replies.";
+    return "OpenCode: at the merge/deploy gate, use the GrepRAG project/session registry and send one concise delivery notice to peers with ready or overlapping work.";
   }
-  return "Coordination: discover same-project peers through this harness and use GrepRAG for cross-harness peers.";
+  return "At the merge/deploy gate, coordinate once with peers in the same repo who have ready or overlapping work.";
 }
 function buildDeliveryAnnounce(env) {
   if (!env.deliveryRepo)
     return null;
   const project = env.projectName?.trim() || "current repo";
   return [
-    `[DELIVERY CONTROL \u2014 ${project}]`,
-    "For full-goal code work, done means checkpointed, coordinated, integrated, pushed, deployed, and production-verified. Checkpoint each passing fix or feature.",
+    `[DELIVERY \u2014 ${project}]`,
+    "Commit useful, passing work.",
     coordinationLine(env.platform),
-    "Before merge, push, deploy, or release: elect one delivery owner. That owner includes every ready peer commit, resolves ordinary mission conflicts, and settles unclaimed dirt by adopt, rescue, or discard.",
-    "Use the canonical commit, deploy, and release skills plus this repo's delivery configuration. Never borrow a branch, remote, provider command, or verification rule from another repo.",
-    "A full-goal delivery mission already provisions ordinary repo-scoped commit, merge, push, deploy, and verification; do not wait for a second keyword."
+    "Include ready peer commits and clear known blockers, then merge to the default branch and deploy immediately. Missing replies and unfinished peer work do not block delivery.",
+    "Use this repo's delivery profile and verify production."
   ].join("\n");
 }
 var deliveryControlModule = {
@@ -2558,9 +2540,9 @@ function buildOpenCodeEnv(params) {
     // No opencode-native friction detector is wired yet: Claude Code's stress /
     // bootstrap-friction signals come from state-trigger.ts reading the
     // transcript in hook.ts, and opencode has no equivalent source plumbed.
-    // 0 = calm keeps the mechanic-friction REMINDER silent while its ANNOUNCE
-    // (the fix-spawn doctrine) still lands every session. Detector design is
-    // parked with scored options in the chip report
+    // 0 = calm keeps the reminder-only mechanic-friction module silent. The
+    // os-primer still lands the memory-first escalation doctrine every session.
+    // Detector design is parked with scored options in the chip report
     // (chip/opencode-fix-chip-system-parity).
     stress: 0,
     armed: params.armed ?? false,

package/dist/windows-shims.js

@@ -10,7 +10,9 @@
  *  silently emitted no loadout announce and the report looked like a server
  *  bug. The CLI must catch that split itself: `greprag status` names every
  *  shim + the version it actually executes; `greprag doctor` rewrites stale
- *  shims to forward to a current one.
+ *  shims to forward to a current one. Durable shims must not forward into
+ *  fnm_multishells: those are per-shell temp directories and can disappear
+ *  while the stable PATH entry remains.
  *
  *  Pure helpers (parse/version/plan) are exported for unit tests; only
  *  `auditWindowsShims`/`repairStaleShims` touch PATH + disk.
@@ -55,6 +57,7 @@ exports.missingRequiredShimFiles = missingRequiredShimFiles;
 exports.auditWindowsShims = auditWindowsShims;
 exports.shimNeedsRepair = shimNeedsRepair;
 exports.planShimRepairs = planShimRepairs;
+exports.shimInstallCommand = shimInstallCommand;
 exports.repairStaleShims = repairStaleShims;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -111,6 +114,9 @@ function missingRequiredShimFiles(scriptPath, name) {
         return [];
     return requiredFilesForShim(name).filter(file => !fs.existsSync(path.join(info.root, file)));
 }
+function isFnmMultishellPath(p) {
+    return !!p && /[\\/]fnm_multishells[\\/]/i.test(path.normalize(p));
+}
 /** Resolve one shim: follow up to 3 .cmd forwarding hops, then read the
  *  owning package version. */
 function resolveShim(name, shimPath, active, installed) {
@@ -134,6 +140,7 @@ function resolveShim(name, shimPath, active, installed) {
     }
     const info = target ? shimPackageInfo(target) : null;
     const missingFiles = info ? requiredFilesForShim(name).filter(file => !fs.existsSync(path.join(info.root, file))) : [];
+    const volatileForward = !isFnmMultishellPath(shimPath) && isFnmMultishellPath(target);
     return {
         name,
         extension: path.extname(shimPath).toLowerCase() === '.ps1' ? '.ps1' : '.cmd',
@@ -143,6 +150,7 @@ function resolveShim(name, shimPath, active, installed) {
         version: info?.version ?? null,
         stale: info !== null && info.version !== installed,
         incomplete: missingFiles.length > 0,
+        volatileForward,
         missingFiles,
         unresolvable: target === null || info === null,
     };
@@ -199,7 +207,7 @@ function auditWindowsShims(installedVersion) {
     return out;
 }
 function shimNeedsRepair(shim) {
-    return shim.stale || shim.incomplete;
+    return shim.stale || shim.incomplete || shim.volatileForward;
 }
 function canForward(from, to) {
     if (from.extension === '.ps1')
@@ -214,6 +222,7 @@ function planShimRepairs(audits) {
             && !shimNeedsRepair(a)
             && !a.unresolvable
             && a.shimPath !== shim.shimPath
+            && (isFnmMultishellPath(shim.shimPath) || !isFnmMultishellPath(a.shimPath))
             && canForward(shim, a));
         return { shim, forwardTo: healthy ? healthy.shimPath : null };
     });
@@ -224,8 +233,15 @@ function describeProblem(shim) {
         parts.push(`v${shim.version}`);
     if (shim.incomplete)
         parts.push(`missing ${shim.missingFiles.join(', ')}`);
+    if (shim.volatileForward)
+        parts.push('fnm temp forward');
     return parts.length ? parts.join(', ') : 'unhealthy';
 }
+function shimInstallCommand() {
+    return process.platform === 'win32'
+        ? 'npm i -g greprag@latest --prefix "%APPDATA%\\npm"'
+        : 'npm i -g greprag@latest';
+}
 function writeForwarder(shim, forwardTo) {
     if (shim.extension === '.ps1') {
         fs.writeFileSync(shim.shimPath, [
@@ -250,7 +266,7 @@ function repairStaleShims(repairs) {
     const lines = [];
     for (const r of repairs) {
         if (!r.forwardTo) {
-            lines.push(`✗ ${r.shim.shimPath} is unhealthy (${describeProblem(r.shim)}) and no current ${r.shim.name} shim exists on PATH to forward to — run \`npm i -g greprag@latest\`, then re-run doctor.`);
+            lines.push(`✗ ${r.shim.shimPath} is unhealthy (${describeProblem(r.shim)}) and no durable current ${r.shim.name} shim exists on PATH to forward to — run \`${shimInstallCommand()}\`, then re-run doctor.`);
             continue;
         }
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greprag",
-  "version": "5.74.10",
+  "version": "5.74.12",
   "description": "GrepRAG — agent memory for Claude Code, Codex, and OpenCode.",
   "main": "dist/index.js",
   "bin": {

package/skill/mechanic/SKILL.md

@@ -2,7 +2,7 @@
 name: mechanic
 description: |
   The Mechanic — keep the harness healthy. The loop is friction → fix → repair:
-  spawn one fix chip per live friction unit, then repair so it can't recur.
+  recall known overcomes first; spawn one fix chip per unresolved friction unit.
   Digest the existing fix queue and audit/design notes, audit fixes for drift,
   mine episodic memory, promote project-agnostic repairs to global. One-at-a-time
   conversational review — never bulk.
@@ -19,10 +19,13 @@ license: MIT
 
 # Mechanic
 
-> **Fix-spawn reflex (ratified 2026-07-12, grepragOS law 4 — supersedes the
-> routing/queueing reflex below wherever they conflict).** Friction is fixed at
-> the MOMENT it happens: `greprag fix spawn --type <type> "<one unit>"` emits a
-> FIX chip for exactly that unit (never absorb adjacent friction). The chip's
+> **Memory-first friction reflex (refined 2026-07-28, grepragOS laws 3–4 —
+> supersedes the routing/queueing reflex below wherever they conflict).** Search
+> Memory for the exact error/friction plus repo/tool first. Apply a clear
+> remembered overcome and continue. Only when Memory has no answer, the overcome
+> fails, or the same friction repeats does
+> `greprag fix spawn --type <type> "<one unit>"` emit a FIX chip for that
+> unresolved unit. The chip's
 > contract: identify the exact friction → make the smallest durable root-cause
 > fix → explain the friction and fix in human terms → checkpoint → hand it to
 > the mission delivery owner. A full-goal chip with no live parent becomes that
@@ -46,7 +49,7 @@ task.
 
 The Mechanic keeps the harness healthy. The loop is **friction → fix → repair**:
 
-- **friction** — a rough spot the agent or operator hit: a gotcha, a rediscovery, a repeated correction, churn, rework. Ordinary misunderstanding or misreading user intent is not friction unless it repeats or exposes a durable doctrine/harness/injection/env/code failure. Live friction becomes one `greprag fix spawn --type <type> "<unit>"` chip at the moment it happens.
+- **friction** — a rough spot the agent or operator hit: a gotcha, a rediscovery, a repeated correction, churn, rework. Ordinary misunderstanding or misreading user intent is not friction unless it repeats or exposes a durable doctrine/harness/injection/env/code failure. Search Memory first; a clear overcome is applied inline, while unresolved friction becomes one `greprag fix spawn --type <type> "<unit>"` chip.
 - **fix** — the repair mission or audit note. Live fixes are owned by spawned FIX chips; the queue remains for existing backlog and deliberate design-input notes.
 - **repair** — the fix wired in so it can't recur: a hook, a code change, or *surfacing it* (a doc line / a fact-seed / an injection). A repaired fix is done.
 
@@ -292,11 +295,11 @@ greprag mechanic off / on             PANIC SWITCH — local file, no network; s
 
 **Legacy Mechanic role.** A `--mechanic` inbox watcher can still receive
 legacy `mechanic_friction` / `mechanic_reply` rows in addition to its own session
-lane, but live working sessions no longer route friction there. New friction is
-always Law 4: `greprag fix spawn --type <type> "<one unit>"`, one FIX chip per
-unit, at the moment it happens. `greprag mechanic set` only fans out a notice
-that teaches this fix-spawn reflex and preserves the reply rail for old mechanic
-threads. The Mechanic replies with `greprag mechanic reply --to <source-session>
+lane, but live working sessions no longer route friction there. Laws 3–4 search
+Memory first, then route each unresolved unit through
+`greprag fix spawn --type <type> "<one unit>"`. `greprag mechanic set` only
+fans out a notice that teaches this reflex and preserves the reply rail for old
+mechanic threads. The Mechanic replies with `greprag mechanic reply --to <source-session>
 "..."` only for legacy follow-up coordination.
 
 **Born shadow → graduate.** Every repair is born `shadow`: it matches and logs would-have-fired

package/skill/mechanic/docs/skill-fix-conventions.md

@@ -6,7 +6,7 @@
 
 The skill-tuning reflex injects a directive when a skill under break-in loads. The old directive said "watch your execution, emit a SELF-TUNING block, propose a fix" — vague (it pointed at the *run*, not the *skill*) and propose-only (no edit ever landed). This doc replaces that with **six locatable skill defects**, each mapped to one concrete edit. The reflex's loop is: **detect a defined friction → locate it in the skill's SKILL.md → apply the fix per the matching recipe → show the diff for one accept/revert.**
 
-A friction that doesn't match one of the six below is **not auto-fixable inline** — spawn a doctrine fix chip for the one unit (`greprag fix spawn --type doctrine "<skill friction unit>"`) and keep working. Use `greprag fix log` only for deliberate audit/design notes, not as the live-friction reflex. Do not invent edits outside these recipes.
+A friction that doesn't match one of the six below is **not auto-fixable inline**. Search Memory for the exact skill/friction first; apply a clear overcome and continue. If Memory has no answer, the overcome fails, or the friction repeats, spawn one doctrine fix chip (`greprag fix spawn --type doctrine "<skill friction unit>"`). Use `greprag fix log` only for deliberate audit/design notes. Do not invent edits outside these recipes.
 
 ## The two edit primitives (skill-optimize vocabulary)
 

package/skill/templates/os.md

@@ -52,11 +52,14 @@ project, repo, customer, handle, or unexplained proper noun, search memory for
 that entity before responding when prior context could affect the answer. Do
 not do this for generic nouns or for entities fully defined in the current turn.
 
-## Law 4 — Friction ⇒ fix spawn, at the moment
+For any env, toolchain, worktree, secret, tool, hook, command, correction, or
+repetition friction, search Memory for the exact error/friction plus repo/tool.
+If Memory has a clear overcome, apply it and continue.
 
-Friction — you repeated yourself, fought a tool, got corrected twice on the
-same thing, rediscovered something already known, hit a setup failure that
-wasn't your edit — is fixed at the MOMENT it happens:
+## Law 4 — Unresolved friction ⇒ fix spawn
+
+Escalate only when Memory has no answer, the remembered overcome fails, or the
+same friction repeats:
 
     greprag fix spawn --type <harness|doctrine|injection|env|code> "<one unit>"
 
@@ -66,9 +69,9 @@ wasn't your edit — is fixed at the MOMENT it happens:
   (Claude Code `spawn_task`, Codex `codex_app__create_thread`, opencode
   bootloader) and send the mission as its first message. Method:
   `greprag load chip-spawn`.
-- **One unit = one chip.** A fix chip exists for exactly one unit of
-  friction. Adjacent friction gets its own spawn — a chip that absorbs new
-  friction loses the context each unit needs.
+- **One unresolved unit = one chip.** A fix chip exists for exactly one unit of
+  unresolved friction. Adjacent friction gets its own spawn — a chip that
+  absorbs new friction loses the context each unit needs.
 - **Type = durable repair surface.** `harness` fixes hooks/watchers/task
   dispatch/harness behavior; `doctrine` fixes `greprag load`, bundled skills,
   and rendered AGENTS/CLAUDE instructions; `injection` fixes recap, Capture,
@@ -86,10 +89,10 @@ wasn't your edit — is fixed at the MOMENT it happens:
   the operator before touching code. Rarely can a chip design the durable
   repair alone; the gate is what keeps repairs durable instead of
   workarounds.
-- **Never queue friction for later.** The queue-first reflex (`fix log` →
-  periodic digestion) is retired; the moment that produced the friction
-  holds the context the fix needs. `greprag fix log` survives only for
-  audit trails and design-input notes that are deliberately not chips.
+- **Never queue unresolved friction for later.** The queue-first reflex
+  (`fix log` → periodic digestion) is retired; the live context belongs with
+  the fix chip. `greprag fix log` survives only for audit trails and
+  design-input notes that are deliberately not chips.
 - Every repair is ROOT-CAUSE: fix the pattern that makes the friction class
   possible, never a guard on today's trigger.
 
@@ -98,4 +101,4 @@ wasn't your edit — is fixed at the MOMENT it happens:
 If the operator explains the same thing twice, the explanation belongs in a
 durable surface — a skill, a load entry, a STATE block, an ADR — not in the
 conversation. Hand-taught doctrine that stays in chat dies with the session;
-that is itself friction (Law 4 applies).
+that is itself unresolved friction (Law 4 applies).

package/dist/codex-checkpoint-hook.js

@@ -1,184 +0,0 @@
-"use strict";
-/** Codex checkpoint coordination — detect a successful Git commit transition
- * and inject the delivery handoff at that exact lifecycle boundary.
- *
- * PreToolUse records the prior HEAD around shell-capable tools. PostToolUse
- * proves HEAD changed via a commit reflog action and emits immediately; the
- * next PreToolUse is a fallback if that lifecycle event was unavailable.
- * User prompt and executor-wrapper wording are irrelevant.
- * adr: adr/codex-checkpoint-coordination.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.checkpointCoordinationText = checkpointCoordinationText;
-exports.recordCodexGitBoundary = recordCodexGitBoundary;
-exports.evaluateCodexCommitResult = evaluateCodexCommitResult;
-exports.evaluatePendingCodexCheckpoint = evaluatePendingCodexCheckpoint;
-const crypto = __importStar(require("crypto"));
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
-function homeDir() {
-    return process.env.USERPROFILE || process.env.HOME || '';
-}
-function normalizedCwd(input) {
-    return path.resolve(input.cwd || process.cwd()).replace(/\\/g, '/').toLowerCase();
-}
-function statePath(input) {
-    const home = homeDir();
-    const session = (input.session_id || '').trim();
-    if (!home || !session)
-        return null;
-    const key = crypto.createHash('sha256')
-        .update(`${session}\0${normalizedCwd(input)}`)
-        .digest('hex')
-        .slice(0, 24);
-    return path.join(home, '.greprag', 'state', `codex-checkpoint-${key}.json`);
-}
-function git(cwd, args) {
-    try {
-        return (0, child_process_1.execFileSync)('git', args, {
-            cwd,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-            windowsHide: true,
-        }).trim() || null;
-    }
-    catch {
-        return null;
-    }
-}
-function currentHead(cwd) {
-    return git(cwd, ['rev-parse', 'HEAD']);
-}
-function currentBranch(cwd) {
-    return git(cwd, ['branch', '--show-current']) || '(detached HEAD)';
-}
-function latestHeadAction(cwd) {
-    return git(cwd, ['reflog', '-1', '--format=%gs', 'HEAD']) || '';
-}
-function isCommitHeadAction(cwd) {
-    return /^commit(?: \([^)]+\))?:/i.test(latestHeadAction(cwd));
-}
-function isShellCapableTool(input) {
-    const name = (input.tool_name || '').toLowerCase();
-    return /(?:^|[.:/_-])(bash|shell|exec|exec_command|write_stdin)$/.test(name);
-}
-function writePending(file, pending) {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(pending, null, 2) + '\n');
-}
-function readPending(file) {
-    try {
-        return JSON.parse(fs.readFileSync(file, 'utf8'));
-    }
-    catch {
-        return null;
-    }
-}
-function clearPending(file) {
-    try {
-        fs.unlinkSync(file);
-    }
-    catch { /* already absent */ }
-}
-function consumePending(input, hookEventName) {
-    const file = statePath(input);
-    if (!file)
-        return null;
-    const pending = readPending(file);
-    if (!pending || pending.cwd !== normalizedCwd(input))
-        return null;
-    clearPending(file);
-    const cwd = input.cwd || process.cwd();
-    const afterHead = currentHead(cwd);
-    if (!afterHead || afterHead === pending.beforeHead || !isCommitHeadAction(cwd))
-        return null;
-    return {
-        hookSpecificOutput: {
-            hookEventName,
-            additionalContext: checkpointCoordinationText(currentBranch(cwd), afterHead.slice(0, 12)),
-        },
-    };
-}
-function checkpointCoordinationText(branch, sha) {
-    return `[DELIVERY COORDINATION — CHECKPOINT CREATED]
-
-Checkpoint: ${branch} @ ${sha}
-
-Coordinate now, before merge, push, deploy, publish, or release.
-
-- Child task: send the LEAD your branch, SHA, checks, status, owned dirt, and blockers. The LEAD owns integration.
-- LEAD/standalone task: call codex_app.list_threads unfiltered, scope to this repo/worktree, exclude yourself, and ask every live peer for its latest checkpoint, owned dirt, blockers, and sequencing needs.
-- Elect exactly one delivery owner. If no peers exist, you are the owner.
-- Use greprag send for cross-harness peers.
-
-Do not begin a delivery action until coordination is settled.`;
-}
-/** PreToolUse leg: remember HEAD around any shell-capable action. The result
- * leg classifies the actual Git transition, so nested executor syntax and
- * dynamically composed commands do not matter. */
-function recordCodexGitBoundary(input) {
-    if (input.hook_event_name !== 'PreToolUse')
-        return;
-    if (!isShellCapableTool(input))
-        return;
-    const file = statePath(input);
-    if (!file)
-        return;
-    const cwd = input.cwd || process.cwd();
-    writePending(file, {
-        sessionId: input.session_id || '',
-        cwd: normalizedCwd(input),
-        toolName: input.tool_name || '',
-        beforeHead: currentHead(cwd),
-        recordedAt: new Date().toISOString(),
-    });
-}
-/** Preferred result leg: emit on the successful commit's own PostToolUse. */
-function evaluateCodexCommitResult(input) {
-    if (input.hook_event_name !== 'PostToolUse')
-        return null;
-    if (!isShellCapableTool(input))
-        return null;
-    return consumePending(input, 'PostToolUse');
-}
-/** Fallback result leg: if PostToolUse was unavailable, emit before the first
- * later tool call. Failed/empty commits leave HEAD unchanged and clear
- * silently. */
-function evaluatePendingCodexCheckpoint(input) {
-    if (input.hook_event_name !== 'PreToolUse')
-        return null;
-    return consumePending(input, 'PreToolUse');
-}