lossless-openclaw-orchestrator 0.1.0-beta.49 → 1.0.0

package/README.md

@@ -1,337 +1,413 @@
-# Lossless OpenClaw Orchestrator
+# Orchestrator CCC+L
+
+**Lossless OpenClaw Orchestrator** turns local agent sessions into searchable,
+summarizable, product-management objects for OpenClaw.
+
+3C+L is the working shorthand for **Codex + Claude Code + Lossless**. The beta is
+Codex-first: Claude Code support is intentionally shipped as an adapter stub
+until its storage and control paths are proven.
+
+[Vision](VISION.md) · [Current Sprint Brief](docs/sprints/brief-lco-codex-autonomy-cockpit-sprint-2026-07-01.md) · [Source Authority](docs/SOURCE_AUTHORITY_PROFILE.md) · [Agent Skill](skills/lossless-openclaw-orchestrator/SKILL.md) · [Release Checklist](docs/RELEASE_CHECKLIST.md) · [Working App Proof Sprint](docs/WORKING_APP_PROOF_SPRINT.md) · [OpenClaw Plugin](docs/OPENCLAW_PLUGIN.md) · [Claude Adapter Boundary](docs/CLAUDE_ADAPTER_BOUNDARY.md) · [Beta Demo](docs/BETA_RELEASE_DEMO.md) · [Beta Release Runbook](docs/BETA_RELEASE_RUNBOOK.md) · [Claim Audit](docs/CLAIM_AUDIT.md) · [PolyForm Noncommercial](LICENSE)
+
+## Why This Exists
+
+OpenClaw should be able to manage hundreds of local agent sessions without
+spending its whole context window rereading raw transcripts.
+
+LCO gives an orchestrator agent a staged recall loop:
+
+1. Find likely sessions cheaply.
+2. Describe the session as compact metadata.
+3. Expand only the few sessions that need evidence.
+4. Recommend or dry-run the next action with source refs.
+
+The product goal is not "search all the logs." The goal is to help an
+orchestrator decide what matters next with the least possible token load.
+
+## Product Spine
+
+The core product object is a managed session.
+
+A useful managed session should expose:
+
+- project, status, priority, owner, blocker, and next action
+- proposed-plan refs, final-message refs, and closeout refs
+- touched files, tool metadata, safe summaries, and source refs
+- archive, fork, resume, steer, send, or interrupt recommendations
+- bounded expansion profiles such as metadata-only, brief, and evidence bundle
+
+The current stable path indexes and recalls Codex session evidence. The next
+roadmap push is to make this spine explicit enough that an OpenClaw agent can
+triage, prioritize, and manage many sessions as work objects instead of
+rediscovering state from text every time.
+
+## What Works Now
+
+| Area | Status | Notes |
+| --- | --- | --- |
+| Codex session indexing | Beta | Imports local Codex session JSONL/archive data into local SQLite. |
+| Search / describe / expand | Beta | Supports the staged `grep -> describe -> expand_query` recall loop. |
+| Plans, finals, files, tools | Beta | Extracts proposed plans, final messages, touched files, tool-call metadata, and safe summaries. |
+| MCP / OpenClaw tools | Beta | Exposes `loo_*` tools for OpenClaw and other MCP clients. |
+| OpenClaw LCM peer reads | Experimental | Reads peer summary DBs read-only without merging stores. |
+| Codex direct controls | Beta boundary | Resume/send/steer/interrupt are approval-gated and dry-run first; installed OpenClaw gateway live proof exists only inside its explicit proof boundary. |
+| Desktop fallback | Experimental | CUA Driver and Peekaboo have backend-specific scratch no-focus proof; product GUI mutation still needs an action-bound proof gate. |
+| Scorecards and release proof | Beta | Public-safe scorecards and release-status commands track what is proven. |
+| QA Lab scenarios | Beta | Dry-run scenario contracts under `evals/scenarios/v1` turn orchestrator workflows into public-safe eval tasks. |
+| Working app runtime proof | Completed proof | M7/#156 proved the named runtime path and proof gates; generic GUI mutation, Claude parity, and 1.0 readiness remain excluded. |
+| Codex autonomy cockpit | P0 beta | Recent session cards, cockpit inbox, read-only watcher/resume-request packets, approval packets, and operating-picture tools are public-safe by default. |
+| Eva operating picture | P0 beta | Business pulse and attention inbox use LCO/Codex, optional structured GitHub items, explicit PLAN_STATE pins, and source-authority coverage; P1 business adapters are not configured yet. |
+| Claude Code adapter | Fixture inventory | Supports redacted metadata-only fixtures with `claude_session:*` refs; no Claude parity, live control, GUI mutation, or cloud sync claim. |
+
+## Current Sprint: 1.0 Stable Release Gate
+
+The roadmap is now ranked by one question:
+
+> Does this help an OpenClaw orchestrator manage hundreds of sessions with less
+> context, less rereading, and safer action?
+
+The current release-hardening sprint is tracked by
+[#302](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/issues/302),
+[#182](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/issues/182),
+and
+[#16](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/issues/16).
+The completed Codex Autonomy Cockpit and Eva Operating Picture P0 foundation is
+tracked by
+[#254](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/issues/254),
+[#255](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/issues/255),
+and the historical sprint brief
+[docs/sprints/brief-lco-codex-autonomy-cockpit-sprint-2026-07-01.md](docs/sprints/brief-lco-codex-autonomy-cockpit-sprint-2026-07-01.md).
+
+The core Codex recall, M9 handoff paths, and P0 cockpit/Eva operating-picture
+paths are working. The current release lane is the explicit 1.0 stable
+promotion gate: release metadata, docs truth, strict release gates, public-safe
+scorecards, fresh npm/OpenClaw gateway proof, and a clean line between completed
+P0 cards and deferred P1 adapters. #298 proves the fresh-profile gateway path
+can reach `ready` with scoped token env-ref onboarding and the protocol-4
+backend caller fix; beta.35 published that compatibility fix. #302 owns the
+stable-release lane and must prove any npm `latest` promotion or GitHub Release
+creation against the exact stable candidate SHA.
+
+Completed P0 foundation is read-only and deterministic:
+
+- #254 added `loo_recent_sessions`, `loo_cockpit_inbox`, read-only
+  watcher/resume-request primitives, evidence-backed session cards, and
+  approval packets for dry-run control context.
+- #260 added read-only Codex app-server status/thread signals and
+  `loo_visible_codex_map`, a public-safe join between sanitized visible Codex
+  candidates and indexed session cards.
+- #255 added `loo_plan_state_pins`, `loo_github_operating_items`,
+  `loo_project_digest`, `loo_attention_inbox`, and `loo_business_pulse`.
+- #264 added a deterministic read-only GitHub operating-item collector so
+  issue/PR/check records become public-safe `github_items` before digest tools
+  summarize them.
+- #271 cleaned cockpit-card presentation so agent-facing titles, summaries, and
+  next actions do not expose directive fragments, markdown tables, duplicated
+  labels, or transcript-shaped excerpts.
+- #272 added `eva-operating-picture-dogfood-v1`, an end-to-end public-safe
+  workflow fixture for GitHub check fidelity, recent Codex cards, cockpit
+  ranking, customer/runtime/security priority, source coverage, and P1 gaps.
+- #258 added a public-safe [source authority profile](docs/SOURCE_AUTHORITY_PROFILE.md)
+  so P0 tools distinguish adapter coverage from who owns each truth claim.
+- `PLAN_STATE.md` is demoted to bootloader, manual pins, approval boundaries,
+  stop conditions, and exception ledger. Unmarked prose is not current-state
+  truth.
+- P1 sources such as Notion, support-control, Company Brain, Stripe,
+  dashboard/export, and model summarization remain `not_configured` until
+  separate read-only adapters prove source-backed collection.
+
+What a local OpenClaw agent can do today:
+
+- Search and describe local Codex sessions through `loo_search_sessions` and
+  `loo_describe_session`.
+- Expand bounded evidence with `loo_expand_session` or `loo_expand_query`.
+- Retrieve plans, finals, touched files, and session maps with the Codex detail
+  tools.
+- List recent sessions and operating-picture attention items with
+  `loo_recent_sessions`, `loo_cockpit_inbox`, `loo_github_operating_items`,
+  `loo_project_digest`, `loo_attention_inbox`, and `loo_business_pulse`.
+- Represent watcher-triggered follow-up requests with `loo_watchers_list`,
+  `loo_watcher_status`, `loo_watcher_dry_run`, and
+  `loo_resume_request_packet`; these tools create request packets only and do
+  not run live Codex control.
+- Inspect Codex app-server readiness and visible-to-indexed session correlation
+  with `loo_codex_app_server_status`, `loo_codex_app_server_threads`, and
+  `loo_visible_codex_map`; these tools report source coverage, confidence, and
+  ambiguity without raw turns, screenshots, remote-control enablement, or GUI
+  mutation.
+- Inspect `authorityCoverage` to see whether LCO, GitHub, or PLAN_STATE is
+  authoritative, fallback-only, unavailable, or not configured for a claim.
+- Dry-run Codex control actions and inspect audit ids before any live action.
+- Check package, plugin, gateway, and first-run readiness through `loo_doctor`,
+  `loo onboard status`, `loo openclaw dogfood`, `loo openclaw tool-smoke`, and
+  `loo openclaw published-smoke`. The published-smoke `setupRecovery` block
+  distinguishes clean-profile `ready` proof from credential, device-pairing,
+  scope-approval, token-rotation, generic setup, and package-failure states. A
+  clean-profile credential blocker is first-run setup, not a package failure:
+  the report points to token generation, env-ref onboarding, gateway status, and
+  fresh-profile tool-smoke commands with token placeholders only.
+
+Completed proof:
+
+- The [Working App Proof Sprint](docs/WORKING_APP_PROOF_SPRINT.md) and #156
+  closed the M7 runtime proof lane for the named Codex-first surfaces.
+- M9 closed the first-class agent skill, docs truth pass, agent dogfood,
+  fresh npm clean-profile smoke, and 1.0 readiness gate.
+- #298 proves a clean OpenClaw profile can install a published package and call
+  `loo_doctor` plus `loo_search_sessions` through an isolated loopback token
+  gateway after the protocol-4 backend caller fix. In #302, pre-promotion gates
+  validate the exact packed stable candidate and merged SHA; fresh npm
+  `@latest` published-smoke and general-readiness run only after publication and
+  must pass before the stable issue closes.
+- Desktop fallback remains action-bound; generic GUI mutation and Codex GUI
+  mutation are not public beta claims.
+- Claude Code remains an adapter stub and fixture inventory, not parity.
+
+## Quick Start
+
+Node.js 22 or newer is required.
 
-**LCO turns local Codex sessions into searchable, bounded, approval-aware
-work objects for OpenClaw.**
-
-Use it when an agent or user needs to answer: what sessions are active, what did
-they plan, what did they finish, what files did they touch, and what is the next
-safe action without rereading raw transcripts.
-
-[![npm beta](https://img.shields.io/npm/v/lossless-openclaw-orchestrator/beta?label=npm%20beta)](https://www.npmjs.com/package/lossless-openclaw-orchestrator)
-[![CI](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/actions/workflows/ci.yml/badge.svg)](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/actions/workflows/ci.yml)
-[![CodeQL](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/actions/workflows/codeql.yml/badge.svg)](https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO/actions/workflows/codeql.yml)
-[![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue)](LICENSE)
-[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
-
-[Setup](docs/SETUP.md) · [Contributing](CONTRIBUTING.md) · [Agent Instructions](AGENTS.md) · [Agent Skill](skills/lossless-openclaw-orchestrator/SKILL.md) · [OpenClaw Plugin](docs/OPENCLAW_PLUGIN.md) · [Security](SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Vision](VISION.md) · [Privacy](docs/PRIVACY.md) · [Claude Boundary](docs/CLAUDE_ADAPTER_BOUNDARY.md) · [Claim Audit](docs/CLAIM_AUDIT.md) · [Release Notes](docs/RELEASE_NOTES_1.0.0.md) · [License](LICENSE)
-
-## Why It Matters
-
-Codex is powerful, but long-running local work can become hard to supervise
-once you have dozens or hundreds of threads. LCO gives your orchestrator agent a
-safe operating picture: search first, inspect compact session cards, expand only
-bounded evidence, and dry-run the next action before anything live happens.
-
-If you are here to contribute, start with [CONTRIBUTING.md](CONTRIBUTING.md).
-If you are an agent working in this repository, read [AGENTS.md](AGENTS.md)
-before editing files.
-
-## What It Does
-
-LCO is a local-first orchestration layer for Codex-heavy work:
-
-- indexes local Codex session stores into a local SQLite database
-- searches sessions by safe summaries, plans, finals, touched files, and refs
-- describes one session without exposing the whole transcript
-- expands only the evidence an agent needs, with token-budgeted profiles
-- exposes `loo_*` tools through MCP and the OpenClaw plugin
-- creates dry-run approval packets before Codex resume/send/steer/interrupt
-- reports Codex Desktop visibility and fallback readiness without GUI mutation
-- validates exact action-bound Desktop collaboration proof packets without executing them
-- summarizes runtime Desktop visibility coverage and next read-only proof steps
-- classifies active threads as running, blocked, needs-nudge, stale, waiting,
-  approval-needed, idle, or unknown from public-safe read-only signals,
-  including attention coverage, non-executed read-only probe recommendations,
-  and non-executed control dry-run recommendations for safe nudge handoff
-- plans one deterministic read-only autonomy loop tick with `execute:false`
-  tool calls so an agent can probe before dry-run handoff without mutation
-
-The result is a staged recall loop:
-
-1. Search broadly.
-2. Describe the likely session.
-3. Expand a small evidence bundle.
-4. Dry-run the next action.
-5. Execute only after the user approves the exact target/action.
-
-## Install
-
-Requirements:
-
-- Node.js 22 or newer
-- npm
-- local Codex session files, usually under `~/.codex/sessions`
-- OpenClaw Desktop/CLI if you want installed `loo_*` tools through OpenClaw
+```bash
+git clone https://github.com/100yenadmin/Lossless-Codex-Orchestrator-LCO.git
+cd Lossless-Codex-Orchestrator-LCO
+npm install
+npm run build
+```
 
-Stable install:
+Published stable package target:
 
 ```bash
 npm install -g lossless-openclaw-orchestrator@latest
-loo doctor
 ```
 
-Beta train, when you explicitly want the newest prerelease:
+Published beta package target:
 
 ```bash
 npm install -g lossless-openclaw-orchestrator@beta
 ```
 
-Package channels:
+Release-candidate package target, once `1.0.0-rc.1` is published:
 
-- `latest` is the stable public channel.
-- `beta` is the active prerelease train.
-- `next` is reserved for release candidates.
+```bash
+npm install -g lossless-openclaw-orchestrator@next
+```
 
-Full first-run instructions live in [docs/SETUP.md](docs/SETUP.md).
+### npm dist-tag policy
 
-## Set Up
+Stable users install through `latest`; public betas stay on `beta`; release
+candidates stay on `next`. The first stable release moves `latest` to `1.0.0`
+only after #302 proves the exact candidate through strict release gates. Keep
+prereleases on prerelease tags such as `beta` or `next`. Do not publish a fake stable package just to move a dist-tag.
 
-Choose where LCO stores its local index. The default is already under
-`~/.openclaw`, but setting it explicitly makes setup easier to inspect:
+Default local database:
 
 ```bash
 export LOO_DB_PATH="$HOME/.openclaw/lossless-openclaw-orchestrator/orchestrator.sqlite"
 ```
 
-Index local Codex sessions:
-
-```bash
-loo index codex --max-files 500 "$HOME/.codex/sessions" "$HOME/.codex/archived_sessions"
-```
-
-Optional: allow read-only recall from one or more OpenClaw LCM peer databases:
+Optional read-only OpenClaw LCM peer DBs:
 
 ```bash
 export LOO_LCM_DB_PATHS="$HOME/.openclaw/lcm.db"
 ```
 
-Check local readiness:
+## CLI
 
 ```bash
+loo onboard status --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/onboarding --now 2026-07-01T00:00:00.000Z --strict
 loo doctor
-loo onboard status --strict
+loo index codex --max-files 150 ~/.codex/sessions ~/.codex/archived_sessions
+loo search "proposed plan billing bridge"
+loo grep --lcm-db ~/.openclaw/lcm.db "billing bridge"
+loo describe codex_thread:019f-example
+loo expand-query --profile brief "billing bridge"
+loo sanitize sessions --thread-id 019f-example --repair-plan --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/issue-<number>-sanitizer
+loo serve
 ```
 
-## First Workflow
-
-Search for a session:
+Desktop readiness checks:
 
 ```bash
-loo search "billing bridge proposed plan"
+loo desktop see cua-driver
+loo desktop see peekaboo --snapshot --max-nodes 50
+loo desktop act cua-driver "click primary" # dry-run only in this beta
 ```
 
-Describe a result:
-
-```bash
-loo describe codex_thread:<thread-id>
-```
+Live desktop act requests are intentionally blocked in this beta. Through MCP or
+OpenClaw, `loo_desktop_act` returns structured blockers for missing or
+mismatched action-bound proof fields so an agent can continue through `loo_desktop_live_proof_harness`
+and `loo_desktop_proof_report` without performing GUI mutation.
 
-Expand a bounded brief:
+Scorecard and release proof commands:
 
 ```bash
-loo expand-ref --profile brief --token-budget 1000 codex_thread:<thread-id>
+loo scorecards sweep --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/issue-<number>-scorecard-sweep --strict
+loo eval scenarios --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/issue-<number>-qa-lab-v1 --strict
+loo eval scenarios --scenario-dir evals/scenarios/v1.1 --runtime-proof-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/runtime-proofs --scenario-id openclaw-gateway-live-codex-v1-1 --scenario-id post-action-refresh-reasoning-v1-1 --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/issue-<number>-qa-lab-v1.1 --strict
+loo release preflight --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-preflight
+loo release status --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status --candidate-sha <release-candidate-sha> --approved-live-control-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/approved-live-control-smoke.json --npm-publish-approval-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/npm-approval.json --github-release-approval-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/github-release-approval.json --github-ci-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/github-ci.json --codeql-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/codeql.json
+loo release demo-status --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/demo
+loo release general-readiness --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/general-readiness --fresh-npm-evidence published-package-smoke.json --agent-dogfood-evidence openclaw-tool-smoke.json --strict
 ```
 
-Expand from a query when you do not know the ref yet:
+QA Lab dry-run scenarios live in `evals/scenarios/v1`. Runtime-required working
+app proof scenarios live in `evals/scenarios/v1.1`. The current
+`loo eval scenarios` command validates `v1` dry-run contracts and `v1.1`
+runtime-required proof markers without performing the live actions itself.
+Milestone 7 runtime scenarios stay incomplete until `--runtime-proof-dir`
+contains public-safe `<scenario-id>.runtime-proof.json` markers from the later
+child issues. Use repeated `--scenario-id` flags to scope the sweep to the
+surfaces claimed by the release: a Codex-first working-app claim includes
+`openclaw-gateway-live-codex-v1-1` and
+`post-action-refresh-reasoning-v1-1`; add the desktop or local UI scenario ids
+only when the release copy claims those surfaces.
+
+For a release candidate that intentionally claims only read/search/describe/expand
+plus dry-run control, name the smaller scope explicitly and do not pass
+live-control proof:
 
 ```bash
-loo expand-query --profile brief --token-budget 1000 "billing bridge"
+loo release preflight --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-preflight --strict
+loo release bundle --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-bundle
+loo release demo-status --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/demo --strict
+loo release status --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status --candidate-sha <release-candidate-sha> --npm-publish-approval-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/npm-approval.json --github-release-approval-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/github-release-approval.json --github-ci-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/github-ci.json --codeql-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/codeql.json --strict
 ```
 
-For normal agent workflows, use the MCP/OpenClaw tools:
-
-- `loo_search_sessions`
-- `loo_describe_session`
-- `loo_expand_session`
-- `loo_codex_plans`
-- `loo_codex_final_messages`
-- `loo_codex_touched_files`
-- `loo_codex_control_dry_run`
-
-`loo_codex_control_dry_run` returns the audit id and hashes an agent should show
-before any live resume/send/steer/interrupt call. Live control requires the
-matching `approval_audit_id`.
-
-The packaged agent playbook is
-[skills/lossless-openclaw-orchestrator/SKILL.md](skills/lossless-openclaw-orchestrator/SKILL.md).
+That scope records approved live Codex control and working-app runtime proof as
+excluded claims. Use the default `codex-live-control` scope when the release
+claims live send/resume/steer or interrupt proof but does not yet claim the
+installed gateway plus post-action refresh loop.
 
-## OpenClaw And MCP
-
-Run the MCP server directly:
+Use `codex-working-app-proof` only when the release candidate has both the
+approved live-control proof and public-safe v1.1 runtime marker files from #158
+and #159:
 
 ```bash
-loo-mcp-server
+loo release preflight --claim-scope codex-working-app-proof --runtime-proof-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/runtime-proof --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-preflight --approved-live-control-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/approved-live-control-smoke.json --strict
+loo release status --claim-scope codex-working-app-proof --runtime-proof-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/runtime-proof --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status --candidate-sha <release-candidate-sha> --approved-live-control-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/approved-live-control-smoke.json --npm-publish-approval-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/npm-approval.json --github-release-approval-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/github-release-approval.json --github-ci-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/github-ci.json --codeql-evidence /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status/codeql.json --strict
 ```
 
-Typical MCP client entry:
+Without `openclaw-gateway-live-codex-v1-1.runtime-proof.json` and
+`post-action-refresh-reasoning-v1-1.runtime-proof.json`, that scope fails closed
+with `runtime_proof_missing:*` blockers.
 
-```json
-{
-  "mcpServers": {
-    "lossless-openclaw-orchestrator": {
-      "command": "loo-mcp-server"
-    }
-  }
-}
-```
+The beta proof workflow lives in [docs/BETA_RELEASE_DEMO.md](docs/BETA_RELEASE_DEMO.md).
+The release cadence and approval gates live in
+[docs/BETA_RELEASE_RUNBOOK.md](docs/BETA_RELEASE_RUNBOOK.md).
 
-Install the OpenClaw plugin from npm:
+## Beta Claim Boundary
 
-```bash
-openclaw plugins install lossless-openclaw-orchestrator@latest
-openclaw plugins list --json
-```
+Allowed public beta claim:
 
-Verify the package and OpenClaw gateway path:
+> Control and collaborate with local Codex sessions through OpenClaw using local
+> indexing, bounded recall, and approval-gated controls.
 
-```bash
-loo openclaw dogfood --profile lco-dogfood --install-source lossless-openclaw-orchestrator@latest --required-tool loo_doctor --required-tool loo_search_sessions --strict
-loo openclaw tool-smoke --profile lco-dogfood --required-tool loo_doctor --required-tool loo_search_sessions --strict
-```
+Forbidden beta claims:
 
-OpenClaw gateway setup may require local credential, device-pairing, token, or
-scope approval steps before tool smoke can pass. LCO reports those as setup
-blockers, not package failures. See [docs/SETUP.md](docs/SETUP.md) and
-[docs/OPENCLAW_PLUGIN.md](docs/OPENCLAW_PLUGIN.md).
+- Full Claude Code parity
+- cloud sync
+- unattended desktop takeover
+- bypasses Codex permissions
+- release-grade enterprise security
 
-## Safety Boundaries
+Detailed public-claim checks live in [docs/CLAIM_AUDIT.md](docs/CLAIM_AUDIT.md).
 
-LCO is Codex-first and local-first.
+## MCP / OpenClaw Tools
 
-Default behavior:
+Tool prefix: `loo_*`.
 
-- local SQLite index
-- public-safe summaries before raw expansion
-- source refs instead of raw transcript paths
-- bounded expansion profiles
-- read-only OpenClaw LCM peer DB access
-- direct Codex protocol before desktop fallback
-- dry-run plus matching `approval_audit_id` before live Codex control
+Read/search:
 
-Not claimed:
+- `loo_index_sessions`
+- `loo_grep`
+- `loo_search_sessions`
+- `loo_describe_ref`
+- `loo_describe_session`
+- `loo_expand_session`
+- `loo_expand_query`
 
-- full Claude Code parity
-- cloud sync
-- unattended desktop takeover
-- permission bypass
-- enterprise or customer-ready security claim
-- generic GUI mutation is not supported
-- Codex GUI mutation is not a stable public claim
-
-Claude Code support is an adapter stub and redacted fixture inventory until its
-storage and control paths are proven. Desktop fallback surfaces report
-readiness, blockers, and proof states; they do not authorize prompt typing,
-clicking, refresh/restart automation, or arbitrary app control.
-
-Claude adapter proof boundaries live in
-[docs/CLAUDE_ADAPTER_BOUNDARY.md](docs/CLAUDE_ADAPTER_BOUNDARY.md). Public
-claim details live in [docs/CLAIM_AUDIT.md](docs/CLAIM_AUDIT.md).
-Privacy details live in [docs/PRIVACY.md](docs/PRIVACY.md) and
-[docs/SAFE_SUMMARIES.md](docs/SAFE_SUMMARIES.md).
-
-## Community And Contributing
-
-LCO is meant to be easy to try and safe to improve. The public contribution
-path is:
-
-1. Read [CONTRIBUTING.md](CONTRIBUTING.md) for issue routing, validation,
-   evidence, and agent-authored PR expectations.
-2. Follow [docs/SETUP.md](docs/SETUP.md) for local install and first-run setup.
-3. Use [AGENTS.md](AGENTS.md) when a coding agent is making or reviewing the
-   change.
-4. File a bug, docs bug, feature request, adapter request, protocol drift
-   report, or unsafe-control report through the GitHub issue forms.
-
-Good first issue candidates are docs gaps, redacted fixture coverage, setup
-diagnostics, issue-template improvements, and narrow CLI help fixes. Use the
-adapter request form to request an adapter; describe the target app/runtime,
-read/index path, control boundary, and redacted proof available to test it.
-
-Never paste raw Codex transcripts, private SQLite databases, tokens, cookies,
-connector URLs, or customer data into public issues or PRs. Use
-[SECURITY.md](SECURITY.md) for private vulnerability reports and
-[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations.
+Codex details:
 
-## Architecture
-
-- `packages/core`: SQLite index, Codex import, safe summaries, source refs,
-  extraction, search, and expansion
-- `packages/mcp-server`: stdio MCP server exposing `loo_*` tools
-- `packages/openclaw-plugin`: OpenClaw plugin entry and manifest surface
-- `packages/cli`: `loo` CLI for setup, indexing, recall, smoke, eval, and
-  release gates
-- `packages/adapters`: Codex transport, audit, redaction, CUA/Peekaboo
-  readiness, and adapter boundaries
-- `skills/`: packaged agent-facing OpenClaw playbook
-- `evals/`: scenario and scorecard contracts
-- `docs/`: setup, privacy, release proof, source authority, adapter boundaries,
-  and deeper operator guides
+- `loo_codex_thread_map`
+- `loo_codex_final_messages`
+- `loo_codex_plans`
+- `loo_codex_touched_files`
+- `loo_codex_tool_calls`
 
-## Roadmap And Proof Status
+Approval-gated controls:
 
-The stable public product is Codex-first local orchestration: index, search,
-describe, expand, OpenClaw/MCP tools, and approval-gated dry-run/live-control
-boundaries.
+- `loo_codex_control_dry_run`
+- `loo_codex_resume_thread`
+- `loo_codex_send_message`
+- `loo_codex_steer_thread`
+- `loo_codex_interrupt_thread`
 
-Current deeper product work is tracked in GitHub issues and summarized in
-[VISION.md](VISION.md). Keep sprint and agent-operator details there, in
-[AGENTS.md](AGENTS.md), and in the packaged
-[agent skill](skills/lossless-openclaw-orchestrator/SKILL.md), not in this
-public landing page.
+Desktop fallback:
 
-## Maintainer Proof
+- `loo_desktop_see`
+- `loo_desktop_act`
 
-Release and readiness proof lives in the runbooks, not in the first-run setup
-path:
+Admin:
 
-- [Release Checklist](docs/RELEASE_CHECKLIST.md)
-- [Release Runbook](docs/BETA_RELEASE_RUNBOOK.md)
-- [Claim Audit](docs/CLAIM_AUDIT.md)
-- [QA Demo](docs/BETA_RELEASE_DEMO.md)
+- `loo_doctor`
+- `loo_lcm_peer_dbs`
+- `loo_permissions`
+- `loo_audit_tail`
 
-For `1.0`, the general release checklist requires fresh npm clean-profile
-evidence, agent dogfood evidence through gateway tools, CI, scorecards, and
-claim-audit proof before `latest` promotion.
+OpenClaw setup lives in [docs/OPENCLAW_PLUGIN.md](docs/OPENCLAW_PLUGIN.md).
 
-Versioned proof contracts live in `evals/scorecards/v1.0` and
-`evals/scenarios/v1`; runtime-required scenario contracts live in
-`evals/scenarios/v1.1`.
+## Architecture
 
-Core proof commands:
+- `packages/core`: SQLite schema, Codex import, search, expansion, extraction, source refs.
+- `packages/mcp-server`: stdio MCP tool server.
+- `packages/openclaw-plugin`: OpenClaw plugin metadata and registration.
+- `packages/cli`: `loo` CLI.
+- `packages/adapters`: Codex control, CUA/Peekaboo boundary, Claude Code stub.
+- `evals/scorecards/v1.0`: beta scorecards for safety, retrieval, install, claims, usability, local Mac search UI, and orchestrator leverage.
+- `evals/scorecards/v1.0/working-app-runtime-proof-review.json`: Milestone 7 runtime proof scorecard.
+- `evals/scenarios/v1`: QA Lab dry-run scenario contracts for session map triage, retrieval, bounded expansion, control safety, gateway dogfood, and release claims.
+- `evals/scenarios/v1.1`: runtime-required working-app proof contracts for installed gateway live control, post-action refresh, desktop collaboration, and connected UI proof.
+- `docs/`: install, demo, privacy, safe summaries, release proof, release runbook, and public-claim boundaries.
 
-```bash
-loo scorecards sweep --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/issue-<number>-scorecard-sweep --strict
-loo eval scenarios --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/issue-<number>-qa-lab --strict
-loo release preflight --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-preflight --strict
-loo release demo-status --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/demo --strict
-loo release status --claim-scope codex-read-search-expand-dry-run --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/release-status --candidate-sha <release-candidate-sha> --npm-publish-approval-evidence npm-publish-approval.json --github-release-approval-evidence github-release-approval.json --github-ci-evidence github-ci.json --codeql-evidence codeql.json --strict
-loo release general-readiness --evidence-dir /Volumes/LEXAR/Codex/lossless-openclaw-orchestrator/YYYY-MM-DD/general-readiness --fresh-npm-evidence published-package-smoke.json --agent-dogfood-evidence openclaw-tool-smoke.json --strict
-```
+Direct Codex protocol is preferred for thread work. GUI automation is a fallback
+for visible app collaboration only.
 
 ## Development
 
 ```bash
-npm install
-npm run build
+npm run typecheck
 npm test
+npm run build
 npm run check
 ```
 
-The test suite uses redacted fixtures and Node's built-in test runner. Heavy
-validation is expected to run in CI; local development should use focused tests
-first.
+The test suite uses redacted fixtures and Node's built-in test runner.
+
+Every meaningful issue should include a failing test, fixture, smoke, or eval
+scenario; minimal implementation; focused validation; public-safe evidence; and
+an issue or PR status update.
+
+## Privacy
+
+The default index is local SQLite. The index stores safe text and metadata so
+agents can search and expand bounded evidence. Raw local session files remain
+the source of truth and should not be committed.
+
+Public evidence should contain counts, refs, hashes, statuses, and redacted
+metadata. It should not contain raw transcripts, raw prompts, SQLite databases,
+tokens, cookies, API keys, screenshots, videos, or private customer data.
 
-For contributor workflow details, use [CONTRIBUTING.md](CONTRIBUTING.md).
+See [docs/PRIVACY.md](docs/PRIVACY.md) and [docs/SAFE_SUMMARIES.md](docs/SAFE_SUMMARIES.md).
 
 ## License
 
-Current source and current npm-published versions are source-available under the
+Current source is source-available under the
 [PolyForm Noncommercial License 1.0.0](LICENSE). Noncommercial use is permitted
 under those terms.
 
 Commercial, internal-business, hosted-service, or product use requires a
 separate commercial license from the project owner.
 
-Earlier prerelease artifacts that previously carried MIT metadata are no longer
-published on npm. Any copies already downloaded remain governed by the license
-terms distributed with those copies.
+Historical beta releases published under the MIT License remain available under
+the terms that applied to those releases. This license transition applies
+prospectively to the current source and future releases.