Docs/Walkthroughs

Walkthroughs

Walkthrough: inspect runtime status

What is installed, and what would an install or an emergency re-enable hit? Two read-only answers: the sessions the runtime is supervising right now, and the integrity of every installed release tree — the second integrity gate an install passes through. The integrity commands run tama hooks integrity against a scratch home holding a copy of a sealed release, so nothing operator-owned is touched. Outputs are pasted verbatim with scratch directories abbreviated to $H. The desktop shows the same facts on Posture and Session.

What is installed, and what would an install or an emergency re-enable hit? Two read-only answers: the sessions the runtime is supervising right now, and the integrity of every installed release tree — the second integrity gate an install passes through. The integrity commands run tama hooks integrity against a scratch home holding a copy of a sealed release, so nothing operator-owned is touched. Outputs are pasted verbatim with scratch directories abbreviated to $H. The desktop shows the same facts on Posture and Session.

#1. Live sessions, from the sealed CLI

tama sessions reads the session-control records under <home>/Library/Application Support/Tama/session-control/ — the same files the desktop polls (enforcement-control). Against a home with no records it prints nothing and exits 0; --json makes the empty answer explicit:

$ tama sessions --home "$H"
$ tama sessions --json --home "$H"
[]

Against the real home of a machine with live supervised sessions, each line is agent id, session id, and hook state — loaded/registered counts for a normally enforcing session, or the explicit allowlist during a global disable (excerpt of a longer capture):

$ tama sessions
omp	ReadBatch13	61/61
omp	ReadBatch05	61/61
kimi	session_d62b	?/?
omp	DeepJeden	allowlist: empty

Read 61/61 as "61 hooks loaded of 61 registered" — the equality Posture and setup require. allowlist: empty is a session running while hooks are globally disabled: its enabledHookIds allowlist is the only thing that would run, and it is empty (concepts/session-enable). ?/? is a session whose runtime has not reported hook counts.

#2. Every installed release, verified against its own name

Installed releases are content-addressed: the directory name is the claimed digest, so verification needs no manifest (hook-releases). On a home where Tama has never installed anything:

$ tama hooks integrity --home "$H"
nothing installed under $H/Library/Application Support/Tama/hooks-runtime
$ echo $?
0

Simulate an installed runtime by copying a sealed release to its content-addressed landing path and pointing current at it — exactly the layout tama hooks install-release produces:

$ tama hooks integrity --home "$H"
intact  $H/Library/Application Support/Tama/hooks-runtime/releases/f7c3422135ac4ea7006c26d25a93d3de6101b61bb05318d22ed9a0cbe761bd15  <- current
$ echo $?
0

Every tree under releases/ is digested against its directory name, and the current one is marked. The installer's second integrity gate checks exactly this tree, so an intact line is the gate's own verdict.

#3. The state an install would refuse

Change one permission bit inside the installed copy and re-read:

$ chmod 700 "$H/Library/Application Support/Tama/hooks-runtime/releases/f7c342…/shared-hooks/registry.json"
$ tama hooks integrity --home "$H"
DRIFTED  $H/Library/Application Support/Tama/hooks-runtime/releases/f7c3422135ac4ea7006c26d25a93d3de6101b61bb05318d22ed9a0cbe761bd15  <- current
$ echo $?
1

This is the state behind Installed Tama hook release failed its integrity check — the second of the two identically worded installer failures (runbook). The installer's own recovery is automatic for the common case: a pre-existing copy that no longer digests to its directory name is deleted and recopied from the release before the gate is re-checked (hook-releases).

#4. The identities the desktop compares

installed.json beside releases/ records what the last successful install wrote — release id, catalog checksum, versions, managed files, pinned Node — and each live session record carries the release id and checksum its runtime actually loaded. Posture calls the machine healthy only when bundled, installed, and loaded identities agree; this walkthrough is the command-line version of that comparison, one identity at a time.