superwait 0.3.0__tar.gz → 0.3.2__tar.gz

{superwait-0.3.0 → superwait-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: superwait
-Version: 0.3.0
+Version: 0.3.2
 Summary: Conditional waiting for coding agents
 Project-URL: Repository, https://github.com/ctxrs/superwait
 Project-URL: Issues, https://github.com/ctxrs/superwait/issues
@@ -50,6 +50,9 @@ 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:
 

{superwait-0.3.0 → superwait-0.3.2}/README.md

@@ -36,6 +36,9 @@ 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:
 

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

@@ -76,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
@@ -102,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.0 → superwait-0.3.2}/pyproject.toml

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

superwait-0.3.2/src/superwait/SKILL.md

@@ -0,0 +1,31 @@
+---
+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.
+
+Prefer a direct `wait_for` MCP call (avoids code-mode wrapper wakeups):
+
+```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.
+For a resumed worker, use an agent target with `after` set to its last cursor.
+Choose the real task deadline, not repeated 30–60-second timeouts. An expired
+continuation stays expired. On an agent timeout, check native status before
+extending: recorded state can be stale. Native process handles need native tools.
+
+If only Codex code mode is available, start `functions.exec` with
+`// @exec: {"yield_time_ms":60000}`. If it yields, resume that cell with
+`functions.wait` and `yield_time_ms: 60000`. Print `result.structuredContent`
+once, not the entire MCP envelope.
+
+For target syntax, direct-tool configuration, quorum, early wakeups, or the CLI
+fallback, read the [local API reference](references/api.md) when needed.

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

@@ -28,6 +28,9 @@ 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.")
@@ -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.3.0 → superwait-0.3.2}/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:
@@ -161,7 +182,7 @@ async def wait_for(request: WaitRequest, store: Store, progress=None):
             if e := r.get("event"):
                 c["cursor"] = e["seq"]
                 if isinstance(t, Agent):
-                    c.update(id=e["key"], handle=t.id, session=e["session"])
+                    c.update(id=e["key"], handle=t.id, session=e["session"], last_observed_at=e["at"])
                 if r["matched"]:
                     data = e["data"]
                     field = "report" if data.get("report") else "summary"
@@ -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
@@ -191,6 +212,12 @@ async def wait_for(request: WaitRequest, store: Store, progress=None):
             ready = [card(t, r) for t, r, _ in main if r["matched"]]
             pending = [card(t, r) for t, r, _ in main if not r["matched"]]
             triggered = [card(t, r) for t, r, _ in wake if r["matched"]]
+            if status == "timed_out":
+                for c in pending:
+                    if c["kind"] == "agent" and "cursor" in c:
+                        c["hint"] = ("This is the last recorded lifecycle observation, not live worker status. "
+                                     "A stop or interruption may have gone unrecorded. Check the worker with "
+                                     "the host's native tools before extending the deadline.")
             reason = {
                 "matched": f"{len(ready)} of {len(primary)} targets ready; {needed} required.",
                 "interrupted": "Wake condition matched: " + ", ".join(str(c["label"]) for c in triggered),
@@ -237,6 +264,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.3.0 → superwait-0.3.2}/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"

{superwait-0.3.0 → superwait-0.3.2}/src/superwait/references/api.md

@@ -41,9 +41,9 @@ return early independently of that threshold.
 | `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 |
+| `timeout` | String containing positive seconds or a duration such as `30s`, `4m30s`, `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 |
+| `interval` | Seconds between probes, as a number or duration such as `3s`; 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
@@ -100,11 +100,29 @@ 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.
 
+An agent ID with no lifecycle observation gets five seconds for hook delivery,
+then becomes `unobserved`. If the required target count cannot be reached without
+it, or it is a wake condition, the wait returns `error` with no continuation.
+`any` and quorum waits continue when other targets can still satisfy them.
+Check the ID, hook trust, and shared database, or use native waiting. A shorter request can
+still time out first. This is not evidence that the worker failed or finished.
+Codex task paths can remain pending while a worker in the specified parent is
+running, because their aliases are learned at stop. Already observed workers
+can run for the full requested deadline.
+
+Hook observations are not a live worker-status feed. In Codex, interruption or
+a missing stop hook can leave a worker recorded as `running`; follow-up turns
+can leave the previous `stopped` observation in place until the next stop.
+On an agent timeout, inspect the worker with native tools before extending the
+deadline. Superwait does not infer completion or failure from elapsed time.
+Use `after` for follow-up responses, as shown below.
+
 ### 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`.
