@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/dom.py

@@ -0,0 +1,117 @@
+"""Frozen DOMSnapshot dataclass — mirrors dom.ts:10-17."""
+
+from dataclasses import dataclass, field
+from typing import Optional, Union
+
+
+@dataclass(frozen=True)
+class DOMSnapshot:
+    url: str
+    query: dict[str, list[str]]
+    cookies: dict[str, str]
+    tree: dict
+    raw_html: str
+    timestamp: float
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DOMSnapshot":
+        return cls(
+            url=d.get("url", ""),
+            query=d.get("query", {}),
+            cookies=d.get("cookies", {}),
+            tree=d.get("tree", {}),
+            raw_html=d.get("rawHtml", d.get("raw_html", "")),
+            timestamp=d.get("timestamp", 0.0),
+        )
+
+    def text_content(self) -> str:
+        """Extract all accessible name text from the AX tree for keyword matching.
+
+        Handles the CDP Accessibility.getFullAXTree format where ``name`` is
+        a dict like ``{"type": "computedString", "value": "..."}``.
+        """
+        parts: list[str] = []
+
+        def walk(node: object) -> None:
+            if isinstance(node, dict):
+                name = node.get("name")
+                if isinstance(name, str) and name:
+                    parts.append(name)
+                elif isinstance(name, dict):
+                    val = name.get("value")
+                    if isinstance(val, str) and val:
+                        parts.append(val)
+                for v in node.values():
+                    walk(v)
+            elif isinstance(node, list):
+                for item in node:
+                    walk(item)
+
+        walk(self.tree)
+        return " ".join(parts)
+
+    def structural_hash(self) -> str:
+        """Hash the DOM tree structure, ignoring text/value content."""
+        import hashlib, json
+
+        def strip_text(obj):
+            if isinstance(obj, dict):
+                return {k: strip_text(v) for k, v in obj.items() if k not in ('name', 'value', 'description')}
+            if isinstance(obj, list):
+                return [strip_text(i) for i in obj]
+            return obj
+
+        return hashlib.sha256(json.dumps(strip_text(self.tree), sort_keys=True).encode()).hexdigest()
+
+
+# ── Hybrid Semantic+Visual types ─────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class HybridNode:
+    """A single interactive element with semantic + visual properties."""
+    id: str
+    role: str
+    name: str
+    value: Optional[str] = None
+    disabled: Optional[bool] = None
+    checked: Optional[Union[bool, str]] = None  # True, False, or 'mixed'
+    expanded: Optional[bool] = None
+    visuals: dict = field(default_factory=dict)  # color, bgColor, border, fontWeight, opacity
+    bounds: dict = field(default_factory=dict)    # x, y, w, h
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "HybridNode":
+        return cls(
+            id=d.get("id", ""),
+            role=d.get("role", ""),
+            name=d.get("name", ""),
+            value=d.get("value"),
+            disabled=d.get("disabled"),
+            checked=d.get("checked"),
+            expanded=d.get("expanded"),
+            visuals=d.get("visuals", {}),
+            bounds=d.get("bounds", {}),
+        )
+
+
+@dataclass(frozen=True)
+class HybridDiff:
+    """Diff between two hybrid snapshots — only what changed."""
+    url: dict  # { before: str, after: str }
+    timestamp: float
+    added: list  # list of HybridNode dicts
+    removed: list  # list of { id, role, name }
+    changed: list  # list of { id, role, name, changes }
+    unchanged_count: int = 0
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "HybridDiff":
+        return cls(
+            url=d.get("url", {}),
+            timestamp=d.get("timestamp", 0.0),
+            added=[HybridNode.from_dict(n) for n in d.get("added", [])],
+            removed=d.get("removed", []),
+            changed=d.get("changed", []),
+            unchanged_count=d.get("unchangedCount", d.get("unchanged_count", 0)),
+        )

package/python/xactor/man/add_card.md

