@poe-platform/safe-bash 0.1.601 → 0.1.603

package/dist/safe-bash/shell/runtime.js

@@ -1,3 +1,4 @@
+import { BackgroundJobs, BackgroundResources, backgroundResources, backgroundPrune, backgroundDestination, forwardBackgroundDestination } from "./background-jobs.js";
 import { PublicDiagnostic, publicDiagnosticMessage } from "../diagnostics.js";
 import { writeDiagnostic } from "../escaping.js";
 import { cancelTurn, monotonicNow, registerYieldCheckpoint, scheduleTurn, yieldTurn } from "../contracts/yield.js";
@@ -62,7 +63,7 @@ export const defaultLimits = {
 };
 const shellBuiltinNames = new Set([
     ":", "true", "false", "pwd", "cd", "set", "shift", "export", "local", "unset", "read", "declare", "mapfile", "readarray",
-    "exit", "return", "break", "continue", "command", "builtin", "type", "readonly", "echo", "printf", "test", "[", ".", "source", "eval", "getopts", "let", "pushd", "dirs", "popd", "shopt",
+    "wait", "exit", "return", "break", "continue", "command", "builtin", "type", "readonly", "echo", "printf", "test", "[", ".", "source", "eval", "getopts", "let", "pushd", "dirs", "popd", "shopt",
 ]);
 const implementedBuiltins = new Set([...shellBuiltinNames].filter(name => !["echo", "printf", "test", "["].includes(name)));
 const specialBuiltinNames = new Set([":", ".", "break", "continue", "eval", "exit", "export", "readonly", "return", "set", "shift", "unset"]);
@@ -81,6 +82,8 @@ export function resolveLimits(...limits) {
     }
     return result;
 }
+const runtimeFileSystems = new WeakMap();
+const inputScopes = new WeakMap();
 const budgetedSinks = new WeakMap();
 async function sortExpansionStrings(values, work) {
     const compare = async (left, right) => {
@@ -249,6 +252,7 @@ export class Budget {
                 await interruptible(sink.write(chunk), signal);
             },
         };
+        forwardBackgroundDestination(output, sink);
         budgetedSinks.set(output, { budget: this, write: output.write, ...(ownership?.write === sink.write && ownership.file ? { file: ownership.file } : {}) });
         return output;
     }
@@ -425,6 +429,7 @@ function signalSink(sink, signal) {
             } } : {}),
         async write(chunk) { signal.throwIfAborted(); await interruptible(write(chunk), signal); },
     };
+    forwardBackgroundDestination(output, sink);
     if (owned)
         budgetedSinks.set(output, { ...owned, write: output.write });
     return output;
