@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/run.md

@@ -0,0 +1,99 @@
+# api.run(argv, input=None, cwd=None, env=None, timeout=120, background=False) -> dict
+<!-- group: Coding -->
+<!-- also: subprocess, exec, argv, stdin, python -c, node -e, quoting, no shell -->
+
+Run one program with exactly these arguments. **No shell. Gated** (it asks as
+`bash`, showing the equivalent command line). **Never raises — read
+`exit_code`.**
+
+## Why this exists
+
+A command used to cross up to four interpreters on its way to the program:
+your Python string, then `bash -c`, then often PowerShell or `python -c` or
+`node -e` or a heredoc. Each layer has its own escapes, and none of them shows
+you what the next one received. Python ate the backslash in `'\''`; bash ate
+`$_` before PowerShell saw it; a regex lost its `\$` and silently matched
+nothing. Those were the commonest ways scripts here broke.
+
+`run` removes the layers instead of asking you to get them right. `argv` goes
+to the operating system as a list, so `argv[1]` arrives as `argv[1]` — nothing
+is expanded, split, globbed or quoted. And a script for another interpreter
+goes in as **`input`**, on stdin, so it is never on a command line at all.
+
+## Examples
+
+```python
+r = await api.run(["git", "log", "--format=%h %s", "-5"])
+```
+
+A script in another language — the source is a value, not something to quote:
+
+```python
+src = r'''
+import sys, re
+print(re.findall(r"\$[0-9.]+", sys.stdin.read()))
+'''
+r = await api.run(["python", "-"], input=src)
+r = await api.run(["node", "-"], input="console.log(process.version)")
+```
+
+Arguments with spaces, quotes and dollar signs need nothing:
+
+```python
+await api.run(["git", "commit", "-m", "Fix the 'it's' case; costs $0"])
+```
+
+Elsewhere, with extra environment:
+
+```python
+await api.run(["pnpm", "test"], cwd="widgex-ide/extension", env={"CI": "1"}, timeout=900)
+```
+
+## Options
+
+- **`argv`** — a list of strings. A single string is refused: that is a command
+  line, and `api.bash` is the call for those.
+- **`input`** — `str` or `bytes`, written to stdin, which is then closed. With
+  no `input`, stdin is empty.
+- **`cwd`** — any path `api.*` accepts, including `/c/...` and `~`.
+- **`env`** — set on top of the inherited environment, never instead of it.
+- **`timeout`**, **`background`** — as for `api.bash`; a background run is
+  managed with `bash_output`, `bash_list` and `bash_kill`.
+
+`argv[0]` is looked up on `PATH` the way a shell would, and the result carries
+the full path in `program`, so "which python was that" has an answer. On
+Windows the Microsoft Store's `python.exe` stubs are skipped. A path with a
+directory in it — `./scripts/x.mjs` — is relative to `cwd`, or the shell's cwd.
+
+**Batch files on Windows.** `npm`, `pnpm` and `npx` are `.cmd` files, and
+Windows runs those through cmd.exe, which reads `& | < > ^ % "` in their
+arguments as cmd syntax. There is no escaping that is safe for every batch
+file, so `run` refuses such an argument (exit code 2, with the reason) rather
+than pass it on. Plain arguments to `.cmd` files work as normal.
+
+The permission card shows the call as the bash command it amounts to:
+`env` as `VAR=value` before it, and `input` as a heredoc after it, so what
+you approve is everything the call does.
+
+## Returns
+
+```python
+{"stdout": str, "stderr": str, "exit_code": int, "program": str}
+```
+
+`exit_code` 127 with `"…: not found on PATH"` means the program does not exist.
+`-1` means it timed out or could not start, exactly as for `bash`.
+
+## Getting it wrong
+
+**Putting a pipeline in `argv`.** `["ls", "|", "grep", "x"]` passes `|` to
+`ls`. Pipes, globs and `&&` are shell features: use `api.bash` for those, or do
+the filtering in Python.
+
+**Writing the script as a normal string.** `input="print('a\nb')"` is Python
+source in *your* Python first, and `\n` there is a newline before `run` ever
+sees it. Use a raw string, `r'''…'''`, for any source with backslashes.
+
+## See also
+
+`bash`, `powershell`, `sandbox`

