@crouton-kit/crouter 0.3.19 → 0.3.20

package/dist/core/__tests__/live-mutation.test.js

@@ -24,6 +24,10 @@
 // (idle-release vs dormant; persona-ack recompose; the A4 boundary) changes
 // accordingly. None of the above drives `crtr node lifecycle` on a live node,
 // nor asserts persona_ack mutation across a live promote, nor the A4 loss site.
+//
+// Part 2 of this axis — the demote/recycle verb split and the A4 promote-then-
+// yield boundary — lives in live-mutation-verbs.test.ts (split for node:test
+// file-level parallelism; each test holds its own isolated harness).
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
@@ -45,15 +49,6 @@ function orchestrationSteers(inj) {
 function persona(m) {
     return { mode: m.mode, lifecycle: m.lifecycle };
 }
-/** The first %pane_id of a tmux window. The spawn path records window+session
- *  but NOT pane (spawn.ts: pane is null until a reconcile/focus), so a node's
- *  live pane must be resolved from its window here. */
-function firstPaneOf(window) {
-    const r = spawnSync('tmux', ['list-panes', '-t', window, '-F', '#{pane_id}'], { encoding: 'utf8' });
-    if (r.status !== 0)
-        return null;
-    return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean)[0] ?? null;
-}
 // ===========================================================================
 // (a) LIFECYCLE FLIP — `crtr node lifecycle` on a LIVE node, both directions,
 //     observing the idle-release behavior change. A round-trip on ONE live
@@ -218,141 +213,3 @@ test('live mode flip: promote base→orchestrator recomposes persona_ack at turn
         assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
     }
 });
