greprag 5.56.0 → 5.58.0

package/skill/greprag/SKILL.md

@@ -13,10 +13,11 @@ description: |
   memory", "memory recap", "memory search", "Odyssey briefing", "catch me
   up", "what did we do last week", "what's been happening in this
   project", "find that bug we hit", "search memory for X", "session
-  context".
+  context", "Codex chip", "chip spawn", "spawn a Codex task", "parallel
+  Codex work", "isolated Codex session", or "repo collisions".
 metadata:
   author: travsteward
-  version: "3.9.0"
+  version: "3.10.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
@@ -30,6 +31,8 @@ Platform setup is progressive:
 - **Claude Code**: see `docs/setup.md § claude-code` for the default hook/Monitor/conventions path (`greprag init --claude` or detected `greprag init`).
 - **OpenCode**: see `docs/setup.md § opencode` for plugin install (`greprag init --opencode`).
 
+For collision-safe parallel Codex implementation, read `docs/codex-chip.md`.
+
 ## Step 1 — Status
 
 ```bash
@@ -50,7 +53,7 @@ For Codex, also inspect:
 node -e "const fs=require('fs'),os=require('os'),p=require('path');const hp=p.join(os.homedir(),'.codex','hooks.json');const envp=p.join(os.homedir(),'.greprag','.env');let h={};try{h=JSON.parse(fs.readFileSync(hp,'utf8'))}catch{};const has=(evt,cmd)=>((h.hooks&&h.hooks[evt])||[]).some(e=>(e.hooks||[]).some(x=>(x.command||'').includes(cmd)));console.log(fs.existsSync(envp)?'CODEX_ENV_OK':'CODEX_ENV_MISSING');console.log(has('UserPromptSubmit','codex-notify')?'CODEX_NOTIFY_OK':'CODEX_NOTIFY_MISSING');console.log(has('PostToolUse','codex-inbox')?'CODEX_INBOX_OK':'CODEX_INBOX_MISSING');console.log(has('Stop','codex-store')?'CODEX_STORE_OK':'CODEX_STORE_MISSING');console.log(has('SessionStart','recap')?'CODEX_RECAP_OK':'CODEX_RECAP_MISSING');"
 ```
 