package/python/xactor/man/sandbox.md

@@ -0,0 +1,144 @@
+# The sandbox
+<!-- group: Concepts -->
+
+Why `import`, `open()` and `os.*` are refused, and what to use instead.
+
+Your code runs in a real Python process with a PEP 578 audit hook installed.
+The hook sees every security-sensitive operation at the C level and, once
+installed, cannot be removed by anything you execute. It is not a linter and
+not a name filter — rebinding, `getattr`, or reaching through a builtin all hit
+the same wall.
+
+## The rule
+
+Inside the code you write, **only `api` reaches the outside world.**
+
+Refused in your code:
+
+- `open()`, and every other direct file access
+- `os.system`, `os.popen`, `subprocess.*`, `socket`, and importing them
+- `eval`, `exec`, `compile`, `input`, `breakpoint`
+- `ctypes` and friends, which would let native code step around the hook
+- `time.sleep`, which would freeze the whole shell — `await asyncio.sleep(n)`
+
+Allowed in your code: ordinary Python, **including imports of the pure
+standard library**. These import normally:
+
+```
+abc ast base64 binascii bisect calendar cmath collections collections.abc
+contextlib copy csv dataclasses datetime decimal difflib enum fnmatch
+fractions functools gzip hashlib heapq hmac html html.parser inspect io
+itertools json keyword math numbers operator pprint random re secrets shlex
+statistics string struct textwrap tomllib traceback types typing unicodedata
+urllib urllib.parse uuid xml.etree.ElementTree zlib
+asyncio os os.path pathlib time
+```
+
+`os` is the sandboxed one (paths, no environment) and `time` has no `sleep`;
+`json`, `os`, `Path` and `asyncio` are also bound without importing. None of
+these can reach the system on their own: a file, process or socket any of them
+tries to open is refused by the same hook as your own `open()`. A refused
+import raises `ImportError`, so `try: … except ImportError:` works.
+
+The same operations *are* permitted inside an `api.*` method's own body. That
+is not an inconsistency: an api call is a declared, named, journalled,
+possibly-gated action, and the whole point of routing through `api` is that the
+IDE can see it. Your code calling `open()` directly is a file access nobody
+recorded.
+
+## What to use instead
+
+| You reached for | Call this |
+|---|---|
+| `open(p).read()` | `await api.read_file(p, raw=True)` — the exact text, no line numbers |
+| `open(p, "w").write(s)` | `await api.write_file(p, s)` — `s` may be `bytes` |
+| `os.listdir(d)` | `await api.ls(d)` |
+| `os.path.exists(p)` | `await api.glob(p)` — empty list means no |
+| `glob.glob(pat)` | `await api.glob(pat)` |
+| `subprocess.run(argv)` | `await api.run(argv)` — no shell, nothing to quote |
+| a shell pipeline | `await api.bash(cmd)` |
+| PowerShell | `await api.powershell(script)` |
+| a third-party module | `await api.run(["python", "-"], input=script)` |
+| `os.chdir(d)` | `await api.cd(d)` |
+| `requests.get(url)` | `await api.run(["curl", "-s", url])`, or the browser calls |
+
+**Do not reach for `api.bash("python -c ...")` to get at a module.** It is a
+second interpreter, outside this sandbox, behind two more layers of quoting —
+the commonest way scripts here broke. If the module is in the list above,
+import it; if it is not, pass the script as `input=` to `api.run`, where
+nothing is quoted at all.
+
+`api.bash`, `api.run` and `api.powershell` are the escape hatch. What they run
+is a normal process — it is not sandboxed, because the *user approved that
+specific command*. That approval is what the sandbox is protecting.
+
+## Modes
+
+The shell runs in one of several sandbox modes chosen by the IDE. `strict` is
+the tightest and is what the rules above describe. Looser modes widen which
+paths an api method may touch; none of them let your own code import or open
+anything. Write code that works under `strict` and it works everywhere.
+
+## Seals
+
+An organisation can **seal** a file or a folder against some or all models —
+read, write, execute, copy or move. A seal is not a permission: no mode, grant
+or approval lifts it, and there is nobody to ask. When a call is refused with
+"WidgeX Seal", carry on without that file and say in your reply that it was
+sealed.
+
+Every way of reaching a sealed file is refused, not only `read_file`:
+`edit_file` (an edit reads), `grep` (the file is skipped and named), `bash`,
+`run` and `powershell` commands that name it — directly, through a glob, a
+`cd`, git's `rev:path`, or inline code that mentions it — `drive` or
+`navigate` to it as a `file://` page, `aux_context=` and any other api that
+would hand it to a model. A command that copies or moves a file out of a
+sealed folder is refused too, because the copy would not be sealed.
+
+Output is screened as well: a line of a read-sealed file that reaches your
+result by any route is replaced with a notice saying it was withheld. Do not try
+to recover withheld lines another way — encoding or transforming a sealed file
+to get it past the screen is exactly what a seal forbids, even where nothing
+can detect it.
+
+## Examples
+
+```python
+# Wrong — open() is refused by the audit hook, and the exec dies here.
+import json
+data = json.load(open("package.json"))
+
+# Right.
+import json
+data = json.loads(await api.read_file("package.json", raw=True))
+```
+
+Checking whether something exists:
+
+```python
+hits = await api.glob("src/**/config.ts")
+if not hits:
+    return "no config found"
+return await api.read_file(hits[0])
+```
+
+## Getting it wrong
+
+**Treating a refusal as a bug in your code and retrying with a different
+spelling.** `__builtins__["open"]`, `os = __import__("os")` and every other
+route hit the same hook. If an api call cannot do what you need, that is a
+missing capability — say so with `api.report_bug(kind="missing_capability")`
+and route around it, usually via `api.run`.
+
+**Putting a whole file's contents into `api.bash` as a heredoc to avoid
+`write_file`.** It works, but `bash` changes are not journalled: they will not
+show up in `xylon_get_diff` and cannot be reverted with the turn. Use
+`write_file` and `edit_file` for file contents.
+
+**Assuming a refusal is silent.** It raises, which aborts the entire exec —
+every line after it in that block never runs. Keep sandbox-risky experiments in
+their own small exec.
+
+## See also
+
+`permissions`, `bash`, `read_file`, `write_file`, `report_bug`

