greprag 5.74.8 → 5.74.10

package/dist/codex-checkpoint-hook.js

@@ -0,0 +1,184 @@
+"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');
+}

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/codex-fast-hook.js

@@ -65,9 +65,10 @@ async function main() {
     const subcommand = process.argv[2];
     if (subcommand !== 'codex-chip-hook'
         && subcommand !== 'codex-pretooluse'
+        && subcommand !== 'codex-posttooluse'
         && subcommand !== 'codex-notify'
         && subcommand !== 'codex-store') {
-        process.stderr.write('Usage: greprag-codex-hook <codex-chip-hook|codex-pretooluse|codex-notify|codex-store>\n');
+        process.stderr.write('Usage: greprag-codex-hook <codex-chip-hook|codex-pretooluse|codex-posttooluse|codex-notify|codex-store>\n');
         process.exit(1);
     }
     const input = await readInput();
@@ -81,6 +82,13 @@ async function main() {
         await runCodexNotify(input);
         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');
+        return;
+    }
     const { evaluateCodexChipHook } = await Promise.resolve().then(() => __importStar(require('./codex-chip-hooks')));
     const chipResult = evaluateCodexChipHook(input);
     if (subcommand === 'codex-chip-hook') {
@@ -89,6 +97,11 @@ 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 (!result?.hookSpecificOutput.permissionDecision && input.tool_name === 'Bash') {
         const { runSearchGuard } = await Promise.resolve().then(() => __importStar(require('./commands/search-guard')));
         result = mergeOutputs(result, runSearchGuard(input));

package/dist/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/coordinate-gate.js

@@ -38,6 +38,7 @@
  *  shared-state mutation actually happens. The eval is ready for a future Write
  *  adapter; only a new triggerFrom* + a `Write|Edit` matcher would be needed. */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasGitSubcommand = hasGitSubcommand;
 exports.classifyRiskyCommand = classifyRiskyCommand;
 exports.triggerFromPreToolUse = triggerFromPreToolUse;
 exports.buildCoordinateDirective = buildCoordinateDirective;
@@ -141,6 +142,30 @@ function classifyGit(tokens) {
         return { kind: 'push', label: 'git push' };
     return null;
 }
+/** True when any executable command segment invokes the requested Git
+ * subcommand, including `git -C <worktree> <subcommand>`. Exported so lifecycle
+ * hooks can key off agent-generated Git actions instead of user prompt words. */
+function hasGitSubcommand(command, expected) {
+    if (!command || !expected)
+        return false;
+    for (const seg of commandSegments(command)) {
+        const tokens = shellWords(seg);
+        if (tokens[0] !== 'git')
+            continue;
+        let i = 1;
+        const optionsWithValue = new Set([
+            '-C', '-c', '--exec-path', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env',
+        ]);
+        while (i < tokens.length && tokens[i].startsWith('-')) {
+            const option = tokens[i++];
+            if (optionsWithValue.has(option) && i < tokens.length)
+                i++;
+        }
+        if (tokens[i] === expected)
+            return true;
+    }
+    return false;
+}
 /** Classify a Bash command into a risky-action trigger, or null. PURE. Matches
  *  the FIRST risky segment (a chained command fires on whichever risky verb
  *  appears first). */

package/dist/commands/init.js

@@ -636,9 +636,9 @@ async function runCodexInit(opts) {
     }
     console.log(`\n  Codex hooks file: ${hooksPath}`);
     console.log(`  Project anchor: ${anchor.anchorPath}`);
-    console.log('  Start a fresh Codex session, then open Settings -> Settings -> Hooks and trust the GrepRAG hook definitions.');
+    console.log('  Open Settings -> Settings -> Hooks and trust the GrepRAG hook definitions, then fully restart Codex Desktop.');
     console.log('  Inbox messages for Codex surface on SessionStart and UserPromptSubmit hook boundaries.');
-    console.log('  Memory hooks will activate on your next Codex session.\n');
+    console.log('  Hooks will activate after the Codex host restart; starting only a new task is not sufficient after hook changes.\n');
 }
 /** greprag init --global
  *  Creates ~/.greprag/project.json with a stable UUID.
@@ -1130,6 +1130,19 @@ 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 permissionHook = {
         matcher: '',
         hooks: [commandHook('codex-permission-context', 3, 'Loading GrepRAG approval context')],

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

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

@@ -24,7 +24,7 @@ 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.',
+        '• 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.`,
         '• 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/opencode-plugin.bundle.js

@@ -1752,7 +1752,7 @@ 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. Named person/org/project/repo/customer/handle or unexplained proper noun \u2192 search Memory before guessing, unless fully defined in-turn.",
+    "\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 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");
@@ -1827,7 +1827,7 @@ var OPENCODE_CHIP_SPAWN_POINTER = [
   "\u2022 Delegating a component of a plan to an isolated chip session, or `greprag fix spawn` just printed a FIX-chip mission? \u2192 run `greprag load chip-bootloader` FIRST for the method: OpenCode chips spawn natively via `greprag opencode chip goal create` + `greprag opencode chip spawn` (HTTP child session; manual paste only when the API is down). \u22652 chips at one objective \u2192 `greprag load chip-leader-opencode` BEFORE the first spawn."
 ].join("\n");
 var CODEX_CHIP_SPAWN_POINTER = [
-  "[greprag Codex delegation \u2014 internal subagent, 1\u20132-chip quick path with the initiator as LEAD, or a separate LEAD for larger/seamed missions.]",
+  "[greprag Codex delegation \u2014 1\u20132-chip quick path with the initiator as LEAD, or a separate LEAD for larger/seamed missions.]",
   "\u2022 About to delegate a Codex task? \u2192 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");
 var loadPrimerModule = {

package/package.json

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

package/skill/greprag/SKILL.md

@@ -148,6 +148,8 @@ Aliases (silent back-compat): `greprag memory briefing` → `recap` (renamed v5.
 
 **Codex/Windows: ABOUT TO VALIDATE WITH NONTRIVIAL `node -e` JAVASCRIPT? STOP — write the code to a temporary `.cjs` file and run `node <file>`.** PowerShell parses the command before Node sees it; regex lookarounds, `$1`, pipes, nested quotes, and semicolons can be split or expanded before Node runs. Keep `node -e` only for tiny quote-free probes.
 
+**Codex/Windows: ABOUT TO CLEAN A GENERATED `dist` DIRECTORY? STOP — run `greprag codex clean-generated <path-to-dist>` instead of inline `Remove-Item -Recurse`.** Codex's native command launcher can reject free-form recursive delete text before PowerShell executes your path checks; the GrepRAG command resolves the `dist` path, requires a Git-root or explicit `--under` bound, rejects symlink/repo-metadata targets, and removes only that checked generated directory.
+
 **Codex messaging has one simple contract.** Discover Codex tasks with `codex_app.list_threads` unfiltered first, scope by cwd, then coordinate Codex-to-Codex with `codex_app.send_message_to_thread`; `query` may narrow only after cwd scoping. `greprag send` is the durable cross-harness inbox rail and fallback queue; it does not by itself prove that an idle Codex task woke or acted. Public installs use `greprag init --codex --tenant-id <handle>` and Codex hooks surface queued inbox rows at SessionStart/UserPromptSubmit boundaries. There is no Codex startup watcher to install. A stored row, completed user-only turn, app-server `turn/start` / `turn/steer`, or `codex exec resume` is not proof of agent action. Only the recipient's actual peer response proves delivery.
 
 **ABOUT TO `greprag send` TO A `@gmail.com` / `@anthropic.com` / REAL EMAIL ADDRESS? STOP — for `inbox`/`send` (internal cross-session messaging), `users.email` IS NEVER A ROUTING ADDRESS.** Use the numeric handle (`1834729@greprag.com`) or claimed vanity alias (`travis@greprag.com`). If you don't know the recipient's handle, ASK — don't guess from their email. adr: adr/numeric-handles.md. Full grammar: `docs/inbox.md § address`.
@@ -158,7 +160,7 @@ Aliases (silent back-compat): `greprag memory briefing` → `recap` (renamed v5.
 
 - `docs/setup.md` — codex · claude-code · opencode · auth · hooks · conventions · permissions · channels · anchor · bulk-register
 - `docs/platforms.md` — exact platform paths for Claude Code · Codex · OpenCode
-- `docs/codex-chip.md` — Codex subagent, quick-chip, Leader, reporting, and cleanup shape
+- `docs/codex-chip.md` — Codex quick-chip, Leader, reporting, and cleanup shape
 - `docs/per-project-flags.md` — flip `memory_capture` / `session_start_recap` / `inbox_notify`
 - `docs/inbox.md` — `greprag send`, `greprag inbox`, address grammar, retract (internal messaging)
 - `docs/email.md` — `greprag email send`/`pending`/`pull`/`boxes`/`domain` — REAL SMTP: send-as custom domains, segregated mailboxes (distinct from `send`)

package/skill/greprag/docs/codex-chip.md

@@ -2,14 +2,18 @@
 
 Use `greprag load codex-chip-spawn` for the Codex block recipe:
 
-- internal same-session subagent (`max_threads=6`, `max_depth=1`; no separate
-  worktree, manifest, inbox, or goal) uses `greprag load codex-subagent-spawn`;
 - quick mode: rename the current task `LEAD: <Mission>` and directly spawn
   1–2 visible `Chip A/B: <Specific Purview>` worktree tasks;
 - Leader mode: rename the current task `PLANNER: <Mission>`, then create a
   separate `LEAD: <Mission>` task before that LEAD spawns
   `Chip A/B/C: <Specific Purview>` children for seams or larger orchestration.
 
+Same-session subagents are native Codex behavior, not GrepRAG chip doctrine.
+Create visible chips with native `codex_app__create_thread`: `target.type =
+project`, the current `projectId`, a Codex `worktree` environment with
+`startingState: { type: "branch", branchName: "<prepared chip branch>" }`,
+plus top-level `model` and `thinking` from `greprag codex models show`.
+
 Normal chips are writable and own discovery, design, implementation, tests, and
 commit. Preserve the Codex-provided worktree, committed result artifact, and
 parent cleanup. The child opening prompt starts with the exact visible title
@@ -28,6 +32,10 @@ means the child archives its own Codex task; `Archive: no` leaves it open. The
 lead remains responsible for integration and post-merge branch bookkeeping,
 not routine child-task archival.
 Review is a separate explicit review chip/session when the lead asks for it.
+If the repo ships `scripts/codex-run.cjs`, children use
+`node scripts/codex-run.cjs -- <command ...>` for build/test/env-driven
+commands so ignored `.env`, `.env.local`, `.dev.vars`, and package-level env
+files are read from the main checkout without copying or printing secrets.
 FIX landing (adr/codex-landing-doctrine.md): a mission whose first line
 begins `FIX:` (from `greprag fix spawn`) uses the handoff's detected
 `workspaceMode`. Usable Git history selects an isolated worktree; non-Git,

package/skill/mechanic/SKILL.md

@@ -97,8 +97,8 @@ the Codex-provided checkout: bundled load entries, skill templates, docs, hook
 context, CLI messages, and tests that teach agents how to use the harness.
 Inspect Codex behavior only far enough to correct those GrepRAG surfaces or to
 report a precise external blocker. Codex owns native task creation, worktrees,
-permissions, Git, and task lifecycle. Do not create another child or use an
-internal subagent unless the parent explicitly changes that assignment.
+permissions, Git, and task lifecycle. Do not create another child unless the
+parent explicitly changes that assignment.
 Landing (adr/codex-landing-doctrine.md): a `MECHANIC: <Mission>` or
 `FIX: <friction>` chip replies to its LEAD with the commit, exact friction,
 change, reason, checks, and cleanup parameters. The LEAD is the delivery owner
@@ -113,8 +113,7 @@ project worktree or local target. For 1–2 children the current
 task is the implicit LEAD; for more than two children or shared seams, load
 `chip-leader` and create a separate `LEAD: <Mission>` that dispatches exact
 `Chip A/B/C: <Specific Purview>` tasks.
-`multi_agent_v1__spawn_agent` is only an ephemeral same-session subagent and
-never satisfies a visible-chip requirement.
+Native same-session helpers never satisfy a visible-chip requirement.
 
 ABOUT TO answer a Mechanic peer who offers to coordinate, integrate, rework, or
 take over a harness repair? STOP — hand off the repair state: commit/branch,

package/skill/templates/codex-chip-spawn.md

@@ -1,95 +1,102 @@
 # Codex Chip Spawn Method
 
-Use this for Codex visible child tasks. Claude-side `spawn_task` rules do not
-apply to Codex: Codex creates the task, selects its workspace, and provides the
-native parent-child reply channel.
-
-## Roles and models
-
-The exact first-line title selects the governance and model slot:
-
-| Title | Purpose | Model slot |
-| --- | --- | --- |
-| `Chip A/B/C: <Specific Purview>` | Independent implementation worker | `chip.worker` |
-| `LEAD: <Mission>` | Own and integrate a multi-chip mission | `chip.leader` |
-| `PLANNER: <Mission>` | Create and brief a separate LEAD | `chip.planner` |
-| `ADVISOR: <Purview>` | Read-only consultation to the LEAD | `chip.advisor` |
-| `FIX: [harness\|doctrine\|injection\|env\|code] <one friction unit>` | Root-cause repair | `chip.fix` |
-
-Check active slots with `greprag codex models show`. Pass the selected slot as
-top-level `model` and `thinking` in `codex_app__create_thread`; do not rely on
-Codex Desktop defaults for a visible chip.
-
-## Mode selection
-
-- 1-2 visible tasks: rename the current task `LEAD: <Mission>` and
-  spawn `Chip A` / `Chip B` directly.
-- More chips or shared seams: rename the current task `PLANNER: <Mission>`,
-  create a separate `LEAD: <Mission>` first, then that LEAD spawns children.
-- Bounded same-session work: use `greprag load codex-subagent-spawn` instead.
-
-A dedicated `LEAD: <Mission>` creates a native top-level goal with
-`create_goal`, verifies it with `get_goal`, then fans out children. PLANNER is
-a handoff role: after briefing the LEAD it goes quiet until completion,
-blocker, explicit decision request, or operator intervention.
-
-## Workspace selection and project preflight
-
-Standard writable chips use the current project with
-`environment: { "type": "worktree" }`. For a FIX chip, run
-`greprag fix spawn` in the source project and honor its top-level
-`workspaceMode` without a fail-then-fallback attempt:
-
-- `workspaceMode=worktree`: use the project worktree target. Before the call,
-  check the saved project/main repo for `.codex/environments/environment.toml`.
-  If missing, stop and set up the repo first with the `codex-environments`
-  skill.
-- `workspaceMode=local`: use the project local target. The source has no usable
-  Git HEAD, so do not initialize Git, invoke `codex-environments`, or request a
-  worktree. This is the project-local task path with serialized writes: the
-  caller yields file writes until the FIX chip reports back.
-- Non-FIX writable chips remain worktree-only.
-- Missing for `PLANNER` or `ADVISOR` consultation: local/projectless fallback
-  is allowed only when the prompt explicitly forbids writes and no child
-  worktree dispatch happens until the repo environment exists.
-
-## Dispatch
-
-Call `codex_app__create_thread` once as a standalone tool call:
+Codex has no Claude Code `pre-spawn-check` validator over `spawn_task`. The
+agent writes the exact first-line title + Block 1 + task body + Block 2 into
+the prompt itself, then dispatches exactly once with
+`codex_app__create_thread`. Codex task creation proves dispatch only; the
+child's native `IN-FLIGHT` reply proves launch/setup.
+
+> **Part of a multi-chip mission?** If this chip is one of ≥2 aimed at a
+> single objective, you should already be inside a chip-leader plan — your
+> **base branch** and **merge target** (the integration branch, *never* master)
+> come from it. If you're not, stop and run `greprag load chip-leader` first.
+> A lone chip targeting its own objective proceeds here directly.
+
+## What the agent provides
+
+- `title: "Chip A: <verb-phrase>"` — exact first prompt line. Use the
+  leader-assigned label (`A`/`B`/`C`...) per workstream, for example
+  `"Chip B: Build freshness engine"`. The label is the shared handle the
+  leader and chip both use end-to-end (title -> report-back self-ID -> merge
+  references). Dedicated orchestration titles are exact too: `PLANNER:
+  <Mission>`, `LEAD: <Mission>`, `ADVISOR: <Purview>`, and `FIX:
+  [type] <one friction unit>`.
+- `prompt:` — exact title line + Block 1 + task body + Block 2 (templates
+  below).
+- The first-line title also selects the model slot:
+  `Chip A/B/C` -> `chip.worker`, `LEAD` -> `chip.leader`, `PLANNER` ->
+  `chip.planner`, `ADVISOR` -> `chip.advisor`, `FIX` -> `chip.fix`.
+- `target:` — Codex project target. Writable worktree chips must include the
+  prepared branch as `startingState`; this is the required Codex parameter
+  Claude does not have:
 
 ```json
 {
   "target": {
     "type": "project",
     "projectId": "<current-project-id>",
-    "environment": { "type": "<worktree|local>" }
+    "environment": {
+      "type": "worktree",
+      "startingState": { "type": "branch", "branchName": "<prepared chip branch>" }
+    }
   },
-  "prompt": "<Block 1 + Task + Block 2>",
+  "prompt": "<exact title + Block 1 + Task + Block 2>",
   "model": "<selected role model>",
   "thinking": "<selected role effort>"
 }
 ```
 
-Creation success proves dispatch, not successful startup. If the result is
-ambiguous, do not retry blindly: use `list_threads` for the expected title,
-inspect candidates with `read_thread`, and retry only after proving no matching
-task exists.
+- `model:` / `thinking:` — select with `greprag codex models show`; pass them
+  top-level in `codex_app__create_thread`, not by relying on Desktop defaults.
 
-## Block 1 - Setup and startup acknowledgement
+`workspaceMode=local` FIX tasks keep the same required Codex shape but use the
+project-local environment and omit `startingState`:
 
-Paste this at the top of the child prompt after the title.
+```json
+{
+  "target": {
+    "type": "project",
+    "projectId": "<current-project-id>",
+    "environment": { "type": "local" }
+  },
+  "prompt": "<exact title + Block 1 + Task + Block 2>",
+  "model": "<selected role model>",
+  "thinking": "<selected role effort>"
+}
+```
+
+Codex has no `mode: interactive` create-thread field. If the chip must pause
+for human input, put that requirement in the task body and make the child
+report `BLOCKED` with the decision needed.
+
+## Block 1 — Setup (verbatim, substitute `<exact-title>`, `<branch>` + mode)
+
+`<exact-title>` = the first prompt line. `<branch>` = the prepared chip branch
+used in `startingState.branchName`. `workspaceMode` comes from the dispatch
+path; standard chips and `workspaceMode=worktree` FIX chips are already in a
+Codex worktree environment.
+
+````
+**Setup — do this FIRST:**
 
 ```text
 ## Setup - do this FIRST
-Stay in the selected workspace and inspect the current repository state.
+Stay in the Codex-provided selected workspace and inspect the current
+repository state.
 Applicable AGENTS.md instructions and the session-start recap are already in
-context. Do not create another worktree; a `workspaceMode=local` FIX stays in
-the project directory and never initializes Git.
-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.
+context.
+Do not create another worktree. Standard chips and `workspaceMode=worktree`
+FIX chips are already in the Codex worktree environment created from
+`startingState.branchName`. A `workspaceMode=local` FIX stays in the project
+directory, never initializes Git, never requests a worktree, and requires the
+caller to yield file writes until the FIX chip reports back.
+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.
 After setup and bootstrap succeed, reply to the LEAD in the native Codex task
 thread:
 `IN-FLIGHT: <exact title> — setup complete; work started`
@@ -111,25 +118,36 @@ the LEAD only: findings, questions, tradeoffs, and recommendations. Do not
 write operator-facing completion language or decide/spawn worker chips.
 ```
 
-## Task body
+The `IN-FLIGHT` reply is non-negotiable — without it the parent assumes the
+Codex task exists but was not successfully launched.
 
-Keep the actual work dominant:
+---
+````
+
+**Multi-chip mission (`greprag load chip-leader`)?** The first-line title alone
+is not enough because Codex can auto-title before the child is renamed. The
+parent or LEAD must set the exact registry/task title immediately after the
+task appears, then read it back twice before treating the title as durable:
 
 ```text
-## Task
-Outcome: <observable result>
-Problem and evidence: <failure, request, or proof motivating the work>
-Relevant files/contracts: <starting points; child still owns discovery>
-Constraints and prior decisions: <invariants that must survive>
-Seams and integration order: <shared contracts/order, or none>
-Acceptance: <checks/evidence that mean done>
-Own repository discovery, design, implementation, tests, and commit; do not
-wait for a parent-authored implementation plan.
+set_thread_title "<exact-title>"
+read_thread -> exact title
+read_thread -> exact title again after the retry delay
 ```
 
-## Block 2 - Report back
+The leader dictates the exact string (for example `Chip A: Converter format
+coverage`). Single chips still use the exact title, but skip leader-assigned
+registry retitle planning.
+
+## Block 2 — Report back (verbatim, substitute `<branch>` + LEAD task)
 
-Paste this at the end of the child prompt.
+Use the native Codex parent-child task-message channel for Codex-to-Codex
+completion. Do not substitute `greprag send` for normal Codex child reports.
+
+````
+---
+
+**Block 2 — Report back via native Codex task reply:**
 
 ```text
 ## Report when done
@@ -161,45 +179,72 @@ worktree pruning. If review is needed, the parent creates a fresh review
 chip/session.
 ```
 
-## FIX contract
-
-For `FIX:` tasks, the mission printed by `greprag fix spawn` is the source of
-truth. The FIX chip keeps the existing route and carries its type in the title,
-for example `FIX: [doctrine] stale skill text sent Codex to Claude rules`.
-Type means durable repair surface: `harness` hooks/watchers/task dispatch,
-`doctrine` load entries/skills/rendered instructions, `injection`
-recap/Capture/doc-pointer/stateful injection, `env` bootstrap/deps/scripts, and
-`code` product/source behavior. It identifies the exact friction, makes the
-smallest durable root-cause fix, explains why it works, verifies and commits
-it, then hands it to the parent delivery owner.
-
-Removal comes first: remove offending doctrine, gates, controls, duplication,
-or wrong boundaries before adding guidance. Add prose or controls only when
-removal cannot solve the friction. Data-only repair rows and diagnosis do not
-require a writable task.
-
-## After spawning
-
-- Wait for the child-confirmed native `IN-FLIGHT` reply; task creation alone
-  does not prove setup/bootstrap succeeded.
-- In `workspaceMode=local`, yield parent file writes until the FIX chip reports
-  back; both tasks share the same project directory.
-- Use native Codex parent-child task replies for Codex-to-Codex reporting.
-- Use `greprag send` only for explicit cross-harness or fallback coordination.
-- Contact same-project Codex peers through `codex_app.list_threads` scoped by
-  `cwd`, then `codex_app.send_message_to_thread`. Coordination asks only about
-  blockers, owned dirt, or sequencing constraints; peer review is a separate
-  child task.
-
-## Parent cleanup
-
-After integration, the parent may clear remaining GrepRAG manifest/branch
-bookkeeping with:
+**Cleanup discipline (HARD RULE):** chip prompts forbid `git clean`,
+`git reset --hard`, `git checkout <other>`, raw recursive delete outside the
+selected workspace, manual worktree deletion, or manual Codex managed-checkout
+pruning.
+````
+
+## After spawning — wait for native IN-FLIGHT (HARD RULE)
+
+The chip reports back to the LEAD through native Codex task replies. Nothing
+else proves it launched correctly: `create_thread` success proves only that
+Codex accepted the dispatch. So immediately after `codex_app__create_thread`
+returns, resolve the visible task, set the exact title, read it back twice, and
+wait for:
+
+```text
+IN-FLIGHT: <exact-title> — setup complete; work started
+```
+
+If `create_thread` returns a generic/transport failure, treat it as ambiguous
+success. Do not call `create_thread` again until recovery checks prove no
+existing task exists: use `list_threads` for the expected title or manifest id,
+inspect candidates with `read_thread`, and recover a matching visible task
+before retrying.
+
+Use native Codex task replies for Codex-to-Codex reporting. Use `greprag send`
+only for explicit cross-harness or fallback coordination; a stored GrepRAG row
+is not proof that an idle Codex task woke or acted.
+
+**Launch state:** the Block 1 `IN-FLIGHT` reply is your only signal the child
+actually entered its selected workspace and completed setup. No `IN-FLIGHT` =
+assume the task is not launched, blocked, or not yet set up — don't wait on
+results from a chip that never started.
+
+## Before composing
+
+`greprag fix list --repaired --scope chip-startup --limit 20 --project <chip-project> --format markdown` — already scoped, no slicing. If non-empty, paste at top of body as `**Project Fixes (do not re-discover):**`. Do not use `fix search` for this pull.
+
+## Merge before testing globally (HARD RULE)
+
+Chips never `npm link` from the worktree — dangling symlinks silently break the
+CLI everywhere. To test a built CLI globally: merge through the repo delivery
+path first, then install from the main checkout.
+
+## Parent merge discipline — cleanup after integration (HARD RULE)
+
+When you (the parent) integrate a Codex chip branch — through the canonical
+commit path or a profile-declared merge — clear the Codex chip bookkeeping in
+the same breath after the child's `Archive: yes` report and merge:
 
 ```bash
 greprag codex chip cleanup <id> --native-archived
 ```
 
 The child archives its own task after sending `Archive: yes`; the parent does
-not perform routine child-task archival. Codex owns managed-worktree pruning.
-Local-mode FIX tasks have no worktree or branch to prune.
+not perform routine child-task archival. The parent may delete the branch after
+merge. Codex owns managed-worktree pruning, and the cleanup command records the
+archive-safe attestation before removing managed checkout state. Local-mode FIX
+tasks have no worktree or branch to prune.
+
+**FIX chips use the same delivery owner.** A `greprag fix spawn` mission is the
+source of truth for FIX behavior. `fix spawn` detects usable Git history and
+emits `workspaceMode`: Git uses an isolated worktree; non-Git, unavailable
+Git, or no commit uses the project-local task with serialized writes. Dispatch
+honors that mode without trying a worktree first. The FIX chip identifies the
+exact friction, makes the smallest durable root-cause fix, verifies and
+checkpoints it, then reports the commit/result and cleanup parameters to the
+parent delivery owner. It creates no human landing gate. If no live parent
+exists and the chip carries the full-goal mission, it becomes delivery owner
+and follows the repo profile.

package/skill/templates/codex-subagent-spawn.md

@@ -1,34 +0,0 @@
-# Codex Internal Subagent
-
-Use an internal subagent for ephemeral, same-session work: a bounded research
-pass, comparison, review, edit, or test whose result can return directly to the
-current task.
-
-## Contract
-
-- Load this method with `greprag load codex-subagent-spawn` when the shape is
-  not already in context.
-- The subagent is ephemeral and same-session. It has no visible worktree task,
-  durable manifest, inbox identity, or goal.
-- Keep concurrency at `max_threads=6` and recursion at `max_depth=1`.
-- Give it one specific question or purview and ask for a compact result with
-  evidence. `fast_scan` is read-only; `routine_worker` and `deep_worker` may
-  perform bounded edits/tests in the parent workspace.
-- Use the configured model slots: `subagent.fast_scan`, `subagent.routine_worker`,
-  and `subagent.deep_worker`. Inspect them with `greprag codex models show`.
-- The parent prevents overlapping concurrent edits and owns the final judgment,
-  integration, and any commit that should outlive the session.
-- Do not use it for independent worktree isolation, parent-visible lifecycle
-  reporting, or work that must outlive the session; choose a quick chip instead.
-
-## Compact brief
-
-```text
-Subagent purview: <one bounded question>
-Context: <the files or facts it may inspect>
-Return: <decision / findings / recommended next step>
-```
-
-Internal subagents do not need `greprag send`; their result is returned to the
-initiating task. If you need a visible child identity, report, or cleanup
-boundary, stop using this primitive and load `codex-chip-spawn`.