@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/command-plugins/bundle.js

@@ -0,0 +1,198 @@
+import { Parser } from 'tar';
+import { validateCommandManifest } from '../command-manifests/manifest.js';
+function issue(code, message, received, expected, next, path) {
+    return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
+}
+function bundleInvalid(message, received, expected, next, path) {
+    return issue('plugin_bundle_invalid', message, received, expected, next, path);
+}
+function archiveEnvelopeIssue(archive) {
+    // tar v7's Parser always sniffs gzip, even when passed gzip: false. Reject
+    // its unambiguous magic bytes before parsing so archive plugins stay tar-only.
+    if (archive[0] === 0x1f && archive[1] === 0x8b) {
+        return bundleInvalid('bundle archive must be uncompressed tar data', 'gzip-compressed archive', 'an uncompressed tar archive', 'Serve the archive without compression.');
+    }
+    if (archive.length === 0 || archive.length % 512 !== 0) {
+        return bundleInvalid('bundle archive must be a non-empty whole number of 512-byte tar blocks', `${archive.length} bytes`, 'a non-empty tar stream with a 512-byte block length', 'Serve one complete uncompressed tar archive.');
+    }
+    if (archive.length < 1024 || !archive.subarray(-1024).every((byte) => byte === 0)) {
+        return bundleInvalid('bundle archive is missing the required two zero-block terminator', 'archive tail is not 1024 zero bytes', 'a complete tar stream ending in two 512-byte zero blocks', 'Serve the complete uncompressed tar archive.');
+    }
+    return undefined;
+}
+function validateMemberName(path, type) {
+    if (path.length === 0 || path.includes('\u0000') || path.includes('\\') || path.startsWith('/') || /^[A-Za-z]:($|\/)/.test(path)) {
+        return bundleInvalid('bundle member path must be a safe relative POSIX path', path, 'a relative path without absolute, drive-letter, backslash, or NUL forms', 'Use a safe relative POSIX member path.', path);
+    }
+    if (type === 'file' && path.endsWith('/')) {
+        return bundleInvalid('only directory members may have a trailing slash', path, 'a regular-file path without a trailing slash', 'Emit this member as a regular file path.', path);
+    }
+    const segments = (type === 'directory' && path.endsWith('/') ? path.slice(0, -1) : path).split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        return bundleInvalid('bundle member path contains an unsafe segment', path, 'non-empty segments other than . or ..', 'Use a safe relative POSIX member path.', path);
+    }
+    return undefined;
+}
+function validateMemberShape(path, type) {
+    if (type === 'file') {
+        if (path === 'bundle.json' || path === 'commands.json' || (path.startsWith('memory/') && path.endsWith('.md')))
+            return undefined;
+        return bundleInvalid('bundle contains an unsupported file member', path, 'bundle.json, commands.json, or memory/**/*.md', 'Remove unsupported members from the archive.', path);
+    }
+    if (path === 'memory' || path.startsWith('memory/'))
+        return undefined;
+    return bundleInvalid('bundle contains an unsupported directory member', path, 'memory or a directory below memory/', 'Remove unsupported directory members from the archive.', path);
+}
+/** A member path as it will exist on disk: directories carry no trailing slash. */
+function materializedPath(member) {
+    return member.type === 'directory' && member.path.endsWith('/') ? member.path.slice(0, -1) : member.path;
+}
+/** Reject member sets that cannot become one filesystem tree — a path claimed as
+ *  both a file and a directory, the same path twice after directory
+ *  normalization, or a file that another member nests beneath. */
+function validateMemberTree(members) {
+    const claimed = new Map();
+    for (const member of members) {
+        const path = materializedPath(member);
+        const existing = claimed.get(path);
+        if (existing !== undefined) {
+            return bundleInvalid(existing === member.type
+                ? 'bundle contains a duplicate member'
+                : 'bundle claims one path as both a file and a directory', `${path} (${existing} and ${member.type})`, 'each materialized path exactly once, with one type', 'Emit each archive path once, as a single member type.', path);
+        }
+        claimed.set(path, member.type);
+    }
+    for (const [path, type] of claimed) {
+        if (type !== 'file')
+            continue;
+        for (const other of claimed.keys()) {
+            if (other.startsWith(`${path}/`)) {
+                return bundleInvalid('bundle nests a member beneath a regular-file path', `${other} beneath file ${path}`, 'members nested only beneath directory paths', 'Emit the parent path as a directory or remove the nested member.', other);
+            }
+        }
+    }
+    return undefined;
+}
+async function parseArchive(archive) {
+    const members = [];
+    const seen = new Set();
+    let memberIssue;
+    await new Promise((resolve, reject) => {
+        const parser = new Parser({
+            strict: true,
+            maxMetaEntrySize: Number.MAX_SAFE_INTEGER,
+            gzip: false,
+            brotli: false,
+            zstd: false,
+            onReadEntry: (entry) => {
+                const path = entry.path;
+                const type = entry.type === 'File' || entry.type === 'OldFile'
+                    ? 'file'
+                    : entry.type === 'Directory'
+                        ? 'directory'
+                        : undefined;
+                if (type === undefined || entry.unsupported || entry.ignore || entry.linkpath !== undefined) {
+                    memberIssue ??= bundleInvalid('bundle member must be a regular file or directory without a link target', `${path} (${entry.type})`, 'a regular file or directory member without link metadata', 'Remove links and unsupported member types from the archive.', path);
+                    entry.resume();
+                    return;
+                }
+                memberIssue ??= validateMemberName(path, type);
+                memberIssue ??= validateMemberShape(path, type);
+                if (seen.has(path)) {
+                    memberIssue ??= bundleInvalid('bundle contains a duplicate member', path, 'each member path exactly once', 'Emit each archive member only once.', path);
+                }
+                seen.add(path);
+                const chunks = [];
+                entry.on('data', (chunk) => chunks.push(chunk));
+                entry.on('end', () => {
+                    if (memberIssue === undefined)
+                        members.push({ path, type, bytes: new Uint8Array(Buffer.concat(chunks)) });
+                });
+            },
+        });
+        parser.on('ignoredEntry', (entry) => {
+            const path = entry.path;
+            memberIssue ??= bundleInvalid('bundle contains an ignored or unsupported archive member', `${path} (${entry.type})`, 'only supported regular file or directory members', 'Remove ignored or unsupported members from the archive.', path);
+            entry.resume();
+        });
+        parser.once('error', reject);
+        parser.once('end', resolve);
+        try {
+            parser.end(Buffer.from(archive));
+        }
+        catch (error) {
+            reject(error);
+        }
+    }).catch((error) => {
+        memberIssue ??= bundleInvalid('bundle archive could not be parsed', error instanceof Error ? error.message : String(error), 'a valid complete uncompressed tar archive', 'Fix the archive format and serve it again.');
+    });
+    return memberIssue === undefined ? { members } : { issue: memberIssue };
+}
+function parseBundleMetadata(bytes) {
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        return bundleInvalid('bundle.json is not valid JSON', 'invalid JSON', '{"bundleVersion":1}', 'Write valid bundle metadata.', 'bundle.json');
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || Object.keys(raw).length !== 1 || raw['bundleVersion'] !== 1) {
+        return bundleInvalid('bundle.json must contain exactly {"bundleVersion":1}', JSON.stringify(raw), 'an object with only bundleVersion set to 1', 'Set bundle.json to {"bundleVersion":1}.', 'bundle.json');
+    }
+    return undefined;
+}
+function parseCommands(bytes, reservedCoreNames) {
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        return {
+            issues: [bundleInvalid('commands.json is not valid JSON', 'invalid JSON', 'a valid command-manifest JSON object', 'Regenerate commands.json.', 'commands.json')],
+        };
+    }
+    const validation = validateCommandManifest(raw, { transport: 'http', reservedCoreNames });
+    return {
+        ...(validation.manifest !== undefined ? { commands: validation.manifest } : {}),
+        issues: validation.issues,
+    };
+}
+/** Validate a Core-served plugin directory archive entirely in memory. */
+export async function validatePluginBundle(archive, options) {
+    const envelope = archiveEnvelopeIssue(archive);
+    if (envelope !== undefined)
+        return { issues: [envelope] };
+    const parsed = await parseArchive(archive);
+    if (parsed.issue !== undefined || parsed.members === undefined)
+        return { issues: [parsed.issue] };
+    const treeIssue = validateMemberTree(parsed.members);
+    if (treeIssue !== undefined)
+        return { issues: [treeIssue] };
+    const bundle = parsed.members.find((member) => member.path === 'bundle.json' && member.type === 'file');
+    const commands = parsed.members.find((member) => member.path === 'commands.json' && member.type === 'file');
+    if (bundle === undefined || commands === undefined) {
+        return {
+            issues: [bundleInvalid('bundle must contain exactly one bundle.json and one commands.json regular file', `bundle.json=${bundle !== undefined}, commands.json=${commands !== undefined}`, 'one regular bundle.json and one regular commands.json member', 'Add the required metadata members to the archive.')],
+        };
+    }
+    const metadataIssue = parseBundleMetadata(bundle.bytes);
+    if (metadataIssue !== undefined)
+        return { issues: [metadataIssue] };
+    const commandValidation = parseCommands(commands.bytes, options.reservedCoreNames);
+    if (commandValidation.commands === undefined)
+        return { issues: commandValidation.issues };
+    return {
+        bundle: {
+            bundleVersion: 1,
+            commands: commandValidation.commands,
+            commandsBytes: commands.bytes,
+            directories: parsed.members
+                .filter((member) => member.type === 'directory')
+                .map((member) => ({ path: member.path })),
+            memory: parsed.members
+                .filter((member) => member.type === 'file' && member.path.startsWith('memory/'))
+                .map((member) => ({ path: member.path, bytes: member.bytes })),
+        },
+        issues: [],
+    };
+}

