@scotthuang/agent-knock-knock 0.13.18 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.14.1 - 2026-10-10
+
+- Add bounded, redacted public progress to Codex CLI backend and Desktop conversation/task Status: the latest commentary and up to two action summaries share an 800-code-point, grapheme-safe budget. Keep exact Watch turn attribution, native timestamps and read failures explicit; List and terminal screen output are unchanged.
+- Share a 720-minute default monitoring hard deadline across backend and terminal Send/Watch entry points and service fallbacks. Backend Renew uses the hard-timeout configuration; terminal managed Renew retains its independent inactivity window. Existing deadlines, replay identities and accepted callback records are unchanged.
+
+### Validation boundaries
+
+- Verified public progress during an active task, 720-minute Send monitoring, a single local completion acknowledgement, and idempotent Send on macOS with Codex CLI and shared app-server both at 0.162.1. This does not establish a new numeric minimum or claim all native operations were repeated.
+- Desktop behavior is covered by regression tests; Desktop live verification was explicitly skipped for this release. The existing exact supported app/build requirement remains unchanged.
+
+## 0.14.0 - 2026-10-10
+
+### Added
+
+- Control loaded Codex CLI conversations through their shared app-server without tmux, Herdr, or terminal input. Add native discovery, exact task send/Watch, durable completion and interaction callbacks, command/file approvals, blocking and async answers, and per-thread permission settings.
+- Discover Codex Desktop conversations alongside terminal sessions, with search, project filtering, pagination, and separate catalog and live-owner evidence. Keep unloaded and creator-unknown conversations discoverable without treating metadata as permission to send.
+- Send tasks to an exact existing Desktop conversation through its original owner, record a durable send intent, and bind monitoring to the accepted native task. Repeated message IDs and uncertain submissions never automatically resend task text.
+- Add Desktop Status and exact task Watch, with durable completion and manual-attention notifications. Monitoring retains its original native task when a later task starts; stopping a Watch leaves the Desktop task running.
+- Add exact-task Recover, observation Renew, managed Close, and manual Retry Callback for direct Codex CLI and Desktop. Separate stopping observation from closing Send management, retain unresolved submission ownership until explicitly closed, and preserve callback identity and uncertain-outcome boundaries without terminal fallback.
+- Add Desktop command/file approval decisions and blocking questionnaire responses through the original conversation owner, with exact native request and result evidence.
+- Add typed responses for Desktop asynchronous questions in the exact active task, with durable response deduplication, native answer confirmation, and expiry of undelivered obsolete reminders.
+- Add per-conversation Desktop Read Only/Default/Full Access settings, explicit model/effort and Plan/default controls, and exact-task cancellation. Verify effective settings instead of treating acknowledgements as success; report the unavailable model catalog explicitly.
+
+### Changed
+
+- Present unified `conversations[]` for Send, Status, and Watch, preferring a verified Codex backend and preserving eligible terminal fallback. Coalesce only exact native identity matches, keep task/interaction routes fixed, and never replay an uncertain mutation through another transport. Preserve raw CLI provider arrays for diagnostics and existing clients.
+- Apply backend-first capability selection across Codex conversation commands, including permission reads/updates and native interaction actions. Allow targeted Status and other eligible operations to resolve an idle terminal through the existing exact native status inspection; preserve no-input List, bound task/interaction identities, and terminal-only lifecycle semantics.
+- Default Desktop List to persisted expanded sidebar membership, with explicit `desktop_view: "history"` / `--desktop-view history` for the broader historical catalog. Keep unconnected rows visible and report unsupported layouts without falling back to history; live counts describe the current page only.
+
+### Fixed
+
+- Recover missed Codex Desktop asynchronous-question notifications by reading questions from native messages as well as pending requests.
+- Preserve exact legacy terminal identifiers and explicit managed-only operations through conversation routing. Keep routing reservations independent of managed Store writer locks so eligible physical Send retains its existing compatibility and lock ordering.
+
+### Compatibility
+
+- Review direct CLI operations on macOS with Codex CLI `0.160.0` and shared app-server `0.162.0`. The local CLI and daemon installation observed at `0.162.1` on 2026-10-10 is not a new end-to-end verification or a numeric minimum; runtime identity and protocol checks determine direct-control availability.
+- Require the reviewed macOS Codex Desktop `26.1002.52244` build `13536` for native writes through its private IPC. This exact build is not a minimum-version promise. Loading inactive conversations and launching replacement CLI sessions remain unsupported.
+- Preserve the existing tmux and Herdr adapters and their terminal-specific interaction controls.
+- Keep Pi and DeepSeek Harness connector releases independent. Their current manifests still pin AKK `0.13.3`; releasing the core package does not upgrade those connector runtimes.
+
 ## 0.13.18 - 2026-10-04
 
 - Adapt Codex 0.160.0 async-question Option-key hints while preserving exact versioned input checks and older keymaps.