package/python/xactor/man/session_fork.md

@@ -0,0 +1,74 @@
+# api.session_fork(prompt, aux_context=None) -> dict
+<!-- group: Sessions -->
+
+Fork into an independent clone: copied repo, copied conversation. Gated.
+
+The child runs in a **cloned copy of the repository** and starts with a copy of
+this conversation's history. Your `prompt` becomes its opening task. It runs
+independently; this call returns as soon as it exists.
+
+## Options
+
+- **`prompt`** — the forked session's starting task. Unlike `agent`,
+  the child already knows what you have been doing, so this can be short: it is
+  the instruction, not the briefing.
+- **`aux_context`** — path to a `.md` or `.txt` file, absolute or relative to
+  the cwd. Its **contents** are read now and attached to the child's opening
+  prompt. Capped at 100,000 characters. Read on this side because the fork runs
+  in a *different* checkout — a path you passed might not exist there.
+
+There is no `model` and no `summary`. The conversation copy is the briefing.
+
+## Returns
+
+```python
+{"sessionId": str, "xylonNodePath": str}
+```
+
+Immediately. The fork exists; it has not finished.
+
+## Examples
+
+Trying an approach without committing the user's tree to it:
+
+```python
+child = await api.session_fork(
+    "Try the approach we just rejected — swap the audit hook for a subprocess "
+    "jail — and report whether the test suite passes. Change nothing else."
+)
+return f"Forked to {child['sessionId']}; its edits are in a clone, not here."
+```
+
+Two approaches in parallel, compared afterwards:
+
+```python
+a = await api.session_fork("Implement it with a ContextVar, as discussed.")
+b = await api.session_fork("Implement it by threading the id through explicitly.")
+ra = await api.session_join(a["sessionId"], timeout=1800)
+rb = await api.session_join(b["sessionId"], timeout=1800)
+return {"contextvar": ra.get("lastMessage"), "explicit": rb.get("lastMessage")}
+```
+
+## Getting it wrong
+
+**Expecting the fork's edits to appear in your repo.** They will not. The clone
+is a separate checkout, and nothing merges it back. A fork's output is what it
+*tells* you, plus a diff you can read from its xylon node. If you want the
+files changed here, do not fork.
+
+**Forking for routine parallelism.** Cloning a repository is expensive, and two
+forks of a large tree cost real disk and real time. `agent` shares the
+directory; `agent` shares even more.
+
+**Forking to give a child context.** It works — the history is copied — but you
+copy *everything*, including whatever is irrelevant. `agent(wait=False,
+summary=...)` gives the child three sentences instead of an hour.
+
+**Forgetting it is gated and long-lived.** The user approves a fork; it then
+sits there consuming tokens until it finishes or is terminated. You can
+`session_terminate` a fork, because it is your descendant.
+
+## See also
+
+`agent`, `session_join`, `session_terminate`,
+`agent-vs-fork`, `sessions`, `xylon`