package/dist/core/command-plugins/discovery.d.ts

@@ -2,7 +2,6 @@ import type { InstalledPlugin, PluginTransport } from '../../types.js';
 import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
 import type { CommandManifestIssue, DeclBranch as DeclBranchGeneric, DeclLeaf as DeclLeafGeneric } from '../command-manifests/schema.js';
 import type { CommandRegistrySnapshot } from '../command-manifests/registry.js';
-import type { HttpPluginManifestStore } from './store.js';
 export interface CommandDiscoveryIssue extends CommandManifestIssue {
     plugin: string;
 }
@@ -22,12 +21,6 @@ export interface PluginCommandValidation {
     transport?: PluginTransport;
     contributions: ValidatedContribution[];
     issues: CommandDiscoveryIssue[];
-    absentStore?: boolean;
-    httpManifestStore?: HttpPluginManifestStore;
-}
-export interface AbsentStoreHydration {
-    hydratedAny: boolean;
-    diagnostics: string[];
 }
 export declare function effectiveCommandPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
 export declare function validatePluginCommands(plugin: InstalledPlugin, reservedNames?: ReadonlySet<string>): PluginCommandValidation;
@@ -38,4 +31,3 @@ export declare function discoverCommandContributions(reservedNames: ReadonlySet<
     issues: CommandDiscoveryIssue[];
 };
 export declare function buildExternalCommandSnapshot(reservedCoreNames: ReadonlySet<string>): CommandRegistrySnapshot;
