@fnndsc/brasa 0.34.0 → 0.35.0

package/dist/core/dispatch.js

@@ -12,330 +12,37 @@
  *
  * @module
  */
-import { builtin_rev, builtin_tac, builtin_yes, builtin_seq, builtin_shuf, builtin_rot13 } from '../builtins/games/text.js';
-import { builtin_factor, builtin_primes, builtin_roll, builtin_calc, builtin_units } from '../builtins/games/numbers.js';
-import { builtin_cowsay, builtin_cowthink } from '../builtins/games/cowsay.js';
-import { builtin_figlet, builtin_banner } from '../builtins/games/figlet.js';
-import { builtin_lolcat } from '../builtins/games/lolcat.js';
-import { builtin_morse } from '../builtins/games/morse.js';
-import { builtin_who, builtin_uptime, builtin_ping, builtin_chrisfetch, builtin_say } from '../builtins/games/lab.js';
-import { builtin_wtf } from '../builtins/games/wtf.js';
-import { builtin_file, builtin_xxd, builtin_strings, builtin_sha256sum, builtin_md5sum } from '../builtins/games/bytes.js';
-import { builtin_qr } from '../builtins/games/qr.js';
-import { builtin_pom, builtin_stardate, builtin_ddate, builtin_sunrise } from '../builtins/games/sky.js';
-import { builtin_timer, builtin_leave, builtin_stopwatch } from '../builtins/games/chimes.js';
-import { builtin_sl, builtin_cmatrix, builtin_rain, builtin_asciiquarium, builtin_tetris, builtin_snake } from '../builtins/games/show.js';
-import { builtin_quiz, builtin_hangman, builtin_2048 } from '../builtins/games/play.js';
-import { builtin_notes } from '../builtins/sys/notes.js';
+import { commands_register, commandOrder_set, envelopeHandler_get, plainHandler_get, builtinCommand_has } from './commandRegistry.js';
+import { coreCommands } from './coreCommands.js';
+import { ENVELOPE_ORDER, PLAIN_ORDER, HELP_ORDER } from './commandOrder.js';
 import { stdin_set } from '../builtins/games/stdin.js';
-import { builtin_netstat } from '../builtins/net/netstat.js';
 import { writeFileSync, appendFileSync } from 'fs';
 import chalk from 'chalk';
-import { builtin_cd, builtin_ls, builtin_pwd, builtin_connect, builtin_logout, builtin_cat, builtin_cp, builtin_mv, builtin_upload, builtin_pacs, builtin_pipeline, builtin_pull, builtin_query, builtin_cubepath, builtin_dcm, builtin_image, builtin_rm, builtin_setfacl, builtin_getfacl, builtin_chmod, builtin_setfattr, builtin_getfattr, builtin_touch, builtin_mkdir, builtin_rmdir, builtin_plugin, builtin_feed, builtin_compute, builtin_tag, builtin_expect, builtin_play, builtin_record, builtin_gather, builtin_group, builtin_user, builtin_pluginmeta, builtin_plugininstance, builtin_workflow, builtin_download, builtin_edit, builtin_config, builtin_files, builtin_links, builtin_dirs, builtin_context, builtin_parametersofplugin, builtin_physicalmode, builtin_timing, builtin_id, builtin_whoami, builtin_whereami, builtin_version, builtin_fortune, builtin_weather, builtin_motd, builtin_date, builtin_cal, builtin_debug, builtin_help, builtin_tree, builtin_du, builtin_store, error_stripDebugPrefix } from '../builtins/index.js';
-import { builtin_executePlugin } from '../builtins/pluginExecute.js';
-import { builtin_proc } from '../builtins/proc.js';
-import { shellWords_expand } from '../builtins/wildcard.js';
-import { help_render, commandHelp_get, pipelineExecutableHelp_render, args_checkHasHelpFlag, } from '../builtins/help.js';
-import { pluginExecutable_handle } from '../builtins/executable.js';
-import { errorStack, Ok, Err, envelope_error } from '@fnndsc/cumin';
-import { envelopeHandler_wrap, envelope_deliver, sink_get, PipeCaptureSink, sinkScope_run } from './sink.js';
+import { error_stripDebugPrefix } from './errorText.js';
+import { exitCode_read, handler_runDirect } from './handlerRun.js';
+import { backendInstalled_get } from './backend.js';
+import { shellWords_expand } from '../lib/wildcard.js';
+import { help_render, helpMissing_render, verb_available, commandHelp_get, args_checkHasHelpFlag, } from '../builtins/help.js';
+import { envelope_deliver, sink_get, PipeCaptureSink, sinkScope_run } from './sink.js';
 import { reference_refusal, reference_resolve, unresolvedStands_get, verbInHand_set } from './expansion.js';
 import { answer_note, answerConsulted_take } from '../session/answer.js';
