Remote files, processes and terminals

With remote execution over SSH set up, the files, commands and terminals of a chat are handled on the remote Linux or macOS computer while DataMind Oda stays on this computer. This page covers how that remote side behaves: files, commands, terminals, confinement, and the codes a failure can carry. The connection itself, and what to install, are in Remote execution over SSH.

Remote files

Paths are resolved on the remote computer. Oda resolves every path there, links included, so an operation acts on the file the path really names.
Changes are guarded. A write creates a file only when it is absent, or replaces one only while the version Oda read is still current; a guarded replace that no longer matches is refused with FS_STALE_VERSION.
Watching is not available. A watch request for a remote file or folder is refused with FS_IO_ERROR, without asking the remote side, and Oda does not check the file in a loop instead.
A dropped connection is an I/O failure. If the connection drops during a file operation, the operation fails and is not retried, and a change may already have completed on the remote computer.

Important

After a dropped connection, check the remote computer before you repeat the work.

Reads are capped at 8 MiB. A whole read, or one window inside a remote file, stays within 8 MiB; a read that would go past that budget is refused with FS_TOO_LARGE. Read larger files in parts.
A file's name stays as it is. When Oda identifies a remote file, a name containing %, a backslash or a line break is encoded in that identifier only, as back\slash.ts becomes back%5Cslash.ts; the file keeps its exact name on the remote computer.

Remote commands

The remote side is prepared before a program starts. Oda reserves and authenticates the channels a program needs (input, output, errors and a control channel) before starting it; each stream is its own channel, so a busy output does not hold up the others.
A start that fails is reported. If a program stops before its start is confirmed, the result reads SSH process terminated before launch acknowledgement.
The end of a command is not the end of its work. A finished remote command reports its exit code, or the signal that ended it. That report does not prove that everything the program started has also stopped; Oda observes the true end separately, and a wait for it resolves only when nothing is left.
Stopping is safe to repeat. Asking to stop the same remote process again changes nothing, even while an earlier stop is still in progress. If the remote side cannot confirm the stop, Oda reports SSH process cleanup could not be confirmed rather than claim the program stopped.
A missing program is a lookup miss. A program Oda cannot find on the remote computer is reported with SUBPROCESS_EXECUTABLE_NOT_FOUND, apart from an SSH failure.
Collected output keeps its positions. A collected result keeps a bounded window of the end of the output, with byte offsets measured from the start of the stream, so the completed result does not change when the connection lags.
Large output can stay on the remote computer. When output is large, the full stream can be kept in a private file on the remote computer; such files stay until the computer's own temporary-file cleanup removes them.

Remote terminals

The terminal runs on the remote computer. The shell starts on the remote side, and its activity comes back from there.
Activity is idle, busy or unknown. A remote terminal reports its activity as idle, busy or unknown; a missing answer is not treated as a quiet terminal.
Signals. Oda can send SIGINT, SIGTERM, SIGKILL, SIGTSTP or SIGHUP to what is running in a remote terminal.
A terminal that cannot be allocated. If Oda cannot allocate a remote terminal and the remote cleanup also fails, the result reads SSH terminal allocation failed and remote cleanup is unknown; treat the remote cleanup as unconfirmed.

The actions a terminal offers, and the notes they return, are described in Terminal tools.

Remote confinement

Confinement is applied on the remote computer. When Oda asks for a confined remote command, the remote side resolves the request and wraps the command itself before it can run. If the confinement cannot be applied, the command is refused before it runs, with SANDBOX_UNAVAILABLE, rather than run unconfined by accident.
Full access runs remote work without confinement, by design. The access modes are described in Workspaces, files and permissions.
What confinement covers. On the remote side, confinement limits file effects only: it does not restrict network access or hide other processes on the remote computer. The remote side states whether it enforces the limits fully or only partly, and a partial level stays partial.

For what a blocked command looks like in the chat, and how a wider one-off retry is approved, see Command sandboxing and approvals.

Error codes

When a remote operation fails, Oda reports the code the remote side returned, unchanged. The common codes:

Code	What it tells you
`FS_STALE_VERSION`	A guarded replace was refused: the file changed since Oda read it. Read the file again, then repeat the change.
`FS_SANDBOX_DENIED`	The remote confinement refused the file change, for example a change attempted under read-only.
`FS_NOT_OBSERVED`	The remote file layer refused the operation and returned this code. Check the file on the remote computer, then retry.
`FS_TOO_LARGE`	A whole read went past the remote side's 8 MiB budget. Read the file in parts.
`FS_IO_ERROR`	An I/O failure: the connection dropped, or a remote file operation Oda does not classify further failed, such as a watch. A dropped connection is not retried.
`FS_ABORTED`	The operation was cancelled before it finished, and is not retried.
`FS_NOT_FOUND`	The remote side does not have that file or folder.
`SUBPROCESS_EXECUTABLE_NOT_FOUND`	The program is not on the remote computer; a lookup miss, reported apart from an SSH failure.
`SANDBOX_UNAVAILABLE`	The remote side could not apply the requested confinement, so the command was refused before it ran.

Connection-level failures, such as a connection that drops or is closed, are described with the connection in Remote execution over SSH.

Questions, answered

Why did a remote file change come back with `FS_STALE_VERSION`?

A guarded replace was refused: the file changed on the remote computer since Oda read it. Read the file again, then repeat the change.

Can Oda read a remote file that is larger than 8 MiB?

Yes, in parts. A whole read, or one window inside a remote file, is capped at 8 MiB; a read that would go past that budget is refused with FS_TOO_LARGE. Ask Oda to read the file in smaller windows.

Why is a remote file operation not retried after the connection drops?

Because Oda cannot know what completed on the remote computer before the connection dropped. A dropped connection during a file operation is reported as an I/O failure, the operation is not retried, and a change may already have been made. Check the remote computer before you repeat the work.

Does the end of a remote command mean everything it started has stopped?

No. A finished remote command reports its exit code, or the signal that ended it, but that does not prove that everything the program started has also stopped. Oda observes the true end separately: a wait for it resolves only when nothing is left.

Is it safe to stop the same remote process again?

Yes. Asking to stop the same remote process again changes nothing, even while an earlier stop is still in progress. If the remote side cannot confirm the stop, Oda reports SSH process cleanup could not be confirmed and does not claim the program stopped.

What does `SSH terminal allocation failed and remote cleanup is unknown` mean?

A remote terminal could not be allocated, and the remote side could not confirm that it cleaned up the half-made terminal. Treat the remote cleanup as unconfirmed, and check the remote computer before continuing.

What do idle, busy and unknown mean for a remote terminal?

They are what a remote terminal reports about its activity: idle, busy, or unknown when no answer has come back. Oda does not treat a missing answer as a quiet terminal.

What does `SSH process terminated before launch acknowledgement` mean?

A remote program stopped before its start was confirmed, so there is no running program for the command. Treat the run as failed and check the remote computer before retrying.