greprag 5.60.3 → 5.60.5

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

@@ -1,177 +1,133 @@
-# 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.
-
-Exact visible titles are role contracts: `PLANNER: <Mission>` owns intent and
-acceptance, `LEAD: <Mission>` is always Luna/xhigh and owns orchestration,
-`Chip A/B/C: <Specific Purview>` are Luna/xhigh workers, and
-`ADVISOR: <Purview>` is read-only Sol/high advice for a documented fundamental
-blocker.
-
-## 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: <Mission>`. Multi-chip workers are
-uniquely named `Chip A: <Specific Purview>`, `Chip B: ...`; a single worker is
-`Chip: <Purview>`. Labels are stable coordination handles, not execution order.
-
-## Prepare the isolated task
-
-Every mission starts with a durable parent-owned goal. Give it a concrete
-objective, final state, and stable acceptance criterion IDs. Every write chip
-declares non-overlapping ownership leases; research uses `--read-only`.
-After the planner attaches the Luna LEAD, the LEAD creates one nested goal and
-runs `greprag codex chip goal bind-lead <lead-id> --goal-id <nested-goal-id>`.
-That emits `GOAL_READY:<goalId>`; no LEAD execution or child dispatch is valid
-before it. All later Chips, ADVISOR, and MECHANIC tasks use that exact goal.
-
-```bash
-greprag codex chip goal create \
-  --objective "<concrete objective>" \
-  --final-state "<observable final state>" \
-  --criterion <id>:"<acceptance statement>"
-
-greprag codex chip spawn "<independent task>" \
-  --name <slug> \
-  --title "<Properly Capitalized Purview>" \
-  --goal-id <goal-id> --covers <criterion-id> \
-  --owns "<path/**>" \
-  --codex-project-id <desktop-project-id> \
-  --parent-session <parent-thread-id> \
-  --json
+# Codex Orchestration
+
+Choose the smallest primitive that matches the work. This method is about
+discoverable task shape; titles are coordination labels, not execution
+authority.
+
+## Identity first
+
+For any coordinated multi-chip mission, rename the orchestrating task before
+spawning children:
+
+```text
+LEAD: <Mission>
+```
+
+Then name children with the exact ordinal schema:
+
+```text
+Chip A: <Specific Purview>
+Chip B: <Specific Purview>
+Chip C: <Specific Purview>
+```
+
+In quick mode, the current task renames itself `LEAD: <Mission>` and directly
+spawns 1–2 children. It is the **implicit LEAD**; no separate leader task is
+created. In Leader mode, the initiator creates a separate `LEAD: <Mission>`
+task, and that LEAD spawns and manages the children.
+
+## Three primitives
+
+### 1. Internal subagent
+
+Use this for ephemeral analysis, research, or bounded edits/tests that can stay
+inside the current session. Load `greprag load codex-subagent-spawn` first.
+
+- Same-session and short-lived; results return to the parent context.
+- No worktree, durable task manifest, inbox identity, or goal is created.
+- Keep the session bounded at `max_threads=6` and `max_depth=1`.
+- `fast_scan` is read-only; `routine_worker` and `deep_worker` may make bounded
+  edits/tests in the parent workspace. The parent avoids overlapping writes and
+  owns integration.
+- If the work needs a visible child, independent persistence, or its own
+  worktree, use a quick chip instead.
+
+### 2. Quick chip
+
+Use this for 1–2 visible, durable worktree tasks with one initiating parent.
+The initiating task is the implicit LEAD after it renames itself; it may
+dispatch `Chip A` and `Chip B` directly.
+
+- Each child gets its own visible task and worktree.
+- Children are writable ordinary chips. Do not add a read-only role, lease,
+  mandatory nested goal, or delivery-proof gate.
+- Preserve the visible native task identity, isolated worktree, concise final
+  report, parent review/integration, and parent-owned archive + cleanup. Normal
+  completion is the native parent-child task result; `greprag send` remains
+  available for explicit cross-harness or peer messaging, but is not mandatory
+  chip ceremony.
+
+### 3. Explicit Leader mission
+
+Use this when the work is more than the quick 1–2-chip shape, or when shared
+files, contracts, ordering, integration, or a seam require a dedicated
+orchestrator. The initiator creates the separate `LEAD: <Mission>` task first.
+That LEAD decomposes the mission, assigns exact `Chip A/B/C: <Specific Purview>`
+titles, dispatches ordinary writable chips, reconciles their reports, and owns
+integration checks and cleanup.
+
+Load `greprag load chip-leader` for the mission worksheet before dispatch.
+
+## Shared chip contract
+
+Visible chips keep the useful durable boundaries:
+
+1. Start in an isolated worktree with a clear purview and parent task
+   relationship.
+2. Make the change or investigation within that worktree; commit when there is
+   a durable result.
+3. Return a final `DONE` or `BLOCKED` result to the parent with commit, checks,
+   and caveats. Use `greprag send` only when explicit messaging is useful.
+4. The parent reviews and integrates reported work, then performs cleanup.
+
+The child never silently changes the orchestration shape. If the work grows
+from quick to Leader-scale, tell the parent and let the parent create the
+dedicated `LEAD: <Mission>` task.
+
+## Selection rule
+
+```text
+bounded thought, no durable surface   → internal subagent
+1–2 visible worktree tasks             → quick chip; current task is LEAD
+more chips or shared seams              → separate LEAD mission
 ```
 
-The parent/`LEAD:` selects each worker model before dispatch; the child never
-self-selects or changes it. `LEAD` and ordinary Chips are fixed to
-`gpt-5.6-luna/xhigh`.
-`PLANNER` may use Luna/xhigh or explicitly Sol/high. `ADVISOR` must be
-`--read-only`, Sol/high, and carry `--model-reason "Fundamental blocker: ..."`.
-The old `--complex`, `--profile complex`, and `--complexity-signal` routing is
-rejected for new spawns. Native Desktop `thinking` uses the callable enum and
-is checked against the selected model's advertised effort matrix. The manifest
-persists role, model, effort, parent session, reason, and criterion evidence.
-The auditable selection fields are `selectedBy`, `reason`, and `matched signals`.
-The hard-signal rubric covers `architecture/API/schema` and
-`high-risk migration/security/accounting`; a scope boundary sends a
-`breakthrough message` and the child `never swaps models autonomously`.
-
-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.
-
-For a multi-chip mission every spawn also uses `--multi-chip --label A` (then B,
-C...) and a different `--title`. Duplicate active slugs, labels, or purview
-titles fail loudly.
-
-The spawn command creates a unique starting branch, records the manifest and
-lease, and returns a `greprag-codex-native-v4` handoff. Pass `createRequest`
-exactly to native `create_thread`: it already contains the full real mission,
-selected `model`, `thinking`, project target, and worktree starting branch.
-The native target schema is `target.type=project` with
-`startingState={type:"branch", branchName}` inside the worktree environment;
-do not invent a checkout path or second bootstrap turn. Do not add `cwd`, `title`, `model`, or `effort` to the native create request; those values belong to the handoff and post-create verification contract.
-`expectedBaseSha` is the attach-time commit invariant behind that reserved branch.
-This is the only assignment turn. Never create a bootstrap task and never send
-the mission again after attach.
-
-Creation returns `clientThreadId` while Codex builds its own detached worktree.
-The initial `UserPromptSubmit` hook provisionally binds the manifest and native
-cwd before tool use. Resolve `threadId` + actual cwd immediately, then call
-`set_thread_title` with the exact handoff title and read it back twice. Retry at
-most three times if auto-title overwrites it; fail loudly if it will not remain
-exact. `create_thread` has no title field, so the mission's first line carries
-the correct identity immediately and task metadata is renamed as soon as the
-resolved task exists. 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. The enforced order is create-real-mission → provisional
-bind → resolve → rename/verify → attach → IN-FLIGHT → monitor. 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.
-The title race contract is `set_thread_title` → read it back twice →
-`IN-FLIGHT → mission` monitor only after the exact title remains stable.
-
-## 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, run
-  `codex chip breakthrough <id> --reason "..."`. This emits a typed
-  `BREAKTHROUGH` event to the recorded parent; the child never swaps models.
-
-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. Reports map
-concrete evidence to every covered goal criterion. The parent reviews the diff,
-integrates it, and runs `greprag codex chip goal accept <goal-id> --summary
-"<review judgment>"` only when all criteria and chips are satisfied. A
-LEAD-owned goal with no additional child chip records final proofs with
-`goal attest --commit <release-commit>` plus repeated `--evidence` and `--check`
-before acceptance. For a verified squash/cherry-pick add `--integrated <chip-id>`
-to acceptance. Acceptance
-returns machine-readable closeout entries: apply each native `archiveRequest`
-first, then its exact `cleanupCommand`. Cleanup does not imply acceptance, is
-refused before it, and requires `--native-archived` for native tasks.
-
-Native chips require parent-side `--native-model-verified` proof before monitor
-start and 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 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 breakthrough <id> --reason "<follow-up>"
-greprag codex chip resume <id>
-greprag codex chip stop <id>
+Do not use a larger coordination layer merely because the task sounds
+important. Use the smallest shape that preserves the required visibility,
+worktree isolation, reporting, messaging, and cleanup.
+
+## Required child opening prompt
+
+Generate the child assignment with this short handoff. Keep the real outcome
+dominant and do not require a parent-authored implementation plan:
+
+```text
+Chip <Label>: <Specific Purview>
+
+## Setup — do this FIRST
+Stay in the Codex-provided isolated worktree; do not create a second worktree.
+Read AGENTS.md and the session-start recap, then inspect the current repo state.
+No leases, read-only mode, or goals.
+If the exact first-line title is `MECHANIC: <Mission>`, make `greprag load
+mechanic` the first Setup action before diagnosis or edits.
+
+## 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>
+Acceptance: <checks/evidence that mean done>
+Own repository discovery, design, implementation, tests, and commit; do not
+wait for a parent-authored implementation plan.
+
+## Report when done
+Return DONE or BLOCKED to the parent with the commit hash, concise result,
+checks, and caveats. Do not merge, push, deploy, or delete the worktree; the
+parent reviews and cleans up. Normal completion is the native parent-child task
+result, not a nonce/ACK protocol or mandatory GrepRAG inbox ceremony.
 ```
 
-For a native chip, `BREAKTHROUGH` is the sole agent-visible control envelope;
-native turn transport remains private. Breakthrough delivery is
-durably queued → injected → acknowledged → acted; empty completed turns are
-not delivery, and natural-turn drain is degraded fallback only. 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.
-After restart/usage interruption, use `resume`, deliver its handoff, and wait for
-the nonce-bound breakthrough acknowledgment. A delivered message without that
-ack is not recovery. Cleaned/cancelled/failed tasks cannot resume; relaunch them.
-For an invalid terminal launch, preserve the mission and run `goal exclude
-<goal-id> --chip <old-chip-id> --reason "<concrete reason>"` before spawning its
-replacement. Excluded evidence cannot satisfy acceptance. To abandon the whole
-mission, stop every chip first, then use `goal cancel <goal-id> --reason
-"<concrete reason>"`; cancelled closeout is not acceptance.
-
-Mechanic repair incidents are not Mechanic task termination: `REPAIR-READY/CLOSED`
-returns the same Luna/xhigh Mechanic to `OPEN+DORMANT` for later typed friction.
-Only final LEAD teardown may accept/clean it with `--mechanic-final`.
+The first line is the exact visible title, alone. Substitute the appropriate
+discoverability label: `Chip A: <Specific Purview>`, `LEAD: <Mission>`,
+`ADVISOR: <Purview>`, or `MECHANIC: <Mission>`. These labels do not change
+execution authority.

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

@@ -0,0 +1,32 @@
+# 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.
+- 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`.