package/CONTRIBUTING.md

@@ -0,0 +1,212 @@
+# Contributing
+
+Thanks for taking the time to improve Agent Knock Knock.
+
+## Development Setup
+
+Use Node.js 22.19 or newer; Node.js 24 is recommended. GitHub Actions runners are intentionally disabled during the current rapid-iteration phase, so pull requests must include the local verification results described below. The supported Node.js boundary remains part of release compatibility even though GitHub does not currently run a hosted matrix.
+
+```bash
+npm ci
+npm run build
+npm run test:fast
+```
+
+The fast tier is the only test tier for normal development, review, and local
+installation, as required by [AGENTS.md](AGENTS.md). Do not run integration or
+full suites merely to open a pull request. Full/release tests are reserved for
+the immediate gate before an actual npm or ClawHub publication. See
+[docs/testing.md](docs/testing.md) for the tier manifest and release workflow.
+
+For local OpenClaw testing, link the plugin from this checkout:
+
+```bash
+openclaw plugins install --link .
+openclaw plugins enable agent-knock-knock
+openclaw gateway restart
+```
+
+## Checks
+
+Before opening a pull request, run:
+
+```bash
+npm run typecheck
+npm run test:fast
+npm pack --dry-run
+```
+
+`npm run test:fast` includes the build and Skill consistency check. `npm test`
+is an alias for `test:full` and belongs to release validation, not this
+development loop. Build, type checking, architecture/evidence validators, and
+non-test packaging checks do not authorize a broader test tier.
+
+The pull request description is the verification record while hosted Actions
+are disabled: include the local Node.js version, exact commands, pass counts,
+and any intentionally skipped credentialed smoke. `package.json` currently has
+no separate lint script, so use `git diff --check` as the whitespace/patch
+format gate and report that fact explicitly.
+
+Routine releases verify the current build-pinned OpenClaw host through
+`npm run test:release`. Run the complete isolated host matrix periodically and
+whenever a declared OpenClaw compatibility floor changes:
+
+```bash
+npm run compat:openclaw
+```
+
+The complete matrix derives the supported Host, Plugin API, and build versions
+from `package.json`, then verifies the adjacent failing API boundary. It uses
+only temporary OpenClaw state and does not make credentialed coding-agent
+turns.
+
+If your change touches logging, callbacks, or trace output, also review the output for secrets and local-only data. Trace output must not expose agent thinking text, raw callback payloads, gateway tokens, API keys, passwords, or proxy credentials.
+
+## Native Lifecycle Live-Smoke Diagnostic
+
+This optional diagnostic runs a fresh real-agent check in addition to the
+deterministic suite. The runner uses existing authenticated coding-agent
+processes and can incur API cost. It never launches, upgrades, restarts, kills,
+or arbitrarily selects a process, and ordinary `npm test` never invokes it.
+During the current rapid-iteration phase, npm and ClawHub publishing do not
+require this diagnostic or consume its evidence.
+
+Prepare one supported Codex pane and one supported Claude Code pane in tmux.
+Both must be idle with an empty composer and have no active Turn, approval,
+callback, dispatch, or lifecycle transition. Record each exact target, tmux
+pane PID, and running agent version:
+
+```bash
+tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_pid} #{pane_current_command}'
+npm run build
+node dist/src/cli.js list --terminal-debug
+```
+
+Each starting native thread `A` must already be persisted by its agent as an
+exact same-workspace resume candidate. In particular, a newly launched Codex
+composer with no completed native turn is not a safe origin: `/clear` can erase
+its only identity before Codex writes a resumable thread row and rollout. Seed
+that pane with one harmless native turn, wait until it is idle, and verify the
+thread is listed before running the diagnostic. The diagnostic's internal New preflight
+rechecks unique Session ownership and a fresh candidate token before `/clear`.
+Do not type in either selected pane while the matrix is running: AKK's locks
+serialize AKK operations, but they cannot fence direct human tmux input.
+
+Keep the evidence outside the repository. The worktree must be clean because
+the result is bound to `git rev-parse HEAD` and the current `package.json`
+version. The runner also fingerprints its compiled JavaScript before and after
+the matrix and fails closed if it changes. Run the complete matrix with both
+explicit opt-ins:
+
+```bash
+AKK_RUN_LIVE_LIFECYCLE_SMOKE=1 npm run smoke:lifecycle -- \
+  --confirm-live \
+  --codex-target <session:window.pane> \
+  --codex-expected-pane-pid <pane-pid> \
+  --codex-expected-version <codex-version> \
+  --claude-target <session:window.pane> \
+  --claude-expected-pane-pid <pane-pid> \
+  --claude-expected-version <claude-version> \
+  --evidence </absolute/private/path/live-lifecycle-evidence.json>
+```
+
+Omit all three `--claude-*` arguments for a Codex-only diagnostic run, or all
+three `--codex-*` arguments for a Claude-only run. Complete matrix evidence
+still requires both agents.
+
+The runner reports one of three outcomes:
+
+- `passed`: the exact pane completed `A → new B → one Send in B → resume A`
+  and finished idle on A with the same process and workspace.
+- `failed`: a check failed with a proven outcome. Inspect the named pane and
+  evidence before deciding whether to run again.
+- `uncertain`: AKK cannot prove whether submitted terminal input completed.
+  Do not rerun the lifecycle command. Inspect that exact pane, run
+  `node dist/src/cli.js list --terminal-debug`, and recover manually with only
+  the newly advertised exact action once the current native thread is known.
+
+The persisted starting thread `A` may already have a managed AKK Session or
+may be an unmanaged, verified native thread. Evidence records that distinction
+explicitly.
+For an unmanaged start, New has no source Session, creates `B` at binding
+generation 1, and exact Resume materializes a new Session for `A` at generation
+1. For a managed start, exact Resume returns to the same `A` Session and advances
+its binding generation by exactly one. Neither lifecycle operation may create a
+Turn in either path.
+
+The JSON contains only allowlisted diagnostic facts and salted fingerprints. It
+does not contain prompts, replies, transcripts, raw native/Session/Turn/
+transition/binding IDs, callback payloads, or credentials. A non-passing run
+still writes evidence for diagnosis, but it cannot pass local verification.
+
+To validate passing evidence against the exact clean commit locally:
+
+```bash
+release_version="$(node -p "require('./package.json').version")"
+release_commit="$(git rev-parse HEAD)"
+
+npm run smoke:lifecycle:attest -- \
+  --evidence </absolute/private/path/live-lifecycle-evidence.json> \
+  --expected-version "${release_version}" \
+  --expected-commit "${release_commit}" \
+  --require-matrix \
+  --max-age-hours 72
+```
+
+The verifier and attestation format remain available so a mandatory release
+gate can be restored later without redesigning the lifecycle evidence model.
+
+### Opt-in monitor fault injection
+
+#93 adds a separate liveness check to the #88 diagnostic contract. Run it only
+against a disposable, already managed Turn while the OpenClaw Gateway and its
+AKK plugin service are running:
+
+1. Start one real background Turn in an explicitly selected idle tmux pane and
+   retain its `state_path` and `event_log_path` from the send result.
+2. From that Turn's event log, read the latest
+   `terminal_bridge_monitor_launch.pid`. Verify it is neither the tmux pane PID
+   nor the Codex/Claude process PID, then terminate only that monitor process.
+3. Do not invoke AKK `status`, `list`, or `reconcile-monitors`. Let the native
+   Turn finish normally.
+4. Within 30 seconds after durable completion, while the Store remains
+   writable, require evidence for `terminal_bridge_monitor_exit_observed`, a
+   `terminal_bridge_monitor_launch` whose reason is
+   `unexpected_exit_recovery`, and the replacement
+   `terminal_bridge_monitor_started`. The detached child and supervisor append
+   their records independently, so do not require those diagnostic records to
+   have a total ordering. Require exactly one
+   `terminal_bridge_completion_detected`, exactly one
+   `terminal_bridge_completion_claimed`, and one immutable `done` callback or
+   outbox entry.
+5. Verify the replacement kept the same Session, Turn, terminal binding ID and
+   binding generation. A changed binding must fence the old monitor instead of
+   completing the Turn.
+
+This scenario deliberately kills only AKK's detached monitor. It does not
+weaken the lifecycle runner's promise never to launch, restart, upgrade, or
+kill a coding-agent process. Store-lock fault injection is deterministic in the
+test suite: holding `.akk-writer.lock` beyond ten seconds must produce a
+deferred diagnostic, resume after release, and never be reported as binding
+supersession.
+
+## Adding a Terminal Agent Adapter
+
+- Implement the `TerminalAgentAdapter` interface defined in `src/terminal-agent-adapter.ts`, including process classification, screen parsing, declared capabilities, ordered approval keys, ordered cancellation keys, and any screen or durable completion detection.
+- Add the complete adapter once to `productionTerminalAgentAdapters` in `src/terminal-agent-registry.ts`. Unsupported capabilities must stay disabled so the bridge fails closed.
+- Keep tmux discovery, capture, and input in `TerminalControlProvider`; agent-specific prompt and completion parsing belongs in the adapter.
+- Add adapter and bridge tests covering discovery, agent-aware IDs, status, send, cancel, approval revalidation and key order, monitoring, completion, and disabled capabilities. Keep legacy `terminal:tmux:<target>:<pid>` IDs working as Codex.
+
+## Pull Requests
+
+- Keep changes focused on one behavior or feature.
+- Include tests for CLI behavior, protocol changes, callback delivery, or trace parsing.
+- Update `README.md` or `CHANGELOG.md` when user-visible behavior changes.
+- Do not commit `dist/`, `node_modules/`, runtime logs, local OpenClaw state, or `.env` files.
+- Complete the pull request checklist and attach local typecheck, full test, package, and compatibility results. When hosted Actions are re-enabled, the Node.js 22 and 24 jobs become required again.
+
+For installation and usage help, see [SUPPORT.md](SUPPORT.md).
+
+## Security Reports
+
+Do not report vulnerabilities through public issues. See `SECURITY.md`.

