greprag 5.74.6 → 5.74.8

package/dist/codex-chip-hooks.js

@@ -64,9 +64,9 @@ function context(input) {
         `Worktree: ${(0, model_1.chipExecutionPath)(chip)}`,
         `Branch: ${chip.worktree.branch}`,
         `Parent session: ${chip.parent.sessionId || 'not recorded'}`,
-        `Finish by committing the durable result and reporting the commit artifact to the parent, including checks, caveats, and a Cleanup line naming archive/task, worktree, and branch actions. The optional host command is ${cli} codex chip report ${chip.id}.`,
+        `Finish by committing the durable result, then send the parent the commit artifact, checks, caveats, Cleanup line, and Archive: yes|no in the actual native task message. After delivery, Archive: yes means archive this child task yourself. The optional host command is ${cli} codex chip report ${chip.id}.`,
         // adr: adr/codex-landing-doctrine.md — one delivery owner, including FIX missions.
-        'Landing: the parent is the delivery owner for merge, archive, cleanup, and any profile-declared push/deploy/release — do not edit the parent checkout or independently cross those 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.',
+        '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.');

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
@@ -20,11 +21,12 @@ 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.
 Every role is an ordinary writable session; roles only orient the work. Native Codex chips commit their durable
-result, then reply to the LEAD in the native task thread with status, commit
-hash, checks, caveats, cleanup parameters, and archive clearance. Include a
-\`Cleanup:\` line naming archive/task, worktree, and branch actions. Use
-\`Clearance: safe to archive\` or \`Clearance: keep open because ...\`. The
-parent integrates, archives when safe, and cleans up the task. Peer review is a
-separate explicit review chip/session when needed. The
+result, then use the native task-message channel to send the LEAD status,
+commit hash, checks, caveats, cleanup parameters, and
+\`Archive: yes\` or \`Archive: no — <reason>\`. The archive decision must be in
+that sent message, not only the child's final response. After delivery,
+\`Archive: yes\` means the child archives its own task; the parent integrates
+the commit and handles post-merge branch bookkeeping. Peer review is a separate
+explicit review chip/session when needed. The
 \`greprag codex chip report\` command remains host bookkeeping for explicit
 CLI-managed chips, not mandatory native Codex completion ceremony.`;

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,25 +16,28 @@ 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 use the native Codex task-message tool to send the LEAD `DONE` or `BLOCKED`, commit hash if any, checks, material caveats, cleanup parameters, and `Archive: yes` or `Archive: no — <reason>`. Do not substitute a final response in your own task.'
         : '- 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.
-- 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.`;
+${reportInstruction}
+- Include a \`Cleanup:\` line naming the task, worktree, and branch actions. When done use \`Cleanup: child archives own task; Codex may prune managed worktree; parent may delete branch after merge\`; when anything must remain open use \`Cleanup: keep task/worktree/branch because ...\`.
+- Put the archive decision in the actual message sent to the LEAD: \`Archive: yes\` or \`Archive: no — <reason>\`. After that message is delivered, \`Archive: yes\` means call \`set_thread_archived\` for your own task; \`Archive: no\` means leave it open. Never make the parent perform routine child-task archival.
+- Landing: do not independently merge, push, deploy, or manually delete the worktree — the parent is the delivery owner and integrates the result, follows the repo profile, and deletes the branch after merge. 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.6",
+  "version": "5.74.8",
   "description": "GrepRAG — agent memory for Claude Code, Codex, and OpenCode.",
   "main": "dist/index.js",
   "bin": {

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

@@ -15,15 +15,18 @@ 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
-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
-`Clearance: keep open because ...`). The lead remains responsible for
-integrating, archiving, and cleanup.
+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 message: commit the durable result, then send the LEAD
+`DONE` or `BLOCKED`, commit hash if any, checks, caveats, cleanup parameters,
+and `Archive: yes` or `Archive: no — <reason>` in the actual sent message, not
+only the child's final response. After successful delivery, `Archive: yes`
+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.
 FIX landing (adr/codex-landing-doctrine.md): a mission whose first line
 begins `FIX:` (from `greprag fix spawn`) uses the handoff's detected

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,58 +55,45 @@ 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.
-
-```json
-{
-  "target": {
-    "type": "project",
-    "projectId": "<current-project-id>",
-    "environment": { "type": "worktree" }
-  },
-  "prompt": "<Block 1 + Task + Block 2>",
-  "model": "<selected chip role model>",
-  "thinking": "<selected chip role effort>"
-}
-```
-
-For a FIX handoff with `workspaceMode=local`, change only the environment:
+Call `codex_app__create_thread` once as a standalone tool call:
 
 ```json
 {
   "target": {
     "type": "project",
     "projectId": "<current-project-id>",
-    "environment": { "type": "local" }
+    "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>"
 }
 ```
 
-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.
+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.
 
-## 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. Then create the listed
@@ -137,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.
@@ -152,61 +133,55 @@ Paste this at the end of the child prompt.
 
 ```text
 ## Report when done
-Commit the durable result first. Then reply to the LEAD in the native Codex task
-thread with `DONE` or `BLOCKED`, commit hash if any, concise result, checks,
-caveats, cleanup parameters, and archive clearance.
+Commit the durable result first. Then use the native Codex task-message tool to
+send the LEAD `DONE` or `BLOCKED`, commit hash if any, concise result, checks,
+material caveats, cleanup parameters, and the archive decision. Do not
+substitute a final response in your own task: the lifecycle report must be the
+actual message sent to the LEAD.
 
 Include one cleanup line:
-`Cleanup: archive task; Codex may prune managed worktree; parent may delete branch after merge`
+`Cleanup: child archives own task; Codex may prune managed worktree; parent may delete branch after merge`
 or
-`Cleanup: archive task; local mode has no worktree or branch to prune`
+`Cleanup: child archives own task; local mode has no worktree or branch to prune`
 or
 `Cleanup: keep task/worktree/branch because ...`
 
-Include one clearance line:
-`Clearance: safe to archive`
+Include one archive line in that same sent message:
+`Archive: yes`
 or
-`Clearance: keep open because ...`
+`Archive: no — <reason>`
+
+After the message is delivered, `Archive: yes` means call
+`set_thread_archived` for your own task; `Archive: no` means leave it open. Do
+not make the parent perform routine child-task archival.
 
-In worktree mode, do not merge, push, deploy, or delete the worktree. In local
-mode, do not archive the task or perform unrelated project cleanup. The parent
-decides whether to archive and cleans up from the child's cleanup parameters.
-If review is needed, the parent spawns a fresh review chip/session with an
-explicit review brief.
+Do not merge, push, deploy, or manually delete the worktree. The parent
+integrates the commit and may delete the branch after merge; Codex owns managed
+worktree pruning. If review is needed, the parent creates a fresh review
+chip/session.
 ```
 
-## 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.
@@ -218,12 +193,13 @@ integration. The no-live-parent full-goal fallback owns those actions itself.
 
 ## Parent cleanup
 
-After the parent integrates/reviews and archives a completed worktree task, it
-may run:
+After integration, the parent may clear remaining GrepRAG manifest/branch
+bookkeeping with:
 
 ```bash
 greprag codex chip cleanup <id> --native-archived
 ```
 
-Codex owns the managed-worktree lifecycle. The child does not prune it.
-Local-mode FIX tasks have no worktree or branch to prune; archive the task only.
+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.