package/dist/commands/codex-native-delivery.d.ts

@@ -1,70 +0,0 @@
-export type NativeDeliveryState = 'queued' | 'native-delivered' | 'acknowledged' | 'acted' | 'degraded';
-export interface NativeCodexSendRequest {
-    threadId: string;
-    prompt: string;
-    messageId: string;
-    nonce: string;
-    ackMarker: string;
-}
-export interface NativeCodexSender {
-    /** The Codex host adapter must implement the native app-layer primitive. */
-    send_message_to_thread(request: NativeCodexSendRequest): Promise<unknown>;
-}
-export interface NativeDeliveryEnvelope {
-    version: 1;
-    messageId: string;
-    nonce: string;
-    targetSession: string;
-    summary: string;
-    state: NativeDeliveryState;
-    attempts: number;
-    requestedAt: string;
-    nativeDeliveredAt?: string;
-    acknowledgedAt?: string;
-    actedAt?: string;
-    lastError?: string;
-    action?: string;
-}
-export interface NativeDeliveryResult {
-    ok: boolean;
-    method: 'send_message_to_thread';
-    reason?: string;
-    lifecycle: NativeDeliveryState;
-    nonce: string;
-    threadId: string;
-    ackMarker: string;
-    visible: boolean;
-    acknowledged: boolean;
-    acted: boolean;
-    action?: string;
-    attempts: Array<{
-        method: string;
-        ok: boolean;
-        detail?: string;
-    }>;
-}
-export declare function deliveryNonce(messageId: string): string;
-export declare function deliveryAckMarker(messageId: string): string;
-export declare function readNativeEnvelope(messageId: string): NativeDeliveryEnvelope | null;
-export declare function queueNativeEnvelope(messageId: string, targetSession: string, summary: string, nonce?: string): NativeDeliveryEnvelope;
-export declare function markNativeDelivered(messageId: string): NativeDeliveryEnvelope;
-/** ACK mutates the original nonce only. It never sends a reply message. */
-export declare function acknowledgeNativeDelivery(messageId: string, nonce: string, action: string): NativeDeliveryEnvelope;
-export declare function markNativeActed(messageId: string, nonce: string, action: string): NativeDeliveryEnvelope;
-export declare function markNativeDegraded(messageId: string, error: string): NativeDeliveryEnvelope;
-/**
- * Load the host bridge supplied by Codex Desktop. A plain CLI process cannot
- * call an MCP/app tool by pretending that app-server is native, so the bridge
- * is explicit and fail-closed. The module must export the exact primitive name
- * `send_message_to_thread`; its result must contain bound visible ACK/action
- * proof before GrepRAG reports success.
- */
-export declare function loadNativeCodexSender(env?: NodeJS.ProcessEnv): NativeCodexSender | null;
-export declare function nativeAdapterConfigured(env?: NodeJS.ProcessEnv): boolean;
-export declare function deliverViaNativeCodex(opts: {
-    messageId: string;
-    targetSession: string;
-    prompt: string;
-    nonce?: string;
-    nativeSender?: NativeCodexSender;
-}): Promise<NativeDeliveryResult>;