package/python/xactor/man/session_harness.md

@@ -0,0 +1,109 @@
+# api.session_harness(prompt, token_budget=None, window='day', machine=None, model=None) -> dict
+<!-- group: Sessions -->
+<!-- also: session_daemonize -->
+
+Turn this session into a harness: the same prompt, re-served every turn. Gated.
+
+A harness runs unattended. At the start of each turn it is handed `prompt` again
+and works until the turn ends; then it starts over. It stops when
+`api.session_rest` is called, when its machine reaches an end state, when a
+human stops it, or when it reaches a limit:
+
+- **tokens** — `token_budget` per window, 1,000,000 per day if you give none.
+  There is no "no limit".
+- **cycles** — 50 in one run.
+
+Reaching a limit stops the harness until a person presses Run in the Harness
+Manager. It does not wait and resume by itself.
+
+**A harness cannot ask the user anything.** That constraint shapes everything
+below.
+
+## Options
+
+- **`prompt`** — the standing task, re-served verbatim every turn. Write it for
+  a session with no memory of the last run: what to look at, what counts as
+  work, and what to do when there is nothing to do.
+- **`token_budget`** — tokens per window, 1,000 to 100,000,000. Omit it for
+  1,000,000. Spending it stops the harness until a person restarts it.
+- **`window`** — `'hour'`, `'day'` or `'week'`. Default `'day'`.
+- **`machine`** — the name of a state machine in `.widgex/harnesses/`, which
+  splits the standing task into states with their own prompts and gated
+  transitions. Every state must have a path to a `"terminal": true` state, or
+  the machine does not load. See `harness` for the format.
+- **`model`** — the model every run uses, e.g. `'claude-opus-5'`, or
+  `'provider/model'` when two providers share an id. An unknown id is refused,
+  with the list of valid ones, and **nothing is armed**.
+
+**Omitting `machine` or `model` keeps whatever is currently set.** This is
+deliberate: re-arming to change a budget must not silently unbind a machine.
+There is no api route to *clear* a binding — that is done from the Harness
+Manager.
+
+## Returns
+
+```python
+{"sessionId": str, "runs": int, "spent": int,
+ "budget": {"tokens": int, "window": str},
+ "machine": {"name": str, "state": str} | None,
+ "model": {"providerId": str, "modelId": str} | None}
+```
+
+`runs` and `spent` are the counters for the current window, so a re-arm shows
+you what the previous arming had used.
+
+## Examples
+
+A standing task with an explicit idle branch:
+
+```python
+return await api.session_harness(
+    "Check the CI dashboard for newly failing tests on main. For each one, find "
+    "the commit that broke it and open an issue naming that commit. If nothing "
+    "is failing, say so in one line and stop for this turn.",
+    token_budget=200_000,
+    window="day",
+)
+```
+
+Raising a budget without disturbing the machine binding:
+
+```python
+return await api.session_harness(prompt, token_budget=500_000, window="week")
+```
+
+Stopping the loop from inside it:
+
+```python
+if not failures:
+    await api.session_rest("main has been green for three consecutive runs")
+    return "Nothing failing — rested."
+```
+
+## Getting it wrong
+
+**Writing a prompt that assumes the previous turn.** "Continue where you left
+off" reaches a session that does not know where that was. State is in the repo
+and the tree, not in the harness. Say how to find it.
+
+**Calling `ask_user`.** It is denied outright — "this harness runs unattended and
+cannot ask questions". Decide, or `session_rest` with the question as your
+reason.
+
+**Expecting a gated call to prompt.** It will not. Gated calls resolve from
+grants: auto-allowed or auto-denied. A harness that needs `edit_file` and has no
+grant for it will be refused every turn, forever.
+
+**No exit condition.** Without a `session_rest` or an end state, the harness
+runs until it hits its token or cycle limit and stops there, having finished
+nothing. Decide what "finished" means before arming.
+
+**Using `session_terminate` to stop it.** That destroys the session. `session_rest`
+stops the loop and leaves it re-armable.
+
+**Assuming `machine=None` unbinds.** It keeps the current machine. Unbinding is
+a Harness Manager action.
+
+## See also
+
+`harness`, `session_rest`, `permissions`, `ask_user`, `sessions`