-export declare function hydrateAbsentHttpPlugins(): Promise<AbsentStoreHydration>;

package/dist/core/command-plugins/discovery.js

@@ -6,8 +6,6 @@ import { validateCommandManifest } from '../command-manifests/manifest.js';
 import { resolveCommandRegistry } from '../command-manifests/registry.js';
 import { adaptPluginContributions } from './compose.js';
 import { validateHttpPluginTransport } from './endpoint.js';
-import { readHttpPluginManifest, resolveHttpPluginManifestStore, writeHttpPluginManifest } from './store.js';
-import { fetchHttpPluginManifest } from './transport/http-fetch.js';
 export function effectiveCommandPlugins(startDir = process.cwd(), profileId) {
     const seen = new Set();
     const result = [];
@@ -97,10 +95,7 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
     const transport = transportFor(plugin, issues);
     if (transport === undefined)
         return { plugin, manifestPath, contributions: [], issues };
-    const httpManifestStore = transport.kind === 'http'
-        ? resolveHttpPluginManifestStore({ root: plugin.root, commands }) ?? undefined
-        : undefined;
-    const safe = transport.kind === 'http' ? httpManifestStore?.path ?? null : safePath(plugin.root, commands);
+    const safe = safePath(plugin.root, commands);
     if (safe === null) {
         issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'commands pointer escapes the plugin root or is not a regular file', received: commands, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix plugin.json.commands.', path: 'commands' });
         return { plugin, manifestPath, transport, contributions: [], issues };
@@ -108,14 +103,12 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
     manifestPath = safe;
     let bytes;
     try {
-        bytes = transport.kind === 'http' ? readHttpPluginManifest(httpManifestStore) : readFileSync(safe);
+        bytes = readFileSync(safe);
     }
     catch {
         bytes = null;
     }
     if (bytes === null) {
-        if (transport.kind === 'http')
-            return { plugin, manifestPath, transport, contributions: [], issues, absentStore: true, httpManifestStore };
         issues.push({ code: 'command_manifest_unreadable', plugin: plugin.name, message: 'commands.json is missing or unreadable', received: safe, expected: 'a readable JSON file', next: 'Reinstall or update the plugin.' });
         return { plugin, manifestPath, transport, contributions: [], issues };
     }
@@ -124,8 +117,6 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
         raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
     }
     catch {
-        if (transport.kind === 'http')
-            return { plugin, manifestPath, transport, contributions: [], issues, absentStore: true, httpManifestStore };
         issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'commands.json is not valid JSON', received: safe, expected: 'a JSON object', next: 'Regenerate commands.json.' });
         return { plugin, manifestPath, transport, contributions: [], issues };
     }
