superwait 0.2.0__tar.gz → 0.3.1__tar.gz

superwait-0.3.1/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: superwait
+Version: 0.3.1
+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.
+For Codex, open `/hooks` and trust the three superwait hooks. After spawning a
+worker, `superwait doctor codex` checks whether its events are reaching superwait.
+See [installation checks](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md#confirm-the-installation-is-active) if they aren't.
+
+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.1/README.md

@@ -0,0 +1,107 @@
+<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.
+For Codex, open `/hooks` and trust the three superwait hooks. After spawning a
+worker, `superwait doctor codex` checks whether its events are reaching superwait.
+See [installation checks](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md#confirm-the-installation-is-active) if they aren't.
+
+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.1}/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.
@@ -26,6 +76,11 @@ no history. It is version-dependent; absent or unsupported metadata leaves
 UUID-based waiting and explicit signals available.
 
 A previously unknown task path remains pending until that mapping arrives.
+If no worker in that parent is running, an unobserved path instead returns a
+setup diagnostic after five seconds. Unobserved native IDs use the same grace
+period; already observed workers can run for the full deadline.
+An `any` or quorum wait can continue without an unobserved target when its other
+targets can still satisfy the required count.
 Task paths require `session` even if only one old mapping exists: an unscoped
 name could otherwise match a previous conversation before the new worker stops.
 Setup installs a SessionStart hook that supplies this context to Codex; it
@@ -52,6 +107,24 @@ Sources: [hooks](https://developers.openai.com/codex/hooks),
 [MCP settings](https://learn.chatgpt.com/docs/extend/mcp),
 [skill discovery](https://learn.chatgpt.com/docs/build-skills).
 
+### Confirm the installation is active
+
+Installing configuration does not approve its hooks. Open `/hooks`, review and
+trust the three superwait definitions, then start a fresh session. Already-open
+sessions may still use the previous configuration. Spawn a worker and check:
+
+```sh
+superwait doctor codex
+superwait agents codex
+```
+
+Check that the new worker appears and its final report arrives. `doctor` shows
+the package version, exact database, event count and latest event time; stored
+old events alone do not prove the current host is recording. If observations
+are missing, check hook trust, host reload, and matching database paths. Use
+native agent waiting until this is fixed; file and command waits still work.
+The CLI is also available when an existing session has not loaded the MCP tool.
+
 ## Claude Code
 
 The same lifecycle event names provide `agent_id` and `session_id`. Setup also

superwait-0.3.1/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.1/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.1}/pyproject.toml

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

superwait-0.3.1/src/superwait/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: superwait
+description: Prefer superwait for waiting on agents, files, services, or signals.
+---
+
+# superwait
+
+Prefer superwait for observable conditions. Use native tools to spawn or steer
+agents, or when superwait reports unobserved workers. Don't retry missing hooks.
+
+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.
+Choose the real task deadline, not repeated 30–60-second timeouts. An expired
+continuation stays expired. Native process handles still need their native tools.
+
+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`.
+The wrapper can still wake the model; prefer a direct tool call when available.
+
+For other conditions, quorum, early wakeups, continuation details, or CLI usage,
+read the [local API reference](references/api.md) only when needed, including
+the CLI fallback if the MCP tool is not exposed.

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

@@ -28,12 +28,15 @@ def parser():
     agents = commands.add_parser("agents", help="List recent hook-observed subagents.")
     agents.add_argument("provider", choices=["codex", "claude", "cursor"])
     agents.add_argument("--session")
+    doctor = commands.add_parser("doctor", help="Check whether lifecycle events are reaching this database.")
+    doctor.add_argument("provider", choices=["codex", "claude", "cursor"])
+    doctor.add_argument("--session", help="Check observations for one parent session.")
     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)
@@ -74,6 +77,10 @@ def main():
                 result = {"seq": store.emit("signal", args.key, args.state, data=data)}
             elif args.command == "agents":
                 result = {"agents": store.agents(args.provider, args.session), "limit": 50}
+            elif args.command == "doctor":
+                from importlib.metadata import version
+                result = {"version": version("superwait"), **store.health(args.provider, args.session)}
+                code = 0 if result["status"] == "observed" else 1
             elif args.command == "hook":
                 from .hooks import record_hook
                 result = record_hook(args.provider, json.load(sys.stdin), store)

{superwait-0.2.0 → superwait-0.3.1}/src/superwait/engine.py

@@ -15,6 +15,9 @@ from .models import Agent, Command, File, HTTP, Signal, WaitRequest
 from .store import AmbiguousAgent, Store
 
 
+AGENT_OBSERVATION_GRACE = 5.0
+
+
 def file_stamp(path):
     try:
         stat = path.stat()
@@ -86,7 +89,13 @@ async def observe(target, store, client, baseline=None):
             else:
                 event = store.signal(target.key, target.state, target.after)
                 matched = bool(event)
-            return {"matched": bool(matched), "state": event["state"] if event else "unknown", "event": event}
+            result = {"matched": bool(matched), "state": event["state"] if event else "unknown", "event": event}
+            if not event and isinstance(target, Agent) and target.provider == "codex" and target.id.startswith("/"):
+                # Codex task paths are learned at Stop, not Start. A live
+                # worker in this parent can still supply the mapping.
+                result["awaiting_alias"] = any(a["state"] == "running"
+                    for a in store.agents("codex", target.session, None))
+            return result
         if isinstance(target, File):
             path = Path(target.path).expanduser().absolute()
             stamp = file_stamp(path)
@@ -143,8 +152,20 @@ async def wait_for(request: WaitRequest, store: Store, progress=None):
             while True:
                 checks += 1
                 results[i] = await observe(targets[i], store, client, baselines[i])
+                target, result = targets[i], results[i]
+                if isinstance(target, Agent) and result.get("state") == "unknown":
+                    result["hint"] = ("No lifecycle observation for this handle. Check superwait doctor "
+                                      + target.provider + "; review hook trust and use native waiting until recording works.")
+                    if time.monotonic() - started >= AGENT_OBSERVATION_GRACE:
+                        if not result.get("awaiting_alias"):
+                            result.update(state="unobserved", error=result["hint"])
                 changed.set()
-                await asyncio.sleep(request.interval)
+                delay = request.interval
+                if isinstance(target, Agent) and result.get("state") == "unknown":
+                    remaining = AGENT_OBSERVATION_GRACE - (time.monotonic() - started)
+                    if remaining > 0:
+                        delay = min(delay, max(.05, remaining))
+                await asyncio.sleep(delay)
 
         async def keepalive():
             while True:
@@ -172,7 +193,7 @@ async def wait_for(request: WaitRequest, store: Store, progress=None):
                             c["transcript_path"] = data["transcript_path"]
                 elif isinstance(t, (Agent, Signal)) and e["seq"] <= t.after:
                     c["state"] = "awaiting_new_event"
-            for key in ("error", "status_code", "exit_code", "stdout", "stderr"):
+            for key in ("error", "hint", "status_code", "exit_code", "stdout", "stderr"):
                 if key in r and r[key] != "":
                     c[key] = r[key]
             return c
@@ -237,6 +258,9 @@ async def wait_for(request: WaitRequest, store: Store, progress=None):
                                 return outcome("interrupted")
                             if sum(r["matched"] for r in results[:len(primary)]) >= needed:
                                 return outcome("matched")
+                            observable = sum(r.get("state") != "unobserved" for r in results[:len(primary)])
+                            if observable < needed or any(r.get("state") == "unobserved" for r in results[len(primary):]):
+                                return outcome("error", "An agent has no lifecycle observations. Check its handle and hook setup, or use native waiting.")
                     finally:
                         for worker in workers:
                             worker.cancel()

{superwait-0.2.0 → superwait-0.3.1}/src/superwait/models.py

@@ -5,7 +5,7 @@ import re
 from datetime import datetime, timezone
 from typing import Annotated, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 
 class Model(BaseModel):
@@ -67,10 +67,15 @@ Target = Annotated[Agent | Signal | File | HTTP | Command, Field(discriminator="
 
 
 def seconds(value: str) -> float:
-    match = re.fullmatch(r"\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?\s*", value)
-    if not match:
-        raise ValueError("duration must be a number with ms, s, m, h, or d (for example 2h)")
-    result = float(match[1]) * {None: 1, "ms": .001, "s": 1, "m": 60, "h": 3600, "d": 86400}[match[2]]
+    number = r"\d+(?:\.\d+)?"
+    if re.fullmatch(rf"\s*{number}\s*", value):
+        result = float(value)
+    else:
+        part = rf"({number})\s*(ms|s|m|h|d)"
+        if not re.fullmatch(rf"\s*(?:{part}\s*)+", value):
+            raise ValueError("duration must be seconds or use ms, s, m, h, d (for example 4m30s)")
+        result = sum(float(n) * {"ms": .001, "s": 1, "m": 60, "h": 3600, "d": 86400}[unit]
+                     for n, unit in re.findall(part, value))
     if not math.isfinite(result) or result <= 0:
         raise ValueError("duration must be finite and positive")
     return result
@@ -86,10 +91,20 @@ class WaitRequest(Model):
     mode: Literal["any", "all", "quorum"] = "all"
     quorum: int | None = Field(default=None, gt=0)
     wake_on: list[Target] = Field(default_factory=list)
-    interval: float = Field(default=1, ge=.05, allow_inf_nan=False)
+    interval: float | str = Field(default=1, description="Seconds between probes, as a number or duration such as 3s; minimum 0.05.")
     deadline: datetime | None = Field(default=None, description="Absolute deadline; survives a caller retry. Overrides timeout.")
     details: bool = Field(default=False, description="Include raw probe observations for troubleshooting.")
 
+    @field_validator("interval", mode="before")
+    @classmethod
+    def parse_interval(cls, value):
+        if not isinstance(value, (str, int, float)) or isinstance(value, bool):
+            raise ValueError("interval must be seconds or a duration string")
+        value = seconds(value) if isinstance(value, str) else float(value)
+        if not math.isfinite(value) or value < .05:
+            raise ValueError("interval must be finite and at least 0.05 seconds")
+        return value
+
     @property
     def conditions(self):
         provider = self.provider or "codex"