lean-computer-use 0.0.0-stage → 0.1.0

package/desk/desk-clean

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""desk-clean <bundle_id> [--app-name NAME] [--launched-by-run]: release run state."""
+import argparse
+import json
+import math
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+from _resolve import (CACHE, DRIVER_MARKER, OWN_FILES, STATE, DeskError,
+                      driver_command, driver_status, state_is_ours)
+
+
+def own_files():
+    if not STATE.exists():
+        return []
+    return [path for path in STATE.iterdir() if (OWN_FILES.fullmatch(path.name) or path.name == DRIVER_MARKER)
+            and not path.is_symlink() and path.is_file()]
+
+
+def read_json(path):
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        return value if isinstance(value, dict) else {}
+    except (ValueError, OSError):
+        return {}
+
+
+def cached_name(bundle_id, files, cache):
+    entry = cache.get(bundle_id)
+    if isinstance(entry, dict) and entry.get("name"):
+        return entry["name"]
+    # Some callers retain a launch result. Match its bundle before using its name.
+    launches = [path for path in files if path.name.startswith("launch_app-")]
+    for path in sorted(launches, key=lambda path: path.stat().st_mtime, reverse=True):
+        launch = read_json(path)
+        detail = launch.get("detail")
+        detail = detail if isinstance(detail, dict) else {}
+        if (launch.get("bundle_id") or detail.get("bundle_id")) == bundle_id:
+            name = launch.get("name") or detail.get("name")
+            if name:
+                return name
+    return None
+
+
+def is_running(escaped, timeout):
+    """Ask macOS itself: the display name need not match the process name."""
+    try:
+        result = subprocess.run(["osascript", "-e", f'application "{escaped}" is running'],
+                                capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise DeskError("osascript is-running check timed out") from None
+    answer = result.stdout.strip()
+    if result.returncode or answer not in ("true", "false"):
+        raise DeskError("osascript is-running check failed")
+    return answer == "true"
+
+
+def quit_app(name):
+    if (not isinstance(name, str) or not name.strip() or name.startswith("-")
+            or any(ord(char) < 32 or ord(char) == 127 for char in name)):
+        raise DeskError("valid --app-name required when no cached launch name is available")
+    wait = float(os.environ.get("DESK_CLEAN_WAIT_S", "5"))
+    if not math.isfinite(wait) or not 0 <= wait <= 5:
+        raise DeskError("DESK_CLEAN_WAIT_S must be between 0 and 5")
+    quit_wait = float(os.environ.get("DESK_CLEAN_QUIT_TIMEOUT_S", "5"))
+    if not math.isfinite(quit_wait) or not 0 < quit_wait <= 5:
+        raise DeskError("DESK_CLEAN_QUIT_TIMEOUT_S must be above 0 and at most 5")
+    escaped = name.replace("\\", "\\\\").replace('"', '\\"')
+    try:
+        # A failed or slow quit command is not the verdict: the is-running poll is.
+        subprocess.run(["osascript", "-e", f'quit app "{escaped}"'],
+                       capture_output=True, text=True, timeout=quit_wait)
+    except subprocess.TimeoutExpired:
+        pass
+    deadline = time.monotonic() + wait
+    while True:
+        if not is_running(escaped, min(5, max(0.5, deadline - time.monotonic()))):
+            return "quit"
+        if time.monotonic() >= deadline:
+            return "still-running"
+        time.sleep(min(0.05, max(0, deadline - time.monotonic())))
+
+
+def clean_state(bundle_id, files, cache):
+    removed = 0
+    cache.pop(bundle_id, None)
+    for path in files:
+        if path == CACHE and cache:
+            # Keep other bundles' identities. Atomic replacement keeps mode 0600.
+            fd, name = tempfile.mkstemp(prefix="apps-", suffix=".json", dir=STATE)
+            temporary = Path(name)
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                    json.dump(cache, handle, ensure_ascii=False)
+                    handle.write("\n")
+                os.replace(temporary, CACHE)
+            finally:
+                temporary.unlink(missing_ok=True)
+        else:
+            try:
+                # Recheck immediately before removal, just like the prune rule.
+                if not path.is_symlink() and path.is_file():
+                    path.unlink()
+                    removed += 1
+            except FileNotFoundError:
+                pass
+    return removed
+
+
+def stop_driver():
+    try:
+        sessions = driver_command("sessions")
+        running = driver_status()
+        if running is False:
+            return "already-stopped"
+        if running is None or sessions.returncode:
+            return "stop-failed"
+        if sessions.stdout.strip().rstrip(".") != "No live sessions":
+            return "left-running-live-sessions" if sessions.stdout.strip() else "stop-failed"
+        # Only the driver's graceful stop command may stop the shared daemon.
+        driver_command("stop")
+        deadline = time.monotonic() + 5
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return "stop-failed"
+            if driver_status(min(2, remaining)) is False:
+                return "stopped"
+            time.sleep(min(0.1, max(0, deadline - time.monotonic())))
+    except DeskError:
+        return "stop-failed"
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("bundle_id")
+    parser.add_argument("--app-name")
+    parser.add_argument("--launched-by-run", action="store_true")
+    options = parser.parse_args()
+    app, rc, error = "left-open", 0, None
+    try:
+        refused = STATE.exists() and not state_is_ours()
+        files = [] if refused else own_files()
+        cache = read_json(CACHE) if CACHE in files else {}
+        if options.launched_by_run:
+            try:
+                name = options.app_name or cached_name(options.bundle_id, files, cache)
+                app = "still-running" if name else "left-open"
+                app = quit_app(name)
+                rc = 3 if app == "still-running" else 0
+            except (DeskError, ValueError, OSError, subprocess.TimeoutExpired) as failure:
+                rc, error = 2, failure
+        removed = clean_state(options.bundle_id, files, cache)
+        driver = stop_driver()
+        if driver == "stop-failed":
+            rc = 3
+        print(f"cleanup: app={app} state_files_removed={removed} "
+              f"remaining_own_files={len(own_files())} driver={driver}")
+        if refused and not error:
+            error = DeskError("refusing to delete: state dir lacks .desk-state marker, "
+                              "is not owned by this user or is not mode 0700")
+        if error and driver != "stop-failed":
+            raise DeskError(str(error))
+        if error:
+            print("desk-clean: " + str(error).replace("\n", " ").replace("\r", " "), file=sys.stderr)
+        return rc
+    except (DeskError, ValueError, OSError) as failure:
+        print("desk-clean: " + str(failure).replace("\n", " ").replace("\r", " "), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/desk/desk-read

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""desk-read <bundle_id> [filter] [--max N]: compact query read plus full JSON file."""
+import argparse
+import json
+import sys
+from _resolve import DeskError, redact, run_tool, save_json
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("bundle_id")
+    parser.add_argument("filter", nargs="?", default="AXStaticText")
+    parser.add_argument("--max", type=int, default=40)
+    options = parser.parse_args()
+    if options.max < 0:
+        parser.error("--max must be nonnegative")
+    try:
+        rc, result, pid, wid, cached = run_tool(options.bundle_id, "get_window_state", {
+            "include_screenshot": False, "query": options.filter,
+        })
+        path = save_json(result, prefix="tree")
+        tree = str(result.get("tree_markdown") or "") if isinstance(result, dict) else ""
+        lines = [safe.strip() for raw, safe in zip(tree.splitlines(), redact(tree).splitlines())
+                 if options.filter.lower() in raw.lower()]
+        print(f"pid={pid} window={wid} cached={cached} shown={min(len(lines), options.max)}/{len(lines)} "
+              f"bytes={path.stat().st_size} file={json.dumps(str(path))}")
+        for line in lines[:options.max]:
+            print(redact(line))
+        if rc or isinstance(result, dict) and result.get("error"):
+            print("desk-read: cua-driver read failed; see saved JSON", file=sys.stderr)
+            return rc or 1
+        return 0
+    except (DeskError, OSError) as error:
+        print("desk-read: " + str(error).replace("\n", " "), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/desk/exit-codes.json

@@ -0,0 +1,13 @@
+[
+  {"command":"desk","exit":"0","test":"test_pid_window_cache_second_call_does_not_launch_app"},
+  {"command":"desk","exit":"1","test":"test_error_result_without_driver_failure_exits_one"},
+  {"command":"desk","exit":"2","test":"test_invalid_arguments_exit_two_without_desktop_call"},
+  {"command":"desk","exit":"other nonzero","test":"test_driver_failure_exit_code_is_preserved"},
+  {"command":"desk-read","exit":"0","test":"test_desk_read_filters_compact_lines_and_saves_full_json"},
+  {"command":"desk-read","exit":"1","test":"test_error_result_without_driver_failure_exits_one"},
+  {"command":"desk-read","exit":"2","test":"test_invalid_arguments_exit_two_without_desktop_call"},
+  {"command":"desk-read","exit":"other nonzero","test":"test_driver_failure_exit_code_is_preserved"},
+  {"command":"desk-clean","exit":"0","test":"test_clean_launched_by_run_quits_with_explicit_name"},
+  {"command":"desk-clean","exit":"2","test":"test_clean_missing_name_fails_safely_and_still_cleans_state"},
+  {"command":"desk-clean","exit":"3","test":"test_clean_still_running_exits_three_and_removes_state"}
+]

package/docs/INSTALLER.md

@@ -0,0 +1,62 @@
+# Installer contract
+
+## Commands
+
+| Command | Behavior |
+|---|---|
+| `npx lean-computer-use` | Preview an install and ask for confirmation. |
+| `npx lean-computer-use install --yes` | Apply the previewed install without a prompt. |
+| `npx lean-computer-use install --with-hooks` | Also merge marked native hook registrations. |
+| `npx lean-computer-use install --dir <path> --share <path>` | Use explicit host and share roots. |
+| `npx lean-computer-use uninstall` | Remove unchanged files recorded in the manifest. |
+| `npx lean-computer-use --uninstall` | Alias for `uninstall`. |
+| `npx lean-computer-use install --dry-run` | Show the same action plan with no writes. |
+| `npx lean-computer-use uninstall --dry` | Preview removal; `--dry` equals `--dry-run`. |
+
+Default host root: `~/.claude`.
+Default share root: `~/.local/share/lean-computer-use`.
+`LEAN_COMPUTER_USE_HOME` overrides the default share root; `--share` takes precedence.
+`--dir` and `--share` may name absolute target roots.
+Recorded paths inside each root must remain relative, contained and free of symlinks.
+
+## Install ownership
+
+The installer writes the skill under `skills/lean-computer-use`, the runner under `agents/desk-runner.md`, and desk tools and hook files under the share root.
+It copies packaged `briefs/desk-brief.md` to `<claude dir>/skills/lean-computer-use/desk-brief.md` as an owned skill file, with the same hash, backup and removal rules.
+It replaces `__DESK_DIR__` in the runner with the installed desk directory.
+Desk scripts are executable.
+It records paths, file hashes and created directories in `<share>/install-manifest.json`.
+
+The installer previews before mutation and asks `y/N` unless `--yes` is supplied.
+A non-interactive install requires `--yes`.
+A differing existing file is preserved unless replacement is approved with `--yes`; replacement keeps a `.bak`.
+The manifest records enough ownership information to preserve or restore prior content on removal.
+The installer never installs third-party tools, runs vendor logins, or changes global settings without confirmation.
+
+## Hook merge
+
+`--with-hooks` backs up `settings.json`, preserves all other keys and registrations, and adds marked entries idempotently.
+MCP native tools and Bash have separate matchers.
+The Bash handler checks that the first word of a command segment is `desk`, `desk-read` or `desk-clean` before it applies native behavior.
+Uninstall removes only entries carrying this install's marker.
+If the snippet was pasted manually, inspect the printed manual steps and remove only those pasted entries yourself.
+
+## Safe removal
+
+Uninstall reads the manifest and rechecks each target before unlinking it.
+Removal budget: uninstall removes every file the installer wrote that still matches its recorded hash; a file you edited stays in place and is listed for review.
+Traversal, absolute recorded paths and symlink targets are refused.
+It removes a directory only when this install created it and it is empty.
+The manifest is removed last.
+Backups of replaced content are restored according to their recorded ownership.
+
+`--dry-run` performs the same validation and reports the same planned actions without writing.
+With no manifest, uninstall exits 2 and names the missing manifest path.
+Restore the manifest from your backup or follow its reported manual cleanup steps after reviewing each file.
+Do not delete a shared skill directory or an entire settings file as a substitute.
+
+## Verification
+
+`test/installer.test.mjs` exercises temporary roots, dry runs, replacement backup, settings merge, edited-file preservation and install/uninstall restoration.
+`npx lean-computer-use doctor --json` compares installed files with the package and reports optional hook registration.
+All tests use temporary paths and fake commands.

package/docs/METHOD.md

@@ -0,0 +1,17 @@
+# Native app method
+
+Every agent step re-reads the conversation available to that agent.
+Put screen work in a small, fresh context and bundle predictable actions so it takes fewer steps.
+The main session frames the task, checks saved evidence, and reports the result; a cheap helper or `desk-runner` performs the app work.
+When no cheap helper is available, the runner handles every native app task.
+
+1. **Frame:** name one app's bundle id, approved actions, done check, evidence path and limits in the [brief](../briefs/desk-brief.md).
+2. **Snapshot:** check `osascript -e 'application "<Name>" is running'` before acting.
+3. **Act:** choose background keys or typing, test one action, and chain the remaining predictable actions in one call.
+4. **Read:** use one case-insensitive substring per `desk-read`, shared by the wanted lines (for example `AXStaticText`). Use two reads when two fields share none. Each printed file path holds the full read so the main session can inspect any other line.
+5. **Clean:** preserve evidence, run `desk-clean`, and compare the final app-running check with the initial snapshot.
+6. **Verify:** the main session opens the saved evidence and checks the stated done signal before reporting.
+
+Choose the focused method you need in [SKILL.md](../skills/lean-computer-use/SKILL.md).
+The [lean-browser-use sibling](https://github.com/aunysillyme/lean-browser-use) applies the same method to web pages.
+Measure your own transcript costs with `npx lean-computer-use measure --json`; this package's synthetic fixture demonstrates the calculation without making a savings claim about your setup.

package/docs/PROVENANCE.md

@@ -0,0 +1,19 @@
+# Provenance
+
+This package implements a native app workflow: frame the job in the main session, run app actions in a smaller context, then verify saved evidence.
+The desk wrappers build on cua-driver from [trycua/cua](https://github.com/trycua/cua).
+The driver is a separate installation; its code and app are not bundled.
+
+| Technique | Source | Local implementation |
+|---|---|---|
+| Background app actions through the accessibility tree | [trycua/cua](https://github.com/trycua/cua) | `desk/desk`, `desk/_resolve.py` |
+| Small-context runner and hook lifecycle | [Claude Code](https://code.claude.com/docs/en/overview) | `agents/desk-runner.md`, `hooks/`, `src/hooks-register.mjs` |
+| Packet actions and index choice from observed candidates | [Jev / typesafe-sdk](https://pypi.org/project/typesafe-sdk/) | `skills/lean-computer-use/methods/desk-run.md`, `same-app-chaining.md` |
+| Filtered output with retained full evidence | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | `desk/desk-read`, `skills/lean-computer-use/methods/filtered-reads.md` |
+| Plain retrieval before interactive browsing | [Crawl4AI](https://github.com/unclecode/crawl4ai), [SearXNG](https://github.com/searxng/searxng) | Context only; native app tasks stay in `docs/METHOD.md` |
+| The same method applied to web pages | [lean-browser-use](https://github.com/aunysillyme/lean-browser-use) | `docs/METHOD.md`, README sibling link |
+
+The public runner and native hooks are written for this package.
+Example transcripts are synthetic.
+Measurements describe this package or its fixture, with commands and dates in `proof/results.json`.
+Upstream licence versions were not rechecked over the network during this build: see the linked repositories and [CREDITS.md](../CREDITS.md).

package/docs/README.md

@@ -0,0 +1,12 @@
+# Documentation
+
+- [Install](install.md): preview, install, optional hooks and removal.
+- [Driver precautions](cua-driver-install.md): verify the upstream app and permissions.
+- [Installer contract](INSTALLER.md): ownership, backups and safe removal.
+- [Method](METHOD.md): the native app workflow in one page.
+- [Skill](../skills/lean-computer-use/SKILL.md): the entry point for an AI agent.
+- [Desk commands](../desk/README.md): action, read and cleanup behavior and exit codes.
+- [Provenance](PROVENANCE.md): upstream techniques and the files that use them.
+- [Stack card](STACK.md): runtime choices and budgets.
+- [Agent instructions](../AGENTS.md): repository layout, commands and enforced rules.
+- [Package proof](../proof/results.json): reproducible measurements with dates and expiry.

package/docs/STACK.md

@@ -0,0 +1,8 @@
+# Stack card
+
+1. **Runs on:** Node >=22 for the installer, doctor and measurement; macOS for native app control.
+2. **User supplies:** Python 3, cua-driver, macOS Accessibility and Screen Recording permissions, and an AI host that reads skill Markdown.
+3. **Install:** `npx lean-computer-use`, one confirmation; optional hooks use `--with-hooks`.
+4. **Pick:** JavaScript ESM checked with TypeScript `checkJs`, plus Python standard library desk tools and hooks because the driver wrappers were Python.
+5. **Budgets:** zero runtime dependencies; packed tarball at most 300 KB, unpacked at most 1 MB; cold `--help` at most 300 ms; offline checks on 2000 files under 2 s; uninstall removes every file the installer wrote that still matches its recorded hash; a file you edited stays in place and is listed for review.
+6. **Checks:** `test/budgets.test.mjs`, `test/installer.test.mjs`, `node --test`, and `python3 -m pytest -q desk/tests hooks/tests`; package receipts live in `proof/results.json`.

package/docs/cua-driver-install.md

@@ -0,0 +1,57 @@
+# Install cua-driver carefully
+
+The upstream driver controls native Mac apps through macOS permissions.
+Use [trycua/cua's README](https://github.com/trycua/cua) for its current installation command and supported release.
+This package does not bundle or install cua-driver.
+The vendor release, checksum and command behavior below are UNVERIFIED for your installed version until you check them locally.
+
+## Verify the download
+
+Compare the downloaded artifact with a checksum published by the upstream project when one is available.
+Confirm the signature's identity against upstream release information.
+For the app bundle, use Apple's signature and notarization checks:
+
+```sh
+codesign --verify --deep --strict /Applications/CuaDriver.app
+spctl --assess --verbose /Applications/CuaDriver.app
+```
+
+Resolve a failed assessment before granting permissions.
+These commands verify the local artifact; a successful check alone does not establish that it is the release you intended to download.
+
+## Check telemetry and permissions
+
+Inspect the commands offered by your installed version:
+
+```sh
+cua-driver --version
+cua-driver telemetry --help
+cua-driver telemetry status
+cua-driver permissions status --json
+```
+
+Disable telemetry with the installed version's supported command (`cua-driver telemetry disable` when listed), then check `cua-driver telemetry status` again.
+The exact disable subcommand is UNVERIFIED until confirmed by your local help output.
+
+Grant Accessibility and Screen Recording deliberately:
+
+```sh
+cua-driver permissions grant
+cua-driver permissions status --json
+cua-driver status
+```
+
+Confirm that `accessibility` and `screen_recording` are true.
+Review macOS System Settings if the permission command opens a settings pane.
+Keep credentials and other sensitive content out of app briefs.
+
+## Use and close
+
+`desk` starts the app-backed daemon on demand in the background, retaining its macOS permission identity.
+After a run, call `desk-clean <bundle> --app-name <Name>`.
+Add `--launched-by-run` only when the initial snapshot showed the app closed and this run launched it.
+This requests a gentle quit, removes owned desk state and stops the driver when no live sessions remain.
+An app that remains running is a pending cleanup result; keep its unsaved work safe and report it.
+
+Use `npx lean-computer-use doctor` to check the installation and receive one-line fixes.
+On other platforms the driver checks are warnings and package checks still run.

package/docs/install.md

@@ -0,0 +1,62 @@
+# Install
+
+Use Node >=22 to run the installer.
+Native app control needs macOS, Python 3 and the separately installed cua-driver.
+Follow [the driver precautions](cua-driver-install.md) before granting system permissions.
+
+```sh
+npx lean-computer-use
+npx lean-computer-use --uninstall
+```
+
+The first command previews its changes and asks for one confirmation.
+The second is the removal alias; `npx lean-computer-use uninstall` is equivalent.
+The installer copies the skill and runner to `~/.claude` and the desk tools and hooks to `~/.local/share/lean-computer-use`.
+The brief template is installed with the skill at `~/.claude/skills/lean-computer-use/desk-brief.md`.
+It does not install the driver or perform a vendor login.
+
+Preview a custom target without writing:
+
+```sh
+npx lean-computer-use install --dir <host-dir> --share <share-dir> --dry-run --yes
+```
+
+`--dry` is an alias for `--dry-run`.
+Use `--yes` for an unattended install after reviewing the plan.
+`LEAN_COMPUTER_USE_HOME` sets the share root when `--share` is absent.
+A differing existing file needs `--yes` to replace it; the installer keeps a `.bak` copy.
+
+## Optional hooks
+
+```sh
+npx lean-computer-use install --with-hooks
+```
+
+This merges marked registrations into `<host-dir>/settings.json` after a backup.
+Other settings and hooks remain in place.
+Repeated installation keeps one copy of each registration.
+Without this flag the installer prints the installed `settings-snippet.json` path and merge instructions.
+For a manual merge, replace the hook-directory placeholder as instructed, append the snippet's event entries to the matching `hooks` arrays, and retain existing entries.
+Restart the host after changing hooks, then run `npx lean-computer-use doctor`.
+
+## Activate
+
+Start a fresh host session so it can discover `skills/lean-computer-use/SKILL.md` and `agents/desk-runner.md`.
+Ask: "Use lean-computer-use. Give desk-runner one Calculator task, verify the saved filtered read, and report cleanup."
+Review the [brief template](../briefs/desk-brief.md) before handing an agent an app task.
+
+## Other hosts
+
+Copy `skills/lean-computer-use/` to the host's documented skill directory and point its runner at the desk tools.
+Copy `briefs/desk-brief.md` into that skill directory as `desk-brief.md`.
+The automatic installation target is Claude Code.
+
+## Remove
+
+```sh
+npx lean-computer-use uninstall --dry-run
+npx lean-computer-use uninstall
+```
+
+Removal uses the install manifest and preserves user-edited files.
+Read [the installer contract](INSTALLER.md) for manifest recovery and manual hook cleanup.

package/hooks/README.md

@@ -0,0 +1,26 @@
+# Native-app hooks
+
+The optional hooks help a runner stop a repeated error and combine small actions. Install their registrations with `npx lean-computer-use --with-hooks`. The installer merges [settings-snippet.json](settings-snippet.json) into the selected Claude Code settings file, substitutes the installed hook folder for `__HOOKS_DIR__`, and marks the entries `lean-computer-use`. Uninstall removes those marked entries while preserving other settings.
+
+Claude Code calls a self-locating shell shim with a JSON payload on stdin. The shim runs its neighboring Python file, which imports `_common.py`. Python uses only its standard library. The hooks run locally and make no network requests. Nothing watches their state or alerts when a hook fails open; the runner still stops and reports after the same error twice.
+
+| Hook | Trigger | Result |
+| --- | --- | --- |
+| `native_retry_guard.sh` | PreToolUse and PostToolUse for native MCP tools and desk commands | Records an error result and blocks a third attempt with identical tool name and input after two errors |
+| `native_batch_nudge.sh` | PostToolUse for native MCP tools and desk commands | Adds one non-blocking context hint after consecutive single actions |
+
+MCP matchers cover `mcp__computer-use__.*` and `mcp__cua-driver__.*`. Bash has its own registration. The scripts match `desk`, `desk-read` and `desk-clean` only when one is the first word of a command segment. Quoted arguments and unrelated shell commands stay outside that match. Here-document payloads are ignored.
+
+## State and closed loop
+
+State lives under `LEAN_COMPUTER_USE_STATE`, or under `${TMPDIR:-/tmp}/lean-computer-use-<uid>` by default. The directory must be owned by the current user with mode 0700. State and lock files use mode 0600. A session's filename is its SHA-256 prefix; a subagent id joins that identity when present. Each hook updates its own section under one file lock. Inputs and responses are represented by hashes rather than saved screen text.
+
+The retry hook records explicit error flags, response text starting with `error`, and failing desk command responses. A success with the same input clears that error count. A successful call to a different target also clears it. A different failed call starts a new count. Probe tools (`list_apps`, `list_windows`, `launch_app`, `end_session`, `status`, `list_tools`) never count or block.
+
+The batch hint appears once per streak. A probe, a filtered `desk-read`, cleanup, or a call chaining desk commands with `&&` resets the streak. The runner chains the remaining actions, reads once, and returns the saved read for independent verification.
+
+## Failure and verification
+
+Malformed JSON, a missing session id, an unsafe state path, or an internal exception allows the tool call. A missing neighboring Python file also allows it. Exit 2 from the retry guard is the sole block signal; its stderr tells the runner to stop, report the error, and try a different approach. The hint uses PostToolUse `additionalContext` JSON on stdout and always exits 0.
+
+Run `python3 -m pytest -q hooks/tests` with the package acceptance suite. The same contracts can run without pytest using `python3 -m unittest discover -s hooks/tests`. They send synthetic stdin payloads, use temporary state under the test folder, verify secure file modes, and invoke both shims. The Python sources and settings snippet in this folder are the source of truth.