-// ===========================================================================
-// (b) THE demote / recycle SPLIT — two DISTINCT verbs after the rename:
-//   • `node demote`  flips a LIVE node's lifecycle→TERMINAL IN PLACE — it keeps
-//     its pane, its MODE, and its parentage, keeps running, is NOT finalized; it
-//     now merely owes a final up the spine (vision F5). It is NOT an
-//     orchestrator→base mode flip — MODE is untouched (so persona.ts
-//     `baseModeGuidance` stays unreachable via live mutation, as before).
-//   • `node recycle` is FINISH+RECYCLE — push final → done, then recycle the
-//     pane into a FRESH general/base/resident root (a DIFFERENT node). The
-//     recycled node keeps mode=orchestrator (it is merely `done`).
-// This test drives BOTH real verbs on one live node and pins each behavior.
-// ===========================================================================
-test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RECYCLE', { skip: SKIP, timeout: 120_000 }, async () => {
-    const h = await createHarness({ sessionPrefix: 'crtr-live-demote' });
-    try {
-        const A = h.spawnRoot('resident root');
-        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
-        // Make B resident + orchestrator so the demote's flip→terminal is visible
-        // and we can prove MODE/parentage survive it.
-        assert.equal(h.cli(B, ['node', 'lifecycle', 'resident', '--node', B]).code, 0, 'B → resident');
-        assert.equal(h.cli(B, ['node', 'promote', '--kind', 'developer']).code, 0, 'promote B');
-        {
-            const b = h.node(B);
-            assert.equal(b.lifecycle, 'resident', 'B resident before demote');
-            assert.equal(b.mode, 'orchestrator', 'B orchestrator before demote');
-        }
-        const bParent = h.node(B).parent;
-        // --- node demote: flip-to-terminal IN PLACE. Keeps B alive, MODE/parentage
-        //     untouched, NOT finalized.
-        const dem = h.cli(B, ['node', 'demote', '--node', B]);
-        assert.equal(dem.code, 0, `node demote exit 0\n${dem.stderr}`);
-        assert.match(dem.stdout, /<demoted /, `demote rendered\n${dem.stdout}`);
-        {
-            const b = h.node(B);
-            assert.equal(b.lifecycle, 'terminal', 'demote flips lifecycle→terminal IN PLACE');
-            assert.equal(b.mode, 'orchestrator', 'demote leaves MODE untouched (not an orchestrator→base flip)');
-            assert.equal(b.parent, bParent, 'demote leaves parentage unchanged');
-            assert.equal(b.status, 'active', 'demote does NOT finish B — it keeps running in place');
-            assert.notEqual(b.intent ?? null, 'done', 'demote does NOT finalize B');
-        }
-        // --- node recycle: FINISH + RECYCLE the SAME pane into a fresh root.
-        //     Resolve B's live %pane_id from its window (the row's `pane` is null
-        //     until a reconcile; the spawn path records only window+session).
-        const pane = firstPaneOf(h.node(B).window);
-        assert.ok(typeof pane === 'string' && pane !== '', 'B has a live pane to recycle');
-        // RECYCLE via the real verb (TMUX_PANE is scrubbed from child env → pass --pane).
-        const res = h.cli(B, ['node', 'recycle', '--node', B, '--pane', pane]);
-        assert.equal(res.code, 0, `recycle exit 0\n${res.stderr}`);
-        // The leaf renders `<recycled ... finalized=".." new_root=".."/>` (not JSON).
-        assert.match(res.stdout, /<recycled /, `recycle recycled the pane\n${res.stdout}`);
-        const newRoot = /new_root="([^"]+)"/.exec(res.stdout)?.[1];
-        const finalized = /finalized="true"/.test(res.stdout);
-        // The recycled node is FINISHED, not mode-flipped.
-        {
-            const b = h.node(B);
-            assert.equal(b.status, 'done', 'recycled node → done (finished), NOT re-roled');
-            assert.equal(b.intent, 'done', 'intent=done (finalize), per the push-final path');
-            assert.equal(b.mode, 'orchestrator', 'recycled node KEEPS mode=orchestrator — recycle is NOT a mode flip');
-            assert.ok(finalized, 'recycle pushed a final for the node');
-        }
-        // The fresh root is a DIFFERENT, BASE×RESIDENT node.
-        assert.ok(typeof newRoot === 'string' && newRoot !== B, 'a fresh root (≠ B) was minted');
-        {
-            const fresh = h.node(newRoot);
-            assert.deepEqual(persona(fresh), { mode: 'base', lifecycle: 'resident' }, 'recycled root is born base×resident (general)');
-            assert.deepEqual(fresh.persona_ack, { mode: 'base', lifecycle: 'resident' }, 'fresh root born acked base×resident');
-        }
-    }
-    finally {
-        const session = h.session;
-        await h.dispose();
-        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
-    }
-});
-// ===========================================================================
-// (b) A4 BOUNDARY — promote-then-yield emits a steer that is discarded. The
-//     oracle/flagship boundary: the base→orchestrator guidance lands as a STEER
-//     only if a turn_end fires while the drift is pending. A `node yield` on a
-//     base node auto-promotes (mode→orchestrator, ack NOT committed) and its
-//     agent_end goes STRAIGHT to reviveInPlace (b') with NO preceding turn_end —
-//     so the only steer-delivery site (turn_end) is BYPASSED. Two deterministic
-//     facts pin the boundary, both confirmed by direct observation:
-//       (1) NO orchestration STEER is ever delivered (the LOSS).
-//       (2) The ack is silently advanced base→orchestrator at the refresh DRAIN
-//           (reviveInPlace→drainBearings→commitPersonaAck), NOT via a steer — so
-//           neither this turn nor (per A4) the fresh revive re-offers it as a
-//           steer; the guidance survives only in the kickoff PROMPT it built.
-//     ⚑ FLAGGED (not fixed): the in-place refresh of this LARGE pending-drift
-//        kickoff prompt did NOT complete a fresh fake-pi boot in the harness (it
-//        stayed at 1 boot, intent=refresh, ack=orchestrator, pane alive) — a
-//        base→orchestrator yield's giant <persona-transition> kickoff pushed
-//        through respawn-pane did not bring up the fresh vehicle. Whether a real
-//        edge (oversized argv through respawn-pane) or a harness artifact, it is
-//        out of scope to fix; this test asserts only the deterministic boundary.
-// ===========================================================================
-test('A4: a base→orchestrator yield with no preceding turn_end loses the orchestration STEER (ack advances silently at the refresh drain)', { skip: SKIP, timeout: 120_000 }, async () => {
-    const h = await createHarness({ sessionPrefix: 'crtr-live-a4' });
-    try {
-        const A = h.spawnRoot('resident root');
-        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
-        assert.deepEqual(persona(h.node(B)), { mode: 'base', lifecycle: 'terminal' }, 'B born base×terminal');
-        const injBefore = h.injected(B).length;
-        // `crtr node yield` (base → auto-promote → intent=refresh). INTERMEDIATE
-        // state, BEFORE any agent_end: mode flipped, ack NOT yet committed (the
-        // turn_end injector has not run), intent=refresh, drift PENDING.
-        const y = h.cli(B, ['node', 'yield', 'refresh against the roadmap']);
-        assert.equal(y.code, 0, `node yield exit 0\n${y.stderr}`);
-        {
-            const b = h.node(B);
-            assert.equal(b.mode, 'orchestrator', 'yield auto-promoted base→orchestrator');
-            assert.equal(b.intent, 'refresh', 'intent=refresh set by the yield');
-            assert.deepEqual(b.persona_ack, { mode: 'base', lifecycle: 'terminal' }, 'ack STILL base — promote/yield never commits it; only an injector does');
-        }
-        // Fire the stop: agent_end sees intent=refresh → (b') reviveInPlace, whose
-        // drainBearings commits the ack synchronously BEFORE the respawn. NO
-        // turn_end fires this turn, so the turn_end steer site is bypassed.
-        await h.stop(B);
-        // (2) The ack is silently advanced to orchestrator at the refresh DRAIN —
-        // not by any steer. (waitFor: the agent_end handler runs after h.stop
-        // observes the recorded event.)
-        await h.waitFor(() => {
-            const a = h.node(B)?.persona_ack;
-            return a?.mode === 'orchestrator' && a?.lifecycle === 'terminal';
-        }, { timeoutMs: 20_000, label: 'persona_ack advanced at the refresh drain (not via a steer)' });
-        assert.deepEqual(h.node(B).persona_ack, { mode: 'orchestrator', lifecycle: 'terminal' }, 'ack committed base→orchestrator by drainBearings during reviveInPlace');
-        // (1) ⚑ LOSS site: across the whole yield→refresh, NO orchestration
-        // guidance was ever delivered as a turn-boundary STEER (the only steer
-        // site, turn_end, never ran). The ack moved without the agent ever being
-        // steered with the new-role guidance — it survives only in the kickoff
-        // prompt drainBearings built for the (here, non-booting) fresh vehicle.
-        assert.equal(orchestrationSteers(h.injected(B).slice(injBefore)).length, 0, '⚑ A4: no orchestration STEER delivered — the turn_end injector was bypassed by the yield');
-    }
-    finally {
-        const session = h.session;
-        await h.dispose();
-        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
-    }
-});

