greprag 5.57.0 → 5.58.0

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.