@fnndsc/chell 4.3.2 → 4.4.0

package/dist/core/dispatch.js

@@ -1,31 +1,32 @@
 /**
- * @file Command parsing and dispatch for the ChELL shell.
+ * @file Command dispatch for the ChELL shell.
  *
- * Turns a line of user input into an executed command:
- * - preprocessing (inline shell escape, semicolon batching, redirects, pipes, wildcards, help)
+ * Turns one parsed command into an executed command with an envelope result:
  * - the built-in command table and dispatch to built-ins, simulated plugin exec, or `chili`
  * - output capture for the redirect/pipe paths
+ * - envelope-producing execution used by the engine facade
  *
- * The startup/connection/REPL glue that drives this layer lives in `./boot.js`.
+ * Line-level orchestration (shell escape, semicolon batching, redirect and
+ * pipe detection) lives in `./engine.js`; the startup/connection/REPL glue
+ * lives in `./boot.js`.
  *
  * @module
  */
 import { writeFileSync, appendFileSync } from 'fs';
 import chalk from 'chalk';
 import { spawn } from 'child_process';
-import { session } from '../session/index.js';
-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_rm, builtin_touch, builtin_mkdir, builtin_plugin, builtin_feed, builtin_compute, builtin_tag, builtin_group, builtin_pluginmeta, builtin_plugininstance, builtin_workflow, builtin_download, builtin_edit, builtin_files, builtin_links, builtin_dirs, builtin_context, builtin_parametersofplugin, builtin_physicalmode, builtin_prompt, builtin_timing, builtin_whoami, builtin_whereami, builtin_debug, builtin_help, builtin_tree, builtin_du, builtin_store, error_stripDebugPrefix } from '../builtins/index.js';
+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_rm, builtin_touch, builtin_mkdir, builtin_plugin, builtin_feed, builtin_compute, builtin_tag, builtin_group, builtin_pluginmeta, builtin_plugininstance, builtin_workflow, builtin_download, builtin_edit, builtin_files, builtin_links, builtin_dirs, builtin_context, builtin_parametersofplugin, builtin_physicalmode, builtin_prompt, builtin_timing, builtin_whoami, builtin_whereami, builtin_version, 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 { wildcards_expandAll } from '../builtins/wildcard.js';
 import { help_show, args_checkHasHelpFlag } from '../builtins/help.js';
 import { pluginExecutable_handle } from '../builtins/executable.js';
 import { errorStack, Ok, Err } from '@fnndsc/cumin';
+import { envelopeHandler_wrap, printingHandler_wrap, ansi_strip, envelope_deliver, sink_get } from './sink.js';
 import { vfs } from '../lib/vfs/vfs.js';
 import { args_tokenize } from '../lib/parser.js';
-import { semicolons_parse } from '../lib/semicolonParser.js';
-import { segment_pipeThrough } from '../lib/pipe.js';
-import { pipes_parse, redirect_parse, redirectTarget_resolve, wildcards_expandCheck, command_shellEscape_detect, } from './preprocess.js';
+import { surface_get, capability_require } from './surface.js';
+import { redirectTarget_resolve, wildcards_expandCheck, } from './preprocess.js';
 import { run as chiliRun } from '@fnndsc/chili/run.js';
 /**
  * Spawns the `chili` CLI as a child process.
@@ -49,9 +50,9 @@ export async function chiliCommand_run(command, args) {
  * Executes a shell command on the host system (shell escape with ! prefix).
  *
  * @param shellCommand - The command to execute on the host shell.
- * @returns A Promise that resolves when the command completes.
+ * @returns A Promise resolving to the command's exit code (1 on spawn failure).
  */