@@ -0,0 +1,89 @@
+# api.add_card(prompt, title=None, backlog=False) -> dict
+<!-- also: add_todo, todo_card, board_card, card, kanban, work-board -->
+<!-- group: Talking to the user -->
+
+Leave a card on the user's board. **Only when the user asks for one.** Not gated.
+
+The board is the user's list, not yours. Finding something on the way past — a
+rename left half-finished, a test that will break on the next refactor, a fix
+that wants its own branch — is not a request for a card: say so in your reply
+and leave it there. When they do ask ("put that on the board", "make a card for
+it"), the card lands in Todo and waits until they have time for it.
+
+## What lands
+
+An ordinary card, sitting with the ones the user wrote themselves. They can drag
+it into Doing and it spawns an agent on it exactly like any other; deleting it
+is how they say no. There is no accept step and nothing is blocked on them.
+
+The one difference is that it is **marked with your node** — a purple edge and a
+`from B8` line — until they act on it. Clicking it, dragging it, editing it or
+starting it clears the mark. So the colour means "you have not seen this yet",
+not "an agent thought of it", and a board they come back to after a day shows at
+a glance what is new.
+
+## Options
+
+- **`prompt`** — what should be done. This is sent **verbatim** to the agent if
+  the card is ever started, so write it as an instruction, not as an
+  observation: *"Rename the `daemon` field in .widgex/bulletin.json to
+  `harness`"*, not *"the bulletin still says daemon"*. Up to 8000 characters.
+- **`title`** — what the card is called on the board. Omit it and the first
+  clause of the prompt is used, which is usually the right answer.
+
+It goes in the sprint in play on the board, as a card the user writes does. Pass `backlog=True` when they said it is for later — "another sprint", "the backlog" — and it stays out of every sprint.
+
+Returns `{ id, title, lane, authored_by, sprint, room }`, where `sprint` says where it went and `room` is how many more cards the board will take from agents before the cap below refuses. In a loop, stop at `room == 0` rather than waiting for the error; a call that raises added nothing, so every call that returned is a card that landed.
+
+## This is not api.todo_write
+
+The two are easy to confuse and are not related.
+
+| | `api.todo_write` | `api.add_card` |
+|---|---|---|
+| whose list | yours | the user's |
+| what it is about | what you are doing now | what somebody should do |
+| lifetime | replaced whole every call, gone on reload | durable, per workspace |
+| where | the chat | the Work board |
+
+`todo_write` is progress reporting. This is leaving work behind. Writing a card
+never removes an earlier one — see [`todo_write`](todo_write.md) if what you
+want is to show how far along you are.
+
+## Judgement
+
+Not gated, so nothing stops you. That makes the restraint yours:
+
+- **No card the user did not ask for.** A general go-ahead from earlier in the
+  conversation does not cover something new, and neither does your own sense
+  that they would want it. A card is a claim on somebody's attention.
+- **Work you were actually asked to do goes in your diff**, not on a card. A
+  card that says "finish the thing I was told to finish" is a way of not
+  finishing it.
+- **A card is not a bug report.** If WidgeX itself got in your way, that is
+  [`report_bug`](report_bug.md) — it goes somewhere the WidgeX team reads,
+  where a card goes to whoever is using it.
+- **A card is not a question.** If you need an answer to carry on, ask —
+  [`ask_user`](ask_user.md) blocks and a card does not.
+
+There is a cap: twenty agent-written cards the user has not looked at yet. Hit
+it and the call fails saying so. Acknowledged cards do not count, so a user who
+is keeping up never meets it. The cap has no override and counts a card the user
+asked for like any other: past it, put the work in your reply and offer to add the
+cards once they have been through the board.
+
+## Where it lands
+
+The board is workspace-scoped, so the card goes to the board of the window your
+session is running in. For a session the board itself started, that is the board
+it came from. A session in a separately-opened worktree window writes to that
+window's board.
+
+```python
+await api.add_card(
+    "Rename the `daemon` field in .widgex/bulletin.json to `harness`. "
+    "The bulletin is the last place still using the old word; the surface "
+    "enum is a Postgres CHECK constraint and needs a backend deploy first.",
+    title="Finish the daemon→harness rename",
+)
+```

package/python/xactor/man/agent-vs-fork.md

@@ -0,0 +1,108 @@
+# agent vs fork
+
+<!-- group: Concepts -->
+
+Two ways to run work elsewhere. There used to be four, and three of them turned
+out to be one call with different arguments.
+
+## What collapsed
+
+`delegate`, `session_extend` and `session_branch` are gone. They differed on two
+questions, and those are now `api.agent`'s arguments:
+
+|  | `isolate=False` | `isolate=True` |
+|---|---|---|
+| **`wait=True`** | was `delegate` | was `session_branch` + `session_join` |
+| **`wait=False`** | was `session_extend` | was `session_branch` |
+
+The one thing `session_extend` had that a bare `wait=False` does not is the
+guarantee that the child opens with a compacted summary of your session rather
+than a pointer to it. That survived as `extend=True` — so the exact replacement
+for the old call is `agent(prompt, extend=True, wait=False)`.
+
+If you knew the old names, you already know this call. If you did not, you never
+have to learn which of three bits of bookkeeping you wanted.
+
+## What did not
+
+`session_fork` stays separate, because it is a different intent rather than a
+different setting:
+
+| | `api.agent` | `session_fork` |
+|---|---|---|
+| Repo | your directory, or a worktree of the same repo | **a whole clone** |
+| Context | fresh, from `prompt` + `summary` | **a copy of this conversation** |
+| Work comes back | as text, or as a merge the user approves | **never** |
+| Costs | a context; a worktree if isolated | real disk, real time, and your whole transcript |
+
+Fork is for work that must not come back — the approach you rejected, tried
+somewhere it cannot hurt anything. Everything you might actually want returned is
+`agent`.
+
+## Choosing
+
+**You want an answer.** `api.agent(prompt, model=...)`. Blocks, hands back
+`{text, model, turns, tokens}`, no session, no node, no permission prompt. This
+is the default and it is underused.
+
+**You want work done while you work, in your tree.**
+`api.agent(..., wait=False)`. Returns immediately; the child edits the same files
+you are editing.
+
+**You want work done alongside yours, then merged.**
+`api.agent(..., wait=False, isolate=True)`. Its own worktree and branch, so
+neither of you disturbs the other, and the user can merge it afterwards. This is
+the one for running several at once.
+
+**The work must never come back.** `api.session_fork`.
+
+## The costs you are trading
+
+- **Waiting costs your turn.** An hour of work in a waited agent is an hour with
+  nothing else happening.
+- **Not waiting costs a whole new context**, and — shared — a second agent
+  editing your files concurrently.
+- **Isolating costs a working copy.** A worktree is cheap, it shares the object
+  store, but your uncommitted work is copied in and committed there as a seed, so
+  those edits then exist twice.
+- **Forking costs a clone and your transcript.** Real disk, real time, and a
+  briefing method that also hands over everything irrelevant.
+
+## Claude's own subagents
+
+Untouched, and not this. The SDK's `Agent`/`Task` tool chooses between three
+Claude tiers, runs inside the model's own machinery, and is invisible to the
+user. `api.agent` reaches every model the user has configured and shows up in
+their session list while it runs.
+
+The rule is ownership: if you started it with `api.`, they can see it.
+
+## Getting it wrong
+
+**Waiting, then using only the text, when you could have delegated.** That is
+what `wait=True` already is. It is the cheap path, not a lesser one.
+
+**Not waiting, then joining immediately.** That is `wait=True` with a session, a
+node and a permission prompt attached.
+
+**Two shared agents at once.** Both edit your directory, at the same time as you
+and each other. `isolate=True` is what keeps them apart.
+
+**Two isolated agents on the same files.** Both merge cleanly and the second one
+silently wins every shared file — git sees no conflict, because it treats the
+first one's work as ordinary history. The wizard warns; split by file where you
+can.
+
+**Expecting an isolated agent to land itself.** The user merges it. "Ready to
+merge" is true; "I've merged it" is not.
+
+**Forking for parallelism.** Two clones of a large tree cost real disk and real
+time. `isolate=True` shares the object store.
+
+**Forgetting `model` on a waited, shared agent.** It is required there and
+nowhere else: picking it is the point, and inheriting yours would put every
+throwaway search on your most expensive model.
+
+## See also
+
+`agent`, `children`, `session_fork`, `session_join`, `sessions`, `xylon`

package/python/xactor/man/agent.md

@@ -0,0 +1,333 @@
+# api.agent(prompt, model=None, isolate=False, wait=True, summary=None, aux_context=None, timeout_seconds=None, extend=False, machine=None, token_budget=None, must=None, raise_=False, title=None, task=None, harness=None) -> dict
+
+<!-- group: Sessions -->
+
+Hand work to another agent. Gated only when it outlives the call.
+
+This replaced `delegate`, `session_extend` and `session_branch`, which differed
+on a few questions and nothing else a caller should have had to think about.
+Those questions are now arguments.
+
+## The two questions
+
+**Do you wait?** `wait=True` (default) runs it inside your turn and hands back
+what it found. `wait=False` starts it and returns at once — collect it later with
+`session_join`, or never.
+
+**Does it get its own files?** `isolate=False` (default) means it works in your
+directory, on your files, at the same time as you. `isolate=True` gives it a
+worktree and a branch of its own, cut from what you can see right now.
+
+|  | `isolate=False` | `isolate=True` |
+|---|---|---|
+| **`wait=True`** | the cheap one — your shell, no session, no node, no prompt | start it, block on it, merge later |
+| **`wait=False`** | a second agent in your tree, working while you work | the one for running several at once |
+
+## And one guarantee: `extend`
+
+By default a child starts cold. It gets your `prompt` and nothing else, and if
+it has a node it is told it *may* read your transcript with
+`xylon_read_messages('..')` — a fallback, not a plan, because transcripts are
+large.
+
+`extend=True` replaces that with a guarantee: **the child works in your working
+tree, and it opens with a compacted summary of this session.** It is the old
+`session_extend`, and it never hands over a bare pointer.
+
+`extend=True` with `isolate=True` is refused — they contradict. Extend keeps
+your working tree; isolate is the one that takes it away.
+
+## The third thing: `raise_`
+
+The two questions above both describe something you *spawn* — it hangs under
+you, and it is yours to read back. `raise_=True` does not spawn anything. It
+opens an **Issue**, through the same mechanism the `+` button drives: an Issue
+record, a titled branch (`widgex/<title>`), and a working copy bound to it, with
+a first session standing in it.
+
+The difference from `isolate=True` is not mechanical — both end up on a branch
+in a worktree — it is about whose work it is. A branch session is a piece of
+*your* work you handed out and will merge back. An Issue is a separate piece of
+work that happens to have started here: it stands beside yours in the Issue
+list, the user lands and retires it with the gestures they already have, and it
+outlives this call, this session and this window.
+
+So: `isolate=True` when you are going to read it back yourself. `raise_=True`
+when you are handing the user a thing, not an answer.
+
+It always asks permission, including with `wait=True` — no combination of
+arguments makes an Issue transient. It is refused with `isolate` or `extend`,
+which each promise something it contradicts. It inherits your model unless you
+name one, like any session.
+
+Spelled with the trailing underscore because `raise` is a Python keyword, so
+`api.agent(prompt, raise=True)` is a SyntaxError rather than an error message.
+
+```python
+child = await api.agent(
+    "Fix the two Windows-only failures in the extension suite. Details in card-3.",
+    raise_=True, wait=False,
+    title="Fix the Windows test failures",
+    summary="I'm mid-way through the document hub; this is unrelated and wants its own branch.",
+)
+return f"Raised {child['issueId']} on {child['branch']}, working in {child['repoDir']}."
+```
+
+**Check `stale_base`.** An Issue is cut from the commit the user's open folder
+is sitting on, and nothing here fetches on a schedule — so if nobody has pulled
+recently, the branch starts from work that is days old and the pull request is
+where it surfaces. When the `+` button hits this it asks and offers to pull
+first. You get no dialog, because moving somebody's checkout while they are
+working in it is not an agent's call to make.
+
+So the Issue is raised from what is there and `stale_base` carries the sentence:
+`'main is 7 commits behind origin/main.'`, or `None` when there was nothing to
+say. Pass it on — the user is the one who can decide whether to rebase it.
+
+```python
+child = await api.agent("…", raise_=True, wait=False, title="Fix the flaky test")
+if child['stale_base']:
+    return f"Raised {child['issueId']} on {child['branch']}. Note: {child['stale_base']}"
+```
+
+## Options
+
+- **`prompt`** — the whole task. It sees nothing of this conversation, so write
+  it as a brief for a stranger: the files, the goal, and the shape of the answer.
+- **`model`** — e.g. `'claude-haiku-4-5'`, or `'provider/model'` when two
+  providers offer the same id. **Required when `wait=True` and
+  `isolate=False`**; inherited otherwise. An unknown id is refused with the list
+  of models available, and nothing is created.
+- **`must`** — what the child has to be able to demonstrate, in plain words:
+  `must=["opens from the row", "survives a restart"]`.
+
+  **The order is the whole point.** An agent that writes its own claims after
+  implementing writes the ones it met — not dishonestly, it is describing what
+  it built, and what it built is what it can see. The result is a demo that
+  cannot fail, because the target was drawn around the arrow after it landed.
+  Dispatch is the only moment these are about the *task* rather than about the
+  implementation.
+
+  The child is told them, and reports which it met when it calls
+  `api.request_review`. It may add claims of its own; it cannot drop one of
+  these. An obligation named in neither `covers` nor `missing` is reported unmet
+  anyway, so there is nothing to gain by omitting one — and an unmet obligation
+  sorts the review row *up*, because the request that admits it needs attention
+  is the one most worth attention.
+
+  Needs a session to report against, so it is refused with `wait=True,
+  isolate=False`: that path answers inside your turn and you read the result
+  directly.
+
+- **`raise_`** — open an Issue instead of spawning a child. See above. Always
+  asks; refused with `isolate` or `extend`.
+- **`title`** — what the Issue is called, and therefore what its branch is
+  called. `raise_=True` only. Defaults to the first line of the prompt, which is
+  usually worth overriding: a branch name is read far more often than written.
+- **`isolate`** — its own worktree and branch.
+- **`wait`** — block and return its answer.
+- **`extend`** — guarantee it your working tree and a compacted summary of this
+  session. Incompatible with `isolate`.
+- **`summary`** — a paragraph telling a non-waited agent what you have been doing
+  and why it was spawned. Costs a fraction of a transcript, so prefer it whenever
+  the agent needs context. Ignored when `wait=True` *unless* `extend=True`, which
+  inlines it into the brief instead.
+- **`aux_context`** — path to a `.md` or `.txt` file, read **now** and inlined
+  into its opening prompt. Capped at 100,000 characters.
+- **`timeout_seconds`** — `wait=True` only. Defaults to 300.
+- **`machine`** — a machine name from `.widgex/harnesses/`, or a path to a `.json`
+  file. Overlays a harness state machine on the child, which then drives it from
+  state to state instead of running one turn and stopping. Needs a session, so it
+  is refused on the cheap `wait=True, isolate=False` path. An unresolvable or
+  unparseable machine is refused with the parse errors, and **no child is
+  created**.
+- **`token_budget`** — lifetime ceiling in tokens for a `machine` overlay.
+  Spending it stops the child until a person restarts it. Omit it for the
+  `widgex.harness.tokenCap` setting (400,000 by default). The child also stops
+  after 50 cycles, and its machine must be able to reach a terminal state.
+  Tokens are counted price-weighted (cache writes ×1.25, cache reads ×0.1), and
+  every turn carries the whole system prompt: **one short first turn has
+  measured about 60,000**, so a budget under ~100,000 can stop the child before
+  it has done anything. When that happens `session_join` says so —
+  `stopped_by: 'harness-budget'` — rather than reporting a crash.
+- **`task`** — add this agent to an existing task (a worktree with its own
+  branch) instead of creating one. The id comes from `api.tasks()`. Cannot be
+  combined with `raise_`, `isolate` or `extend`. The Coordinator must use this
+  or `raise_` for any agent that outlives its turn. Always asks permission,
+  including with `wait=True`: it creates a session that outlives the call
+  regardless of `wait`, which only decides whether you block on its first turn.
+- **`harness`** — which harness drives the agent — the same thing `machine`
+  names, under the name the rest of WidgeX uses. Give one or the other, not
+  both.
+
+A non-extended agent given no `summary` is told it may read your transcript with
+`xylon_read_messages('..')` if it needs the background. That is a fallback, not a
+plan: transcripts are large.
+
+## Where an extended child hangs, and what it opens with
+
+One rule decides both:
+
+> **An extended child hangs off the node whose summary it was given.**
+
+**With `summary`.** It is banked on your node as a real checkpoint, you carry on
+in a fresh `A<n>`, and the child hangs off the node that was sealed. A supplied
+summary is treated as being as good as a checkpoint, so nothing is re-derived and
+no compaction happens. Because it becomes your node's checkpoint, write it about
+*the work* — the child's task belongs in `prompt`.
+
+**Without `summary`.** Nothing is written to the tree. The child inherits the
+nearest checkpoint above you — after a compaction, the node that was sealed then
+— and hangs off *that* node, which makes it your sibling rather than your
+descendant. If much has happened since, it also gets a budgeted account of it. If
+you have never compacted there is no checkpoint to inherit, so the child hangs
+off you and is briefed from the transcript instead.
+
+`checkpoint` in the return names the node it opened from, either way.
+
+Nothing asks you for a fresh summary here, and nothing can: this call runs inside
+a tool call, and every summary-producing path in the IDE waits on a result that
+your own tool call is blocking. That is why the guarantee is built from a
+compaction baseline and the turns since it, both of which are already in memory.
+
+## Returns
+
+```python
+# wait=True, no session (the cheap path)
+{"text": str, "model": str, "turns": int, "tokens": {...}}
+# wait=True, with a session — the joined answer, plus what it is standing in
+{..., "branch": str | None, "baseSha": str | None,
+ "issueId": str | None, "repoDir": str | None}
+# wait=False
+{"sessionId": str, "node": str, "branch": str | None, "baseSha": str | None,
+ "issueId": str | None, "repoDir": str | None,
+ "model": str | None, "machine": str | None, "machineState": str | None,
+ "checkpoint": str | None}
+```
+
+`issueId` and `repoDir` are filled only by `raise_=True`, and they are the two
+facts you cannot recover afterwards from a session id alone: which Issue to
+land, and which directory it is being done in.
+
+## Why `model` is required for the cheap one
+
+The whole point of running a search on a small model is that you chose to. A call
+that silently inherited yours would put every throwaway grep on the most
+expensive thing you have, which is the default that made model guidelines
+necessary. Where the agent is a session it inherits, because a session is a
+long-lived thing you can see and change the model of afterwards.
+
+## Everything you start is visible
+
+A waited agent appears under you in the session list while it runs, and
+disappears when it returns — it has no node and no transcript, so there is
+nothing to come back to. A session child stays.
+
+This is the difference from Claude's own `Agent`/`Task` tool, which is not ours
+and is not shown. If you started it with `api.`, the user can see it.
+
+`api.children()` is the same information, for you.
+
+## Isolated work does not land itself
+
+An isolated agent's changes reach your branch only when the **user** merges
+them. You cannot land them and neither can it. Report accurately: "it's ready to
+merge" is true; "I've merged it" is not.
+
+Your uncommitted work is copied into its worktree and committed there as a seed
+commit — `WidgeX: parent's work in progress at the branch point` — so it starts
+from the tree you are looking at. Your copy stays here, uncommitted.
+
+Two consequences: those edits now exist twice, and drift if you keep editing
+yours; and the seed commit travels back when its work lands, so the merge
+reconciles two commits with the same content.
+
+## Examples
+
+A search you do not want in your context:
+
+```python
+r = await api.agent(
+    "Find every call site of retryBudget in src/ and report file:line.",
+    model="claude-haiku-4-5",
+)
+return r["text"]
+```
+
+Two jobs at once, each landing separately:
+
+```python
+a = await api.agent("Add the fetch-on-land path in GitUtils, with tests.",
+                    isolate=True, wait=False,
+                    summary="We're splitting the landing work; you own the git layer.")
+b = await api.agent("Add the queue row in surfaces.ts, with tests.",
+                    isolate=True, wait=False,
+                    summary="We're splitting the landing work; you own the panel layer.")
+return f"Two branches going: {a['branch']} and {b['branch']}."
+```
+
+A long job in your own tree, checked on later:
+
+```python
+child = await api.agent(
+    "Port test/auth/*.test.mjs to the new fixture API. Report what broke.",
+    wait=False,
+    summary="I'm mid-refactor of src/auth; the fixture API changed shape today.",
+)
+return f"Started {child['sessionId']} on the auth tests."
+```
+
+Continuing your own work in a second session, which is what `extend` is for:
+
+```python
+child = await api.agent(
+    "Finish porting the remaining fixtures in test/auth/, then run the suite.",
+    extend=True, wait=False,
+)
+return f"Handed off to {child['sessionId']}, opened from {child['checkpoint']}."
+```
+
+A child that drives itself through a state machine instead of stopping:
+
+```python
+return await api.agent(
+    "Keep the release notes current as commits land on main.",
+    wait=False, machine="release-notes", token_budget=200_000,
+)
+```
+
+## Getting it wrong
+
+**Waiting when you did not need to.** `wait=True` holds your turn. An hour of
+work in a waited agent is an hour with nothing else happening.
+
+**Not waiting when you only wanted an answer.** If you are going to
+`session_join` immediately and use nothing but `lastMessage`, `wait=True` does
+the same job without a session, a node or a permission prompt.
+
+**Two shared-tree agents at once.** Both edit your directory, at the same time as
+you and as each other. `isolate=True` is the one that keeps them apart.
+
+**Two isolated agents on the same files.** Allowed, and both merge cleanly — git
+sees no conflict, because whichever lands second treats the first one's work as
+ordinary history and simply wins every file they share. The merge wizard warns
+about the overlap. Split by file where you can.
+
+**Expecting a subagent to fan out.** It cannot call `agent`, `fork`, `join` or
+`terminate`. Work that needs sub-work needs a session — spawn it yourself.
+
+**Speculative work that must never come back.** Isolated work *can* come back;
+that is the point. `session_fork` is the one that cannot.
+
+**Writing `extend`'s `summary` as a brief for the child.** It is stored as your
+node's checkpoint and ranked against every other checkpoint in the tree from then
+on, so "port the auth tests" describes the wrong session forever. Say what *you*
+did; put the instruction in `prompt`.
+
+**Expecting `..` to be your live node after an unbriefed `extend`.** The child
+hangs off a checkpoint above you, so `..` is that checkpoint, not where you are
+now. `checkpoint` in the return says which.
+
+## See also
+
+`children`, `session_join`, `session_fork`, `sessions`, `xylon`