sneakoscope 2.0.17 → 3.0.0

package/README.md

@@ -1,10 +1,31 @@
-# Sneakoscope Codex
+<div align="center">
 
-Fast legacy-free proof-first Codex trust layer with image-based Voxel TriWiki.
+# 🔭 Sneakoscope Codex
 
-Sneakoscope Codex (`sks`) is a Codex CLI/App harness that makes repeatable Codex work auditable.
+**Proof-first Codex orchestration — massive parallel agent swarms you can actually watch, audit, and trust.**
 
-SKS does not try to clone every other harness. It focuses on one thing: making Codex work auditable, visual-evidence-bound, safety-gated, and reproducible through Completion Proof.
+[![npm version](https://img.shields.io/npm/v/sneakoscope?color=cb3837&logo=npm)](https://www.npmjs.com/package/sneakoscope)
+[![node](https://img.shields.io/badge/node-%3E%3D20.11-339933?logo=node.js&logoColor=white)](#requirements)
+[![license](https://img.shields.io/badge/license-MIT-blue)](#license)
+[![zellij](https://img.shields.io/badge/UI-Zellij%20stacked%20panes-1e90ff)](#mad-zellij-launch)
+
+`npm i -g sneakoscope` → `sks --mad` → watch up to **100 shadow-clone workers** code in parallel,<br/>each in a live Zellij pane, every claim backed by Completion Proof.
+
+</div>
+
+---
+
+Sneakoscope Codex (`sks`) is a Codex CLI/App harness that makes repeatable Codex work **auditable**. It does not try to clone every other harness. It focuses on one thing relentlessly: Codex work becomes visual-evidence-bound, safety-gated, and reproducible through Completion Proof.
+
+| | What you get |
+| --- | --- |
+| 🍥 **`$Naruto` swarm** | Up to 100 parallel clone workers behind a hardware-safe concurrency governor, lease-based parallel writes, and a scheduler that backfills idle slots while runnable work remains |
+| 🖥️ **Live Zellij cockpit** | Workers stack vertically as native Zellij stacked panes; each pane streams heartbeat, current file, tool events, and stdout tails every second |
+| 🧾 **Completion Proof** | Every serious route ends with schema-backed proof artifacts — no "trust me, it's done" |
+| 🛡️ **Safety gates** | DB/migration/destructive operations stay gated, 190+ release gate scripts, Honest Mode |
+| 🖼️ **Visual evidence** | Image Voxel TriWiki plus `$imagegen`/`gpt-image-2`-bound visual review flows |
+
+![Sneakoscope Codex Trust Layer](docs/assets/sneakoscope-architecture-pipeline.jpg)
 
 ## LLM Init Prompt for Hermes / OpenClaw Agent Builders
 
@@ -12,47 +33,34 @@ SKS does not try to clone every other harness. It focuses on one thing: making C
 Set up this agent project with Sneakoscope Codex. Use [[mandarange/Sneakoscope-Codex](https://github.com/mandarange/Sneakoscope-Codex)] as the repo reference and [npm i -g sneakoscope] as the recommended global install command, then run the appropriate `sks` setup, doctor, Codex App, and proof checks for this repo. Keep generated SKS state out of source control unless documented, and record every version-facing change in CHANGELOG.md.
 ```
 
-![Sneakoscope Codex Trust Layer](docs/assets/sneakoscope-architecture-pipeline.jpg)
-
-## Current Release
+## 🚀 Current Release
 
-SKS **2.0.17** is the micro-hardening release for strict production PID proof, true scheduler active-time utilization, live Zellij slot telemetry freshness, Mad-DB result lifecycle audit, and unified runtime/release proof summaries.
+SKS **3.0.0** is the parallel-runtime stabilization release. The whole live-swarm experience — what you actually *see* while 5, 20, or 100 workers run — was rebuilt and proven end-to-end.
 
 What changed:
 
-- Zellij slot panes distinguish `slot_status_renderer` panes from Codex worker panes, and the first visible worker now stacks downward below the `SLOTS` anchor with real geometry proof available under `real-check`.
-- Naruto allocation owners now flow into work graph items, scheduler slices, queue ownership, and worker runtime proof; inactive owners are rebalanced and active write conflicts stay out of concurrent execution.
-- Naruto active-pool checks now exercise actual child-worker spawn/result collection paths while production source-of-truth stays with the agent orchestrator scheduler.
-- Worktree candidate output requires GPT Final approval before apply; GPT `modified` output replaces candidate patches and GPT `rejected` blocks apply.
-- Visible Zellij reservations are capped before pane launch so concurrent worker starts cannot over-open the right column.
-- Git worktree integration now proves the primary repo receives validated worktree diffs, with rollback hash evidence recorded around the apply step.
-- Agent role config repair detects stale generated role files and rewrites structured GPT-5.5-compatible configs atomically.
-- Release gates now include slot-only UI, compact slot renderer, headless overflow, role-config repair, worktree primary-runtime, real active-pool, extreme real parallelism, and real right-column geometry checks.
-- Release audit, dynamic selection, and stamp hashing use `release-gates.v2.json` as the manifest source of truth.
-- Git capability checks detect repo roots, Git dirs, worktree support, and safe cache roots while blocking in-repo worktree roots unless `SKS_ALLOW_IN_REPO_WORKTREES=1` is explicit.
-- Worker worktree allocation creates isolated branches/paths under `$SKS_WORKTREE_ROOT`, `$XDG_CACHE_HOME/sks/worktrees`, or `~/.cache/sks/worktrees`; main checkouts stay untouched until integration.
-- Product Design plugin readiness now checks both local and remote Codex App catalogs, auto-installs the remote plugin when needed, and records the installed/enabled skill surface.
-- UI/design/PPT runtime routes prefer Product Design for research, ideation, audit, design QA, prototype, URL-to-code, image-to-code, share, and user-context steps.
-- Naruto read-only runs force write mode off, propagate no-patch reasons through worker proof, and skip changed-file lease checks when no write-capable patch envelope exists.
-- `codex-sdk` is the default native agent backend for Team, QA, Research, Naruto, MAD-SKS, and direct agent runs, with every runtime task entering through `runCodexTask`.
-- Codex App UI snapshot, preservation, clobber guard, and doctor repair checks protect host-owned Fast UI/profile settings around `sks --mad`.
-- Provider context resolves `openai`, `codex-lb`, and `codex-app` with badge/fallback surfaces while avoiding private Codex App UI mutation.
-- UltraRouter writes `ultra-router-proof.json` decisions with tier, scores, hard filters, cache state, and cheapest-good-enough profile selection.
-- Reliability Shield writes `codex-reliability-shield.json` for empty-result retry, stream-idle blocking, tool-result repair, and no-CoT keepalive heartbeats.
-- Raw `codex exec` execution is removed from runtime fallback paths; explicit legacy requests are blocked with `legacy_codex_exec_runtime_removed`.
-- SDK runs write `codex-control-proof.json`, `codex-thread-registry.json`, `codex-sdk-events.jsonl`, and schema-validated worker results.
-- Zellij proof now links `pane_id`, `slot_id`, `generation_index`, `session_id`, `sdk_thread_id`, provider, and `service_tier`.
-- Production runtime scripts are TypeScript source under `src/scripts` and build to `dist/scripts`; Python remains optional diagnostics under `pytools`.
-- Release gates include `codex-control:*`, `ultra-router:*`, `codex-sdk:*`, Codex App Fast UI preservation, provider badges, Zellij spawn-on-demand, slot/pane binding, release truth, and real smoke checks.
-- Research synthesis is now evidence-bound in non-mock runs; deterministic report generation is mock/fallback only.
-- Research quality checks reject repeated paragraphs, template-like prose, low source density, low claim density, and thin implementation sections.
-- Research handoffs now include context, key claims, evidence summary, blueprint sections, parallel work items, acceptance tests, rollback, and source appendix for `$Team` or `$Naruto`.
+- **Slot panes are finally alive.** The watch renderer froze for entire missions because the telemetry snapshot cache never invalidated; snapshot reads are now mtime-aware, multi-process flushes merge instead of clobbering each other, and the disk `updated_at` stays authoritative for stale detection.
+- **One SLOTS column, vertical stack.** Concurrent workers used to race anchor creation and split the screen into N side-by-side columns. Anchor + worker pane creation is serialized per session, and workers join a native Zellij stacked-pane group (`new-pane --stacked`, opt out with `SKS_ZELLIJ_WORKER_STACKED=0`).
+- **Live renderer is the default worker pane.** `full-debug` showed nothing until worker exit (workers run with `--json`); the default `compact-slots` renderer streams heartbeat, current file, tool events, and stdout tails every second.
+- **Zellij stays current like Codex does.** `sks --mad` / `sks naruto run` offer a `[Y/n]` upgrade to the latest stable Zellij (GitHub releases lookup, 6h cache), plus an explicit `sks zellij update [--yes]` subcommand and `SKS_SKIP_ZELLIJ_UPDATE` escape.
+- **Faster, honest dispatch.** Scheduler batch telemetry writes run concurrently per batch instead of serializing two file writes per worker; naruto backpressure throttling (50%/25% under host pressure) is reported in the run header instead of staying silent.
+- **Wired, not decorative.** The naruto finalizer gate and the agent message bus now run in production paths; dead swarm code (`naruto-work-stealing`, `zellij-right-column-layout-proof`) was removed.
 
 Quick checks:
 
 ```bash
 npm run typecheck
 npm run build
+npm run codex:0138-capability
+npm run codex-sdk:version-compat
+npm run codex-app:handoff
+npm run codex-plugin:inventory
+npm run qa-loop:app-handoff
+npm run image:artifact-path-contract
+npm run codex:effort-order
+npm run codex:account-usage
+npm run codex:0138-doctor
+npm run doctor:codex-0138-fix
 npm run codex-control:capability
 npm run codex-control:structured-output
 npm run codex-control:event-stream-ledger
@@ -71,7 +79,7 @@ npm run codex-control:all-pipelines
 
 Broader release checks still live behind `npm run release:check`. Detailed release history is in [CHANGELOG.md](CHANGELOG.md), and release readiness is tracked in [docs/release-readiness.md](docs/release-readiness.md).
 
-## Parallelism, UX, And Integrations
+## 🍥 Parallelism, UX, And Integrations
 
 - **Extreme parallel fan-out (`$Naruto` / native agents).** Each clone is a separate CLI worker that spends almost all of its wall-clock awaiting the Codex API, so live concurrency scales by **memory and the provider rate limit, not CPU cores** — a capable host can run up to 100 workers in parallel. The 429/rate-limit backoff is handled by the centralized responses retry policy. Tune it with `SKS_NARUTO_MAX_CONCURRENCY` (hard cap, 1–100), `SKS_NARUTO_GB_PER_WORKER` (memory budget per worker), and `SKS_NARUTO_MIN_CONCURRENCY` (low-free-memory floor).
 
@@ -97,7 +105,7 @@ Broader release checks still live behind `npm run release:check`. Detailed relea
 
 - **CLI-only SKS update notices.** Codex App hooks no longer stop normal work to ask for an SKS update. CLI launch surfaces such as `sks --mad` print a non-blocking latest-version notice, `sks update-check` / `sks update check` show the explicit status, and `sks doctor --fix` runs the guarded global SKS update path before repair.
 
-## Retention And Cleanup
+## 🧹 Retention And Cleanup
 
 SKS keeps durable learning context separate from disposable route work files. Durable context includes `.sneakoscope/memory/**`, shared TriWiki records, `.sneakoscope/wiki/context-pack.json`, wrongness memory, image voxels, avoidance rules, route Completion Proof, trust reports, evidence indexes, reflections, and agent proof summaries. These files are treated as the long-term learning and audit chain.
 
@@ -112,68 +120,105 @@ npm run retention:cleanup-safety
 
 The cleanup contract is policy-backed in `.sneakoscope/policy.json`, but the default posture is now immediate cleanup for short-lived temp files while preserving long-term SKS learning and proof artifacts.
 
-## Documentation
+## 📚 Documentation
+
+<details>
+<summary><b>Core concepts & architecture</b> — proof, trust, pipeline design</summary>
 
 - Completion Proof: [docs/completion-proof.md](docs/completion-proof.md)
-- TypeScript architecture: [docs/typescript-architecture.md](docs/typescript-architecture.md)
 - Trust Kernel: [docs/trust-kernel.md](docs/trust-kernel.md)
+- Pipeline architecture: [docs/pipeline-architecture.md](docs/pipeline-architecture.md)
+- TypeScript architecture: [docs/typescript-architecture.md](docs/typescript-architecture.md)
+- Runtime truth matrix: [docs/runtime-truth-matrix.md](docs/runtime-truth-matrix.md)
+- Fake vs real proof policy: [docs/fake-vs-real-proof-policy.md](docs/fake-vs-real-proof-policy.md)
+- Core dominance: [docs/core-dominance.md](docs/core-dominance.md)
+- Permission kernel: [docs/permission-kernel.md](docs/permission-kernel.md)
+- Immutable harness guard: [docs/immutable-harness-guard.md](docs/immutable-harness-guard.md)
+- Package boundary: [docs/package-boundary.md](docs/package-boundary.md)
+- Managed paths: [docs/managed-paths.md](docs/managed-paths.md)
+- Performance budgets: [docs/performance-budgets.md](docs/performance-budgets.md)
+- Route finalization: [docs/route-finalization.md](docs/route-finalization.md)
+- Rust accelerator: [docs/rust-accelerator.md](docs/rust-accelerator.md)
+
+</details>
+
+<details>
+<summary><b>Agents & parallelism</b> — Naruto swarm, worker panes, parallel writes</summary>
+
+- Naruto massive parallel swarm: [docs/naruto.md](docs/naruto.md)
+- Native Agent Kernel: [docs/native-agent-kernel.md](docs/native-agent-kernel.md)
+- Native agent engines: [docs/native-agent-engines.md](docs/native-agent-engines.md)
+- Native CLI Session Swarm: [docs/native-cli-session-swarm.md](docs/native-cli-session-swarm.md)
+- No-subagent scaling: [docs/no-subagent-scaling.md](docs/no-subagent-scaling.md)
+- Parallel write agents: [docs/parallel-write-agents.md](docs/parallel-write-agents.md)
+- Agent patch queue: [docs/agent-patch-queue.md](docs/agent-patch-queue.md)
+- Strategy-first parallel write: [docs/strategy-first-parallel-write.md](docs/strategy-first-parallel-write.md)
+- Intelligent work graph: [docs/intelligent-work-graph.md](docs/intelligent-work-graph.md)
+- Agent terminal lanes: [docs/agent-terminal-lanes.md](docs/agent-terminal-lanes.md)
+- Agent cleanup executor: [docs/agent-cleanup-executor.md](docs/agent-cleanup-executor.md)
+- MCP readOnly scheduler: [docs/mcp-readonly-scheduler.md](docs/mcp-readonly-scheduler.md)
+- MAD-SKS: [docs/mad-sks.md](docs/mad-sks.md)
+- MAD-SKS rollback: [docs/mad-sks-rollback.md](docs/mad-sks-rollback.md)
+- ADHD orchestration gate: [docs/adhd-orchestrating-gate.md](docs/adhd-orchestrating-gate.md)
+- Zellij migration: [docs/migration/tmux-to-zellij.md](docs/migration/tmux-to-zellij.md)
+
+</details>
+
+<details>
+<summary><b>Memory & learning</b> — TriWiki, wrongness memory, fixtures</summary>
+
 - TriWiki Wrongness Memory: [docs/triwiki-wrongness-memory.md](docs/triwiki-wrongness-memory.md)
-- Git collaboration: [docs/git-collaboration.md](docs/git-collaboration.md)
-- Git hygiene: [docs/git-hygiene.md](docs/git-hygiene.md)
 - Shared TriWiki: [docs/shared-triwiki.md](docs/shared-triwiki.md)
 - Shared Wrongness Memory: [docs/shared-wrongness-memory.md](docs/shared-wrongness-memory.md)
-- Git policy: [docs/git-policy.md](docs/git-policy.md)
 - Wrongness Learning Loop: [docs/wrongness-learning-loop.md](docs/wrongness-learning-loop.md)
-- Package boundary: [docs/package-boundary.md](docs/package-boundary.md)
-- Black-box package tests: [docs/black-box-package-tests.md](docs/black-box-package-tests.md)
-- Codex CLI compatibility: [docs/codex-cli-compat.md](docs/codex-cli-compat.md)
-- MAD-SKS rollback: [docs/mad-sks-rollback.md](docs/mad-sks-rollback.md)
-- MAD-SKS: [docs/mad-sks.md](docs/mad-sks.md)
-- Permission kernel: [docs/permission-kernel.md](docs/permission-kernel.md)
-- Immutable harness guard: [docs/immutable-harness-guard.md](docs/immutable-harness-guard.md)
+- Image Voxel TriWiki: [docs/image-voxel-ledger.md](docs/image-voxel-ledger.md)
+- Image Wrongness: [docs/image-wrongness.md](docs/image-wrongness.md)
+- Feature fixtures: [docs/feature-fixtures.md](docs/feature-fixtures.md)
+
+</details>
+
+<details>
+<summary><b>Codex integration</b> — App, CLI compat, codex-lb, hooks</summary>
+
 - Codex App: [docs/codex-app.md](docs/codex-app.md)
-- Core dominance: [docs/core-dominance.md](docs/core-dominance.md)
-- Performance budgets: [docs/performance-budgets.md](docs/performance-budgets.md)
-- Native Agent Kernel: [docs/native-agent-kernel.md](docs/native-agent-kernel.md)
+- Codex CLI compatibility: [docs/codex-cli-compat.md](docs/codex-cli-compat.md)
+- Codex official Goal mode: [docs/codex-official-goal-mode.md](docs/codex-official-goal-mode.md)
+- Codex App Hooks/PAT: [docs/hooks-pat.md](docs/hooks-pat.md)
+- codex-lb: [docs/codex-lb.md](docs/codex-lb.md)
 - Source Intelligence Layer: [docs/source-intelligence-layer.md](docs/source-intelligence-layer.md)
 - X AI / Context7 / Codex Web policy: [docs/xai-context7-codex-web-policy.md](docs/xai-context7-codex-web-policy.md)
 - Main no-Scout / worker Scout policy: [docs/main-no-scout-worker-scout-policy.md](docs/main-no-scout-worker-scout-policy.md)
-- Agent terminal lanes: [docs/agent-terminal-lanes.md](docs/agent-terminal-lanes.md)
-- Zellij migration: [docs/migration/tmux-to-zellij.md](docs/migration/tmux-to-zellij.md)
 - Real Codex dynamic smoke: [docs/real-codex-dynamic-smoke.md](docs/real-codex-dynamic-smoke.md)
-- Agent cleanup executor: [docs/agent-cleanup-executor.md](docs/agent-cleanup-executor.md)
-- Intelligent work graph: [docs/intelligent-work-graph.md](docs/intelligent-work-graph.md)
-- Fake vs real proof policy: [docs/fake-vs-real-proof-policy.md](docs/fake-vs-real-proof-policy.md)
-- Runtime truth matrix: [docs/runtime-truth-matrix.md](docs/runtime-truth-matrix.md)
-- ADHD orchestration gate: [docs/adhd-orchestrating-gate.md](docs/adhd-orchestrating-gate.md)
-- Strategy-first parallel write: [docs/strategy-first-parallel-write.md](docs/strategy-first-parallel-write.md)
 - Appshots pipeline: [docs/appshots-pipeline.md](docs/appshots-pipeline.md)
 - Appshots thread attachments: [docs/appshots-thread-attachments.md](docs/appshots-thread-attachments.md)
-- MCP readOnly scheduler: [docs/mcp-readonly-scheduler.md](docs/mcp-readonly-scheduler.md)
-- Parallel write agents: [docs/parallel-write-agents.md](docs/parallel-write-agents.md)
-- Agent patch queue: [docs/agent-patch-queue.md](docs/agent-patch-queue.md)
-- Native CLI Session Swarm: [docs/native-cli-session-swarm.md](docs/native-cli-session-swarm.md)
-- No-subagent scaling: [docs/no-subagent-scaling.md](docs/no-subagent-scaling.md)
 - Fast mode default and `$Fast-On`/`$Fast-Off` toggles: [docs/fast-mode-default.md](docs/fast-mode-default.md)
-- Migration 1.18.7 to 1.18.8: [docs/migration-1.18.7-to-1.18.8.md](docs/migration-1.18.7-to-1.18.8.md)
-- Codex official Goal mode: [docs/codex-official-goal-mode.md](docs/codex-official-goal-mode.md)
+
+</details>
+
+<details>
+<summary><b>Git & collaboration</b></summary>
+
+- Git collaboration: [docs/git-collaboration.md](docs/git-collaboration.md)
+- Git hygiene: [docs/git-hygiene.md](docs/git-hygiene.md)
+- Git policy: [docs/git-policy.md](docs/git-policy.md)
+
+</details>
+
+<details>
+<summary><b>Quality & release</b> — gates, E2E, migrations, gaps</summary>
+
+- Release readiness: [docs/release-readiness.md](docs/release-readiness.md)
 - Release parallel full coverage: [docs/release-parallel-full-coverage.md](docs/release-parallel-full-coverage.md)
 - Priority closure P0-P4: [docs/priority-closure-p0-p4.md](docs/priority-closure-p0-p4.md)
-- Image Voxel TriWiki: [docs/image-voxel-ledger.md](docs/image-voxel-ledger.md)
-- Image Wrongness: [docs/image-wrongness.md](docs/image-wrongness.md)
-- Route finalization: [docs/route-finalization.md](docs/route-finalization.md)
-- Feature fixtures: [docs/feature-fixtures.md](docs/feature-fixtures.md)
-- Managed paths: [docs/managed-paths.md](docs/managed-paths.md)
+- Black-box package tests: [docs/black-box-package-tests.md](docs/black-box-package-tests.md)
+- Hermetic E2E: [docs/testing-hermetic-e2e.md](docs/testing-hermetic-e2e.md)
 - Rollback: [docs/rollback.md](docs/rollback.md)
 - Known gaps: [docs/known-gaps.md](docs/known-gaps.md)
-- Native agent engines: [docs/native-agent-engines.md](docs/native-agent-engines.md)
-- Hermetic E2E: [docs/testing-hermetic-e2e.md](docs/testing-hermetic-e2e.md)
-- Pipeline architecture: [docs/pipeline-architecture.md](docs/pipeline-architecture.md)
-- Rust accelerator: [docs/rust-accelerator.md](docs/rust-accelerator.md)
-- Codex App Hooks/PAT: [docs/hooks-pat.md](docs/hooks-pat.md)
-- codex-lb: [docs/codex-lb.md](docs/codex-lb.md)
+- Migration 1.18.7 to 1.18.8: [docs/migration-1.18.7-to-1.18.8.md](docs/migration-1.18.7-to-1.18.8.md)
+
+</details>
 
-## 60-second start
+## ⚡ 60-Second Start
 
 Recommended install: use the global npm package so `sks` and the Codex App `$` skills are refreshed together.
 
@@ -192,13 +237,13 @@ sks selftest --mock
 sks rust smoke --json
 ```
 
-## Three core promises
+## 🤝 Three Core Promises
 
 1. Completion Proof for every serious route
 2. Image Voxel TriWiki anchors and relations for every visual route
 3. Route contracts, evidence indexes, wrongness memory, trust reports, Codex App, codex-lb, hooks, Rust fallback parity, DB, route modularity, and generated fixtures verified by release gates
 
-## Install
+## 📦 Install
 
 Recommended path:
 
@@ -243,7 +288,7 @@ sks commit --json
 sks selftest --mock
 ```
 
-## What Sneakoscope Adds
+## 🎁 What Sneakoscope Adds
 
 `sks` adds a Zellij-backed Codex CLI runtime, Codex App `$` commands, Team/QA/PPT/Research/DB/GX/Wiki routes, OpenClaw and Hermes skill generation, Context7-gated current docs, TriWiki context packs, DB safety, design SSOT policy, skill dreaming, release checks, and Honest Mode.
 
@@ -279,7 +324,7 @@ Project setup writes shared `.gitignore` entries for generated SKS files: `.snea
 
 During npm postinstall, SKS installs generated Codex App skills and tries `skills add MohtashamMurshid/getdesign` when the `skills` CLI is available. Design work still flows through one authority: `design.md`.
 
-## Terminal CLI Usage
+## 💻 Terminal CLI Usage
 
 Use terminal commands when you want to inspect, set up, verify, or start a CLI-first workspace.
 
@@ -487,7 +532,7 @@ $PPT create a customer proposal deck as HTML/PDF
 
 `$PPT` seals presentation context before artifact work and grounds design in `design.md`, getdesign inputs, and source material. The route loads `imagegen`; when the sealed deck needs generated raster assets or generated slide visual critique, use Codex App `$imagegen`/`gpt-image-2` and record the real output path in the PPT image/review ledgers.
 
-## Codex App Usage
+## 🧩 Codex App Usage
 
 Sneakoscope has two surfaces:
 
@@ -571,7 +616,7 @@ SKS does not install Git pre-commit hooks. Release metadata is changed only by e
 
 TriWiki is intentionally sparse: `sks wiki sweep` records demote, soft-forget, archive, delete, promote-to-skill, and promote-to-rule candidates instead of injecting every old claim into future prompts. `sks harness fixture` validates the broader Harness Growth Factory contract: deliberate forgetting fixtures, skill card metadata, experiment schema, tool-error taxonomy, permission profiles, MultiAgentV2 defaults, and tmux cockpit view coverage. `sks code-structure scan` flags handwritten files above 1000/2000/3000-line thresholds so new logic can be extracted before command files become harder to maintain.
 
-## OpenClaw And Hermes Agent Usage
+## 🤖 OpenClaw And Hermes Agent Usage
 
 Sneakoscope can generate an OpenClaw skill package for agents that need to operate SKS-enabled repositories.
 
@@ -609,7 +654,7 @@ SKS_HERMES=1 sks dollar-commands --json
 SKS_HERMES=1 sks status --json
 ```
 
-## Prompt `$` Commands
+## 💬 Prompt `$` Commands
 
 Use these inside Codex App or another agent prompt. They are prompt commands, not terminal commands.
 
@@ -617,7 +662,7 @@ Common prompts: `$Team`, `$From-Chat-IMG`, `$with-local-llm-on`, `$with-local-ll
 
 `$MAD-DB` is the prompt-visible Mad-DB alias for one-cycle DB break-glass work. It maps to the same guarded MAD-SKS permission route, while the terminal lifecycle remains `sks mad-db status|enable|revoke`; it is not a permanent DB unlock and catastrophic DB safeguards remain active.
 
-## Common Workflows
+## 🔁 Common Workflows
 
 First install:
 
@@ -646,7 +691,7 @@ sks wiki refresh
 sks wiki validate .sneakoscope/wiki/context-pack.json
 ```
 
-## Safety Model
+## 🛡️ Safety Model
 
 Sneakoscope intentionally treats these as high-risk:
 
@@ -658,7 +703,7 @@ Sneakoscope intentionally treats these as high-risk:
 
 By default, SKS favors inspection, local files, branch-safe changes, explicit confirmation for destructive DB operations, and completion claims backed by tests or artifacts.
 
-## Troubleshooting
+## 🔧 Troubleshooting
 
 ### `sks` points to an old version
 
@@ -744,7 +789,7 @@ sks wiki validate .sneakoscope/wiki/context-pack.json
 
 Finalization requires evidence, valid Team cleanup artifacts, reflection when required, and Honest Mode.
 
-## Development And Release
+## 🏗️ Development And Release
 
 Run local checks:
 

package/crates/sks-core/Cargo.lock

@@ -76,7 +76,7 @@ dependencies = [
 
 [[package]]
 name = "sks-core"
-version = "2.0.17"
+version = "3.0.0"
 dependencies = [
  "serde_json",
 ]

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "2.0.17"
+version = "3.0.0"
 edition = "2021"
 
 [dependencies]

package/crates/sks-core/src/main.rs

@@ -4,7 +4,7 @@ use std::io::{self, Read, Seek, SeekFrom};
 fn main() {
     let mut args = std::env::args().skip(1);
     match args.next().as_deref() {
-        Some("--version") => println!("sks-rs 2.0.17"),
+        Some("--version") => println!("sks-rs 3.0.0"),
         Some("compact-info") => {
             let mut input = String::new();
             let _ = io::stdin().read_to_string(&mut input);

package/dist/.sks-build-stamp.json

@@ -1,8 +1,8 @@
 {
   "schema": "sks.dist-build-stamp.v1",
   "package_name": "sneakoscope",
-  "package_version": "2.0.17",
-  "source_digest": "1c6ef84350a97acdfd592ae544ec9054e2ee0a997076e725bc99b771c4693cf2",
-  "source_file_count": 2201,
-  "built_at_source_time": 1780974441836
+  "package_version": "3.0.0",
+  "source_digest": "4404689ab837df49f305f9fa2995c5301fefb9305f47cde1abec4613dcbbfeaa",
+  "source_file_count": 2262,
+  "built_at_source_time": 1781078944628
 }

package/dist/bin/sks.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const FAST_PACKAGE_VERSION = '2.0.17';
+const FAST_PACKAGE_VERSION = '3.0.0';
 const args = process.argv.slice(2);
 try {
     if (args[0] === '--agent' && args[1] === 'worker') {

package/dist/commands/doctor.js

@@ -19,6 +19,10 @@ import { repairCodexAppFastUi } from '../core/codex-app/codex-app-fast-ui-repair
 import { resolveProviderContext } from '../core/provider/provider-context.js';
 import { readLocalModelConfig } from '../core/agents/ollama-worker-config.js';
 import { repairAgentRoleConfigs } from '../core/agents/agent-role-config.js';
+import { writeCodex0138CapabilityArtifacts } from '../core/codex-control/codex-0138-capability.js';
+import { runCodex0138Doctor } from '../core/doctor/codex-0138-doctor.js';
+import { writeCodexPluginInventoryArtifacts, pluginAppTemplatePolicy } from '../core/codex-plugins/codex-plugin-json.js';
+import { writeMcpPluginInventoryArtifacts } from '../core/mcp/mcp-plugin-inventory.js';
 export async function run(_command, args = []) {
     const doctorFix = flag(args, '--fix');
     let setupRepair = null;
@@ -167,6 +171,13 @@ export async function run(_command, args = []) {
         : null;
     const { detectImagegenCapability } = await import('../core/imagegen/imagegen-capability.js');
     const imagegen = await detectImagegenCapability({ codexBin: codexBin || undefined }).catch((err) => ({ ok: false, error: err.message, auth_readiness: null }));
+    const codex0138Capability = await writeCodex0138CapabilityArtifacts(root, { codexBin: codexBin || null }).catch((err) => ({ error: err?.message || String(err), report: null }));
+    const codex0138Doctor = await runCodex0138Doctor(root, { fix: doctorFix }).catch((err) => ({ schema: 'sks.codex-0138-doctor.v1', ok: false, error: err?.message || String(err), blockers: ['codex_0138_doctor_exception'], warnings: [] }));
+    const pluginInventory = await writeCodexPluginInventoryArtifacts(root).catch((err) => ({ error: err?.message || String(err), report: null, artifact: null }));
+    const pluginPolicy = pluginInventory?.report ? pluginAppTemplatePolicy(pluginInventory.report) : null;
+    const mcpPluginInventory = pluginInventory?.report
+        ? await writeMcpPluginInventoryArtifacts(root, { inventory: pluginInventory.report }).catch((err) => ({ error: err?.message || String(err), candidates: null }))
+        : null;
     const pkgBytes = await dirSize(root).catch(() => 0);
     const ready = await writeDoctorReadinessMatrix(root, {
         codex,
@@ -180,10 +191,14 @@ export async function run(_command, args = []) {
         agent_role_config: agentRoleConfigRepair,
         repair: configRepair,
         codex_app_ui: codexAppUi,
+        codex_0138_doctor: codex0138Doctor,
+        codex_plugin_inventory: pluginInventory?.report || null,
+        codex_plugin_app_template_policy: pluginPolicy,
         require_codex_cli_config_load: flag(args, '--fix') || flag(args, '--require-actual-codex'),
         operator_actions: [
             ...(codexConfig.operator_actions || []),
-            ...(configRepair?.operator_actions || [])
+            ...(configRepair?.operator_actions || []),
+            ...(pluginPolicy?.doctor_warnings || [])
         ]
     });
     const zellijReadiness = buildZellijReadiness(root, zellij, ready);
@@ -211,6 +226,13 @@ export async function run(_command, args = []) {
             auth_readiness: imagegen.auth_readiness || null,
             codex_app_builtin_available: imagegen.codex_app?.available === true
         },
+        codex_0138: {
+            capability: codex0138Capability.report || null,
+            doctor: codex0138Doctor,
+            plugins: pluginInventory?.report || null,
+            plugin_app_template_policy: pluginPolicy,
+            mcp_plugin_inventory: mcpPluginInventory?.candidates || null
+        },
         ready,
         sneakoscope: { ok: await exists(`${root}/.sneakoscope`) },
         package: { bytes: pkgBytes, human: formatBytes(pkgBytes) },
@@ -262,6 +284,22 @@ export async function run(_command, args = []) {
                 console.log(`  - ${action}`);
         }
     }
+    const codex0138 = codex0138Capability.report || {};
+    console.log('Codex 0.138 features:');
+    console.log(`  /app handoff: ${codex0138.supports_app_handoff ? 'ok' : 'unavailable'}`);
+    console.log(`  plugin JSON: ${codex0138.supports_plugin_json ? 'ok' : 'unavailable'}`);
+    console.log(`  image path exposure: ${codex0138.supports_image_path_exposure ? 'ok' : 'unavailable'}`);
+    console.log(`  OAuth MCP pre-refresh: ${codex0138.supports_oauth_mcp_prerefresh ? 'ok' : 'unavailable'}`);
+    const plugins = pluginInventory?.report?.plugins || [];
+    const remoteMcpCount = plugins.flatMap((plugin) => plugin.remote_mcp_servers || []).length;
+    const unavailableTemplates = pluginPolicy?.unavailable_app_templates?.length || 0;
+    console.log(`Codex plugins: ${pluginInventory?.report ? 'ok' : 'warning'}`);
+    console.log(`  Remote MCP servers: ${remoteMcpCount} candidates`);
+    console.log(`  Unavailable app templates: ${unavailableTemplates}`);
+    for (const warning of pluginPolicy?.doctor_warnings || [])
+        console.log(`  warning: ${warning}`);
+    if (codex0138Doctor?.fixed?.length)
+        console.log(`  doctor --fix repaired: ${codex0138Doctor.fixed.join(', ')}`);
     console.log(`codex-lb:  ${codexLb.ok ? 'ok' : `warning ${codexLb.circuit?.state || 'unknown'}`}`);
     if (localModel) {
         console.log('Local LLM:');

package/dist/commands/mad-sks.js

@@ -1,10 +1,12 @@
 import { madHighCommand } from '../core/commands/mad-sks-command.js';
 import { ensureMadLaunchDependencies, formatMadLaunchDependencyAction, maybePromptCodexUpdateForLaunch, maybePromptCodexLbSetupForLaunch, maybePromptSksUpdateForLaunch } from '../cli/install-helpers.js';
+import { maybePromptZellijUpdateForLaunch } from '../core/zellij/zellij-update.js';
 import { PACKAGE_VERSION } from '../core/fsx.js';
 export async function run(_command, args = []) {
     return madHighCommand(['--mad-sks', ...args], {
         maybePromptSksUpdateForLaunch,
         maybePromptCodexUpdateForLaunch,
+        maybePromptZellijUpdateForLaunch,
         ensureMadLaunchDependencies,
         printDepsInstallAction: (action) => console.error(formatMadLaunchDependencyAction(action)),
         maybePromptCodexLbSetupForLaunch,

package/dist/commands/zellij.js

@@ -4,6 +4,7 @@ import { projectRoot, readJson } from '../core/fsx.js';
 import { flag } from '../cli/args.js';
 import { printJson } from '../cli/output.js';
 import { checkZellijCapability } from '../core/zellij/zellij-capability.js';
+import { checkZellijUpdateNotice, upgradeZellijToLatest } from '../core/zellij/zellij-update.js';
 import { runZellij } from '../core/zellij/zellij-command.js';
 import { appendZellijLaneCommand, normalizeZellijSlot } from '../core/zellij/zellij-lane-runtime.js';
 import { buildZellijDashboardSnapshot, renderZellijDashboardText } from '../core/zellij/zellij-dashboard-renderer.js';
@@ -22,6 +23,8 @@ export async function run(_command = 'zellij', args = []) {
     const root = await projectRoot();
     if (sub === 'help')
         return printHelp(json);
+    if (sub === 'update' || sub === 'upgrade')
+        return zellijUpdate(args, json);
     if (sub === 'repair')
         return zellijRepair(root, args, json);
     if (sub === 'dispatch' || sub === 'send')
@@ -73,6 +76,58 @@ async function zellijStatus(root, args, json) {
     if (!result.ok)
         process.exitCode = 1;
 }
+async function zellijUpdate(args, json) {
+    const apply = flag(args, '--yes') || flag(args, '-y') || flag(args, '--apply');
+    const notice = await checkZellijUpdateNotice({});
+    if (!apply || !notice.update_available) {
+        const result = {
+            schema: 'sks.zellij-update-command.v1',
+            subcommand: 'update',
+            ok: !notice.error,
+            mode: apply ? 'apply' : 'check',
+            current_version: notice.current_version,
+            latest_version: notice.latest_version,
+            update_available: notice.update_available,
+            zellij_missing: notice.zellij_missing,
+            source: notice.source,
+            upgrade_command: notice.upgrade_command,
+            message: notice.message,
+            next_actions: notice.update_available ? ['Apply with: sks zellij update --yes'] : [],
+            error: notice.error || null
+        };
+        if (json)
+            printJson(result);
+        else {
+            console.log(notice.message);
+            if (notice.update_available)
+                console.log('Apply with: sks zellij update --yes');
+        }
+        if (notice.error && !notice.latest_version)
+            process.exitCode = 1;
+        return;
+    }
+    const upgraded = await upgradeZellijToLatest({});
+    const result = {
+        schema: 'sks.zellij-update-command.v1',
+        subcommand: 'update',
+        ok: upgraded.status === 'upgraded' || upgraded.status === 'installed' || upgraded.status === 'noop',
+        mode: 'apply',
+        status: upgraded.status,
+        before_version: upgraded.before_version,
+        after_version: upgraded.after_version,
+        latest_version: upgraded.latest_version,
+        command: upgraded.command,
+        error: upgraded.error || null
+    };
+    if (json)
+        printJson(result);
+    else if (result.ok)
+        console.log(`Zellij ${upgraded.before_version || 'unknown'} -> ${upgraded.after_version || upgraded.latest_version || 'latest'} (${upgraded.command})`);
+    else
+        console.log(`Zellij update ${upgraded.status}: ${upgraded.error || upgraded.command}`);
+    if (!result.ok)
+        process.exitCode = 1;
+}
 async function zellijFocusWorker(root, args, json) {
     const missionId = resolveMissionId(root, readOption(args, '--mission', readOption(args, '--mission-id', 'latest') || 'latest') || 'latest');
     const slotId = normalizeZellijSlot(readOption(args, '--slot', positionalAfter(args, 'focus-worker') || 'slot-001'));
@@ -265,9 +320,10 @@ function printHelp(json) {
         schema: ZELLIJ_COMMAND_SCHEMA,
         subcommand: 'help',
         ok: true,
-        usage: 'sks zellij status|repair|dispatch|send|focus-worker|worker-logs|dashboard|close-drained [--json]',
+        usage: 'sks zellij status|update|repair|dispatch|send|focus-worker|worker-logs|dashboard|close-drained [--json]',
         subcommands: {
             status: 'Report Zellij runtime capability and interactive-route readiness.',
+            update: 'Check the latest stable Zellij release; apply the upgrade with --yes (Homebrew).',
             repair: 'Explain how to install/repair Zellij (no automatic install).',
             dispatch: 'Append a nonblocking JSONL command for a lane; optionally write to a reconciled pane id with --write-pane.',
             send: 'Alias for dispatch.',
@@ -283,6 +339,7 @@ function printHelp(json) {
     else {
         console.log('sks zellij — inspect and repair the Zellij interactive runtime');
         console.log('  sks zellij status [--require-real] [--json]');
+        console.log('  sks zellij update [--yes] [--json]');
         console.log('  sks zellij repair [--explain] [--json]');
         console.log('  sks zellij dispatch --mission M --slot slot-001 --text "..." [--write-pane] [--json]');
         console.log('  sks zellij focus-worker slot-001 [--mission M] [--json]');