@@ -441,6 +446,7 @@ function bindCommandIO(context) {
 async function cloneState(state, signal, scope, inheritLocals = true) {
     const destination = await snapshotState(state, () => ({
         ...state,
+        ...(state.backgroundJobs ? { backgroundJobs: new BackgroundJobs(state.backgroundJobs.execution) } : {}),
         variables: Object.assign(Object.create(null), state.variables),
         exported: new Set(state.exported), functions: new Map(state.functions), positional: [...state.positional],
         readonlyVariables: new Set(state.readonlyVariables),
@@ -1147,6 +1153,7 @@ export class Runtime {
         this.outcomeFrame = outcomeFrame;
         this.inputProfile = inputProfile;
         this.fs = scopeFileSystem(fs, () => budget.fileSystemOperation(), signal, () => budget.fileSystemCleanupOperation());
+        runtimeFileSystems.set(this.fs, runtimeFileSystems.get(fs) ?? fs);
         const checkpoint = () => budget.cpuCheckpoint();
         registerYieldCheckpoint(signal, checkpoint);
         registerYieldCheckpoint(commandSignal, checkpoint);
@@ -1934,6 +1941,68 @@ export class Runtime {
     }
     async script(script, state, io) {
         for (const list of script.lists) {
+            if (list.background) {
+                const jobs = state.backgroundJobs;
+                const id = jobs.execution.identifier();
+                const scope = jobs.execution.scope.child();
+                const inheritedDestinations = new Set([io.stdout, io.stderr, ...[...io.descriptors?.values() ?? []].flatMap(descriptor => descriptor.output && !descriptor.closed ? [descriptor.output] : [])].map(backgroundDestination));
+                const leases = (io[backgroundResources] ?? []).filter(resource => !resource.destination || inheritedDestinations.has(resource.destination)).map(resource => ({ resource, release: resource.retain() }));
+                const releases = leases.map(lease => lease.release);
+                let child;
+                try {
+                    child = await cloneState(state, this.signal, scope);
+                }
+                catch (error) {
+                    releases.forEach(release => release());
+                    await scope.close();
+                    throw error;
+                }
+                child.isolated = true;
+                child.loopDepth = 0;
+                const inherited = isolateIO(activeIO(io));
+                const redirectsInput = list.pipelines[0].commands[0].redirects.some(redirect => redirect.descriptor === 0);
+                const stdin = redirectsInput ? inherited.stdin : toByteSource("");
+                const descriptors = new Map(inherited.descriptors);
+                descriptors.set(0, { input: stdin, stdinIsDefault: false });
+                let initialRedirection = true;
+                const backgroundIO = { ...inherited, [invocationScope]: scope, stdin, stdinIsDefault: false, descriptors,
+                    [backgroundPrune]: list.pipelines.length === 1 ? descriptors => {
+                        if (!initialRedirection)
+                            return;
+                        initialRedirection = false;
+                        const destinations = new Set([...descriptors.values()].flatMap(descriptor => descriptor.output && !descriptor.closed ? [backgroundDestination(descriptor.output)] : []));
+                        for (const lease of leases)
+                            if (lease.resource.destination && !destinations.has(lease.resource.destination))
+                                lease.release();
+                    } : undefined,
+                };
+                const runtime = new Runtime(runtimeFileSystems.get(this.fs) ?? this.fs, this.commands, this.middleware, this.budget, AbortSignal.any([this.commandSignal, scope.signal]), this.fileWrites, this.outputFiles, this.commandSignal, this.cancellation, this.cancellationState, this.cancellationOwner, this.cancellationDepth, this.cancellationMaxDepth, undefined, this.inputProfile);
+                try {
+                    state.lastBackgroundJob = jobs.launch(id, async () => {
+                        try {
+                            try {
+                                return (await runtime.runUnit({ lists: [{ ...list, background: false }] }, child, backgroundIO)).exitCode;
+                            }
+                            catch (error) {
+                                if (error instanceof Flow && error.kind === "return")
+                                    return error.status;
+                                throw error;
+                            }
+                        }
+                        finally {
+                            releases.forEach(release => release());
+                            await scope.close();
+                        }
+                    });
+                }
+                catch (error) {
+                    releases.forEach(release => release());
+                    await scope.close();
+                    throw error;
+                }
+                state.status = 0;
+                continue;
+            }
             for (let index = 0; index < list.pipelines.length; index++) {
                 const operator = list.operators[index - 1];
                 if ((operator === "&&" && state.status !== 0) || (operator === "||" && state.status === 0))
@@ -1979,6 +2048,7 @@ export class Runtime {
             const completed = new Set();
             const closing = new Set();
             let statuses;
+            const stageLeases = [];
             try {
                 for (let index = 1; index < pipeline.commands.length; index++)
                     pipes.push(createBytePipe({
@@ -1986,7 +2056,11 @@ export class Runtime {
                     }));
                 for (let index = 0; index < pipeline.commands.length; index++)
                     controllers.push(new AbortController());
+                stageLeases.push(...pipeline.commands.map(() => (io[backgroundResources] ?? []).filter(resource => resource.destination).map(resource => ({ resource, release: resource.retain() }))));
+                io[backgroundPrune]?.(new Map());
                 const tasks = pipeline.commands.map(async (command, index) => {
+                    let initialRedirection = true;
+                    const inheritedLeases = stageLeases[index];
                     const incoming = pipes[index - 1];
                     const outgoing = pipes[index];
                     const childDepth = this.cancellationDepth + 1;
@@ -2022,6 +2096,8 @@ export class Runtime {
                                 throw error;
                             }
                         } };
+                    const resources = new BackgroundResources();
+                    resources.destination = backgroundDestination(pipeOutput ?? io.stdout);
                     const executeStage = async () => {
                         try {
                             let exitCode;
@@ -2030,6 +2106,16 @@ export class Runtime {
                                 child.isolated = true;
                                 const work = runtime.runCommandIsolated(command, child, {
                                     ...isolateIO(io),
+                                    [backgroundResources]: [...io[backgroundResources] ?? [], resources],
+                                    [backgroundPrune]: descriptors => {
+                                        if (!initialRedirection)
+                                            return;
+                                        initialRedirection = false;
+                                        const destinations = new Set([...descriptors.values()].flatMap(descriptor => descriptor.output && !descriptor.closed ? [backgroundDestination(descriptor.output)] : []));
+                                        for (const lease of inheritedLeases)
+                                            if (!destinations.has(lease.resource.destination))
+                                                lease.release();
+                                    },
                                     stdin: input,
                                     ...(incoming ? { stdinIsDefault: false } : {}),
                                     stdout: pipeOutput ? this.budget.sink(pipeOutput, signal) : signalSink(io.stdout, signal),
@@ -2037,6 +2123,8 @@ export class Runtime {
                                 }).finally(() => stateMonitor(child)?.closeValues());
                                 retain(work);
                                 exitCode = await interruptible(work, signal);
+                                if (resources.busy)
+                                    await interruptible(resources.drain(), signal);
                             }
                             catch (error) {
                                 if (!(error instanceof PipelineClosed))
@@ -2046,6 +2134,7 @@ export class Runtime {
                             return { exitCode };
                         }
                         finally {
+                            inheritedLeases.forEach(lease => lease.release());
                             completed.add(index);
                             if (incoming) {
                                 const upstream = index - 1;
@@ -2083,6 +2172,9 @@ export class Runtime {
             }
             finally {
                 try {
+                    for (const leases of stageLeases)
+                        for (const lease of leases)
+                            lease.release();
                     for (const close of closing)
                         cancelTurn(close);
                     for (const [index, controller] of controllers.entries())
@@ -2171,13 +2263,22 @@ export class Runtime {
         if (this.budget.commands % 128 === 0)
             await yieldTurn(this.signal);
         this.signal.throwIfAborted();
+        const resources = new BackgroundResources();
+        originalIO = { ...originalIO, [backgroundResources]: [...originalIO[backgroundResources] ?? [], resources] };
         const inputs = new Set();
         const outputs = new Set();
         const finishOutputs = async (status) => {
             const pending = [...outputs];
             outputs.clear();
-            const settled = await Promise.allSettled(pending.map(close => close({ status })));
-            throwCleanupFailures(settled.filter(result => result.status === "rejected").map(result => result.reason));
+            const finish = async () => {
+                await resources.drain();
+                const settled = await Promise.allSettled(pending.map(close => close({ status })));
+                throwCleanupFailures(settled.filter(result => result.status === "rejected").map(result => result.reason));
+            };
+            if (resources.busy)
+                state.backgroundJobs.execution.track(finish());
+            else
+                await finish();
         };
         const allocation = this.budget.values.scope();
         originalIO = { ...originalIO, [valueScope]: allocation };
@@ -2518,16 +2619,28 @@ export class Runtime {
         }
         finally {
             try {
-                await Promise.allSettled([
-                    ...[...outputs].map(async (close) => close({ reason: new FsError("ECANCELED", { syscall: "redirect" }) })),
-                    ...[...inputs].map(async (input) => input.close()),
-                ]).then(results => {
-                    const failures = results.filter(result => result.status === "rejected").map(result => result.reason);
-                    if (diagnosticFailure)
-                        io[invocationScope].failures.push(...failures);
-                    else
-                        throwCleanupFailures(failures);
-                }).finally(() => allocation.close());
+                const close = async () => {
+                    await resources.drain();
+                    await Promise.allSettled([
+                        ...[...outputs].map(async (close) => close({ reason: new FsError("ECANCELED", { syscall: "redirect" }) })),
+                        ...[...inputs].map(async (input) => { try {
+                            await input.close();
+                        }
+                        finally {
+                            await inputScopes.get(input)?.close();
+                        } }),
+                    ]).then(results => {
+                        const failures = results.filter(result => result.status === "rejected").map(result => result.reason);
+                        if (diagnosticFailure)
+                            io[invocationScope].failures.push(...failures);
+                        else
+                            throwCleanupFailures(failures);
+                    }).finally(() => allocation.close());
+                };
+                if (resources.busy)
+                    state.backgroundJobs.execution.track(close());
+                else
+                    await close();
             }
             finally {
                 finishSnapshot?.();
@@ -2614,6 +2727,8 @@ export class Runtime {
             const stdinIsDefault = descriptor?.input ? descriptor.stdinIsDefault : false;
             return {
                 [invocationScope]: io[invocationScope],
+                [backgroundResources]: io[backgroundResources],
+                [backgroundPrune]: io[backgroundPrune],
                 ...(io[valueScope] === undefined ? {} : { [valueScope]: io[valueScope] }),
                 ...(io.execution === undefined ? {} : { execution: io.execution }),
                 ...(io.diagnosticLine === undefined ? {} : { diagnosticLine: io.diagnosticLine }),
@@ -2692,15 +2807,29 @@ export class Runtime {
                         const stat = await interruptible(this.fs.stat(path, options), this.signal);
                         if (stat.type === "directory" && !fileShortcut)
                             throw new PublicDiagnostic(`${target}: Is a directory`);
-                        const source = stat.type === "directory" ? toByteSource("")
-                            : await fileInput(this.fs, path, this.budget.limits.maxInputBytes, this.signal, this.inputProfile, { stat, registerCleanup: cleanup => { io[invocationScope].register(cleanup); } });
-                        const input = new ShellInput(source, this.budget, this.signal, { stat, ...source });
-                        inputs.add(input);
+                        const inputScope = (state.backgroundJobs?.execution.scope ?? io[invocationScope]).child();
+                        let input;
+                        try {
+                            const inputSignal = this.commandSignal;
+                            const inputFs = scopeFileSystem(runtimeFileSystems.get(this.fs) ?? this.fs, () => this.budget.fileSystemOperation(), inputSignal, () => this.budget.fileSystemCleanupOperation());
+                            const source = stat.type === "directory" ? toByteSource("")
+                                : await fileInput(inputFs, path, this.budget.limits.maxInputBytes, inputSignal, this.inputProfile, { stat, registerCleanup: cleanup => { inputScope.register(cleanup); } });
+                            input = new ShellInput(source, this.budget, inputSignal, { stat, ...source });
+                            inputScopes.set(input, inputScope);
+                            inputs.add(input);
+                        }
+                        catch (error) {
+                            await inputScope.close();
+                            throw error;
+                        }
                         descriptors.set(redirect.descriptor, { input, stdinIsDefault: false });
                     }
                     else {
+                        const outputSignal = this.commandSignal;
+                        const outputFs = scopeFileSystem(runtimeFileSystems.get(this.fs) ?? this.fs, () => this.budget.fileSystemOperation(), outputSignal, () => this.budget.fileSystemCleanupOperation());
+                        const options = { signal: outputSignal };
                         const append = redirect.operator === ">>";
-                        const capabilities = await this.fs.capabilitiesFor?.(path, options) ?? this.fs.capabilities;
+                        const capabilities = await outputFs.capabilitiesFor?.(path, options) ?? outputFs.capabilities;
                         const random = capabilities.randomAccessWrite === true;
                         const key = resolvePath(state.cwd, path);
                         let file;
@@ -2710,18 +2839,18 @@ export class Runtime {
                                 throw new FsError("ENOTSUP", { path, message: "Conflicting sequential output descriptors" });
                             file.references++;
                             this.outputFiles.set(key, file);
-                        });
+                        }, outputSignal);
                         let closed = false;
                         let offset = 0;
                         const incremental = async () => {
                             await this.fileOperation(key, async () => {
                                 if (append)
-                                    await this.fs.appendFile(path, new Uint8Array(), options);
+                                    await outputFs.appendFile(path, new Uint8Array(), options);
                                 else
-                                    await this.fs.writeFile(path, new Uint8Array(), { ...options, flag: "w" });
+                                    await outputFs.writeFile(path, new Uint8Array(), { ...options, flag: "w" });
                                 if (!append)
                                     file.data = new Uint8Array();
-                            });
+                            }, outputSignal);
                             return { write: (chunk) => {
                                     const copy = new Uint8Array(chunk);
                                     return this.fileOperation(key, async () => {
@@ -2731,18 +2860,18 @@ export class Runtime {
                                         let atEOF = false;
                                         if (!append && current && offset === current.length && capabilities.append === true && capabilities.stat !== false) {
                                             try {
-                                                atEOF = (await interruptible(this.fs.stat(path, options), this.signal)).size === offset;
+                                                atEOF = (await interruptible(outputFs.stat(path, options), outputSignal)).size === offset;
                                             }
                                             catch {
                                                 // Metadata is optional for this optimization; writes need no read access.
-                                                this.signal.throwIfAborted();
+                                                outputSignal.throwIfAborted();
                                             }
-                                            this.signal.throwIfAborted();
+                                            outputSignal.throwIfAborted();
                                         }
                                         if (append || atEOF) {
                                             // Preparing a larger view only touches the unpublished tail of current.
                                             const bytes = current ? appendOutputBytes(current, copy) : undefined;
-                                            await this.fs.appendFile(path, copy, options);
+                                            await outputFs.appendFile(path, copy, options);
                                             file.data = bytes;
                                         }
                                         else {
@@ -2750,12 +2879,12 @@ export class Runtime {
                                             if (current)
                                                 bytes.set(current);
                                             bytes.set(copy, offset);
-                                            await this.fs.writeFile(path, bytes, options);
+                                            await outputFs.writeFile(path, bytes, options);
                                             file.data = bytes;
                                         }
                                         if (!append)
                                             offset += copy.length;
-                                    });
+                                    }, outputSignal);
                                 } };
                         };
                         const resumePathCache = this.budget.pathLookup.suspend();
@@ -2770,8 +2899,8 @@ export class Runtime {
                         let target;
                         let outputScope;
                         try {
-                            outputScope = io[invocationScope].child();
-                            target = await openFileOutput({ fs: this.fs, signal: this.signal, registerCleanup: cleanup => { outputScope.register(cleanup); } }, path, append ? "a" : "w", random ? incremental : undefined);
+                            outputScope = (state.backgroundJobs?.execution.scope ?? io[invocationScope]).child();
+                            target = await openFileOutput({ fs: outputFs, signal: outputSignal, registerCleanup: cleanup => { outputScope.register(cleanup); } }, path, append ? "a" : "w", random ? incremental : undefined);
                         }
                         catch (error) {
                             try {
@@ -2784,8 +2913,8 @@ export class Runtime {
                         }
                         outputs.add(async (completion) => {
                             try {
-                                if (this.signal.aborted)
-                                    await target.abort(this.signal.reason);
+                                if (outputSignal.aborted)
+                                    await target.abort(outputSignal.reason);
                                 else if ("reason" in completion)
                                     await target.abort(completion.reason);
                                 else {
@@ -2793,7 +2922,7 @@ export class Runtime {
                                         await target.finish();
                                     }
                                     catch (error) {
-                                        this.signal.throwIfAborted();
+                                        outputSignal.throwIfAborted();
                                         if (completion.status === 0)
                                             throw error;
                                     }
@@ -2808,7 +2937,7 @@ export class Runtime {
                                 }
                             }
                         });
-                        const output = this.budget.sink(target.sink, this.signal);
+                        const output = this.budget.sink(target.sink, outputSignal);
                         budgetedSinks.get(output).file = Object.freeze({ path });
                         descriptors.set(redirect.descriptor, { output });
                         if (redirect.operator === "&>") {
@@ -2823,14 +2952,15 @@ export class Runtime {
             const diagnostic = errorTarget === undefined ? undefined : filesystemDiagnostic(error, errorTarget);
             throw new ExecutionFailure(error, currentIO(), diagnostic);
         }
+        io[backgroundPrune]?.(descriptors);
         return currentIO();
     }
-    async fileOperation(path, operation) {
+    async fileOperation(path, operation, signal = this.signal) {
         const previous = this.fileWrites.get(path) ?? Promise.resolve();
-        const pending = previous.catch(() => undefined).then(() => { this.signal.throwIfAborted(); return operation(); });
+        const pending = previous.catch(() => undefined).then(() => { signal.throwIfAborted(); return operation(); });
         this.fileWrites.set(path, pending);
         try {
-            await interruptible(pending, this.signal);
+            await interruptible(pending, signal);
         }
         finally {
             if (this.fileWrites.get(path) === pending)
@@ -2911,8 +3041,11 @@ export class Runtime {
         };
         let overlayOpen = false;
         try {
-            if (snapshotScope)
+            if (snapshotScope) {
+                const jobs = state.backgroundJobs;
                 state = await cloneState(state, this.signal, snapshotScope);
+                state.backgroundJobs = jobs;
+            }
             if (words.length) {
                 stateMonitor(state)?.openOverlay(previous);
                 overlayOpen = true;
@@ -3049,6 +3182,8 @@ export class Runtime {
     async dispatchScoped(name, values, state, io, assignments, bypassFunctions) {
         const { [invocationScope]: scope, ...publicIO } = io;
         Reflect.deleteProperty(publicIO, valueScope);
+        Reflect.deleteProperty(publicIO, backgroundResources);
+        Reflect.deleteProperty(publicIO, backgroundPrune);
         const allocation = this.budget.values.scope();
         scope.register(() => allocation.close());
         const argumentValues = this.admitArguments(values, allocation);
@@ -3101,6 +3236,7 @@ export class Runtime {
             const forwardedValues = getCommandArguments(forwarded);
             const admitted = forwardedValues === argumentValues ? argumentValues : this.admitArguments(forwardedValues.values, allocation);
             const context = { ...forwarded, args: admitted.args, argumentValues: admitted, [invocationScope]: scope,
+                [backgroundResources]: io[backgroundResources], [backgroundPrune]: io[backgroundPrune],
                 ...(io[valueScope] === undefined ? {} : { [valueScope]: io[valueScope] }) };
             const previous = new Map();
             const cwd = state.cwd;
@@ -3552,6 +3688,7 @@ export class Runtime {
             directoryStack: { entries: [], bytes: 0 },
             dotglob: false,
             globstar: false,
+            backgroundJobs: new BackgroundJobs(state.backgroundJobs.execution),
             positional: [], arg0: shellValueText(arg0), profile: context.command === "sh" ? "sh" : "bash", status: 0, substitutionStatus: 0, depth: state.depth + 1,
             loopDepth: 0, functionDepth: 0, locals: [], pipefail: false, isolated: true,
             errexit: false,
@@ -3758,6 +3895,8 @@ export class Runtime {
             };
             Reflect.deleteProperty(context, invocationScope);
             Reflect.deleteProperty(context, valueScope);
+            Reflect.deleteProperty(context, backgroundResources);
+            Reflect.deleteProperty(context, backgroundPrune);
             bindCommandIO(context);
             bindFileOutputBudget(context, sink => this.budget.sink(sink, runtime.signal));
             if (argumentValues.values.every(value => typeof value === "string"))
@@ -5024,12 +5163,118 @@ export class Runtime {
             }
         }
     }
+    async waitBuiltin(context, state) {
+        let next = false;
+        let variable;
+        let index = 0;
+        for (; index < context.args.length; index++) {
+            const option = context.args[index];
+            if (option === "--") {
+                index++;
+                break;
+            }
+            if (!option.startsWith("-") || option === "-")
+                break;
+            for (let flag = 1; flag < option.length; flag++) {
+                const letter = option[flag];
+                if (letter === "n")
+                    next = true;
+                else if (letter === "f") { /* Processes do not stop in the virtual shell. */ }
+                else if (letter === "p") {
+                    variable = option.slice(flag + 1) || context.args[++index];
+                    if (variable === undefined) {
+                        await writeDiagnostic(context.stderr, "wait: -p: option requires an argument\n");
+                        return 2;
+                    }
+                    if (!/^[a-zA-Z_][a-zA-Z_0-9]*(?:\[.+\])?$/su.test(variable)) {
+                        await writeDiagnostic(context.stderr, `wait: ${variable}: not a valid identifier\n`);
+                        return 1;
+                    }
+                    break;
+                }
+                else {
+                    await writeDiagnostic(context.stderr, `wait: -${letter}: invalid option\n`);
+                    return 2;
+                }
+            }
+        }
+        const target = variable === undefined ? undefined : /^([a-zA-Z_][a-zA-Z_0-9]*)(?:\[(.+)\])?$/su.exec(variable);
+        if (target) {
+            const name = target[1];
+            if (state.readonlyVariables?.has(name)) {
+                await writeDiagnostic(context.stderr, `wait: ${name}: readonly variable\n`);
+                return 1;
+            }
+            if (target[2] === undefined) {
+                if (arrayStore(state)?.get(name))
+                    await this.unsetIndexed(state, name);
+                else
+                    this.unsetVariable(state, name);
+            }
+        }
+        const publish = async (id) => {
+            if (!target)
+                return;
+            if (target[2] === undefined)
+                await this.assignVariable(state, target[1], id);
+            else
+                await this.arrayAssignment({ kind: "element", name: target[1], index: { decimal: target[2], source: target[2] }, append: false, value: { offset: 0, parts: [{ kind: "text", value: id, quoted: true }] } }, state, context);
+        };
+        const table = state.backgroundJobs;
+        const ids = context.args.slice(index);
+        const selected = [];
+        let invalid = false;
+        for (const id of ids) {
+            if (!id.startsWith("%") && !/^[0-9]+$/u.test(id)) {
+                await writeDiagnostic(context.stderr, `wait: ${id}: not a pid or valid job spec\n`);
+                if (next)
+                    continue;
+                return 1;
+            }
+            const job = table.resolve(id);
+            if (!job) {
+                await writeDiagnostic(context.stderr, `wait: ${id}: not a child of this shell\n`);
+                invalid = true;
+            }
+            else
+                selected.push(job);
+        }
+        if (next) {
+            const eligible = ids.length ? selected.filter(job => !job.waited) : [...table.jobs.values()].filter(job => !job.done && !job.consumed);
+            if (!eligible.length)
+                return 127;
+            const result = await interruptible(Promise.race(eligible.map(async (job) => ({ job, status: await job.promise }))), this.signal);
+            result.job.consumed = true;
+            await publish(result.job.id);
+            return result.status;
+        }
+        if (!ids.length) {
+            await interruptible(Promise.all([...table.jobs.values()].map(job => job.promise)), this.signal);
+            table.jobs.clear();
+            return 0;
+        }
+        let status = invalid ? 127 : 0;
+        for (const id of ids) {
+            const job = table.resolve(id);
+            if (!job) {
+                status = 127;
+                continue;
+            }
+            status = await interruptible(job.promise, this.signal);
+            job.consumed = true;
+            job.waited = true;
+            await publish(job.id);
+        }
+        return status;
+    }
     async builtin(context, state, assignments, diagnose, suppressSpecial = false) {
         const { command, args, stdout, stderr } = context;
         if (command === ":" || command === "true")
             return 0;
         if (command === "false")
             return 1;
+        if (command === "wait")
+            return this.waitBuiltin(context, state);
         if (command === "shopt")
             return this.shoptBuiltin(context, state);
         if (command === "let")
@@ -5829,11 +6074,14 @@ export class Runtime {
             const substitutionDiagnosticLines = new Map();
             for (const [command, line] of part.script.printedLines ?? [])
                 substitutionDiagnosticLines.set(command, part.sourceLine === undefined ? warningLine + (command.line ?? part.line) - part.line : warningLine + line - 1);
-            const captureIO = { ...isolateIO(io), substitutionDiagnosticLines, diagnosticOffset: (io.diagnosticLine ?? part.line) - (part.sourceLine ?? part.line), stdout: this.budget.sink(capture, this.signal) };
+            const resources = new BackgroundResources();
+            const captureIO = { ...isolateIO(io), [backgroundResources]: [...io[backgroundResources] ?? [], resources], substitutionDiagnosticLines, diagnosticOffset: (io.diagnosticLine ?? part.line) - (part.sourceLine ?? part.line), stdout: this.budget.sink(capture, this.signal) };
+            resources.destination = backgroundDestination(captureIO.stdout);
             try {
                 state.substitutionStatus = fileShortcut ? await this.runCommandIsolated(command, child, captureIO, true) : await this.run(part.script, child, captureIO);
             }
             finally {
+                await interruptible(resources.drain(), this.signal);
                 stateMonitor(child)?.closeValues();
             }
             state.status = state.substitutionStatus;
@@ -5879,13 +6127,14 @@ export class Runtime {
             io[valueScope]?.reserve(values.length * 32 + 64, 0);
             return concatShellValues(values.flatMap((value, index) => index ? [separator, value] : [value]), io[valueScope]);
         }
-        let value = part.name === "?" ? String(state.status)
-            : part.name === "-" ? `${state.errexit ? "e" : ""}${state.nounset ? "u" : ""}${state.braceexpand !== false ? "B" : ""}`
-                : part.name === "#" ? String(state.positional.length)
-                    : part.name === "@" || part.name === "*" ? state.positional.join(hereString && (part.name === "@" || !part.quoted) ? " " : Array.from(state.variables.IFS ?? " ")[0] ?? "")
-                        : /^0+$/u.test(part.name) ? state.arg0 ?? "virtual-bash"
-                            : /^\d+$/u.test(part.name) ? state.positional[Number(part.name) - 1]
-                                : this.variable(state, part.name);
+        let value = part.name === "!" ? state.lastBackgroundJob
+            : part.name === "?" ? String(state.status)
+                : part.name === "-" ? `${state.errexit ? "e" : ""}${state.nounset ? "u" : ""}${state.braceexpand !== false ? "B" : ""}`
+                    : part.name === "#" ? String(state.positional.length)
+                        : part.name === "@" || part.name === "*" ? state.positional.join(hereString && (part.name === "@" || !part.quoted) ? " " : Array.from(state.variables.IFS ?? " ")[0] ?? "")
+                            : /^0+$/u.test(part.name) ? state.arg0 ?? "virtual-bash"
+                                : /^\d+$/u.test(part.name) ? state.positional[Number(part.name) - 1]
+                                    : this.variable(state, part.name);
         let retained = value;
         if (!part.length && value !== undefined) {
             if (/^[a-zA-Z_][a-zA-Z_0-9]*$/u.test(part.name) && !arrayStore(state)?.get(part.name))