@crouton-kit/crouter 0.3.17 → 0.3.18

package/dist/builtin-personas/design/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Architect a solution — produce one design document an implementer can build from without re-deciding anything left open.
+---
+
 You are a design agent. Given a bounded design task — a component, subsystem, or interaction surface — you produce one design document an implementer can build from without re-deciding anything you left open. That, not emitting a document, is the bar for done.
 
 Read your task for the scope, the constraints, and the interface contracts you must honor. Write the design to `context/design-<subject>.md` in the standard shape: Context & constraints, Architecture (lead with a diagram, then prose), Components & responsibilities, Interfaces & contracts, Data model, Key flows, Decisions, Open risks. Three things make it a design rather than a description: every decision that closes a real option is captured in Decisions with the alternatives you rejected and why — resolve the choice, never hand the implementer a branch to pick; every interface is concrete enough that both sides can build to it without negotiating; and it stays above implementation — no function bodies, library calls, algorithm walkthroughs, or implementation ordering. If something could be pasted into source, cut it.

package/dist/builtin-personas/developer/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Implement a change — make the feature or fix genuinely work against its acceptance criteria, not merely compile.
+---
+
 You are an implementation agent. Your job is to **implement this feature or change** so the goal it serves is genuinely met — not to emit a diff that compiles and stop.
 
 Work directly. Read the relevant files before editing, match the existing code style and module conventions, and keep your delegation shallow — a focused exploration or a review pass is worth handing off, but most of the work is yours. Throw errors early; no silent fallbacks. Break things correctly rather than patching them badly; prefer clean, breaking changes over backwards-compat hacks in pre-production code.

package/dist/builtin-personas/explore/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Map or investigate an unfamiliar codebase — read-only research that answers a question with concrete file:line evidence.
+---
+
 You are a fast codebase exploration agent. Your work is **read-only research** — do not modify any files.
 
 Answer the question or map the area you have been given. Use grep, find, and file reads to trace code paths, locate symbols, and understand the architecture, following cross-references rather than guessing when you can look it up. Done is the **question fully answered** — every part of it, with evidence — not a plausible partial sketch; if the area turns out too large to map well in one window, promote yourself into an explore orchestrator and fan out scouts rather than skimming the surface and guessing the rest.

package/dist/builtin-personas/general/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Anything else — the catch-all worker for a task that does not fit a specialist kind.
+---
+
 You are a general-purpose worker — the catch-all for work that doesn't fit a specialist kind. Your job is to complete whatever task is handed to you, and "done" means the **goal actually met**, whatever it was, not an artifact emitted in its direction.
 
 Work directly and concisely. Prefer action over clarification: make reasonable assumptions when the task is underspecified and proceed, surfacing only genuine blockers — a missing decision a person must make — not mere uncertainties you could resolve by reading or trying. Verify the result against what was asked before you call it done. If the task turns out larger than one window can finish well, or it clearly wants a specialist's discipline, promote yourself into an orchestrator rather than grinding it out shallowly.

package/dist/builtin-personas/plan/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Break work into steps — turn a spec or design into a concrete, phased, parallelizable plan with every decision resolved.
+---
+
 You are a planning agent. Given a spec, design, or requirement, you produce a concrete, navigable plan an implementer builds from without guessing — every decision resolved, not a document that defers the hard calls to the build. A plan that is 80% right costs more than no plan, because agents build the wrong thing confidently.
 
 A plan is a map, not a script: resolve the ambiguity, define the boundaries, and structure the work for parallelism. Agents read the codebase themselves — point at the pattern to follow ("follow src/jobs/index.ts") rather than re-describing code they will rewrite anyway. Break the work into phased tasks with explicit dependencies, each task small enough for one implementation agent, and flag which can run in parallel. Every design choice lands on a concrete answer; do not hand the implementer a branch to pick. The plan is a living current-state artifact, not a log of how you reached it — state the resolved approach, fold every answer into the task it governs, and carry no decision history, superseded ideas, or standing open questions. Do not implement — plan only.

package/dist/builtin-personas/plan/reviewers/architecture-fit/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: proposed files/modules/abstractions fit the system's existing decomposition; flags new units that duplicate existing ones or cross layer boundaries
+whenToUse: proposed files/modules/abstractions fit the system's existing decomposition; flags new units that duplicate existing ones or cross layer boundaries
 ---
 
 You are an **architecture-fit reviewer**. Given a plan, verify that the files, modules, and abstractions it proposes fit the system's existing decomposition rather than cutting across it.

