@zenera/cli 1.1.9 → 1.1.11

package/dist/tui/theme.d.ts

@@ -13,8 +13,12 @@ export interface Theme {
     readonly accent: string;
     /** Read-only badge, busy label. */
     readonly warn: string;
-    /** Gutters and marks: structure, not content. Always drawn dim. */
-    readonly rule?: string;
+    /**
+     * Branch colours, cycled in order of first sight. A fan-out is the one
+     * place where colour carries information rather than decoration: eight
+     * branches reporting at once are only separable if they are told apart.
+     */
+    readonly lanes: readonly string[];
 }
 export declare const THEMES: Record<Appearance, Theme>;
 export type ThemeChoice = Appearance | 'auto';

package/dist/tui/theme.js

@@ -8,9 +8,10 @@
 // the person's own turn, the agent name, a warning, an error — take a colour.
 //
 // That alone fixes most of it. `white` was the bug: it is legible on exactly
-// one kind of background, and half the world runs the other kind. What is left
-// is the handful of accents that ANSI *does* let a light theme get wrong —
-// `cyan` on paper, `gray` on paper — so those swap.
+// one kind of background, and half the world runs the other kind. `gray` was
+// the same bug wearing a hat — bright black, dimmed again, is a step from
+// unreadable on dark and invisible on paper. What is left is the handful of
+// accents that ANSI *does* let a light theme get wrong, so those swap.
 //
 // Note what is *not* here: no hex, no 256-colour ramps, no attempt at a brand.
 // A palette that ignores the user's scheme is worse on both schemes than one
@@ -21,17 +22,20 @@ const DARK = {
     line: {
         you: { color: 'cyan' },
         agent: {},
-        tool: { color: 'gray', dim: true },
+        // Dim alone, never dim *and* `gray`: bright black is already the
+        // faintest colour a terminal has, and dimming it again puts the bulk
+        // of the transcript a step from unreadable.
+        tool: { dim: true },
         note: { color: 'cyan', dim: true },
         error: { color: 'red' },
     },
     accent: 'cyan',
     warn: 'yellow',
-    rule: 'gray',
+    lanes: ['magenta', 'cyan', 'green', 'yellow', 'blue', 'red'],
 };
