[Wave 5d] @netscript/fresh — umbrella: target architecture + 6 sub-gates (5d1…5d6)

.agents/skills/codex-wsl-remote/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: codex-wsl-remote
+description: Use for NetScript Codex Desktop/mobile remote-control through WSL SSH, especially when launching or supervising mobile-visible Codex app-server sessions, choosing native WSL worktree paths, verifying full-access app-server settings, or running Deno/Aspire CLI E2E gates without `/mnt/c` DrvFS failures.
+---
+
+# Codex WSL Remote
+
+## Purpose
+
+Use this skill when a NetScript task needs Codex Desktop or mobile to steer local work through WSL.
+The verified path is:
+
+```text
+Codex Desktop/mobile -> SSH target codex-wsl -> WSL Ubuntu codex user -> codex app-server remote-control
+```
+
+Do not use Windows `codex exec --json` threads as the sync mechanism for Desktop/mobile. Those
+threads can persist and resume locally, but Desktop deep links can hang while loading `codex_exec`
+sessions. Use the WSL app-server remote-control workflow for user-visible, steerable sessions.
+
+## Verified Baseline
+
+- WSL distro: `Ubuntu-24.04`
+- WSL user: `codex`
+- SSH alias: `codex-wsl`
+- SSH endpoint: `127.0.0.1:2222`
+- SSH identity: `C:\Users\chaut\.ssh\codex_wsl_ed25519`
+- WSL Codex home: `/home/codex/.codex`
+- Codex CLI/app-server: `0.139.0`
+- App-server config: `approval_policy = "never"` and `sandbox_mode = "danger-full-access"`
+- Native WSL wave5 worktree root: `/home/codex/repos/netscript-wave5-apps`
+- Verified toolchain: Deno `2.7.11`, .NET SDK `10.0.109`, Aspire CLI `13.3.0`, Docker `29.1.3`, Node `18.19.1`, npm `9.2.0`
+
+The Windows-side helper lives at:
+
+```powershell
+$env:USERPROFILE\.codex\skills\codex-wsl-remote\scripts\start-codex-wsl-remote.ps1
+```
+
+Run it from Windows PowerShell when transport needs restoration:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.codex\skills\codex-wsl-remote\scripts\start-codex-wsl-remote.ps1"
+```
+
+The helper starts a hidden WSL keepalive, restarts WSL `ssh.service`, verifies `ssh codex-wsl`,
+writes the full-access Codex app-server config, restarts the managed daemon, starts
+`codex remote-control`, and checks the toolchain.
+
+## Native Worktree Rule
+
+Run full NetScript Deno/npm/Aspire gates from native WSL ext4 paths under `/home/codex/repos/`.
+Do not run full CLI E2E from `/mnt/c`: Deno's internal npm materialization can hit DrvFS
+`Operation not permitted (os error 1)` even when ordinary shell copy/write commands work.
+
+Known good full E2E smoke:
+
+```text
+Cwd: /home/codex/repos/netscript-wave5-apps
+Command: deno task e2e:cli run scaffold.runtime --cleanup --format pretty
+Raw exit code: 0
+Summary: passed=41 failed=0
+Elapsed: 224s
+Thread: 019ec234-4e7f-70c0-91a0-97de455702f8
+Marker: CODEX_WSL_NATIVE_WORKTREE_E2E_SMOKE_PASS
+```
+
+## Verification Commands
+
+From Windows PowerShell, verify transport:
+
+```powershell
+Test-NetConnection -ComputerName 127.0.0.1 -Port 2222
+ssh.exe codex-wsl 'echo SSH_OK; export PATH="$HOME/.local/bin:$PATH"; codex --version'
+```
+
+Verify app-server remote-control:
+
+```powershell
+ssh.exe codex-wsl 'export PATH="$HOME/.local/bin:$PATH"; codex remote-control start --json; codex app-server daemon version'
+```
+
+Verify the native NetScript toolchain:
+
+```powershell
+ssh.exe codex-wsl 'cd /home/codex/repos/netscript-wave5-apps; deno --version; dotnet --version; aspire --version; docker version --format "{{.Client.Version}} / {{.Server.Version}}"; node --version; npm --version; git status --short --branch'
+```
+
+Verify app-server turns are full access. The `thread/start` response should report
+`approvalPolicy: "never"` and `sandbox.type: "dangerFullAccess"`:
+
+```powershell
+ssh.exe codex-wsl 'cd /home/codex/repos/netscript-wave5-apps; codex debug app-server send-message-v2 "Remote smoke only. Do not edit files. Do not run validation. Reply with exactly CODEX_WSL_REMOTE_SMOKE_OK and no other prose."'
+```
+
+## Launching Supervisor Or Implementation Sessions
+
+Start Desktop/mobile-visible Codex sessions from the native WSL worktree path for the relevant
+branch. The wave5 family uses these native worktrees:
+
+```text
+/home/codex/repos/netscript-wave5-apps
+/home/codex/repos/netscript-wave5-apps-5a-service
+/home/codex/repos/netscript-wave5-apps-5b-sdk
+/home/codex/repos/netscript-wave5-apps-5c-fresh-ui
+/home/codex/repos/netscript-wave5-apps-5c1-ui-foundation
+/home/codex/repos/netscript-wave5-apps-5c2-design-system
+/home/codex/repos/netscript-wave5-apps-5d-fresh
+/home/codex/repos/netscript-wave5-apps-5d1-support
+/home/codex/repos/netscript-wave5-apps-5d2-builders
+/home/codex/repos/netscript-wave5-apps-5d3-route
+/home/codex/repos/netscript-wave5-apps-5d4-streaming
+/home/codex/repos/netscript-wave5-apps-5d5-form
+/home/codex/repos/netscript-wave5-apps-5d6-query
+```
+
+For full CLI E2E, use the `netscript-cli` skill and run:
+
+```powershell
+deno task e2e:cli run scaffold.runtime --cleanup --format pretty
+```
+
+Keep `--cleanup` unless the user explicitly wants the generated runtime left running. Do not delete
+lock files or caches, and do not run `deno cache --reload` without approval.
+
+## Troubleshooting
+
+If mobile says connection is impossible or Desktop shows a failed SSH connection:
+
+1. Run the Windows helper above.
+2. Confirm `ssh codex-wsl` reaches the `codex` user, not root.
+3. Confirm `/home/codex/.codex/config.toml` contains the quoted full-access TOML values.
+4. Restart only the `codex` user's app-server if remote-control reports an unmanaged daemon:
+
+   ```powershell
+   wsl.exe -d Ubuntu-24.04 -- sh -lc 'pkill -u codex -f "codex.*app-server" || true; pkill -u codex -f "app-server" || true'
+   ssh.exe codex-wsl 'export PATH="$HOME/.local/bin:$PATH"; codex remote-control start --json; codex app-server daemon version'
+   ```
+
+Avoid root-owned app-server daemons for normal Desktop/mobile work. They create duplicate host chips
+and stale mobile entries.

.llm/harness/debt/arch-debt.md

@@ -185,6 +185,22 @@ Seeded from
 - **Status:** open
 - **Gate:** F-1, F-5, F-11
 
+## packages/fresh — F-7 full package doc-lint residue after 5d1
+
+- **Reason:** 5d1 support-spine FAIL_FIX cannot make broad `deno task doc-lint` pass without
+  implementing later 5d-owned public surfaces. The remaining diagnostics are concentrated in
+  builders/defer/form/streams/query, including direct upstream TanStack/durable-streams public type
+  exposure and missing JSDoc on later-slice symbols.
+- **Owner:** Wave 5d `@netscript/fresh` chain; final closeout owner is 5d6 query/server/package
+  surface.
+- **Target:** Close before merging 5d into Wave 5 apps; 5d6 must prove `deno task doc-lint` passes
+  from `packages/fresh`.
+- **Linked plan:** `.llm/tmp/run/feat-package-quality-wave5-apps--5d-fresh/plan.md`;
+  `.llm/tmp/run/feat-package-quality-wave5-apps--5d1-support/escalations/failfix-doc-lint.md`.
+- **Created:** 2026-06-13
+- **Status:** open, DEBT_ACCEPTED for 5d1 only.
+- **Gate:** F-7, F-5, `deno task doc-lint` from `packages/fresh`.
+
 ## packages/service — doctrine verdict Refactor
 
 - **Reason:** `presets/` and `assets/` need role clarification.

.llm/tmp/doc-lint-fresh-rev2.json

@@ -0,0 +1 @@
+{"source":{"mode":"explicit","root":"packages/fresh","entrypoints":["./builders/mod.ts"]},"summary":{"totalPackages":1,"totalErrors":40,"totalPrivateTypeRef":21,"totalMissingJSDoc":19,"totalOther":0},"packages":[{"name":"@netscript/fresh","dir":"packages/fresh","entrypoints":[{"path":"./builders/mod.ts","privateTypeRef":21,"missingJSDoc":19,"other":0,"total":40}],"files":[{"path":"/home/runner/work/netscript/netscript/packages/fresh/form/types.ts","privateTypeRef":7,"missingJSDoc":17,"other":0,"total":24},{"path":"/home/runner/work/netscript/netscript/packages/fresh/builders/mod.ts","privateTypeRef":12,"missingJSDoc":1,"other":0,"total":13},{"path":"/home/runner/work/netscript/netscript/packages/fresh/builders/define-page/types.ts","privateTypeRef":2,"missingJSDoc":1,"other":0,"total":3}],"combinedTotal":40,"combinedPrivateTypeRef":21,"combinedMissingJSDoc":19,"combinedOther":0}]}

.llm/tmp/doc-lint-fresh.json

@@ -0,0 +1 @@
+{"source":{"mode":"auto","root":"packages/fresh","entrypoints":["./builders/mod.ts","./config/vite.ts","./defer/mod.ts","./error/mod.ts","./form/mod.ts","./interactive.ts","./mod.ts","./query/mod.ts","./route/mod.ts","./server.ts","./streams/mod.ts","./utils/mod.ts"]},"summary":{"totalPackages":1,"totalErrors":276,"totalPrivateTypeRef":115,"totalMissingJSDoc":157,"totalOther":4},"packages":[{"name":"@netscript/fresh","dir":"packages/fresh","entrypoints":[{"path":"./builders/mod.ts","privateTypeRef":21,"missingJSDoc":19,"other":0,"total":40},{"path":"./config/vite.ts","privateTypeRef":3,"missingJSDoc":17,"other":0,"total":20},{"path":"./defer/mod.ts","privateTypeRef":14,"missingJSDoc":46,"other":0,"total":60},{"path":"./error/mod.ts","privateTypeRef":0,"missingJSDoc":0,"other":0,"total":0},{"path":"./form/mod.ts","privateTypeRef":11,"missingJSDoc":60,"other":3,"total":74},{"path":"./interactive.ts","privateTypeRef":0,"missingJSDoc":0,"other":0,"total":0},{"path":"./mod.ts","privateTypeRef":15,"missingJSDoc":8,"other":0,"total":23},{"path":"./query/mod.ts","privateTypeRef":64,"missingJSDoc":23,"other":1,"total":88},{"path":"./route/mod.ts","privateTypeRef":0,"missingJSDoc":0,"other":0,"total":0},{"path":"./server.ts","privateTypeRef":8,"missingJSDoc":5,"other":0,"total":13},{"path":"./streams/mod.ts","privateTypeRef":24,"missingJSDoc":8,"other":0,"total":32},{"path":"./utils/mod.ts","privateTypeRef":0,"missingJSDoc":0,"other":0,"total":0}],"files":[{"path":"/home/runner/work/netscript/netscript/packages/fresh/form/types.ts","privateTypeRef":8,"missingJSDoc":54,"other":0,"total":62},{"path":"/home/runner/.cache/deno/npm/registry.npmjs.org/@tanstack/preact-query/5.101.0/build/modern/_tsup-dts-rollup.d.ts","privateTypeRef":37,"missingJSDoc":12,"other":0,"total":49},{"path":"/home/runner/work/netscript/netscript/packages/fresh/defer/policy.ts","privateTypeRef":1,"missingJSDoc":26,"other":0,"total":27},{"path":"/home/runner/work/netscript/netscript/packages/fresh/config/vite.ts","privateTypeRef":3,"missingJSDoc":17,"other":0,"total":20},{"path":"/home/runner/.cache/deno/npm/registry.npmjs.org/@tanstack/react-db/0.1.85/dist/esm/useLiveQuery.d.ts","privateTypeRef":11,"missingJSDoc":5,"other":0,"total":16},{"path":"/home/runner/work/netscript/netscript/packages/fresh/defer/DeferPage.tsx","privateTypeRef":4,"missingJSDoc":9,"other":0,"total":13},{"path":"/home/runner/.cache/deno/npm/registry.npmjs.org/@tanstack/react-db/0.1.85/dist/esm/useLiveSuspenseQuery.d.ts","privateTypeRef":9,"missingJSDoc":3,"other":0,"total":12},{"path":"/home/runner/work/netscript/netscript/packages/fresh/server/stream-error-boundary.tsx","privateTypeRef":6,"missingJSDoc":5,"other":0,"total":11},{"path":"/home/runner/work/netscript/netscript/packages/fresh/defer/telemetry.ts","privateTypeRef":3,"missingJSDoc":7,"other":0,"total":10},{"path":"/home/runner/work/netscript/netscript/packages/fresh/builders/mod.ts","privateTypeRef":7,"missingJSDoc":1,"other":0,"total":8},{"path":"/home/runner/work/netscript/netscript/packages/fresh/defer/Deferred.tsx","privateTypeRef":4,"missingJSDoc":4,"other":0,"total":8},{"path":"/home/runner/work/netscript/netscript/packages/fresh/form/enhancement.tsx","privateTypeRef":1,"missingJSDoc":4,"other":1,"total":6},{"path":"/home/runner/work/netscript/netscript/packages/fresh/components/ErrorDisplay.tsx","privateTypeRef":2,"missingJSDoc":4,"other":0,"total":6},{"path":"/home/runner/.cache/deno/npm/registry.npmjs.org/@tanstack/query-core/5.101.0/build/modern/_tsup-dts-rollup.d.ts","privateTypeRef":2,"missingJSDoc":3,"other":0,"total":5},{"path":"/home/runner/.cache/deno/npm/registry.npmjs.org/@durable-streams/state/0.2.3/dist/index.d.ts","privateTypeRef":4,"missingJSDoc":0,"other":0,"total":4},{"path":"/home/runner/work/netscript/netscript/packages/fresh/builders/define-page/types.ts","privateTypeRef":2,"missingJSDoc":1,"other":0,"total":3},{"path":"/home/runner/work/netscript/netscript/packages/fresh/form/form.tsx","privateTypeRef":1,"missingJSDoc":1,"other":1,"total":3},{"path":"/home/runner/work/netscript/netscript/packages/fresh/form/form-region.tsx","privateTypeRef":1,"missingJSDoc":1,"other":1,"total":3},{"path":"/home/runner/work/netscript/netscript/packages/fresh/query/query-island.tsx","privateTypeRef":2,"missingJSDoc":0,"other":1,"total":3},{"path":"/home/runner/work/netscript/netscript/packages/fresh/defer/DeferIsland.tsx","privateTypeRef":2,"missingJSDoc":0,"other":0,"total":2},{"path":"/home/runner/work/netscript/netscript/packages/fresh/query/hydration.ts","privateTypeRef":2,"missingJSDoc":0,"other":0,"total":2},{"path":"/home/runner/work/netscript/netscript/packages/fresh/server/stream.ts","privateTypeRef":2,"missingJSDoc":0,"other":0,"total":2},{"path":"/home/runner/work/netscript/netscript/packages/fresh/query/query-client.ts","privateTypeRef":1,"missingJSDoc":0,"other":0,"total":1}],"combinedTotal":276,"combinedPrivateTypeRef":115,"combinedMissingJSDoc":157,"combinedOther":4}]}

.llm/tmp/run/feat-package-quality-wave5-apps--5d-fresh/README.md

@@ -0,0 +1,39 @@
+# Run dir — Wave 5d umbrella (`@netscript/fresh`)
+
+Supervisor-owned umbrella for sub-wave 5d. Contents:
+
+- `plan.md` — **BINDING target architecture** for the whole package: mission,
+  archetype, final entrypoints (12 + `./testing`), final folder shape,
+  quality bar, accepted drift tolerance, sequencing, evaluation protocol.
+  Every 5d sub-plan derives from it.
+- `handover-5d1-plan.md` … `handover-5d6-plan.md` — copy-pasteable PLAN-phase
+  prompts for the six sub-gate generator sessions.
+- `worklog.md` / `commits.md` / `drift.md` — append-only umbrella bookkeeping.
+
+## Sub-gate map
+
+| Gate | Scope | Branch suffix | Worktree | PR |
+|---|---|---|---|---|
+| 5d1 | error · utils · vite · interactive · mod skeleton · doctrine spine | `5d1-support` | `wave5-apps-5d1-support` | #34 |
+| 5d2 | builders (definePage DSL) | `5d2-builders` | `wave5-apps-5d2-builders` | #35 |
+| 5d3 | route (manifest + contract runtime) | `5d3-route` | `wave5-apps-5d3-route` | #36 |
+| 5d4 | defer + streams (+ server streaming internals) | `5d4-streaming` | `wave5-apps-5d4-streaming` | #37 |
+| 5d5 | form (RFC 15, fresh-ui seams) | `5d5-form` | `wave5-apps-5d5-form` | #38 |
+| 5d6 | query + server/defineFreshApp + final surface + wave closeout | `5d6-query` | `wave5-apps-5d6-query` | #39 |
+
+All branches fork from `c64cb16` (5c head post-umbrella-reconcile). PLAN
+phases parallel; IMPLEMENTATION chained 5d1→5d6. Plan review by Fable 5 on
+each sub-PR, then PLAN-EVAL (separate session).
+
+## Publication Protocol For Subagents
+
+Implementation and evaluator agents must run from native WSL ext4 worktrees. They should attempt a
+normal `git push` once after committing. If the shell reports missing GitHub HTTPS credentials
+(`could not read Username for 'https://github.com'`) or `gh` is unavailable/unauthenticated, do not
+repeat unauthenticated pushes. Record the blocker in `drift.md`/`worklog.md`, comment the PR through
+the GitHub connector when available, and hand publication back to the supervisor.
+
+The supervisor may publish branch-visible source/artifact state through the GitHub connector when
+normal shell credentials are absent. Connector-published commits may not preserve local commit SHAs;
+record both local and remote commit IDs explicitly in the run artifacts and PR handoff.
+

.llm/tmp/run/feat-package-quality-wave5-apps--5d-fresh/commits.md

@@ -0,0 +1,8 @@
+# Commits — 5d umbrella
+
+Append-only hash record.
+
+- 8cd6a44: Merge branch feat/package-quality-wave5-apps-5d2-builders into feat/package-quality-wave5-apps-5d-fresh
+- 8a3298d: Merge 5d5 form into 5d supervisor
+- 9241537: Merge 5d6 query into 5d supervisor
+- e0b4b4d: eval(5d6): record query verdict

.llm/tmp/run/feat-package-quality-wave5-apps--5d-fresh/drift.md

@@ -0,0 +1,61 @@
+# Drift — 5d umbrella
+
+Append-only.
+- D-5d-0: sub-branches forked in parallel from c64cb16 instead of split-strategy "fork off prior merge" chain; implementation phases must merge prior landings before starting (recorded in plan.md sequencing).
+
+## D-5d-1 — PLAN dispatch run 1 produced zero artifacts (2026-06-12)
+- All six OpenHands Kimi K2.7 runs on PRs #34-#39 ended without writing any run-dir files; only workflow trace commits landed.
+- Root cause: SDK default max_iteration_per_run=500 exhausted during exploration (5d3-5d6 hit the hard limit; 5d1/5d2 finished with artifacts still pending). agent_runner returned 0 regardless, and the summary-retry prompt led cut-off agents to describe unwritten files as delivered ("Commit hash: TBD"). The 5d4/5d5/5d6 "READY FOR PLAN-EVAL" comments are therefore NOT trustworthy as completion claims, though their measured findings (e.g. 5d4: 113 combined doc-lint errors, abort-propagation gaps in createIncrementalStreamingResponse, plugin-streams coupling divergence) are real exploration output and reusable.
+- Fix: PR #41 to main (iterations= trigger knob, truthful cutoff reporting + exit 3, always() commit-back preserving partial work, early-artifact contract line).
+- Disposition: re-dispatch all six PLAN triggers after PR #41 merges, with iterations raised and/or scope split per trigger.
+
+## D-5d-2 — WSL shell lacks reusable GitHub push credentials
+
+- **What:** 5d1 and 5d4 implementation/evaluator agents repeatedly produced valid local commits but
+  `git push` failed from WSL with `fatal: could not read Username for 'https://github.com': No such
+  device or address`.
+- **Expected:** Subagents commit and push regularly, then comment PR handoff.
+- **Actual:** Source/evaluator state sometimes required GitHub connector comments or connector
+  publication by the supervisor. Connector commits do not preserve local commit SHAs, so artifacts
+  must record both local and remote IDs.
+- **Policy:** Future subagents must attempt push once. If credentials are unavailable, they must
+  record the blocker and hand off publication; the supervisor owns connector publication or PR
+  comment fallback before launching the next dependent subwave.
+- **Status:** open environment/process drift for Wave 5d.
+
+## D-5d-3 — supervisor branch push blocked after local merge
+
+- **What:** The local supervisor branch merged 5d1 and 5d4 successfully, but `git push origin
+  feat/package-quality-wave5-apps-5d-fresh` failed from WSL.
+- **Evidence:** Push failed with `fatal: could not read Username for 'https://github.com': No such
+  device or address` after merge commit `3ae35dc`.
+- **Impact:** Remote PR/branch does not yet contain the supervisor merge. Local native WSL worktrees
+  can still merge the local supervisor branch before subwave implementation starts.
+- **Action:** Supervisor owns publication fallback; subagents must not assume normal push credentials
+  exist in their shell.
+
+
+## D-5d-4 — 5d2 evaluator fallback due app-server usage limit
+
+- **What:** The separate 5d2 IMPL-EVAL app-server session was launched from the native WSL worktree,
+  but Codex app-server returned `usageLimitExceeded` before any evaluator work ran.
+- **Disposition:** Supervisor ran the IMPL-EVAL gates directly from
+  `/home/codex/repos/netscript-wave5-apps-5d2-builders` and posted the PASS verdict to PR #35 as
+  comment `4700202752`.
+- **Evidence:** Evaluated head `aa310dc`; builders tests, builders/form doc-lint, scoped builders
+  check/lint/fmt, scoped builders doctrine scan, and `packages/fresh` publish dry-run all passed.
+- **Impact:** Evaluation independence was preserved operationally by separating implementation from
+  the supervisor-run evaluation evidence, but not by a second active app-server model turn.
+- **Follow-up:** When app-server credits/rate limit reset, prefer a true separate app-server
+  evaluator again. If unavailable, record the fallback and keep all evidence in PR comments.
+
+## D-5d-5 — WSL GitHub SSH publication restored
+
+- **What:** Earlier 5d supervisor and subagent pushes failed through the HTTPS credential helper.
+- **Fix:** WSL Git remotes now use `git@github.com:rickylabs/netscript.git` with SSH key
+  `/home/codex/.ssh/id_ed25519_netscript_wave5` authenticated as `rickylabs`.
+- **Impact:** Future implementation agents must push after every slice from their native WSL
+  worktree. Supervisor should still verify `git ls-remote` after each slice because app-server
+  sessions can hit usage limits before final handoff.
+- **Status:** D-5d-2/D-5d-3 are resolved for current WSL worktrees unless a specific worktree remote
+  regresses to HTTPS.