package/dist/builtin-personas/plan/reviewers/code-smells/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: nullability mismatches, type conflicts across parts, hidden N+1s, over-fetching, missing error boundaries, leaky abstractions; owns file-level conflicts between parts
+whenToUse: nullability mismatches, type conflicts across parts, hidden N+1s, over-fetching, missing error boundaries, leaky abstractions; owns file-level conflicts between parts
 ---
 
 You are a **code-smells / design reviewer**. Given a plan, find the design flaws that would ship if it were implemented as written — before any code makes them expensive.

package/dist/builtin-personas/plan/reviewers/pattern-consistency/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: the plan honors the codebase's real conventions; reads actual source and cites the pattern each finding deviates from; owns contract-level conflicts between parts
+whenToUse: the plan honors the codebase's real conventions; reads actual source and cites the pattern each finding deviates from; owns contract-level conflicts between parts
 ---
 
 You are a **pattern-consistency reviewer**. Given a plan, verify that what it proposes honors the conventions the codebase actually follows — naming, error handling, API shape, module layout, data access, test structure.

package/dist/builtin-personas/plan/reviewers/requirements-coverage/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: every requirement and design constraint maps to a concrete plan task, classified Covered/Partial/Missing; flags only blocking gaps
+whenToUse: every requirement and design constraint maps to a concrete plan task, classified Covered/Partial/Missing; flags only blocking gaps
 ---
 
 You are a **requirements-coverage reviewer**. Given a plan plus the requirements and design it must satisfy, verify that every requirement and every design constraint maps to a concrete task in the plan.

package/dist/builtin-personas/plan/reviewers/security/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: input validation, injection surfaces, auth/authz gaps, data exposure, races; flags only risks with a concrete exploit path
+whenToUse: input validation, injection surfaces, auth/authz gaps, data exposure, races; flags only risks with a concrete exploit path
 ---
 
 You are a **security reviewer**. Given a plan, assess the security risks that would ship if it were implemented as written.

package/dist/builtin-personas/review/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Validate or critique code, a plan, or a spec — deliver a complete, severity-rated verdict without adjudicating.
+---
+
 You are a review agent. Your job is to deliver a **verdict** on the code, plan, or spec you were given — a complete, accurate account of what is and isn't sound. Be critical and precise.
 
 You **detect; you do not adjudicate.** Report each finding accurately and rate its severity — Critical, Major, Minor, Nit — by how bad it actually is; whether a finding blocks is the owner's call, not yours, so don't approve, gate, or soften. For each, state the location, the problem, and — where it isn't obvious — the fix. Cover the whole surface you were given; a verdict that skipped half the diff is not a verdict, so if the surface is too large to review well in one window, promote yourself into a review orchestrator and fan it out rather than skim.

package/dist/builtin-personas/spec/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Write a specification — pin down behavior, non-goals, interfaces, edge cases, and testable acceptance criteria from a goal.
+---
+
 You are a spec writer. Given a goal or feature request, you produce a specification a planner turns into tasks without guessing your intent — that, not emitting a document, is the bar for done.
 
 A spec is genuinely done only when it pins down every dimension a downstream reader would otherwise have to guess: the behavior (what the feature does), the non-goals (what it deliberately does not do — the boundary is as load-bearing as the behavior), the inputs, outputs, and interfaces, the edge cases, and acceptance criteria written so each is testable — an implementer can check it pass or fail without coming back to ask you. Stay at the level of intent and constraint; include implementation detail only where it is genuinely constraining, and cut anything a planner would rewrite anyway. The cost of a flaw here is asymmetric — a planner builds confidently on a wrong premise — so a guessed spec is worse than an admitted gap. Deliver the full spec, complete and self-contained, nothing truncated. The spec states current intent as settled fact, not the path that reached it — fold every clarified decision into the section it belongs in and carry no decision log, superseded framing, or already-answered question; surface a question only when it is genuinely unresolved and needs the human.

package/dist/builtin-skills/skills/crouter-development/personas/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: crouter-development/personas
 type: playbook
-description: How to define a custom node kind (persona) for crtr — base/orchestrator files, the frontmatter contract, scope resolution and overrides, and how to write the prose. Use when adding a new `--kind`, overriding a builtin agent, or debugging persona resolution.
-keywords: [persona, node kind, --kind, orchestrator, base, system prompt]
+description: How to define a custom node kind (persona) for crtr — the PERSONA.md/orchestrator files, the frontmatter contract (incl. whenToUse), nested sub-personas, scope resolution and overrides, and how to write the prose. Use when adding a new `--kind`, overriding a builtin agent, or debugging persona resolution.
+keywords: [persona, node kind, --kind, orchestrator, PERSONA.md, whenToUse, sub-persona, system prompt]
 ---
 
 # Authoring crtr personas (custom node kinds)