-import { vfs } from '../lib/vfs/vfs.js';
 import { shellWords_referencesExpand, shellWords_tokenize, shellWords_values, } from '../lib/parser.js';
 import { surface_get, capability_require } from './surface.js';
 import { sudoCommand_run } from './elevation.js';
 import { redirectTarget_resolve, pathnameExpansion_isEligible, } from './preprocess.js';
-import { chiliCommand_run, chiliCommand_exists, chiliDelegationNotice_build } from './chiliDelegate.js';
-export { chiliCommand_run };
+import { envelope_error } from '@fnndsc/menu';
+import { errorStack, Ok, Err } from '@fnndsc/fond';
 /**
- * Handles a command chell does not recognize. If chili has no such command
- * either, reports `command not found` on the error channel and does not
- * delegate — no chili run, no context init. Otherwise emits the hand-off notice
- * on the live sink *before* running chili, so the notice appears ahead of
- * chili's (possibly slow) output rather than being glued on after it returns.
- *
- * @param command - The unrecognized command name.
- * @param args - The command's arguments.
- * @returns The delivered envelope (chili's result, or a not-found error).
- */
-async function unknownCommand_delegate(command, args) {
-    if (!(await chiliCommand_exists(command))) {
-        const envelope = envelope_error('', undefined, `${chalk.red(`chell: command not found: ${command}`)}\n`);
-        envelope_deliver(envelope);
-        return envelope;
-    }
-    sink_get().data_write(chiliDelegationNotice_build(command));
-    const chiliEnvelope = await chiliCommand_run(command, ['-s', ...args]);
-    envelope_deliver(chiliEnvelope);
-    return chiliEnvelope;
-}
-/**
- * Builtins that have been converted to return envelopes, keyed by command
- * name. Entries here are also present in COMMAND_HANDLERS in wrapped form;
- * this registry exists so envelope-aware hosts can bypass the wrapper and
- * receive the structured result.
+ * Shape of a converted builtin: returns its outcome as an envelope instead
+ * of printing. The engine layer will consume these directly; the dispatch
+ * table below consumes them through {@link envelopeHandler_wrap}.
  */