package/python/xactor/man/session_join.md

@@ -0,0 +1,102 @@
+# api.session_join(session_id, timeout=None) -> dict
+<!-- group: Sessions -->
+
+Wait for a child session to finish its current turn. Not gated.
+
+Blocks until the target reaches `done` or `error`, or until the timeout — a
+child still working then comes back as `timeout` and **keeps running**.
+
+## Options
+
+- **`session_id`** — the id from `session_fork` or `agent`.
+- **`timeout`** — seconds. Must satisfy `0 < timeout <= 3600`. Defaults to
+  **300**. A non-number, zero, or anything over an hour raises `ValueError`
+  before it waits.
+
+**Raise the exec's own `timeout_seconds` above this**, or the tool call running
+your code is killed while the join is still waiting. The tool call defaults to
+120 seconds, which is shorter than this call's own default of 300.
+
+## Returns
+
+```python
+{"lastMessage": str, "xylonNodePath": str, "status": "done" | "error" | "timeout"}
+```
+
+plus an **`error`** key when the run failed.
+
+`status` is the only reliable signal:
+
+| `status` | Meaning | `lastMessage` |
+|---|---|---|
+| `done` | The turn finished. | the child's answer |
+| `error` | The run failed. | **empty** — read `error` |
+| `timeout` | Still working. | whatever it had said so far |
+
+A failed run has an **empty `lastMessage`**, because the reason is recorded as
+a system message rather than an assistant one. An empty `lastMessage` on its
+own cannot be told apart from a child that simply had nothing to say.
+
+## Examples
+
+Check `status` first. Always:
+
+```python
+r = await api.session_join(child_id, timeout=900)
+if r["status"] == "error":
+    return {"child_failed": child_id, "why": r.get("error")}
+if r["status"] == "timeout":
+    return f"{child_id} is still working; I'll leave it running."
+return r["lastMessage"]
+```
+
+Polling, rather than one long block:
+
+```python
+for _ in range(4):
+    r = await api.session_join(child_id, timeout=600)
+    if r["status"] != "timeout":
+        break
+    await api.todo_write(todos)      # keep the user informed between waits
+return r
+```
+
+Waiting on several children:
+
+```python
+out = {}
+for cid in child_ids:
+    r = await api.session_join(cid, timeout=300)
+    out[cid] = r["lastMessage"] if r["status"] == "done" else r["status"]
+return out
+```
+
+## Getting it wrong
+
+**Reading `lastMessage` without checking `status`.** This is the failure this
+call is most known for:
+
+```python
+# Wrong — a crashed child reports as a silent success.
+r = await api.session_join(cid)
+return r["lastMessage"] or "the child had nothing to add"
+```
+
+You will tell the user the work is done when it failed.
+
+**Leaving the exec timeout at its default.** `timeout=1800` inside a tool call
+capped at 120 seconds means your code dies at 120 seconds and the child is
+orphaned. Set the tool call's `timeout_seconds` higher than the join's.
+
+**Treating `timeout` as a failure.** The child is still going. Either wait
+again or report that it is running; do not restart the work.
+
+**Joining a `agent`.** A delegate is not a session and has no id — it
+already blocked and returned its answer directly.
+
+**Joining something that is not your descendant.** Only sessions you spawned
+are yours to wait on.
+
+## See also
+
+`agent`, `session_fork`, `session_terminate`, `agent`, `sessions`