@@ -171,31 +162,3 @@ export function buildExternalCommandSnapshot(reservedCoreNames) {
     const resolved = resolveCommandRegistry(candidates, reservedCoreNames);
     return { contributions: resolved.contributions, issues: [...validations.flatMap((validation) => validation.issues.map((issue) => contributorIssue(validation.plugin, issue))), ...resolved.issues] };
 }
-export async function hydrateAbsentHttpPlugins() {
-    let hydratedAny = false;
-    const diagnostics = [];
-    for (const validation of discoverPluginCommandCandidates()) {
-        if (validation.transport?.kind !== 'http')
-            continue;
-        const unsafePath = validation.issues.find((issue) => issue.code === 'command_path_unsafe');
-        if (unsafePath !== undefined) {
-            diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${unsafePath.code}: ${unsafePath.message} — ${unsafePath.next}`);
-            continue;
-        }
-        if (!validation.absentStore || validation.httpManifestStore === undefined)
-            continue;
-        try {
-            const result = await fetchHttpPluginManifest({ name: validation.plugin.name, endpoint: validation.transport.endpoint, ...(validation.transport.authEnv !== undefined ? { authEnv: validation.transport.authEnv } : {}) });
-            if (result.status === 200) {
-                writeHttpPluginManifest(validation.httpManifestStore, result.raw);
-                hydratedAny = true;
-            }
-            else
-                diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${result.message} — run \`crtr pkg plugin update --name ${validation.plugin.name}\``);
-        }
-        catch (error) {
-            diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${error.message} — run \`crtr pkg plugin update --name ${validation.plugin.name}\``);
-        }
-    }
-    return { hydratedAny, diagnostics };
-}

package/dist/core/command-plugins/transport/http-fetch.d.ts

@@ -1,42 +1,16 @@
 import type { HttpPluginFetchTarget } from '../endpoint.js';
-import type { HttpPluginManifestStore } from '../store.js';
-/** Result of a successful manifest fetch. */
+/** Exact archive bytes returned by a successful authenticated bundle fetch. */
 export interface FetchSuccess {
     status: 200;
     raw: Uint8Array;
 }
-/** Typed failures from manifest fetch. */
 export type FetchResult = FetchSuccess | FetchFailure;
 export interface FetchFailure {
     status: 'auth_env_missing' | 'cli_unreachable' | 'cli_protocol_error';
     message: string;
 }
 /**
- * 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 `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
- * - A single 10-second socket-inactivity timeout (Node's `timeout` option) covers
- *   the whole request — there is no separate connect clock and no 30s total cap;
- *   that two-clock model belongs to the invoker's per-leaf HTTP calls (§6.6), not
- *   this simpler manifest-fetch primitive.
- * - Returns exact response bytes on 2xx success
- * - Returns typed `cli_unreachable` NETWORK on transport/timeout failures
- * - Returns typed `cli_protocol_error` GENERAL on non-2xx without parseable error body
- *
- * No retries, no conditional request (ETag/If-None-Match), no 304 handling.
+ * One authenticated GET for a plugin directory archive. It has one ten-second
+ * inactivity timeout and never retries or conditionally revalidates.
  */
