superwait 0.2.0__tar.gz → 0.3.0__tar.gz

superwait-0.3.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: superwait
+Version: 0.3.0
+Summary: Conditional waiting for coding agents
+Project-URL: Repository, https://github.com/ctxrs/superwait
+Project-URL: Issues, https://github.com/ctxrs/superwait/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx2<3,>=2.13
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: pydantic<3,>=2.12
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/ctxrs/superwait/main/docs/assets/superwait-banner.png" alt="20% of your tokens are spent on the wait tool call. superwait cuts that in half, so you save 10% of total spend." width="100%">
+
+**superwait gives coding agents one place to wait for the outcome they need.** It works with Codex, Claude Code, and Cursor, runs locally, and makes no model calls while checking conditions.
+
+[Install](#install) · [How it works](#how-it-works) · [Host setup](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md) · [Reference](https://github.com/ctxrs/superwait/blob/main/docs/reference.md) · [About the numbers](https://github.com/ctxrs/superwait/blob/main/docs/savings.md)
+
+## Why use superwait?
+
+A build is still running. A reviewer hasn't finished. A service isn't ready yet. Your agent checks, reads “still running,” and calls another wait.
+
+Each trip back to the model can process the conversation again just to decide to keep waiting. With several workers, it also has to track which results arrived, which ones matter, and how much time is left.
+
+superwait lets the agent describe that outcome once:
+
+> Wait for two of the three reviewers. Wake early if the test worker reports a blocker. Stop after 30 minutes.
+
+Local code checks the conditions. The agent gets the completed results and remaining work when there is something to act on. If a blocker interrupts the wait, it can resume with the original deadline intact.
+
+## Install
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it. uv manages Python for you, so there is no separate Python installation step.
+
+```sh
+uv tool install --python 3.12 superwait
+```
+
+### Set up your host once (recommended)
+
+Run **one** command for your coding agent. It applies across your projects for your user account:
+
+```sh
+superwait setup codex
+# Or, for your host:
+superwait setup claude
+superwait setup cursor
+```
+
+Restart your coding agent and review its normal MCP and hook trust prompts. Set up before spawning workers so their lifecycle events can be recorded.
+
+Then ask your agent:
+
+> Use superwait to wait for both reviewers, but return early if either reports a blocker. Stop after 30 minutes.
+
+Setup adds the tool, lifecycle hooks, and instructions to your host's user configuration. It preserves unrelated settings, backs up files it changes, and doesn't add files to your repositories. There is no superwait account, API key, or hosted service to configure.
+
+### Only need it in one repository?
+
+Use project-only setup instead:
+
+```sh
+superwait setup codex --project .
+```
+
+Use `claude` or `cursor` for those hosts. Choose one scope for each project to avoid duplicate hooks. See [setup locations and existing installations](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md#installation-scope) for details.
+
+## How it works
+
+1. **Describe the result.** Wait for any, all, or a chosen number of workers and conditions. Add a deadline and anything that should wake the agent early.
+2. **Let local code watch.** The wait engine checks conditions concurrently. Hooks record worker events; file, HTTP, and command checks run locally as requested.
+3. **Continue with useful results.** The response explains why the wait ended, includes completed reports, and lists what remains pending. A ready-to-use continuation preserves the deadline and remaining count.
+
+The same engine is available as an MCP tool and a CLI. For a long wait that exceeds your host's tool timeout, the agent can use its background terminal.
+
+### What can you wait for?
+
+| You need… | superwait watches… |
+| --- | --- |
+| Enough reviews to proceed | Any, all, or a quorum of subagents |
+| A checkpoint or blocker | An explicit signal from a worker or script |
+| An artifact to be ready | A file appearing, changing, disappearing, or containing text |
+| A service to come online | An HTTP response with the requested status |
+| A custom readiness check | A command returning the requested exit code |
+
+Early-wake conditions can be combined with any of these. A timeout returns the partial results; it does not cancel the workers.
+
+See the [request and result reference](https://github.com/ctxrs/superwait/blob/main/docs/reference.md) for examples, continuation behavior, and CLI usage.
+
+## When does it help most?
+
+Use superwait when an agent keeps checking unchanged state, or when several workers and external conditions need to be coordinated together. A single native wait is often enough for one worker. superwait adds the compound conditions, early wakeups, and shared deadline.
+
+It does not replace your host's built-in wait tools automatically. Your agent needs to use it, and the condition must be observable through a supported hook or check.
+
+## Works with ctx
+
+superwait is made by **ctx engineering**, the team behind [ctx](https://github.com/ctxrs/ctx).
+
+We recommend installing ctx alongside superwait. ctx gives your coding agents fast, local search across their past sessions, so they can recover earlier decisions, reuse investigations, and find solutions they've already worked out. Results link back to the original messages and tool calls.
+
+[Install ctx and get started →](https://github.com/ctxrs/ctx#install-and-set-up-ctx)
+
+## About the numbers
+
+Our corpus study found that wait-only model responses accounted for about **20% of input tokens**. Auditing repeated waits identified roughly half of that input as a consolidation opportunity—about **9–10% of total input**, before replacement overhead.
+
+Actual token and spend savings depend on your corpus, model pricing, caching, and host integration; input-token savings are not the same as measured bill savings. [See the study and how to evaluate your own workload](https://github.com/ctxrs/superwait/blob/main/docs/savings.md).
+
+## Host support and details
+
+Linux and Codex have live integration coverage. Claude Code and Cursor have adapter tests; full live workflows in those hosts, other operating systems, and multi-hour host waits still need qualification.
+
+- [Host setup, permissions, and compatibility](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md)
+- [API, CLI, long waits, and local data](https://github.com/ctxrs/superwait/blob/main/docs/reference.md)
+- [Contributing](https://github.com/ctxrs/superwait/blob/main/CONTRIBUTING.md) · [PyPI](https://pypi.org/project/superwait/) · [MIT license](https://github.com/ctxrs/superwait/blob/main/LICENSE)

superwait-0.3.0/README.md

@@ -0,0 +1,104 @@
+<img src="https://raw.githubusercontent.com/ctxrs/superwait/main/docs/assets/superwait-banner.png" alt="20% of your tokens are spent on the wait tool call. superwait cuts that in half, so you save 10% of total spend." width="100%">
+
+**superwait gives coding agents one place to wait for the outcome they need.** It works with Codex, Claude Code, and Cursor, runs locally, and makes no model calls while checking conditions.
+
+[Install](#install) · [How it works](#how-it-works) · [Host setup](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md) · [Reference](https://github.com/ctxrs/superwait/blob/main/docs/reference.md) · [About the numbers](https://github.com/ctxrs/superwait/blob/main/docs/savings.md)
+
+## Why use superwait?
+
+A build is still running. A reviewer hasn't finished. A service isn't ready yet. Your agent checks, reads “still running,” and calls another wait.
+
+Each trip back to the model can process the conversation again just to decide to keep waiting. With several workers, it also has to track which results arrived, which ones matter, and how much time is left.
+
+superwait lets the agent describe that outcome once:
+
+> Wait for two of the three reviewers. Wake early if the test worker reports a blocker. Stop after 30 minutes.
+
+Local code checks the conditions. The agent gets the completed results and remaining work when there is something to act on. If a blocker interrupts the wait, it can resume with the original deadline intact.
+
+## Install
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it. uv manages Python for you, so there is no separate Python installation step.
+
+```sh
+uv tool install --python 3.12 superwait
+```
+
+### Set up your host once (recommended)
+
+Run **one** command for your coding agent. It applies across your projects for your user account:
+
+```sh
+superwait setup codex
+# Or, for your host:
+superwait setup claude
+superwait setup cursor
+```
+
+Restart your coding agent and review its normal MCP and hook trust prompts. Set up before spawning workers so their lifecycle events can be recorded.
+
+Then ask your agent:
+
+> Use superwait to wait for both reviewers, but return early if either reports a blocker. Stop after 30 minutes.
+
+Setup adds the tool, lifecycle hooks, and instructions to your host's user configuration. It preserves unrelated settings, backs up files it changes, and doesn't add files to your repositories. There is no superwait account, API key, or hosted service to configure.
+
+### Only need it in one repository?
+
+Use project-only setup instead:
+
+```sh
+superwait setup codex --project .
+```
+
+Use `claude` or `cursor` for those hosts. Choose one scope for each project to avoid duplicate hooks. See [setup locations and existing installations](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md#installation-scope) for details.
+
+## How it works
+
+1. **Describe the result.** Wait for any, all, or a chosen number of workers and conditions. Add a deadline and anything that should wake the agent early.
+2. **Let local code watch.** The wait engine checks conditions concurrently. Hooks record worker events; file, HTTP, and command checks run locally as requested.
+3. **Continue with useful results.** The response explains why the wait ended, includes completed reports, and lists what remains pending. A ready-to-use continuation preserves the deadline and remaining count.
+
+The same engine is available as an MCP tool and a CLI. For a long wait that exceeds your host's tool timeout, the agent can use its background terminal.
+
+### What can you wait for?
+
+| You need… | superwait watches… |
+| --- | --- |
+| Enough reviews to proceed | Any, all, or a quorum of subagents |
+| A checkpoint or blocker | An explicit signal from a worker or script |
+| An artifact to be ready | A file appearing, changing, disappearing, or containing text |
+| A service to come online | An HTTP response with the requested status |
+| A custom readiness check | A command returning the requested exit code |
+
+Early-wake conditions can be combined with any of these. A timeout returns the partial results; it does not cancel the workers.
+
+See the [request and result reference](https://github.com/ctxrs/superwait/blob/main/docs/reference.md) for examples, continuation behavior, and CLI usage.
+
+## When does it help most?
+
+Use superwait when an agent keeps checking unchanged state, or when several workers and external conditions need to be coordinated together. A single native wait is often enough for one worker. superwait adds the compound conditions, early wakeups, and shared deadline.
+
+It does not replace your host's built-in wait tools automatically. Your agent needs to use it, and the condition must be observable through a supported hook or check.
+
+## Works with ctx
+
+superwait is made by **ctx engineering**, the team behind [ctx](https://github.com/ctxrs/ctx).
+
+We recommend installing ctx alongside superwait. ctx gives your coding agents fast, local search across their past sessions, so they can recover earlier decisions, reuse investigations, and find solutions they've already worked out. Results link back to the original messages and tool calls.
+
+[Install ctx and get started →](https://github.com/ctxrs/ctx#install-and-set-up-ctx)
+
+## About the numbers
+
+Our corpus study found that wait-only model responses accounted for about **20% of input tokens**. Auditing repeated waits identified roughly half of that input as a consolidation opportunity—about **9–10% of total input**, before replacement overhead.
+
+Actual token and spend savings depend on your corpus, model pricing, caching, and host integration; input-token savings are not the same as measured bill savings. [See the study and how to evaluate your own workload](https://github.com/ctxrs/superwait/blob/main/docs/savings.md).
+
+## Host support and details
+
+Linux and Codex have live integration coverage. Claude Code and Cursor have adapter tests; full live workflows in those hosts, other operating systems, and multi-hour host waits still need qualification.
+
+- [Host setup, permissions, and compatibility](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md)
+- [API, CLI, long waits, and local data](https://github.com/ctxrs/superwait/blob/main/docs/reference.md)
+- [Contributing](https://github.com/ctxrs/superwait/blob/main/CONTRIBUTING.md) · [PyPI](https://pypi.org/project/superwait/) · [MIT license](https://github.com/ctxrs/superwait/blob/main/LICENSE)

{superwait-0.2.0 → superwait-0.3.0}/docs/hosts.md

@@ -1,7 +1,34 @@
 # Host integration
 
 All three hosts use the same `wait_for`, `list_agents`, and `signal` MCP API.
-The CLI runs the same wait engine. Setup writes only to the project you name.
+The CLI runs the same wait engine.
+
+## Installation scope
+
+**Host-wide setup is recommended:** run `superwait setup codex`, `superwait setup
+claude`, or `superwait setup cursor` once. This installs into the selected host's
+user configuration and applies across projects for that OS user. It does not
+configure other users, remote machines, or cloud agent VMs.
+
+Host-wide setup requires superwait 0.3.0 or newer. If you installed 0.2.0, run
+`uv tool upgrade superwait` before following the [README](../README.md#install).
+
+| Host | User MCP configuration | User lifecycle hooks | User skill |
+| --- | --- | --- | --- |
+| Codex | `~/.codex/config.toml` | `~/.codex/hooks.json` | `~/.agents/skills/superwait/SKILL.md` |
+| Claude Code | `~/.claude.json` | `~/.claude/settings.json` | `~/.claude/skills/superwait/SKILL.md` |
+| Cursor | `~/.cursor/mcp.json` | `~/.cursor/hooks.json` | `~/.cursor/skills/superwait/SKILL.md` |
+
+Codex honors `CODEX_HOME` for its config and hooks; its user skill stays in
+`~/.agents/skills`. Claude Code honors `CLAUDE_CONFIG_DIR`: when set, the MCP
+entry goes into `.claude.json` inside that directory, with settings and skills
+alongside it. Cursor uses its standard `~/.cursor` directory.
+
+### Project-only setup
+
+Add `--project /path/to/repo` to limit setup to one repository. This explicitly
+uses the repository paths below, even if a user configuration directory is set
+in your environment.
 
 | Host | MCP configuration | Lifecycle hook configuration | Skill |
 | --- | --- | --- | --- |
@@ -9,6 +36,29 @@ The CLI runs the same wait engine. Setup writes only to the project you name.
 | Claude Code | `.mcp.json` | `.claude/settings.json` | `.claude/skills/superwait/SKILL.md` |
 | Cursor | `.cursor/mcp.json` | `.cursor/hooks.json` | `.cursor/skills/superwait/SKILL.md` |
 
+Setup preserves unrelated settings, creates owner-only `.superwait-backup`
+copies of existing files before changing them, and can be run again without
+duplicating its hook entries in the same scope. It does not change host trust
+or approval settings.
+
+### Moving an existing project installation to host-wide setup
+
+Setup does not remove existing project installations. Hosts can load hooks from
+both scopes, which would record events twice. Remove only the old superwait MCP
+entry, its hook entries, and its installed skill from the project before using
+the host-wide installation there. Keep unrelated settings and hooks. For Codex,
+the managed MCP entry is between `# BEGIN superwait` and `# END superwait`.
+Then restart the host and review its normal trust prompts.
+
+Sources: [Codex config](https://learn.chatgpt.com/docs/config-file/config-reference),
+[Codex hooks](https://developers.openai.com/codex/hooks),
+[Codex skills](https://learn.chatgpt.com/docs/build-skills),
+[Claude Code MCP scopes](https://code.claude.com/docs/en/mcp#user-scope),
+[Claude Code settings](https://code.claude.com/docs/en/settings),
+[Cursor MCP](https://cursor.com/docs/context/mcp),
+[Cursor hooks](https://cursor.com/docs/hooks),
+[Cursor skills](https://cursor.com/docs/context/skills).
+
 ## Codex
 
 `SubagentStart` and `SubagentStop` supply the agent ID and parent session ID.

superwait-0.3.0/docs/reference.md

@@ -0,0 +1,39 @@
+# Superwait reference
+
+The [full API and CLI reference](../src/superwait/references/api.md) is also
+installed beside the skill as `references/api.md`, so agents can read it locally
+only when needed.
+
+## Install from source
+
+To install the current source instead of the PyPI release:
+
+```sh
+uv tool install 'git+https://github.com/ctxrs/superwait'
+```
+
+## Python and package installation
+
+[uv](https://docs.astral.sh/uv/getting-started/installation/) is the recommended
+installer. It creates a persistent, isolated tool environment and can download
+Python automatically. You do not need to set up Python or a virtual environment
+yourself. To explicitly select a runtime for the published package:
+
+```sh
+uv tool install --python 3.12 superwait
+```
+
+The [README](../README.md#install) covers host-wide setup, available in 0.3.0
+and newer. Upgrade an existing uv installation with `uv tool upgrade superwait`.
+
+If you already manage Python 3.11+ with pipx, `pipx install superwait` is another
+option. Keep whichever tool environment you install: the generated MCP and hook
+commands point at its Python executable. A temporary `uvx` run is not the
+recommended setup path because its cached environment can be removed.
+
+If `superwait` is not found after installation, follow uv's printed PATH
+instructions or run `uv tool update-shell` and open a new terminal. Setup itself
+does not edit shell profiles.
+
+Sources: [uv tool environments](https://docs.astral.sh/uv/guides/tools/),
+[automatic Python downloads](https://docs.astral.sh/uv/guides/install-python/#automatic-python-downloads).

superwait-0.3.0/docs/savings.md

@@ -0,0 +1,46 @@
+# Where the numbers come from
+
+[Back to the README](../README.md)
+
+The banner is a rounded savings pitch based on a retrospective study of coding-agent history. The study measured how many tokens accompanied waiting responses and estimated which repeated responses could be consolidated. It did not measure a 10% reduction in bills from installing superwait.
+
+## What we measured
+
+We froze a sample of 200 Codex sessions before analyzing their waiting behavior. After excluding one session with ambiguous turn and token attribution, the analysis retained 199 sessions and 24,897 attributed model responses.
+
+A **wait-only response** calls only recognized waiting tools. Input counts include cached input; cached tokens are a subset, not an additional total.
+
+| Finding | Result |
+| --- | ---: |
+| Input processed across the retained sample | 3.112 billion tokens |
+| Input associated with wait-only responses | About 20% |
+| Repeated-wait follow-ups eligible for investigation | 2,436 across 43 tasks |
+| Probability-sampled transitions retained in the manual audit | 187 |
+| Estimated input associated with skippable deterministic repeats | 281.6 million tokens, or 9.05% of total input |
+| Including conditional cases that require preserving additional behavior | 317.9 million tokens, or 10.22% of total input |
+
+The main estimate is about 46% of wait-only input; including the conditional cases reaches about 52%. That is the basis for the headline's “20%” and “half.”
+
+The manual audit also included 20 supplemental cases for coverage. These did not enter the numerical projection. Separate reviewers checked overlapping cases and the accounting.
+
+## What that means for savings
+
+Waiting time itself does not consume model tokens. The opportunity is avoiding another model response whose only useful action is to keep waiting.
+
+The estimate is gross input-token opportunity, before the cost of instructions, monitor setup, result delivery, and changes to later context or cache use. Approximately 99.3% of the main projected input was cached. Cached input, fresh input, and output can have different prices, so a raw input percentage does not establish the same percentage reduction in spending.
+
+The current package also cannot consume a host's opaque execution-cell or terminal-session handles directly. About 91.6% of the main input projection involved that integration requirement. The retrospective therefore does not establish that installing superwait delivers the full projected saving. Longer native waits can also eliminate some repeated checks.
+
+The corpus deliberately oversampled parent tasks and covered Codex sessions from one workflow. It is not a representative benchmark for every developer, model, or supported host.
+
+## Evaluate your own workload
+
+Use the same tasks, model, host configuration, and completion criteria for a baseline and a superwait run.
+
+1. **Start with a good baseline.** Use the host's supported native wait and timeout settings. Keep required progress updates and result delivery.
+2. **Use observable conditions.** Give superwait the worker, signal, file, HTTP, or command conditions that actually describe readiness.
+3. **Compare whole runs.** Record input, cached input, and output separately, including instructions and setup overhead. Also compare task completion, useful updates, failures, and elapsed time.
+4. **Apply your prices.** Compute each run's bill using its cached-input, uncached-input, and output rates. Divide the cost difference by the baseline cost to get spend savings.
+5. **Repeat across tasks.** Report how you selected the workload and which host integrations were available.
+
+No corpus upload is required for this comparison. Use the usage records your host or provider makes available. superwait does not currently ship an automatic token-savings evaluator.

{superwait-0.2.0 → superwait-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "superwait"
-version = "0.2.0"
+version = "0.3.0"
 description = "Conditional waiting for coding agents"
 readme = "README.md"
 license = "MIT"

superwait-0.3.0/src/superwait/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: superwait
+description: Prefer superwait for waiting on agents, files, services, or signals.
+---
+
+# superwait
+
+Prefer superwait over native wait tools or polling loops. Use native tools to
+spawn or steer agents.
+
+Call the `wait_for` MCP tool:
+
+```json
+{"request":{"agents":["worker-a-id","worker-b-id"],"timeout":"10m"}}
+```
+
+Use handles returned by the host. For Codex `/root/...` paths, add `session`
+from startup context. The default waits for all agents. Read the `ready`
+reports; use `continue_wait` as the next `request` for remaining work.
+
+In Codex code mode, start `functions.exec` with
+`// @exec: {"yield_time_ms":60000}`. If it yields, resume that cell with
+`functions.wait` and `yield_time_ms: 60000`.
+
+For other conditions, quorum, early wakeups, continuation details, or CLI usage,
+read the [local API reference](references/api.md) only when needed.

{superwait-0.2.0 → superwait-0.3.0}/src/superwait/cli.py

@@ -31,9 +31,9 @@ def parser():
     hook = commands.add_parser("hook", help="Host lifecycle adapter; reads JSON on stdin.")
     hook.add_argument("provider", choices=["codex", "claude", "cursor"])
     commands.add_parser("serve", help="Serve the MCP API over stdio.")
-    setup = commands.add_parser("setup", help="Configure hooks, MCP, and the skill in a project.")
+    setup = commands.add_parser("setup", help="Configure hooks, MCP, and the skill for your host.")
     setup.add_argument("provider", choices=["codex", "claude", "cursor"])
-    setup.add_argument("--project", required=True, type=Path)
+    setup.add_argument("--project", type=Path, help="Only configure this project; default: all projects for your user.")
     setup.add_argument("--max-wait", default="24h", help="Host tool timeout, where supported.")
     prune = commands.add_parser("prune", help="Delete old local observations.")
     prune.add_argument("--days", type=float, default=30)

superwait-0.3.0/src/superwait/references/api.md

@@ -0,0 +1,223 @@
+# Superwait API reference
+
+Superwait exposes the same wait engine through an MCP tool and a CLI. The MCP
+server provides `wait_for`, `list_agents`, and `signal`.
+
+## Wait requests
+
+Call `wait_for` with a `request`:
+
+```json
+{
+  "request": {
+    "agents": ["reviewer-a-id", "reviewer-b-id", "reviewer-c-id"],
+    "mode": "quorum",
+    "quorum": 2,
+    "wake_on": [
+      {"kind": "signal", "key": "review-42/blocker", "state": "blocked"}
+    ],
+    "timeout": "2h"
+  }
+}
+```
+
+Use native worker IDs from the selected host. Codex task paths such as
+`/root/reviewer_a` also work when accompanied by the parent `session` supplied
+in its startup context. `list_agents` is available for discovery and
+troubleshooting.
+
+`mode` is `all` by default, or `any`, or `quorum` with a count. Conditions in
+`targets` count toward the same threshold as `agents`. Conditions in `wake_on`
+return early independently of that threshold.
+
+### Request fields
+
+| Field | Meaning / default |
+| --- | --- |
+| `agents` | Worker handles; shorthand for agent conditions; default `[]` |
+| `provider` | `codex`, `claude`, or `cursor`; defaults to the configured host (standalone: `codex`) |
+| `session` | Parent session for unscoped agent conditions in the selected provider; required for Codex task paths |
+| `targets` | Explicit conditions; default `[]`; at least one agent or target is required |
+| `mode` | `all` (default), `any`, or `quorum` |
+| `quorum` | Required positive count for `quorum` mode only; no greater than the number of agents and targets |
+| `wake_on` | Conditions that interrupt the wait; default `[]` |
+| `timeout` | String containing positive seconds or a duration such as `30s`, `10m`, `2h`, `1d`; default `10m`; `ms` also supported |
+| `deadline` | Timezone-qualified timestamp overriding `timeout`; continuation preserves it |
+| `interval` | Seconds between probes; default `1`, minimum `0.05`; increase for remote checks |
+| `details` | Include raw observations; default `false` |
+
+Unknown fields and duplicate main targets are rejected. Every condition accepts
+an optional `label` for readable results. The same condition types work in
+`targets` and `wake_on`.
+
+### Conditions
+
+| Condition | Matches when |
+| --- | --- |
+| `agent` | A lifecycle hook observes a requested worker state |
+| `signal` | A task-specific event is published |
+| `file` | A path exists, is missing, changes, or contains literal text |
+| `http` | A GET returns the requested status code |
+| `command` | An observational command returns the requested exit code |
+
+| Kind | Required fields | Optional fields |
+| --- | --- | --- |
+| `agent` | `provider`, `id` | `session`; `states` defaults to `["stopped", "error", "aborted"]` (`running` also supported); `after` defaults to `0` |
+| `signal` | `key` | `state` (any if omitted); `after` defaults to `0` |
+| `file` | `path` | `event`: `exists` (default), `missing`, `changed`, or `contains`; `text` required for `contains`; `since` is a continuation baseline, not needed for new waits |
+| `http` | `url` (`http://` or `https://`) | `status` defaults to `200`; redirects are not followed |
+| `command` | Nonempty `argv` array | `cwd`; `exit_code` defaults to `0`; positive `probe_timeout` defaults to `10` seconds |
+
+`after` is a nonnegative event cursor: only later observations match. File
+`contains` uses literal UTF-8 text; `changed` compares file metadata against the
+initial observation or preserved `since` baseline.
+
+For example, wait for a healthy service and a ready log, but wake on a blocker:
+
+```json
+{
+  "request": {
+    "targets": [
+      {"kind": "http", "url": "http://localhost:8080/health", "status": 200},
+      {"kind": "file", "path": "/workspace/server.log", "event": "contains", "text": "Ready"}
+    ],
+    "wake_on": [{"kind": "file", "path": "/workspace/blocker.json"}],
+    "timeout": "10m"
+  }
+}
+```
+
+Checks run concurrently. Command probes take an argument array and run without
+a shell. They repeat, so use them only for observational checks. `interval`
+controls polling and defaults to one second. Prefer absolute paths when the MCP
+server's working directory may differ from the caller's.
+
+### Agent handles and hooks
+
+Install hooks before spawning workers. Codex task paths become resolvable
+when a stop hook supplies worker metadata; native UUIDs need no extra session
+scope. The Codex CLI fills the session from `CODEX_THREAD_ID` when available.
+Cursor stop hooks sometimes lack enough identity: use a unique outcome signal
+for indistinguishable concurrent assignments.
+
+### Other MCP tools
+
+`list_agents(provider, session?)` returns `agents` and `limit` (50) for recent
+hook-observed workers. Use it for discovery or troubleshooting, not before every
+wait. `provider` is required: `codex`, `claude`, or `cursor`.
+
+`signal(key, state="ready", data=null)` publishes an event and returns its `seq`
+cursor. The key and state must be nonempty strings; optional data is a JSON object.
+Use task-specific keys: existing matching signals count unless `after` excludes
+them.
+
+Publish an explicit checkpoint or blocker through the `signal` MCP tool or CLI:
+
+```sh
+superwait signal review-42/blocker \
+  --state blocked \
+  --data '{"reason":"missing fixture"}'
+```
+
+## Results and continuation
+
+The result includes:
+
+- `status`: `matched`, `interrupted`, `timed_out`, or `error`
+- `reason`: why the wait ended
+- `ready`: completed reports
+- `pending`: remaining work or condition errors
+- `triggered`: early wake conditions that fired
+- `progress`: counts of `ready`, `required`, and `total` conditions
+- `deadline`: the absolute deadline; `elapsed_seconds`: time spent waiting
+- `continue_wait`: a ready-to-use request for remaining work, or `null`
+
+Reports include the observed state, available worker result, and event cursor
+where applicable. `details: true` adds `checks` and raw `targets` / `wake_on`
+observations. An early wake condition wins if it and the main threshold match
+in the same check.
+
+Pass `continue_wait` back as the next request to resume. It preserves the
+deadline, remaining count, and file-change baselines, and advances past
+delivered event signals. Persistent conditions such as an existing blocker
+file must clear or be removed before continuing. After a quorum is reached,
+continuation waits for all remaining work.
+
+A stopped worker response does not prove its assignment succeeded. Read its
+report; another host hook may continue that worker. For a resumed worker, use
+an `agent` target with `after` set to its last returned cursor. Unknown workers
+stay pending.
+
+For a new response from a resumed worker:
+
+```json
+{
+  "request": {
+    "session": "parent-session-from-startup-context",
+    "targets": [{"kind": "agent", "provider": "codex", "id": "/root/reviewer_a", "after": 42}],
+    "timeout": "2h"
+  }
+}
+```
+
+## Long waits and the CLI
+
+Setup configures a per-server MCP timeout of 24 hours plus 30 seconds for Codex
+and Claude Code. Change the ceiling with `setup --max-wait 3d`. Each request
+still has its own `timeout` or timezone-qualified `deadline`. An absolute
+deadline survives continuation; a timed-out continuation remains expired.
+
+In Codex code mode, start `functions.exec` with
+`// @exec: {"yield_time_ms":60000}`. If it yields, resume that cell with
+`functions.wait` and `yield_time_ms: 60000`. This avoids unnecessary model
+turns collecting an unfinished tool call.
+
+For long Cursor waits, or waits beyond a host's configured MCP timeout, run the
+same request through the host's background terminal:
+
+```sh
+superwait wait --request wait.json --output result.json
+```
+
+`wait.json` contains the request itself without the MCP `request` wrapper. The
+CLI prints one final JSON result and atomically saves the optional output. It
+exits 0 for matched or interrupted, 124 for timeout, 130 for Ctrl-C, and 2 for
+an invalid request or target ambiguity. The CLI does not background itself.
+
+Cancellation stops the wait and probes it launched. It does not cancel the
+workers being observed. The process and machine must remain alive.
+
+### CLI commands
+
+Global options go before the command: `--db PATH` selects the shared store;
+`--provider codex|claude|cursor` selects the default host for agent shorthand.
+
+| Command | Options / behavior |
+| --- | --- |
+| `wait` | `--request FILE` (default `-` reads stdin); `--timeout DURATION` overrides duration and clears a supplied deadline; `--output FILE` saves the result |
+| `signal KEY` | `--state STATE` (default `ready`); `--data JSON` (default `{}`) |
+| `agents PROVIDER` | Optional `--session SESSION`; lists up to 50 recent workers |
+| `setup PROVIDER` | Host-wide by default; `--project PATH` installs for one repository; `--max-wait DURATION` defaults to `24h` |
+| `serve` | Runs the MCP server over stdio |
+| `hook PROVIDER` | Lifecycle recorder used by setup; reads the host's JSON event from stdin |
+| `prune` | `--days NUMBER` deletes older observations; positive number, default `30` |
+
+Setup installs `SKILL.md` and this reference together, preserving unrelated
+host settings and saving originals of changed files as `.superwait-backup`.
+Restart the host and review its MCP/hooks trust prompts after setup.
+
+## Local state
+
+Hooks and waiters share a local SQLite database, defaulting to
+`$XDG_STATE_HOME/superwait/events.sqlite3` or
+`~/.local/state/superwait/events.sqlite3`. Set `SUPERWAIT_DB` or pass `--db` to
+use another store. Stored observations include worker IDs, report excerpts,
+and available transcript paths.
+
+```sh
+superwait prune --days 30
+```
+
+The Codex task-name adapter reads only the metadata header of the exact worker
+transcript supplied by its hook. It does not scan conversation history. Network
+requests occur only for explicitly requested HTTP or command checks.