package/README.md

@@ -2,204 +2,144 @@
 
 [![npm](https://img.shields.io/npm/v/%40scotthuang%2Fagent-knock-knock)](https://www.npmjs.com/package/@scotthuang/agent-knock-knock)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.19-339933)](https://nodejs.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/scotthuang/agent-knock-knock/blob/main/LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Agent Knock Knock lets **OpenClaw, Pi, or DeepSeek Harness** control Codex and Claude Code already running in **tmux or Herdr**. Watch work without staring at a remote terminal, send the next instruction from chat, and get callbacks when the coding agent finishes or needs attention.
+**Let your agent orchestrate the coding conversations you already use.**
+AKK lets a controller such as OpenClaw discover your conversations, send tasks,
+and receive completion or question notifications while you stay in chat.
 
-AKK never launches a hidden replacement agent. The controller Host, the human, and AKK all use the same visible terminal and native coding-agent session.
+**Codex CLI shared-backend connections and Codex Desktop work without tmux or
+Herdr.** AKK controls the original conversation, so you see the same work in
+Codex. Claude Code and applicable Codex terminal workflows use tmux or Herdr.
+AKK does not launch a hidden replacement agent.
 
-**Stay in the terminal. Stay in control. No hooks. No agent-side plugins. No YOLO.**
+AKK 0.14.0 introduces Codex CLI shared-backend control, Codex Desktop support,
+unified conversation routing, and exact-task recovery. **0.14.1 adds bounded
+public progress in Status and shared 12-hour monitoring defaults.** See the
+[release notes](CHANGELOG.md#0141---2026-10-10) for changes and validation limits.
 
-## Install for OpenClaw
+## What you can do
 
-You need OpenClaw `2026.6.5`+, Node.js `22.19.0`+, and an authenticated `codex` or `claude` CLI running as the same OS user.
+- **Find and select conversations** by project and title. Desktop also lists
+  saved sidebar entries that are not connected; those rows cannot receive tasks.
+- **Send and follow an exact task**, or Watch work you started yourself.
+  Results and attention notifications return to the initiating controller.
+- **Answer supported questions, approve requests, and set permissions** through
+  the selected provider's advertised actions. Desktop also supports explicit
+  model settings and exact task cancellation.
+- **Recover monitoring and callback failures** without resending the task.
+  [Backend Recovery](docs/backend-task-recovery.md) distinguishes Recover,
+  Renew, Close, Unwatch, and Retry Callback.
 
-```bash
-openclaw plugins install clawhub:@scotthuang/agent-knock-knock
-openclaw gateway restart
-```
-
-Start a shared coding-agent terminal in your project:
-
-```bash
-cd /absolute/path/to/project
-tmux new-session -s akk-work -c "$(pwd -P)" codex
-```
-
-Use `claude` instead of `codex` if preferred. Herdr users can follow the [Herdr quick start](docs/quickstart-herdr.md).
-
-In OpenClaw, first send:
-
-```text
-/akk doctor
-```
+## Quick start with OpenClaw
 
-After `AKK doctor: ready`, send a separate message:
+Use Node.js `22.19.0`+, OpenClaw `2026.6.5`+, and an authenticated coding agent
+under the same OS user as AKK.
 
-```text
-/akk inspect this repository and summarize it
-```
-
-That is the complete first-task flow. For terminal setup and multiple panes, see the [tmux quick start](docs/quickstart-tmux.md). Direct `/akk ...` commands need no OpenClaw tool-policy changes.
-
-## Install for Pi
+### 1. Install AKK
 
-Pi can be the controller Host without OpenClaw. The current connector targets Pi `0.84.4`:
+Use ClawHub for the OpenClaw plugin, including the 0.14 backend and Desktop
+features:
 
 ```bash
-npm install -g @earendil-works/pi-coding-agent@0.84.4
-pi install npm:@scotthuang/agent-knock-knock-pi@next
-pi
-```
-
-Pi should show `AKK ready`. With Codex or Claude Code already running in tmux or Herdr, enter `/akk list`. The connector provides `/akk`, the complete capability-handshake-verified semantic tool catalog, the bundled `agent-knock-knock` skill, callbacks to the initiating Pi session, and native approval dialogs. See the [Pi connector guide](connectors/pi/README.md).
-
-## Install for DeepSeek Harness
-
-The connector supports DeepSeek Harness Web `0.1.1-rc.2`, `0.1.2-alpha.1`, and
-`0.1.5-rc.2`:
-
-```bash
-dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@next
-dsh web
+openclaw plugins install clawhub:@scotthuang/agent-knock-knock
+openclaw gateway restart
 ```
 
-Open a Web conversation and enter `/akk list`. The connector gives every conversation `/akk`, the same capability-handshake-verified semantic tool catalog, the bundled `agent-knock-knock` skill, and callbacks to the exact Harness Agent that initiated the work. See the [DeepSeek Harness connector guide](connectors/deepseek-harness/README.md).
-
-## See It in Action
+The [installation guide](docs/openclaw-operations.md#choose-one-installation-path)
+also covers npm. Building a reviewed checkout is optional; see
+[local development installation](docs/openclaw-operations.md#local-development-build).
+Choose one installation path per OpenClaw profile.
 
-[![AKK orchestrating a Claude Code-to-Codex handoff through tmux](https://raw.githubusercontent.com/scotthuang/agent-knock-knock/main/docs/assets/akk-tmux-handoff-demo.gif)](https://github.com/scotthuang/agent-knock-knock/blob/main/docs/assets/akk-tmux-handoff-demo.mp4)
+### 2. Make your conversation available
 
-*OpenClaw asks Claude Code to write a file, waits for AKK to report completion, then hands the result to Codex. Both terminals remain available for direct human control. Click the preview for the full-quality video.*
+- **Codex CLI direct:** keep a main CLI conversation connected to a reachable
+  local shared backend. No terminal container is required. An embedded backend
+  or unloaded history is not a direct-control target; see the
+  [CLI guide](docs/codex-cli-native-compatibility.md).
+- **Codex Desktop:** open the intended local conversation in the reviewed app
+  build. A saved conversation with no verified live owner must be opened in
+  Desktop before AKK can send to it. See the [Desktop guide](docs/codex-desktop-compatibility.md).
+- **Claude Code or Codex terminal control:** follow the [tmux](docs/quickstart-tmux.md)
+  or [Herdr](docs/quickstart-herdr.md) quick start, including `/akk doctor`.
 
-## What AKK Gives You
+### 3. List, select, and send
 
-Suppose several Codex or Claude Code jobs are already running in tmux or Herdr:
-
-Codex CLI 0.158.0/0.159.0/0.159.2/0.159.3/0.160.0 supports exact paginated task Watches for ordinary terminal
-Send, native question responses, and durable completion callbacks. The adapter
-checks the foreground thread and server version before attaching; uncertain
-answers are never automatically replayed. See the [0.158.0/0.159.0/0.159.2/0.159.3/0.160.0 compatibility
-review](docs/codex-0.160.0-compatibility.md) for managed-session and already-open
-question boundaries. Codex 0.157.x retains its [partial compatibility](docs/codex-0.157.1-compatibility.md).
-
-- **Watch without babysitting.** `/akk watch <terminal>` observes work already in progress and sends a callback when it finishes, needs approval, or becomes blocked. You can leave the terminal and continue from your phone or another chat client.
-- **Send without typing in a tiny remote console.** `/akk <selector>: <message>` sends your natural-language instruction to the selected live coding-agent terminal. An explicit user Send has priority over stale AKK management state.
-- **Identify an ambiguous Codex foreground explicitly.** When several rollout files or a recent `/clear` prevent durable attribution, an advertised foreground-identification action can inspect one exact idle pane without guessing which rollout is current.
-- **Set Codex permissions before a task.** `/akk permissions <exact-terminal-id>` reads the current setting and native choices; `/akk set-permissions <exact-terminal-id> <advertised-mode-id>` applies your selected mode to that idle session and verifies it before Send. Full Access works like the other options; AKK handles its native confirmation automatically without an extra user prompt. See [Codex permissions](docs/codex-permissions.md).
-- **Switch models through the native catalog.** `/akk models <exact-terminal-id>` lists the choices currently offered by one exact physical Codex or Claude Code pane; a Codex rollout/native-thread attribution is not required, so this also works before the first rollout materializes. `/akk set-model ...` consumes one exact advertised model/reasoning-effort tuple without accepting raw slash commands, keys, or menu indexes. Codex synchronizes the model and ordinary efforts through `max` to the current and future-session defaults; its `ultra` effort is current-session-only, and the native UI does not expose the exact non-Ultra effort chosen for future sessions, so AKK omits that unobservable field. Claude Code changes only the current session.
-- **Continue or clear only a proven model-control residue.** If a failed profiled Codex 0.154.0/0.155.1 model-control attempt leaves an exact `/model` completion surface or bare `/model` Composer, a fresh List may advertise both `/akk models <exact-terminal-id>` and `/akk repair-model-control <exact-terminal-id>`. Models uses a separate residual-bound authority to continue that exact native slash command into read-only catalog discovery without retyping it. If the exact native picker is already open, List marks the pane non-idle and advertises repair only. Repair remains the cleanup-only escape hatch, never presses Enter, and must prove an empty Composer.
-- **Inspect and recover.** `/akk status <turn-or-watch>` shows current state when a callback is delayed. Durable callback records and Watches provide a recovery path after transient Host failures.
-- **Approve deliberately.** AKK can surface Codex or Claude Code permission requests and submit an explicit human decision. It preserves the coding agent's existing permission mode.
-- **Hand control back and forth.** Attach to the same tmux or Herdr pane whenever you want. AKK does not create a parallel hidden conversation.
-
-The common workflow is:
+In your OpenClaw chat, send:
 
 ```text
 /akk list
-/akk watch <exact-terminal-id>
-/akk models <exact-terminal-id>
-/akk set-model <exact-terminal-id> <advertised-model-id> <advertised-reasoning-effort>
-/akk codex: run the tests and explain any failures
-/akk status <turn-id-or-watch-id>
 ```
 
-If List advertises `repair-model-control`, it is an alternative cleanup flow:
+Then send a separate message asking OpenClaw to use the listed conversation:
 
 ```text
-/akk repair-model-control <exact-terminal-id>
-/akk list
-/akk models <exact-terminal-id>
-/akk set-model <exact-terminal-id> <advertised-model-id> <advertised-reasoning-effort>
+Use AKK to send “Summarize this project's test setup” to the Codex conversation
+for my-project, and tell me when that task finishes.
 ```
 
-Use identifiers and actions from a fresh `/akk list`; do not guess or cache terminal IDs. Model switching is fail-closed: the same exact physical pane/process must still be free of an active Turn or any input-owning approval, questionnaire/editor, or read-only viewer, and must show either an exact idle empty Composer or one stable profiled Codex 0.154.0/0.155.1 `/model` residual. A profiled Codex 0.154.0/0.155.1 zero-rollout pane does not require `identify_foreground` or a resolved native rollout identity; Claude Code still requires its exact current native Session. When List advertises both actions for a Composer residual, `model_options` may continue it into the catalog while `repair_model_control` only clears it. An open exact picker is non-idle and exposes repair only. If continuation, repair, or model switching reports `uncertain`, inspect the pane instead of retrying automatically.
+If several rows match, select the exact listed conversation. The controller
+uses its returned ID and available Send action; you do not need to choose a
+transport. Enable [natural-language tool routing](docs/openclaw-operations.md#optional-natural-language-routing)
+if your OpenClaw tool policy restricts AKK. Direct `/akk ...` commands do not
+require that policy change.
 
-## How It Works
-
-```text
-OpenClaw / Pi / DeepSeek Harness
-              │
-       AKK Host adapter
-              │
-   Session · Turn · Watch · Callback
-              │
-         tmux / Herdr
-              │
-      Codex / Claude Code
-```
+Keep the returned task/Watch ID to query `/akk status <id>` later. To observe
+work already running, ask OpenClaw to Watch that listed conversation. A
+callback accepted by OpenClaw does not itself prove delivery to WeChat or
+another downstream channel.
 
-For a managed Send, AKK verifies the selected terminal and coding-agent process, writes one user request, monitors that exact Turn, and returns completion or attention callbacks to the initiating Host session. If stale AKK bookkeeping blocks an explicit Codex Send before terminal input, AKK can fall back to a verified one-time physical Send and attach a task Watch for callback and Status recovery.
+## Compatibility at a glance
 
-Native Pi and DeepSeek Harness connectors accept the shared catalog through a
-versioned, secretless Host Adapter capability handshake. Startup verifies the
-ordered semantic tool registration and the bundled Skill against catalog and
-Skill SHA-256 digests; an older, missing, or drifted handshake fails closed
-instead of mounting a partial tool surface. Connector package versions remain
-independent of one another.
+These are distinct provider boundaries, not a blanket minimum Codex version.
 
-In the current OpenClaw plugin and core Host Adapter, an idle Codex pane with ambiguous foreground rollout identity may advertise `identify_foreground`. That action issues one closed `/status` command to the exact pane. It does not mutate the AKK Store, but it does type into the visible terminal. Its 30-second result is diagnostic only and grants no later authority. The separate `identify_and_send` action keeps one terminal lock across the probe and one requested task, then relies on exact request acceptance—not the status card—for durable Session and Turn identity. List and Status never run this probe. Codex 0.158.0/0.159.0/0.159.2/0.159.3/0.160.0 exact Send and active-task Watch use a separate closed `/status` transaction to bind the foreground paginated thread; subsequent observation is read-only.
-
-AKK is local-first: there is no hosted control plane or telemetry. It stores only the local state needed for routing, lifecycle recovery, callback delivery, and idempotency.
-
-## Compatibility
-
-| Component | Supported boundary |
+| Connection | Requirements and verified scope |
 | --- | --- |
-| Terminal hosts | tmux; local Herdr `0.8.0` protocol `19` |
-| Coding agents | Codex and Claude Code; unknown complete versions are allowed with a compatibility warning and fail naturally if behavior changed |
-| OpenClaw | `2026.6.5`+; plugin API and Gateway `2026.5.12`+ |
-| Pi connector | Pi `0.84.4` |
-| DeepSeek Harness connector | `0.1.1-rc.2`, `0.1.2-alpha.1`, and `0.1.5-rc.2` |
-| Runtime | Node.js `22.19.0`+ on macOS or Linux |
-
-The adjacent OpenClaw boundary `2026.5.10-beta.2` is intentionally unsupported. Herdr support is exact-version because its local control protocol is not yet a stable public API. See each connector guide for its tested release status and limitations.
+| **Codex CLI direct** | Loaded main CLI thread on a compatible local shared backend. Live-tested on **macOS: CLI 0.160.0 + app-server 0.162.0**. Runtime identity/protocol checks determine availability; no numeric minimum has been established. |
+| **Codex Desktop** | Verified **macOS app 26.1002.52244, build 13536**, bundle `com.openai.codex` at `/Applications/ChatGPT.app`. Native writes require that **exact version/build** and a verified live owner. |
+| **Codex / Claude Code terminals** | tmux or local Herdr **0.8.0 / protocol 19**. Reviewed Codex TUI profiles include **0.160.0**; Claude Code **2.1.285** was verified on macOS arm64. Operations depend on the agent version and current UI. |
+| **OpenClaw / runtime** | OpenClaw **2026.6.5+**, plugin API/Gateway **2026.5.12+**; Node.js **22.19.0+**. Core terminal support targets macOS/Linux; the Desktop profile is macOS-only. |
+
+Additional targeted verification on 2026-10-10 used **CLI 0.162.1 + backend
+0.162.1** for public Status progress, 12-hour Send monitoring and an isolated
+completion callback. Other native capabilities were not repeated in that run.
+Frontend and backend versions need not match. The [CLI evidence](docs/codex-cli-native-compatibility.md#compatibility-and-limits)
+and [Desktop profile](docs/codex-desktop-compatibility.md#version-and-platform-evidence)
+separate current observations, tested operations, and unsupported cases.
+
+Direct CLI currently lacks model control, cancellation, and native new/resume
+operations. Some can use a verified terminal capability; others, including
+paginated Codex new/resume, remain unsupported. Desktop has no terminal fallback
+and cannot create or cold-load conversations. Backend busy/blocked states or
+uncertain execution never trigger a retry through another transport. See
+[routing and operation limits](docs/codex-cli-native-compatibility.md#automatic-conversation-routing-2026-10-10).
+
+## Other controller Hosts
+
+[Pi](connectors/pi/README.md) and [DeepSeek Harness](connectors/deepseek-harness/README.md)
+have independent connector packages and installation guides. Their current
+package manifests pin AKK **0.13.3**; their published capabilities must not be
+inferred from this 0.14 README. See each guide for its reviewed
+Host versions, callbacks, and upgrade procedure.
 
 ## Documentation
 
-Choose the guide that matches what you are trying to do:
-
-| Guide | Use it for |
+| Guide | What it covers |
 | --- | --- |
-| [tmux quick start](docs/quickstart-tmux.md) | First OpenClaw task, multiple panes, and selectors |
-| [Herdr quick start](docs/quickstart-herdr.md) | Local Herdr discovery and exact-version checks |
-| [Pi connector](connectors/pi/README.md) | Pi installation, semantic tool catalog, bundled skill, native approval, callbacks, upgrade, and uninstall |
-| [DeepSeek Harness connector](connectors/deepseek-harness/README.md) | Harness installation, approval contract, callbacks, upgrade, and troubleshooting |
-| [Operator guide](docs/operator-guide.md) | Complete command reference, reliable Send, Watch, Status, approval, recovery, Sessions, and native threads |
-| [OpenClaw operations](docs/openclaw-operations.md) | npm alternative, configuration, auto-approval policy, supervisor behavior, and troubleshooting |
-| [Host Bridge and Profiles](docs/host-bridge-profiles.md) | Connect another controller Host through MCP/stdio and a declarative Profile |
-| [Terminal handoff protocol](docs/bidirectional-agent-protocol.md) | Identity, Turn lifecycle, callback guarantees, safety fences, and handoff semantics |
-| [Storage and logging](docs/storage-and-logging.md) | State directories, permissions, protocol migration, logs, and privacy |
-| [Testing](docs/testing.md) | Test tiers, architecture checks, and evidence workflows |
-| [Contributing](CONTRIBUTING.md) | Local development and contribution workflow |
-
-## Installation Alternatives
-
-OpenClaw users who prefer npm can install the same core package directly:
-
-```bash
-npm install -g @scotthuang/agent-knock-knock
-agent-knock-knock install-openclaw --verify
-```
-
-ClawHub remains the recommended OpenClaw path. Do not install both variants into the same OpenClaw profile.
-
-To build the repository locally:
-
-```bash
-npm install
-npm run build
-npm run test:fast
-```
-
-Connector development uses `npm run pi:build` from the repository root, or `cd connectors/pi && npm run build`; DeepSeek Harness has the matching `npm run deepseek:build` script.
-
-## Security and Privacy
-
-AKK controls terminals, so treat installation as privileged local automation. Use an unprivileged OS account, restrict tmux and Herdr sockets, keep the state directory private, and review approval prompts before allowing input. Ordinary AKK Send does not change agent permissions. The explicit Codex permission tool applies only the user-selected native mode; model-facing tools never receive terminal-control tokens, callback credentials, Composer text, or approval fingerprints.
-
-Report vulnerabilities privately using [GitHub Security Advisories](https://github.com/scotthuang/agent-knock-knock/security/advisories/new). Please do not include secrets, private terminal output, or credentials in a public issue.
-
-## License
-
-[MIT](LICENSE)
+| [CLI direct control](docs/codex-cli-native-compatibility.md) | Discovery, sending, Watch, interactions, routing, and version evidence |
+| [Codex Desktop](docs/codex-desktop-compatibility.md) | Sidebar discovery, live-owner requirements, native controls, and tested build |
+| [Backend Recovery](docs/backend-task-recovery.md) | Exact-task recovery, renewal, Close versus Unwatch, and callback retry |
+| [tmux](docs/quickstart-tmux.md) · [Herdr](docs/quickstart-herdr.md) | Terminal setup and the first task |
+| [Operator guide](docs/operator-guide.md) | Command reference, terminal models/lifecycle, identity, and advanced controls |
+| [OpenClaw operations](docs/openclaw-operations.md) | Installation, tool policy, configuration, and troubleshooting |
+| [Codex permissions](docs/codex-permissions.md) | Terminal permission choices and verification |
+| [Host Bridge](docs/host-bridge-profiles.md) | Connect another controller through MCP/stdio and a Host Profile |
+| [Storage and logging](docs/storage-and-logging.md) | Local state, privacy, logs, and protocol migration |
+| [Testing](docs/testing.md) · [Contributing](CONTRIBUTING.md) | Development checks and contribution workflow |
+
+AKK runs locally, with no hosted control plane or telemetry. Send preserves the
+agent's permissions; explicit settings and approval actions apply the user's
+choice. Keep local control sockets and AKK state private. Report vulnerabilities
+through [GitHub Security Advisories](https://github.com/scotthuang/agent-knock-knock/security/advisories/new).
+
+[MIT license](LICENSE).

package/connectors/deepseek-harness/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Knock Knock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.