greprag 5.74.9 → 5.74.11

package/dist/codex-chip-hooks.js

@@ -69,7 +69,7 @@ function context(input) {
         'Landing: the parent is the delivery owner for merge, post-merge branch/manifest bookkeeping, and any profile-declared push/deploy/release; the child owns routine archival of its own task after the terminal message is delivered. Do not edit the parent checkout or independently cross delivery boundaries. A mission whose first line begins `FIX:` (emitted by `greprag fix spawn`) is writable in its isolated checkout/worktree and hands its verified checkpoint to that owner without a human approval gate. If no live parent exists and the chip carries the full-goal mission, it becomes delivery owner. `greprag fix spawn` only prints the mission; visible Codex task dispatch creates the isolated checkout/worktree.',
     ];
     if ((0, model_1.chipMissionKind)(chip) === 'fix') {
-        lines.push('Harness: Codex. Mission: visible native FIX chip with ordinary writable authority, not an internal subagent.', 'Scope: repair GrepRAG-owned harness surfaces in this checkout: load entries, skill templates, docs, hook context, CLI messages, and tests. Codex owns native task creation, worktrees, permissions, Git, and task lifecycle.', 'Own diagnosis, implementation, tests, commit, and parent report. Inspect Codex behavior only far enough to correct GrepRAG guidance or report a precise external blocker.', 'FIX peer handoff: if a peer offers to coordinate, integrate, rework, or take over a harness repair, hand off branch/commit, dirty files, checks, blockers, and caveats. Do not defend patch ownership; peers may take ownership within their assigned GrepRAG harness scope.', 'Visible delegation route: load `codex-chip-spawn` and create the child with `codex_app__create_thread` using the current project worktree target; load `chip-leader` for multi-chip seams. Never use `multi_agent_v1__spawn_agent` for a visible chip.');
+        lines.push('Harness: Codex. Mission: visible native FIX chip with ordinary writable authority, not a same-session helper.', 'Scope: repair GrepRAG-owned harness surfaces in this checkout: load entries, skill templates, docs, hook context, CLI messages, and tests. Codex owns native task creation, worktrees, permissions, Git, and task lifecycle.', 'Own diagnosis, implementation, tests, commit, and parent report. Inspect Codex behavior only far enough to correct GrepRAG guidance or report a precise external blocker.', 'FIX peer handoff: if a peer offers to coordinate, integrate, rework, or take over a harness repair, hand off branch/commit, dirty files, checks, blockers, and caveats. Do not defend patch ownership; peers may take ownership within their assigned GrepRAG harness scope.', 'Visible delegation route: load `codex-chip-spawn` and create the child with `codex_app__create_thread` using the current project worktree target; load `chip-leader` for multi-chip seams. Same-session helper tools never satisfy a visible-chip requirement.');
     }
     return output(input.hook_event_name || 'SessionStart', lines.join('\n'));
 }

package/dist/commands/codex-chip/help.js