-// On a light background `gray` is bright black — pale grey on white — and
-// `cyan` and `yellow` are barely darker than the paper. Dimmed default
-// foreground and `blue`/`magenta` are the same information, still legible.
+// On a light background `cyan` and `yellow` are barely darker than the paper.
+// Dimmed default foreground and `blue`/`magenta` are the same information,
+// still legible.
 const LIGHT = {
     appearance: 'light',
     line: {
@@ -43,6 +47,8 @@ const LIGHT = {
     },
     accent: 'blue',
     warn: 'magenta',
+    // No cyan or yellow: on paper they are barely darker than the paper.
+    lanes: ['magenta', 'blue', 'green', 'red'],
 };
 export const THEMES = { dark: DARK, light: LIGHT };
 export function parseChoice(value) {

package/dist/tui/wrap.d.ts

@@ -7,6 +7,98 @@
  * and bounds the work per keystroke on a stream that never stops growing.
  */
 export declare function windowOf(text: string, width: number, rows: number): string[];
+/**
+ * `text` flattened onto one row of at most `width` columns, ellipsized when it
+ * did not fit. Newlines and runs of space collapse: a row is a row, and a tool
+ * argument or a result preview arrives with whatever shape it happened to have.
+ */
+export declare function clip(text: string, width: number): string;
 /** Word wrap. Every returned row is at most `width` columns wide. */
 export declare function wrap(text: string, width: number): string[];
+/** The three footer rows, its margin, the prompt, and a row in hand. */
+export declare const CHROME_ROWS = 7;
+/** How much of the reasoning stream is worth showing. It is a progress bar. */
+export declare const THINKING_ROWS = 6;
+/** How much of the frame the work in flight may take. A branch is a box now,
+ *  not a row, so a fan-out of two costs fourteen of these. */
+export declare const ACTIVITY_ROWS = 16;
+/** The rule that opens a reasoning block and the one that closes it. */
+export declare const THINKING_CHROME = 2;
+export interface Budget {
+    /** rows for the list of what is in flight */
+    activity: number;
+    /** rows for the tail of the reasoning stream */
+    thinking: number;
+    /** rows for the answer as it arrives */
+    live: number;
+    /**
+     * What the three of them occupy together, rules included — a constant for
+     * a given terminal, whatever is happening inside it. The region grows to
+     * this and stops, and never shrinks back while the turn runs, which is what
+     * keeps the footer on one row instead of riding up and down on the
+     * reasoning block.
+     */
+    total: number;
+}
+/**
+ * How many rows each repainting block may draw in a terminal `rows` tall.
+ *
+ * Activity is capped first and never takes the last two rows: the answer as it
+ * arrives matters more than the machinery producing it. Reasoning yields to it
+ * in turn, because it is a progress indicator and the answer is the point.
+ *
+ * `thinking` is how many rows of reasoning are wanted, counting text only: none
+ * when there is no reasoning, fewer than `THINKING_ROWS` once the stream has
+ * settled and its tail is history rather than progress. The two rules are
+ * charged on top, so a block too cramped to be worth boxing is not drawn at all
+ * rather than drawn as a border with a line in it.
+ */
+export declare function budgetOf(rows: number, activity: number, thinking: number): Budget;
+/** The rows a branch box may spend on its own calls and its reasoning. */
+export declare const BRANCH_ROWS = 5;
+/** Rows a branch box spends on chrome: the title rule and the closing one. */
+export declare const BOX_CHROME = 2;
+/**
+ * How many call rows each of `count` branch boxes may draw, given the rows the
+ * activity region has to divide between them.
+ *
+ * Every branch gets the same number, because they are the same kind of thing
+ * and a fan-out is read across, not down. A wide fork spends its rows on being
+ * complete rather than on being detailed: eight branches showing one call each
+ * is a picture of the fork, eight rows of one branch is not.
+ */
+export declare function branchRows(count: number, allowance: number): number;
+/**
+ * How wide the answer is drawn. A line of prose spanning a 200-column terminal
+ * is measurably harder to read than one that stops, which is why every demo in
+ * `examples/` puts its answer in a box of bounded width — the terminal is the
+ * page, not the paragraph.
+ */
+export declare function answerWidth(columns: number): number;
+/**
+ * A tool payload as a person would read it, rather than as it was serialised.
+ *
+ * A lone field is printed as its bare value, because the name of a generic tool
+ * says almost nothing on its own — `run_command` is every shell command there
+ * is, and the argument is the part that identifies THIS call.
+ *
+ * It scans rather than parses: previews are cut to a length, so the JSON very
+ * often does not close, and precisely the calls worth reading are the long ones
+ * that got cut.
+ */
+export declare function readable(preview: string): string;
+/** A run of lines from an answer, and whether it was fenced as code. */
+export interface Segment {
+    code: boolean;
+    /** the fence's info string, when it had one */
+    title?: string;
+    lines: string[];
+}
+/**
+ * Splits an answer on ``` fences. Prose is left exactly as it was — the common
+ * answer has no fence in it and comes back in one piece — but a fenced block is
+ * the one thing a terminal must not reflow: its indentation is its meaning, and
+ * wrapping it as prose destroys it.
+ */
+export declare function segmentsOf(text: string): Segment[];
 //# sourceMappingURL=wrap.d.ts.map

package/dist/tui/wrap.js

@@ -23,8 +23,23 @@
 export function windowOf(text, width, rows) {
     const w = Math.max(8, width);
     const n = Math.max(1, rows);
-    const wrapped = wrap(text.slice(-w * n * 2).replace(/\n{2,}/g, '\n'), w);
-    return wrapped.slice(-n);
+    // Trailing blank rows are never information, and a stream that ends on a
+    // paragraph break would spend one of the few rows it has on nothing.
+    const tail = text
+        .slice(-w * n * 2)
+        .replace(/\n{2,}/g, '\n')
+        .trimEnd();
+    return wrap(tail, w).slice(-n);
+}
+/**
+ * `text` flattened onto one row of at most `width` columns, ellipsized when it
+ * did not fit. Newlines and runs of space collapse: a row is a row, and a tool
+ * argument or a result preview arrives with whatever shape it happened to have.
+ */
+export function clip(text, width) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    const w = Math.max(1, width);
+    return flat.length <= w ? flat : `${flat.slice(0, w - 1)}…`;
 }
 /** Word wrap. Every returned row is at most `width` columns wide. */
 export function wrap(text, width) {
@@ -59,4 +74,134 @@ export function wrap(text, width) {
     }
     return out;
 }
+// ---------------------------------------------------------------------------
+// Dividing the frame
+//
+// The same invariant, stated as arithmetic: every repainting block gets its
+// rows from here, and the sum is never more than the viewport has to give.
+// ---------------------------------------------------------------------------
+/** The three footer rows, its margin, the prompt, and a row in hand. */
+export const CHROME_ROWS = 7;
+/** How much of the reasoning stream is worth showing. It is a progress bar. */
+export const THINKING_ROWS = 6;
+/** How much of the frame the work in flight may take. A branch is a box now,
+ *  not a row, so a fan-out of two costs fourteen of these. */
+export const ACTIVITY_ROWS = 16;
+/** The rule that opens a reasoning block and the one that closes it. */
+export const THINKING_CHROME = 2;
+/**
+ * How many rows each repainting block may draw in a terminal `rows` tall.
+ *
+ * Activity is capped first and never takes the last two rows: the answer as it
+ * arrives matters more than the machinery producing it. Reasoning yields to it
+ * in turn, because it is a progress indicator and the answer is the point.
+ *
+ * `thinking` is how many rows of reasoning are wanted, counting text only: none
+ * when there is no reasoning, fewer than `THINKING_ROWS` once the stream has
+ * settled and its tail is history rather than progress. The two rules are
+ * charged on top, so a block too cramped to be worth boxing is not drawn at all
+ * rather than drawn as a border with a line in it.
+ */
+export function budgetOf(rows, activity, thinking) {
+    const total = Math.max(2, rows - CHROME_ROWS);
+    const shown = Math.min(Math.max(0, activity), ACTIVITY_ROWS, Math.max(0, total - 2));
+    const rest = total - shown;
+    const room = rest - 1 - THINKING_CHROME;
+    const tail = room >= 1 ? Math.min(Math.max(0, thinking), THINKING_ROWS, room) : 0;
+    return {
+        activity: shown,
+        thinking: tail,
+        live: rest - tail - (tail ? THINKING_CHROME : 0),
+        total,
+    };
+}
+/** The rows a branch box may spend on its own calls and its reasoning. */
+export const BRANCH_ROWS = 5;
+/** Rows a branch box spends on chrome: the title rule and the closing one. */
+export const BOX_CHROME = 2;
+/**
+ * How many call rows each of `count` branch boxes may draw, given the rows the
+ * activity region has to divide between them.
+ *
+ * Every branch gets the same number, because they are the same kind of thing
+ * and a fan-out is read across, not down. A wide fork spends its rows on being
+ * complete rather than on being detailed: eight branches showing one call each
+ * is a picture of the fork, eight rows of one branch is not.
+ */
+export function branchRows(count, allowance) {
+    if (count <= 0) {
+        return 0;
+    }
+    const each = Math.floor(Math.max(0, allowance) / count) - BOX_CHROME;
+    return Math.max(1, Math.min(BRANCH_ROWS, each));
+}
+/**
+ * How wide the answer is drawn. A line of prose spanning a 200-column terminal
+ * is measurably harder to read than one that stops, which is why every demo in
+ * `examples/` puts its answer in a box of bounded width — the terminal is the
+ * page, not the paragraph.
+ */
+export function answerWidth(columns) {
+    return Math.max(24, Math.min(columns - 4, 96));
+}
+// ---------------------------------------------------------------------------
+// Reading a payload
+// ---------------------------------------------------------------------------
+/** One field of a preview: a JSON string, or a bare token when it was cut. */
+const FIELD = /"([A-Za-z_][\w-]*)"\s*:\s*("(?:[^"\\]|\\.)*"?|[^,}\s]+)/g;
+/**
+ * A tool payload as a person would read it, rather than as it was serialised.
+ *
+ * A lone field is printed as its bare value, because the name of a generic tool
+ * says almost nothing on its own — `run_command` is every shell command there
+ * is, and the argument is the part that identifies THIS call.
+ *
+ * It scans rather than parses: previews are cut to a length, so the JSON very
+ * often does not close, and precisely the calls worth reading are the long ones
+ * that got cut.
+ */
+export function readable(preview) {
+    const found = [...preview.matchAll(FIELD)];
+    if (!found.length) {
+        return preview.trim();
+    }
+    const fields = found.map((m) => [m[1], unquote(m[2])]);
+    const one = fields.length === 1 ? fields[0] : undefined;
+    return one ? one[1] : fields.map(([k, v]) => `${k}=${v}`).join(' ');
+}
+function unquote(raw) {
+    if (!raw.startsWith('"')) {
+        return raw;
+    }
+    const body = raw.length > 1 && raw.endsWith('"') ? raw.slice(1, -1) : raw.slice(1);
+    return body.replace(/\\[nrt]/g, ' ').replace(/\\(["\\/])/g, '$1');
+}
+/**
+ * Splits an answer on ``` fences. Prose is left exactly as it was — the common
+ * answer has no fence in it and comes back in one piece — but a fenced block is
+ * the one thing a terminal must not reflow: its indentation is its meaning, and
+ * wrapping it as prose destroys it.
+ */
+export function segmentsOf(text) {
+    const out = [];
+    let current = { code: false, lines: [] };
+    const flush = () => {
+        if (current.lines.length) {
+            out.push(current);
+        }
+    };
+    for (const raw of text.split('\n')) {
+        const fence = /^\s*```+\s*(\S*)/.exec(raw);
+        if (!fence) {
+            current.lines.push(raw);
+            continue;
+        }
+        flush();
+        current = current.code
+            ? { code: false, lines: [] }
+            : { code: true, title: fence[1] || undefined, lines: [] };
+    }
+    flush();
+    return out;
+}
 //# sourceMappingURL=wrap.js.map

package/dist/validate.d.ts

@@ -73,6 +73,8 @@ export interface SkillReport {
 export interface ModelReport {
     /** the alias it is declared under, or the reference itself */
     name: string;
+    /** what `name` resolves to, when it is an alias rather than a reference */
+    ref?: string;
     /** what the config declared it for */
     role: DeclaredRole;
     /** the provider it resolves to */

package/dist/validate.js

@@ -181,6 +181,7 @@ export async function validateProject(opts) {
     for (const spec of config.agents) {
         agents.push(checkAgent(root, config, spec, entry, available, record, add));
     }
+    checkReturnPaths(config, add);
     // -----------------------------------------------------------------------
     // Skills
     // -----------------------------------------------------------------------
@@ -244,7 +245,7 @@ async function askModels(targets, opts, add) {
         if (probe.check.state === 'live') {
             return;
         }
-        const where = `${report.role} "${report.name}"${report.provider ? ` (${report.provider})` : ''}`;
+        const where = named(report);
         if (probe.check.state === 'blocked') {
             const pick = report.role === 'embedding' ? '--embedding' : '--chat';
             add({
@@ -576,6 +577,75 @@ function checkAgent(root, config, spec, entry, available, record, add) {
         ownSandbox: Boolean(spec.sandbox),
     };
 }
+/**
+ * Every hand-off must be returnable.
+ *
+ * A hand-off is a one-way door: control moves to the other agent and stays
+ * there. Nothing hands it back on its own, so an agent reached by an edge that
+ * has no way home owns the conversation for the rest of the session — the next
+ * question, whatever it is about, is answered by the specialist the router sent
+ * the user to. That is not a runtime error; it is a system that quietly stops
+ * being the system that was drawn.
+ *
+ * So for every `A → B` there must be a path from B back to A. Indirect counts:
+ * `B → C → A` is a way home, which is the same as saying every hand-off edge
+ * lies on a cycle.
+ *
+ * Forks are exempt, and always will be. A branch runs, answers, and control
+ * returns to the agent that forked it — the return is the mechanism, not an
+ * edge someone has to remember to declare. An agent that wants an answer rather
+ * than to give up the conversation should fork, not hand off.
+ *
+ * A warning rather than an error: the project loads, runs, and answers. What it
+ * cannot do is come back. `--strict` is for the repository that wants that to
+ * fail the build.
+ */
+function checkReturnPaths(config, add) {
+    const known = new Set(config.agents.map((a) => a.name));
+    // Unknown names and self-hand-offs are already errors of their own; walking
+    // them here would only report the same mistake in a second vocabulary.
+    const edges = new Map(config.agents.map((a) => [
+        a.name,
+        (a.handoffs ?? []).filter((to) => to !== a.name && known.has(to)),
+    ]));
+    const reaches = (from, to) => {
+        const seen = new Set([from]);
+        const queue = [from];
+        while (queue.length) {
+            for (const next of edges.get(queue.shift()) ?? []) {
+                if (next === to) {
+                    return true;
+                }
+                if (!seen.has(next)) {
+                    seen.add(next);
+                    queue.push(next);
+                }
+            }
+        }
+        return false;
+    };
+    for (const [from, targets] of edges) {
+        for (const to of targets) {
+            if (reaches(to, from)) {
+                continue;
+            }
+            add({
+                severity: 'warning',
+                code: 'handoff.one-way',
+                where: `agents.${from}.handoffs`,
+                message: `"${to}" has no way back to "${from}": nothing it can hand off to, ` +
+                    `directly or through another agent, reaches "${from}" again. A hand-off ` +
+                    `does not return by itself, so once control moves to "${to}" it stays ` +
+                    `there — every later question in the session is answered by "${to}", ` +
+                    'whether or not it is that agent’s job',
+                fix: `add "${from}" to agents.${to}.handoffs (or to the handoffs of an agent ` +
+                    `"${to}" can reach), or — if "${from}" wants an answer rather than to give ` +
+                    `up the conversation — drop the edge and declare fork: { agents: [${to}] } ` +
+                    `on "${from}", because a branch returns on its own`,
+            });
+        }
+    }
+}
 async function checkSkills(root, config, available, record, add) {
     const declared = config.skills
         ? Array.isArray(config.skills)
@@ -1183,6 +1253,15 @@ function checkModels(root, config, keys, add, probe = false) {
             if (keys) {
                 report.credential = held.present ? 'present' : 'missing';
             }
+            // An alias is the one name the provider has never heard of, so the
+            // report says what it stands for — otherwise `main was refused`
+            // names nothing anyone can look up or retype.
+            const spec = typeof ref === 'string' ? registry.parse(ref) : ref;
+            const api = 'api' in spec && spec.api ? `/${spec.api}` : '';
+            const resolved = `${need.provider}${api}:${spec.model}`;
+            if (resolved !== name) {
+                report.ref = resolved;
+            }
         }
         catch (err) {
             add({
@@ -1208,7 +1287,7 @@ function checkModels(root, config, keys, add, probe = false) {
             add({
                 severity: 'warning',
                 code: `credential.${issue.reason}`,
-                where: `${role} "${name}" (${issue.provider})`,
+                where: named(report, issue.provider),
                 message: issue.reason === 'missing'
                     ? `nothing to authenticate with — ${issue.env} is not set, and the ` +
                         'keyring holds no key for this provider'
@@ -1257,6 +1336,12 @@ function checkModels(root, config, keys, add, probe = false) {
     }
     return { providers: registry.names(), models, targets };
 }
+/** How a finding names a model: as written, and as resolved when the two differ. */
+function named(report, provider = report.provider) {
+    return (`${report.role} "${report.name}"` +
+        (report.ref ? ` = ${report.ref}` : '') +
+        (provider ? ` (${provider})` : ''));
+}
 /** The config key a bad reference was written under. */
 function whereFor(config, role, name, usedBy) {
     if (role === 'embedding') {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.9",
+    "version": "1.1.11",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.9",
+        "@zenera/neo": "^1.1.11",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",

package/templates/editor/.github/copilot-instructions.md

@@ -307,6 +307,9 @@ wrong provider (§7.3), and any combination of knobs the vendor rejects at reque
 time, such as OpenAI reasoning on chat completions (§7.6). Both surface on the
 first call, so read §7 before writing a `models:` entry.
 
+**Caught by `zen check`, not by the loader** — a handoff with no path back
+(`handoff.one-way`, §6.3). The project runs; it just cannot return.
+
 **Comments in `agents.yaml`** — this file is the architecture diagram of the
 project, and its comments are read by whoever has to change it next. Write them
 at that level:
@@ -1086,18 +1089,20 @@ Do **not** split because:
 
 **Router + specialists.** A cheap, fast agent whose only job is classification
 and handoff. Its prompt is short, it holds few tools, and it must be forbidden
-from answering. Specialists never hand back to it.
+from answering. Every specialist hands back to it — a handoff does not return on
+its own, so without that edge the first routed question is the last one routed.
 
 ```yaml
 agents:
     - { name: intake, model: router, handoffs: [billing, technical, escalation] }
-    - { name: billing, model: balanced, skills: { allow: [refund_policy, invoicing] } }
-    - { name: technical, model: balanced, tools: [search_logs, restart_service] }
-    - { name: escalation, model: careful }
+    - { name: billing, model: balanced, handoffs: [intake], skills: { allow: [refund_policy] } }
+    - { name: technical, model: balanced, handoffs: [intake], tools: [search_logs] }
+    - { name: escalation, model: careful, handoffs: [intake] }
 ```
 
 **Pipeline.** Fixed stages, each handing to the next; only the last answers the
-user. Encode the order in `handoffs:` so a stage cannot skip ahead.
+user. Encode the order in `handoffs:` so a stage cannot skip ahead — and close
+the loop, by handing back from the last stage to the first.
 
 **Fan-out / join.** For independent parallel work — ten regions, four review
 lenses, six candidate suppliers — declare `fork:` on the agent that owns the
@@ -1113,12 +1118,39 @@ multi-agent instinct suggests.
   Write it as a routing condition: _"Applies the written peril policies to a
   claim and explains the outcome."_ — not _"The adjuster agent."_
 - Handoffs are bare name strings; there is no per-edge configuration.
-- Self-handoff is a load error. Cycles are legal but usually a bug — a router in
-  the `handoffs` of its own specialists produces ping-pong.
+- Self-handoff is a load error.
+- **Every handoff must be returnable.** For every `A → B` there must be a path
+  from `B` back to `A`. Indirect counts — `B → C → A` is a way home — so the
+  rule is that every handoff edge lies on a cycle. `zen check` warns
+  (`handoff.one-way`) on any edge that does not.
 - Handoff collapses history by policy: the receiving agent sees a selection, not
   the full transcript. Do not assume it saw a detail three turns back; if it
   matters, put it in the handoff.
 
+**Why the return edge is not optional.** A handoff is a one-way door: control
+moves and stays moved. Nothing hands it back, so an agent reached by a dead-end
+edge owns the conversation for the rest of the session — the next question,
+whatever it is about, is answered by the specialist the router sent the user to.
+The drawn architecture holds for one turn and then quietly stops being the
+architecture.
+
+**Forks are the exception, and the alternative.** A branch runs, answers, and
+control returns to the agent that forked it; the return is the mechanism, not an
+edge anyone has to declare. So there are two shapes and they are not
+interchangeable:
+
+- The other agent should **own the conversation from here** → `handoffs:`, and
+  something on the far side has to lead back.
+- This agent needs **an answer and then carries on** → `fork:`. Never a handoff:
+  a handoff spends the conversation to get the answer.
+
+But the return is **condensed**: `A → fork → B` rejoins as one tool result
+holding B's answer, so A never sees the steps B took — no tool calls, no files
+read, no intermediate reasoning. That is what makes fanning out cheap, and it is
+what to design around: whatever A will need must be _in_ the answer, so say so in
+B's prompt. Work whose value is the trace rather than the conclusion does not
+survive a fork.
+
 ### 6.4 Forking (fan-out / join)
 
 Forking is **opt-in per agent**. Without the key the agent is never offered the
@@ -1158,7 +1190,9 @@ Rules worth knowing before you write the key:
 - Nesting is capped by the run's `maxForkDepth` (2 by default), so a branch may
   fork again but not without bound.
 - Fork vs handoff: a handoff is _one_ conversation changing owner; a fork is the
-  _same_ question asked N times at once and merged.
+  _same_ question asked N times at once and merged. **A fork returns; a handoff
+  does not** — which is why a handoff needs a return path (§6.3) and a fork
+  needs nothing.
 
 Choose `context:` deliberately — the model sets it per call, so say in the
 agent's prompt which one this work wants:
@@ -1237,8 +1271,8 @@ model: balanced # fallback for agents that do not pin their own
 
 agents:
     - { name: intake, model: router, handoffs: [adjuster] }
-    - { name: adjuster, model: balanced, handoffs: [escalation] }
-    - { name: escalation, model: careful }
+    - { name: adjuster, model: balanced, handoffs: [escalation, intake] }
+    - { name: escalation, model: careful, handoffs: [intake] }
 ```
 
 ### 7.3 Shorthand
@@ -1582,7 +1616,7 @@ Before finishing any change here:
 - [ ] `agents.yaml` still loads; no unknown keys, no dangling names
 - [ ] Top-level `default:` names the entry agent explicitly
 - [ ] Every agent has a `description:` written as a routing condition
-- [ ] No self-handoff; no accidental cycle back to the router
+- [ ] No self-handoff; every handoff has a path back (`zen check` warns if not)
 - [ ] Names match `^[a-z0-9]+(?:[-_][a-z0-9]+)*$`
 - [ ] An agent expected to fan out has `fork:`, and its prompt says when to use it
 - [ ] Comments explain the design, not the runtime or the key they sit above
@@ -1660,6 +1694,7 @@ Before finishing any change here:
 | A model or embedder refuses every call     | `zen models test <ref>` — if `blocked`, `zen models pick` — §8      |
 | Answers instead of routing                 | Router prompt prohibition; check `handoffs:`                        |
 | Routes to the wrong specialist             | The target agents' `description:` fields                            |
+| Gets stuck in the agent it routed to       | The target needs a handoff back — §6.3                              |
 | Loses a detail after a handoff             | Say it in the handoff; check the collapse policy                    |
 | Works through N independent items serially | `fork:` on that agent, and a prompt line — §6.4                     |
 | Forks when the steps actually depend       | Prompt line: branches cannot see each other                         |
@@ -1689,8 +1724,10 @@ Before finishing any change here:
 - **Fixing prompts with models.** See §4.4.
 - **The chatty router.** A router that answers before handing off, because its
   prompt never forbade it.
-- **Ping-pong handoffs.** Specialists that hand back to the router, which hands
-  back to a specialist.
+- **The one-way handoff.** A specialist with no way back, so the router routes
+  once and then never sees the conversation again — §6.3.
+- **Handing off for an answer.** Wanting one lookup and spending the whole
+  conversation on it. That is a `fork:`, which returns by itself — §6.4.
 - **Forking a chain.** Branches never see each other, so a fork whose second
   branch needs the first branch's answer is a sequence wearing a fork's clothes.
 - **Installing the toolchain every run.** A prompt that begins with `apt-get

package/templates/editor/.github/prompts/new-agent.prompt.md

@@ -29,8 +29,11 @@ If it is warranted:
 3. Add the `agents.yaml` entry. `description:` is written **for the model** — it
    is the whole of what a sibling sees when deciding to hand off. Grant the
    narrowest `tools:` the job needs.
-4. Wire the handoffs in both directions only if both directions are real.
-   Specialists handing back to a router is ping-pong; prefer terminating.
+4. Wire the return edge. A handoff does not come back on its own, so every
+   `A → B` needs a path from B back to A — directly, or through another agent.
+   `zen check` warns on an edge that has none. If what this agent really wants
+   is an _answer_ rather than to give up the conversation, declare `fork:`
+   instead: a branch returns by itself.
 5. Add a one-line comment above the entry saying why this agent exists — its
    job or its tier, not what the keys mean.