-export const ENVELOPE_HANDLERS = {
-    cat: builtin_cat,
-    cd: builtin_cd,
-    cp: builtin_cp,
-    mv: builtin_mv,
-    rm: builtin_rm,
-    setfacl: builtin_setfacl,
-    getfacl: builtin_getfacl,
-    chmod: builtin_chmod,
-    setfattr: builtin_setfattr,
-    getfattr: builtin_getfattr,
-    mkdir: builtin_mkdir,
-    rmdir: builtin_rmdir,
-    touch: builtin_touch,
-    pwd: builtin_pwd,
-    netstat: builtin_netstat,
-    id: builtin_id,
-    whoami: builtin_whoami,
-    whereami: builtin_whereami,
-    timing: builtin_timing,
-    physicalmode: builtin_physicalmode,
-    debug: builtin_debug,
-    version: builtin_version,
-    fortune: builtin_fortune,
-    cowsay: builtin_cowsay,
-    cowthink: builtin_cowthink,
-    figlet: builtin_figlet,
-    banner: builtin_banner,
-    lolcat: builtin_lolcat,
-    rev: builtin_rev,
-    tac: builtin_tac,
-    yes: builtin_yes,
-    seq: builtin_seq,
-    factor: builtin_factor,
-    primes: builtin_primes,
-    shuf: builtin_shuf,
-    roll: builtin_roll,
-    rot13: builtin_rot13,
-    morse: builtin_morse,
-    calc: builtin_calc,
-    units: builtin_units,
-    who: builtin_who,
-    uptime: builtin_uptime,
-    ping: builtin_ping,
-    chrisfetch: builtin_chrisfetch,
-    say: builtin_say,
-    wtf: builtin_wtf,
-    file: builtin_file,
-    xxd: builtin_xxd,
-    strings: builtin_strings,
-    sha256sum: builtin_sha256sum,
-    md5sum: builtin_md5sum,
-    qr: builtin_qr,
-    pom: builtin_pom,
-    stardate: builtin_stardate,
-    ddate: builtin_ddate,
-    sunrise: builtin_sunrise,
-    timer: builtin_timer,
-    leave: builtin_leave,
-    stopwatch: builtin_stopwatch,
-    sl: builtin_sl,
-    cmatrix: builtin_cmatrix,
-    rain: builtin_rain,
-    asciiquarium: builtin_asciiquarium,
-    tetris: builtin_tetris,
-    snake: builtin_snake,
-    quiz: builtin_quiz,
-    hangman: builtin_hangman,
-    '2048': builtin_2048,
-    weather: builtin_weather,
-    motd: builtin_motd,
-    notes: builtin_notes,
-    date: builtin_date,
-    cal: builtin_cal,
-    ls: builtin_ls,
-    tree: builtin_tree,
-    du: builtin_du,
-    help: builtin_help,
-    proc: builtin_proc,
-    logout: builtin_logout,
-    cubepath: builtin_cubepath,
-    dcm: builtin_dcm,
-    image: builtin_image,
-    query: builtin_query,
-    feed: builtin_feed,
-    feeds: builtin_feed,
-    compute: builtin_compute,
-    computes: builtin_compute,
-    tag: builtin_tag,
-    tags: builtin_tag,
-    expect: builtin_expect,
-    play: builtin_play,
-    record: builtin_record,
-    gather: builtin_gather,
-    group: builtin_group,
-    groups: builtin_group,
-    user: builtin_user,
-    users: builtin_user,
-    pluginmeta: builtin_pluginmeta,
-    pluginmetas: builtin_pluginmeta,
-    meta: builtin_pluginmeta,
-    metas: builtin_pluginmeta,
-    plugininstance: builtin_plugininstance,
-    plugininstances: builtin_plugininstance,
-    instance: builtin_plugininstance,
-    instances: builtin_plugininstance,
-    job: builtin_plugininstance,
-    jobs: builtin_plugininstance,
-    workflow: builtin_workflow,
-    workflows: builtin_workflow,
-    files: builtin_files,
-    links: builtin_links,
-    dirs: builtin_dirs,
-    context: builtin_context,
-    parametersofplugin: builtin_parametersofplugin,
-    plugin: builtin_plugin,
-    plugins: builtin_plugin,
-    pacsservers: (args) => chiliCommand_run('pacsservers', ['-s', ...args]),
-    pacsqueries: (args) => chiliCommand_run('pacsqueries', ['-s', ...args]),
-    pacsretrieve: (args) => chiliCommand_run('pacsretrieve', ['-s', ...args]),
-    connect: builtin_connect,
-    upload: builtin_upload,
-    download: builtin_download,
-    store: builtin_store,
-    edit: builtin_edit,
-    config: builtin_config,
-    pacs: builtin_pacs,
-    pull: builtin_pull,
-    pipeline: builtin_pipeline,
-    pipelines: builtin_pipeline,
-};
-export const COMMAND_HANDLERS = {
-    connect: envelopeHandler_wrap(builtin_connect),
-    logout: envelopeHandler_wrap(builtin_logout),
-    cd: envelopeHandler_wrap(builtin_cd),
-    ls: envelopeHandler_wrap(builtin_ls),
-    pwd: envelopeHandler_wrap(builtin_pwd),
-    netstat: envelopeHandler_wrap(builtin_netstat),
-    cat: envelopeHandler_wrap(builtin_cat),
-    rm: envelopeHandler_wrap(builtin_rm),
-    setfacl: envelopeHandler_wrap(builtin_setfacl),
-    getfacl: envelopeHandler_wrap(builtin_getfacl),
-    chmod: envelopeHandler_wrap(builtin_chmod),
-    setfattr: envelopeHandler_wrap(builtin_setfattr),
-    getfattr: envelopeHandler_wrap(builtin_getfattr),
-    cp: envelopeHandler_wrap(builtin_cp),
-    mv: envelopeHandler_wrap(builtin_mv),
-    touch: envelopeHandler_wrap(builtin_touch),
-    mkdir: envelopeHandler_wrap(builtin_mkdir),
-    rmdir: envelopeHandler_wrap(builtin_rmdir),
-    upload: envelopeHandler_wrap(builtin_upload),
-    pacs: envelopeHandler_wrap(builtin_pacs),
-    pipeline: envelopeHandler_wrap(builtin_pipeline),
-    pipelines: envelopeHandler_wrap(builtin_pipeline),
-    pull: envelopeHandler_wrap(builtin_pull),
-    query: envelopeHandler_wrap(builtin_query),
-    cubepath: envelopeHandler_wrap(builtin_cubepath),
-    dcm: envelopeHandler_wrap(builtin_dcm),
-    image: envelopeHandler_wrap(builtin_image),
-    download: envelopeHandler_wrap(builtin_download),
-    edit: envelopeHandler_wrap(builtin_edit),
-    config: envelopeHandler_wrap(builtin_config),
-    context: envelopeHandler_wrap(builtin_context),
-    parametersofplugin: envelopeHandler_wrap(builtin_parametersofplugin),
-    physicalmode: envelopeHandler_wrap(builtin_physicalmode),
-    timing: envelopeHandler_wrap(builtin_timing),
-    id: envelopeHandler_wrap(builtin_id),
-    whoami: envelopeHandler_wrap(builtin_whoami),
-    whereami: envelopeHandler_wrap(builtin_whereami),
-    debug: envelopeHandler_wrap(builtin_debug),
-    fortune: envelopeHandler_wrap(builtin_fortune),
-    cowsay: envelopeHandler_wrap(builtin_cowsay),
-    cowthink: envelopeHandler_wrap(builtin_cowthink),
-    figlet: envelopeHandler_wrap(builtin_figlet),
-    banner: envelopeHandler_wrap(builtin_banner),
-    lolcat: envelopeHandler_wrap(builtin_lolcat),
-    rev: envelopeHandler_wrap(builtin_rev),
-    tac: envelopeHandler_wrap(builtin_tac),
-    yes: envelopeHandler_wrap(builtin_yes),
-    seq: envelopeHandler_wrap(builtin_seq),
-    factor: envelopeHandler_wrap(builtin_factor),
-    primes: envelopeHandler_wrap(builtin_primes),
-    shuf: envelopeHandler_wrap(builtin_shuf),
-    roll: envelopeHandler_wrap(builtin_roll),
-    rot13: envelopeHandler_wrap(builtin_rot13),
-    morse: envelopeHandler_wrap(builtin_morse),
-    calc: envelopeHandler_wrap(builtin_calc),
-    units: envelopeHandler_wrap(builtin_units),
-    who: envelopeHandler_wrap(builtin_who),
-    uptime: envelopeHandler_wrap(builtin_uptime),
-    ping: envelopeHandler_wrap(builtin_ping),
-    chrisfetch: envelopeHandler_wrap(builtin_chrisfetch),
-    say: envelopeHandler_wrap(builtin_say),
-    wtf: envelopeHandler_wrap(builtin_wtf),
-    file: envelopeHandler_wrap(builtin_file),
-    xxd: envelopeHandler_wrap(builtin_xxd),
-    strings: envelopeHandler_wrap(builtin_strings),
-    sha256sum: envelopeHandler_wrap(builtin_sha256sum),
-    md5sum: envelopeHandler_wrap(builtin_md5sum),
-    qr: envelopeHandler_wrap(builtin_qr),
-    pom: envelopeHandler_wrap(builtin_pom),
-    stardate: envelopeHandler_wrap(builtin_stardate),
-    ddate: envelopeHandler_wrap(builtin_ddate),
-    sunrise: envelopeHandler_wrap(builtin_sunrise),
-    timer: envelopeHandler_wrap(builtin_timer),
-    leave: envelopeHandler_wrap(builtin_leave),
-    stopwatch: envelopeHandler_wrap(builtin_stopwatch),
-    sl: envelopeHandler_wrap(builtin_sl),
-    cmatrix: envelopeHandler_wrap(builtin_cmatrix),
-    rain: envelopeHandler_wrap(builtin_rain),
-    asciiquarium: envelopeHandler_wrap(builtin_asciiquarium),
-    tetris: envelopeHandler_wrap(builtin_tetris),
-    snake: envelopeHandler_wrap(builtin_snake),
-    quiz: envelopeHandler_wrap(builtin_quiz),
-    hangman: envelopeHandler_wrap(builtin_hangman),
-    '2048': envelopeHandler_wrap(builtin_2048),
-    weather: envelopeHandler_wrap(builtin_weather),
-    motd: envelopeHandler_wrap(builtin_motd),
-    notes: envelopeHandler_wrap(builtin_notes),
-    date: envelopeHandler_wrap(builtin_date),
-    cal: envelopeHandler_wrap(builtin_cal),
-    help: envelopeHandler_wrap(builtin_help),
-    proc: envelopeHandler_wrap(builtin_proc),
-    tree: envelopeHandler_wrap(builtin_tree),
-    du: envelopeHandler_wrap(builtin_du),
-    store: envelopeHandler_wrap(builtin_store),
-    plugin: envelopeHandler_wrap(builtin_plugin),
-    plugins: envelopeHandler_wrap(builtin_plugin),
-    feed: envelopeHandler_wrap(builtin_feed),
-    feeds: envelopeHandler_wrap(builtin_feed),
-    compute: envelopeHandler_wrap(builtin_compute),
-    computes: envelopeHandler_wrap(builtin_compute),
-    tag: envelopeHandler_wrap(builtin_tag),
-    tags: envelopeHandler_wrap(builtin_tag),
-    expect: envelopeHandler_wrap(builtin_expect),
-    play: envelopeHandler_wrap(builtin_play),
-    record: envelopeHandler_wrap(builtin_record),
-    gather: envelopeHandler_wrap(builtin_gather),
-    group: envelopeHandler_wrap(builtin_group),
-    groups: envelopeHandler_wrap(builtin_group),
-    pluginmeta: envelopeHandler_wrap(builtin_pluginmeta),
-    pluginmetas: envelopeHandler_wrap(builtin_pluginmeta),
-    meta: envelopeHandler_wrap(builtin_pluginmeta),
-    metas: envelopeHandler_wrap(builtin_pluginmeta),
-    plugininstance: envelopeHandler_wrap(builtin_plugininstance),
-    plugininstances: envelopeHandler_wrap(builtin_plugininstance),
-    instance: envelopeHandler_wrap(builtin_plugininstance),
-    instances: envelopeHandler_wrap(builtin_plugininstance),
-    job: envelopeHandler_wrap(builtin_plugininstance),
-    jobs: envelopeHandler_wrap(builtin_plugininstance),
-    workflow: envelopeHandler_wrap(builtin_workflow),
-    workflows: envelopeHandler_wrap(builtin_workflow),
-    files: envelopeHandler_wrap(builtin_files),
-    links: envelopeHandler_wrap(builtin_links),
-    dirs: envelopeHandler_wrap(builtin_dirs),
-    pacsservers: envelopeHandler_wrap((args) => chiliCommand_run('pacsservers', ['-s', ...args])),
-    pacsqueries: envelopeHandler_wrap((args) => chiliCommand_run('pacsqueries', ['-s', ...args])),
-    pacsretrieve: envelopeHandler_wrap((args) => chiliCommand_run('pacsretrieve', ['-s', ...args])),
-};
-export { COMMAND_HANDLERS_KEYS } from '../command-keys.js';
+// The engine registers its core commands and the order commands list in; a
+// backend registers its own beside them (the ChRIS backend's from brasa's
+// entry). Every lookup below goes through the registry.
+commands_register(coreCommands);
+commandOrder_set({ envelope: ENVELOPE_ORDER, plain: PLAIN_ORDER, help: HELP_ORDER });
+export { ENVELOPE_HANDLERS, COMMAND_HANDLERS } from './commandRegistry.js';
 /**
  * Prints elapsed time since startTime if timing is enabled.
  *
@@ -348,101 +55,6 @@ export function command_timingMaybePrint(startTime, enabled) {
     const elapsed = performance.now() - startTime;
     sink_get().data_write(`${chalk.gray(`[${elapsed.toFixed(2)}ms]`)}\n`);
 }
-/**
- * Handles a pipeline name invoked directly as an executable from /bin.
- * Routes flag combinations to the appropriate pipeline subcommand:
- *   --diagram             → pipeline diagram (preserving renderer flags)
- *   --signalflow          → pipeline diagram --signalflow
- *   --help / -h           → contextual pipeline-executable help
- *   --nodes / --parameters → pipeline info
- *   --manifest             → pipeline manifest
- *   --source / --readme    → pipeline source
- *   (bare or --compute)    → pipeline run
- *
- * @param name - The pipeline name as typed.
- * @param args - Arguments following the pipeline name.
- * @returns The pipeline builtin's envelope, preserving diagram models and text.
- */
-async function pipelineExecutable_handle(name, args) {
-    const exitCodeBefore = exitCode_read();
-    let envelope;
-    if (args.includes('--help') || args.includes('-h')) {
-        envelope = { status: 'ok', rendered: pipelineExecutableHelp_render(name) };
-    }
-    else if (args.includes('--diagram')) {
-        const diagramArgs = args.filter((argument) => argument !== '--diagram');
-        envelope = await builtin_pipeline(['diagram', name, ...diagramArgs]);
-    }
-    else if (args.includes('--signalflow')) {
-        envelope = await builtin_pipeline(['diagram', name, '--signalflow']);
-    }
-    else if (args.includes('--manifest')) {
-        envelope = await builtin_pipeline(['manifest', name]);
-    }
-    else if (args.includes('--nodes') || args.includes('--parameters')) {
-        envelope = await builtin_pipeline(['info', name]);
-    }
-    else if (args.includes('--source') || args.includes('--readme')) {
-        envelope = await builtin_pipeline(['source', name]);
-    }
-    else {
-        envelope = await builtin_pipeline(['run', name, ...args]);
-    }
-    const result = envelope ?? { status: 'ok', rendered: '' };
-    const exitCodeAfter = exitCode_read();
-    if (exitCodeAfter !== 0 && exitCodeAfter !== exitCodeBefore)
-        result.status = 'error';
-    return result;
-}
-/**
- * Finds exact plugin and pipeline executable matches in the virtual `/bin`.
- *
- * @param command - Executable name as typed.
- * @returns Matching dynamic executable entries, if the listing is available.
- */
-async function binExecutableMatches_get(command) {
-    const binResult = await vfs.data_get('/bin');
-    if (!binResult.ok) {
-        return { plugin: undefined, pipeline: undefined };
-    }
-    return {
-        plugin: binResult.value.find((item) => item.name === command && item.type === 'plugin'),
-        pipeline: binResult.value.find((item) => item.name === command && item.type === 'pipeline'),
-    };
-}
-/**
- * Reads the current process exit code as a number.
- *
- * @returns The exit code, treating an unset code as zero.
- */
-function exitCode_read() {
-    return typeof process.exitCode === 'number' ? process.exitCode : 0;
-}
-/**
- * Runs a printing handler uncaptured, preserving an explicit envelope or
- * deriving one from the exit-code delta for legacy handlers.
- *
- * This is the passthrough for commands that cannot be captured yet: the
- * interactive holdouts (their prompts must reach the terminal) and the
- * progress writers (their live updates must stay live). The handler prints
- * exactly as it always has; the placeholder envelope records only the
- * outcome, with no rendered text, so envelope consumers never re-print what
- * the terminal already showed. Migrated handlers may return that envelope
- * directly while retaining the same live-output behavior.
- *
- * @param handler - A legacy printing command handler.
- * @param args - Parsed arguments.
- * @returns A placeholder envelope carrying the command's outcome.
- */
-async function handler_runDirect(handler, args) {
-    const exitCodeBefore = exitCode_read();
-    const explicitEnvelope = await handler(args);
-    if (explicitEnvelope !== undefined)
-        return explicitEnvelope;
-    const exitCodeAfter = exitCode_read();
-    const failed = exitCodeAfter !== 0 && exitCodeAfter !== exitCodeBefore;
-    return { status: failed ? 'error' : 'ok', rendered: '' };
-}
 /**
  * Drains the errorStack from a checkpoint into an envelope's structured
  * `errors` field, and escalates status to `error` when an error-type message
@@ -484,8 +96,8 @@ export async function command_dispatchEnvelope(command, args) {
 }
 /**
  * Runs the dispatch itself (without the error drain). Expands environment
- * references in the arguments, then checks ENVELOPE_HANDLERS, then
- * unconverted COMMAND_HANDLERS, then /bin plugin/pipeline names, then falls
+ * references in the arguments, then checks the registry's envelope handlers,
+ * then its plain handlers, then /bin plugin/pipeline names, then falls
  * back to chili through the capture bridge.
  *
  * Envelope-speaking handlers are delivered through the active sink here, so
@@ -501,9 +113,18 @@ async function commandDispatchEnvelope_run(command, args) {
         process.exit(0);
     }
     if (command === 'sudo') {
-        return await sudoCommand_run(args, commandDispatchEnvelope_run);
+        // The nested command delivers its own envelope; sudo's own refusals
+        // (usage, nesting, no administrator, credentials) are delivered here.
+        let nestedRan = false;
+        const envelope = await sudoCommand_run(args, async (nested, nestedArgs) => {
+            nestedRan = true;
+            return commandDispatchEnvelope_run(nested, nestedArgs);
+        });
+        if (!nestedRan)
+            envelope_deliver(envelope);
+        return envelope;
     }
-    const envelopeHandler = ENVELOPE_HANDLERS[command];
+    const envelopeHandler = envelopeHandler_get(command);
     if (envelopeHandler) {
         // A handler that resolves without an envelope (as stubbed handlers in
         // tests do) is treated as having produced no output.
@@ -514,22 +135,39 @@ async function commandDispatchEnvelope_run(command, args) {
         envelope_deliver(envelope);
         return envelope;
     }
-    const handler = COMMAND_HANDLERS[command];
+    const handler = plainHandler_get(command);
     if (handler) {
         return handler_runDirect(handler, args);
     }
-    const binMatches = await binExecutableMatches_get(command);
-    if (binMatches.plugin) {
-        return handler_runDirect((pluginArgs) => builtin_executePlugin(command, pluginArgs), args);
-    }
-    if (binMatches.pipeline) {
-        const envelope = await pipelineExecutable_handle(command, args);
-        envelope_deliver(envelope);
-        return envelope;
-    }
-    // Unknown commands are guarded, then delegated to chili — its output is
-    // captured through its own seam, with no console capture here.
-    return unknownCommand_delegate(command, args);
+    return unknownCommand_handle(command, args, false);
+}
+/**
+ * Hands a word nothing registered answers to the backend, and says
+ * `command not found` when the backend does not know it either.
+ *
+ * @param command - The word.
+ * @param args - Its arguments.
+ * @param captured - Whether the line's output is being captured.
+ * @returns The delivered envelope.
+ */
+async function unknownCommand_handle(command, args, captured) {
+    const answered = (await backendInstalled_get()?.fallback?.unknown?.(command, args, captured)) ?? null;
+    if (answered !== null)
+        return answered;
+    const envelope = envelope_error('', undefined, `${chalk.red(`chell: command not found: ${command}`)}\n`);
+    envelope_deliver(envelope);
+    return envelope;
+}
+/**
+ * A word the backend claims ahead of the registry (ChRIS: a plugin named
+ * with its version).
+ *
+ * @param command - The word.
+ * @param args - Its arguments.
+ * @returns The backend's envelope, or null when it does not claim the word.
+ */
+async function commandClaim_try(command, args) {
+    return (await backendInstalled_get()?.fallback?.claim?.(command, args)) ?? null;
 }
 /**
  * Dispatches a parsed command to its handler.
@@ -553,7 +191,12 @@ export async function command_dispatch(command, args) {
  *   because the output went to the file, not the terminal.
  */
 export async function redirect_execute(redirectInfo) {
-    const { buffer } = await chellCommand_executeAndCapture(redirectInfo.command);
+    const { buffer, model } = await chellCommand_executeAndCapture(redirectInfo.command);
+    // The rows went to a file, but the command still answered with them: an
+    // index after `ls > listing.txt` counts them as it would after `ls`.
+    if (model !== undefined) {
+        answer_note(model.kind, model.data, redirectInfo.command.trim());
+    }
     const targetResult = redirectTarget_resolve(redirectInfo.filePath, redirectInfo.command);
     if (!targetResult.ok) {
         const lastError = errorStack.stack_pop();
@@ -583,14 +226,12 @@ async function helpEnvelope_maybe(command, args) {
         return null;
     }
     let rendered;
-    if (commandHelp_get(command) !== undefined) {
+    if (commandHelp_get(command) !== undefined && verb_available(command)) {
         rendered = help_render(command);
     }
     else {
-        const binMatches = await binExecutableMatches_get(command);
-        rendered = binMatches.pipeline
-            ? pipelineExecutableHelp_render(command)
-            : help_render(command);
+        const backendHelp = (await backendInstalled_get()?.fallback?.help?.(command)) ?? null;
+        rendered = backendHelp ?? helpMissing_render(command);
     }
     const envelope = { status: 'ok', rendered };
     envelope_deliver(envelope);
@@ -646,7 +287,7 @@ async function commandWords_expand(command, args) {
 }
 /**
  * Executes a chell command and captures its output.
- * Consults COMMAND_HANDLERS — the single source of truth — so the pipe path
+ * Consults the command registry — the single source of truth — so the pipe path
  * is always consistent with the direct-execution path.
  *
  * @param commandLine - The command line to execute.
@@ -687,38 +328,36 @@ async function chellCommand_executeAndCapture(commandLine) {
     // streaming commands and binary cat write to the same sink directly (raw
     // bytes kept byte-for-byte). The err channel passes through to stderr live.
     const pipeSink = new PipeCaptureSink(sink_get());
+    let model;
     await sinkScope_run(pipeSink, async () => {
         const helpEnvelope = await helpEnvelope_maybe(command, args);
         if (helpEnvelope)
             return;
-        const envelopeHandler = ENVELOPE_HANDLERS[command];
+        const envelopeHandler = envelopeHandler_get(command);
         if (envelopeHandler) {
             const envelope = await envelopeHandler(args);
             if (envelope) {
                 envelope_deliver(envelope);
+                model = envelope.model;
             }
             return;
         }
-        const pluginEnvelope = await pluginExecutable_handle(command, args);
-        if (pluginEnvelope) {
-            envelope_deliver(pluginEnvelope);
+        const claimed = await commandClaim_try(command, args);
+        if (claimed) {
+            envelope_deliver(claimed);
+            model = claimed.model;
             return;
         }
-        const handler = COMMAND_HANDLERS[command];
+        const handler = plainHandler_get(command);
         if (handler) {
             await handler(args);
             return;
         }
-        const binMatches = await binExecutableMatches_get(command);
-        if (binMatches.pipeline) {
-            const envelope = await pipelineExecutable_handle(command, args);
-            envelope_deliver(envelope);
-            return;
-        }
-        await unknownCommand_delegate(command, args);
+        const answered = await unknownCommand_handle(command, args, true);
+        model = answered.model;
     });
     const buffer = pipeSink.buffer_get();
-    return { text: buffer.toString('utf-8'), buffer };
+    return { text: buffer.toString('utf-8'), buffer, ...(model !== undefined ? { model } : {}) };
 }
 /**
  * Executes a pipe chain by running the first command in chell and piping
@@ -743,7 +382,7 @@ export async function pipe_execute(segments) {
     for (let i = 1; i < segments.length; i++) {
         const segment = segments[i];
         const word = segment.trim().split(/\s+/)[0] ?? '';
-        if (word !== '' && (word in ENVELOPE_HANDLERS || word in COMMAND_HANDLERS)) {
+        if (word !== '' && builtinCommand_has(word)) {
             stdin_set(currentInput.toString('utf-8'));
             try {
                 currentInput = (await chellCommand_executeAndCapture(segment)).buffer;
@@ -816,7 +455,7 @@ export async function command_executeToEnvelope(trimmedLine, startTime, timingEn
     // command_dispatchEnvelope, so it drains the errorStack itself.
     const checkpoint = errorStack.checkpoint_mark();
     const exitCodeBefore = exitCode_read();
-    const pluginEnvelope = await pluginExecutable_handle(command, args);
+    const pluginEnvelope = await commandClaim_try(command, args);
     if (pluginEnvelope) {
         envelope_deliver(pluginEnvelope);
         command_timingMaybePrint(startTime, timingEnabled);