docs(runner): specify phase 4b live codex web ui

packages/paperclip-runner/spec/paperclip-native-runner-implementation-plan.md

@@ -246,17 +246,127 @@ uncreated until the Phase 4 runnable demo, tests, package-local documentation,
 tutorial, OKF journal entry, review gates, QA evidence, and human checkpoint are
 complete.
 
-## Phase 5 — Browser reference console and reusable SDK surface
+## Phase 4b — Live Codex protocol Web UI
 
-**Purpose:** turn the proven protocol into a reference implementation that package users can adopt without the Paperclip app.
+**Purpose:** prove that the Phase 4 Codex driver can power a useful live browser
+experience before the package freezes a reusable browser SDK or touches the
+Paperclip control plane.
 
-**Tracer bullet:** a standalone Vite browser app connects to the mock core, launches/replays a run, renders phases and typed events, handles runtime requests, and exposes a small SDK API used by an example app.
+**Ordering decision:** this is the correct next standalone test after Phase 4.
+Phases 0–3 already provide the canonical protocol, reducer, mock core, and
+recovery behavior. Phase 4 provides the real Codex thread/turn driver, steering,
+interruption, reconciliation, and skillless result path. Phase 4b must not begin
+until Phase 4 implementation, reviews, QA, and the human checkpoint are complete.
+It does not depend on Phase 5 or Phase 6. Instead, it extracts the real-driver
+browser tracer from the former Phase 5 scope; Phase 5 will generalize the proven
+client and components into a stable SDK.
+
+**Tracer bullet:** a standalone package-local Vite page connects to the mock
+core and a real Codex app-server session, starts or resumes a chat, renders the
+canonical event stream, steers an active turn, interrupts it gracefully, answers
+or rejects runtime requests, shows parent/child agent activity, exercises Codex
+goal operations when the installed app-server advertises them, and preserves a
+replayable session after refresh or reconnect.
+
+**Lowest-layer slices:**
+
+1. extend the Phase 4 driver and canonical protocol only where the browser proof
+   exposes a real gap: bidirectional app-server requests and responses,
+   approval/permission/user-input lifecycles, goal capability discovery and
+   operations, and parent/child thread lineage;
+2. add a package-local browser transport and reducer adapter against the mock
+   core, with no `server/`, `ui/`, `packages/db/`, or production API imports;
+3. build the minimal live chat shell, then add protocol inspector and debugging
+   controls without inventing a second event model;
+4. add deterministic demo-chat manifests that exercise normal completion,
+   mid-turn steering, graceful interruption and resume, command/file approval,
+   user input, subagent visibility, goal set/view/pause/resume/clear when
+   supported, reconnect, and replay;
+5. run the real Codex path end to end, retain screenshots and exact command
+   evidence, then run the service on this execution machine and report the
+   reachable `paperclip-dev:PORT` in the checkpoint comment.
 
 **Deliverables:**
 