-async function shellCommand_execute(shellCommand) {
+export async function shellCommand_execute(shellCommand) {
     return new Promise((resolve) => {
         const child = spawn(shellCommand, {
             shell: true,
@@ -62,74 +63,14 @@ async function shellCommand_execute(shellCommand) {
             if (code !== null && code !== 0) {
                 console.error(chalk.red(`Shell command exited with code ${code}`));
             }
-            resolve();
+            resolve(code ?? 0);
         });
         child.on('error', (err) => {
             console.error(chalk.red(`Failed to execute shell command: ${err.message}`));
-            resolve();
+            resolve(1);
         });
     });
 }
-/**
- * Handles a command entered by the user.
- *
- * @param line - The input line.
- * @returns A Promise that resolves once the command has been processed.
- */
-export async function command_handle(line) {
-    const trimmedLine = line.trim();
-    if (!trimmedLine)
-        return;
-    // Start timing if enabled
-    const timingEnabled = session.timingEnabled_get();
-    const startTime = timingEnabled ? performance.now() : 0;
-    if (command_shellEscape_detect(trimmedLine)) {
-        await shellEscape_handle(trimmedLine, startTime, timingEnabled);
-        return;
-    }
-    const semicolonResult = await semicolons_handle(trimmedLine, startTime, timingEnabled);
-    if (!semicolonResult.ok) {
-        return;
-    }
-    if (semicolonResult.value)
-        return;
-    const redirectResult = await redirect_handle(trimmedLine, startTime, timingEnabled);
-    if (!redirectResult.ok) {
-        return;
-    }
-    if (redirectResult.value)
-        return;
-    const pipeResult = await pipe_handle(trimmedLine, startTime, timingEnabled);
-    if (!pipeResult.ok) {
-        return;
-    }
-    if (pipeResult.value)
-        return;
-    const tokens = args_tokenize(trimmedLine);
-    if (tokens.length === 0)
-        return;
-    let [command, ...args] = tokens;
-    // Check for --help flag before any processing
-    const helpResult = help_showMaybe(command, args);
-    if (helpResult.ok && helpResult.value) {
-        return;
-    }
-    // Expand wildcards for commands that support it
-    const expandResult = await wildcards_expand(command, args);
-    if (!expandResult.ok) {
-        return;
-    }
-    args = expandResult.value;
-    // Attempt to handle as a simulated plugin execution
-    if (await pluginExecutable_handle(command, args)) {
-        // Display timing if enabled
-        command_timingMaybePrint(startTime, timingEnabled);
-        return;
-    }
-    await command_dispatch(command, args);
-    // Display timing if enabled
-    command_timingMaybePrint(startTime, timingEnabled);
-}
 /**
  * Captures console output during command execution.
  *
@@ -170,65 +111,134 @@ async function output_capture(fn) {
     const text = buffer.toString('utf-8');
     return { text, buffer };
 }
-export const COMMAND_HANDLERS = {
-    connect: builtin_connect,
-    logout: builtin_logout,
-    cd: builtin_cd,
-    ls: builtin_ls,
-    pwd: builtin_pwd,
+/**
+ * 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.
+ */
+/**
+ * Composes the capture bridge with envelope delivery, so a legacy printing
+ * handler participates in the dispatch table with envelope semantics and
+ * unchanged observable output.
+ *
+ * @param handler - A legacy printing command handler.
+ * @returns A wrapped handler for the dispatch table.
+ */
+function printingBridge_wrap(handler) {
+    return envelopeHandler_wrap(printingHandler_wrap(handler));
+}
+export const ENVELOPE_HANDLERS = {
     cat: builtin_cat,
-    rm: builtin_rm,
+    cd: builtin_cd,
     cp: builtin_cp,
     mv: builtin_mv,
-    touch: builtin_touch,
+    rm: builtin_rm,
     mkdir: builtin_mkdir,
+    touch: builtin_touch,
+    pwd: builtin_pwd,
+    whoami: builtin_whoami,
+    whereami: builtin_whereami,
+    timing: builtin_timing,
+    physicalmode: builtin_physicalmode,
+    debug: builtin_debug,
+    version: builtin_version,
+    // Bridged (captured) handlers: envelope semantics without typed models.
+    // plugin is deliberately absent: its add flow prompts for admin
+    // credentials through readline, which capture would make invisible.
+    ls: printingHandler_wrap(builtin_ls),
+    tree: printingHandler_wrap(builtin_tree),
+    du: printingHandler_wrap(builtin_du),
+    help: printingHandler_wrap(builtin_help),
+    proc: printingHandler_wrap(builtin_proc),
+    logout: printingHandler_wrap(builtin_logout),
+    cubepath: printingHandler_wrap(builtin_cubepath),
+    query: printingHandler_wrap(builtin_query),
+    feed: printingHandler_wrap(builtin_feed),
+    feeds: printingHandler_wrap(builtin_feed),
+    compute: printingHandler_wrap(builtin_compute),
+    computes: printingHandler_wrap(builtin_compute),
+    tag: printingHandler_wrap(builtin_tag),
+    tags: printingHandler_wrap(builtin_tag),
+    group: printingHandler_wrap(builtin_group),
+    groups: printingHandler_wrap(builtin_group),
+    pluginmeta: printingHandler_wrap(builtin_pluginmeta),
+    pluginmetas: printingHandler_wrap(builtin_pluginmeta),
+    meta: printingHandler_wrap(builtin_pluginmeta),
+    metas: printingHandler_wrap(builtin_pluginmeta),
+    plugininstance: printingHandler_wrap(builtin_plugininstance),
+    plugininstances: printingHandler_wrap(builtin_plugininstance),
+    instance: printingHandler_wrap(builtin_plugininstance),
+    instances: printingHandler_wrap(builtin_plugininstance),
+    job: printingHandler_wrap(builtin_plugininstance),
+    jobs: printingHandler_wrap(builtin_plugininstance),
+    workflow: printingHandler_wrap(builtin_workflow),
+    workflows: printingHandler_wrap(builtin_workflow),
+    files: printingHandler_wrap(builtin_files),
+    links: printingHandler_wrap(builtin_links),
+    dirs: printingHandler_wrap(builtin_dirs),
+    context: printingHandler_wrap(builtin_context),
+    parametersofplugin: printingHandler_wrap(builtin_parametersofplugin),
+};
+export const COMMAND_HANDLERS = {
+    connect: builtin_connect,
+    logout: printingBridge_wrap(builtin_logout),
+    cd: envelopeHandler_wrap(builtin_cd),
+    ls: printingBridge_wrap(builtin_ls),
+    pwd: envelopeHandler_wrap(builtin_pwd),
+    cat: envelopeHandler_wrap(builtin_cat),
+    rm: envelopeHandler_wrap(builtin_rm),
+    cp: envelopeHandler_wrap(builtin_cp),
+    mv: envelopeHandler_wrap(builtin_mv),
+    touch: envelopeHandler_wrap(builtin_touch),
+    mkdir: envelopeHandler_wrap(builtin_mkdir),
     upload: builtin_upload,
     pacs: builtin_pacs,
     pipeline: builtin_pipeline,
     pipelines: builtin_pipeline,
     pull: builtin_pull,
-    query: builtin_query,
-    cubepath: builtin_cubepath,
+    query: printingBridge_wrap(builtin_query),
+    cubepath: printingBridge_wrap(builtin_cubepath),
     download: builtin_download,
     edit: builtin_edit,
-    context: builtin_context,
-    parametersofplugin: builtin_parametersofplugin,
-    physicalmode: builtin_physicalmode,
+    context: printingBridge_wrap(builtin_context),
+    parametersofplugin: printingBridge_wrap(builtin_parametersofplugin),
+    physicalmode: envelopeHandler_wrap(builtin_physicalmode),
     prompt: builtin_prompt,
-    timing: builtin_timing,
-    whoami: builtin_whoami,
-    whereami: builtin_whereami,
-    debug: builtin_debug,
-    help: builtin_help,
-    proc: builtin_proc,
-    tree: builtin_tree,
-    du: builtin_du,
+    timing: envelopeHandler_wrap(builtin_timing),
+    whoami: envelopeHandler_wrap(builtin_whoami),
+    whereami: envelopeHandler_wrap(builtin_whereami),
+    debug: envelopeHandler_wrap(builtin_debug),
+    help: printingBridge_wrap(builtin_help),
+    proc: printingBridge_wrap(builtin_proc),
+    tree: printingBridge_wrap(builtin_tree),
+    du: printingBridge_wrap(builtin_du),
     store: builtin_store,
     plugin: builtin_plugin,
     plugins: builtin_plugin,
-    feed: builtin_feed,
-    feeds: builtin_feed,
-    compute: builtin_compute,
-    computes: builtin_compute,
-    tag: builtin_tag,
-    tags: builtin_tag,
-    group: builtin_group,
-    groups: builtin_group,
-    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,
+    feed: printingBridge_wrap(builtin_feed),
+    feeds: printingBridge_wrap(builtin_feed),
+    compute: printingBridge_wrap(builtin_compute),
+    computes: printingBridge_wrap(builtin_compute),
+    tag: printingBridge_wrap(builtin_tag),
+    tags: printingBridge_wrap(builtin_tag),
+    group: printingBridge_wrap(builtin_group),
+    groups: printingBridge_wrap(builtin_group),
+    pluginmeta: printingBridge_wrap(builtin_pluginmeta),
+    pluginmetas: printingBridge_wrap(builtin_pluginmeta),
+    meta: printingBridge_wrap(builtin_pluginmeta),
+    metas: printingBridge_wrap(builtin_pluginmeta),
+    plugininstance: printingBridge_wrap(builtin_plugininstance),
+    plugininstances: printingBridge_wrap(builtin_plugininstance),
+    instance: printingBridge_wrap(builtin_plugininstance),
+    instances: printingBridge_wrap(builtin_plugininstance),
+    job: printingBridge_wrap(builtin_plugininstance),
+    jobs: printingBridge_wrap(builtin_plugininstance),
+    workflow: printingBridge_wrap(builtin_workflow),
+    workflows: printingBridge_wrap(builtin_workflow),
+    files: printingBridge_wrap(builtin_files),
+    links: printingBridge_wrap(builtin_links),
+    dirs: printingBridge_wrap(builtin_dirs),
     pacsservers: async (args) => {
         await chiliCommand_run('pacsservers', ['-s', ...args]);
     },
@@ -246,7 +256,7 @@ export { COMMAND_HANDLERS_KEYS } from '../command-keys.js';
  * @param startTime - Timestamp from `performance.now()` at command start.
  * @param enabled - Whether timing display is active.
  */
-function command_timingMaybePrint(startTime, enabled) {
+export function command_timingMaybePrint(startTime, enabled) {
     if (!enabled)
         return;
     const elapsed = performance.now() - startTime;
@@ -293,103 +303,155 @@ export function envRefs_expand(token) {
     });
 }
 /**
- * Dispatches a parsed command to its handler.
- * Expands environment references in the arguments, then checks
- * COMMAND_HANDLERS, then /bin plugin names, then falls back to chili.
+ * 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 legacy printing handler uncaptured and derives an envelope from the
+ * exit-code delta.
+ *
+ * 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.
+ *
+ * @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();
+    await handler(args);
+    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
+ * was drained.
+ *
+ * This is the per-command error boundary: it captures exactly the messages a
+ * command left on the stack, so a remote surface receives full error detail
+ * with each result and stale errors cannot bleed into the next command.
+ * Escalating status from a drained error is a reliable per-command failure
+ * signal, independent of whether the command happened to change
+ * `process.exitCode`.
+ *
+ * @param checkpoint - A checkpoint from `errorStack.checkpoint_mark()`.
+ * @param envelope - The envelope to attach drained errors to.
+ * @returns The same envelope, with errors and possibly status updated.
+ */
+function envelope_drainErrorsInto(checkpoint, envelope) {
+    const drained = errorStack.checkpoint_drain(checkpoint);
+    if (drained.length > 0) {
+        envelope.errors = drained;
+        if (envelope.status === 'ok' && drained.some((message) => message.type === 'error')) {
+            envelope.status = 'error';
+        }
+    }
+    return envelope;
+}
+/**
+ * Dispatches a parsed command to its handler and returns its envelope, with
+ * any errors the command left on the stack drained into the envelope.
  *
  * @param command - The command name.
  * @param args - Parsed arguments.
+ * @returns The envelope of the executed command.
  */
-export async function command_dispatch(command, args) {
+export async function command_dispatchEnvelope(command, args) {
+    const checkpoint = errorStack.checkpoint_mark();
+    const envelope = await commandDispatchEnvelope_run(command, args);
+    return envelope_drainErrorsInto(checkpoint, envelope);
+}
+/**
+ * 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
+ * back to chili through the capture bridge.
+ *
+ * Envelope-speaking handlers are delivered through the active sink here, so
+ * direct execution prints exactly as it always has; unconverted handlers
+ * print for themselves and yield a placeholder envelope.
+ *
+ * @param command - The command name.
+ * @param args - Parsed arguments.
+ * @returns The envelope of the executed command.
+ */
+async function commandDispatchEnvelope_run(command, args) {
     if (command === 'exit') {
         process.exit(0);
     }
     args = args.map(envRefs_expand);
+    const envelopeHandler = ENVELOPE_HANDLERS[command];
+    if (envelopeHandler) {
+        // A handler that resolves without an envelope (as stubbed handlers in
+        // tests do) is treated as having produced no output.
+        const envelope = await envelopeHandler(args);
+        if (!envelope) {
+            return { status: 'ok', rendered: '' };
+        }
+        envelope_deliver(envelope);
+        return envelope;
+    }
     const handler = COMMAND_HANDLERS[command];
     if (handler) {
-        await handler(args);
-        return;
+        return handler_runDirect(handler, args);
     }
     const binResult = await vfs.data_get('/bin');
     if (binResult.ok) {
         const pluginItem = binResult.value.find(item => item.name === command && item.type === 'plugin');
         const pipelineItem = binResult.value.find(item => item.name === command && item.type === 'pipeline');
         if (pluginItem) {
-            await builtin_executePlugin(command, args);
-            return;
+            return handler_runDirect((pluginArgs) => builtin_executePlugin(command, pluginArgs), args);
         }
         if (pipelineItem) {
-            await pipelineExecutable_handle(command, args);
-            return;
+            return handler_runDirect((pipelineArgs) => pipelineExecutable_handle(command, pipelineArgs), args);
         }
     }
-    console.log(chalk.yellow(`Unknown chell command '${command}' -- delegating to chili`));
-    await chiliCommand_run(command, ['-s', ...args]);
+    const fallback = printingHandler_wrap(async (fallbackArgs) => {
+        console.log(chalk.yellow(`Unknown chell command '${command}' -- delegating to chili`));
+        await chiliCommand_run(command, ['-s', ...fallbackArgs]);
+    });
+    const envelope = await fallback(args);
+    envelope_deliver(envelope);
+    return envelope;
 }
 /**
- * Executes a shell-escaped command and prints timing if enabled.
+ * Dispatches a parsed command to its handler.
  *
- * @param line - Full input line including the leading `!`.
- * @param startTime - Timing reference from `performance.now()`.
- * @param timingEnabled - Whether to print elapsed time after execution.
- */
-async function shellEscape_handle(line, startTime, timingEnabled) {
-    const shellCommand = line.substring(1).trim();
-    if (!shellCommand)
-        return;
-    await shellCommand_execute(shellCommand);
-    command_timingMaybePrint(startTime, timingEnabled);
-}
-/**
- * Splits a semicolon-separated command line and executes each segment in sequence.
- * Returns Ok(true) if the line contained semicolons and was handled, Ok(false) if not.
+ * Compatibility shape over {@link command_dispatchEnvelope} for callers that
+ * do not consume envelopes.
  *
- * @param line - Full input line.
- * @param startTime - Timing reference.
- * @param timingEnabled - Whether to print total elapsed time after all segments.
+ * @param command - The command name.
+ * @param args - Parsed arguments.
+ * @returns A Promise that resolves once the command has been dispatched.
  */
-async function semicolons_handle(line, startTime, timingEnabled) {
-    const commands = semicolons_parse(line);
-    if (commands.length <= 1) {
-        return Ok(false);
-    }
-    for (const cmd of commands) {
-        try {
-            await command_handle(cmd);
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            console.error(chalk.red(`Command error: ${msg}`));
-            if (stopOnError) {
-                return Err();
-            }
-        }
-    }
-    if (timingEnabled) {
-        const elapsed = performance.now() - startTime;
-        console.log(chalk.gray(`[Total: ${elapsed.toFixed(2)}ms]`));
-    }
-    return Ok(true);
+export async function command_dispatch(command, args) {
+    await command_dispatchEnvelope(command, args);
 }
 /**
- * Handles output redirection (`>` / `>>`). Captures command output and writes to the target file.
- * Returns Ok(true) if redirection was detected and handled, Ok(false) if not.
+ * Executes a redirected command (`>` / `>>`): captures the command's output
+ * and writes it to the target file.
  *
- * @param line - Full input line.
- * @param startTime - Timing reference.
- * @param timingEnabled - Whether to print elapsed time after execution.
+ * @param redirectInfo - The parsed redirection (command, operator, target).
+ * @returns An envelope recording the outcome; rendered text stays empty
+ *   because the output went to the file, not the terminal.
  */
-async function redirect_handle(line, startTime, timingEnabled) {
-    const redirectInfo = redirect_parse(line);
-    if (!redirectInfo) {
-        return Ok(false);
-    }
+export async function redirect_execute(redirectInfo) {
     const { buffer } = await chellCommand_executeAndCapture(redirectInfo.command);
     const targetResult = redirectTarget_resolve(redirectInfo.filePath, redirectInfo.command);
     if (!targetResult.ok) {
         const lastError = errorStack.stack_pop();
         console.error(chalk.red(lastError ? lastError.message : 'Redirect error'));
-        return Err();
+        return { status: 'error', rendered: '' };
     }
     if (redirectInfo.operator === '>') {
         writeFileSync(targetResult.value, buffer);
@@ -397,33 +459,7 @@ async function redirect_handle(line, startTime, timingEnabled) {
     else {
         appendFileSync(targetResult.value, buffer);
     }
-    command_timingMaybePrint(startTime, timingEnabled);
-    return Ok(true);
-}
-/**
- * Handles pipe chains (`cmd1 | cmd2 | ...`). Executes the first segment in chell and
- * pipes the output through subsequent host-shell processes.
- * Returns Ok(true) if a pipe was detected and handled, Ok(false) if not.
- *
- * @param line - Full input line.
- * @param startTime - Timing reference.
- * @param timingEnabled - Whether to print elapsed time after the chain completes.
- */
-async function pipe_handle(line, startTime, timingEnabled) {
-    const segments = pipes_parse(line);
-    if (segments.length <= 1) {
-        return Ok(false);
-    }
-    try {
-        await pipe_execute(segments);
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        console.error(chalk.red(`Pipe error: ${msg}`));
-        return Err();
-    }
-    command_timingMaybePrint(startTime, timingEnabled);
-    return Ok(true);
+    return { status: 'ok', rendered: '' };
 }
 /**
  * Shows help for a command if `--help` or `-h` is present in args.
@@ -486,10 +522,31 @@ async function chellCommand_executeAndCapture(commandLine) {
         }
         args = expandResult.value;
     }
-    return output_capture(async () => {
-        if (command === 'exit') {
-            process.exit(0);
+    if (command === 'exit') {
+        process.exit(0);
+    }
+    // Envelope-speaking commands feed pipes and redirects from their envelope:
+    // rendered text with ANSI stripped (plain pipes, the documented deviation),
+    // error-stream text passed live to stderr exactly as the inherit behavior
+    // always did. Direct stdout writers (binary cat) are still captured; their
+    // bytes precede the envelope's rendered text if a command mixes both.
+    const envelopeHandler = ENVELOPE_HANDLERS[command];
+    if (envelopeHandler) {
+        let envelope;
+        const { buffer: directBuffer } = await output_capture(async () => {
+            envelope = await envelopeHandler(args);
+        });
+        if (!envelope) {
+            return { text: '', buffer: Buffer.alloc(0) };
+        }
+        if (envelope.renderedErr !== undefined && envelope.renderedErr.length > 0) {
+            process.stderr.write(envelope.renderedErr);
         }
+        const plain = ansi_strip(envelope.rendered);
+        const buffer = Buffer.concat([directBuffer, Buffer.from(plain, 'utf-8')]);
+        return { text: buffer.toString('utf-8'), buffer };
+    }
+    return output_capture(async () => {
         if (await pluginExecutable_handle(command, args, { piped: true })) {
             return;
         }
@@ -503,42 +560,77 @@ async function chellCommand_executeAndCapture(commandLine) {
     });
 }
 /**
- * Executes a pipe chain by running the first command in chell and piping through local tools.
+ * Executes a pipe chain by running the first command in chell and piping
+ * through local tools, delivering the final output on the data channel.
  *
  * @param segments - Array of command segments separated by pipes.
- * @returns A Promise that resolves when the pipe chain completes.
+ * @returns An envelope whose rendered text is the chain's final output.
  */
-async function pipe_execute(segments) {
-    if (segments.length === 0)
-        return;
+export async function pipe_execute(segments) {
+    if (segments.length === 0) {
+        return { status: 'ok', rendered: '' };
+    }
+    // The first segment is a chell command run in-engine; the rest run through
+    // the surface, so nothing spawns on a daemon host — a surface without the
+    // capability (a browser) fails the pipeline with a clear message.
+    if (segments.length > 1) {
+        capability_require('pipeSegments', 'this surface cannot run pipeline segments');
+    }
     // Execute first segment in chell and capture output
     const firstCommand = segments[0];
     const { buffer } = await chellCommand_executeAndCapture(firstCommand);
-    if (segments.length === 1) {
-        // No pipes, just output the result
-        process.stdout.write(buffer);
-        return;
-    }
-    // Chain remaining segments as spawned processes
+    // Chain remaining segments through the surface's own tools.
     let currentInput = buffer;
     for (let i = 1; i < segments.length; i++) {
-        currentInput = await segment_pipeThrough(segments[i], currentInput);
+        currentInput = await surface_get().pipeSegment(segments[i], currentInput);
     }
     // Output final result
-    process.stdout.write(currentInput);
+    sink_get().data_write(currentInput);
+    return { status: 'ok', rendered: currentInput.toString('utf-8') };
 }
 /**
- * Whether a batch (semicolon list, script) should abort on the first error.
- * Read by {@link semicolons_handle}; set by the boot layer for `-e` / script modes.
- */
-let stopOnError = false;
-/**
- * Sets the shared stop-on-error flag. Exposed so the boot layer (which owns the
- * `-e` flag and script execution) can drive the flag that the dispatch layer reads.
+ * Executes one plain command line (no shell escape, batch, redirect or pipe)
+ * and returns its envelope.
+ *
+ * Mirrors the historical direct-execution order exactly: help flag
+ * short-circuit, wildcard expansion, simulated plugin execution, then table
+ * dispatch. Timing is printed at the same points the shell always printed
+ * it (after plugin execution or dispatch; never after help or a wildcard
+ * failure).
  *
- * @param value - `true` to abort a batch on the first error.
+ * @param trimmedLine - The trimmed command line.
+ * @param startTime - Timing reference from `performance.now()`.
+ * @param timingEnabled - Whether to print elapsed time after execution.
+ * @returns The command's envelope, or null when the line held no tokens.
  */
-export function stopOnError_set(value) {
-    stopOnError = value;
+export async function command_executeToEnvelope(trimmedLine, startTime, timingEnabled) {
+    const tokens = args_tokenize(trimmedLine);
+    if (tokens.length === 0)
+        return null;
+    let [command, ...args] = tokens;
+    // Check for --help flag before any processing
+    const helpResult = help_showMaybe(command, args);
+    if (helpResult.ok && helpResult.value) {
+        return { status: 'ok', rendered: '' };
+    }
+    // Expand wildcards for commands that support it
+    const expandResult = await wildcards_expand(command, args);
+    if (!expandResult.ok) {
+        return { status: 'error', rendered: '' };
+    }
+    args = expandResult.value;
+    // Attempt to handle as a simulated plugin execution. This path bypasses
+    // command_dispatchEnvelope, so it drains the errorStack itself.
+    const checkpoint = errorStack.checkpoint_mark();
+    const exitCodeBefore = exitCode_read();
+    if (await pluginExecutable_handle(command, args)) {
+        command_timingMaybePrint(startTime, timingEnabled);
+        const exitCodeAfter = exitCode_read();
+        const failed = exitCodeAfter !== 0 && exitCodeAfter !== exitCodeBefore;
+        return envelope_drainErrorsInto(checkpoint, { status: failed ? 'error' : 'ok', rendered: '' });
+    }
+    const envelope = await command_dispatchEnvelope(command, args);
+    command_timingMaybePrint(startTime, timingEnabled);
+    return envelope;
 }
 //# sourceMappingURL=dispatch.js.map