+wait. `provider` is required: `codex`, `claude`, or `cursor`. The `health` field
+reports the shared database, observation count, and latest observation time.
 
 `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.
@@ -133,7 +151,9 @@ The result includes:
 - `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`
+where applicable. Agent cards with an observation include `last_observed_at`
+(Unix seconds); a timed-out pending agent also includes a native-status check
+hint. `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.
 
@@ -145,8 +165,8 @@ 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.
+an `agent` target with `after` set to its last returned cursor. Unobserved IDs
+return the setup diagnostic described above; they never count as completed.
 
 For a new response from a resumed worker:
 
@@ -166,11 +186,35 @@ 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.
+Choose the actual task deadline rather than repeatedly issuing short waits.
+Use `wake_on` for blockers that should interrupt it.
 
-In Codex code mode, start `functions.exec` with
+Prefer a direct MCP call when exposed. 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.
+The wrapper still requires model interactions when it yields; superwait cannot
+remove the host's execution-cell limit. When printing a nested MCP result, print
+`result.structuredContent` once; the full envelope repeats it as text too.
+Native terminal/process handles still require the native collection tool.
+
+### Direct tools in Codex code mode
+
+Codex 0.153.1 supports exposing selected namespaces directly. If code mode is
+enabled, add `mcp__superwait` to this list in your Codex configuration:
+
+```toml
+[features.code_mode]
+direct_only_tool_namespaces = ["mcp__superwait"]
+```
+
+Edit an existing table/list in place and preserve any other namespaces; do not
+add a duplicate TOML table. Start a fresh session and verify `wait_for` is a
+direct tool. This removes execution-cell resume calls for that wait, not MCP
+timeouts or turns needed for other work. Setup does not change this optional,
+Codex-specific setting.
+
+### CLI fallback
 
 For long Cursor waits, or waits beyond a host's configured MCP timeout, run the
 same request through the host's background terminal:
@@ -197,6 +241,7 @@ Global options go before the command: `--db PATH` selects the shared store;
 | `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 |
+| `doctor PROVIDER` | Optional `--session SESSION`; shows the database, package version, lifecycle-event count, and latest event time; exit 1 if none have been observed |
 | `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 |
@@ -206,6 +251,24 @@ 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.
 
+### Verify agent recording
+
+In Codex, open `/hooks` and review/trust the superwait hooks. Spawning a new
+worker must produce observations in the same database the MCP server reads:
+
+```sh
+superwait doctor codex
+superwait agents codex
+```
+
+`doctor` reports `no_observations` for an empty or wrong-scoped store. `observed`
+means events exist, not that the currently running host loaded the latest setup.
+Check `last_event_at` (Unix seconds) and a new worker's final report. Existing
+sessions may retain their old hooks until restarted or resumed with fresh config.
+File, HTTP, command and signal waits do not require agent hooks. Setup never
+approves hooks or bypasses host trust. If the MCP tool is absent, use the CLI
+command installed at the end of this reference, then reload the host.
+
 ## Local state
 
 Hooks and waiters share a local SQLite database, defaulting to

{superwait-0.3.0 → superwait-0.3.2}/src/superwait/server.py

@@ -16,7 +16,8 @@ def serve(store: Store, default_provider="codex"):
         "Codex task paths require session from the SessionStart context to avoid matching another conversation. "
         "Results give ready reports, pending work, triggered conditions, and a copyable continue_wait request. "
         "list_agents is for discovery or troubleshooting; a stopped response is not proof its task passed. "
-        "Unknown agents remain pending. signal reports checkpoints or blockers explicitly. "
+        "Unobserved required agents return an actionable error after a short hook-delivery grace period. "
+        "Use one realistic deadline, not repeated short waits. signal reports checkpoints or blockers explicitly. "
         "For a wait longer than the host's MCP timeout, use the superwait CLI in its background terminal. "
         "Cancelling a wait never stops the agents it observes."
     ))
@@ -29,7 +30,8 @@ def serve(store: Store, default_provider="codex"):
         A target is agent, signal, file, http, or command. Command probes execute
         repeatedly without a shell: use observational checks. File changed uses
         the state at call entry. timeout accepts 30s, 10m, 2h, 1d. An absolute
