greprag 5.74.5 → 5.74.7

package/dist/commands/codex-chip/cleanup-command.js

@@ -34,10 +34,14 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pruneDependencyInstalls = pruneDependencyInstalls;
+exports.codexManagedWorktreeRoot = codexManagedWorktreeRoot;
+exports.cleanupCodexOrphanPath = cleanupCodexOrphanPath;
+exports.runCleanupOrphanCommand = runCleanupOrphanCommand;
 exports.runCleanupCommand = runCleanupCommand;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const proc_1 = require("../../proc");
 const git_1 = require("./git");
 const model_1 = require("./model");
 const store_1 = require("./store");
@@ -89,6 +93,80 @@ function pruneDependencyInstalls(checkout) {
         walk(root);
     return removed;
 }
+function codexManagedWorktreeRoot() {
+    return path.resolve(process.env.CODEX_HOME || path.join(process.env.HOME || process.env.USERPROFILE || os.homedir(), '.codex'), 'worktrees');
+}
+function assertUnderManagedRoot(target, safeRoot = codexManagedWorktreeRoot()) {
+    const root = path.resolve(safeRoot);
+    const resolved = path.resolve(target);
+    const relative = path.relative(root, resolved);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`Refusing cleanup outside the managed Codex worktree root: ${root}.`);
+    }
+    return resolved;
+}
+function gitCandidateDirs(root) {
+    const candidates = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        if (entries.some(entry => entry.name === '.git')) {
+            candidates.push(dir);
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            if (entry.name === 'node_modules')
+                continue;
+            walk(path.join(dir, entry.name));
+        }
+    };
+    if (fs.existsSync(root))
+        walk(root);
+    return candidates;
+}
+function isUsableGitCheckout(dir) {
+    try {
+        return (0, proc_1.safeExecFileSync)('git', ['-C', dir, 'rev-parse', '--is-inside-work-tree'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+function cleanupCodexOrphanPath(targetArg, opts = {}) {
+    if (!targetArg)
+        throw new Error('Orphan path is required.');
+    const target = assertUnderManagedRoot(targetArg);
+    if (!fs.existsSync(target))
+        return { target, removed: false, gitCandidates: [] };
+    const gitCandidates = gitCandidateDirs(target);
+    const usable = gitCandidates.filter(isUsableGitCheckout);
+    if (usable.length) {
+        throw new Error(`Refusing to remove a usable Git checkout under the orphan path: ${usable[0]}.`);
+    }
+    if (!opts.dryRun)
+        fs.rmSync(target, { recursive: true, force: true });
+    return { target, removed: !fs.existsSync(target), gitCandidates };
+}
+function runCleanupOrphanCommand(args) {
+    const target = args[0];
+    const result = cleanupCodexOrphanPath(target, { dryRun: args.includes('--dry-run'), json: args.includes('--json') });
+    if (args.includes('--json'))
+        return void console.log(JSON.stringify({
+            protocol: 'greprag-codex-orphan-cleanup-v1',
+            ...result,
+        }, null, 2));
+    console.log(`${result.removed ? 'removed' : 'not-found'}  ${result.target}`);
+}
 function runCleanupCommand(args) {
     const ref = args[0];
     if (!ref)
@@ -115,9 +193,7 @@ function runCleanupCommand(args) {
     }
     if (!manifest.worker?.settledAt && !force)
         throw new Error('Chip worker has not settled; wait or use --force for a dead stale worker.');
-    const safeRoot = native
-        ? path.resolve(process.env.CODEX_HOME || path.join(process.env.HOME || process.env.USERPROFILE || os.homedir(), '.codex'), 'worktrees')
-        : path.resolve((0, store_1.chipWorktreeRoot)(manifest.project.id));
+    const safeRoot = native ? codexManagedWorktreeRoot() : path.resolve((0, store_1.chipWorktreeRoot)(manifest.project.id));
     const target = path.resolve(native ? (0, model_1.chipExecutionPath)(manifest) : manifest.worktree.path);
     const relative = path.relative(safeRoot, target);
     if (!relative || relative.startsWith('..') || path.isAbsolute(relative))

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

@@ -491,6 +491,8 @@ async function runCodexChip(args) {
         return blockChip(rest);
     if (sub === 'cleanup')
         return (0, cleanup_command_1.runCleanupCommand)(rest);
+    if (sub === 'cleanup-orphan')
+        return (0, cleanup_command_1.runCleanupOrphanCommand)(rest);
     if (sub === 'reconcile')
         return reconcile();
     if (sub === 'list') {

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

@@ -8,6 +8,7 @@ exports.CODEX_CHIP_HELP = `greprag codex chip — Codex task orchestration
   greprag codex chip handoff <id|name> [--json]
   greprag codex chip verify-title <id|name> <attestation flags from handoff>
   greprag codex chip attach|status|stop|cleanup <id|name>
+  greprag codex chip cleanup-orphan <path-under-CODEX_HOME/worktrees> [--json]
   greprag codex chip report <id|name> --summary "<result>" [--check "<check>"]
   greprag codex chip block <id|name> --reason "<blocker>" | list | reconcile
   greprag codex chip resume <id|name> | list | reconcile

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

@@ -4,6 +4,7 @@ exports.chipPrompt = chipPrompt;
 const model_1 = require("./model");
 /** The short native handoff keeps the real assignment dominant. */
 function chipPrompt(manifest, _cliCommand = 'greprag') {
+    // adr: adr/codex-chip-lifecycle.md
     const executionPath = manifest.codex.runtime === 'native' && !manifest.codex.nativeCwd
         ? 'the Codex-provided isolated worktree for this task'
         : (0, model_1.chipExecutionPath)(manifest);
@@ -15,24 +16,27 @@ function chipPrompt(manifest, _cliCommand = 'greprag') {
         ? '- Create a native top-level mission goal with `create_goal`, then run `get_goal` and verify the active goal names this mission before any child fanout.\n'
         : '';
     const native = manifest.codex.runtime === 'native';
+    const startupInstruction = native
+        ? `- After setup and bootstrap succeed, reply to the LEAD in the native Codex task thread: \`IN-FLIGHT: ${(0, model_1.chipTitle)(manifest)} — setup complete; work started\`. If setup fails, reply \`BLOCKED\` with the exact failure instead.\n`
+        : '';
     const reportInstruction = native
-        ? '- Commit the completed durable result, including report-only artifacts, then reply to the LEAD in the native Codex task thread with status, commit hash, checks, caveats, cleanup parameters, and archive clearance.'
+        ? '- Commit the durable result, then reply to the LEAD in the native Codex task thread with `DONE` or `BLOCKED`, commit hash if any, checks, material caveats, cleanup parameters, and archive clearance.'
         : '- Commit the completed durable result, including report-only artifacts, then run `greprag codex chip report <id> --summary "<result>" --check "<check>"`. The report must carry the commit artifact back to the parent.';
     return `${(0, model_1.chipTitle)(manifest)}
 
 Setup — do this FIRST:
-${mechanicSetup}${leaderSetup}- Stay in ${executionPath}; read AGENTS instructions and the session-start recap, then inspect the current repository state.
+${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.
-- Do not create a second worktree. This isolated worktree is fully writable; there are no leases, read-only mode, or GrepRAG goal gates.
+- 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}
 
 Task:
 ${manifest.task}
 - Own repository discovery, design, implementation, and tests; do not wait for a parent-authored implementation plan.
-${reportInstruction}
 
 Report when done:
-- In your final response to the parent, include the commit hash, concise result, checks, and caveats.
+${reportInstruction}
 - Include a \`Cleanup:\` line naming the archive/task action, worktree action, and branch action. Use \`Cleanup: archive task; Codex may prune managed worktree; parent may delete branch after merge\` when done, or \`Cleanup: keep task/worktree/branch because ...\` when anything must remain open.
 - Include \`Clearance: safe to archive\` when no follow-up is needed, or \`Clearance: keep open because ...\` when the lead should not archive yet.
 - Landing: do not independently merge, push, deploy, or delete the worktree — the parent is the delivery owner and integrates the result, follows the repo profile, and cleans up the task. If this task begins \`FIX:\` (a fix-spawn mission), hand the verified checkpoint to that owner without a human approval gate. If no live parent exists and this task carries the full-goal mission, become delivery owner. \`greprag fix spawn\` only prints the mission; visible Codex task dispatch creates the isolated checkout/worktree.`;

package/package.json

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

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

@@ -15,10 +15,13 @@ commit. Preserve the Codex-provided worktree, committed result artifact, and
 parent cleanup. The child opening prompt starts with the exact visible title
 alone (`Chip A: <Specific Purview>`, `LEAD: <Mission>`, `PLANNER: <Mission>`,
 `ADVISOR: <Purview>`, or `FIX: [type] <one friction unit>`) and then carries Block 1
-setup, task body, and Block 2 report-back. It has no lease,
-read-only, mandatory nested-goal, or nonce/ACK requirement. Completion is the
-native Codex parent-child task reply: commit the durable result, then reply to
-the LEAD with `DONE` or `BLOCKED`, commit hash if any, checks, caveats, and
+setup, task body, and Block 2 report-back. After setup/bootstrap succeeds, the
+child sends the native parent-task reply
+`IN-FLIGHT: <exact title> — setup complete; work started`; setup failure sends
+`BLOCKED` with the exact failure. It has no lease, read-only, mandatory
+nested-goal, or nonce/ACK requirement. Completion is another native
+parent-child task reply: commit the durable result, then reply to the LEAD with
+`DONE` or `BLOCKED`, commit hash if any, checks, caveats, and
 cleanup parameters (`Cleanup: archive task; Codex may prune managed worktree;
 parent may delete branch after merge` or `Cleanup: keep task/worktree/branch
 because ...`) plus archive clearance (`Clearance: safe to archive` or

package/skill/templates/chip-leader.md

@@ -41,6 +41,15 @@ verifies the active goal names this mission before fanout. That native goal
 tracks the LEAD mission; it is not a GrepRAG lease, durable manifest, or child
 permission gate.
 
+LEAD is an orchestrator, not an implementation chip. After `create_goal` /
+`get_goal`, the LEAD's next required action is creating the listed
+`Chip A/B/C: <Specific Purview>` visible Codex tasks/worktrees. Before all
+required children exist, LEAD must not implement the phase, edit application,
+worker, or product source files, or treat Chip A/B/C as sections of its own work. If
+child creation fails, LEAD stops and reports `BLOCKED`; it must not continue
+solo. Allowed LEAD edits are mission/runtime docs, integration reconciliation
+after chip reports, and tiny mechanical conflict fixes during merge.
+
 ## Quick versus Leader
 
 - **Quick:** the current task renames itself `LEAD: <Mission>` and directly
@@ -87,7 +96,8 @@ ordering in the brief rather than relying on hidden coordination metadata.
    blocker, explicit LEAD decision request, or operator status request.
 4. In the dedicated LEAD, create the native top-level mission goal with
    `create_goal`, then verify it with `get_goal`.
-5. From the LEAD, spawn each `Chip A/B/C: <Specific Purview>` with its own
+5. Next, before any implementation edit, spawn each
+   `Chip A/B/C: <Specific Purview>` with its own
    visible worktree and the mission context it needs.
    A `FIX: [type] <one friction unit>` child must make `greprag load mechanic` its
    first Setup action before diagnosis or edits.

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

@@ -4,27 +4,17 @@ 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.
 
-## What the agent provides
-
-- `title:` exact first line, one of:
-  - `Chip A: <Specific Purview>`
-  - `Chip B: <Specific Purview>`
-  - `Chip C: <Specific Purview>`
-  - `LEAD: <Mission>`
-  - `PLANNER: <Mission>`
-  - `ADVISOR: <Purview>`
-  - `FIX: [harness|doctrine|injection|env|code] <one friction unit>`
-- `prompt:` Block 1 + task body + Block 2 below.
-- `target:` current project. Standard writable chips use
-  `environment: { "type": "worktree" }`. A FIX chip uses the
-  `workspaceMode` emitted by `greprag fix spawn`: `worktree` selects a
-  worktree; `local` selects `environment: { "type": "local" }`.
-- `model` / `thinking:` selected from the role slot:
-  - `Chip A/B/C` -> `chip.worker`
-  - `LEAD` -> `chip.leader`
-  - `PLANNER` -> `chip.planner`
-  - `ADVISOR` -> `chip.advisor`
-  - `FIX` -> `chip.fix`
+## 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
@@ -39,14 +29,16 @@ Codex Desktop defaults for a visible chip.
 - 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. No leases,
-read-only mode, GrepRAG goal gates, nonce ACK, or delivery-proof ceremony.
+`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
 
-For a FIX chip, run `greprag fix spawn` in the source project and read its
-top-level `workspaceMode`. This is capability detection, not a retry policy:
-never attempt a worktree first and fall back after it fails.
+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`.
@@ -54,7 +46,8 @@ never attempt a worktree first and fall back after it fails.
   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. The caller yields file writes until the FIX chip reports back.
+  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
@@ -62,61 +55,55 @@ never attempt a worktree first and fall back after it fails.
 
 ## Dispatch
 
-Call `codex_app__create_thread` as a standalone tool call. Never batch it with
-another spawn or subagent call.
+Call `codex_app__create_thread` once as a standalone tool call:
 
 ```json
 {
   "target": {
     "type": "project",
     "projectId": "<current-project-id>",
-    "environment": { "type": "worktree" }
+    "environment": { "type": "<worktree|local>" }
   },
   "prompt": "<Block 1 + Task + Block 2>",
-  "model": "<selected chip role model>",
-  "thinking": "<selected chip role effort>"
+  "model": "<selected role model>",
+  "thinking": "<selected role effort>"
 }
 ```
 
-For a FIX handoff with `workspaceMode=local`, change only the environment:
+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.
 
-```json
-{
-  "target": {
-    "type": "project",
-    "projectId": "<current-project-id>",
-    "environment": { "type": "local" }
-  },
-  "prompt": "<Block 1 + Task + Block 2>",
-  "model": "<selected chip role model>",
-  "thinking": "<selected chip role effort>"
-}
-```
-
-Once `create_thread` reports success, creation is complete. Do not call it
-again for the same mission. If it fails generically or the transport is
-ambiguous, recover first: `list_threads` for the expected title, then
-`read_thread` candidates. Retry only after that proves no matching child exists.
-
-## Block 1 - Setup
+## Block 1 - Setup and startup acknowledgement
 
 Paste this at the top of the child prompt after the title.
 
 ```text
 ## Setup - do this FIRST
-Honor the selected workspace. Standard chips and `workspaceMode=worktree` FIX
-chips stay in the Codex-provided isolated worktree. A `workspaceMode=local` FIX
-chip works directly in the project directory, never initializes Git or creates
-a worktree, and requires the caller to yield file writes until it reports back.
-Read AGENTS.md and the session-start recap, then inspect the current repo state.
+Stay in the 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.
+After setup and bootstrap succeed, reply to the LEAD in the native Codex task
+thread:
+`IN-FLIGHT: <exact title> — setup complete; work started`
+If setup fails, reply `BLOCKED` with the exact failure instead.
 If the exact first-line title is `LEAD: <Mission>`, create a native top-level
 mission goal with `create_goal`, then run `get_goal` and verify the active goal
-names this mission before any child fanout.
+names this mission before any child fanout. Then create the listed
+`Chip A/B/C: <Specific Purview>` visible Codex tasks/worktrees before any
+implementation edit. LEAD is an orchestrator, not an implementation chip: do
+not implement the phase, edit app/worker/product source files, or treat
+Chip A/B/C as sections of your own work before all required children exist. If
+child creation fails, stop and report `BLOCKED`; do not continue solo. Allowed
+LEAD edits are mission/runtime docs, integration reconciliation after chip
+reports, and tiny mechanical conflict fixes during merge.
 If the exact first-line title starts with `FIX:`, run
 `greprag load mechanic` before diagnosis or edits.
 If the exact first-line title is `ADVISOR: <Purview>`, report consultation to
@@ -130,10 +117,11 @@ Keep the actual work dominant:
 
 ```text
 ## Task
-Outcome: <desired observable result>
-Why: <one sentence; omit if obvious>
-Seams: <shared files/contracts/order, or none>
-Starting state / integration: <what this worktree starts from and who integrates>
+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.
@@ -168,38 +156,27 @@ If review is needed, the parent spawns a fresh review chip/session with an
 explicit review brief.
 ```
 
-## FIX chips
+## FIX contract
 
 For `FIX:` tasks, the mission printed by `greprag fix spawn` is the source of
-truth. `fix spawn` detects workspace capability and emits `workspaceMode`:
-usable Git history selects an isolated worktree; non-Git, unavailable Git, or
-no commit selects the project-local task path with serialized writes. Dispatch
-must honor that value without trying a worktree first.
-
-The FIX chip keeps the existing `FIX:` route and carries its type in the title,
+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. Repo writes use the selected workspace mode;
-data-only repair rows and diagnosis need no writable task. The chip identifies
-the exact friction, makes the smallest durable root-cause fix, explains the
-friction and fix in human terms, verifies and checkpoints it, then hands the
-commit/result to the parent delivery owner without a second human approval
-gate. With no live parent and a full-goal mission, it becomes delivery owner
-and follows the repo profile.
-Removal comes first: remove offending text, gates, controls, duplicated
-doctrine, and wrong boundaries before adding new guidance. Add prose or
-controls only when no removal action can solve the friction; never wrap bad
-doctrine in explanatory caveats when deleting the bad boundary fixes it.
-As a child, it does not independently land, archive, or clean up selected
-workspace state; the parent delivery owner does that immediately after
-integration. The no-live-parent full-goal fallback owns those actions itself.
+`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
 
-- Never retry `create_thread` blindly; recover with `list_threads` /
-  `read_thread` first.
+- 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.