Command environment and containment

While DataMind Oda works on a task, it runs commands on your computer, and every other program it starts uses the same machinery: the language servers it starts for code navigation, the shells kept alive between commands, and the helper programs behind delegated work. This page covers the shell Oda uses, the limits every command runs under, what those programs see of your settings, how a command is started and held together, and what happens to it and its output when the work ends. Commands you type in your own terminal are not these commands; that shell is yours.

What Oda runs, and under what limits

• The commands in a chat are one surface of this machinery; Shell commands covers how they run and how to read them. The others are Language servers for code navigation, the Persistent shells kept between commands, and the separate programs behind Subagent backends.
• Every program starts the same way, and each command is held together with everything it starts, so the whole piece of work can be stopped as one.
• Commands follow the chat's access mode. A command that tries to change files beyond what the mode allows is stopped by the file sandbox, and the attempted change is not made; Command sandbox and approvals covers the denial and the one wider retry you can allow, and Workspaces, files and permissions covers the modes themselves.

The shell that runs your commands

Oda uses the shell that fits your computer:

• One shell only. Oda loads exactly one shell engine. An installation that adds a second one fails to start rather than running both.
• No leftover state. A one-shot command runs in a fresh shell process that loads none of your profile or startup files, so its folder and variables do not carry into the next call. When work needs the same folder and variables across commands, see Persistent shells.

On Windows, Oda looks for PowerShell and uses the first candidate it can run:

1. A path configured for Oda, when one is set.
2. The standard PowerShell 7 install folder.
3. The folders on your PATH.
4. Windows PowerShell 5.1, as a last resort.

When the configured path changes, Oda looks again for later commands; no restart is needed.

Limits every command runs under

Oda applies the same limits to each command, whichever shell runs it:

The time limit and the output cap can be changed from the Plugins page; see Shell settings. Changes apply to later commands without restarting Oda. A value Oda cannot use is caught when the next command runs, not when it is saved.

What a command sees of your environment

• Each command starts from a cleaned copy of your computer's settings: a variable whose name contains KEY, PASSWORD, SECRET or TOKEN, in any casing, is left out, along with Oda's own working values.
• The cleaning reads names, not values, so treat it as a guard and not a guarantee: a secret kept in a variable with an unrelated name can still reach a command.
• When a step deliberately hands a value over, that value still arrives, alongside the cleaned copy. Oda can also drop an inherited variable for one command without touching the rest.
• Everyday facts arrive unchanged: where programs live (PATH), your home folder, your language and text settings, and your proxy settings; Network proxies in Oda covers how a proxy reaches the programs Oda runs. When only ALL_PROXY is set, Oda also fills it into HTTP_PROXY for the Node programs it starts, because they read that one; localhost, 127.0.0.1 and ::1 stay direct.

What every command receives

• Plain output. Colour and paging are turned off: NO_COLOR=1, PAGER=cat and GIT_PAGER=cat are set. bash commands also get TERM=dumb. PowerShell commands have their output pinned to UTF-8.
• Managed variables, so your own scripts can find the same facts Oda works with:

How a command starts

• A start is fully explicit: the program, its arguments, the folder it runs in, the settings it receives and how its input and output are wired are all supplied; nothing is filled in silently.
• What runs is the program and its arguments exactly as named; shell text is not interpreted for you. When a shell step is needed, the shell itself is named as the program.
• A request that names no program is refused before anything starts.
• The program must resolve. A full path is used as given; a bare name is looked up on the program search path, with the Windows endings .COM, .EXE, .BAT and .CMD among the names tried. A relative path is refused with is a relative path; use an absolute path or a bare PATH name, a name that cannot be found with was not found on PATH, and a file that cannot be run with is not an executable file. Nothing runs.
• A command cancelled before the program could run reports aborted before spawn: <reason>.
• On Windows, a program that cannot start reports spawn <program> <code>, with a short code such as ENOENT. A failure with no known short code reports spawn <program> UNKNOWN (Windows error <number>); the number, and any text after it, carries the system's own reason, for example a security policy that blocks the program. If the part of Oda that owns processes on Windows cannot start, the command reports an error instead of running.

How a command is held and stopped

• Each command gets a managed range: the program, and everything it starts, move together, and stopping the work stops the whole range. Oda asks the processes to stop first and forces anything still running after a short grace period; asking again changes nothing. Process containment and cleanup covers how the range is owned on each kind of computer.
• A wait for a command to finish resolves only when nothing of the command is left; when that cannot be proven, the wait fails instead of guessing.
• On Windows, the programs Oda starts for commands, and its own stop helpers, start with their windows hidden, so a background command never flashes a console window or takes focus from what you are doing.
• Oda prefers the strongest containment your computer can offer, and re-checks that support at each start. When it is unavailable, the command runs under a weaker fallback, and Oda records one note per app run, naming the reason.
• Oda never starts a command a second time through the fallback: once the stronger path may have started it, it is not replayed.