@@ -15,8 +15,9 @@ exports.CODEX_CHIP_HELP = `greprag codex chip — Codex task orchestration
 
 Native Codex Desktop is the default: omit --runtime. Use --runtime cli only for
 the explicit headless fallback. Spawn prepares the Desktop create request and
-handoff with an isolated worktree and starting branch. The standalone CLI does
-not create the Desktop task itself. The active topology is an implicit LEAD for
+handoff with a Codex worktree environment plus
+\`startingState.branchName\`. The standalone CLI does not create the Desktop
+task itself. The active topology is an implicit LEAD for
 quick chips, an explicit LEAD for multi-chip orchestration, and Chip A/B/C with
 optional ADVISOR orientation. FIX missions are visible one-friction tasks from
 \`greprag fix spawn\`: they select \`chip.fix\` and load mechanic doctrine.

package/dist/commands/codex-chip/prompt.js

@@ -26,7 +26,8 @@ function chipPrompt(manifest, _cliCommand = 'greprag') {
 
 Setup — do this FIRST:
 ${mechanicSetup}${leaderSetup}- Stay in ${executionPath}. Applicable AGENTS instructions and the session-start recap are already in context; inspect the current repository state.
-- Bootstrap this checkout before build/test: if \`scripts/ensure-npm-deps.cjs\` exists, run \`node scripts/ensure-npm-deps.cjs\`; if \`scripts/worktree-bootstrap.cjs\` exists, run \`node scripts/worktree-bootstrap.cjs\`. Never link or junction \`node_modules\` to another checkout.
+- Bootstrap this checkout before build/test: if \`scripts/worktree-bootstrap.cjs\` exists, run \`node scripts/worktree-bootstrap.cjs\`; if only \`scripts/ensure-npm-deps.cjs\` exists, run \`node scripts/ensure-npm-deps.cjs\`. Never link or junction \`node_modules\` to another checkout.
+- When running build/test or other env-driven commands, use \`node scripts/codex-run.cjs -- <command ...>\` if that wrapper exists. It loads ignored env files from the main checkout; never copy or print secrets.
 - Do not create a second worktree. The selected workspace is fully writable; there are no leases, read-only mode, or GrepRAG goal gates.
 - The durable manifest is ${manifest.id}; it is task bookkeeping, not a scope or permission gate.
 ${startupInstruction}

package/dist/commands/codex-generated-cleanup.js

@@ -0,0 +1,170 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanupCodexGeneratedDist = cleanupCodexGeneratedDist;
+exports.runCodexCleanGenerated = runCodexCleanGenerated;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const proc_1 = require("../proc");
+function samePath(left, right) {
+    const l = path.resolve(left);
+    const r = path.resolve(right);
+    return process.platform === 'win32' ? l.toLowerCase() === r.toLowerCase() : l === r;
+}
+function isInside(parent, child) {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return !!relative && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+function gitRootFor(start) {
+    try {
+        return path.resolve(String((0, proc_1.safeExecFileSync)('git', ['-C', start, 'rev-parse', '--show-toplevel'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })).trim());
+    }
+    catch {
+        return null;
+    }
+}
+function assertDistLeaf(target) {
+    if (path.basename(target).toLowerCase() !== 'dist') {
+        throw new Error(`Refusing generated cleanup for non-dist path: ${target}`);
+    }
+}
+function assertNoRepoMetadata(target) {
+    if (fs.existsSync(path.join(target, '.git'))) {
+        throw new Error(`Refusing to remove a directory containing .git metadata: ${target}`);
+    }
+}
+function cleanupBound(target, opts) {
+    const cwd = path.resolve(opts.cwd || process.cwd());
+    if (opts.under) {
+        const bound = path.resolve(cwd, opts.under);
+        if (samePath(bound, target) || !isInside(bound, target)) {
+            throw new Error(`Refusing cleanup outside explicit --under bound: ${target}`);
+        }
+        return { bound, boundKind: 'explicit-under' };
+    }
+    const parent = path.dirname(target);
+    if (!fs.existsSync(parent)) {
+        throw new Error(`Refusing cleanup because parent directory does not exist: ${parent}`);
+    }
+    const gitStart = fs.existsSync(target) && fs.lstatSync(target).isDirectory() ? target : parent;
+    const gitRoot = gitRootFor(gitStart);
+    if (!gitRoot) {
+        throw new Error(`Refusing cleanup outside a Git worktree; pass --under <dir> for an explicit bound: ${target}`);
+    }
+    if (samePath(gitRoot, target) || !isInside(gitRoot, target)) {
+        throw new Error(`Refusing cleanup outside Git root ${gitRoot}: ${target}`);
+    }
+    return { bound: gitRoot, boundKind: 'git-root' };
+}
+function cleanupCodexGeneratedDist(targetArg, opts = {}) {
+    if (!targetArg || !targetArg.trim())
+        throw new Error('Missing generated directory path.');
+    const cwd = path.resolve(opts.cwd || process.cwd());
+    const target = path.resolve(cwd, targetArg);
+    assertDistLeaf(target);
+    const bound = cleanupBound(target, opts);
+    const dryRun = !!opts.dryRun;
+    if (!fs.existsSync(target)) {
+        return { target, ...bound, removed: false, dryRun, reason: 'missing' };
+    }
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Refusing to remove symlink/reparse target: ${target}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`Refusing to remove non-directory generated path: ${target}`);
+    }
+    assertNoRepoMetadata(target);
+    if (dryRun) {
+        return { target, ...bound, removed: false, dryRun, reason: 'dry-run' };
+    }
+    fs.rmSync(target, { recursive: true, force: false });
+    if (fs.existsSync(target))
+        throw new Error(`Cleanup did not remove target: ${target}`);
+    return { target, ...bound, removed: true, dryRun };
+}
+function parseArgs(args) {
+    let under;
+    let dryRun = false;
+    let json = false;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--under') {
+            under = args[++i];
+            if (!under)
+                throw new Error('Missing value for --under.');
+            continue;
+        }
+        if (arg.startsWith('--'))
+            throw new Error(`Unknown clean-generated flag: ${arg}`);
+        positional.push(arg);
+    }
+    if (positional.length !== 1) {
+        throw new Error('Usage: greprag codex clean-generated <path-to-dist> [--under <dir>] [--dry-run] [--json]');
+    }
+    return { target: positional[0], under, dryRun, json };
+}
+function runCodexCleanGenerated(args) {
+    const parsed = parseArgs(args);
+    const result = cleanupCodexGeneratedDist(parsed.target, {
+        under: parsed.under,
+        dryRun: parsed.dryRun,
+    });
+    if (parsed.json) {
+        console.log(JSON.stringify(result));
+        return;
+    }
+    const action = result.reason === 'missing'
+        ? 'already absent'
+        : result.reason === 'dry-run'
+            ? 'would remove'
+            : result.removed
+                ? 'removed'
+                : 'unchanged';
+    console.log(`Codex generated cleanup ${action}: ${result.target}`);
+    console.log(`Bound: ${result.boundKind} ${result.bound}`);
+}

package/dist/commands/codex-model-policy.js

@@ -36,7 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KNOWN_CODEX_MODEL_EFFORTS = exports.DEFAULT_CODEX_MODEL_POLICY = exports.CODEX_MODEL_EFFORTS = void 0;
 exports.loadCodexModelPolicy = loadCodexModelPolicy;
 exports.resolveChipModelSlot = resolveChipModelSlot;
-exports.resolveSubagentModelSlot = resolveSubagentModelSlot;
 exports.printCodexModelPolicy = printCodexModelPolicy;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
@@ -51,11 +50,6 @@ exports.DEFAULT_CODEX_MODEL_POLICY = {
         advisor: { model: 'gpt-5.6-sol', effort: 'high' },
         fix: { model: 'gpt-5.5', effort: 'high' },
     },
-    subagent: {
-        fast_scan: { model: 'gpt-5.5', effort: 'medium' },
-        routine_worker: { model: 'gpt-5.5', effort: 'high' },
-        deep_worker: { model: 'gpt-5.6-luna', effort: 'xhigh' },
-    },
 };
 exports.KNOWN_CODEX_MODEL_EFFORTS = {
     'gpt-5.6-sol': ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'],
@@ -90,11 +84,6 @@ function applyPolicy(base, patch, source) {
             throw new Error(`${source} has unknown chip model slot ${key}.`);
         base.chip[key] = applySlot(base.chip[key], chipPatch[key] || {}, `${source} chip.${key}`);
     }
-    for (const key of Object.keys(patch.subagent || {})) {
-        if (!(key in base.subagent))
-            throw new Error(`${source} has unknown subagent model slot ${key}.`);
-        base.subagent[key] = applySlot(base.subagent[key], patch.subagent[key] || {}, `${source} subagent.${key}`);
-    }
     return base;
 }
 function readPolicyFile(filePath) {
@@ -148,9 +137,6 @@ function loadCodexModelPolicy(cwd = process.cwd(), homeDir = process.env.HOME ||
 function resolveChipModelSlot(role, policy = loadCodexModelPolicy()) {
     return policy.chip[role];
 }
-function resolveSubagentModelSlot(role, policy = loadCodexModelPolicy()) {
-    return policy.subagent[role];
-}
 function printCodexModelPolicy(args = []) {
     const json = args.includes('--json');
     const policy = loadCodexModelPolicy();
@@ -160,6 +146,4 @@ function printCodexModelPolicy(args = []) {
     console.log('Config files: ~/.greprag/codex-models.json, then .greprag/codex-models.json');
     for (const [role, slot] of Object.entries(policy.chip))
         console.log(`  chip.${role}: ${slot.model} / ${slot.effort}`);
-    for (const [role, slot] of Object.entries(policy.subagent))
-        console.log(`  subagent.${role}: ${slot.model} / ${slot.effort}`);
 }

package/dist/commands/codex.js

@@ -53,6 +53,7 @@ const codex_app_server_1 = require("./codex-app-server");
 const codex_delivery_1 = require("./codex-delivery");
 const codex_model_policy_1 = require("./codex-model-policy");
 const codex_startup_1 = require("./codex-startup");
+const codex_generated_cleanup_1 = require("./codex-generated-cleanup");
 const codex_watch_health_1 = require("./codex-watch-health");
 var codex_startup_2 = require("./codex-startup");
 Object.defineProperty(exports, "codexStartupInfo", { enumerable: true, get: function () { return codex_startup_2.codexStartupInfo; } });
@@ -458,6 +459,7 @@ const HELP = `greprag codex — Codex-specific helpers.
   greprag codex models show [--json]
   greprag codex chip spawn "<task>" --name <name> [--role worker|leader|planner|advisor] [--runtime cli]
   greprag codex chip list|status|steer|stop|report|block|cleanup|reconcile