-- stable TypeScript client/reducer API;
-- standalone browser devtools/reference app;
-- phase strip, timeline, connection health, composer, tool/file/plan/terminal views, requests, inspector, and replay controls;
+- standalone browser demo under `packages/paperclip-runner/` with a package-local
+  dev server and live connection to the mock core plus Phase 4 Codex driver;
+- chat transcript, streaming assistant/reasoning/tool items, composer, explicit
+  steer action, graceful stop/interrupt action, resume/reconnect state, and
+  connection/session status;
+- inline command, file-change, permission, tool, and user-input request cards
+  with approve, approve-for-session when offered, reject, cancel, and resolved
+  states derived from the upstream request contract;
+- visible parent/child thread or subagent lineage, activity, terminal state, and
+  unsupported-capability explanations instead of fabricated controls;
+- goal command palette and durable goal banner for set/view/pause/resume/clear,
+  gated by app-server capability/version detection; unsupported goal operations
+  must be disabled with an exact diagnostic;
+- protocol inspector showing canonical events, raw upstream method/event names,
+  identities, sequence/cursor state, pending requests, capability negotiation,
+  and redacted diagnostics;
+- preloaded demo-chat manifests with expected observations and reset controls;
+- selective source adaptation of compatible shadcn/ui and Vercel AI Elements
+  primitives after UX review, with a component decision record and no dependency
+  on the Paperclip application UI;
+- package-local reference documentation, Simplified English hand-run tutorial,
+  cumulative tutorial update, tutorial-index entry, screenshots, and OKF journal
+  entry.
+
+**Tests/evidence:** driver conformance for every newly exposed request/response
+or capability; reducer live/replay parity; stale-turn steering rejection;
+interrupt-before-start and interrupt-during-tool races; approval accept/reject,
+request cleanup, and no double response; goal capability present/absent fixtures;
+parent/child lineage and unsupported child-steering fixtures; reconnect and page
+refresh recovery; secret-redaction and browser-boundary tests; component,
+keyboard, and accessibility checks; deterministic demo-chat tests; a real Codex
+end-to-end recording; screenshots; exact startup command; bound host and port;
+and the final `paperclip-dev:PORT` handoff.
+
+**Security and credential rule:** use the execution environment's existing Codex
+authentication through the same Phase 4 allowlisted driver path. Never serialize
+credentials to browser state, fixtures, screenshots, diagnostics, protocol
+events, or documentation. The browser talks only to the package-local demo
+server/mock core; it does not receive provider credentials or Paperclip API
+credentials.
+
+**Owners/review:** UXDesigner reviews the interaction map and adapted component
+choices before UI implementation; CodexCoder owns driver/protocol/server work;
+ClaudeCoder or CodexCoder owns the package-local React UI after UX review;
+SecurityEngineer reviews credentials, approvals, browser transport, filesystem,
+and debug output; CTO reviews the protocol boundary and goal/subagent capability
+semantics; QA executes every demo chat, the clean-start tutorial, reconnect, and
+the reported machine port. Require screenshots for UX and QA review.
+
+**Depends on:** completed and human-accepted Phase 4. Phase 4b blocks Phase 5.
+
+**Human checkpoint:** open the reported `paperclip-dev:PORT`, run the preloaded
+demo chats, steer and interrupt a live Codex turn, resolve at least one real
+request, inspect subagent/goal state when supported, refresh and replay the same
+session, and approve or revise the interaction contract. Do not create Phase 5
+tasks until the user explicitly accepts this checkpoint and asks to continue.
+
+**Planning-only state (2026-08-08):** Phase 4 is still finishing. This section
+specifies Phase 4b only. Do not create Phase 4b implementation children, start a
+service, claim a port, or start Phase 5 until the board approves the updated plan
+and later explicitly authorizes execution after Phase 4 completes.
+
+## Phase 5 — Browser reference console and reusable SDK surface
+
+**Purpose:** generalize the Phase 4b browser proof into a stable reference
+implementation and reusable SDK surface that package users can adopt without the
+Paperclip app.
+
+**Tracer bullet:** a second small example app consumes the extracted TypeScript
+client/reducer/component APIs, runs against fake and real drivers, and reproduces
+the accepted Phase 4b lifecycle without importing demo internals.
+
+**Deliverables:**
+
+- extracted and versioned browser transport, TypeScript client/reducer, and
+  reusable component contracts based on the accepted Phase 4b behavior;
+- standalone browser devtools/reference app plus a separate minimal SDK consumer;
+- phase strip, timeline, connection health, composer, tool/file/plan/terminal
+  views, request adapters, inspector, replay controls, and extension points;
 - selective adaptation of compatible shadcn/ui and AI Elements source components;
 - accessibility and design-token compliance;
 - screenshots and component decision record explaining reused, adapted, and rejected components.
@@ -265,7 +375,8 @@ complete.
 
 **Owners/review:** UXDesigner creates/reviews the component plan first; ClaudeCoder or CodexCoder implements after UX approval; QA performs browser validation and screenshot review.
 
-**Depends on:** Phase 3. It may proceed in parallel with late Phase 4 driver work once protocol and recovery contracts are frozen.
+**Depends on:** completed and human-accepted Phase 4b. Do not run it in parallel
+with Phase 4 or Phase 4b because it freezes APIs from the live proof.
 
 **Human checkpoint:** use the browser tutorial as a small SDK consumer, run fake and real-driver sessions, and give UI feedback before Paperclip integration starts.
 

packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md

@@ -6572,7 +6572,8 @@ them to collapse into one public endpoint.
 1. Fake driver local loopback.
 2. Direct Codex local execution target.
 3. Direct Codex in one cold sandbox provider with legacy/native workspace-equivalence tests passing.
-4. UI steering/interrupt.
+4. Standalone Phase 4b live Codex Web UI with steering, interruption,
+   requests, goal capability detection, subagent lineage, reconnect, and replay.
 5. Reconnect/replay fault suite.
 6. Second provider.
 7. ACP/acpx driver.
@@ -6605,11 +6606,78 @@ Never change an active run from native to legacy mid-session.
 
 The implementation phases, dependency policy, package-local documentation layout, human checkpoints, and retained future backlog now live in [`paperclip-native-runner-implementation-plan.md`](./paperclip-native-runner-implementation-plan.md).
 