-export declare function fetchHttpPluginManifest(registration: HttpPluginFetchTarget): Promise<FetchResult>;
-/**
- * Explicit refresh: unconditional fetch and replace stored manifest.
- *
- * 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 refreshHttpPlugin(target: HttpPluginFetchTarget, store: HttpPluginManifestStore): Promise<Uint8Array>;
+export declare function fetchHttpPluginBundle(registration: HttpPluginFetchTarget): Promise<FetchResult>;

package/dist/core/command-plugins/transport/http-fetch.js

@@ -1,31 +1,11 @@
 import { URL } from 'node:url';
 import { request as httpsRequest } from 'node:https';
 import { request as httpRequest } from 'node:http';
-import { writeHttpPluginManifest } from '../store.js';
-import { general, network, usage } from '../../errors.js';
-// ---------------------------------------------------------------------------
-// Core fetch primitive
-// ---------------------------------------------------------------------------
 /**
- * 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 `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
- * - A single 10-second socket-inactivity timeout (Node's `timeout` option) covers
- *   the whole request — there is no separate connect clock and no 30s total cap;
- *   that two-clock model belongs to the invoker's per-leaf HTTP calls (§6.6), not
- *   this simpler manifest-fetch primitive.
- * - Returns exact response bytes on 2xx success
- * - Returns typed `cli_unreachable` NETWORK on transport/timeout failures
- * - Returns typed `cli_protocol_error` GENERAL on non-2xx without parseable error body
- *
- * No retries, no conditional request (ETag/If-None-Match), no 304 handling.
+ * One authenticated GET for a plugin directory archive. It has one ten-second
+ * inactivity timeout and never retries or conditionally revalidates.
  */