package/python/xactor/man/session_land.md

@@ -0,0 +1,73 @@
+# Landing a child's branch (no api call — the user does this)
+
+<!-- group: Sessions -->
+
+Taking a branch child's work back into a parent branch. **There is no
+`api.session_land`.** Landing is the "Land changes" wizard in the session
+queue, and the user drives it.
+
+This page is here because the operation is one you will be asked about and will
+want to explain — and because it used to document a call, in enough detail that
+an agent reading the manual would go on to invoke one that has never existed.
+What follows is what landing does, so you can say so; the last section is what
+to do instead of reaching for it.
+
+## Only what the child did
+
+A child spawned with `api.agent(isolate=True)` gets a copy of the parent's
+uncommitted work at the moment it was spawned. That copy is committed on the
+child's branch so its own work can be measured against something, but it is
+**not** the child's work and it does not come back — the parent already has it.
+
+The consequence worth knowing when you are reading a landing preview: a child
+that has done nothing of its own has **nothing to land**, even though its
+branch carries a commit. It is reported as idle rather than merged. Merging it
+would put the parent's own work back on top of the parent, and with three
+children it would do so three times.
+
+## What the preview answers
+
+The wizard previews before it merges, and the question it answers is the one
+landing children one at a time cannot: **which files more than one child
+touched**. Git will merge two children's edits to the same file perfectly
+happily, and the result can still be one child silently undoing the other. The
+overlap list names those paths and the branches that collide on them, while
+there is still a choice about the order — or about whether to take both.
+
+## Outcomes you may be shown
+
+- **`landed`** — its work is in the target branch.
+- **`conflicted`** — git stopped. The pass stops with it.
+- **`skipped`** — deliberately left out: mid-turn, blocked by uncommitted
+  work, or already in the target. The pass carries on.
+- **`not-attempted`** — the pass had already stopped. Nothing was done to it.
+- **`failed`** — it threw. Distinct from a conflict, which is a resting state.
+
+## If a landing conflicts, stop
+
+Report what happened and stop. Do not go into the worktree and fix the merge:
+the user has a screen for exactly that, with both sides in front of them, and a
+conflict is a question about intent rather than a mechanical failure. Say which
+branch stopped it and what it collided with.
+
+Taking one side of a conflicted file *when the user has asked you to* is
+ordinary work and is not gated — `git checkout --ours -- <path>` moves no ref.
+Switching branches still is.
+
+## Do not do this with git
+
+Running `git merge` in `api.bash` reaches the same commits and skips everything
+that makes the operation safe: the per-repository lock that stops two windows
+landing at once, the refusal when either branch has moved since it was looked
+at, the sibling-overlap warning, and the accounting write that clears the
+child's row in the user's queue and lets its branch be deleted afterwards. A
+repository merged that way looks right and has no record of what happened to
+it.
+
+So when a landing is what is wanted: say so, and let the user run the wizard.
+
+## See also
+
+`agent` spawns the children this is about — `isolate=True` is the one that
+gives a child a branch and a worktree of its own. `agent-vs-fork` covers which
+relationship to reach for in the first place.