-The spike specification remains the normative contract. Keep it updated when implementation evidence changes architecture, protocol, security, persistence, API, UI, performance, or exit criteria. Keep sequencing and task-creation details in the implementation plan. Phase 0, Phase 1, Phase 2, and Phase 3 are complete, including the Phase 3 implementation, security, UX, QA, documentation, tutorial, journal, and human checkpoint gates. On 2026-08-08, the board authorized Phase 4. The package-local Phase 4 driver, conformance suite, safe real-model tracer, documentation, tutorial, and OKF evidence are implemented without changes or imports from `server/`, `ui/`, `packages/db/`, or production control-plane behavior. Security review, CTO contract review, QA tutorial evidence, and the human checkpoint remain pending. Keep Phase 5 and later tasks uncreated until those gates complete.
+The spike specification remains the normative contract. Keep it updated when implementation evidence changes architecture, protocol, security, persistence, API, UI, performance, or exit criteria. Keep sequencing and task-creation details in the implementation plan. Phase 0, Phase 1, Phase 2, and Phase 3 are complete, including the Phase 3 implementation, security, UX, QA, documentation, tutorial, journal, and human checkpoint gates. On 2026-08-08, the board authorized Phase 4. The package-local Phase 4 driver, conformance suite, safe real-model tracer, documentation, tutorial, and OKF evidence are implemented without changes or imports from `server/`, `ui/`, `packages/db/`, or production control-plane behavior. Security review, CTO contract review, QA tutorial evidence, and the human checkpoint remain pending.
+
+### 29.1 Phase 4b live Codex protocol Web UI contract
+
+Phase 4b is the next standalone tracer after Phase 4, but it is not authorized
+to start while Phase 4 is still finishing. It moves the real-driver browser
+proof out of the old Phase 5 scope so the team can validate the interaction
+contract before extracting stable SDK APIs.
+
+The Phase 4b implementation must remain entirely under
+`packages/paperclip-runner/`. It uses the mock control-plane adapter and the
+Phase 4 Codex app-server driver. It must not import or modify `server/`, `ui/`,
+`packages/db/`, production routes, production persistence, or legacy adapter
+behavior. The browser receives no Paperclip or provider credential. Existing
+Codex authentication remains server-side in the allowlisted Phase 4 launch
+boundary.
+
+The runnable proof must provide:
+
+1. a live chat transcript and composer over the canonical event/reducer path;
+2. same-turn steering with stale-turn rejection and visible acknowledgement;
+3. graceful interruption across before-start, active-generation, and active-tool
+   races without silently replacing the session;
+4. inline command, file-change, permission, tool, and user-input request states,
+   including upstream-supported accept, session-accept, reject, cancel, cleanup,
+   and terminal outcomes;
+5. capability-negotiated Codex goal controls for set, view, pause, resume, and
+   clear when the installed app-server exposes them, plus a precise disabled
+   state when it does not;
+6. parent/child thread or subagent lineage and activity derived from upstream
+   identities, with unsupported direct child steering shown as unsupported
+   rather than emulated;
+7. reconnect, refresh, resume, and replay of the same normalized session;
+8. a protocol inspector for raw upstream methods/events, canonical events,
+   identity, sequence/cursor state, pending requests, capabilities, and redacted
+   diagnostics;
+9. preloaded demo-chat manifests that exercise completion, steering,
+   interruption/resume, approvals, user input, subagents, goals, reconnect, and
+   replay with explicit expected observations;
+10. package-local documentation, tutorial index, cumulative tutorial update,
+    Simplified English hand-run guide, screenshots, exact command evidence, and
+    an OKF journal entry.
+
+Phase 4b may extend the driver/protocol at the lowest layer only where the live
+proof finds a missing app-server mapping. In particular, Phase 4 currently
+proves thread/turn lifecycle, steering, interruption, reconciliation, usage,
+canonical replay, and structured completion. Browser-resolved upstream
+requests, goal operations, and parent/child lineage are explicit Phase 4b
+contracts and must receive deterministic conformance fixtures before UI work
+claims them.
+
+Use source-adapted shadcn/ui and Vercel AI Elements primitives where they fit,
+after UX review. Keep the package's own protocol and reducer authoritative;
+third-party chat message or tool-part types must not become the runner protocol.
+Require a component decision record, accessibility checks, keyboard operation,
+and screenshots.
+
+The completion evidence must include a real Codex end-to-end run and a live
+service started on this execution machine. The checkpoint comment must state the
+exact startup command, host binding, port, and reachable `paperclip-dev:PORT` so
+the human can exercise it. That runtime handoff is an implementation/QA
+deliverable, not part of this planning-only revision.
+
+Phase 5 begins only after the Phase 4b human checkpoint is accepted and the user
+explicitly asks to continue. Phase 5 generalizes the accepted browser proof into
+a stable TypeScript SDK, reusable component contracts, and a second minimal
+consumer application. Phase 6 remains the first Paperclip control-plane
+integration phase.
 
 ## 30. Dependency sequencing
 
-The phase dependency graph, task-creation gates, owner guidance, per-phase completion contract, and retained issue-sized future backlog are maintained in [`paperclip-native-runner-implementation-plan.md`](./paperclip-native-runner-implementation-plan.md).
+The phase dependency graph, task-creation gates, owner guidance, per-phase completion contract, and retained issue-sized future backlog are maintained in [`paperclip-native-runner-implementation-plan.md`](./paperclip-native-runner-implementation-plan.md). The current order is Phase 4 completion and human acceptance, then Phase 4b planning approval and explicit execution authorization, then the Phase 4b human checkpoint, then Phase 5. Do not create Phase 4b or Phase 5 implementation tasks from this planning revision.
 
 ---