-        deadline overrides timeout and preserves the deadline on retries.
+        deadline overrides timeout and preserves the deadline on retries. Use a
+        realistic task deadline rather than repeating 30-60 second requests.
         Returns matched/interrupted/timed_out/error, ready reports, pending work,
         and triggered conditions. Pass continue_wait back as request to continue
         remaining work with the same deadline. details=true adds raw observations.
@@ -48,7 +50,7 @@ def serve(store: Store, default_provider="codex"):
         Specify session when known. Empty means no hooks have observed these
         agents, not that they finished. after=seq waits for a later observation.
         """
-        return {"agents": store.agents(provider, session), "limit": 50}
+        return {"agents": store.agents(provider, session), "limit": 50, "health": store.health(provider, session)}
 
     @server.tool()
     def signal(key: str, state: str = "ready", data: dict | None = None) -> dict[str, Any]:

{superwait-0.3.0 → superwait-0.3.2}/src/superwait/setup.py

@@ -117,4 +117,6 @@ def configure(provider, project=None, db=None, max_wait="24h"):
         + shlex.join(prefix) + " wait --request wait.json\n```\n")
     return {"scope": "user" if user_scope else "project",
             "written": written, "database": str(db), "max_wait": max_wait,
-            "next": "Restart the host and review its MCP/hooks trust prompts. Cursor: use the CLI for waits beyond its tool timeout."}
+            "next": "Restart the host and review its MCP/hooks trust prompts (/hooks in Codex). "
+                    f"After spawning a worker, run superwait doctor {provider} to verify lifecycle observations. "
+                    "Cursor: use the CLI for waits beyond its tool timeout."}

{superwait-0.3.0 → superwait-0.3.2}/src/superwait/store.py

@@ -111,3 +111,16 @@ class Store:
     def prune(self, days=30):
         with self.connect() as db:
             return db.execute("DELETE FROM events WHERE at < ?", (time.time() - days * 86400,)).rowcount
+
+    def health(self, provider, session=None):
+        query = "SELECT COUNT(*) AS agent_events, MAX(at) AS last_event_at FROM events WHERE kind='agent' AND provider=?"
+        args = [provider]
+        if session is not None:
+            query += " AND session=?"
+            args.append(session)
+        with self.connect() as db:
+            result = dict(db.execute(query, args).fetchone())
+        return {"status": "observed" if result["agent_events"] else "no_observations",
+                "provider": provider, "session": session, "database": str(self.path), **result,
+                "next": "Verify a newly spawned worker appears and its final report arrives. "
+                        "If not, review hook trust (/hooks in Codex), reload the host, and check that hooks and MCP use this database."}

superwait-0.3.2/tests/test_observations.py

@@ -0,0 +1,156 @@
+import asyncio
+import json
+
+import pytest
+from pydantic import ValidationError
+
+from superwait import engine
+from superwait.cli import main
+from superwait.engine import wait_for
+from superwait.hooks import record_hook
+from superwait.models import WaitRequest, seconds
+from superwait.store import Store
+
+
+@pytest.mark.parametrize("value,expected", [("4m30s", 270), ("1h 2m 3.5s", 3723.5),
+    ("200ms", .2), (" 1.5 ", 1.5), ("0m1s", 1)])
+def test_compound_durations(value, expected):
+    assert seconds(value) == expected
+
+
+@pytest.mark.parametrize("value", ["", "0s", "-1s", "1m nope", "1m30", "nan", "1e3s", "1..5s"])
+def test_duration_rejects_malformed_or_nonpositive_input(value):
+    with pytest.raises(ValueError):
+        seconds(value)
+
+
+@pytest.mark.parametrize("interval", [3, "3s", "3000ms"])
+def test_interval_duration_uses_shared_request_schema(interval):
+    request = WaitRequest(agents=["worker"], timeout="4m30s", interval=interval)
+    assert request.interval == 3
+    assert request.duration() == 270
+    assert WaitRequest.model_validate_json(request.model_dump_json()).interval == 3
+
+
+@pytest.mark.parametrize("interval", [None, True, {}, "0s", "1ms", float("inf"), float("nan")])
+def test_interval_rejects_invalid_values(interval):
+    with pytest.raises(ValidationError):
+        WaitRequest(agents=["worker"], interval=interval)
+
+
+async def test_missing_agent_errors_without_spending_the_whole_deadline(tmp_path, monkeypatch):
+    monkeypatch.setattr(engine, "AGENT_OBSERVATION_GRACE", .1)
+    result = await asyncio.wait_for(wait_for(WaitRequest(agents=["missing"], timeout="1h", interval=30),
+                                           Store(tmp_path / "db")), 1)
+    assert result["status"] == "error"
+    assert result["pending"][0]["state"] == "unobserved"
+    assert "doctor" in result["pending"][0]["error"]
+    assert result["continue_wait"] is None
+
+
+async def test_late_hook_recovers_during_grace_and_observed_worker_can_run_longer(tmp_path, monkeypatch):
+    monkeypatch.setattr(engine, "AGENT_OBSERVATION_GRACE", .15)
+    store = Store(tmp_path / "db")
+    waiting = asyncio.create_task(wait_for(WaitRequest(agents=["worker"], timeout="2s", interval=.05), store))
+    await asyncio.sleep(.06)
+    store.emit("agent", "worker", "running", provider="codex", session="parent")
+    await asyncio.sleep(.2)
+    assert not waiting.done()
+    store.emit("agent", "worker", "stopped", provider="codex", session="parent", data={"summary":"finished"})
+    assert (await waiting)["ready"][0]["result"] == "finished"
+
+
+async def test_task_path_waits_for_stop_mapping_while_parent_has_running_worker(tmp_path, monkeypatch):
+    monkeypatch.setattr(engine, "AGENT_OBSERVATION_GRACE", .1)
+    store = Store(tmp_path / "db")
+    store.emit("agent", "uuid", "running", provider="codex", session="parent")
+    waiting = asyncio.create_task(wait_for(WaitRequest(agents=["/root/reviewer"], session="parent",
+                                                      timeout="2s", interval=.05), store))
+    await asyncio.sleep(.2)
+    assert not waiting.done()
+    transcript = tmp_path / "worker.jsonl"
+    transcript.write_text(json.dumps({"type":"session_meta","payload":{"id":"uuid",
+        "source":{"subagent":{"thread_spawn":{"parent_thread_id":"parent","agent_path":"/root/reviewer"}}}}})+"\n")
+    record_hook("codex", {"hook_event_name":"SubagentStop", "session_id":"parent", "agent_id":"uuid",
+                          "agent_transcript_path":str(transcript),"last_assistant_message":"done"}, store)
+    assert (await waiting)["ready"][0]["result"] == "done"
+
+
+async def test_other_parent_cannot_keep_unknown_path_wait_alive(tmp_path, monkeypatch):
+    monkeypatch.setattr(engine, "AGENT_OBSERVATION_GRACE", .1)
+    store = Store(tmp_path / "db")
+    store.emit("agent", "uuid", "running", provider="codex", session="other")
+    result = await wait_for(WaitRequest(agents=["/root/reviewer"], session="parent", timeout="2s", interval=.05), store)
+    assert result["status"] == "error"
+
+
+@pytest.mark.parametrize("state,after", [("running", 0), ("stopped", 1)])
+async def test_agent_timeout_exposes_observation_age_and_native_fallback(tmp_path, state, after):
+    store = Store(tmp_path / "db")
+    cursor = store.emit("agent", "worker", state, provider="codex", session="parent")
+    observed_at = store.latest("agent", "worker", provider="codex")["at"]
+    result = await wait_for(WaitRequest(targets=[{"kind": "agent", "provider": "codex",
+        "id": "worker", "after": after}], timeout="100ms", interval=.05), store)
+    assert result["status"] == "timed_out"
+    pending = result["pending"][0]
+    assert pending["state"] == ("running" if state == "running" else "awaiting_new_event")
+    assert pending["cursor"] == cursor
+    assert pending["last_observed_at"] == observed_at
+    assert "native tools" in pending["hint"]
+    # A timeout must neither manufacture a terminal event nor lose its deadline.
+    assert store.latest("agent", "worker", provider="codex")["seq"] == cursor
+    assert result["continue_wait"]["deadline"] == result["deadline"]
+
+
+async def test_matched_agent_and_file_timeout_do_not_get_stale_worker_hint(tmp_path):
+    store = Store(tmp_path / "db")
+    store.emit("agent", "worker", "stopped", provider="codex", session="parent", data={"summary": "done"})
+    result = await wait_for(WaitRequest(agents=["worker"], timeout="1s"), store)
+    assert result["status"] == "matched"
+    assert result["ready"][0]["result"] == "done"
+    assert "last_observed_at" in result["ready"][0]
+    assert "hint" not in result["ready"][0]
+    result = await wait_for(WaitRequest(targets=[{"kind": "file", "path": str(tmp_path / "absent")}],
+                                        timeout="100ms"), store)
+    assert result["status"] == "timed_out"
+    assert "hint" not in result["pending"][0]
+    assert "last_observed_at" not in result["pending"][0]
+
+
+async def test_unknown_agent_does_not_override_ready_quorum_or_wake(tmp_path):
+    store = Store(tmp_path / "db")
+    store.emit("signal", "ready", "ready")
+    for request in [WaitRequest(agents=["unknown"], targets=[{"kind":"signal","key":"ready"}], mode="any"),
+                    WaitRequest(agents=["unknown"], wake_on=[{"kind":"signal","key":"ready"}])]:
+        assert (await wait_for(request, store))["status"] in ("matched", "interrupted")
+
+
+@pytest.mark.parametrize("mode,quorum", [("any", None), ("quorum", 2)])
+async def test_unobserved_optional_agent_does_not_abort_pending_threshold(tmp_path, monkeypatch, mode, quorum):
+    monkeypatch.setattr(engine, "AGENT_OBSERVATION_GRACE", .1)
+    store = Store(tmp_path / "db")
+    store.emit("signal", "first", "ready")
+    keys = ["later"] if mode == "any" else ["first", "later"]
+    waiting = asyncio.create_task(wait_for(WaitRequest(agents=["unknown"],
+        targets=[{"kind": "signal", "key": key} for key in keys], mode=mode, quorum=quorum,
+        timeout="2s", interval=.05), store))
+    await asyncio.sleep(.2)
+    assert not waiting.done()
+    store.emit("signal", "later", "ready")
+    result = await waiting
+    assert result["status"] == "matched"
+    assert result["pending"][0]["state"] == "unobserved"
+
+
+def test_doctor_distinguishes_missing_scoped_observations(tmp_path, monkeypatch, capsys):
+    db = tmp_path / "db"
+    store = Store(db)
+    for expected in (1, 0):
+        monkeypatch.setattr("sys.argv", ["superwait", "--db", str(db), "doctor", "codex", "--session", "parent"])
+        with pytest.raises(SystemExit) as exit:
+            main()
+        assert exit.value.code == expected
+        result = json.loads(capsys.readouterr().out)
+        assert result["agent_events"] == (0 if expected else 1)
+        store.emit("agent", "worker", "running", provider="codex", session="parent")
+    assert store.health("codex", "other")["status"] == "no_observations"

{superwait-0.3.0 → superwait-0.3.2}/tests/test_transport.py

@@ -95,3 +95,17 @@ async def test_mcp_cancellation_reaps_its_command_probe(tmp_path):
                 except ProcessLookupError:
                     break
                 await asyncio.sleep(.02)
+
+
+async def test_mcp_duration_strings_and_missing_hook_diagnostic(tmp_path):
+    params = StdioServerParameters(command=sys.executable, args=["-m", "superwait", "--db", str(tmp_path / "db"), "serve"], env=dict(os.environ))
+    async with Client(params) as client:
+        health = (await client.call_tool("list_agents", {"provider": "codex"})).structured_content["health"]
+        assert health["status"] == "no_observations"
+        assert health["agent_events"] == 0
+        result = await asyncio.wait_for(client.call_tool("wait_for", {"request": {
+            "agents": ["missing"], "timeout": "1m30s", "interval": "10s"}}), 8)
+        assert not result.is_error
+        assert result.structured_content["status"] == "error"
+        assert result.structured_content["pending"][0]["state"] == "unobserved"
+        assert result.structured_content["continue_wait"] is None

{superwait-0.3.0 → superwait-0.3.2}/uv.lock

@@ -746,7 +746,7 @@ wheels = [
 
 [[package]]
 name = "superwait"
-version = "0.3.0"
+version = "0.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },

superwait-0.3.0/src/superwait/SKILL.md

@@ -1,26 +0,0 @@
----
-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.