-export async function fetchHttpPluginManifest(registration) {
-    // Check auth env var and fail before network if named but empty
+export async function fetchHttpPluginBundle(registration) {
     let token;
     if (registration.authEnv) {
         token = process.env[registration.authEnv];
@@ -36,101 +16,43 @@ export async function fetchHttpPluginManifest(registration) {
             };
         }
     }
-    // Parse endpoint URL
     let url;
     try {
         url = new URL(registration.endpoint);
     }
-    catch (err) {
+    catch {
         return {
             status: 'cli_protocol_error',
             message: `Invalid endpoint URL: ${registration.endpoint}`,
         };
     }
-    // Prepare request headers
-    const headers = {
-        'Accept': 'application/json',
-    };
-    if (token) {
+    const headers = { Accept: 'application/x-tar' };
+    if (token)
         headers['Authorization'] = `Bearer ${token}`;
-    }
-    // Perform the GET request
     return new Promise((resolve) => {
         const request = url.protocol === 'https:' ? httpsRequest : httpRequest;
-        const options = {
-            method: 'GET',
-            headers,
-            timeout: 10_000, // 10 second manifest fetch timeout per spec §6.6
-        };
-        const req = request(url, options, (res) => {
+        const req = request(url, { method: 'GET', headers, timeout: 10_000 }, (res) => {
             let body = Buffer.alloc(0);
-            res.on('data', (chunk) => {
-                body = Buffer.concat([body, chunk]);
-            });
+            res.on('data', (chunk) => { body = Buffer.concat([body, chunk]); });
             res.on('end', () => {
                 if (!res.statusCode) {
-                    resolve({
-                        status: 'cli_protocol_error',
-                        message: 'No HTTP status code received.',
-                    });
-                    return;
+                    resolve({ status: 'cli_protocol_error', message: 'No HTTP status code received.' });
                 }
-                // Success: 2xx status
-                if (res.statusCode >= 200 && res.statusCode < 300) {
-                    resolve({
-                        status: 200,
-                        raw: new Uint8Array(body),
-                    });
-                    return;
+                else if (res.statusCode >= 200 && res.statusCode < 300) {
+                    resolve({ status: 200, raw: new Uint8Array(body) });
+                }
+                else {
+                    resolve({ status: 'cli_protocol_error', message: `HTTP ${res.statusCode} from ${registration.endpoint}` });
                 }
-                // Non-2xx failure
-                resolve({
-                    status: 'cli_protocol_error',
-                    message: `HTTP ${res.statusCode} from ${registration.endpoint}`,
-                });
             });
         });
         req.on('timeout', () => {
             req.destroy();
-            resolve({
-                status: 'cli_unreachable',
-                message: `Request timeout (10s) fetching ${registration.endpoint}`,
-            });
+            resolve({ status: 'cli_unreachable', message: `Request timeout (10s) fetching ${registration.endpoint}` });
         });
-        req.on('error', (err) => {
-            resolve({
-                status: 'cli_unreachable',
-                message: `Network error fetching ${registration.endpoint}: ${err.message}`,
-            });
+        req.on('error', (error) => {
+            resolve({ status: 'cli_unreachable', message: `Network error fetching ${registration.endpoint}: ${error.message}` });
         });
         req.end();
     });
 }
-// ---------------------------------------------------------------------------
-// Store-integrated helpers
-// ---------------------------------------------------------------------------
-/**
- * Explicit refresh: unconditional fetch and replace stored manifest.
- *
- * 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 refreshHttpPlugin(target, store) {
-    // Unconditional fetch
-    const result = await fetchHttpPluginManifest(target);
-    if (result.status !== 200) {
-        if (result.status === 'auth_env_missing') {
-            throw usage(result.message);
-        }
-        if (result.status === 'cli_unreachable') {
-            throw network(result.message);
-        }
-        throw general(result.message);
-    }
-    // Write to the resolved HTTP manifest store.
-    writeHttpPluginManifest(store, result.raw);
-    return result.raw;
-}

package/dist/core/command.d.ts

@@ -166,17 +166,5 @@ export interface ParseArgvOptions {
  *  Returns a plain object whose keys are camelCase parameter names.
  *  Optionally tracks which parameters were explicitly provided via a callback. */
 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. 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>;
+export declare function runCli(root: RootDef, argv: string[]): Promise<void>;
 export {};

package/dist/core/command.js

@@ -547,7 +547,7 @@ export async function parseArgv(params, tokens, options) {
     }
     return result;
 }
-export async function runCli(root, argv, options) {
+export async function runCli(root, argv) {
     // argv is process.argv — strip node binary + script path. `--json` is a
     // global: pull it out anywhere it appears so the rest of argv parses against
     // the leaf schema unchanged, and switch stdout from rendered prose to raw
@@ -570,21 +570,6 @@ export async function runCli(root, argv, options) {
     }
     let { node, path, remaining } = walk(root, tokens);
     try {
-        // 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 &&
-            remaining.length > 0 &&
-            remaining[0] !== '-h' &&
-            remaining[0] !== '--help') {
-            const rebuilt = await options.onUnknownFirstTokenMiss();
-            if (rebuilt !== undefined)
-                ({ node, path, remaining } = walk(rebuilt, tokens));
-        }
         // Passthrough branches (e.g. `crtr capture`) opt out of the tree model
         // entirely: forward every token after the branch verbatim to an external
         // binary before any of the normal unknown-path / help / dispatch logic

package/dist/core/config.d.ts

@@ -1,4 +1,5 @@
 import type { Scope, ScopeConfig, ScopeState, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
+import { type BindingId } from './keybindings/catalog.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
 export declare function readConfig(scope: Scope): ScopeConfig;
@@ -22,6 +23,9 @@ export declare function writeConfig(scope: Scope, config: ScopeConfig): void;
 export declare function writeRawConfig(scope: Scope, config: Partial<ScopeConfig>): void;
 export declare function writeState(scope: Scope, state: ScopeState): void;
 export declare function ensureScopeInitialized(scope: Scope, root: string): void;
+/** Normalize the user-owned list of attach actions allowed to bridge through an
+ * occupied tmux root binding. Unknown and non-attach ids have no effect. */
+export declare function normalizeTmuxPassthrough(raw: unknown): BindingId[];
 /** 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
  *  scopes onto each other WITHOUT each scope's own default-fill masking a

package/dist/core/config.js

@@ -1,12 +1,14 @@
 import { mkdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
+import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings/catalog.js';
 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';
+import { normalizeWorkingGerunds } from '../shared/working-activity.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -132,7 +134,7 @@ export function ensureScopeInitialized(scope, root) {
         // a missing `modelLadders` from whatever build is CURRENTLY running, and an explicit
         // user override (`sys config set modelLadders...`) still persists and still wins.
         // Keybindings are sparse user overrides, so an untouched scope omits that member too.
-        const { modelLadders: _omittedModelLadders, keybindings: _omittedKeybindings, brokerThresholds, ...rest } = defaultScopeConfig();
+        const { modelLadders: _omittedModelLadders, keybindings: _omittedKeybindings, tmux_passthrough: _omittedTmuxPassthrough, brokerThresholds, ...rest } = defaultScopeConfig();
         // Broker thresholds are host-wide daemon policy, so only user scope
         // persists them. Project config must never acquire a machine setting.
         atomicWriteJson(cfgPath, scope === 'user' ? { ...rest, brokerThresholds } : rest);
@@ -149,6 +151,14 @@ function normalizeKeybindings(raw) {
     }
     return out;
 }
+const ATTACH_PANE_BINDING_IDS = new Set(BINDING_CATALOG.filter(isAttachPaneBinding).map((definition) => definition.id));
+/** Normalize the user-owned list of attach actions allowed to bridge through an
+ * occupied tmux root binding. Unknown and non-attach ids have no effect. */
+export function normalizeTmuxPassthrough(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return [...new Set(raw.filter((id) => typeof id === 'string' && BINDING_IDS.has(id) && ATTACH_PANE_BINDING_IDS.has(id)))];
+}
 function mergeModelLadders(raw, base = defaultModelLaddersConfig()) {
     const defaults = base;
     if (raw === null || typeof raw !== 'object')
@@ -414,6 +424,12 @@ function mergeBrokerThresholds(raw, defaults) {
         ? { warning, automaticReviveCap }
         : { ...defaults };
 }
+function normalizeWhipMessages(raw) {
+    if (!Array.isArray(raw))
+        return [...DEFAULT_WHIP_MESSAGES];
+    const messages = raw.filter((message) => typeof message === 'string' && message.trim() !== '').map((message) => message.trim());
+    return messages.length > 0 ? messages : [...DEFAULT_WHIP_MESSAGES];
+}
 function mergeConfig(partial) {
     const defaults = defaultScopeConfig();
     const schema_version = defaults.schema_version;
@@ -436,19 +452,28 @@ function mergeConfig(partial) {
         : 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 working_gerunds = normalizeWorkingGerunds(partial.working_gerunds);
+    const whip_mode = typeof partial.whip_mode === 'boolean' ? partial.whip_mode : defaults.whip_mode;
+    const whip_messages = normalizeWhipMessages(partial.whip_messages);
+    const mouse_mode_default = MOUSE_MODE_DEFAULTS.includes(partial.mouse_mode_default)
+        ? partial.mouse_mode_default
+        : defaults.mouse_mode_default;
     const live_cycles = normalizePositiveInteger(partial.live_cycles, defaults.live_cycles);
     const condensed_history = CONDENSED_HISTORY_MODES.includes(partial.condensed_history)
         ? partial.condensed_history
         : defaults.condensed_history;
     const fold_finished_tools = typeof partial.fold_finished_tools === 'boolean' ? partial.fold_finished_tools : defaults.fold_finished_tools;
+    const summarize_tool_calls = typeof partial.summarize_tool_calls === 'boolean' ? partial.summarize_tool_calls : defaults.summarize_tool_calls;
+    const detailed_tool_recaps = typeof partial.detailed_tool_recaps === 'boolean' ? partial.detailed_tool_recaps : defaults.detailed_tool_recaps;
     const keybindings = normalizeKeybindings(partial.keybindings);
+    const tmux_passthrough = normalizeTmuxPassthrough(partial.tmux_passthrough);
     const modelLadders = mergeModelLadders(partial.modelLadders);
     const modelRoutes = mergeModelRoutes(partial.modelRoutes);
     const modelRouting = mergeModelRouting(partial.modelRouting, undefined);
     const kinds = mergeKinds(partial.kinds);
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
-    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 };
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, whip_messages, mouse_mode_default, live_cycles, condensed_history, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, 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