@@ -26,13 +26,14 @@ Never edit `src/builtin-personas/` for a local need — that ships to everyone.
 ```
 <root>/personas/
 ├── <kind>/
-│   ├── base.md               # worker persona (mode=base)
-│   └── orchestrator.md       # orchestrator persona (mode=orchestrator) — optional
-├── orchestration-kernel.md   # shared; @include-d by orchestrator files
-└── runtime-base.md           # shared; prepended to EVERY persona automatically
+│   ├── PERSONA.md            # worker persona (mode=base)
+│   ├── orchestrator.md      # orchestrator persona (mode=orchestrator) — optional
+│   └── <sub>/PERSONA.md     # nested sub-persona — kind string `<kind>/<sub>` (any depth)
+├── orchestration-kernel.md  # shared; @include-d by orchestrator files
+└── runtime-base.md          # shared; prepended to EVERY persona automatically
 ```
 
-A kind exists once `<kind>/` holds a `base.md` **or** `orchestrator.md`. `crtr node new --kind <x>` validates against the discovered set and errors with the valid list — your fast existence check.
+The role-body file is **`PERSONA.md`** (not `base.md` — that layout was retired). A kind exists once `<kind>/` holds a `PERSONA.md` **or** `orchestrator.md`; it then appears in the live `<kinds>` list at `crtr node new -h` / `crtr node promote -h` (each row built from the kind's `whenToUse` frontmatter) — your fast existence check. Note `node new` does **not** validate `--kind` (so a sub-persona string like `plan/reviewers/security` spawns fine); `node promote` / `node yield` do validate against the top-level kind set.
 
 ## Scope + precedence
 
@@ -48,11 +49,11 @@ Personas are **scope-root content, not plugin content** — they don't ship via
 
 ## The two files
 
-**`base.md`** — the worker. Second person. State scope → method → deliverable, and end by reporting via `crtr push final`. Default lifecycle `terminal` (finishes in one window). → how to write one: `[[crouter-development/personas/base-prompt]]`.
+**`PERSONA.md`** — the worker (mode=base). Second person. State scope → method → deliverable, and end by reporting via `crtr push final`. Default lifecycle `terminal` (finishes in one window). → how to write one: `[[crouter-development/personas/base-prompt]]`.
 
 **`orchestrator.md`** — the owner that delegates to children and never does the work itself. Name the child kinds it drives and set per-phase exit criteria. **Must end with `@include orchestration-kernel.md`** — the loader inlines it; without it the orchestrator boots with no fan-out protocol. Default lifecycle `resident`. → how to write one: `[[crouter-development/personas/orchestrator-prompt]]`.
 
-If a kind has only `base.md`, `--mode orchestrator` composes `base.md body + kernel` and forces `resident` — so write `orchestrator.md` only when the worker and owner prose genuinely differ.
+If a kind has only `PERSONA.md`, `--mode orchestrator` composes `PERSONA.md body + kernel` and forces `resident` — so write `orchestrator.md` only when the worker and owner prose genuinely differ.
 
 ## Frontmatter contract
 
@@ -66,6 +67,8 @@ YAML frontmatter on either file supplies launch knobs; the body is the system pr
 | `extensions` | string[] | pi extensions, **added after** the always-on canvas extensions. |
 | `skills` | string[] | skills attached at launch. |
 | `roadmapSkill` | string | orchestrator only — a skill whose body is injected as roadmap-shaping guidance when the node runs as an orchestrator. |
+| `whenToUse` | string | on a `<kind>/PERSONA.md` — the one-line "when to use this kind" gloss shown in the `<kinds>` list at `node new -h` / `node promote -h`. |
+| `availableTo` | string[] \| `*` | sub-persona only — which kinds see it in their spawn menu. Default: its top-level ancestor kind. `*` / `all` = every kind. |
 
 `resolve()` never throws: a missing/empty persona falls back to `"You are a <kind> agent…"` defaults, so a node always boots. `runtime-base.md` (the push/finish/delegate/feed/ask protocol) is prepended to every persona — **don't restate it in the body.**
 
@@ -73,23 +76,30 @@ YAML frontmatter on either file supplies launch knobs; the body is the system pr
 
 `@include <filename>` inlines another persona-root file, resolved through the same project>user>builtin chain. Used for `orchestration-kernel.md`; drop an `orchestration-kernel.md` at user/project scope to change orchestrator protocol fleet-wide.
 
+## Sub-personas
+
+A **sub-persona** is a specialist nested under a kind — any descendant dir (any depth) that holds a `PERSONA.md`, e.g. `plan/reviewers/security/PERSONA.md`. It is reachable only by its **full kind string** (`plan/reviewers/security`) and surfaces in a kind's composed prompt (a "Sub-personas you may spawn" menu), never in the global kind list. Intermediate dirs without a `PERSONA.md` (e.g. `reviewers/`) are transparent grouping namespaces — they stay in the kind string but register nothing themselves.
+
+Visibility is its `availableTo` frontmatter: omit it and the sub-persona is visible only to its top-level ancestor kind (so `plan/reviewers/*` show up only for `plan`); set `availableTo: [plan, developer]` to surface it in those kinds; set `availableTo: "*"` for every kind. Sub-personas are visibility-only — they are NOT validated at `node new`, so any kind can still spawn one explicitly by its full string.
+
 ## Dev loop
 
 ```bash
 mkdir -p ~/.crouter/personas/researcher
-$EDITOR ~/.crouter/personas/researcher/base.md         # frontmatter + prose
-crtr node new --kind researcher "map the auth flow"    # spawn; a bad --kind prints the valid kinds
+$EDITOR ~/.crouter/personas/researcher/PERSONA.md       # whenToUse frontmatter + prose
+crtr node new -h                                        # confirm `researcher` now appears in the <kinds> list
+crtr node new --kind researcher "map the auth flow"     # spawn it
 ```
 
-No scaffold command — create the dir + files by hand. Copy a builtin (`explore/base.md`, `developer/orchestrator.md`) as a starting template.
+No scaffold command — create the dir + files by hand. Copy a builtin (`explore/PERSONA.md`, `developer/orchestrator.md`) as a starting template.
 
 ## Failure modes
 
 - **Orchestrator with no `@include orchestration-kernel.md`** — boots without the fan-out protocol; can't delegate. Always include it.
 - **Restating runtime-base** — the push/finish/delegate protocol is already prepended. Duplicating it wastes context and drifts out of sync.
-- **`lifecycle: resident` on a worker `base.md`** — the node never finishes. Reserve `resident` for interactive/long-lived kinds.
+- **`lifecycle: resident` on a worker `PERSONA.md`** — the node never finishes. Reserve `resident` for interactive/long-lived kinds.
 - **Editing `src/builtin-personas/` for a local need** — ships to everyone. Override at user/project scope.
-- **Kind not listed after creating the dir** — neither `base.md` nor `orchestrator.md` is present, or the filename is wrong. The dir alone doesn't register a kind.
+- **Kind not listed after creating the dir** — neither `PERSONA.md` nor `orchestrator.md` is present, or the filename is wrong (it must be exactly `PERSONA.md` — `base.md` no longer registers a kind). The dir alone doesn't register a kind.
 
 ## Related
 

package/dist/builtin-skills/skills/crouter-development/personas/base-prompt/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: crouter-development/personas/base-prompt
 type: playbook
-description: How to write a base persona prompt (base.md) — the system prompt for a single-window worker node. Covers what a base persona is for, what to put in it, the identity/deliverable/boundary/report shape, and the voice to use. Use when writing or revising a <kind>/base.md.
-keywords: [base persona, base.md, worker prompt, system prompt, terminal node]
+description: How to write a base persona prompt (the mode=base PERSONA.md) — the system prompt for a single-window worker node. Covers what a base persona is for, what to put in it, the identity/deliverable/boundary/report shape, and the voice to use. Use when writing or revising a <kind>/PERSONA.md.
+keywords: [base persona, PERSONA.md, worker prompt, system prompt, terminal node]
 ---
 
 # Writing a base persona prompt
 
-`base.md` is the system prompt for a **terminal worker** — a node that does one job in one context window and finishes. Its whole purpose is to make a focused specialist that produces a deliverable and reports it. This skill is the philosophy of what belongs in a base persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
+`PERSONA.md` (mode=base) is the system prompt for a **terminal worker** — a node that does one job in one context window and finishes. Its whole purpose is to make a focused specialist that produces a deliverable and reports it. This skill is the philosophy of what belongs in a base persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
 
-Audience: LLM agents writing a `<kind>/base.md`.
+Audience: LLM agents writing a `<kind>/PERSONA.md`.
 
 ## What a base persona is for
 

package/dist/commands/daemon.js

@@ -93,7 +93,7 @@ const daemonStop = defineLeaf({
             throw new InputError({
                 error: 'kill_failed',
                 message: `failed to signal pid ${pid}: ${err.message}`,
-                next: 'The pidfile may be stale; remove ~/.crtr/crtrd.pid manually.',
+                next: 'The pidfile may be stale; remove ~/.crouter/canvas/crtrd.pid manually.',
             });
         }
     },

package/dist/commands/human/prompts.js

@@ -2,12 +2,12 @@ import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { spawnNode } from '../../core/runtime/nodes.js';
 import { interactionDir } from '../../core/artifact.js';
-import { isInTmux, spawnAndDetach } from '../../core/spawn.js';
+import { isInTmux } from '../../core/spawn.js';
 import { mkdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { validateDeck, approveDeck, notifyDeck, atomicWriteJson, deckPath, display, } from '@crouton-kit/humanloop';
-import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, pickPlacement, runCmd, resolveMaxPanes, } from './shared.js';
+import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, detachHumanTui, resolveMaxPanes, } from './shared.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
@@ -212,13 +212,7 @@ export const humanNotify = defineLeaf({
         atomicWriteJson(join(idir, 'run.json'), rc);
         let shown = false;
         if (isInTmux()) {
-            const spawn = spawnAndDetach({
-                command: runCmd(idir),
-                cwd,
-                placement: pickPlacement(),
-                killAfterSeconds: 0,
-            });
-            shown = spawn.status === 'spawned';
+            shown = detachHumanTui(idir, cwd).status === 'spawned';
         }
         return { shown, dir: idir };
     },

package/dist/commands/human/shared.d.ts

@@ -1,3 +1,4 @@
+import { type DetachResult } from '../../core/spawn.js';
 export declare const DECK_SCHEMA_HINT: string;
 export interface RunRecord {
     mode: 'ask' | 'approve' | 'notify' | 'review';
@@ -9,7 +10,31 @@ export interface RunRecord {
     pane_id?: string;
 }
 export declare function resolveMaxPanes(): number;
-export declare function pickPlacement(): 'split-h' | 'new-window';
+export declare function pickPlacement(targetPane?: string): 'split-h' | 'new-window';
+/**
+ * The tmux pane the humanloop TUI should open BESIDE so a PERSON actually sees
+ * it. A prompt raised by a canvas node must NOT land in the backstage `crtr`
+ * session (the holding ground for un-watched node panes) — it lands in the
+ * session the user is watching that node's graph in:
+ *   1. node prompt (CRTR_NODE_ID set) → the HIGHEST FOCUSED node of its graph
+ *      (`graphSurfaceTarget`, the focused node closest to the graph root): split
+ *      beside it, in the session/window the user already has it open in.
+ *   2. nothing in the graph on screen (or a dead focus pane), or a bare-shell
+ *      prompt → the user's currently-attached pane (`attachedClientPane`).
+ *   3. neither resolvable → undefined (tmux falls back to the caller pane).
+ * The TUI lands in the right place but NEVER switches the user's session/window
+ * (no switch-client / select-window; new-window opens `-d`). They see it when
+ * they look at the node they are already watching.
+ */
+export declare function resolveHumanTarget(): string | undefined;
+/**
+ * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
+ * session the user is watching (`resolveHumanTarget`). The single spawn path
+ * behind ask/approve/review (`spawnHumanJob`) and notify. `detached: true` keeps
+ * the user's view put — the prompt lands beside the watched node without
+ * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
+ */
+export declare function detachHumanTui(idir: string, cwd: string, jobId?: string): DetachResult;
 export declare function runCmd(dir: string): string;
 export declare function followUpResult(_jobId: string): string;
 export declare function followUpDrain(_jobId: string): string;

package/dist/commands/human/shared.js

@@ -2,7 +2,8 @@ import { readConfig } from '../../core/config.js';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { atomicWriteJson, readJson } from '@crouton-kit/humanloop';
-import { countPanesInCurrentWindow, spawnAndDetach, shellQuote } from '../../core/spawn.js';
+import { countPanesInWindow, spawnAndDetach, shellQuote, attachedClientPane, paneAlive, } from '../../core/spawn.js';
+import { graphSurfaceTarget } from '../../core/runtime/placement.js';
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
     'source?:{sessionName?,askedBy?,blockedSince?}, ' +
     'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
@@ -11,8 +12,51 @@ export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {tit
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;
 }
-export function pickPlacement() {
-    return countPanesInCurrentWindow() >= resolveMaxPanes() ? 'new-window' : 'split-h';
+export function pickPlacement(targetPane) {
+    return countPanesInWindow(targetPane) >= resolveMaxPanes() ? 'new-window' : 'split-h';
+}
+/**
+ * The tmux pane the humanloop TUI should open BESIDE so a PERSON actually sees
+ * it. A prompt raised by a canvas node must NOT land in the backstage `crtr`
+ * session (the holding ground for un-watched node panes) — it lands in the
+ * session the user is watching that node's graph in:
+ *   1. node prompt (CRTR_NODE_ID set) → the HIGHEST FOCUSED node of its graph
+ *      (`graphSurfaceTarget`, the focused node closest to the graph root): split
+ *      beside it, in the session/window the user already has it open in.
+ *   2. nothing in the graph on screen (or a dead focus pane), or a bare-shell
+ *      prompt → the user's currently-attached pane (`attachedClientPane`).
+ *   3. neither resolvable → undefined (tmux falls back to the caller pane).
+ * The TUI lands in the right place but NEVER switches the user's session/window
+ * (no switch-client / select-window; new-window opens `-d`). They see it when
+ * they look at the node they are already watching.
+ */
+export function resolveHumanTarget() {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId !== undefined && nodeId !== '') {
+        const f = graphSurfaceTarget(nodeId);
+        if (f !== null && f.pane !== null && paneAlive(f.pane))
+            return f.pane;
+    }
+    return attachedClientPane() ?? undefined;
+}
+/**
+ * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
+ * session the user is watching (`resolveHumanTarget`). The single spawn path
+ * behind ask/approve/review (`spawnHumanJob`) and notify. `detached: true` keeps
+ * the user's view put — the prompt lands beside the watched node without
+ * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
+ */
+export function detachHumanTui(idir, cwd, jobId) {
+    const targetPane = resolveHumanTarget();
+    return spawnAndDetach({
+        command: runCmd(idir),
+        cwd,
+        ...(jobId !== undefined ? { jobId } : {}),
+        placement: pickPlacement(targetPane),
+        killAfterSeconds: 0,
+        detached: true,
+        ...(targetPane !== undefined ? { targetPane } : {}),
+    });
 }
 export function runCmd(dir) {
     return `CRTR_HUMAN_DIR=${shellQuote(dir)} crtr human _run`;
@@ -51,13 +95,7 @@ export function followUpReview(_jobId) {
  * on run.json (not returned) so `human cancel` can later kill the TUI.
  */
 export function spawnHumanJob(jobId, idir, cwd) {
-    const spawn = spawnAndDetach({
-        command: runCmd(idir),
-        cwd,
-        jobId,
-        placement: pickPlacement(),
-        killAfterSeconds: 0,
-    });
+    const spawn = detachHumanTui(idir, cwd, jobId);
     if (spawn.status !== 'spawned') {
         return { spawned: false, follow_up: followUpDrain(jobId) };
     }

package/dist/commands/node.js

@@ -15,7 +15,8 @@ import { detachToBackground, focus as placementFocus, windowAlive, windowOfPane,
 import { buildLaunchSpec } from '../core/runtime/launch.js';
 import { closeNode } from '../core/runtime/close.js';
 import { appendInbox } from '../core/feed/inbox.js';
-import { availableKinds } from '../core/personas/index.js';
+import { availableKinds, kindWhenToUse, subPersonasFor } from '../core/personas/index.js';
+import { stateBlock } from '../core/help.js';
 import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, readContextTokens, } from '../core/canvas/index.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
 // off yielding than holding its fat window open for the child's result: the
@@ -47,6 +48,52 @@ function assertKind(kind) {
         throw new InputError({ error: 'unknown_kind', message: `unknown kind: ${kind}`, field: 'kind', next: `Valid kinds: ${kinds.join(', ')}.` });
     }
 }
+/** A live `<kinds count=N>` state element — one `<kind> — <whenToUse>` line per
+ *  installed top-level persona kind (project > user > builtin), lazily built so
+ *  it reflects the caller's cwd/project scope. Appended to `node new -h` and
+ *  `node promote -h` so custom kinds appear in help. Soft-fails via the renderer.
+ *
+ *  CONTEXT-AWARE: when the CALLER is a live node (CRTR_NODE_ID set) whose kind
+ *  has sub-personas available to it, a SECOND `<sub-personas for=K count=M>`
+ *  block is appended right after — the specialist sub-personas THAT kind may
+ *  spawn (full kind string + whenToUse). Everything but the top-level `<kinds>`
+ *  block soft-fails to omission (caller block wrapped in its own try/catch). */
+function kindsStateBlock() {
+    const kinds = availableKinds();
+    const lines = kinds
+        .map((k) => {
+        const w = kindWhenToUse(k);
+        return w ? `${k} — ${w}` : k;
+    })
+        .join('\n');
+    const block = stateBlock('kinds', { count: kinds.length }, lines);
+    const sub = callerSubPersonasBlock();
+    return sub ? `${block}\n${sub}` : block;
+}
+/** When the caller is a live node whose kind has sub-personas available to it,
+ *  render a `<sub-personas for="<kind>" count=M>` block — one
+ *  `<full-kind-string> — <whenToUse>` line per sub-persona spawnable BY that
+ *  kind (e.g. `plan/reviewers/security`). Returns '' (so the second block is
+ *  omitted) when CRTR_NODE_ID is unset, getNode returns null, the caller kind
+ *  has no sub-personas, or anything throws — this is help output, never error. */
+function callerSubPersonasBlock() {
+    try {
+        const id = process.env['CRTR_NODE_ID'];
+        if (id === undefined || id === '')
+            return '';
+        const node = getNode(id);
+        if (node === null)
+            return '';
+        const subs = subPersonasFor(node.kind);
+        if (subs.length === 0)
+            return '';
+        const lines = subs.map((s) => (s.whenToUse ? `${s.kind} — ${s.whenToUse}` : s.kind)).join('\n');
+        return stateBlock('sub-personas', { for: node.kind, count: subs.length }, lines);
+    }
+    catch {
+        return '';
+    }
+}
 // ---------------------------------------------------------------------------
 // node new — spawn a terminal worker as a background window under the root
 // ---------------------------------------------------------------------------
@@ -60,7 +107,7 @@ const nodeNew = defineLeaf({
         summary: 'spawn a terminal worker onto the canvas as a background window — returns its node id',
         params: [
             { kind: 'stdin', name: 'prompt', required: true, constraint: 'First user message for the spawned node. Piped on stdin or passed as a positional.' },
-            { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind — match the work: explore (map/investigate a codebase), spec (write a spec), design (architect a solution), plan (break work into steps), developer (implement a change), review (validate/critique), general (anything else).' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind — match the work to the kind. The <kinds> list below names every installable kind and when to use each; the <sub-personas> block (when present) names the specialist sub-personas available to YOU, each spawnable by its full kind string (e.g. plan/reviewers/security).' },
             { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for a worker that finishes in one window; orchestrator to create the child directly as a sub-orchestrator (it boots with the orchestrator persona + a seeded roadmap and fans its scope out) — use it when the unit is too large for one window, e.g. a big review, instead of spawning a base worker and counting on it to promote itself.' },
             { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Dir the node is pinned to. Defaults to the caller cwd.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name (tmux window + resume picker). Defaults to the kind.' },
@@ -76,9 +123,10 @@ const nodeNew = defineLeaf({
             { name: 'status', type: 'string', required: true, constraint: 'Always "active" on spawn.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign for the caller: the child runs independently and its finish wakes you on its own, so never wait or poll on it — either pick up other work now or end your turn. If you are an orchestrator already deep in context (>100k), it instead steers you to `crtr node yield` now so your fresh revive absorbs the child\'s result. Read it, then act.' },
         ],
+        dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
         effects: [
-            'Creates a node under ~/.crtr/nodes/<id>/ and indexes it in canvas.db.',
+            'Creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db.',
             'Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only.',
             'Opens a tmux window running pi: a background (non-focus-stealing) window in the shared crtr session for a child; with --root, a new window in your current session (in-tmux) or the shared session (outside tmux), with the client switched to it.',
         ],
@@ -561,7 +609,7 @@ const nodePromote = defineLeaf({
         name: 'node promote',
         summary: 'promote yourself to an orchestrator — do this when your task outgrows one context window (many phases to delegate and persist across refreshes); not for work that fits one window, and not merely because you spawned a child. Mode only — lifecycle stays as-is unless you pass --resident',
         params: [
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator: developer (own feature delivery), review, spec, design, plan, explore, general. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every installable kind and when to use each; the <sub-personas> block (when present) names the specialist sub-personas available to YOU, spawnable by full kind string. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
             { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'ALSO flip lifecycle→resident: make the node interactable — it stays dormant, woken by inbox/human, and is never forced to submit a final. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done).' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
         ],
@@ -577,6 +625,7 @@ const nodePromote = defineLeaf({
             { name: 'user_memory_path', type: 'string', required: true, constraint: 'Absolute path to your USER-GLOBAL memory index (<crtrHome>/memory/MEMORY.md) — who the human is, how they like to work; loaded into every orchestrator everywhere.' },
             { name: 'project_memory_path', type: 'string', required: true, constraint: 'Absolute path to your PROJECT memory index (<crtrHome>/projects/<key>/memory/MEMORY.md) — facts bound to this repo; loaded into every orchestrator working here.' },
         ],
+        dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
         effects: ['Flips mode→orchestrator + kind→chosen (lifecycle unchanged unless --resident, which also flips lifecycle→resident); rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold + all three scoped memory stores (user-global, project, node-local) if absent.', 'Your new-role guidance is injected automatically at the turn boundary by the persona injector — the command no longer returns it.'],
     },

package/dist/core/__tests__/human-surface-target.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/human-surface-target.test.js

@@ -0,0 +1,98 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-surface-target.test.ts
+//
+// BUG REGRESSION: `crtr human ask|approve|review|notify` surfaced its humanloop
+// TUI in the backstage `crtr` session (the asking node's own pane) — a session
+// the user never watches — because spawnAndDetach was called with no `-t`
+// target. The fix routes the TUI to the HIGHEST FOCUSED node of the asking
+// node's graph (the viewport the user is actually watching the work in).
+//
+// This locks in the PURE selection (`graphSurfaceTarget`, db-only, no tmux):
+// walk the asking node's spine to its root, enumerate the tree root-first, and
+// return the focus row of the node closest to the root that occupies a viewport.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, subscribe } from '../canvas/canvas.js';
+import { openFocusRow, closeFocusRow, getFocusByNode } from '../canvas/focuses.js';
+import { closeDb } from '../canvas/db.js';
+import { graphSurfaceTarget } from '../runtime/placement.js';
+let home;
+let savedTmux;
+function node(id, parent) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-surface-'));
+    process.env['CRTR_HOME'] = home;
+    savedTmux = process.env['TMUX'];
+    delete process.env['TMUX']; // PURE: graphSurfaceTarget never touches tmux
+});
+after(() => {
+    closeDb();
+    if (savedTmux !== undefined)
+        process.env['TMUX'] = savedTmux;
+    rmSync(home, { recursive: true, force: true });
+});
+// Graph R → M → W (parent edges + the auto-subscribe spine the runtime builds:
+// a parent subscribes_to its child, so view(R) walks down to M then W).
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-surface-'));
+    process.env['CRTR_HOME'] = home;
+    createNode(node('R', null));
+    createNode(node('M', 'R'));
+    createNode(node('W', 'M'));
+    subscribe('R', 'M');
+    subscribe('M', 'W');
+});
+test('highest focused = the root when only the root is on screen', () => {
+    openFocusRow('f-r', '%10', 'work', 'R');
+    const t = graphSurfaceTarget('W');
+    assert.equal(t?.node_id, 'R');
+    assert.equal(t?.pane, '%10');
+});
+test('falls to the focused mid-orchestrator when the root is NOT on screen', () => {
+    openFocusRow('f-m', '%20', 'work', 'M');
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'M');
+});
+test('picks the SHALLOWEST focused node when several are on screen', () => {
+    openFocusRow('f-m', '%20', 'work', 'M');
+    openFocusRow('f-w', '%30', 'work', 'W');
+    // M is closer to the root than W → M wins.
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'M');
+    openFocusRow('f-r', '%10', 'work', 'R');
+    // Root trumps everything.
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'R');
+});
+test('null when nothing in the graph is on screen (caller falls back)', () => {
+    assert.equal(graphSurfaceTarget('W'), null);
+});
+test('a focus row with no pane is skipped, not selected', () => {
+    openFocusRow('f-r', null, null, 'R'); // focus exists but not yet placed on a pane
+    openFocusRow('f-m', '%20', 'work', 'M');
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'M');
+});
+test('the asking node itself, when it is the focused root, is returned', () => {
+    openFocusRow('f-r', '%10', 'work', 'R');
+    assert.equal(graphSurfaceTarget('R')?.node_id, 'R');
+});
+test('sanity: a closed focus drops out of the selection', () => {
+    openFocusRow('f-m', '%20', 'work', 'M');
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'M');
+    closeFocusRow('f-m');
+    assert.equal(getFocusByNode('M'), null);
+    assert.equal(graphSurfaceTarget('W'), null);
+});