@nac3/forge-cli 1.24.1 → 1.25.0

package/docs/doctrine/session-orchestration.md

@@ -1,86 +1,91 @@
-# Doctrine: session orchestration (yujin.session.*)
-
-When it is optimal, you may launch other `yf chat` instances as
-HEADLESS AGENT sub-sessions to do orthogonal, well-scoped work in
-parallel with this conversation, and collect their results over the
-coordination bridge. This is the `yujin.session.*` verb family.
-
-This doctrine is about WHEN to spawn and how to keep it safe and
-cheap. It is distinct from `agent-orchestrator` (product-side agents
-the generated software dispatches on the user's machine).
-
-## Off by default
-
-The whole capability is gated by `multiagent.enabled` in the limits
-config (Ajustes > Limites), DEFAULT OFF. While off, the
-`yujin.session.*` verbs are hidden from the manifest, this doctrine is
-not injected, the system prompt tells you it is OFF, and the handlers
-refuse. So you only see + use these verbs when the user has explicitly
-turned multi-agent on. If the user asks for parallel sub-sessions while
-it is off, tell them to enable it in Ajustes > Limites.
-
-## The verbs
-
-- `yujin.session.spawn { task, project_root?, budget_tokens?, label? }`
-  -- launch a sub-session for one self-contained task. Returns a
-  handle immediately (NON-blocking). The user approves each spawn
-  (it spends BYOK tokens autonomously).
-- `yujin.session.collect { handle?, wait_ms? }` -- read the results
-  sub-sessions have published. `wait_ms` blocks up to that long for
-  at least one result; default 0 = return whatever has arrived.
-- `yujin.session.list` -- what you have spawned + whether each is
-  still alive.
-- `yujin.session.stop { handle }` -- terminate one.
-
-## Spawn ONLY when it pays off
-
-A sub-session boots a whole headless server and spends tokens, so the
-overhead must be justified. Spawn when ALL of these hold:
-
-1. **Orthogonal** -- the subtask is independent of the work you are
-   doing right now; it does not need the live conversation context.
-   (The child gets ONLY the `task` string you write -- be specific.)
-2. **Parallelizable** -- it can run while you keep working, and you
-   genuinely benefit from not blocking on it (e.g. a wide read /
-   research / analysis sweep over a different subsystem).
-3. **No write collision** -- it will not edit the same files you are
-   editing. If both might write, scope them to different paths or do
-   it yourself.
-4. **Fits a budget** -- set `budget_tokens` to bound the spend.
-
-Do NOT spawn for:
-
-- Trivial tasks (a single read, a one-line answer) -- the overhead
-  costs more than doing it inline.
-- Anything that needs the user's live judgement or the chat history.
-- Work you could do with one of your own verbs in this turn.
-
-Typical good uses: "map how subsystem X wires together and report the
-key files + entry points", "search the whole repo for every place
-pattern Y appears and summarise", "read these 8 docs and extract the
-constraints". Launch one per independent angle, then `collect`.
-
-## The child's scope (enforced, not advisory)
-
-A sub-session runs with a RESTRICTED verb scope (enforced in
-`nac3_invoke` via `YF_AGENT_MODE`):
-
-- CAN: read / search / write files in its project root, run SAFE
-  shell, query the graph / pendings / reader.
-- CANNOT: `git push` / `git commit`, destructive actions, `fs.move`,
-  re-anchor the project, mutate the workflow / pending / keys, run
-  lifecycle servers, or spawn its OWN sub-sessions (no grandchildren).
-
-So the child is a safe builder/analyst. Anything outward or
-irreversible stays with YOU, the parent, where the user can approve
-it. Have the child RETURN its deliverable; you surface it (pizarron,
-etc.) and you do the push/commit.
-
-## Lifecycle
-
-Sub-sessions are one-shot: a child runs its task to completion (a
-`[SESSION_DONE]` marker), publishes its result, and exits. The full
-result is written to disk; the bridge signal carries a summary + the
-path. Always `collect` what you spawn -- do not leave results
-unread. If a child is no longer useful or is burning budget, `stop`
-it.
+# Doctrine: session orchestration (yujin.session.*)
+
+When it is optimal, you may launch other `yf chat` instances as
+HEADLESS AGENT sub-sessions to do orthogonal, well-scoped work in
+parallel with this conversation, and collect their results over the
+coordination bridge. This is the `yujin.session.*` verb family.
+
+This doctrine is about WHEN to spawn and how to keep it safe and
+cheap. It is distinct from `agent-orchestrator` (product-side agents
+the generated software dispatches on the user's machine).
+
+## Off by default
+
+The whole capability is gated by `multiagent.enabled` in the limits
+config (Ajustes > Limites), DEFAULT OFF. While off, the
+`yujin.session.*` verbs are hidden from the manifest, this doctrine is
+not injected, the system prompt tells you it is OFF, and the handlers
+refuse. So you only see + use these verbs when the user has explicitly
+turned multi-agent on. If the user asks for parallel sub-sessions while
+it is off, tell them to enable it in Ajustes > Limites.
+
+## The verbs
+
+- `yujin.session.spawn { task, project_root?, budget_tokens?, label? }`
+  -- launch a sub-session for one self-contained task. Returns a
+  handle immediately (NON-blocking). The user approves each spawn
+  (it spends BYOK tokens autonomously).
+- `yujin.session.collect { handle?, wait_ms? }` -- read the results
+  sub-sessions have published. `wait_ms` blocks up to that long for
+  at least one result; default 0 = return whatever has arrived.
+- `yujin.session.list` -- what you have spawned, with TWO facts that are
+  not the same one (PND-256): `alive` is whether the process exists
+  (asked of the OS), and `registered` is whether the child already
+  published itself on the coordination bridge. A child can be alive and
+  not yet registered (booting), and a dead child can linger in the
+  roster. Reading one as the other costs either a needless relaunch or
+  an endless wait.
+- `yujin.session.stop { handle }` -- terminate one.
+
+## Spawn ONLY when it pays off
+
+A sub-session boots a whole headless server and spends tokens, so the
+overhead must be justified. Spawn when ALL of these hold:
+
+1. **Orthogonal** -- the subtask is independent of the work you are
+   doing right now; it does not need the live conversation context.
+   (The child gets ONLY the `task` string you write -- be specific.)
+2. **Parallelizable** -- it can run while you keep working, and you
+   genuinely benefit from not blocking on it (e.g. a wide read /
+   research / analysis sweep over a different subsystem).
+3. **No write collision** -- it will not edit the same files you are
+   editing. If both might write, scope them to different paths or do
+   it yourself.
+4. **Fits a budget** -- set `budget_tokens` to bound the spend.
+
+Do NOT spawn for:
+
+- Trivial tasks (a single read, a one-line answer) -- the overhead
+  costs more than doing it inline.
+- Anything that needs the user's live judgement or the chat history.
+- Work you could do with one of your own verbs in this turn.
+
+Typical good uses: "map how subsystem X wires together and report the
+key files + entry points", "search the whole repo for every place
+pattern Y appears and summarise", "read these 8 docs and extract the
+constraints". Launch one per independent angle, then `collect`.
+
+## The child's scope (enforced, not advisory)
+
+A sub-session runs with a RESTRICTED verb scope (enforced in
+`nac3_invoke` via `YF_AGENT_MODE`):
+
+- CAN: read / search / write files in its project root, run SAFE
+  shell, query the graph / pendings / reader.
+- CANNOT: `git push` / `git commit`, destructive actions, `fs.move`,
+  re-anchor the project, mutate the workflow / pending / keys, run
+  lifecycle servers, or spawn its OWN sub-sessions (no grandchildren).
+
+So the child is a safe builder/analyst. Anything outward or
+irreversible stays with YOU, the parent, where the user can approve
+it. Have the child RETURN its deliverable; you surface it (pizarron,
+etc.) and you do the push/commit.
+
+## Lifecycle
+
+Sub-sessions are one-shot: a child runs its task to completion (a
+`[SESSION_DONE]` marker), publishes its result, and exits. The full
+result is written to disk; the bridge signal carries a summary + the
+path. Always `collect` what you spawn -- do not leave results
+unread. If a child is no longer useful or is burning budget, `stop`
+it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nac3/forge-cli",
-  "version": "1.24.1",
+  "version": "1.25.0",
   "description": "Yujin Forge -- voice-first NAC-3 React development framework. CLI + chat panel + spec ingest + 10-format document reader + voice loop.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Pablo Kuschnirof <pablo@rpaforce.com>",