@nac3/forge-cli 1.25.0 → 1.27.0

package/dist/core/machine_files.js

@@ -0,0 +1,97 @@
+/**
+ * LOS ARCHIVOS DE LA MAQUINA, Y LA UNICA PUERTA POR DONDE LA BATERIA NO
+ * ENTRA.
+ *
+ * Esto no es una abstraccion por prolijidad: es una familia de defectos
+ * MEDIDA tres veces en el mismo archivo de configuracion del dueno.
+ *
+ *   1. 2026-10-19 -- la bateria del publish dejo entradas "test approval
+ *      gate" y llaves de prueba en el nac3_log.jsonl del dueno. Se
+ *      "arreglo" resolviendo el path en el momento de la llamada en vez de
+ *      al importar el modulo (src/nac3/dispatch_log.ts).
+ *   2. 2026-11-03 -- la bateria llevaba meses escribiendo en el
+ *      usage.jsonl del dueno: 8.764 de 8.821 eventos de la ventana de 30
+ *      dias, el 99,4%, todos valuados en cero dolares. Y el archivo es la
+ *      unica fuente del reporte de costos. Se le puso una guarda... que no
+ *      alcanzo: la bateria completa siguio dejando cuatro. La causa real es
+ *      una CARRERA, no un permiso (G-12 en docs/GOTCHAS.md).
+ *   3. 2026-11-03, mas tarde, midiendo la pregunta "escribe en algun otro
+ *      archivo mio?" con el arbol de configuracion fotografiado antes y
+ *      despues de la bateria completa: SI, en dos mas --
+ *      `cache/reader_sessions.json` y, todavia, `nac3_log.jsonl`. El de
+ *      reader fue el peor: el archivo QUEDO MAS CHICO que antes de correr,
+ *      porque el almacen tiene tope y las sesiones de prueba desalojaron
+ *      las del dueno. No fue contaminacion: fue perdida de datos.
+ *
+ * La forma general del defecto, que es la que esta funcion cierra:
+ *
+ *     el permiso se evalua en un instante y el PATH se resuelve en otro.
+ *
+ * Mientras sean dos lecturas del entorno en dos momentos distintos, el
+ * `void escribir(...)` que nadie espera va a despertar despues del
+ * `afterEach` que borro YF_CONFIG_DIR y va a aterrizar en la carpeta de la
+ * maquina. Por eso la puerta devuelve el DESTINO COMPLETO resuelto, de una
+ * sola vez: quien la usa no vuelve a mirar el entorno en esa llamada.
+ *
+ * Y fail-closed adentro de la bateria: sin YF_CONFIG_DIR, o con uno que
+ * apunta a la carpeta de la maquina, se NIEGA. El peor caso pasa a ser que
+ * un test pierda un recibo, no que la unica medicion honesta de costo del
+ * experimento quede contaminada -- o que al dueno le desaparezcan sus
+ * sesiones del lector.
+ *
+ * Lo que esta funcion NO hace, a proposito: no mueve YF_CONFIG_DIR para
+ * toda la bateria. Ese es un override ANCHO y este repositorio ya tiene la
+ * cicatriz de uno (src/chat/instance_lock.ts: "un override angosto es el
+ * arreglo; uno ancho era el bug"). Hay tests que necesitan la config real
+ * para leer. Lo que ningun test necesita es ESCRIBIR en la del dueno.
+ *
+ * ASCII-only.
+ */
+import os from 'node:os';
+import path from 'node:path';
+/** La carpeta de configuracion de la MAQUINA: la del dueno, la que ningun
+ *  test puede tocar. Se calcula aparte del configDir() de cada modulo a
+ *  proposito -- hace falta poder comparar el destino CONTRA ella. */
+export function machineConfigDir(env = process.env) {
+    const home = env['USERPROFILE'] || env['HOME'] || os.homedir();
+    return path.join(home, '.yujin-forge');
+}
+export function sameDir(a, b) {
+    const n = (x) => path.resolve(x).replace(/[\\/]+$/, '').toLowerCase();
+    return n(a) === n(b);
+}
+/** Estamos adentro de la bateria? Vitest lo declara en el entorno. */
+export function inBattery(env = process.env) {
+    return env['VITEST'] === 'true' || env['VITEST'] === '1';
+}
+/**
+ * EL DESTINO DE UN ARCHIVO DE ESTADO, DECIDIDO DE UNA SOLA VEZ Y SIN
+ * AWAITS EN EL MEDIO.
+ *
+ * `rel` es la ruta relativa dentro de la carpeta de configuracion
+ * ('usage.jsonl', 'nac3_log.jsonl', 'cache/reader_sessions.json'). El
+ * llamador escribe en `file` y crea `dir` -- y no vuelve a leer el entorno.
+ */
+export function machineFileDestination(rel, env = process.env) {
+    const override = env['YF_CONFIG_DIR'] || env['YUJIN_FORGE_HOME'];
+    const tiene = typeof override === 'string' && override.trim() !== '';
+    const base = tiene ? override.trim() : machineConfigDir(env);
+    if (inBattery(env)) {
+        if (!tiene) {
+            return { allowed: false, why: 'bateria sin YF_CONFIG_DIR: ' + rel + ' iria al archivo del dueno' };
+        }
+        if (sameDir(base, machineConfigDir(env))) {
+            return {
+                allowed: false,
+                why: 'bateria con YF_CONFIG_DIR apuntando a la carpeta de la maquina (' + base + ')',
+            };
+        }
+    }
+    const file = path.join(base, ...rel.split('/'));
+    return { allowed: true, dir: path.dirname(file), file };
+}
+/** Atajo para quien solo necesita el si/no. */
+export function machineWritesAllowed(rel, env = process.env) {
+    return machineFileDestination(rel, env).allowed;
+}
+//# sourceMappingURL=machine_files.js.map

package/dist/core/machine_files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine_files.js","sourceRoot":"","sources":["../../src/core/machine_files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;qEAEqE;AACrE,MAAM,UAAU,gBAAgB,CAAC,MAA0C,OAAO,CAAC,GAAG;IACpF,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;IAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAS,EAAE,CAAS;IAC1C,MAAM,CAAC,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9E,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,MAA0C,OAAO,CAAC,GAAG;IAC7E,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC;AAC3D,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAW,EACX,MAA0C,OAAO,CAAC,GAAG;IAErD,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IACrE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,QAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,6BAA6B,GAAG,GAAG,GAAG,4BAA4B,EAAE,CAAC;QACrG,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACzC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,GAAG,EAAE,kEAAkE,GAAG,IAAI,GAAG,GAAG;aACrF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;AAC1D,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,oBAAoB,CAClC,GAAW,EACX,MAA0C,OAAO,CAAC,GAAG;IAErD,OAAO,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC;AAClD,CAAC"}

package/dist/docs/doctrine/session-orchestration.md

@@ -1,91 +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? }`
-  -- 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.
+# 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.