@north-light/crouter 0.3.163 → 0.3.165

package/dist/core/command-plugins/{adapter.js → transport/exec-invoke.js}

@@ -8,9 +8,9 @@
 // environment and owns its own time budget (no crtr timeout) — this is a trust
 // boundary, not a sandbox (installed code can already read the caller's files).
 import { spawnSync } from 'node:child_process';
-import { CrtrError } from '../errors.js';
-import { diag } from '../io.js';
-import { ExitCode } from '../../types.js';
+import { CrtrError } from '../../errors.js';
+import { diag } from '../../io.js';
+import { ExitCode } from '../../../types.js';
 const MAX_STDOUT = 10 * 1024 * 1024; // 10 MiB hard cap on plugin stdout.
 const RESERVED_CODES = new Set(['internal', 'unknown_path', 'command_collision', 'plugin_protocol_error']);
 // Strict snake_case: no leading/trailing underscore, no consecutive underscores.
@@ -18,7 +18,7 @@ const SNAKE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
 const NEXT = 'Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plugin.';
 /** Validates a result object against declared output field descriptors.
  *  Returns null if valid; otherwise returns a { field, receivedType } error.
- *  Transport-neutral: used by both command-plugin and configured-CLI adapters. */
+ *  Transport-neutral: used by exec and HTTP transport adapters. */
 export function validateDeclaredResult(output, result) {
     for (const f of output) {
         const present = Object.prototype.hasOwnProperty.call(result, f.name) && result[f.name] !== undefined && result[f.name] !== null;

package/dist/core/{configured-clis/fetch.d.ts → command-plugins/transport/http-fetch.d.ts}

@@ -1,4 +1,5 @@
-import type { ConfiguredCliRegistration } from './registration.js';
+import type { HttpPluginFetchTarget } from '../endpoint.js';
+import type { HttpPluginManifestStore } from '../store.js';
 /** Result of a successful manifest fetch. */
 export interface FetchSuccess {
     status: 200;
@@ -11,10 +12,10 @@ export interface FetchFailure {
     message: string;
 }
 /**
- * Fetch a configured CLI manifest from the registered endpoint.
+ * Fetch a HTTP-transport plugin manifest from the registered endpoint.
  *
  * Implements the core authenticated GET primitive for T0/T2/T4 fetches:
- * - Reads bearer token from `authEnvVar` env var at invocation time
+ * - Reads bearer token from `authEnv` env var at invocation time
  * - Fails with `auth_env_missing` USAGE before network if env var is named but empty
  * - Performs one GET request with `Accept: application/json` header
  * - Attaches `Authorization: Bearer <token>` header when auth var is configured
@@ -28,24 +29,14 @@ export interface FetchFailure {
  *
  * No retries, no conditional request (ETag/If-None-Match), no 304 handling.
  */
-export declare function fetchConfiguredCliManifest(registration: ConfiguredCliRegistration): Promise<FetchResult>;
+export declare function fetchHttpPluginManifest(registration: HttpPluginFetchTarget): Promise<FetchResult>;
 /**
  * Explicit refresh: unconditional fetch and replace stored manifest.
  *
- * Called when user runs `crtr pkg cli refresh <name>`. Always fetches
- * regardless of cache state, and replaces stored manifest on success.
- * On failure, preserves existing cache and throws CrtrError.
+ * Called when user runs `crtr pkg plugin update <name>`. Always fetches
+ * regardless of stored-manifest state, and replaces it on success.
+ * On failure, preserves existing manifest bytes and throws CrtrError.
  *
  * Returns the raw manifest bytes on success.
  */
-export declare function refreshConfiguredCli(registration: ConfiguredCliRegistration): Promise<Uint8Array>;
-/**
- * Register-time fetch: fetch and store manifest during registration.
- *
- * Called when user runs `crtr pkg cli register`. Performs one authenticated
- * GET and stores exact bytes. On failure, preserves any prior cached manifest
- * and returns the error (does not throw).
- *
- * Returns a discriminated result: success with bytes, or typed failure.
- */
-export declare function registerFetchConfiguredCli(registration: ConfiguredCliRegistration): Promise<FetchSuccess | FetchFailure>;
+export declare function refreshHttpPlugin(target: HttpPluginFetchTarget, store: HttpPluginManifestStore): Promise<Uint8Array>;

package/dist/core/{configured-clis/fetch.js → command-plugins/transport/http-fetch.js}

@@ -1,16 +1,16 @@
 import { URL } from 'node:url';
 import { request as httpsRequest } from 'node:https';
 import { request as httpRequest } from 'node:http';
-import { writeConfiguredCliCacheManifest } from './cache.js';
-import { general, network, usage } from '../errors.js';
+import { writeHttpPluginManifest } from '../store.js';
+import { general, network, usage } from '../../errors.js';
 // ---------------------------------------------------------------------------
 // Core fetch primitive
 // ---------------------------------------------------------------------------
 /**
- * Fetch a configured CLI manifest from the registered endpoint.
+ * Fetch a HTTP-transport plugin manifest from the registered endpoint.
  *
  * Implements the core authenticated GET primitive for T0/T2/T4 fetches:
- * - Reads bearer token from `authEnvVar` env var at invocation time
+ * - Reads bearer token from `authEnv` env var at invocation time
  * - Fails with `auth_env_missing` USAGE before network if env var is named but empty
  * - Performs one GET request with `Accept: application/json` header
  * - Attaches `Authorization: Bearer <token>` header when auth var is configured
@@ -24,15 +24,15 @@ import { general, network, usage } from '../errors.js';
  *
  * No retries, no conditional request (ETag/If-None-Match), no 304 handling.
  */
-export async function fetchConfiguredCliManifest(registration) {
+export async function fetchHttpPluginManifest(registration) {
     // Check auth env var and fail before network if named but empty
     let token;
-    if (registration.authEnvVar) {
-        token = process.env[registration.authEnvVar];
+    if (registration.authEnv) {
+        token = process.env[registration.authEnv];
         if (!token) {
             return {
                 status: 'auth_env_missing',
-                message: `Environment variable '${registration.authEnvVar}' is required but not set or empty.`,
+                message: `Environment variable '${registration.authEnv}' is required but not set or empty.`,
             };
         }
     }
@@ -112,15 +112,15 @@ export async function fetchConfiguredCliManifest(registration) {
 /**
  * Explicit refresh: unconditional fetch and replace stored manifest.
  *
- * Called when user runs `crtr pkg cli refresh <name>`. Always fetches
- * regardless of cache state, and replaces stored manifest on success.
- * On failure, preserves existing cache and throws CrtrError.
+ * Called when user runs `crtr pkg plugin update <name>`. Always fetches
+ * regardless of stored-manifest state, and replaces it on success.
+ * On failure, preserves existing manifest bytes and throws CrtrError.
  *
  * Returns the raw manifest bytes on success.
  */
-export async function refreshConfiguredCli(registration) {
+export async function refreshHttpPlugin(target, store) {
     // Unconditional fetch
-    const result = await fetchConfiguredCliManifest(registration);
+    const result = await fetchHttpPluginManifest(target);
     if (result.status !== 200) {
         if (result.status === 'auth_env_missing') {
             throw usage(result.message);
@@ -130,27 +130,7 @@ export async function refreshConfiguredCli(registration) {
         }
         throw general(result.message);
     }
-    // Write to cache (replaces existing)
-    writeConfiguredCliCacheManifest(registration, result.raw);
+    // Write to the resolved HTTP manifest store.
+    writeHttpPluginManifest(store, result.raw);
     return result.raw;
 }
-/**
- * Register-time fetch: fetch and store manifest during registration.
- *
- * Called when user runs `crtr pkg cli register`. Performs one authenticated
- * GET and stores exact bytes. On failure, preserves any prior cached manifest
- * and returns the error (does not throw).
- *
- * Returns a discriminated result: success with bytes, or typed failure.
- */
-export async function registerFetchConfiguredCli(registration) {
-    // Perform fetch
-    const result = await fetchConfiguredCliManifest(registration);
-    if (result.status !== 200) {
-        // On failure, preserve existing cache and return error
-        return result;
-    }
-    // On success, write to cache
-    writeConfiguredCliCacheManifest(registration, result.raw);
-    return result;
-}

package/dist/core/{configured-clis/invoker.d.ts → command-plugins/transport/http-invoke.d.ts}

@@ -1,12 +1,12 @@
-import type { InputParam, Field } from '../help.js';
-import type { RestMapping, ManifestTimeouts } from '../command-manifests/schema.js';
-import type { LeafRunContext } from '../command.js';
-export interface ConfiguredCliInvokerSpec {
+import type { InputParam, Field } from '../../help.js';
+import type { RestMapping, ManifestTimeouts } from '../../command-manifests/schema.js';
+import type { LeafRunContext } from '../../command.js';
+export interface HttpInvokerSpec {
     /** The effective registration: local name, manifest endpoint, optional auth env var. */
     registration: {
         name: string;
         endpoint: string;
-        authEnvVar?: string;
+        authEnv?: string;
     };
     /** Manifest-level REST base override (§4.2); falls back to the endpoint origin. */
     baseUrl?: string;
@@ -22,7 +22,7 @@ export interface ConfiguredCliInvokerSpec {
     commandPath: string[];
 }
 /**
- * Execute one configured-CLI leaf. Unary leaves return the validated response
+ * Execute one HTTP-transport plugin leaf. Unary leaves return the validated response
  * object (crtr's ordinary dispatcher renders it, or mirrors it under --json).
  * Streaming leaves relay NDJSON frames to stdout incrementally and return void.
  *
@@ -33,4 +33,4 @@ export interface ConfiguredCliInvokerSpec {
  * process.exitCode = NETWORK — it never throws into handle() and never writes a
  * second result/error object to stdout.
  */
-export declare function invokeConfiguredLeaf(spec: ConfiguredCliInvokerSpec, input: Record<string, unknown>, context?: LeafRunContext): Promise<Record<string, unknown> | void>;
+export declare function invokeHttpLeaf(spec: HttpInvokerSpec, input: Record<string, unknown>, context?: LeafRunContext): Promise<Record<string, unknown> | void>;

package/dist/core/{configured-clis/invoker.js → command-plugins/transport/http-invoke.js}

@@ -1,10 +1,8 @@
-// Configured-CLI HTTP invoker — the execution seam for a validated, composed
-// configured-CLI leaf. On explicit leaf invocation only (never on help /
-// discovery), it turns a leaf's `rest` mapping + parsed input into one native
-// HTTP request and maps the response back onto crtr's output / error / exit
-// machinery (spec §6). It is the configured-CLI analogue of the command-plugin
-// `executeExternalLeaf` spawn — but the trust surface is definition + HTTP, so
-// there is nothing to spawn and nothing to sandbox.
+// HTTP-transport plugin invoker — the execution seam for a validated composed
+// HTTP leaf. On explicit leaf invocation only (never on help or discovery), it
+// turns a leaf's `rest` mapping and parsed input into one native HTTP request
+// and maps the response onto crtr's output, error, and exit machinery. Its
+// trust surface is the manifest definition plus HTTP, so it spawns nothing.
 //
 // Ownership boundary: this module owns request construction, local-file
 // materialization, bearer attachment, the native HTTP lifecycle with three
@@ -17,10 +15,10 @@ import { readFileSync, statSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
-import { validateDeclaredResult } from '../command-plugins/adapter.js';
-import { CrtrError } from '../errors.js';
-import { diag, writeStdout } from '../io.js';
-import { ExitCode } from '../../types.js';
+import { validateDeclaredResult } from './exec-invoke.js';
+import { CrtrError } from '../../errors.js';
+import { diag, writeStdout } from '../../io.js';
+import { ExitCode } from '../../../types.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -38,7 +36,7 @@ class StreamIdleError extends Error {
 // Public entry
 // ---------------------------------------------------------------------------
 /**
- * Execute one configured-CLI leaf. Unary leaves return the validated response
+ * Execute one HTTP-transport plugin leaf. Unary leaves return the validated response
  * object (crtr's ordinary dispatcher renders it, or mirrors it under --json).
  * Streaming leaves relay NDJSON frames to stdout incrementally and return void.
  *
@@ -49,7 +47,7 @@ class StreamIdleError extends Error {
  * process.exitCode = NETWORK — it never throws into handle() and never writes a
  * second result/error object to stdout.
  */
-export async function invokeConfiguredLeaf(spec, input, context) {
+export async function invokeHttpLeaf(spec, input, context) {
     const plan = buildRequestPlan(spec, input, context);
     if (spec.rest.streaming === true) {
         await requestStreaming(spec, plan);
@@ -93,14 +91,14 @@ function buildRequestPlan(spec, input, context) {
     // 5: auth — read the env var immediately before request creation. Missing or
     // empty fails pre-network; the value never appears in errors or evidence.
     let authorization;
-    const authEnvVar = spec.registration.authEnvVar;
-    if (authEnvVar !== undefined && authEnvVar !== '') {
-        const token = process.env[authEnvVar];
+    const authEnv = spec.registration.authEnv;
+    if (authEnv !== undefined && authEnv !== '') {
+        const token = process.env[authEnv];
         if (token === undefined || token === '') {
-            throw new CrtrError('auth_env_missing', `${label(spec)}: environment variable ${authEnvVar} is not set or empty`, ExitCode.USAGE, {
-                field: authEnvVar,
-                received: authEnvVar,
-                next: `Export ${authEnvVar} with the bearer token, then retry.`,
+            throw new CrtrError('auth_env_missing', `${label(spec)}: environment variable ${authEnv} is not set or empty`, ExitCode.USAGE, {
+                field: authEnv,
+                received: authEnv,
+                next: `Export ${authEnv} with the bearer token, then retry.`,
             });
         }
         authorization = `Bearer ${token}`;
@@ -510,20 +508,20 @@ function deriveExit(status) {
 function protocolError(spec, received, expected) {
     return new CrtrError('cli_protocol_error', `${label(spec)}: ${received}. Expected ${expected}.`, ExitCode.GENERAL, {
         received,
-        next: `Run \`crtr pkg cli refresh ${spec.registration.name}\` or inspect the backend response.`,
+        next: `Run \`crtr pkg plugin update ${spec.registration.name}\` or inspect the backend response.`,
     });
 }
 function unreachable(spec, plan, detail) {
     return new CrtrError('cli_unreachable', `${label(spec)}: ${detail}`, ExitCode.NETWORK, {
         received: plan.url.origin,
-        next: `Check connectivity to ${plan.url.host} and retry; run \`crtr pkg cli refresh ${spec.registration.name}\` if the command surface changed.`,
+        next: `Check connectivity to ${plan.url.host} and retry; run \`crtr pkg plugin update ${spec.registration.name}\` if the command surface changed.`,
     });
 }
 // ---------------------------------------------------------------------------
 // Small helpers
 // ---------------------------------------------------------------------------
 function label(spec) {
-    return `configured CLI "${spec.registration.name}" command \`${spec.commandPath.join(' ')}\``;
+    return `HTTP-transport plugin "${spec.registration.name}" command \`${spec.commandPath.join(' ')}\``;
 }
 function errCode(e) {
     const err = e;

package/dist/core/command.d.ts

@@ -160,15 +160,14 @@ export interface ParseArgvOptions {
 export declare function parseArgv(params: InputParam[], tokens: string[], options?: ParseArgvOptions): Promise<Record<string, unknown>>;
 /** Optional seams for `runCli`. */
 export interface RunCliOptions {
-    /** The ONE unknown-first-token retry seam (amended configured-CLI spec
-     *  §5.1, §8). Called EXACTLY once, and ONLY when an unknown FIRST token
-     *  misses at root (walk stopped at root, `path` empty, on a real non-help
-     *  token) — the sole site absent-store configured-CLI hydration may fire. A
-     *  deeper unknown token under a known command (`path` non-empty) never calls
-     *  it. Returns a freshly rebuilt root when hydration produced new commands to
-     *  re-walk the original argv against, else undefined to surface the plain
-     *  `unknown_path` error. crtr's core fast path passes no options, so a
-     *  recognized core first token is dispatched with zero configured-CLI I/O. */
+    /** The one unknown-first-token retry seam. Called exactly once only when an
+     *  unknown first token misses at root (walk stopped at root, `path` empty,
+     *  on a real non-help token), where absent HTTP-plugin stores may hydrate.
+     *  A deeper unknown token under a known command (`path` non-empty) never
+     *  calls it. It returns a freshly rebuilt root when hydration produced new
+     *  commands to re-walk the original argv against, otherwise undefined to
+     *  surface the plain `unknown_path` error. crtr's core fast path passes no
+     *  options, so a recognized core first token has zero HTTP-plugin I/O. */
     onUnknownFirstTokenMiss?: () => Promise<RootDef | undefined>;
 }
 export declare function runCli(root: RootDef, argv: string[], options?: RunCliOptions): Promise<void>;

package/dist/core/command.js

@@ -489,7 +489,7 @@ export async function parseArgv(params, tokens, options) {
     // supply takes its value from that environment variable when it is set and
     // non-empty. It is recorded as PROVIDED — the caller's environment is a real
     // source, not a display default — so it satisfies the required check below and
-    // ships through the configured-CLI invoker's presence rule (a static `default`
+    // ships through the HTTP transport's presence rule (a static `default`
     // deliberately does neither).
     for (const p of params) {
         if (p.kind !== 'flag' && p.kind !== 'positional')
@@ -564,14 +564,11 @@ export async function runCli(root, argv, options) {
     }
     let { node, path, remaining } = walk(root, tokens);
     try {
-        // The ONE unknown-first-token retry (§5.1): an unknown FIRST token — walk
-        // stopped at root (path empty) on a real, non-help token — is the only site
-        // absent-store configured-CLI hydration may fire. A deeper unknown token
-        // under a known command (path non-empty) NEVER triggers it. Invoke the seam
-        // exactly once; if it hydrated new commands it returns a rebuilt root and we
-        // re-walk the original argv once, then dispatch proceeds normally against the
-        // re-resolved node. Kept inside the try so a seam throw routes through the
-        // same error handler as everything else.
+        // An unknown first token that misses at root is the only site absent
+        // HTTP-plugin stores may hydrate. A deeper unknown token under a known
+        // command never triggers it. Invoke the seam once; if it hydrated commands,
+        // re-walk the original argv against the rebuilt root. Keeping it inside the
+        // try sends any seam failure through the ordinary error handler.
         if (options?.onUnknownFirstTokenMiss !== undefined &&
             node.kind === 'root' &&
             path.length === 0 &&

package/dist/core/config.js

@@ -6,6 +6,7 @@ import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
 import { profileRoot } from './profiles/manifest.js';
+import { SCOPE_CONFIG_KEYS } from './user-settings.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -418,7 +419,6 @@ function mergeConfig(partial) {
     const schema_version = defaults.schema_version;
     const marketplaces = partial.marketplaces === undefined ? {} : partial.marketplaces;
     const plugins = partial.plugins === undefined ? {} : partial.plugins;
-    const configuredClis = partial.configuredClis === undefined ? {} : partial.configuredClis;
     const au = partial.auto_update;
     const rawInterval = au && typeof au.interval_hours === 'number' ? au.interval_hours : undefined;
     const interval_hours = rawInterval !== undefined && Number.isFinite(rawInterval) && rawInterval >= 0
@@ -431,6 +431,9 @@ function mergeConfig(partial) {
     };
     const rawMaxPanes = partial.max_panes_per_window;
     const max_panes_per_window = normalizePositiveInteger(rawMaxPanes, defaults.max_panes_per_window);
+    const auto_open_child_viewers = typeof partial.auto_open_child_viewers === 'boolean'
+        ? partial.auto_open_child_viewers
+        : defaults.auto_open_child_viewers;
     const brokerThresholds = mergeBrokerThresholds(partial.brokerThresholds, defaults.brokerThresholds);
     const completion_bell = typeof partial.completion_bell === 'boolean' ? partial.completion_bell : defaults.completion_bell;
     const live_cycles = normalizePositiveInteger(partial.live_cycles, defaults.live_cycles);
@@ -445,7 +448,7 @@ function mergeConfig(partial) {
     const kinds = mergeKinds(partial.kinds);
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
-    return { schema_version, marketplaces, plugins, configuredClis, auto_update, max_panes_per_window, brokerThresholds, completion_bell, live_cycles, condensed_history, fold_finished_tools, keybindings, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, live_cycles, condensed_history, fold_finished_tools, keybindings, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
@@ -580,13 +583,6 @@ export function subKindsAvailableTo(kind) {
     }
     return out.sort((a, b) => a.kind.localeCompare(b.kind));
 }
-/** Every top-level `ScopeConfig` key, diffed one-by-one by `updateConfig` so
- *  an untouched key is never rewritten. */
-const CONFIG_TOP_LEVEL_KEYS = [
-    'schema_version', 'marketplaces', 'plugins', 'configuredClis', 'auto_update',
-    'max_panes_per_window', 'brokerThresholds', 'completion_bell', 'live_cycles', 'condensed_history', 'fold_finished_tools', 'keybindings', 'modelLadders', 'kinds',
-    'remoteCanvas', 'spawnEnv',
-];
 /** The SPARSE `modelLadders` to persist after a config mutation: the raw
  *  on-disk sparse ladder (absent rungs stay absent) plus ONLY the specific
  *  rungs / `defaultProvider` the mutation actually changed away from the
@@ -632,7 +628,7 @@ function mutateConfigAtPath(path, mutate) {
         const cfg = mergeConfig(raw);
         mutate(cfg);
         const partial = { ...raw };
-        for (const key of CONFIG_TOP_LEVEL_KEYS) {
+        for (const key of SCOPE_CONFIG_KEYS) {
             if (key === 'modelLadders')
                 continue;
             if (!isDeepStrictEqual(cfg[key], baseline[key])) {

package/dist/core/env-name.d.ts

@@ -0,0 +1,6 @@
+export interface EnvNameValidation {
+    isValid: boolean;
+    errors: string[];
+}
+/** Validate an environment variable identifier without reading its value. */
+export declare function validateEnvVarName(name: unknown): EnvNameValidation;

package/dist/core/env-name.js

@@ -0,0 +1,9 @@
+/** Validate an environment variable identifier without reading its value. */
+export function validateEnvVarName(name) {
+    const errors = [];
+    if (typeof name !== 'string')
+        errors.push('env var name must be a string');
+    else if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        errors.push('env var name must start with letter/underscore, followed by alphanumeric/underscore');
+    return { isValid: errors.length === 0, errors };
+}

package/dist/core/io.d.ts

@@ -12,7 +12,7 @@ export interface ErrorPayload {
     message: string;
     received?: unknown;
     field?: string;
-    /** Transport status of a failed backend call (configured CLIs). It is kept out
+    /** Transport status of a failed backend call (HTTP-transport plugins). It is kept out
      *  of `received` on purpose: `received` names the caller's offending VALUE, and
      *  reporting an HTTP status there is a false claim about what was sent. */
     http_status?: number;

package/dist/core/keybindings/__tests__/resolve.test.js

@@ -3,27 +3,43 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { BINDING_CATALOG, KeybindingConcurrentEditError, KeybindingValidationError, SAFETY_REQUIREMENTS, canonicalTerminalStroke, formatStroke, matchesTerminalInput, normalizeGesture, normalizeSparseOverrides, persistUserKeybindings, resolveKeybindings, resolveUserKeybindings, } from '../index.js';
+import { ATTACH_CONTROL_BINDINGS, BINDING_CATALOG, KeybindingConcurrentEditError, KeybindingValidationError, SAFETY_REQUIREMENTS, canonicalTerminalStroke, formatStroke, matchesTerminalInput, normalizeGesture, normalizeSparseOverrides, persistUserKeybindings, resolveKeybindings, resolveUserKeybindings, } from '../index.js';
 import { readConfig } from '../../config.js';
 const typeCheckedBindingId = 'crtr.graph.down';
 // @ts-expect-error The catalog type rejects IDs that are not built in.
 const rejectedBindingId = 'crtr.graph.not-real';
+// @ts-expect-error The Attach submenu opener has no tmux-global pair.
+const rejectedAttachGlobalId = 'crtr.tmux.menu-global.attach';
 void typeCheckedBindingId;
 void rejectedBindingId;
+void rejectedAttachGlobalId;
 function ids(prefix, actions) {
     return actions.map((action) => `${prefix}.${action}`);
 }
 function pairedMenuIds(actions) {
     return actions.flatMap((action) => [`crtr.tmux.menu.${action}`, `crtr.tmux.menu-global.${action}`]);
 }
+function pairedAttachIds(pairs) {
+    return pairs.flatMap(([menuAction, directId]) => [`crtr.tmux.menu.attach.${menuAction}`, directId]);
+}
 const REQUIRED_IDS = [
     'crtr.tmux.menu.open',
+    'crtr.tmux.menu.attach',
     ...pairedMenuIds(['promote', 'resume', 'fork', 'demote', 'detach', 'close-subtree', 'background-bash', 'file-review', 'pin', 'show', 'view-settings', 'fold-tools', 'metadata', 'context', 'providers', 'graph', 'focus-manager', 'copy-id', 'reload-viewer', 'issues', 'issue.idea', 'issue.bug']),
     ...ids('crtr.tmux.node', ['next', 'previous']),
     'crtr.tmux.inbox.toggle',
     ...ids('crtr.tmux.view', ['next', 'previous']),
-    ...ids('crtr.attach', ['detach', 'clear-or-detach', 'graph.toggle', 'model-ladder.next', 'model-ladder.previous', 'command.inspect', 'file-review']),
-    'crtr.mode.cycle',
+    ...pairedAttachIds([
+        ['detach', 'crtr.attach.detach'],
+        ['clear-or-detach', 'crtr.attach.clear-or-detach'],
+        ['mode-cycle', 'crtr.mode.cycle'],
+        ['graph.toggle', 'crtr.attach.graph.toggle'],
+        ['model-ladder.next', 'crtr.attach.model-ladder.next'],
+        ['model-ladder.previous', 'crtr.attach.model-ladder.previous'],
+        ['command.inspect', 'crtr.attach.command.inspect'],
+        ['file-review', 'crtr.attach.file-review'],
+        ['profile-files', 'crtr.attach.profile-files'],
+    ]),
     ...ids('crtr.graph', ['down', 'up', 'first', 'last', 'collapse-or-manager', 'expand-or-child', 'focus', 'revive', 'focus-manager', 'close-subtree', 'dismiss']),
     ...ids('crtr.graph.confirm', ['accept', 'cancel']),
     ...ids('crtr.view.host', ['force-quit', 'editor.backspace']),
@@ -79,6 +95,21 @@ test('catalog is closed, complete, ordered, and has valid collision-free default
         for (const gesture of definition.defaults)
             assert.equal(normalizeGesture(gesture, definition), gesture);
     }
+    const byId = new Map(BINDING_CATALOG.map((definition) => [definition.id, definition]));
+    for (const definition of BINDING_CATALOG) {
+        if (definition.pair === undefined)
+            continue;
+        const paired = byId.get(definition.pair.pairedId);
+        assert.equal(paired?.pair?.pairedId, definition.id, `${definition.id} must have a reciprocal pair`);
+        assert.notEqual(paired?.pair?.field, definition.pair.field, `${definition.id} pair fields must differ`);
+        assert.ok(definition.pair.field === 'menu' || paired?.pair?.field === 'menu', `${definition.id} must pair with a menu selector`);
+    }
+    for (const { menuId, actionId } of ATTACH_CONTROL_BINDINGS) {
+        assert.equal(byId.get(menuId)?.pair?.field, 'menu');
+        assert.equal(byId.get(menuId)?.pair?.pairedId, actionId);
+        assert.equal(byId.get(actionId)?.pair?.field, 'direct');
+        assert.equal(byId.get(actionId)?.pair?.pairedId, menuId);
+    }
     const resolved = resolveKeybindings();
     assert.equal(resolved.bindings.size, BINDING_CATALOG.length);
     assert.deepEqual(resolved.diagnostics, []);
@@ -148,6 +179,12 @@ test('tmux menu selectors collide only inside their own menu', () => {
     const selector = resolveKeybindings({ 'crtr.tmux.menu.promote': ['j'] });
     assert.deepEqual(selector.gestures('crtr.tmux.menu.promote'), ['j']);
     assert.deepEqual(selector.diagnostics, []);
+    const attachSelector = resolveKeybindings({ 'crtr.tmux.menu.attach.detach': ['o'] });
+    assert.deepEqual(attachSelector.gestures('crtr.tmux.menu.attach.detach'), ['o']);
+    assert.deepEqual(attachSelector.diagnostics, [], 'attach submenu selectors may reuse top-level menu selectors');
+    const attachCollision = resolveKeybindings({ 'crtr.tmux.menu.attach.detach': ['c'] });
+    assert.deepEqual(attachCollision.gestures('crtr.tmux.menu.attach.detach'), ['d']);
+    assert.ok(attachCollision.diagnostics.some((item) => item.code === 'collision'), 'selectors in the same attach submenu must remain unique');
 });
 test('reachability rejects deliberate unbinding that would trap a context', () => {
     const graph = resolveKeybindings({

package/dist/core/keybindings/attach-control.d.ts

@@ -0,0 +1,37 @@
+export declare const ATTACH_CONTROL_BINDINGS: readonly [{
+    readonly menuId: "crtr.tmux.menu.attach.detach";
+    readonly actionId: "crtr.attach.detach";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.clear-or-detach";
+    readonly actionId: "crtr.attach.clear-or-detach";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.mode-cycle";
+    readonly actionId: "crtr.mode.cycle";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.graph.toggle";
+    readonly actionId: "crtr.attach.graph.toggle";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.model-ladder.next";
+    readonly actionId: "crtr.attach.model-ladder.next";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.model-ladder.previous";
+    readonly actionId: "crtr.attach.model-ladder.previous";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.command.inspect";
+    readonly actionId: "crtr.attach.command.inspect";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.file-review";
+    readonly actionId: "crtr.attach.file-review";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.profile-files";
+    readonly actionId: "crtr.attach.profile-files";
+}];
+export type AttachBindingId = typeof ATTACH_CONTROL_BINDINGS[number]['actionId'];
+export type AttachMenuBindingId = typeof ATTACH_CONTROL_BINDINGS[number]['menuId'];
+export interface ExtractedAttachControlInput {
+    readonly actionId: AttachBindingId;
+    readonly remaining: string;
+}
+export declare function decodeAttachControlInput(data: string): AttachBindingId | undefined;
+export declare function encodeAttachControlInput(actionId: AttachBindingId): string;
+export declare function extractAttachControlInput(data: string): ExtractedAttachControlInput | undefined;

package/dist/core/keybindings/attach-control.js

@@ -0,0 +1,38 @@
+export const ATTACH_CONTROL_BINDINGS = [
+    { menuId: 'crtr.tmux.menu.attach.detach', actionId: 'crtr.attach.detach' },
+    { menuId: 'crtr.tmux.menu.attach.clear-or-detach', actionId: 'crtr.attach.clear-or-detach' },
+    { menuId: 'crtr.tmux.menu.attach.mode-cycle', actionId: 'crtr.mode.cycle' },
+    { menuId: 'crtr.tmux.menu.attach.graph.toggle', actionId: 'crtr.attach.graph.toggle' },
+    { menuId: 'crtr.tmux.menu.attach.model-ladder.next', actionId: 'crtr.attach.model-ladder.next' },
+    { menuId: 'crtr.tmux.menu.attach.model-ladder.previous', actionId: 'crtr.attach.model-ladder.previous' },
+    { menuId: 'crtr.tmux.menu.attach.command.inspect', actionId: 'crtr.attach.command.inspect' },
+    { menuId: 'crtr.tmux.menu.attach.file-review', actionId: 'crtr.attach.file-review' },
+    { menuId: 'crtr.tmux.menu.attach.profile-files', actionId: 'crtr.attach.profile-files' },
+];
+const ATTACH_CONTROL_PREFIX = '\x1b_crtr;';
+const ATTACH_CONTROL_SUFFIX = '\x1b\\';
+const ATTACH_BINDING_IDS = new Set(ATTACH_CONTROL_BINDINGS.map(({ actionId }) => actionId));
+export function decodeAttachControlInput(data) {
+    if (!data.startsWith(ATTACH_CONTROL_PREFIX) || !data.endsWith(ATTACH_CONTROL_SUFFIX))
+        return undefined;
+    const actionId = data.slice(ATTACH_CONTROL_PREFIX.length, -ATTACH_CONTROL_SUFFIX.length);
+    return ATTACH_BINDING_IDS.has(actionId) ? actionId : undefined;
+}
+export function encodeAttachControlInput(actionId) {
+    return `${ATTACH_CONTROL_PREFIX}${actionId}${ATTACH_CONTROL_SUFFIX}`;
+}
+export function extractAttachControlInput(data) {
+    let match;
+    for (const { actionId } of ATTACH_CONTROL_BINDINGS) {
+        const encoded = encodeAttachControlInput(actionId);
+        const index = data.indexOf(encoded);
+        if (index >= 0 && (match === undefined || index < match.index))
+            match = { actionId, encoded, index };
+    }
+    if (match === undefined)
+        return undefined;
+    return {
+        actionId: match.actionId,
+        remaining: data.slice(0, match.index) + data.slice(match.index + match.encoded.length),
+    };
+}