tama stage

Stage a session's recorded text edits without taking other changes merely because they share a file. Tama reads completed tool receipts, reconstructs their deltas and lets Git merge those deltas into a private index. It publishes that index atomically only when every selected transition succeeds. It does not edit working files, create a commit, compile source or install a product.

#Invocation

tama stage --session <session> [--repo <checkout>] [--json] [--inspect]

--session names a retained session, not a caller-supplied patch. --repo selects the checkout; without it the current directory selects the repository. --inspect computes the same candidate without publishing it. Inspection may write Git objects and ignored scratch files, but leaves the actual index unchanged. --json returns the structured result.

#Example: shared file, separate changes

tama stage --session <your-session> --inspect
 tama stage --session <your-session>
 git commit -m 'Preserve the recorded operation cause'

Run these as separate commands. The commit guard checks the resulting index, not a future index that an earlier command on the same shell line might produce. Whole-path commits, --all, --include and pathspec-file commits refuse because they can import working-tree hunks after that inspection. Existing unrelated staged entries are preserved by staging; they must not be included in your commit. The guard refuses an entry or hunk not established by your receipts even when you edited another part of the same file.

Git's commit-msg hook (tama hook review-commit) reads the same ownership from the index Git is about to commit, however the commit was spelled: git commit -a, an alias, sh -c "git commit …" or a script. The committing session is the one whose recorded agent process (pid in its session record under the session-control root) is an ancestor of the hook, each parent read from the kernel for that one process (proc_pidinfo with PROC_PIDTBSDINFO on macOS, /proc/<pid>/stat on Linux), so a sandbox that refuses to start ps changes nothing. A process the kernel no longer has ends the walk; any other failure refuses the commit naming the kernel's answer and ending the process tree this command runs in cannot be read, since ending the walk there would read an agent's commit as the operator's. When such a session commits, every staged entry must be established by its receipts exactly as staging would produce it; otherwise the commit is refused before history changes with review-commit: commit refused before history changed: the staged index is not only <agent> session <session>'s recorded edits: <cause>, or, when the session's transcript cannot be found, this commit runs in <agent> session <session>, whose transcript cannot be found, so its staged index cannot be read against the session's recorded edits. An index, a Git command or receipts that cannot be read are not reported as another session's change: the commit is refused with whether the staged index is only <agent> session <session>'s recorded edits cannot be read: <cause>, and the shell-line guard with BLOCKED: whether `<command>` commits only this session's recorded edits cannot be read: <cause>.

A commit no recorded session's process tree holds is read by what it carries. That is the operator's own commit, or one an agent started outside its own process tree (detached with nohup, setsid or a double fork, or handed to another daemon). Every session whose recorded agent process the kernel still has is asked whether some staged path holds exactly what its recorded edits make of that file. A commit carrying no running session's edit is the operator's and is not read for ownership. A commit that carries one is read against that session as if it had started it, and passes when the whole index is that session's edits; otherwise it is refused with this commit was started outside any agent session's process tree but carries running sessions' recorded edits, and is no one session's alone: <each session's finding>. A detached commit that stages only another session's recorded edits therefore reads as that session's commit. A commit made with --no-verify or with plumbing (git commit-tree) runs no hook and is read only by the shell-line guard.

#Evidence and supported transitions