What is kept of a command's output

• When more output arrives than the run keeps, the end of the output is kept, because errors and results cluster there, and the result is marked as cut; Result limits and spill files covers the notes a cut carries and how each kind of result is shortened.
• With a size set for the stream, the command's complete output is written to a private file while it runs: a folder only your user account can open, with randomly named files. Oda does not delete the file when the command ends, so the output can still be read back afterwards. A stream that outgrows that size loses the incomplete file and keeps only the marked end.
• A read that starts before the part still held comes back marked incomplete: Oda returns what is left and says the read is lossy, so treat what you get as partial.
• A failure report that a delegated helper program attaches to its result is capped at 4,096 bytes; when it is cut, it ends with [diagnostic truncated].
• A command's ending is recorded as its exit code, or as the signal that ended it; no separate timeout or cancellation label is added to that record.

When Oda stops or closes

• When you quit Oda, or when it exits through an error it can catch, it stops the commands it still manages before leaving, so they do not keep running on their own.
• A forced kill, an out-of-memory stop, or a crash below the app cannot be caught from inside Oda; those cases are left to the operating system, or to an outside supervisor, to clean up.
• A private control channel Oda uses to manage a running command is reserved: nothing outside Oda can set it up, and an attempt to supply it is refused before the command starts. A program that expects the channel but is not given it fails with subprocess control channel was not inherited. Nothing on the channel enters the command's output, and it carries no authority to skip an approval.

Questions, answered

Which shell does Oda run commands in?

PowerShell on Windows; bash on macOS and Linux. Oda loads exactly one shell engine, so commands never run through a mix of shells. On Windows it uses, in order, a configured path, the standard PowerShell 7 install folder, your PATH, then Windows PowerShell 5.1 as a last resort.

Can I change the time limit or the output cap?

Yes. Open the Plugins page and change them there; the changes apply to later commands without a restart. A value Oda cannot use is accepted when saved, and the next command fails instead of running, with a message about the value. See Shell settings.

Does a command see my passwords and keys?

No. Variables whose names contain KEY, PASSWORD, SECRET or TOKEN, in any casing, are left out, as are Oda's own working values. The cleaning reads names and not values, so a secret kept under an unrelated name is not covered; when a step deliberately hands a value over, it still arrives.

What variables does every command receive?

DATAMIND_HOME (Oda's data folder), DATAMIND_SHELL (set to 1), DATAMIND_SESSION_ID (the chat the command belongs to), and DATAMIND_PROFILE and DATAMIND_PROFILE_DIR when a profile is set. Colour and paging are also turned off, so results are plain text.

Why was my command refused before it started?

The start request was incomplete or the program could not be resolved: a missing program name, a relative path, a name not found on PATH, or a file that cannot be run. Oda reports which one, and nothing runs.

How is a command different from a terminal session?

A command runs once: it starts, does its work, returns its output and ends. A terminal session is an interactive shell that stays open while Oda types into it and reads what comes back; Terminal sessions covers those.

Why did a program fail to start on Windows?

A program that cannot start reports spawn <program> <code>, with a short code such as ENOENT. A failure with no known short code reports spawn <program> UNKNOWN (Windows error <number>); the number and any text after it carry the system's own reason, for example a security policy that blocks the program. Nothing ran.

When a command is stopped, does everything it started stop too?

Yes. A command and everything it starts are held as one managed range. Stopping the work asks the whole range to stop, gives it three seconds by default, and then forces anything still running.

Can I still read a command's full output after it ends?

Yes. When the complete output is written to a file while the command runs, the file stays after the command ends, so Oda can read it back or search inside it when you ask. It sits in a folder only your user account can open; Result limits and spill files covers where such files live and when they are cleared up.

Why did part of an earlier output come back incomplete?

The run keeps a window of the most recent output. Once older output slides out of that window, a read that starts from before it cannot return the missing part, so Oda returns what is still held and says the read is lossy. Treat the result as partial.

What happens to running commands when Oda closes or crashes?

When you quit Oda, or when it exits through an error it can catch, it stops the commands it manages before leaving. A forced kill, an out-of-memory stop, or a crash below the app cannot be caught from inside Oda, so those cases are left to the operating system, or an outside supervisor, to clean up.

Could my command be started a second time when containment falls back?

No. Oda never starts a command a second time through the weaker fallback: once the stronger path may have started it, it is not replayed. A command that ran under the fallback ran that way from the start.