@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/input/stdin-filter.js

@@ -0,0 +1,379 @@
+/**
+ * Stdin filter (mouse-wheel-region-routing section 4.2 / 5.2, extended by
+ * tui-paste-handling section 5.1).
+ *
+ * WHY A WRAPPER AND NOT A SECOND LISTENER. Ink 5.2.1 owns stdin in a way that
+ * forbids a second reader: `components/App.js` calls `setEncoding('utf8')`,
+ * `ref()`, `setRawMode(true)`, subscribes to `'readable'` and drains with
+ * `read()`. Attaching our own `'data'` listener to the same `process.stdin`
+ * would switch the stream into flowing mode and RACE Ink's `read()` for chunks
+ * -- some keystrokes would reach Ink, some would not, non-deterministically
+ * (D-3). So the filter REPLACES the stream Ink is given: it reads the real
+ * stdin, strips every mouse report, frames every paste, and writes the
+ * remainder into a `PassThrough` that carries the surface Ink requires.
+ *
+ * ONE CHANNEL, NOT TWO, AND THAT NOW COVERS PASTES AS WELL (D-2 / D-3). A second
+ * chained filter would need a second `PassThrough` and would reopen the ordering
+ * hazard this note closes; a side-channel paste emit would apply the payload
+ * BEFORE text that preceded it in the same chunk, because `wrapper.write` is
+ * asynchronous and a synchronous emit is not. The paste therefore travels
+ * INLINE, wrapped in `PASTE_OPEN` / `PASTE_CLOSE` (I-5).
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h` or `\x1b[?2004h`. Reporting or
+ * bracketed paste enabled while Ink still holds the raw stream does not degrade
+ * the feature -- it types `[<0;12;5M` or `[200~` into the user's message, which
+ * is strictly worse than the bug being fixed.
+ *
+ * THE HANDLE ANSWERS EXACTLY ONE QUESTION: "is a stream wrapped?" (I-11 / D-17).
+ * It stopped being the answer to "is the mouse on?" the moment paste could build
+ * a filter on its own -- `paste` defaults to `true`, so `aragon --no-mouse`
+ * builds one. `cli.tsx` reads its own `mouseOn` / `pasteOn` booleans; this module
+ * is told which features it is running and never derives them.
+ */
+import { PassThrough } from 'node:stream';
+import { MAX_PENDING_MOUSE_CHARS, splitMouseEvents, isMousePrefix, } from './mouse-events.js';
+import { PASTE_ASSEMBLY_MAX_MS, PASTE_BURST_MS, PASTE_CLOSE, PASTE_MAX_BYTES, PASTE_OPEN, formatPasteSize, } from './limits.js';
+import { PASTE_BEGIN_MARK, PASTE_END_MARK, classifyChunk, sanitisePaste, trailingPastePrefixLength, } from './paste-parse.js';
+/**
+ * How long a possible-prefix tail is held before being flushed as text.
+ *
+ * This is what stops a lone `\x1b` -- the Esc key, which aborts a run -- from
+ * being held hostage waiting for a `[` that will never arrive. Worst-case Esc
+ * latency becomes 12 ms, and only for the keystroke that is literally a bare
+ * ESC; every other key resolves both prefix tests to false immediately.
+ */
+const PENDING_FLUSH_MS = 12;
+/**
+ * Ceiling on the held-back tail, shared by both prefix families.
+ *
+ * NO CHANGE IS NEEDED HERE FOR PASTE (P2-5). `MAX_PENDING_MOUSE_CHARS` is 32 and
+ * the longest paste marker is 6, so 32 already covers both. v1 of the design said
+ * the ceiling "becomes `max(MAX_PENDING_MOUSE_CHARS, PASTE_BEGIN_MARK.length)`",
+ * which is the same number written in a way that invites someone to edit the
+ * constant.
+ *
+ * TAKEN FROM THE MODULE THAT OWNS IT rather than written again: this file already
+ * imports from `mouse-events.js`, so there is no cycle to dodge here and no
+ * reason for a second copy of a number whose only justification is that it equals
+ * that one.
+ */
+const MAX_PENDING_CHARS = MAX_PENDING_MOUSE_CHARS;
+/** Assign a method onto the PassThrough without widening its public type. */
+function define(target, name, value) {
+    Object.defineProperty(target, name, { value, writable: true, configurable: true });
+}
+const byteLength = (s) => Buffer.byteLength(s, 'utf8');
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a mouse
+ * report, or 0. Shortest match wins, mirroring `trailingPastePrefixLength`.
+ *
+ * MEASURED SEPARATELY FROM THE PASTE FAMILY, and the longer hold wins.
+ * `isMousePrefix` does not match `\x1b[2`, which IS a prefix of both paste
+ * markers, so a single combined test would leak half a marker into the draft.
+ */
+function trailingMousePrefixLength(text) {
+    const max = Math.min(text.length, MAX_PENDING_CHARS);
+    for (let k = 1; k <= max; k += 1) {
+        if (isMousePrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}
+export function createStdinFilter(real, features, bridge, onWarn) {
+    const wrapper = new PassThrough();
+    const listeners = new Set();
+    let pending = '';
+    let flushTimer = null;
+    let burstTimer = null;
+    let assemblyTimer = null;
+    let disposed = false;
+    let paste = { kind: 'idle' };
+    // --- The surface Ink reads off the stream it is handed. ------------------
+    // `isRawModeSupported()` reads `props.stdin.isTTY` (App.js:34), so this has
+    // to be a DELEGATING GETTER rather than a snapshot: a stdin that is not a TTY
+    // must still report so through the wrapper, or Ink throws instead of falling
+    // back.
+    Object.defineProperty(wrapper, 'isTTY', {
+        get: () => real.isTTY,
+        configurable: true,
+    });
+    define(wrapper, 'setRawMode', (mode) => {
+        real.setRawMode?.(mode);
+        return wrapper;
+    });
+    define(wrapper, 'ref', () => {
+        real.ref?.();
+        return wrapper;
+    });
+    define(wrapper, 'unref', () => {
+        real.unref?.();
+        return wrapper;
+    });
+    const emit = (event) => {
+        for (const listener of [...listeners])
+            listener(event);
+    };
+    const clearTimer = (t) => {
+        if (t)
+            clearTimeout(t);
+        return null;
+    };
+    /** `.unref()` so a held tail can never keep the process alive on its own. */
+    const arm = (fn, ms) => {
+        const t = setTimeout(fn, ms);
+        t.unref?.();
+        return t;
+    };
+    // -----------------------------------------------------------------------
+    // Paste emission
+    // -----------------------------------------------------------------------
+    /**
+     * Write one frame, or refuse the paste and say so.
+     *
+     * D-11: above `PASTE_MAX_BYTES` the body is DROPPED and the user gets a toast
+     * naming the size and the limit. Truncating would lose their data and look
+     * like success. The body stops being accumulated the moment it goes over
+     * (`overflow`), so memory stays bounded while the rest of the payload is still
+     * being consumed -- consuming it is not optional, because the alternative is
+     * two megabytes of the user's file arriving as keystrokes.
+     */
+    const emitPaste = (body, bytes, overflow) => {
+        if (disposed)
+            return;
+        if (overflow || bytes > PASTE_MAX_BYTES) {
+            const text = `Paste too large (${formatPasteSize(bytes)}); limit is ` +
+                `${formatPasteSize(PASTE_MAX_BYTES)}. Nothing was inserted.`;
+            onWarn?.(text);
+            bridge?.notify?.('warn', text);
+            return;
+        }
+        const payload = sanitisePaste(body);
+        if (payload.length === 0)
+            return;
+        // ONE `write()` call, at the position the paste occupied in the stream.
+        wrapper.write(PASTE_OPEN + payload + PASTE_CLOSE);
+    };
+    const flushBurst = () => {
+        burstTimer = clearTimer(burstTimer);
+        if (paste.kind !== 'burst')
+            return;
+        const { body, bytes } = paste;
+        paste = { kind: 'idle' };
+        emitPaste(body, bytes, false);
+    };
+    const flushBracketed = (reason) => {
+        assemblyTimer = clearTimer(assemblyTimer);
+        if (paste.kind !== 'bracketed')
+            return;
+        const { body, bytes, overflow } = paste;
+        paste = { kind: 'idle' };
+        if (reason === 'timeout') {
+            // I-4: an unterminated marker must never wedge input. Emitting what
+            // arrived is strictly better than holding the keyboard hostage.
+            onWarn?.('bracketed paste never terminated; flushing what arrived');
+        }
+        emitPaste(body, bytes, overflow);
+    };
+    // -----------------------------------------------------------------------
+    // The scan (section 5.1, and the ORDER below is the specification)
+    // -----------------------------------------------------------------------
+    /**
+     * Text that reached the pass-through: Tier 2 classification, then mouse
+     * stripping, then Ink.
+     *
+     * MOUSE PARSING IS SUSPENDED FOR THE DURATION OF ANY PASTE BODY (I-3), burst
+     * and bracketed alike. The Tier 2 population is precisely the terminals with
+     * no bracketed paste, and the likeliest thing such a user pastes into a TUI
+     * dev tool is a terminal log full of `\x1b[<0;12;5M`-shaped bytes. Eating
+     * those would corrupt their data silently. v1 covered only Tier 1, which left
+     * the loss in place for exactly the terminals Tier 2 exists to serve (P1-7).
+     */
+    const handleOutsidePaste = (text, holdTail) => {
+        if (text.length === 0)
+            return;
+        if (paste.kind === 'burst') {
+            paste = { kind: 'burst', body: paste.body + text, bytes: paste.bytes + byteLength(text) };
+            burstTimer = clearTimer(burstTimer);
+            burstTimer = arm(flushBurst, PASTE_BURST_MS);
+            return;
+        }
+        if (features.paste && classifyChunk(text) === 'paste') {
+            paste = { kind: 'burst', body: text, bytes: byteLength(text) };
+            burstTimer = clearTimer(burstTimer);
+            burstTimer = arm(flushBurst, PASTE_BURST_MS);
+            return;
+        }
+        // Step 0: with `mouse` false this degenerates to "pass the text on", which
+        // is byte-identical to the unwrapped stream.
+        if (!features.mouse) {
+            wrapper.write(text);
+            return;
+        }
+        const split = splitMouseEvents(text);
+        if (split.text.length > 0)
+            wrapper.write(split.text);
+        for (const event of split.events)
+            emit(event);
+        if (split.pending.length === 0)
+            return;
+        // `holdTail` is false when a paste marker follows this run in the SAME
+        // chunk: no later byte can complete the mouse prefix, so holding it would
+        // reorder it behind the paste. Appending (never prepending) is what keeps
+        // `pending` in stream order when both prefix families fire at once.
+        if (holdTail)
+            pending += split.pending;
+        else
+            wrapper.write(split.pending);
+    };
+    const appendBracketed = (text) => {
+        if (paste.kind !== 'bracketed' || text.length === 0)
+            return;
+        const bytes = paste.bytes + byteLength(text);
+        const overflow = paste.overflow || bytes > PASTE_MAX_BYTES;
+        paste = {
+            kind: 'bracketed',
+            body: overflow ? paste.body : paste.body + text,
+            bytes,
+            overflow,
+        };
+    };
+    const feed = (raw) => {
+        let rest = raw;
+        while (rest.length > 0) {
+            if (paste.kind === 'bracketed') {
+                const end = rest.indexOf(PASTE_END_MARK);
+                if (end === -1) {
+                    // Hold a trailing strict prefix of the END marker for the next chunk.
+                    // NO 12 ms FLUSH TIMER HERE: inside a body every byte is payload, so
+                    // nothing is being kept from the keyboard, and `assemblyTimer` is the
+                    // bound that matters (I-4).
+                    const hold = trailingPastePrefixLength(rest);
+                    appendBracketed(rest.slice(0, rest.length - hold));
+                    pending = rest.slice(rest.length - hold);
+                    return;
+                }
+                appendBracketed(rest.slice(0, end));
+                flushBracketed('end');
+                rest = rest.slice(end + PASTE_END_MARK.length);
+                continue;
+            }
+            // idle | burst. BOTH markers are consumed unconditionally, in every mode
+            // and whether or not this process enabled DEC 2004 (I-16): something else
+            // may have left it on, and a stray END typed into the draft is the same
+            // failure arriving from outside.
+            const begin = rest.indexOf(PASTE_BEGIN_MARK);
+            const strayEnd = rest.indexOf(PASTE_END_MARK);
+            const first = begin === -1 ? strayEnd : strayEnd === -1 ? begin : Math.min(begin, strayEnd);
+            if (first === -1) {
+                const keep = Math.max(trailingPastePrefixLength(rest), features.mouse ? trailingMousePrefixLength(rest) : 0);
+                const tail = rest.slice(rest.length - keep);
+                handleOutsidePaste(rest.slice(0, rest.length - keep), true);
+                pending += tail;
+                return;
+            }
+            handleOutsidePaste(rest.slice(0, first), false);
+            if (begin === -1 || first < begin) {
+                rest = rest.slice(first + PASTE_END_MARK.length);
+                continue;
+            }
+            // P2-4: the burst is flushed FIRST, so two bodies can never be
+            // concatenated into one token out of order.
+            flushBurst();
+            paste = { kind: 'bracketed', body: '', bytes: 0, overflow: false };
+            assemblyTimer = clearTimer(assemblyTimer);
+            assemblyTimer = arm(() => flushBracketed('timeout'), PASTE_ASSEMBLY_MAX_MS);
+            rest = rest.slice(first + PASTE_BEGIN_MARK.length);
+        }
+    };
+    const flushPending = () => {
+        flushTimer = clearTimer(flushTimer);
+        if (pending.length === 0 || disposed)
+            return;
+        const text = pending;
+        pending = '';
+        // A tail that never completed is ordinary text; it goes through the same
+        // scan so a burst already open keeps coalescing it.
+        handleOutsidePaste(text, false);
+    };
+    const onData = (chunk) => {
+        if (disposed)
+            return;
+        flushTimer = clearTimer(flushTimer);
+        const decoded = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        const carried = pending;
+        pending = '';
+        feed(carried + decoded);
+        if (paste.kind === 'bracketed' || pending.length === 0)
+            return;
+        if (pending.length > MAX_PENDING_CHARS) {
+            // A malformed sequence that looks like a prefix forever must never wedge
+            // input: past the ceiling the tail becomes ordinary text.
+            const text = pending;
+            pending = '';
+            handleOutsidePaste(text, false);
+            return;
+        }
+        flushTimer = arm(flushPending, PENDING_FLUSH_MS);
+    };
+    // P2-7: a closed stdin must still terminate Ink's reader, or it waits forever
+    // on a stream that will never produce another byte.
+    const onEnd = () => {
+        flushBracketed('timeout');
+        flushBurst();
+        flushPending();
+        if (!wrapper.writableEnded)
+            wrapper.end();
+    };
+    // `setEncoding('utf8')` on the REAL stream so Node's StringDecoder handles
+    // multi-byte boundaries for us -- the scan works on characters, and a UTF-8
+    // sequence split across two chunks would otherwise become two mojibake
+    // characters before it ever reached `splitMouseEvents`.
+    real.setEncoding?.('utf8');
+    real.on('data', onData);
+    real.once('end', onEnd);
+    real.once('close', onEnd);
+    return {
+        stdin: wrapper,
+        source: {
+            subscribe(listener) {
+                listeners.add(listener);
+                return () => listeners.delete(listener);
+            },
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            flushTimer = clearTimer(flushTimer);
+            burstTimer = clearTimer(burstTimer);
+            assemblyTimer = clearTimer(assemblyTimer);
+            real.removeListener('data', onData);
+            real.removeListener('end', onEnd);
+            real.removeListener('close', onEnd);
+            listeners.clear();
+            // I-7: a live `'data'` listener on stdin keeps the event loop alive, and
+            // `aragon` would hang on exit instead of returning to the shell.
+            real.pause?.();
+            real.unref?.();
+        },
+    };
+}
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): a construction failure must
+ * degrade to "the wheel is inert and pastes are keystrokes" -- a supported,
+ * tested rung of the fail-safe ladder -- rather than leaving `?1000h` or `?2004h`
+ * on with no filter in front of Ink. `cli.tsx` derives BOTH `mouseOn` and
+ * `pasteOn` from the returned handle for exactly that reason.
+ */
+export function tryCreateStdinFilter(real, features, onError, bridge) {
+    try {
+        return createStdinFilter(real, features, bridge, onError);
+    }
+    catch (err) {
+        onError?.(err instanceof Error ? err.message : String(err));
+        return null;
+    }
+}

package/dist/logging/install.d.ts

@@ -71,6 +71,8 @@ export declare function setScreenRestore(fn: () => void): void;
  * `process.on('SIGINT')` added later never runs at all (P0-1).
  */
 export declare function setSignalTerminator(fn: (signo: number) => void): void;
+/** Register a synchronous hook to run before the signal terminator. */
+export declare function addSignalHook(fn: () => void): () => void;
 /** Tests only: undo the hook swaps so cases cannot leak into each other. */
 export declare function resetProcessHooksForTest(): void;
 export interface PendingNote {

package/dist/logging/install.js

@@ -91,10 +91,52 @@ export function setScreenRestore(fn) {
 export function setSignalTerminator(fn) {
     signalTerminator = fn;
 }
+/**
+ * Work to run BEFORE whatever `signalTerminator` does, on every signal and on a
+ * fatal crash (background-service-supervision §3.6 / P1-2).
+ *
+ * AN APPEND-ONLY LIST, NOT A SECOND SINGLE SLOT, AND THAT IS THE WHOLE POINT.
+ * `setSignalTerminator` is a SINGLE SLOT that `cli.tsx` already claims for the
+ * alternate-screen restore; registering a second terminator from anywhere else
+ * would REPLACE it, which that file's own comment names as the bug that leaves
+ * the user staring at a blank alternate screen. So a subsystem that needs to run
+ * on the way out — the process supervisor, which must reap its children — adds a
+ * hook instead, and nothing about the screen path changes.
+ *
+ * IT ALSO RUNS FROM `handleFatal`, so a crash reaps too. And it is deliberately
+ * SYNCHRONOUS: `signalTerminator` calls `process.exit()` synchronously and
+ * `process.on('exit')` permits only synchronous work, so a hook that awaited
+ * anything would simply not finish (I-9).
+ *
+ * A THROWING HOOK MUST NOT STOP THE EXIT. Each one is wrapped, for the reason
+ * `handleFatal`'s own two wrapped steps record: a failure on the way out must
+ * never be the reason the process fails to leave.
+ */
+const signalHooks = [];
+/** Register a synchronous hook to run before the signal terminator. */
+export function addSignalHook(fn) {
+    signalHooks.push(fn);
+    return () => {
+        const at = signalHooks.indexOf(fn);
+        if (at >= 0)
+            signalHooks.splice(at, 1);
+    };
+}
+function runSignalHooks() {
+    for (const hook of [...signalHooks]) {
+        try {
+            hook();
+        }
+        catch {
+            // A hook that throws must not stop the exit; see the note above.
+        }
+    }
+}
 /** Tests only: undo the hook swaps so cases cannot leak into each other. */
 export function resetProcessHooksForTest() {
     screenRestore = () => { };
     signalTerminator = null;
+    signalHooks.length = 0;
 }
 /**
  * Resolve the BOOTSTRAP level.
@@ -189,12 +231,18 @@ function installProcessHooks(logger, port) {
         handleFatal(logger, port, 'unhandled_rejection', reason);
     });
     // Normal exit. Only synchronous work is possible here, and the whole write
-    // path is synchronous precisely so this can be one line.
+    // path is synchronous precisely so this can be one line — plus the hooks,
+    // which are synchronous for exactly that reason (I-9).
     port.on('exit', () => {
+        runSignalHooks();
         logger.flushSync();
     });
     for (const [name, signo] of Object.entries(SIGNAL_NUMBERS)) {
         port.on(name, () => {
+            // BEFORE the flush and before the terminator: the terminator exits the
+            // process, so anything that has to happen on the way out has to happen
+            // first, and a child process left running outlives its parent.
+            runSignalHooks();
             logger.flushSync();
             // Exiting is NOT optional here: merely having a signal listener stops Node
             // from terminating by default, so skipping this would turn Ctrl+C into
@@ -219,6 +267,10 @@ function installProcessHooks(logger, port) {
  */
 function handleFatal(logger, port, msg, err) {
     const error = err instanceof Error ? err : new Error(String(err));
+    // FIRST, and outside the try below: a crash must still reap the children it
+    // spawned, and it must do so before the screen restore and the stack write,
+    // both of which can themselves fail (R-10).
+    runSignalHooks();
     try {
         logger.error('cli', msg, { message: error.message, stack: error.stack });
         logger.flushSync();

package/dist/proc/classify.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Is this command one that does not exit on its own?
+ * (background-service-supervision §3.5.)
+ *
+ * PURE. No process, no filesystem, no clock — so the whole table below is
+ * enumerable by a test and readable by a reviewer in one screen.
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * A CONSERVATIVE ALLOWLIST OVER THE LEADING TOKEN AND SCRIPT NAME, NEVER A VERB
+ * HEURISTIC (R-1). The cost of a false positive is real: a build that is
+ * backgrounded returns before it finished, and the model reads a half-empty log
+ * as success. So `npm run build` and `npm test` must not match, and a chained
+ * command must not match at all — a chain's TAIL is what the model actually
+ * wants the result of.
+ */
+/**
+ * The classifier's table, exported so `classify.test.ts` can enumerate it and a
+ * reviewer can read it whole.
+ *
+ * Each pattern is anchored at the start of the (trimmed, env-prefix-stripped)
+ * command. `\b`-style boundaries are spelled explicitly because a bare `vite`
+ * must not match `vitest`.
+ */
+export declare const LONG_RUNNING_PATTERNS: readonly RegExp[];
+/**
+ * Does the command contain a TOP-LEVEL `&&`, `||`, `;` or `|`?
+ *
+ * "Top level" means outside quotes: `echo "a && b"` is one command. Anything
+ * quoted is skipped, which is enough for the judgement being made here — this
+ * decides whether to REFUSE to background, so an over-eager reading is the safe
+ * direction.
+ */
+export declare function hasTopLevelChain(command: string): boolean;
+/**
+ * Would this command sit there rather than exiting?
+ *
+ * FALSE FOR ANYTHING CHAINED, unconditionally and before the table is consulted.
+ */
+export declare function looksLongRunning(command: string): boolean;
+/**
+ * The port the command asks for, when it names one.
+ *
+ * Used ONLY to enable the probe detector, so a miss is free (the URL detector
+ * still runs) and a wrong hit is bounded by the pre-flight probe: a port that
+ * already answers before we spawn disables the detector entirely rather than
+ * declaring every launch instantly ready.
+ *
+ * `--port N`, `--port=N`, `-p N`, `PORT=N`, and a `:N` suffix on a host in the
+ * command text (`php -S 127.0.0.1:8080`).
+ */
+export declare function extractPortHint(command: string): number | undefined;

package/dist/proc/classify.js

@@ -0,0 +1,143 @@
+/**
+ * Is this command one that does not exit on its own?
+ * (background-service-supervision §3.5.)
+ *
+ * PURE. No process, no filesystem, no clock — so the whole table below is
+ * enumerable by a test and readable by a reviewer in one screen.
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * A CONSERVATIVE ALLOWLIST OVER THE LEADING TOKEN AND SCRIPT NAME, NEVER A VERB
+ * HEURISTIC (R-1). The cost of a false positive is real: a build that is
+ * backgrounded returns before it finished, and the model reads a half-empty log
+ * as success. So `npm run build` and `npm test` must not match, and a chained
+ * command must not match at all — a chain's TAIL is what the model actually
+ * wants the result of.
+ */
+/**
+ * The classifier's table, exported so `classify.test.ts` can enumerate it and a
+ * reviewer can read it whole.
+ *
+ * Each pattern is anchored at the start of the (trimmed, env-prefix-stripped)
+ * command. `\b`-style boundaries are spelled explicitly because a bare `vite`
+ * must not match `vitest`.
+ */
+export const LONG_RUNNING_PATTERNS = Object.freeze([
+    // Package-manager scripts whose NAME says "does not exit".
+    /^(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|watch|preview)(?:\s|$)/i,
+    // Node/JS dev servers and bundlers in watch mode.
+    /^next\s+(?:dev|start)(?:\s|$)/i,
+    /^vite(?:\s|$)/i,
+    /^nuxt\s+dev(?:\s|$)/i,
+    /^astro\s+dev(?:\s|$)/i,
+    /^remix\s+dev(?:\s|$)/i,
+    /^ng\s+serve(?:\s|$)/i,
+    /^webpack\s+serve(?:\s|$)/i,
+    /^nodemon(?:\s|$)/i,
+    /^tsc\s+(?:--watch|-w)(?:\s|$)/i,
+    /^(?:serve|http-server)(?:\s|$)/i,
+    // Python.
+    /^uvicorn(?:\s|$)/i,
+    /^gunicorn(?:\s|$)/i,
+    /^hypercorn(?:\s|$)/i,
+    /^flask\s+run(?:\s|$)/i,
+    /^python[0-9.]*\s+(?:\S*[\\/])?manage\.py\s+runserver(?:\s|$)/i,
+    /^python[0-9.]*\s+-m\s+http\.server(?:\s|$)/i,
+    // Ruby / PHP / Rust.
+    /^rails\s+(?:server|s)(?:\s|$)/i,
+    /^php\s+-S(?:\s|$)/i,
+    /^cargo\s+watch(?:\s|$)/i,
+    // Containers. `up` WITHOUT `-d` only; the `-d` form is checked below.
+    /^docker(?:\s+compose|-compose)\s+up(?:\s|$)/i,
+    // Plain watchers.
+    /^tail\s+-f(?:\s|$)/i,
+    /^watch\s+/i,
+]);
+/** `docker compose up -d` returns on its own, so it is a foreground command. */
+const DOCKER_DETACHED = /(?:^|\s)(?:-d|--detach)(?:\s|$)/i;
+/**
+ * A leading `KEY=value ` run of assignments, which POSIX shells accept and which
+ * would otherwise hide the real leading token (`PORT=5173 vite`).
+ */
+const ENV_PREFIX = /^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)+/;
+/** Strip a leading env-assignment run, so the table can anchor on the command. */
+function stripEnvPrefix(command) {
+    return command.replace(ENV_PREFIX, '');
+}
+/**
+ * Does the command contain a TOP-LEVEL `&&`, `||`, `;` or `|`?
+ *
+ * "Top level" means outside quotes: `echo "a && b"` is one command. Anything
+ * quoted is skipped, which is enough for the judgement being made here — this
+ * decides whether to REFUSE to background, so an over-eager reading is the safe
+ * direction.
+ */
+export function hasTopLevelChain(command) {
+    let quote = null;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === ';')
+            return true;
+        // A lone `|` is a pipe and `||` is an or; both disqualify. So does `&`, in
+        // BOTH of its readings: `&&` is a chain, and a trailing single `&` is the
+        // manual-detach the prompt block bans - whatever it backgrounds, we cannot
+        // supervise. One branch each, because the two `&` cases have one answer.
+        if (ch === '|' || ch === '&')
+            return true;
+    }
+    return false;
+}
+/**
+ * Would this command sit there rather than exiting?
+ *
+ * FALSE FOR ANYTHING CHAINED, unconditionally and before the table is consulted.
+ */
+export function looksLongRunning(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (hasTopLevelChain(trimmed))
+        return false;
+    const bare = stripEnvPrefix(trimmed);
+    if (/^docker(?:\s+compose|-compose)\s+up(?:\s|$)/i.test(bare) && DOCKER_DETACHED.test(bare)) {
+        return false;
+    }
+    return LONG_RUNNING_PATTERNS.some((re) => re.test(bare));
+}
+/**
+ * The port the command asks for, when it names one.
+ *
+ * Used ONLY to enable the probe detector, so a miss is free (the URL detector
+ * still runs) and a wrong hit is bounded by the pre-flight probe: a port that
+ * already answers before we spawn disables the detector entirely rather than
+ * declaring every launch instantly ready.
+ *
+ * `--port N`, `--port=N`, `-p N`, `PORT=N`, and a `:N` suffix on a host in the
+ * command text (`php -S 127.0.0.1:8080`).
+ */
+export function extractPortHint(command) {
+    const candidates = [
+        /(?:^|\s)--port[=\s]+(\d{1,5})(?:\s|$)/i,
+        /(?:^|\s)-p[=\s]+(\d{1,5})(?:\s|$)/,
+        /(?:^|\s)PORT=(\d{1,5})(?:\s|$)/,
+        /(?:^|\s)\S*?:(\d{2,5})(?:\s|$)/,
+    ];
+    for (const re of candidates) {
+        const m = re.exec(command);
+        if (!m || !m[1])
+            continue;
+        const port = Number.parseInt(m[1], 10);
+        if (Number.isFinite(port) && port > 0 && port <= 65535)
+            return port;
+    }
+    return undefined;
+}