Arcane.terminal.close()

This focused page is derived from the mechanically checked full member inventory.

Syntax

Arcane.terminal.close(sessionId)

Parameters

sessionId: 1–128-character session identifier

Return value

Promise<{sessionId,accepted:true}>

Description

Closes input and requests session termination. The resolved value acknowledges the request; observe terminal.exit for actual process completion.

Overview

Arcane.terminal.close(sessionId) asks the host to close one app-owned terminal session. It is non-idempotent process control. The host may close input and then terminate the process according to its platform policy.

The resolved result acknowledges the close request; it is not the process exit record. Subscribe to terminal.exit before calling close() and use that event as the final lifecycle observation. Calling close() again after the host retires the session can reject with TERMINAL_SESSION_NOT_FOUND.

Session identifier

Acceptance result

The method resolves to:

const result = {
    sessionId: 'term-example',
    accepted: true
};

accepted: true means that the host accepted the close request. It does not mean the process has exited, that an exit code is already available, or that all earlier output chunks have been rendered.

Errors and recovery

TERMINAL_SESSION_INVALID means the identifier does not satisfy the public session-id contract. TERMINAL_SESSION_NOT_FOUND means the session has already exited or been retired. Treat the latter as stale local state and refresh the owned inventory instead of repeatedly closing the same id.

METHOD_NOT_ALLOWED and ARCANE_TRANSPORT_UNAVAILABLE indicate an availability or host problem, not a session problem. Reopen the admitted Arcane Terminal host rather than retrying the close call in a browser preview.

Example

const terminal = globalThis.Arcane?.terminal;
const events = globalThis.Arcane?.events;

if (!terminal?.close || !terminal?.list || !events?.on) {
    throw new Error('Terminal session closure is unavailable.');
}

const {sessions} = await terminal.list();
const session = sessions[0];

if (!session) {
    throw new Error('Start a terminal session before closing it.');
}

let offExit = function ignoreExitUnsubscribe() {};

const exited = new Promise(function waitForTerminalExit(resolve) {
    offExit = events.on('terminal.exit', function handleTerminalExit(payload) {
        if (payload.sessionId === session.id) {
            offExit();
            resolve(payload);
        }
    });
});

try {
    const result = await terminal.close(session.id);
    console.log('Close request accepted', result.accepted);

    const exit = await Promise.race([
        exited,
        new Promise(function waitForExitTimeout(_resolve, reject) {
            setTimeout(function rejectExitTimeout() {
                reject(new Error('Timed out waiting for terminal.exit.'));
            }, 5000);
        })
    ]);
    console.log('Process exited', exit.exitCode, exit.signal);
} catch (error) {
    if (error instanceof Arcane.Error) {
        console.error(error.code, error.message, error.resolution);
    } else {
        console.error(error);
    }
} finally {
    offExit();
}

Reference group

Applications, terminal, and capabilities