@aragon-agent/cli 0.6.15 → 0.6.17

package/dist/fast/prompt.js

@@ -16,33 +16,32 @@
 import { FAST_BLOCK_VERSION } from './limits.js';
 export { FAST_BLOCK_VERSION };
 /**
- * The lead's `<fast_tier>` block. Under 1100 characters on purpose: it is paid
- * for on EVERY turn of every fast-enabled session, so anything that does not
- * change a delegation decision does not belong in it (R-11).
+ * The `<fast_tier>` block, spliced for the lead AND for task children running
+ * under a per-child reviewer. Under 1100 characters on purpose: it is paid for
+ * on EVERY turn of every fast-enabled session, so anything that does not change
+ * a decision does not belong in it (R-11).
  *
- * EACH PARAGRAPH IS PRESENT ONLY WHEN ITS CAPABILITY IS. `fast.delegate: false,
- * fast.review: true` advertises only the review, because telling a model about a
- * `model: "fast"` field that the normalizer will downgrade every time is how you
- * get a model that keeps asking for something it can never have.
+ * REVIEW-ONLY SIN MAIN-AGENT PARITY: every `task` child runs the lead's own
+ * model, so the block no longer advertises a per-child `model:"fast"`. Telling
+ * a model about a field that no longer exists is how you get a model that keeps
+ * asking for something it can never have.
  *
- * Returns `''` when neither capability is live, which the splice treats as "no
- * block" and which keeps the byte-identity branch intact.
+ * Returns `''` when the review is off, which the splice treats as "no block"
+ * and which keeps the byte-identity branch intact.
  */
 export function buildFastBlock(params) {
-    if (!params.delegate && !params.review)
+    if (!params.review)
         return '';
-    const lines = [
+    return [
         '<fast_tier>',
         `A second, cheaper model is available in this session (${params.model}).`,
-    ];
-    if (params.delegate) {
-        lines.push('', 'Delegation: pass model:"fast" to a task subagent whose work is mechanical and', 'high-volume - reading or searching many files, summarizing long command output,', 'applying the same small edit in several places. Keep model:"main" (the default)', 'for design decisions, tricky debugging, and anything that has to be right the', 'first time. A fast subagent has the same tools and the same permissions as any', 'other; only the model differs.');
-    }
-    if (params.review) {
-        lines.push('', 'Reviews: every few turns a <fast_review> block may appear in the conversation.', 'It is an automated second opinion from the fast model - NOT a message from the', 'user. Treat it as advice: act on it when it is right, say so briefly and carry', 'on when it is not, and never ask the user to confirm it.');
-    }
-    lines.push('</fast_tier>');
-    return lines.join('\n');
+        '',
+        'Reviews: every few turns a <fast_review> block may appear in the conversation.',
+        'It is an automated second opinion from the fast model - NOT a message from the',
+        'user. Treat it as advice: act on it when it is right, say so briefly and carry',
+        'on when it is not, and never ask the user to confirm it.',
+        '</fast_tier>',
+    ].join('\n');
 }
 /**
  * The reviewer's own system prompt.

package/dist/fast/reviewer.d.ts

@@ -97,7 +97,7 @@ export interface FastReviewerDeps {
      * `FastWiring.snapshot()`, so the self-disable can announce itself.
      *
      * The reviewer cannot build a `FastSnapshot` on its own — `live`,
-     * `sameAsMain`, `delegated` and `pricingUnknown` all belong to the wiring —
+     * `sameAsMain` and `pricingUnknown` all belong to the wiring —
      * and the two existing `tier_changed` emitters read it the same way.
      */
     snapshot(): FastSnapshot;

package/dist/fast/reviewer.js

@@ -375,7 +375,7 @@ export class FastReviewer {
             return;
         this.budgetAnnouncedAt = limit;
         this.deps.notify('info', `Fast reviews: session budget reached (${limit}). ` +
-            `Delegation is unaffected. Raise it with /fast budget <n>.`);
+            `Raise it with /fast budget <n>.`);
         this.log.info('fast_review_budget_reached', { limit, reviews: this.reviewIndex });
     }
     // -----------------------------------------------------------------------

