greprag 5.74.10 → 5.74.11

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/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);
@@ -2558,9 +2541,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.11",
   "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).