-If any Codex check is missing, route to `docs/setup.md § codex`. If hooks exist but memory is not being captured, remind the user to open Codex Desktop Settings -> Settings -> Hooks, trust the 6 GrepRAG commands, and start a fresh session.
+If any Codex check is missing, route to `docs/setup.md § codex`. If hooks exist but memory is not being captured, remind the user to open Codex Desktop Settings -> Settings -> Hooks, trust the GrepRAG commands, and start a fresh session.
 
 Chip-spawn convention marker (in `~/.claude/CLAUDE.md`):
 ```bash
@@ -125,7 +128,7 @@ Aliases (silent back-compat): `greprag memory briefing` → `recap` (renamed v5.
 
 **COLLISION IN A REPO? (another live session working the SAME repo) — MESSAGE IT, DON'T CLOBBER IT.** `greprag inbox watchers --json` lists every live session under your tenant (`project_id · session_id(8hex) · title`); a collision = a row with YOUR project and a different `session_id`. When you spot one, (1) `greprag send "…what you're touching…" --to <handle>@greprag.com/<their-8hex> --from-session <your-8hex>` a contextual heads-up, and (2) do code work in a worktree on its own branch, merging to main only on the operator's word. The `greprag-hook collision-check` SessionStart reflex injects this directive automatically once wired — but the discipline is yours regardless. Full mechanism + wiring: `docs/collision-schematic.md`.
 
-**Codex: DO NOT CLAIM HOOKS ARE ACTIVE JUST BECAUSE `~/.codex/hooks.json` EXISTS.** Codex Desktop requires Settings -> Settings -> Hooks trust review before command hooks run automatically. If turn capture is missing after `greprag init --codex`, tell the user: open Codex Desktop Settings -> Settings -> Hooks, trust the 6 GrepRAG hooks, then start a fresh Codex session.
+**Codex: DO NOT CLAIM HOOKS ARE ACTIVE JUST BECAUSE `~/.codex/hooks.json` EXISTS.** Codex Desktop requires Settings -> Settings -> Hooks trust review before command hooks run automatically. If turn capture is missing after `greprag init --codex`, tell the user: open Codex Desktop Settings -> Settings -> Hooks, trust the GrepRAG hooks, then start a fresh Codex session.
 
 **Codex live inbox push requires the startup watcher plus target-thread delivery.** Hooks only fire at Codex turn/tool/session boundaries. Public installs should use `greprag init --codex --tenant-id <handle> --install-watcher`; run `greprag codex doctor --wake-test` to inspect state, and use `greprag codex watch --session <id>` only for foreground testing. The sidecar listens to GrepRAG inbox SSE. Native `send_message_to_thread` / `codex_delegation` proved the messaging pattern; on Windows the public sidecar uses Codex app-server stdio `thread/resume` for the exact target thread, then `turn/start` or `turn/steer`, and keeps the bridge alive until the turn settles. `codex exec resume` is diagnostic/history-only because it can append to history without surfacing in the active Desktop pane. If wake-test reports no app-server-resume path, describe live push as unavailable/non-visible and rely on turn-bound inbox steering for reliable delivery.
 
@@ -137,6 +140,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` — first-class Codex task spawn, leases, reporting, steering, cleanup
 - `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

@@ -0,0 +1,38 @@
+# Codex chips
+
+Use a chip when parallel work needs an independent Codex task and repository
+isolation. A chip is a new app-server thread, not a native subagent.
+
+```bash
+greprag codex chip spawn "<task>" --name <slug> --owns "src/area/**"
+```
+
+The standard/default profile is `gpt-5.6-luna` at `xhigh`. Use
+`--profile complex` (or `--complex`) for `gpt-5.6-sol` at `high` when the chip
+owns orchestration or unusually difficult work. Explicit `--model <model-id>`
+and `--effort none|minimal|low|medium|high|xhigh|max|ultra` create a custom
+override.
+
+Declare every path the child may change. Split overlapping work differently;
+never bypass a lease collision. Use `--read-only` for research or review.
+
+Inspect and control with:
+
+```bash
+greprag codex chip list
+greprag codex chip status <id|name>
+greprag codex chip steer <id|name> "<correction>"
+greprag codex chip stop <id|name>
+```
+
+The child commits inside its isolated checkout and runs `greprag codex chip report`.
+The host validates the receipt and imports only that unique branch. The parent reviews
+the reported commit and integrates it. Never ask the child to merge, push, or
+delete its own checkout. After integration, the parent runs:
+
+```bash
+greprag codex chip cleanup <id|name>
+```
+
+Messages between the parent and child use the normal GrepRAG session inbox, so
+the same communication path also works across Claude, Codex, and OpenCode.

package/skill/greprag/docs/setup.md

@@ -21,6 +21,7 @@ This writes `~/.greprag/.env` plus `~/.codex/hooks.json`. The Codex hooks are:
 - `PostToolUse` → `greprag-hook codex-inbox`
 - `Stop` → `greprag-hook codex-store`
 - `PostCompact` → `greprag-hook session-id`
+- chip lifecycle events → `greprag-hook codex-chip-hook`
 
 It also installs the bundled `/greprag` skill at
 `~/.codex/skills/greprag` and refreshes the shared identity cache at
@@ -35,7 +36,7 @@ greprag codex startup install
 
 After install, Codex still requires trust review. Tell the user:
 
-> Open Codex Desktop Settings -> Settings -> Hooks, trust the 6 GrepRAG hooks,
+> Open Codex Desktop Settings -> Settings -> Hooks, trust the GrepRAG hooks,
 > then start a fresh Codex session.
 
 Do not try to approve hooks on the user's behalf. This is Codex Desktop's trust
@@ -53,7 +54,7 @@ node -e "const fs=require('fs'),os=require('os'),p=require('path');const hp=p.jo
 If hook entries are missing, re-run `greprag init --codex`. If entries exist
 but turns are not saving, the most likely cause is untrusted hooks or an old
 session that started before trust. Tell the user to open Codex Desktop Settings
--> Settings -> Hooks, trust the 6 GrepRAG commands, and restart Codex.
+-> Settings -> Hooks, trust the GrepRAG commands, and restart Codex.
 
 Codex live inbox delivery requires the sidecar. Public installs should use the
 startup helper above. For foreground/manual testing:

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

@@ -0,0 +1,139 @@
+# Codex Chip Spawn
+
+This is the Codex Desktop chip method. It is separate from Claude Code
+`spawn_task`: never use or copy the Claude Block 1/Block 2 prompt here.
+
+## Gate: one chip or a mission?
+
+A single independent task proceeds directly. If two or more chips target one
+objective, or you are about to create a second chip, stop and run `greprag load
+chip-leader`. Plan the integration branch, ownership seams, dependency order,
+merge order, and whole-feature test gate before another spawn. Rename the
+orchestrating task so its title begins `LEAD: `. Every spawned worker title
+begins `Chip: `; the native handoff supplies the exact title.
+
+## Prepare the isolated task
+
+Every write chip declares non-overlapping ownership leases; research uses
+`--read-only`. The parent session id is mandatory.
+
+```bash
+greprag codex chip spawn "<independent task>" \
+  --name <slug> \
+  --owns "<path/**>" \
+  --codex-project-id <desktop-project-id> \
+  --parent-session <parent-thread-id> \
+  --json
+```
+
+The parent/`LEAD:` selects each worker model before dispatch; the child never
+self-selects or changes it. Defaults are exact:
+
+- **Standard — `gpt-5.6-luna` / `xhigh`:** bounded single-owner execution with
+  clear acceptance criteria: scoped implementation, tests, docs, or focused
+  research/review.
+- **Complex — `gpt-5.6-sol` / `high`:** use when *any* hard signal applies:
+  orchestration/decomposition; multi-chip integration or merge arbitration;
+  architecture/API/schema decisions; cross-cutting ownership; ambiguous
+  requirements needing synthesis; high-risk migration/security/accounting
+  correctness; or novel diagnosis with multiple interacting hypotheses.
+
+In multi-chip missions the `LEAD:` itself is Sol/high, but it classifies every
+worker independently—workers do not inherit Sol. Complex selection requires a
+concise `--model-reason` plus one or more `--complexity-signal` values:
+`orchestration`, `multi-chip-integration`, `architecture-api-schema`,
+`cross-cutting-ownership`, `ambiguous-synthesis`, `high-risk-correctness`, or
+`novel-multi-hypothesis-diagnosis`. Explicit `--model`/`--effort` overrides are
+supported and require `--model-reason`; standard records its rubric reason by
+default. Native Desktop `thinking` uses the callable enum and is checked against
+the selected model's advertised effort matrix.
+An arbitrary custom native model also requires `--native-model-verified`, which
+means the parent verified it on the Desktop surface before dispatch. The
+manifest persists profile/model/effort, parent session in
+`selectedBy`, reason, and matched signals.
+
+Native Desktop is the default runtime.
+`--runtime cli` is opt-in and only valid when PATH Codex `model/list` actually
+exposes the requested model and effort; validation remains fail-loud.
+
+The spawn command creates a unique starting branch, records the manifest and
+lease, and returns a `greprag-codex-native-v3` handoff. Pass `createRequest`
+exactly to native `create_thread`: `target.type=project`, the supplied Codex
+`projectId` from `list_projects`, and `environment.type=worktree` with
+`startingState={type:"branch", branchName}`.
+`expectedBaseSha` is the attach-time commit invariant behind that reserved branch.
+Do not add `cwd`, `title`, `model`, or `effort`—they are not valid create fields.
+
+Creation returns `clientThreadId` while Codex builds its own detached worktree.
+Wait for the bootstrap/auto-title turn to settle and verify the nonce-bearing
+`bootstrapAck`. Resolve `threadId` + actual cwd with `list_threads`/`read_thread`.
+Then call `set_thread_title` with the exact `Chip: ` name (`LEAD: ` for an
+orchestrator) and read it back twice. Retry the rename at most three times if
+auto-title overwrites it; fail loudly if it will not remain exact. Only then run
+`verifyTitleCommand`, rerun handoff, and run `attachCommand`. Attach validates
+project/base/sandbox attestation, writes the marker, sends parent `IN-FLIGHT`,
+and starts the monitor. Rerun handoff again and deliver `sendRequest` via
+`send_message_to_thread`. The enforced order is create → settle → rename →
+verify → attach → IN-FLIGHT → mission. This two-phase send applies
+`model` + `thinking` after creation because high/xhigh validation rejects a
+worktree `startingState` create request. A standalone CLI cannot
+invoke the Desktop-owned surface, so it prepares rather than pretending an old
+PATH app-server successfully ran a 5.6 turn.
+
+## Mandatory parent inbox lifecycle
+
+The child must address the recorded parent session, not a bare mailbox:
+
+- `IN-FLIGHT` immediately after it starts work.
+- `DONE` before ending, with commit + checks, by running the exact `codex chip
+  report` command in its opening prompt.
+- `BLOCKED` before ending when it cannot finish, by running the exact `codex
+  chip block` command.
+- If the work crosses the selected model boundary, send a breakthrough message
+  explaining the new signal. The parent decides whether to steer or relaunch;
+  the child never swaps models autonomously.
+
+The attached host monitor validates receipts from the recorded native cwd,
+exact base ancestry, clean state, and every changed path against the lease. A
+detached HEAD is valid; the host imports the reported exact commit into the
+reserved chip ref, then sends the terminal inbox event. The
+child never merges, pushes, cleans up, or edits the parent checkout. The parent
+reviews/integrates and runs `greprag codex chip cleanup <id>` only afterward.
+After a verified squash/cherry-pick (where the exact report commit is not an
+ancestor), the parent acknowledges integration with `cleanup <id> --integrated`;
+ordinary merge ancestry remains automatic.
+
+Native chips have a receipt deadline (default 180 minutes; override with
+`--native-timeout-minutes`). This standalone CLI cannot query Desktop-private
+turn status, so it never guesses that a settled task succeeded: write *and read*
+chips must submit `report`/`block`, and timeout fails loudly. One live monitor
+per chip is enforced. `reconcile` expires unattached setup after 10 minutes,
+retires stale blocked chips after 24 hours, and surfaces terminal-delivery
+failure. Lifecycle inbox sends validate HTTP status, target session, sender
+session, and durable event receipts; a duplicate monitor cannot double-send.
+If initial `IN-FLIGHT` delivery fails, attach remains verified and retryable
+instead of terminally stranding the task. Server-side idempotency serializes
+the claim and preserves the originally resolved target across retries.
+
+The native worktree sandbox is the physical boundary. Verification accepts only
+the Codex-issued `client-new-thread:<uuid>` token (or its bare UUID form), a
+distinct resolved UUID task ID, the expected project/base/bootstrap proof,
+an attested `workspace-write` sandbox, and a Git root beneath Codex's own
+`worktrees` directory at the exact base commit. Hook guards require the exact
+bound task/cwd/sandbox and deny out-of-lease file tools, destructive
+Git/cleanup, and symlink/junction creation; link-based escape is never allowed.
+Generated verify/attach/report commands pin resolved stable Node and CLI paths,
+so restarting Codex does not invalidate an in-flight chip contract.
+
+Useful recovery commands:
+
+```bash
+greprag codex chip handoff <id> --json
+greprag codex chip status <id>
+greprag codex chip steer <id> "<follow-up>"
+greprag codex chip stop <id>
+```
+
+For a native chip, `steer` emits a `send_message_to_thread` handoff. Stop fails
+loud until the parent interrupts the Desktop task, then confirms that fact with
+`stop <id> --native-interrupted`; the CLI never records a false cancellation.