@nac3/forge-cli 1.26.0 → 1.27.0

package/dist/version.d.ts

@@ -2,5 +2,5 @@
  * Yujin Forge CLI version. Kept in sync with package.json by the npm
  * "version" lifecycle (scripts/sync_version.mjs) so the two never drift.
  */
-export declare const VERSION = "1.26.0";
+export declare const VERSION = "1.27.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -2,5 +2,5 @@
  * Yujin Forge CLI version. Kept in sync with package.json by the npm
  * "version" lifecycle (scripts/sync_version.mjs) so the two never drift.
  */
-export const VERSION = '1.26.0';
+export const VERSION = '1.27.0';
 //# sourceMappingURL=version.js.map

package/docs/doctrine/session-orchestration.md

@@ -1,109 +1,109 @@
-# 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?, model? }`
-  -- 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).
-  `model` PINS the child brain as "provider/model" (PND-263). Without
-  it the child inherits the global `brain_config`, so its brain comes
-  out by OMISSION -- which is wrong whenever the brain is part of the
-  point. Measured in the Urazuke A/B experiment: the step-13 audit done
-  by the inherited non-frontier brain wrote FOUR of the nine findings it
-  announced, with a false P0; the same audit over the same commit with a
-  frontier brain wrote SEVENTEEN, all seventeen verified. The step asks
-  for a second opinion, and an inherited brain turns it into a
-  formality. Two rules on the pin, both deliberate: the slash is
-  REQUIRED (Forge never guesses the provider from the model name), and
-  an unknown provider -- or one whose key is not in the vault -- is
-  REFUSED at the door instead of silently falling back to another. A pin
-  also overrides the eco/frontier classifier and the escalation: it is a
-  request, not a preference.
-- `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.
-5. **Brain chosen, not inherited** -- when the brain matters (an AUDIT
-   by another session, a review, a second opinion), pass `model`. An
-   auditor that comes out by omission satisfies the form of the step and
-   loses its point.
-
-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?, model? }`
+  -- 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).
+  `model` PINS the child brain as "provider/model" (PND-263). Without
+  it the child inherits the global `brain_config`, so its brain comes
+  out by OMISSION -- which is wrong whenever the brain is part of the
+  point. Measured in the Urazuke A/B experiment: the step-13 audit done
+  by the inherited non-frontier brain wrote FOUR of the nine findings it
+  announced, with a false P0; the same audit over the same commit with a
+  frontier brain wrote SEVENTEEN, all seventeen verified. The step asks
+  for a second opinion, and an inherited brain turns it into a
+  formality. Two rules on the pin, both deliberate: the slash is
+  REQUIRED (Forge never guesses the provider from the model name), and
+  an unknown provider -- or one whose key is not in the vault -- is
+  REFUSED at the door instead of silently falling back to another. A pin
+  also overrides the eco/frontier classifier and the escalation: it is a
+  request, not a preference.
+- `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.
+5. **Brain chosen, not inherited** -- when the brain matters (an AUDIT
+   by another session, a review, a second opinion), pass `model`. An
+   auditor that comes out by omission satisfies the form of the step and
+   loses its point.
+
+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.