Arcane.terminal.signal()

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

Syntax

Arcane.terminal.signal(sessionId, signal="interrupt")

Parameters

sessionId; signal: "interrupt" or "terminate"

Return value

Promise<{sessionId,signal,accepted}>

Description

Requests a supported control signal. accepted reports process-controller acceptance, not process exit; observe terminal.exit for completion.

Overview

Arcane.terminal.signal(sessionId, signal = "interrupt") sends one supported control request to a running app-owned session. It is non-idempotent process control. Subscribe to terminal.exit before signaling when the application needs to observe whether the process exits.

Signal request

On desktop Core hosts, interrupt maps to the host's SIGINT process-control request and terminate maps to SIGTERM. Android applies the supported request through its sandbox process-destruction boundary; applications must not depend on Unix signal details there.

Acceptance result

The method resolves to:

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

accepted is a boolean and may be false. A true value means the host accepted the control request, not that the process exited or used a particular exit code. Observe terminal.exit for the final outcome.

Errors and recovery

Do not retry a signal automatically after an ambiguous transport failure; the first request may already have affected the process.

Example

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

if (!terminal?.signal || !terminal?.list || !events?.on) {
    throw new Error('Terminal process control is unavailable.');
}

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

if (!session) {
    throw new Error('Start a terminal session before signaling 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.signal(session.id, 'interrupt');
    console.log('Interrupt request accepted', result.accepted);

    if (result.accepted) {
        const exit = await Promise.race([
            exited,
            new Promise(function waitForExitTimeout(resolve) {
                setTimeout(function resolveExitTimeout() {
                    resolve(null);
                }, 2000);
            })
        ]);
        console.log(exit ? 'Session exited' : 'Session remains available');
    }
} catch (error) {
    if (error instanceof Arcane.Error) {
        console.error(error.code, error.message, error.resolution);
    } else {
        throw error;
    }
} finally {
    offExit();
}

Reference group

Applications, terminal, and capabilities