`run` 0.1.0

Start one program from the deployer's programs directory with exact arguments, no shell, a fixed environment, a deadline and an output cap; answers its exit status and output. Opt-in: it can run whatever the directory holds, and it does not sandbox it.

run [--root DIR] [--timeout-ms N] [--max-output N] [--stdin] [--max-stdin N] [--format json|text] -- PROGRAM [ARG...]

output: one JSON document
schema: run.v1
reversibility: irreversible-consequential
guarantees: bounded_memory
concurrency: none: it takes no lock and cannot see what the program it starts then does
confinement: beneath: with --root, paths are checked lexically against it and then opened beneath it one component at a time, following no symbolic link (path.symlink), so nothing outside the root is reachable through one; without it, a reader opens the path as given, links and all, and a writer still follows no link in the file's own name
reads the environment: no
reads the clock: no
compiler: de4e52fd8180
for an agent: SKILL.md (run skill)

Authority

Derived by cancho authority from the source, embedded in the binary, and checked against tools.toml's ceiling in CI. Every label is bounded.

args
child_signal
clock
err_write
exec("/opt/cancho-tools/programs")
fs_read("")
heap
io_read
io_write
pipe_read
pipe_write
poll

What the row cannot say:

path extent: a path from the command line is checked at run time, so the row says fs_read("")
what a symlink reaches
what standard output carries
resource use beyond the tool's own caps (memory, wall time)
per-invocation behaviour such as --dry-run, which the row cannot see

Operands

Operand	Role	How many	Meaning
`PROGRAM`	`name`	1	a program name in the programs directory, never a path
`ARG...`	`text`	0 or more	the program's arguments, passed byte for byte

Flags

Flag	Kind	Role	Default	Meaning
`--root`	`path`	`root`		start the program in this directory (default: the working directory) and refuse a directory outside it
`--timeout-ms`	`nat`	`none`	`30000`	the longest the program may run, in milliseconds, after which it is killed (1 to 600000)
`--max-output`	`nat`	`none`	`1048576`	the most bytes kept from each of standard output and standard error, and the program is killed at the first byte past it (ceiling 67108864)
`--stdin`	`bool`	`none`		give the program this tool's standard input as its standard input (default: nothing)
`--max-stdin`	`nat`	`none`	`1048576`	the most standard input accepted with --stdin (ceiling 67108864)
`--format`	`choice:json/text`	`none`	`json`	json for a program, text writes the program's standard output to standard output and its standard error to standard error

Limits

Limit	Default	Ceiling
`timeout-ms`	30,000	600,000
`max-output`	1,048,576	67,108,864
`max-stdin`	1,048,576	67,108,864

Exit codes

Code	Name	Meaning
0	`SUCCESS`	what was asked was done; zero matches is success
2	`INVALID_ARGS`	the invocation is malformed or names something of the wrong kind; nothing was read
3	`NOT_FOUND`	a named input does not exist
4	`PERMISSION_DENIED`	the operating system refused, or the tool's own confinement did
8	`PRECONDITION_FAILED`	the answer is no, or a limit was reached

Rules (21)

Match on rule, not on the message. A retry repair is an argv that can be run as it stands, and never widens what the tool may touch.

Rule	Exit	Repair	When
`args.unknown-flag`	2	sometimes	a flag that is not in the tool's table
`args.missing-value`	2	never	a flag that takes a value was given none
`args.bad-value`	2	never	a flag's value is not of the flag's kind
`args.unexpected-value`	2	never	a flag that takes no value was given one
`args.duplicate-flag`	2	never	the same flag was given twice
`args.missing-operand`	2	never	an operand the tool needs was not given
`path.empty`	2	never	an empty path
`path.dotdot`	2	sometimes	a path with a `..` component
`path.absolute`	2	always	an absolute path where one relative to --root is wanted
`path.outside-root`	4	never	an absolute path that is not under --root
`path.too-long`	2	never	a path longer than 4096 bytes
`path.symlink`	4	never	a path that runs through a symbolic link, which the tool does not follow
`io.not-found`	3	never	a named input does not exist
`io.not-a-directory`	3	never	a path runs through something that is not a directory
`io.permission-denied`	4	never	the operating system refused access
`limit.input-too-large`	8	sometimes	an input longer than --max-bytes
`run.program-name`	2	never	the program is not one plain name (it is empty, `.`, `..` or has a `/`)
`run.program-not-found`	3	never	the programs directory holds no program of that name
`run.spawn-failed`	8	never	the operating system could not start the program or its channels
`limit.timeout`	8	never	the program ran past --timeout-ms and was killed
`limit.output-too-large`	8	never	the program wrote more than --max-output to one stream and was killed

Evidence

each gate is a test in cancho-tools/tests/conformance, run by CI on the commit this binary was built from:

M1 schema conformance
M2 determinism
M3 rule coverage and hint soundness
M4 fault injection
M5 differential against GNU
M6 authority
M7 mutation behaviour
M8 confinement
M9 memory flatness

Agent in the loop: not run: no claim that this tool is more agent-friendly than the incumbents is made (cancho docs/agent-toolbox.md section 7.2).

run 0.1.0