+  greprag codex clean-generated <path-to-dist> [--under <dir>] [--dry-run] [--json]
   greprag codex doctor
   greprag codex startup remove
 
@@ -518,6 +520,10 @@ async function runCodex(args) {
         await (0, command_1.runCodexChip)(args.slice(1));
         return;
     }
+    if (sub === 'clean-generated') {
+        (0, codex_generated_cleanup_1.runCodexCleanGenerated)(args.slice(1));
+        return;
+    }
     if (sub !== 'watch' && sub !== 'arm') {
         console.error(`Unknown codex command: ${sub}\n`);
         console.log(HELP);

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-primer-reminder.js

@@ -46,7 +46,7 @@ exports.OPENCODE_CHIP_SPAWN_POINTER = [
 /** POINTER — Codex Desktop's native chip path. This is intentionally distinct
  *  from Claude Code spawn_task: different lifecycle, runtime, and handoff. */
 exports.CODEX_CHIP_SPAWN_POINTER = [
-    '[greprag Codex delegation — internal subagent, 1–2-chip quick path with the initiator as LEAD, or a separate LEAD for larger/seamed missions.]',
+    '[greprag Codex delegation — 1–2-chip quick path with the initiator as LEAD, or a separate LEAD for larger/seamed missions.]',
     '• About to delegate a Codex task? → run `greprag load codex-chip-spawn` FIRST. Use exact first-line titles `LEAD: <Mission>`, `Chip A/B/C: <Specific Purview>`, and `FIX: [type] <one friction unit>`. Chips are ordinary writable native tasks; completion is a native Codex task reply to the LEAD after committing. A `FIX:` task loads `greprag load mechanic` first.',
 ].join('\n');
 exports.loadPrimerModule = {

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'],
@@ -73,10 +73,6 @@ const LIBRARY = {
         files: ['skill/templates/codex-chip-spawn.md'],
         purpose: 'Spawn an independent writable native Codex Desktop task with an isolated worktree and native completion/cleanup.',
     },
-    'codex-subagent-spawn': {
-        files: ['skill/templates/codex-subagent-spawn.md'],
-        purpose: 'Use bounded ephemeral Codex subagents inside the current session without a visible task, worktree, manifest, inbox identity, or goal.',
-    },
     'skill-change': {
         files: ['skill/templates/skill-change.md'],
         purpose: 'Internal bundled schema for safely updating a skill after a run: when to edit, Convention A/B shapes, and when to propose instead.',
@@ -432,7 +428,8 @@ async function runLoad(args) {
             return;
         console.error(`Unknown load entry: ${name}\n`);
         await printCatalog();
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     const bodies = [];
     for (const file of entry.files) {

package/dist/commands/mechanic-spawn.js

@@ -148,8 +148,9 @@ function buildFixMission(friction, scope, parentSession, type = inferFixType(fri
         '1. `greprag load mechanic`',
         ...workspace.setup,
         '4. Read AGENTS.md and the session-start recap, then inspect the current repository state.',
-        '5. Bootstrap this checkout before build/test: if `scripts/ensure-npm-deps.cjs` exists, run `node scripts/ensure-npm-deps.cjs`; if `scripts/worktree-bootstrap.cjs` exists, run `node scripts/worktree-bootstrap.cjs`. Never link or junction `node_modules` to another checkout.',
-        '6. Reproduce the friction before changing anything.',
+        '5. Bootstrap this checkout before build/test: if `scripts/worktree-bootstrap.cjs` exists, run `node scripts/worktree-bootstrap.cjs`; if only `scripts/ensure-npm-deps.cjs` exists, run `node scripts/ensure-npm-deps.cjs`. Never link or junction `node_modules` to another checkout.',
+        '6. When running build/test or other env-driven commands, use `node scripts/codex-run.cjs -- <command ...>` if that wrapper exists. It loads ignored env files from the main checkout; never copy or print secrets.',
+        '7. Reproduce the friction before changing anything.',
         '',
         '**Repair contract**',
         `- ${workspace.work}`,

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. 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) {