package/python/xactor/man/session_nudge.md

@@ -0,0 +1,73 @@
+# api.session_nudge(session_id, prompt) -> dict
+<!-- also: nudge, re-prompt, reprompt, wake_child, chase, reuse_subagent, persistent_subagent -->
+<!-- group: Handing work to another agent -->
+
+Send a fresh prompt into a child of yours that has gone idle. Requires
+permission; a harness holding the session-spawning grant is allowed it without
+asking.
+
+Two jobs, and the second is the one worth planning around.
+
+## Chasing
+
+A subagent that stopped without finishing is not lost. It still has everything
+it read, everything it worked out, and whatever it half-did. Name **what is
+outstanding**, in the words you dispatched it with:
+
+```python
+api.session_nudge(child, "The importer is converted but you never said whether "
+                         "the fixtures still pass. Run them and report.")
+```
+
+"Finish the task" tells it nothing it did not already believe it had done. If
+you dispatched it with `must=[…]`, those obligations are the words to use — and
+when a child ends, the notice you are served names them for you.
+
+A subagent that stopped is usually not being lazy. It hit something: a decision
+it could not make, a test it could not run, a dependency that is not there. Ask
+what stopped it as well as telling it to carry on — and if the answer is a
+decision, that is not something to nudge. That is something to take to the user.
+
+## Reuse
+
+The expensive part of a subagent is not the subagent. It is the reading: the
+files it had to open before it could say anything useful. A child that has
+already read the importer is the cheapest possible place to send your next
+question about the importer, because it is not going to read it again.
+
+```python
+for row in await api.children():
+    if row["nudgeable"] and "importer" in (row["asked"] or ""):
+        await api.session_nudge(row["sessionId"], "What does csv.ts do with "
+                                                  "newlines inside a quoted field?")
+        break
+```
+
+`api.children()` is the roster. Match on **`asked`** — what that child was
+originally sent to do — and not on `label`, which is overwritten with the branch
+name and so reads the same for every child sharing a worktree.
+
+This matters most to an agent that cannot read anything itself. If every
+question costs a fresh subagent that starts from an empty head, delegating is a
+tax on curiosity; if it costs a re-prompt, it is just how you work.
+
+## What comes back
+
+`{delivered: True}`, or `{delivered: False, reason: "..."}`.
+
+A refusal is an ordinary answer rather than an exception, because the commonest
+one — *"it is still working"* — is a normal thing to find when you look, and
+walking a roster should not mean a `try` around every row.
+
+| Refused when | Because |
+|---|---|
+| it is mid-turn | A nudge reacts to a session having *stopped*. It is never queued: one arriving mid-sentence reads as an answer to something nobody asked. |
+| it is not your descendant | Same subtree rule as `session_terminate`. You cannot reach a parent, a sibling or a stranger. |
+| it is you | A session prompting itself is a loop with no exit. |
+| the prompt is empty | It would say nothing. |
+
+## It is not `api.agent`
+
+`agent` makes a new one. This talks to one you already have. When you find
+yourself about to spawn a second reader for a subject you already have a reader
+for, this is the call you wanted.