Reference
Trust boundary and state provenance
See what a value from a cloned repository can decide and what each machine has to confirm.
What comes from the clone does not decide execution
Running Orkastery in a third-party repository does not execute code just because of that. A value that comes from the clone does not become a process option, an executable or a path outside the root; the only commands run by design are the declared ones.
The trust boundary is the audit of every process call and every path the core builds with data from the clone, with the class of each one and no exploitation recipe. The full matrix, module by module, is in the source.
In version 0.6.10, the audit fixes and the state provenance rules ship, the latter as a security patch, by the owner’s decision.
What the core trusts
The command line belongs to whoever is at the keyboard: it is trusted, but validated when it goes to git, as with --remoto, --para, --de and thread ids. The environment and the account folders (~/.orkastery, ~/.claude and ~/.codex) are trusted too.
Not trusted: the versioned manifest and setup (orkastery.yaml and orkastery.setup.json), state versioned in the clone (.orkastery and the .ork-ci/<thread>.json bundles), the state branches (ork/roadmap-reservas, the factory’s and the ork/* ones) and whatever comes from another machine in the network (snapshots, reservations and the roadmap frontmatter). Tool output (git, runtime) is data, never code.
Every process call and every path in the matrix gets one of these classes. Every process call in the core uses an argument vector, without a shell; a shell exists only in the declared commands and in the MCP sandbox probe.
- Declared: a command that the manifest or a claim declares to run. It is the product (re-running what is claimed), and
SECURITY.mddocuments it. - Inert: constants only, or trusted data.
- Defended: external data, but validated, placed after
--end-of-options, with a qualified ref or a checked sha. - Fixed: it was option injection, an executable chosen by the clone or a path outside the root.
- Fixed by owner decision: it closes a pending item by changing behavior, and the owner chose to merge it as a security patch.
- Pending with the owner: closing it means changing behavior that is documented or accepted today, and the decision belongs to the owner.
Declared commands
They are the only ones the core runs by design, and SECURITY.md lists them all. The documentation promises no runtime warning: treat the orkastery.yaml and the state of a third-party repository like a Makefile.
ork doctor, ork board, ork thread list, ork init, ork thread new and ork retry plan do not run declared commands.
verify.build,verify.test,verify.typecheckandverify.preparo, in the worktree, throughork verify,ork fix open,ork fix reverify,ork retry run(in the corrigir-dirigido action), the baseline ofork phase runand the gate ofork ship.ci.commandand the.ork-ci/<thread>.jsonbundle, inork ci runon the CI runner.- Claims (
claims.jsonland--verificar) and thedoneWheninthread.json, in the same commands as verify;ork claims addruns them only with the manifest policy. - GO-FIX corrections and the claims of audit findings (
board.jsonl), inork fix reverifyand in the check of an audit round. - The runtime binary (claude and codex), through the adapters, in
ork phase runandork retry run.
ork verify <thread>
ork fix reverify <thread>
ork audit verify <rodada>
ork ci run --branch <branch>The five provenance rules
In version 0.6.10, five rules (P1 to P5) close the items the audit left pending with the owner. The idea is the same in all of them: what comes with the repository does not decide the executable, a path outside the root or what this machine publishes; when the use is legitimate, the machine confirms outside git, and the refusal is typed and names the command.
- Sandbox posture (P1): a
runtime.sandboxthat gives the agent full access (danger-full-access) only dispatches through Codex afterork setup sandbox confirmar <postura>, stored in.orkastery/private/postura-local.json(0600, outside git, for this checkout only). Without it,ork phase runandork retry runrefuse withruntime.sandbox-nao-confirmado, andork doctorreports it. - Tracked state (P2): versioned
.orkasterystate does not choose the cwd, the worktree or the executable (estado.rastreado). A cwd that comes fromthread.json, the ledger or the queue, for the agent or for git, only counts at the project root or in a worktree the repository has registered (estado.worktree-nao-registrada). This covers dispatch, resume, verify, claims, GO-FIX, the GO proof, handoff, liveness,ork ci prepare,ork worktree auditandork worktree release. - Pulse and digest transport (P2): only the local
pulse-host.jsonandmaster-host.jsoncount, regular files not tracked by git (transporte.rastreado). - Recall and handoff pointers (P2):
ork recall,ork handoff recallandork handoff exportonly read a file that, by its real path, sits at the project root or in the thread’s registered worktree. Recall refuses withponteiro.fora-da-raiz, and export no longer points outside. - Worktree folder (P3): a
worktree.dirthat leads outside the root by its real path (absolute path, parent directory, a link in the path or.git) only creates a worktree afterork setup worktree confirmar, stored in.orkastery/private/worktree-local.json(0600, outside git, for this checkout and this folder only). Without it, creation refuses withworktree.dir-fora-da-raiz, andork doctorreports it. Existing worktrees keep working, and the MCP still refuses a worktree outside the root. - Eval (P4):
ork evalonly runs the catalog (behavior scenarios, hooks andcore/dist) of the package that is running. A directory with skills, references and eval folders found from the cwd that is not the package’s own refuses witheval.catalogo-alheio, and the message says how to run that checkout’s eval on purpose. The kit’s CI, withnode core/dist/index.js evalat the root, does not change. - Shared factory (P5):
fabrica.compartilhada:truein the manifest no longer turns on publishing this machine’s snapshot (threads, name and host) to the clone’s remote, nor reading the other machines. Only the machine’s own membership does:ork fabrica entrar, in~/.orkastery/maquina.json, orORK_FABRICA_COMPARTILHADA=1. With the request in the manifest and no membership,ork doctorandork fabricawarn withfabrica.nao-confirmada.
ork setup sandbox confirmar danger-full-access
ork setup worktree confirmar
ork fabrica entrar
ork doctor
git rm -r --cached .orkasteryWhat the audit fixed
In version 0.6.10, the audit fixes these cases without changing accepted behavior:
- The
mergeShaand the target branch of aship_donein the ledger only reach thegit logof the revert detection as a hexadecimal sha and a branch name, after--end-of-options; before, a ledger versioned in the clone passed an option to git, inork masterandork ship. ork docs sincronizarno longer falls back to the raw manifest base when it does not resolve, and, from the ledger sha and the frontmatter commit, only a hexadecimal sha reaches git.- The manifest refuses a
worktree.base_branchthat is not a valid branch name for git (it starts with a hyphen or contains ..). - The manifest refuses a relative
memory.cli: it accepts a name looked up inPATH, like orkmind, or an absolute path. The OrkMind probe, including the one inork doctor, ignores relativePATHentries and a shebang with a relative interpreter, andork brainruns the executable with its cwd in$HOME, not at the clone root. .orkastery,.orkastery/threadsand a thread folder as a symbolic link refuse withestado.link, and appends to the ledger, claims and board useO_NOFOLLOW; before, a versioned link sent the write outside the root.- The id of an audit round read from
run.jsonmust be a simple name (audit.rodada-invalida). SECURITY.mdnow lists every declared command, includingverify.preparo,ci.command, the.ork-ci/<thread>.jsonbundles anddoneWhen.
Private data barrier and DSN outside the environment
In version 0.6.10, the private data barrier is a core command: ork privado varrer looks for home paths, email outside the allowed list, hostnames in machine format and the terms of the local list, which stays outside git. Exceptions in orkastery.privado.json require an exact pattern and value, without wildcards, with the path only as a filter and a required reason. The report states file, line, column and pattern, never the value, and masks the name of a file with a finding.
With the dado_privado policy in the manifest, ork verify scans the thread diff and fails with policy.violation in block, and ork ci prepare refuses to write the bundle when there is a finding. In the core CI, the scan is a step of the documentacao job. The local list is only read as a regular file of the current user, without a link and with 0600 permissions; when absent, as in CI, only the generic patterns run, and the output says so.
The memory DSN gains a source outside the agents’ environment: memory.database_url_file points to ~/.orkastery/segredos/<nome>, and the manifest cannot choose a file outside that folder. The two sources are exclusive, so ork never falls back from one to the other. Before opening, it checks with lstat every folder between the home and the secrets folder, opens with O_NOFOLLOW and requires a regular file of the user running ork, with exact 0600 or 0400 permissions, up to 4 KiB and a single line with the DSN.
A child process response that repeats the DSN or its password is refused whole, with memory.transport.secret, brain.transport.secret or brain.migration.secret, without the value. The limit is stated honestly: the agent runs as the owner’s user and can read a 0600 file of theirs. The gain is the password out of env, the transcript and the model context; strong isolation needs another user or an intermediary.
ork privado varrer
ork privado varrer --base origin/main
ork memory statusWhat remains with the owner
The audit left six items pending with the owner, because closing them changed accepted or documented behavior. The first five, P1 to P5, got the provenance rules on this page, merged by the owner’s decision. P6 remains pending.
On the same list, these remain recorded, with low risk:
ork retry run --dry-run, in the corrigir-dirigido action, re-runs claims and verify: they are declared commands, but this goes against the meaning of--dry-run.- The runtime profile recorded in the ledger chooses the
CLAUDE_CONFIG_DIRand theCODEX_HOMEof query commands. - P6: the manifest’s
memory.clican be any name onPATHor an absolute path, including inside the clone, andmemory.database_url_envnames any environment variable. The value reaches the Brain executable on every query, and the file sourcememory.database_url_fileonly accepts ork’s secrets folder, so the class does not widen. ci.external_repositoriesaccepts a parent-directory segment in the path of a read through the GitHub API.ork adapter installstill finds the catalog from the project, asork evalused to, but only copies the adapter into the project itself and prefers the executable onPATHwhen there is one.
For core contributors
Rules for code in core/src:
- A value from the clone on its way to git: validate it before the call with
remotoValidoorexigirRemoto,branchValidaorshaValido(core/src/branch-de-estado.ts), and put--end-of-optionsbefore it. - A branch ref goes fully qualified, and a merge goes by the checked sha, never by name.
- An executable never comes from the manifest through a relative path, and the cwd of an executable chosen by configuration is not the clone root.
- A path with an id read from a file has a single segment, checked by regex, and the state directory is not a link.
- Appends to state use
O_NOFOLLOW; a whole-file write goes through a temporary file created with wx and then renamed. - A path read from a pointer stored in state is checked by its real path with
exigirCaminhoContido(core/src/procedencia.ts). A decision the manifest cannot take alone becomes a local confirmation in.orkastery/private, withlerArquivoPrivadoandgravarArquivoPrivado(core/src/postura-local.ts). - The fix’s test fails the previous code; the reference tests are
core/test/fronteira-de-confianca.test.ts,core/test/procedencia-e-postura.test.tsandcore/test/fronteira-pendentes.test.ts.