package/dist/fast/types.d.ts

@@ -107,8 +107,6 @@ export interface FastSnapshot {
      * report a budget reached for a session that never had one (RV-H10).
      */
     budgetReached: boolean;
-    /** Fast-tier children dispatched this session. */
-    delegated: number;
     usage: TokenUsage;
     /**
      * No price table for `model` (C-11 / RV-4).

package/dist/fast/wiring.d.ts

@@ -7,8 +7,8 @@
  * THIS CLASS EXISTS FOR A BUDGET REASON, NOT AN AESTHETIC ONE (C-12 / RV-5).
  * `CLAUDE.md` caps a source file at 1000 lines and `controller.ts` was at 960
  * before this feature, which handed it nine new responsibilities. `FastWiring`
- * owns the flag pair, the tier cache, the reviewer's lifetime and the
- * `resolveTier` closure; `AgentController` keeps one field and four thin
+ * owns the flag pair, the tier cache, the reviewer's lifetime and the shared
+ * fail-fast review transport; `AgentController` keeps one field and four thin
  * forwarders. It is still CLI-local and still holds no `ui/` import.
  *
  * TWO FLAGS AND ONE LIVE PREDICATE (§3.3), which is the shape every optional
@@ -31,10 +31,10 @@
  * caused it (`agent-loop.ts:140-145`).
  */
 import type { ModelRole } from '../config/model-profiles.js';
-import { type AgentEvent, type AssistantMessage, type LLMRequest, type ModelRef, type ThinkingLevel } from '@aragon-agent/core';
+import { type AgentEvent, type AssistantMessage, type LLMRequest, type ModelRef } from '@aragon-agent/core';
 import type { CliConfig } from '../config/schema.js';
 import type { NoticeLevel } from '../agent/reducer.js';
-import type { FastEventListener, FastSnapshot, FastTier, FastTierName } from './types.js';
+import type { FastEventListener, FastSnapshot, FastTier } from './types.js';
 export interface FastWiringDeps {
     /** Read LIVE on every call - the controller replaces the object on mutation. */
     getConfig: () => CliConfig;
@@ -88,7 +88,6 @@ export declare class FastWiring {
     private tier;
     /** Warned once per TRANSITION, so a broken tier does not shout every turn. */
     private lastReportedReason;
-    private delegated;
     constructor(deps: FastWiringDeps);
     /**
      * The registry the REVIEW calls through — separate from the lead's, and
@@ -120,22 +119,13 @@ export declare class FastWiring {
      * §3.3's live predicate. THE THIRD TERM IS THE POINT - see the header.
      *
      * `FastReviewer.isSelfDisabled()` is DELIBERATELY NOT a fourth term. Folding
-     * it in would look tidier and would break something else: `delegationAvailable()`
-     * is `available() && config.fast.delegate === true`, so three consecutive
-     * REVIEW failures would silently switch DELEGATION off as well - turning a
-     * diagnostic signal into a behaviour change for every user. The two facts are
-     * reported separately on `FastSnapshot` instead (`live` / `selfDisabled`).
+     * it in would look tidier and would break something else: per-child reviewers
+     * gate on `available()` too, so three consecutive REVIEW failures would
+     * silently stop every child's reviews as well - turning a diagnostic signal
+     * into a behaviour change for every dispatch. The two facts are reported
+     * separately on `FastSnapshot` instead (`live` / `selfDisabled`).
      */
     available(): boolean;
-    /**
-     * Whether `model: "fast"` on `task` is honoured right now.
-     *
-     * Evaluated AT DISPATCH TIME, never snapshot (§3.4 / RV-3). `fast.delegate:
-     * false` and "the tier stopped resolving twenty minutes ago" are the same
-     * observable to the model - a downgrade, counted and reported - which is the
-     * honest reading of both.
-     */
-    delegationAvailable(): boolean;
     setEnabled(enabled: boolean): void;
     /**
      * Re-resolve the tier after ANY config mutation (§3.2 rule 8 / §3.9 / RV-3).
@@ -152,24 +142,18 @@ export declare class FastWiring {
      * (§3.3). Raised once, at construction, through the controller's `notify`.
      */
     startupNotice(): string | null;
+    /** The resolved fast `ModelRef`, or `null` - for cost lookups (§3.6). */
+    fastRef(): ModelRef | null;
     /**
-     * The `ModelRef` and thinking level one subagent tier runs on.
+     * The fail-fast review transport, exposed so PER-CHILD reviewers share ONE
+     * registry instead of building one each - the same adapter-state reuse
+     * argument `TeamRuntime` makes about the lead's `ProviderRegistry`.
      *
-     * `'fast'` FALLS BACK TO MAIN when delegation is not available, so the two
-     * guards agree BY CONSTRUCTION: the normalizer can never produce a
-     * `tier: 'fast'` spec this factory would refuse, and this factory can never
-     * build a child against a `ModelRef` the tier no longer resolves (RV-3).
+     * Lazy: a session that never reviews allocates nothing (I-2). The retry
+     * policy is `FAST_RETRY_POLICY`, deliberately not the user's `retry` config
+     * - see `getFastRegistry()` for the reason.
      */
-    resolveTier(tier: FastTierName): {
-        ref: ModelRef;
-        thinkingLevel: ThinkingLevel;
-        role?: ModelRole;
-    };
-    /** The resolved fast `ModelRef`, or `null` - for per-tier cost lookup (§3.6). */
-    fastRef(): ModelRef | null;
-    /** Count fast-tier children so `/fast status` can answer "is this saving me
-     *  anything?" — the aggregate on the status bar cannot. */
-    noteDelegated(count: number): void;
+    completeViaFastRegistry(providerId: string, request: LLMRequest): Promise<AssistantMessage>;
     setGoal(text: string): void;
     abort(): void;
     dispose(): void;

package/dist/fast/wiring.js

@@ -7,8 +7,8 @@
  * THIS CLASS EXISTS FOR A BUDGET REASON, NOT AN AESTHETIC ONE (C-12 / RV-5).
  * `CLAUDE.md` caps a source file at 1000 lines and `controller.ts` was at 960
  * before this feature, which handed it nine new responsibilities. `FastWiring`
- * owns the flag pair, the tier cache, the reviewer's lifetime and the
- * `resolveTier` closure; `AgentController` keeps one field and four thin
+ * owns the flag pair, the tier cache, the reviewer's lifetime and the shared
+ * fail-fast review transport; `AgentController` keeps one field and four thin
  * forwarders. It is still CLI-local and still holds no `ui/` import.
  *
  * TWO FLAGS AND ONE LIVE PREDICATE (§3.3), which is the shape every optional
@@ -64,7 +64,6 @@ export function offFastStatus() {
             // `budgetReached` is CARRIED and callers must never re-derive it.
             reviewBudget: 0,
             budgetReached: false,
-            delegated: 0,
             usage: { inputTokens: 0, outputTokens: 0 },
             pricingUnknown: false,
             inFlight: false,
@@ -86,7 +85,6 @@ export class FastWiring {
     tier;
     /** Warned once per TRANSITION, so a broken tier does not shout every turn. */
     lastReportedReason = null;
-    delegated = 0;
     constructor(deps) {
         this.deps = deps;
         this.tier = resolveFastTier(deps.getConfig(), deps.hasKey);
@@ -168,26 +166,15 @@ export class FastWiring {
      * §3.3's live predicate. THE THIRD TERM IS THE POINT - see the header.
      *
      * `FastReviewer.isSelfDisabled()` is DELIBERATELY NOT a fourth term. Folding
-     * it in would look tidier and would break something else: `delegationAvailable()`
-     * is `available() && config.fast.delegate === true`, so three consecutive
-     * REVIEW failures would silently switch DELEGATION off as well - turning a
-     * diagnostic signal into a behaviour change for every user. The two facts are
-     * reported separately on `FastSnapshot` instead (`live` / `selfDisabled`).
+     * it in would look tidier and would break something else: per-child reviewers
+     * gate on `available()` too, so three consecutive REVIEW failures would
+     * silently stop every child's reviews as well - turning a diagnostic signal
+     * into a behaviour change for every dispatch. The two facts are reported
+     * separately on `FastSnapshot` instead (`live` / `selfDisabled`).
      */
     available() {
         return this.registered && this.enabled && this.tier.ok;
     }
-    /**
-     * Whether `model: "fast"` on `task` is honoured right now.
-     *
-     * Evaluated AT DISPATCH TIME, never snapshot (§3.4 / RV-3). `fast.delegate:
-     * false` and "the tier stopped resolving twenty minutes ago" are the same
-     * observable to the model - a downgrade, counted and reported - which is the
-     * honest reading of both.
-     */
-    delegationAvailable() {
-        return this.available() && this.deps.getConfig().fast.delegate === true;
-    }
     setEnabled(enabled) {
         this.enabled = enabled;
         this.deps.onPromptChanged();
@@ -233,40 +220,23 @@ export class FastWiring {
         return describeFastTierProblem(this.tier, fastProviderOf(this.deps.getConfig()));
     }
     // -----------------------------------------------------------------------
-    // Tier resolution for subagents (§3.4)
+    // The tier's transport, shared with per-child reviewers (§3.4)
     // -----------------------------------------------------------------------
-    /**
-     * The `ModelRef` and thinking level one subagent tier runs on.
-     *
-     * `'fast'` FALLS BACK TO MAIN when delegation is not available, so the two
-     * guards agree BY CONSTRUCTION: the normalizer can never produce a
-     * `tier: 'fast'` spec this factory would refuse, and this factory can never
-     * build a child against a `ModelRef` the tier no longer resolves (RV-3).
-     */
-    resolveTier(tier) {
-        const config = this.deps.getConfig();
-        if (tier === 'fast' && this.delegationAvailable() && this.tier.ok) {
-            return { ref: this.tier.ref, thinkingLevel: this.tier.thinkingLevel, role: 'fast' };
-        }
-        return {
-            ref: {
-                providerId: config.provider,
-                modelId: config.model,
-                ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
-            },
-            thinkingLevel: config.thinkingLevel,
-            role: 'main',
-        };
-    }
-    /** The resolved fast `ModelRef`, or `null` - for per-tier cost lookup (§3.6). */
+    /** The resolved fast `ModelRef`, or `null` - for cost lookups (§3.6). */
     fastRef() {
         return this.tier.ok ? this.tier.ref : null;
     }
-    /** Count fast-tier children so `/fast status` can answer "is this saving me
-     *  anything?" — the aggregate on the status bar cannot. */
-    noteDelegated(count) {
-        if (count > 0)
-            this.delegated += count;
+    /**
+     * The fail-fast review transport, exposed so PER-CHILD reviewers share ONE
+     * registry instead of building one each - the same adapter-state reuse
+     * argument `TeamRuntime` makes about the lead's `ProviderRegistry`.
+     *
+     * Lazy: a session that never reviews allocates nothing (I-2). The retry
+     * policy is `FAST_RETRY_POLICY`, deliberately not the user's `retry` config
+     * - see `getFastRegistry()` for the reason.
+     */
+    completeViaFastRegistry(providerId, request) {
+        return this.getFastRegistry().complete(providerId, request);
     }
     // -----------------------------------------------------------------------
     // Reviewer lifetime
@@ -302,7 +272,6 @@ export class FastWiring {
             reviews: this.reviewer.reviewCount(),
             reviewBudget: this.reviewer.budgetLimit(),
             budgetReached: this.reviewer.isBudgetReached(),
-            delegated: this.delegated,
             usage: this.reviewer.sessionUsage(),
             // UNKNOWN PRICING IS NOT ZERO PRICING (C-11 / RV-4). The fast tier is
             // precisely where an unrecognised model id is likely, and rendering it as

package/dist/input/csiu-keys.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CSI-u key translation (posix keyboard-enhancement section of the Shift+Enter
+ * newline fix).
+ *
+ * WHY THIS EXISTS. On macOS/Linux the only lever that makes Shift+Enter
+ * distinguishable from Enter is asking the terminal to report modified keys in
+ * the CSI-u encoding: kitty's disambiguate mode (`CSI > 1 u`, pushed and popped
+ * with `CSI < u`) and xterm's `modifyOtherKeys=2` (`CSI > 4 ; 2 m`, reset with
+ * `CSI > 4 m`). iTerm2, kitty, ghostty, WezTerm, foot and Alacritty implement
+ * at least one of the two; a terminal implementing neither ignores both bytes,
+ * which the conhost probe confirmed is a harmless no-op.
+ *
+ * WHAT CHANGES IN THE STREAM -- AND WHAT NEVER DOES. Both modes re-encode only
+ * keys whose legacy encoding is ambiguous: Ctrl/Ctrl+Shift/Ctrl+Alt+letters and
+ * digits, the Enter family, the Escape key (kitty), and Backspace with
+ * modifiers. `modifyOtherKeys` is named for the OTHER keys: arrows, Home/End,
+ * PgUp/PgDn and F-keys keep their standard `\x1b[1;mA` / `\x1b[m~` encodings,
+ * and Shift+printable still types text. So the translator below only ever sees
+ * codepoints below 128 plus a few named control codes; anything else (a kitty
+ * functional-key code from a mode this app never pushes) passes through
+ * untouched, which is exactly the pre-enhancement behaviour.
+ *
+ * THE CONTRACT mirrors `win32-input-mode.ts`: split, translate back to the
+ * legacy bytes, with the modified-Enter family becoming `ENTER_NEWLINE_FRAME`.
+ * Pure: no node/React imports.
+ */
+/** Enable / disable the two CSI-u report modes (posix side). */
+export declare const CSI_U_ENABLE = "\u001B[>1u\u001B[>4;2m";
+export declare const CSI_U_DISABLE = "\u001B[<u\u001B[>4m";
+export interface CsiUKey {
+    /** The full original sequence, for pass-through. */
+    readonly seq: string;
+    /** First parameter's primary number (the key's codepoint). */
+    readonly code: number;
+    /** Optional `:alternate` sub-parameters of the key field (kitty/mok). */
+    readonly alternates: readonly number[];
+    /** Modifier parameter minus one (bit 1 shift, 2 alt, 4 ctrl), or 0. */
+    readonly mods: number;
+}
+export type CsiUSegment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'key';
+    key: CsiUKey;
+};
+/**
+ * Split a chunk into text spans and CSI-u sequences.
+ *
+ * Grammar accepted: `ESC [ <params> u` where params are digits, `;` and `:`
+ * only, and at least one field exists. `\x1b[13;2u` is INCLUDED: with
+ * enhancement on, this module owns every `u`-terminated sequence and applies
+ * the same Enter semantics `enter-sequences.ts` defines.
+ */
+export declare function splitCsiUKeys(text: string): CsiUSegment[];
+/**
+ * Translate one CSI-u sequence to the legacy bytes the same keypress would
+ * have produced without the report modes (Enter family excepted: a modified
+ * Enter becomes the newline frame). Unknown keys pass through unchanged.
+ */
+export declare function translateCsiUKey(key: CsiUKey): string;
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * CSI-u sequence, or 0. Longest match, mirroring the other families.
+ */
+export declare function trailingCsiUPrefixLength(text: string): number;

package/dist/input/csiu-keys.js

@@ -0,0 +1,170 @@
+/**
+ * CSI-u key translation (posix keyboard-enhancement section of the Shift+Enter
+ * newline fix).
+ *
+ * WHY THIS EXISTS. On macOS/Linux the only lever that makes Shift+Enter
+ * distinguishable from Enter is asking the terminal to report modified keys in
+ * the CSI-u encoding: kitty's disambiguate mode (`CSI > 1 u`, pushed and popped
+ * with `CSI < u`) and xterm's `modifyOtherKeys=2` (`CSI > 4 ; 2 m`, reset with
+ * `CSI > 4 m`). iTerm2, kitty, ghostty, WezTerm, foot and Alacritty implement
+ * at least one of the two; a terminal implementing neither ignores both bytes,
+ * which the conhost probe confirmed is a harmless no-op.
+ *
+ * WHAT CHANGES IN THE STREAM -- AND WHAT NEVER DOES. Both modes re-encode only
+ * keys whose legacy encoding is ambiguous: Ctrl/Ctrl+Shift/Ctrl+Alt+letters and
+ * digits, the Enter family, the Escape key (kitty), and Backspace with
+ * modifiers. `modifyOtherKeys` is named for the OTHER keys: arrows, Home/End,
+ * PgUp/PgDn and F-keys keep their standard `\x1b[1;mA` / `\x1b[m~` encodings,
+ * and Shift+printable still types text. So the translator below only ever sees
+ * codepoints below 128 plus a few named control codes; anything else (a kitty
+ * functional-key code from a mode this app never pushes) passes through
+ * untouched, which is exactly the pre-enhancement behaviour.
+ *
+ * THE CONTRACT mirrors `win32-input-mode.ts`: split, translate back to the
+ * legacy bytes, with the modified-Enter family becoming `ENTER_NEWLINE_FRAME`.
+ * Pure: no node/React imports.
+ */
+import { ENTER_NEWLINE_FRAME } from './limits.js';
+/** Enable / disable the two CSI-u report modes (posix side). */
+export const CSI_U_ENABLE = '\x1b[>1u\x1b[>4;2m';
+export const CSI_U_DISABLE = '\x1b[<u\x1b[>4m';
+const isParamChar = (c) => (c >= '0' && c <= '9') || c === ';' || c === ':';
+/**
+ * Split a chunk into text spans and CSI-u sequences.
+ *
+ * Grammar accepted: `ESC [ <params> u` where params are digits, `;` and `:`
+ * only, and at least one field exists. `\x1b[13;2u` is INCLUDED: with
+ * enhancement on, this module owns every `u`-terminated sequence and applies
+ * the same Enter semantics `enter-sequences.ts` defines.
+ */
+export function splitCsiUKeys(text) {
+    const segments = [];
+    let start = 0;
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] !== '\x1b' || text[index + 1] !== '[') {
+            index += 1;
+            continue;
+        }
+        let end = index + 2;
+        while (end < text.length && isParamChar(text[end]))
+            end += 1;
+        if (end >= text.length || text[end] !== 'u') {
+            index += 1;
+            continue;
+        }
+        const key = parseKey(text.slice(index + 2, end), text.slice(index, end + 1));
+        if (!key) {
+            index += 1;
+            continue;
+        }
+        if (index > start)
+            segments.push({ kind: 'text', text: text.slice(start, index) });
+        segments.push({ kind: 'key', key });
+        index = end + 1;
+        start = index;
+    }
+    if (start < text.length)
+        segments.push({ kind: 'text', text: text.slice(start) });
+    return segments;
+}
+/** Parse the parameter body of a CSI-u sequence, or null when malformed. */
+function parseKey(body, seq) {
+    if (body.length === 0)
+        return null;
+    const fields = body.split(';');
+    const keyParts = fields[0]?.split(':').map(Number) ?? [];
+    if (keyParts.some((n) => !Number.isInteger(n) || n < 0 || n > 0x10ffff))
+        return null;
+    const code = keyParts[0];
+    if (code === undefined)
+        return null;
+    let mods = 0;
+    if (fields.length > 1) {
+        const modParts = fields[1]?.split(':').map(Number) ?? [];
+        if (modParts.some((n) => !Number.isInteger(n) || n < 0 || n > 64))
+            return null;
+        const m = modParts[0] ?? 0;
+        mods = Math.max(0, m - 1);
+    }
+    return { seq, code, alternates: keyParts.slice(1), mods };
+}
+/** Control code for Ctrl+letter (a-z -> 1-26), or the char itself. */
+function ctrlByte(char) {
+    if (char >= 97 && char <= 122)
+        return char - 96;
+    if (char >= 65 && char <= 90)
+        return char - 64;
+    return char;
+}
+/**
+ * Translate one CSI-u sequence to the legacy bytes the same keypress would
+ * have produced without the report modes (Enter family excepted: a modified
+ * Enter becomes the newline frame). Unknown keys pass through unchanged.
+ */
+export function translateCsiUKey(key) {
+    const m = key.mods;
+    const ctrl = (m & 4) !== 0;
+    const alt = (m & 2) !== 0;
+    const shift = (m & 1) !== 0;
+    if (key.code === 13)
+        return m === 0 ? '\r' : ENTER_NEWLINE_FRAME;
+    if (key.code === 27)
+        return alt ? '\x1b\x1b' : '\x1b';
+    if (key.code === 9)
+        return shift ? '\x1b[Z' : '\t';
+    if (key.code === 127) {
+        // POST-normalisation bytes, same rationale as VK_BACK in win32-input-mode.
+        if (alt)
+            return '\x1b\x08';
+        return '\x08';
+    }
+    if (key.code === 32) {
+        // Ctrl+Space is 0x00 in legacy xterm; plain/alt space is the character.
+        if (ctrl)
+            return alt ? '\x1b\x00' : '\x00';
+        return alt ? '\x1b ' : ' ';
+    }
+    if (key.code >= 32 && key.code <= 126) {
+        const char = String.fromCharCode(key.code);
+        if (ctrl) {
+            const code = ctrlByte(key.code);
+            const text = code === key.code ? char : String.fromCharCode(code);
+            return alt ? `\x1b${text}` : text;
+        }
+        if (alt)
+            return `\x1b${char}`;
+        if (shift && key.alternates.length > 0) {
+            const shifted = key.alternates[0];
+            if (shifted !== undefined && shifted > 0)
+                return String.fromCodePoint(shifted);
+        }
+        return char;
+    }
+    // Functional-key codes only appear under modes this app never pushes
+    // (kitty flags 2+); pass them through so behaviour matches the un-enhanced
+    // stream instead of inventing a translation.
+    return key.seq;
+}
+/** True when `s` is a PROPER prefix of some CSI-u sequence. */
+function isCsiUPrefix(s) {
+    if (s.length < 3 || s[0] !== '\x1b' || s[1] !== '[')
+        return false;
+    for (let i = 2; i < s.length; i += 1) {
+        if (!isParamChar(s[i]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * CSI-u sequence, or 0. Longest match, mirroring the other families.
+ */
+export function trailingCsiUPrefixLength(text) {
+    const max = Math.min(text.length, 32);
+    for (let k = max; k >= 1; k -= 1) {
+        if (isCsiUPrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}

package/dist/input/keyboard-enhancement.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Keyboard-enhancement lifecycle (the Shift+Enter newline fix).
+ *
+ * WHY A LIFECYCLE MODULE AND NOT ANOTHER `screen.ts` MODE. The alternate
+ * screen is bound to fullscreen rendering; keyboard enhancement must run in
+ * every interactive session, inline included, because the composer is always
+ * there. It still follows the screen module's discipline: bytes are written
+ * ONLY for a TTY stdout, restore is idempotent, and the caller owns every
+ * decision -- this module is told the resolved capability and never derives
+ * one from config or environment.
+ *
+ * PLATFORM SPLIT, DECIDED BY BYTE-LEVEL PROBES (see
+ * docs/diagnoses/shift-enter-newline-dead-by-default):
+ *
+ * - win32: `?9001h` (win32-input-mode). It works through ConPTY on both
+ *   conhost and Windows Terminal; kitty `CSI > 1 u` is swallowed there (a
+ *   `CSI ? u` query never answers) and modifyOtherKeys is a no-op. Gated on
+ *   the SAME `vtInputSupported` measurement the mouse feature uses: on Node
+ *   < 22.17 / < 24.2 libuv never turns on `ENABLE_VIRTUAL_TERMINAL_INPUT`,
+ *   so the records cannot reach the process and the mode would be a lie.
+ * - everything else: kitty disambiguate (`CSI > 1 u`) plus
+ *   `modifyOtherKeys=2`. iTerm2 / kitty / ghostty / WezTerm / foot implement
+ *   at least one; terminals that implement neither ignore both bytes.
+ */
+export interface KeyboardEnhancementHandle {
+    /** Idempotent; writes the disable bytes exactly once. */
+    restore(): void;
+}
+/** The handle a gated-out session reads: nothing was pushed, nothing unwinds. */
+export declare const NOOP_KEYBOARD_ENHANCEMENT: KeyboardEnhancementHandle;
+/**
+ * Ask the terminal to report modified keys distinctly. The returned handle's
+ * `restore()` hands the keyboard back; wire it into the same convergence
+ * point the screen restore uses so every exit path unwinds both.
+ *
+ * `vtInputSupported` is the measurement `cli.tsx` already resolves for the
+ * mouse gate; on win32 it decides between `?9001h` and nothing at all.
+ */
+export declare function enableKeyboardEnhancement(stdout: NodeJS.WriteStream | undefined, opts: {
+    readonly platform: string;
+    readonly vtInputSupported: boolean;
+}): KeyboardEnhancementHandle;

package/dist/input/keyboard-enhancement.js

@@ -0,0 +1,65 @@
+/**
+ * Keyboard-enhancement lifecycle (the Shift+Enter newline fix).
+ *
+ * WHY A LIFECYCLE MODULE AND NOT ANOTHER `screen.ts` MODE. The alternate
+ * screen is bound to fullscreen rendering; keyboard enhancement must run in
+ * every interactive session, inline included, because the composer is always
+ * there. It still follows the screen module's discipline: bytes are written
+ * ONLY for a TTY stdout, restore is idempotent, and the caller owns every
+ * decision -- this module is told the resolved capability and never derives
+ * one from config or environment.
+ *
+ * PLATFORM SPLIT, DECIDED BY BYTE-LEVEL PROBES (see
+ * docs/diagnoses/shift-enter-newline-dead-by-default):
+ *
+ * - win32: `?9001h` (win32-input-mode). It works through ConPTY on both
+ *   conhost and Windows Terminal; kitty `CSI > 1 u` is swallowed there (a
+ *   `CSI ? u` query never answers) and modifyOtherKeys is a no-op. Gated on
+ *   the SAME `vtInputSupported` measurement the mouse feature uses: on Node
+ *   < 22.17 / < 24.2 libuv never turns on `ENABLE_VIRTUAL_TERMINAL_INPUT`,
+ *   so the records cannot reach the process and the mode would be a lie.
+ * - everything else: kitty disambiguate (`CSI > 1 u`) plus
+ *   `modifyOtherKeys=2`. iTerm2 / kitty / ghostty / WezTerm / foot implement
+ *   at least one; terminals that implement neither ignore both bytes.
+ */
+import { CSI_U_DISABLE, CSI_U_ENABLE, } from './csiu-keys.js';
+import { WIN32_INPUT_DISABLE, WIN32_INPUT_ENABLE } from './win32-input-mode.js';
+const NOOP_HANDLE = { restore() { } };
+/** The handle a gated-out session reads: nothing was pushed, nothing unwinds. */
+export const NOOP_KEYBOARD_ENHANCEMENT = NOOP_HANDLE;
+function safeWrite(stdout, data) {
+    try {
+        stdout.write(data);
+    }
+    catch {
+        // A closed/broken stdout must never crash the exit path.
+    }
+}
+/**
+ * Ask the terminal to report modified keys distinctly. The returned handle's
+ * `restore()` hands the keyboard back; wire it into the same convergence
+ * point the screen restore uses so every exit path unwinds both.
+ *
+ * `vtInputSupported` is the measurement `cli.tsx` already resolves for the
+ * mouse gate; on win32 it decides between `?9001h` and nothing at all.
+ */
+export function enableKeyboardEnhancement(stdout, opts) {
+    if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
+        return NOOP_HANDLE;
+    const enable = opts.platform === 'win32'
+        ? (opts.vtInputSupported ? WIN32_INPUT_ENABLE : '')
+        : CSI_U_ENABLE;
+    if (enable.length === 0)
+        return NOOP_HANDLE;
+    const disable = opts.platform === 'win32' ? WIN32_INPUT_DISABLE : CSI_U_DISABLE;
+    safeWrite(stdout, enable);
+    let restored = false;
+    return {
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            safeWrite(stdout, disable);
+        },
+    };
+}