Complete native workflow adapters and verified Grok reader support

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pstack-codex",
-  "version": "0.1.0-alpha.1+codex.20260918173629",
+  "version": "0.1.0-alpha.1+codex.20260919065323",
   "description": "Faithful pstack workflow port for Codex with standalone Claude Code and optional Grok Build workers.",
   "author": {
     "name": "J0UH"

.github/workflows/ci.yml

@@ -16,6 +16,7 @@ jobs:
         with:
           bun-version: '1.3.13'
       - run: python3 scripts/build.py --check
+      - run: python3 -m pip install -r requirements-test.txt
       - run: python3 -m unittest discover -s tests -v
       - run: python3 scripts/package.py --check
       - run: bun install --frozen-lockfile

README.md

@@ -6,7 +6,9 @@
 
 **Open-source workflow library for Codex** — a Codex port of [Lauren Tan’s (`@poteto`) pstack](https://github.com/cursor/plugins/tree/main/pstack). Potato energy, serious verification. Not an official Cursor, OpenAI, or xAI release.
 
-You talk to **poteto-mode**. **Astra** coordinates. Session work runs in a **sandbox**. Workers (**Fable** / Claude Code, optional **Grok Build**) return evidence. **Grok Bot** is the outer loop: its **own computer**, **routines**, and **webhook wakes** — the path that can keep working after you close the chat (see below for what this Codex port actually supports today).
+The source is pinned to pstack **0.15.2** at `5bf2b1544db739998121a306340631963c2ff3de`. The original skills, principles, playbooks, and agent roles are preserved.
+
+You talk to **poteto-mode**. **Astra** coordinates native agents and CLI workers. **Fable** through Claude Code and optional **Grok Build** return evidence. Optional **Grok Bot** provides its own cloud computer, routines, and webhook wakes. The host supplies execution protections, and the verified capabilities are listed below.
 
 ```text
 $pstack-codex:poteto-mode <your task>
@@ -20,6 +22,8 @@ That’s the verified activation form. Follow-ups continue the work; `new task`
 
 ## How it works
 
+Use `$pstack-codex:poteto-mode` with your task. Explicit dollar-form mentions may appear on later prose lines and may end in punctuation; quoted examples and fenced code do not activate the mode. Slash-form activation stays on the first line. Poteto mode chooses the playbook and supporting skills. It can move through `how`, `architect`, `arena`, implementation, review and verification without you listing that sequence. Follow-ups continue the current work; `new task` rematches; `exit poteto-mode` stops applying the mode.
+
 <p align="center">
   <img src="docs/assets/pstack-loop-v2.png" alt="Activate, coordinate, verify" width="100%" />
 </p>
@@ -28,21 +32,23 @@ That’s the verified activation form. Follow-ups continue the work; `new task`
 flowchart LR
     U[Your request] --> P[poteto-mode]
     P --> A[Astra in Codex]
-    A --> S[Session sandbox]
+    A --> S[Host execution environment]
+    A --> N[Native Codex agents]
     A --> F[Fable / Claude Code]
     A --> G[Optional Grok Build CLI]
     A -.->|outer loop / wake<br/>host-dependent| B[Grok Bot own computer]
     B --> R[Routines and webhooks]
     S --> E[Evidence]
+    N --> E
     F --> E
     G --> E
     R --> E
     E --> U
 ```
 
-**Session sandbox** is the disposable workspace for the current turn. **Workers** are execution backends Astra can call. **Grok Bot** is different: upstream pstack’s `make-bot-ui` skill describes a **UI on the bot’s computer** that POSTs to a **webhook routine**, so the bot wakes with JSON — server holds the sender key, Tailscale can expose the page. That is the “keeps working when chat closes” machine.
+Execution uses the current host's configured permissions and sandbox. The plugin does not create a disposable workspace or an isolated VM for every turn. Upstream pstack's `make-bot-ui` skill describes a UI and server on the Bot computer. The server POSTs JSON to a webhook routine and keeps the sender key out of the browser. Tailscale can make that page reachable.
 
-Honest Codex-port note (from [`adapters/host.md`](adapters/host.md) + [`docs/verification.md`](docs/verification.md)): this package **preserves** those skills and contracts, but **does not ship a verified durable-wake / Grok Bot webhook adapter** for Codex alone. Current-turn work and bounded waits work; unattended continuation needs an authorized host adapter. We do not pretend local Codex is that computer.
+This port preserves those instructions. Native Codex timed wake has passed a live check. The optional Bot app handoff has also returned a verified public-page screenshot. Live Bot webhook delivery, a reachable failure queue, and durable external event wakes remain unverified. See the [host contract](adapters/host.md) and [verification record](docs/verification.md).
 
 ## Grok Bot’s computer
 
@@ -52,27 +58,31 @@ Honest Codex-port note (from [`adapters/host.md`](adapters/host.md) + [`docs/ver
 
 From `skills/make-bot-ui`: build a page; a server **on this computer** POSTs to a webhook routine; the bot wakes on `[routine]` with a `<webhook_event>` body. Secrets stay out of the browser and out of chat. Optional Tailscale for reachability. That computer is shared across agents on the node — one Tailscale hostname, not a second invented box.
 
-## Install
+The plugin is reusable across projects. Build commands, verification tools, deployment effects and business rules come from the current project. Activation and mode state are scoped to the conversation and project.
 
-<p align="center">
-  <img src="docs/assets/pstack-install-v3.png" alt="Install — clone, build, plugin add; trust hooks; new session" width="100%" />
-</p>
+The external `cursor-team-kit` companions `deslop`, `control-cli`, and `control-ui` are included too. Poteto loads their bundled instructions when a workflow calls them. They do not need a separate install and are not registered as separate slash commands. Cursor's built-in authoring and automation tools have different portability limits. See [companion skills and built-ins](docs/companions.md).
 
 ## Status
 
 This is an early, tested port, **not a claim of complete Cursor runtime parity**. Read [verification](docs/verification.md) for the exact evidence and remaining gaps.
 
 - All **47 registered pstack skills**, **23 playbooks**, **23 principles**, two agent roles, three companion skills, and the three dormant Benny skills are retained.
 - Claude analysis, writer and scoped local-Git reader profiles have been exercised against the real CLI; native/Claude handoffs and mode lifecycle have dedicated checks.
-- Grok's adapter is optional. Its protected live probe was blocked by a local sandbox startup error. Grok reader/writer profiles are not enabled.
-- Cursor cloud placement, durable wakeups (`/loop`, `/goal`, timed audit ticks and watcher-driven wakes), **Grok Bot webhook wakes**, Benny event automations, some transcript integrations and model-specific plan validation still have explicit limitations on this Codex host — **source and routes remain present** (see How it works). Missing capabilities do not become silent weaker substitutes.
+- Optional Grok analysis and file-reader profiles passed real production-adapter checks on the tested Linux build. Writer, shell access and non-Linux dispatch remain disabled. See [Grok's supported scope](docs/grok.md).
+- Cursor cloud placement, durable wakeups (`/loop`, `/goal`, timed audit ticks and watcher-driven wakes), Grok Bot webhooks, Benny event automations, some transcript integrations and model-specific plan validation still have explicit limitations. Their source and routes remain present. Missing capabilities do not become silent weaker substitutes.
 
-The package alone cannot arm Autonomous run, Babysit drive, Shipping watch, either Autopilot, Orchestrate, unattended Hillclimb, or Visual parity loops for unattended continuation. Current-turn work and bounded waits remain possible; future wakeups need an authorized, verified host adapter. Their original stopping rules remain intact.
+The [native workflow adapter](docs/native-workflows.md) maps goals, timed heartbeats, task identities and plan checks onto actual Codex capabilities. A real timed wake and its cleanup have passed. Across-turn event bridges and isolated cloud workers remain separate prerequisites; timed polling and worktrees do not pretend to replace them. See the [23-playbook capability map](docs/workflow-capabilities.json).
 
-Two completed Fable 5.1 reviews approved the documented limited alpha after repairs. See the [exact commit, verdicts and limits](docs/fable-review.md).
+Fable 5.1 approved the current implementation at its exact recorded code commit and documented scope. Astra authored the latest Grok changes, which passed real Linux acceptance before review. See the [current review](docs/integration-review.md) and [earlier alpha record](docs/fable-review.md). This remains a tested alpha with the explicit capability limits above.
+
+Use the [read-only doctor](docs/doctor.md) to distinguish installation, authentication and verified worker evidence. [Grok Bot](docs/grok-bot.md) is optional for cloud-computer and Bot-native work; ordinary coding and review do not require it.
 
 ## Install
 
+<p align="center">
+  <img src="docs/assets/pstack-install-v3.png" alt="Install — clone, build, plugin add; trust hooks; new session" width="100%" />
+</p>
+
 Requirements: a supported local Codex installation, Python 3.10+ on POSIX, and Git. Claude roles also require an independently installed and authenticated [Claude Code CLI](https://code.claude.com/docs/en/overview). Grok roles require independently installed [Grok Build](https://docs.x.ai/build/overview). Bun and GitHub CLI are needed for the upstream helpers that use them; they are not required for reading a skill.
 
 ```sh
@@ -134,7 +144,9 @@ The receipt verifies transport, response-model attribution and effective capabil
 ```sh
 python3 scripts/build.py
 python3 scripts/build.py --check
-python3 -m unittest discover -s tests -v
+python3 -m venv .local/tests
+.local/tests/bin/python -m pip install -r requirements-test.txt
+.local/tests/bin/python -m unittest discover -s tests -v
 python3 scripts/package.py
 python3 scripts/package.py --check
 ```

adapters/ADAPTATIONS.md

@@ -28,7 +28,7 @@ The current user's Astra/Fable/optional-Grok policy is supplied separately by th
 
 The setup host notice points to `docs/setup.md` and the model schema. Original discovery, budget, confirmation and override decisions remain; Codex represents backend/model/effort separately. Mode starter prompts contain an explicit mention, hook context supplies authoritative session/project identity, and the CLI resolves recorded identity across worktree cwd changes. TypeScript path-trigger metadata is enforced inside active pstack workflows by the host contract; global path-trigger discovery outside the mode is not implemented.
 
-- The source plan checker is unchanged. It has fixed ten-lane, Grok-slug, `/goal`, trunk-command and timing markers. A different Codex plan cannot honestly pass by weakening or forging them. A reviewed parameterization remains future work.
+- The source plan checker is unchanged. It has fixed ten-lane, Grok-slug, `/goal`, trunk-command and timing markers. A different Codex plan cannot honestly pass by weakening or forging them. The separate `scripts/check_plan.mjs` now checks Codex plans against explicit model policy and native host markers, retaining the substantive gates. It certifies format, not runtime readiness.
 - The source worktree audit has Cursor transcript assumptions. Filesystem inspection alone does not make transcript-based liveness accurate on Codex.
 - Graphite-dependent stack state, Bun/bootstrap behavior, remote/cloud placement, and watcher wake behavior retain their source implementations and prerequisites. Native Codex tools do not automatically supply those guarantees.
 - Cursor-only routine/webhook/secret cards and Benny event triggers/editor flows are unsupported until real host adapters are verified. Dormant files remain intact and are not registered as slash skills or enabled.