lossless-openclaw-orchestrator

# Lossless Codex Orchestrator Use this skill when an OpenClaw agent needs to understand or safely manage local Codex sessions through the installed `lco_*` tools. ## Safety Boundary - Prefer local `lco_*` tools through the OpenClaw gateway. - Treat the compact public facade as the normal path; do not rank every declared tool as an equal first step. - Start with public-safe summaries, metadata, refs, and bounded expansion. - Do not read raw transcripts when a `lco_*` describe, expand, final, plan, or touched-file tool can answer the question. - Keep LCO local-only unless the user explicitly exports a public-safe report. - Preserve Codex approval and sandbox gates. OpenClaw approval authorizes the requested LCO action only. - Live resume, send, steer, or interrupt actions require a matching dry-run and `approval_audit_id`. - Claude Code is adapter-stub only in this beta; use Codex-first claims. - Desktop fallback proof is action-bound; do not claim generic GUI mutation. - `cli_visible` or app-server-visible is not the same as Codex Desktop-visible collaboration. Use `lco_codex_desktop_coherence` before making any Desktop visibility claim. - When Desktop visibility is not proven, use `lco_codex_desktop_fallback_status` to inspect CUA-first and Peekaboo-secondary readiness before suggesting any visible fallback path. - Use `lco_codex_collaboration_cockpit` when the user wants one read-only active-lane summary across recent cards, inbox urgency, watcher requests, and supplied Desktop coherence/fallback evidence. - Use `lco_codex_collaboration_next_steps` after the cockpit when you need the exact next bounded tool call. Its packets are read-only suggestions with `execute=false`; do not treat them as approval to run live control or GUI actions. - Use `lco_codex_runtime_desktop_visibility_status` when you need one compact lane-level answer about which Codex Desktop collaboration lanes are covered, partial, or blocked. Treat any returned next tool call as a read-only `execute=false` recommendation, not as approval to mutate the Desktop. - Use `lco_codex_active_thread_state` when you need one compact read-only answer about which active threads are running, blocked, stale, or need a nudge. Use `nextControlDryRun` only as a non-executed dry-run handoff; treat low-confidence or conflicting states as inspect-first, never as approval to send or steer. - `LCO` is the public product abbreviation. New user-facing examples use `lco_*`; the historical `loo_*` names remain maintained compatibility aliases for at least two minor releases and invoke the same targets. Concrete maintained aliases include `loo_search_sessions`, `loo_expand_query`, and `loo_codex_control_dry_run`; prefer the matching `lco_*` names in new output. - `LCO_TOOL_PROFILE=facade|standard|all` filters MCP/OpenClaw tool listing. `facade` lists the compact public path and its `lco_*` aliases, `standard` adds workflow-detail tools such as `lco_doctor`, and `all` remains the default full catalog. - `LCO_TELEMETRY=1` enables opt-in retrieval telemetry only for local search-to-describe/expand correlation. It writes LCO-owned derived cache, requires a telemetry session id for correlation, and does not store raw query text. ## Compact Public Facade Normal agents should start here: 1. `lco_index_sessions` with bounded roots or limits for first-run or stale-index refresh, then `lco_find` for public-safe matches from one query. 2. `lco_prepared_inbox` for the prepared-state operating picture. 3. `lco_describe_ref` for the specific source ref or Codex thread. 4. `lco_expand_query` for one bounded evidence brief when the ref is not known. 5. `lco_recent_sessions` to refresh recent or active cards after a read or approved action. 6. `lco_attention_inbox` for the compact attention queue. 7. `lco_project_digest` for bounded provenance and handoff. 8. `lco_codex_control_route` for one opaque, expiring Codex target or the explicit Desktop-observation route. 9. `lco_codex_deliver` first with `dry_run:true`, then with the identical bindings, `dry_run:false`, and the matching approval id. Use `workflow_detail`, `proof_debug`, and `internal_low_level` tools only when the facade output or a proof/debug task gives you a specific reason. Expert tools remain explicit so blockers, safety state, and proof boundaries can be inspected instead of hidden behind a single magic command. ## Find Active Codex Sessions 1. Call `lco_doctor` to confirm the local DB, Codex stores, and tool readiness. If its `codexJsonlDrift` block reports drift, recall may be incomplete for the flagged files: newer Codex event kinds are being observed that the parser does not extract yet. Treat that as a caveat on completeness claims, not an error. 2. If the index is stale, call `lco_index_sessions` with bounded roots or limits. 3. Call `lco_search_sessions` with a narrow query and a small limit. 4. Prefer returned thread ids, source refs, status, latest timestamp, and safe summary fields over raw event text. ## Describe This Session 1. Use `lco_describe_ref` with `thread_id` for a known Codex thread. 2. Use `lco_describe_ref` with `source_ref` for a source-prefixed ref such as `codex_thread:*`. 3. Summarize status, project, likely objective, blockers, latest assistant closeout, and next safe action. ## Expand 1k/4k 1. Use `lco_expand_session` when you already know the `thread_id`. 2. Use `lco_expand_query` when you have a query and want the best matching ref. 3. Use `profile=brief` or `token_budget=1000` for a quick handoff. 4. Use `profile=evidence` or `token_budget=4000` only when the agent needs a stronger evidence bundle. 5. Stop expanding once the next action is clear. ## Find Plans, Finals, And Touched Files Use the Codex detail tools instead of expanding entire sessions: - `lco_codex_extract` with `kind: "plans"` for proposed-plan blocks and plan refs. - `lco_codex_extract` with `kind: "final_messages"` for latest final assistant messages. - `lco_codex_extract` with `kind: "touched_files"` for files likely touched by the session. - `lco_codex_extract` with `kind: "tool_calls"` when tool metadata matters, without reading full tool call payloads. - `lco_codex_session_management_map` when the agent needs the session-management view before recommending archive, fork, resume, or handoff. ## Route, Dry-Run, And Deliver 1. Call `lco_codex_control_route` to obtain one opaque, expiring target. 2. Call `lco_codex_deliver` with `dry_run:true`. 3. Inspect the target binding, action, `params_hash`, and any `message_hash`. 4. Ask the user to approve that exact target and action. 5. Repeat the identical `lco_codex_deliver` call with `dry_run:false` and the returned `approval_audit_id`. 6. If delivery reports a missing or mismatched audit id, stop and route again; do not repair or reuse the rejected approval. 7. Immediately before a separately approved interrupt, route again and require a fresh active, turn-bound target. An idle delivery changes task state, so never reuse its pre-delivery target for interrupt. Use workflow-detail tools such as `lco_codex_control_dry_run`, `lco_codex_resume_thread`, `lco_codex_send_message`, `lco_codex_steer_thread`, and `lco_codex_interrupt_thread` only when the facade result explicitly routes to that lower-level fallback. ## Check Desktop Coherence 1. Use `lco_codex_app_server_status` and `lco_codex_app_server_threads` for read-only direct/app-server signals. 2. Use `lco_visible_codex_map` only with public-safe visible metadata; do not select, click, type, refresh, restart, or capture screenshots by default. 3. Call `lco_codex_desktop_coherence` with the target `thread_id` or `source_ref` and the public-safe map evidence. 4. Treat `desktop_visible` as a proven visibility state only for the supplied evidence. Treat `cli_visible`, `desktop_refresh_required`, `desktop_restart_required`, and `unknown` as gap states. 5. If visibility is not proven, call `lco_codex_desktop_fallback_status` and route blockers to the desktop fallback lane rather than claiming same-session Desktop collaboration. If fallback status returns `coherence_input_missing`, run the exact `lco_codex_desktop_coherence` `nextToolCall` before retrying fallback readiness. 6. Call `lco_codex_collaboration_cockpit` when the next response should combine recent cards, inbox urgency, watcher requests, and supplied Desktop evidence into one public-safe attention summary. 7. Call `lco_codex_collaboration_next_steps` when you need exact next tool packets for watcher resume requests, Desktop coherence, or fallback-status checks. Execute nothing from the planner unless a later tool has its own approval gate. 8. Call `lco_codex_runtime_desktop_visibility_status` when you need a compact covered/partial/blocked status for runtime Desktop visibility across active lanes. It reports source coverage and next read-only proof steps only. 9. Call `lco_codex_active_thread_state` when you need active-thread state counts and reason codes before recommending attention order. If an item includes `nextControlDryRun`, show it as an `execute=false` dry-run recommendation, not as a live-control approval. ## Recommended Agent Loop 1. Start with `lco_find` when the user gives a query and the index is current, or call `lco_index_sessions` first when the database is new or stale. Start with `lco_prepared_inbox` when the user asks what needs attention. 2. Use `lco_describe_ref` for the selected inbox/source ref. 3. When resuming a known Codex thread, use `lco_prepared_state_status` with `thread_id`; treat `targetCoverage.status=source_present_not_indexed` or `active_session_pending_index` as a cache-refresh route, not as a missing thread or raw-transcript permission. 4. Use `lco_expand_query` with a 1k budget only when the compact card and describe output are not enough. 5. Use `lco_recent_sessions`, `lco_attention_inbox`, or `lco_project_digest` to refresh the operating picture or handoff. 6. Use `lco_doctor`, `lco_search_sessions`, `lco_describe_ref`, `lco_expand_session`, and `lco_codex_extract` only as workflow-detail fallbacks when the facade cannot answer the task. 7. Optionally run `lco_codex_desktop_coherence` when the user asks whether the same work is visible in Codex Desktop 8. If Desktop visibility is not proven, run `lco_codex_desktop_fallback_status` before recommending CUA/Peekaboo work; if it returns `coherence_input_missing`, run the returned coherence call first 9. Run `lco_codex_collaboration_cockpit` when the user wants one active-lane cockpit summary 10. Run `lco_codex_collaboration_next_steps` when the next action needs an exact tool packet instead of prose 11. Run `lco_codex_runtime_desktop_visibility_status` when the user asks what is actually covered for Desktop-visible collaboration right now 12. Run `lco_codex_active_thread_state` when the user asks which active Codex threads are running, blocked, stale, or need a nudge 13. Recommend a next action with source refs 14. If action is requested, run `lco_codex_control_route`, then `lco_codex_deliver` with `dry_run:true` 15. Wait for explicit approval, then repeat the identical delivery with `dry_run:false` and the matching `approval_audit_id` ## Codex Desktop-First Daily Loop Use this loop when the user wants the daily Codex operating picture, active Desktop collaboration state, or a safe next nudge recommendation. 1. Start read-only with `lco_codex_app_server_status`, `lco_codex_app_server_threads`, and `lco_visible_codex_map`. 2. Run `lco_codex_desktop_coherence` before any Codex Desktop-visible claim. Treat `cli_visible`, `desktop_refresh_required`, `desktop_restart_required`, and `unknown` as proof gaps. 3. If coherence exists, use `lco_codex_desktop_fallback_status` for fallback readiness. If it returns `coherence_input_missing`, follow the returned `nextToolCall` for coherence first. 4. Build the daily attention view with `lco_codex_collaboration_cockpit`, `lco_codex_runtime_desktop_visibility_status`, `lco_codex_active_thread_state`, and `lco_codex_autonomy_tick`. 5. For `needs_nudge` or `needs_approval`, show `nextControlDryRun` as an `execute=false` handoff only. Do not run live control from this packet. Treat all autonomy tick steps as recommendations until the requesting user separately asks for and approves the exact action. 6. Live control requires the exact dry-run audit id, matching `approval_audit_id`, and explicit requesting-user approval for the exact target and action. 7. After an approved live action, run post-action refresh before claiming success or updating the operating picture. 8. If proof fails, create an issue-ready public-safe packet instead of pasting raw logs, raw transcripts, screenshots, or unredacted tool evidence. ## Public-Safe Output Shape When reporting to a user or another agent, include: - thread id or source ref - session title or safe summary - status and latest timestamp - proposed plan refs, final-message refs, touched files - why the selected session matters - next safe command or dry-run command - explicit boundaries that remain unproven Do not include raw prompt text, secrets, cookies, tokens, full transcripts, raw SQLite rows, screenshots, or unredacted tool payloads.