A session's receipts are read from the transcript its recorded agent process holds open for writing now, as /usr/sbin/lsof (/usr/bin/lsof off macOS), run by its path, lists that process's open files: a .jsonl file under a harness's live root, opened for writing. OMP moves a session to a new transcript, named after a new id, whose session record names the transcript it moved from as parentSession and the session's first id as providerPromptCacheKey, with every earlier record copied in, while the session's process keeps the first id; the moved transcript then holds every edit of the session, before and after the move, and an edit made after the move is staged and read by the commit hook as the session's own. When no running process of the session holds a transcript, as once its process has ended, the newest of its transcripts is read: among the one whose session record is the session's and every one naming the session as its providerPromptCacheKey, the one no other was moved from; a harness that writes no session record has its transcript found by name. Transcripts held by several running processes of one session refuse, naming them, and so do transcripts moved from the same one (a branch), since which holds the session's work cannot be told; a transcript folder or a transcript's leading record that cannot be read refuses, naming it, and an lsof that fails saying why refuses with its words. The transcript's session record must name the requested session as its id or as the providerPromptCacheKey a move keeps. A successful result must match its recorded invocation. Only the result of a tool the hook vocabulary names as changing files (the harness's edit and write tools, a patch, a structural edit, a rename, move or delete) is a receipt: a read of a file or of a directory also reports the resolvedPath it read, and is no edit. Text edits use complete oldText/newText snapshots. A full-file write whose result reports only resolvedPath is read from its own content argument, every byte it left in the file; it observed no before-state, so its base is the session's own earlier state of that path when the session touched it before, and otherwise what the file held in the index being staged (in the commit check, what HEAD held). Its whole content is then the session's change, and the working-tree check below still requires those bytes to be in the file. A write result with neither an op nor a content argument refuses, naming the call. Recorded creation and deletion are distinct from an empty file.

A result may contain one file receipt, or a changes or perFileResults array of file receipts, one per file a call changed. Each member is bound to the same successful tool call and validated before publication; an empty array names no file and refuses nothing. A write with an explicit op and the corresponding snapshots uses the same transition reader. An update receipt that keeps no oldText/newText (the edit tool keeps only its numbered diff for a large file, such as a lockfile) is read by applying that diff to the path's state before it: the bytes the session's latest earlier receipt of the path left, or, for its first edit, what HEAD holds there. Each kept and removed line must read in that state exactly as the diff shows it; otherwise that path alone carries the cause, the numbered diff of <path> does not apply: line <n> reads "…" before the edit, but its diff shows "…", and so does a path whose earlier receipt was refused or deleted it. A receipt missing the text its operation needs refuses its own path only (edit <call> of <path> (<op>) carries no <field>, so its bytes cannot be established). Real journey: tests/shared-checkout/numbered.rs (target shared_checkout_numbered) stages a retained session whose lockfile receipts keep only numbered diffs onto its baseline tree and compares the exact result.

A receipt of a path the repository ignores and does not track, such as a commit message or a note a session wrote under the checkout's ignored build directory, is part of no commit: git check-ignore on the receipts' path names reads which paths those are. Such a path is neither staged nor refuses staging, and the commit hook does not read it either, whatever its receipt holds, so a notes file several sessions append to never refuses a commit of the session's tracked files. A check-ignore that cannot read the paths refuses, naming the command and Git's stderr.

Independent text changes merge; conflicting content or creation/deletion refuses the operation. Every proposed delta must still be present in the working tree. Symlinks, unresolved index entries, non-UTF-8 content and unsupported transitions refuse with the affected file. Text receipts do not authorize mode changes. Existing file modes remain unchanged; new file mode comes from Git's observation of the real file.

A path whose recorded edits cannot be replayed, because one of them overlaps a change another session made between two of this session's edits, keeps that cause (session edits overlap or cannot be reconstructed for <path>: <cause>) until a whole-file write of it gives the path a known state again. Staging refuses with it, since it would stage that path. The commit hook refuses with it only a commit that stages that path; a commit of the session's other paths is read against their receipts as usual.

#Output and diagnostics

{"session":String,"repository":String,"paths":[String],"calls":[String],"tree":String,"applied":Boolean}

paths names the index entries changed by this operation; calls identifies the successful edit receipts used. tree is the candidate Git tree, not a build or verification verdict. Repeating a successful operation reports no remaining unstaged deltas. Staging preserves unrelated index entries, so the candidate tree alone does not assert that the whole index belongs to this session.

An absent transcript, invalid session identity, unmatched result, missing snapshot, stale edit, overlap, index lock, unavailable Git command or filesystem failure exits nonzero and names the failed operation and cause. Git's stdout and stderr are retained in its failure. Failed staging does not publish the private index. A held lock is not removed or retried. Scratch lives under the checkout's ignored .build/tama-stage, isolated by index path. A scratch path that is not ignored or resolves through a symlink refuses. Whether the scratch is ignored is read with git check-ignore on its path name, without the literal pathspec magic the index operations use, because check-ignore refuses that magic; a GIT_LITERAL_PATHSPECS in the caller's environment does not reach it either.

#Desktop and native interface

Open Reviews → Session-owned staging, enter the session and checkout, then choose Inspect changes or Stage session changes. The screen shows paths, receipt calls, candidate tree and the exact refusal. It calls the same implementation through tama request stage, with body {"session":String,"repository":String,"inspect":Boolean}. This is the native request protocol, not a shell invocation of the staging command.

#Real qualification

tests/shared-checkout/commit.rs invokes the actual CLI against real retained session receipts and Git trees, using a separate index inside the canonical checkout. Set TAMA_STAGE_CASE to a retained capture containing repository, session, writeSession, readSession, readTree, ignoredSession, ignoredTree, baselineTree, expectedTree, writtenTree, conflictTree and files. The capture must contain independent changes by different sessions in a shared file, batched file transitions and an overlapping index tree. writeSession identifies an actual session that created a file in this repository with the harness's whole-file write, whose result names only the path; writtenTree is the tree staging it onto baselineTree gives, the file with the bytes the write carried. readSession identifies an actual session that read a directory with the harness's read tool and then edited files here; readTree is the tree staging its edits onto baselineTree gives. ignoredSession identifies an actual session that wrote a file under a path this repository ignores and edited tracked files; ignoredTree is the tree staging it onto baselineTree gives, its tracked edits without the ignored file. No transcript or provider response is manufactured. Missing capture is a failed prerequisite, not a passing test.

The journey checks inspection without mutation, exact session-only staged bytes, repeated staging, a file created by a whole-file write staged with the bytes it wrote, a session's directory read leaving no receipt of its own, a file the repository ignores left out of the staged tree, the overlap refusal, preservation of the operator's index and working files, and retains revision-bound command streams, exit statuses and observed tree identities.

tests/shared-checkout/hook.rs (cargo test --test shared_checkout_commit_hook) reads the same capture: it stages the captured session's hunks into an isolated index with the built tama stage, then runs the built tama hook review-commit over it as Git's hook would, with a session record naming the test process as the session's agent process and an attested message. The session's own hunks are not refused for ownership; the capture's conflicting tree is refused naming the session and the foreign index; the write session's staged file, under a session record naming it, is not refused for ownership either. The operator's index and working files are compared afterwards and the outputs are retained under Cargo's test directory.

tests/shared-checkout/continued.rs (cargo test --test shared_checkout_continued) qualifies a moved session. Set TAMA_STAGE_CONTINUED_CASE to a retained capture of an actual OMP session that was moved and went on editing: repository, session (the id its process keeps), transcript (the moved transcript), baselineTree, expectedTree (every edit the moved transcript records), continuedFile (a path edited only after the move, which the journey checks differs between the two trees) and foreignTree (expectedTree with another session's change). The test records itself as the session's agent process in an isolated session-control root and holds the moved transcript open for appending, as OMP does, writing nothing. The built tama stage must give expectedTree; the built tama hook review-commit does not refuse that index for ownership and refuses foreignTree naming the session. With the transcript let go, as when the session's process has ended, staging must still give expectedTree and the hook must still not refuse it for ownership. The operator's index is compared afterwards and the outputs are retained under Cargo's test directory.