package/dist/core/canvas/canvas.js

@@ -22,7 +22,7 @@ import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from '.
 const IDENTITY_KEYS = [
     'node_id', 'name', 'description', 'cycles', 'created', 'cwd', 'host_kind', 'kind', 'mode',
     'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'passive_default',
-    'home_session', 'pi_session_id', 'pi_session_file', 'launch',
+    'home_session', 'pi_session_id', 'pi_session_file', 'model_override', 'launch',
 ];
 /** Project any node object down to its durable-identity subset. */
 function toIdentity(m) {

package/dist/core/canvas/types.d.ts

@@ -104,6 +104,12 @@ export interface NodeIdentity {
      *  PATH is opened directly — immune to any cwd discrepancy. Null for older
      *  nodes booted before this field existed → revive falls back to the bare id. */
     pi_session_file?: string | null;
+    /** A caller-pinned model TIER (ultra/strong/medium/light) that overrides the
+     *  persona's declared default. Durable so it survives a polymorph: every
+     *  spec-rebuild path (promote/demote/lifecycle/reset) re-passes it to
+     *  buildLaunchSpec, while the persona default is recomputed fresh for the
+     *  (possibly new) kind. Null/undefined ⇒ use the persona default. */
+    model_override?: string | null;
     /** Full pi launch recipe; rewritten on every polymorph. */
     launch?: LaunchSpec;
 }

package/dist/core/runtime/launch.d.ts

@@ -22,8 +22,14 @@ export declare const CANVAS_VIEW_PATH: string;
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export declare const CANVAS_EXTENSIONS: string[];
-/** Bare model aliases resolve to the anthropic provider under pi (avoids the
- *  bedrock default). Anything with a `/` or an unknown name passes through. */
+/** The named capability tiers a caller picks with `--model`, in descending
+ *  strength. Each maps to a concrete pi model spec. `strong`/`medium`/`light`
+ *  resolve to the latest opus/sonnet/haiku; `ultra` to the frontier model. */
+export declare const MODEL_TIERS: Record<string, string>;
+/** Resolve a model token to the spec pi gets via `--model`. A named tier
+ *  (ultra/strong/medium/light) maps to its concrete spec; a bare alias
+ *  (sonnet/opus/haiku) resolves to the anthropic provider under pi (avoids the
+ *  bedrock default); anything with a `/` or an unknown name passes through. */
 export declare function normalizeModel(model: string): string;
 /** Compose a node's full pi launch recipe from its persona. The system prompt
  *  is composed from FOUR inputs: kind×mode (the persona body) plus lifecycle
@@ -36,6 +42,7 @@ export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
     lifecycle: Lifecycle;
     hasManager: boolean;
     extraEnv?: Record<string, string>;
+    model?: string;
 }): {
     launch: LaunchSpec;
     lifecycle: 'terminal' | 'resident';

package/dist/core/runtime/launch.js

@@ -60,9 +60,22 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_RESUME_PATH,
     CANVAS_VIEW_PATH,
 ];
-/** Bare model aliases resolve to the anthropic provider under pi (avoids the
- *  bedrock default). Anything with a `/` or an unknown name passes through. */
+/** The named capability tiers a caller picks with `--model`, in descending
+ *  strength. Each maps to a concrete pi model spec. `strong`/`medium`/`light`
+ *  resolve to the latest opus/sonnet/haiku; `ultra` to the frontier model. */
+export const MODEL_TIERS = {
+    ultra: 'anthropic/claude-fable-5',
+    strong: 'anthropic/opus',
+    medium: 'anthropic/sonnet',
+    light: 'anthropic/haiku',
+};
+/** Resolve a model token to the spec pi gets via `--model`. A named tier
+ *  (ultra/strong/medium/light) maps to its concrete spec; a bare alias
+ *  (sonnet/opus/haiku) resolves to the anthropic provider under pi (avoids the
+ *  bedrock default); anything with a `/` or an unknown name passes through. */
 export function normalizeModel(model) {
+    if (model in MODEL_TIERS)
+        return MODEL_TIERS[model];
     const bare = new Set(['sonnet', 'opus', 'haiku']);
     if (bare.has(model))
         return `anthropic/${model}`;
@@ -80,8 +93,12 @@ export function normalizeModel(model) {
  *  declared extensions follow. */
 export function buildLaunchSpec(kind, mode, opts) {
     const p = resolvePersona(kind, mode, { lifecycle: opts.lifecycle, hasManager: opts.hasManager });
+    // A caller-supplied override (durable on `meta.model_override`, re-passed on
+    // every polymorph) wins over the persona's declared default; absent both, the
+    // model is left unset and the node inherits pi's default.
+    const chosenModel = opts.model ?? p.model;
     const launch = {
-        model: p.model !== undefined ? normalizeModel(p.model) : undefined,
+        model: chosenModel !== undefined ? normalizeModel(chosenModel) : undefined,
         tools: p.tools,
         extensions: [...CANVAS_EXTENSIONS, ...p.extensions],
         systemPrompt: p.systemPrompt,

package/dist/core/runtime/nodes.d.ts

@@ -98,6 +98,10 @@ export interface SpawnNodeOpts {
     passiveDefault?: boolean;
     /** Resolved pi launch recipe (from resolve(kind,mode)). */
     launch?: LaunchSpec;
+    /** Caller-pinned model tier (ultra/strong/medium/light) that overrides the
+     *  persona default. Persisted to `meta.model_override` so polymorphs preserve
+     *  it. Omit to use the persona default. */
+    modelOverride?: string | null;
     /** Override the generated id (e.g. when a caller pre-allocates one). */
     nodeId?: string;
 }

package/dist/core/runtime/nodes.js

@@ -179,6 +179,7 @@ export function spawnNode(opts) {
         parent,
         spawned_by: spawnedBy,
         fork_from: opts.forkFrom,
+        model_override: opts.modelOverride ?? null,
         passive_default: opts.passiveDefault ?? false,
         intent: null,
         pi_session_id: null,

package/dist/core/runtime/promote.js

@@ -46,6 +46,9 @@ export function promote(nodeId, opts = {}) {
     const { launch } = buildLaunchSpec(targetKind, 'orchestrator', {
         lifecycle: opts.resident === true ? 'resident' : node.lifecycle,
         hasManager: node.parent !== null,
+        // Preserve a caller-pinned model tier across the polymorph (the persona
+        // default is recomputed fresh for targetKind).
+        model: node.model_override ?? undefined,
     });
     // Seed a barebones roadmap scaffold if absent so the file exists for a
     // refresh. Pre-fill its Goal from the node's goal doc when present (set at

package/dist/core/runtime/reset.js

@@ -112,7 +112,7 @@ export function resetRoot(nodeId, newSessionId, newSessionFile) {
     //    Re-seed persona_ack to the fresh persona so the pristine `/new`
     //    conversation never gets a spurious mode/lifecycle transition steer (the
     //    persona injector compares against this ack).
-    const { launch } = buildLaunchSpec(meta.kind, 'base', { lifecycle: 'resident', hasManager: false });
+    const { launch } = buildLaunchSpec(meta.kind, 'base', { lifecycle: 'resident', hasManager: false, model: meta.model_override ?? undefined });
     updateNode(nodeId, {
         mode: 'base',
         lifecycle: 'resident',
@@ -180,7 +180,7 @@ export function relaunchRoot(oldId, pane, deps = {}) {
         window: oldMeta.window ?? null,
     };
     const newId = newNodeId();
-    const { launch } = buildLaunchSpec(oldMeta.kind, 'base', { lifecycle: 'resident', hasManager: false });
+    const { launch } = buildLaunchSpec(oldMeta.kind, 'base', { lifecycle: 'resident', hasManager: false, model: oldMeta.model_override ?? undefined });
     // Park-old + mint-new is the single most fragile spot in the runtime, so it is
     // ONE atomic unit: every ROW write below runs inside a sqlite transaction. A
     // failure anywhere — including the respawn DISPATCH — rolls the whole thing
@@ -206,6 +206,7 @@ export function relaunchRoot(oldId, pane, deps = {}) {
             parent: null,
             spawnedBy: oldId, // audit-only successor link; does NOT touch the spine
             nodeId: newId,
+            modelOverride: oldMeta.model_override,
             launch,
         });
         transition(newId, 'yield'); // active (from spawn) + intent=refresh safety net

package/dist/core/runtime/spawn.d.ts

@@ -39,6 +39,10 @@ export interface SpawnChildOpts {
      *  headless broker. Persisted as `host_kind` at birth (resolved from
      *  `--headless` / the `headless` config default by the caller). */
     hostKind?: 'tmux' | 'broker';
+    /** Pin the node to a model TIER (ultra/strong/medium/light), overriding the
+     *  persona's declared default. Persisted to `meta.model_override` so it
+     *  survives polymorphs. Omit to use the persona default. */
+    model?: string;
 }
 /** Resolve a `--fork-from` value to the source pi gets as `--fork <path|id>`.
  *  A live node id resolves to its captured session FILE (absolute, cwd-immune),

package/dist/core/runtime/spawn.js

@@ -161,7 +161,7 @@ export function spawnChild(opts) {
     // Spine: a managed child reports up to its spawner (has a manager); an
     // independent root sits top-of-spine with nobody to push to. Mirrors the
     // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
-    const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root });
+    const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model });
     // Name the worker from its task now, so its first editor label carries it.
     const meta = spawnNode({
         kind: opts.kind,
@@ -180,6 +180,7 @@ export function spawnChild(opts) {
         // identity over the source's copied-in conversation.
         forkFrom: opts.forkFrom,
         hostKind: opts.hostKind,
+        modelOverride: opts.model,
         launch,
     });
     // Persist the task as the child's goal for a fresh revive to re-read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",