Reference

Tama operational model

No log, cache, or UI snapshot is authoritative policy state. Hook catalog checksum and release ID are the evidence used to compare the signed bundle, installed release, and live runtime.

#Ownership and trust boundaries

Resource	Authority	Writer	Retention and removal
Signed `Tama.app`	Published release artifact	Release operator	Replace only through an explicit upgrade; remove with the app
Bundled catalog	Signed app bundle	Release build	Immutable for the life of that app version
Installed hook release	`~/Library/Application Support/Tama/hooks-runtime/releases/<release-id>`	Tama installer	Retained while referenced by `current` or `installed.json`; remove during uninstall
Current hook release	`hooks-runtime/current` symlink	Tama installer transaction	Atomically replaced; previous ID recorded in `installed.json`
Emergency state	`hook-emergency-state.json` and `emergency-backup/`	Emergency controller	Removed only after successful re-enable or explicit uninstall
Session records	`session-control/*.session.json`	Agent supervisor	Stale records are ignored and removed; directory mode `0700`
Session overrides	`session-control/*.override.json`	Agent supervisor after a validated Tama request	Atomic files, mode `0600`; removed during reset/uninstall
Session-control requests	`session-control/*.request.json` and matching response	Tama and agent supervisor	Private, single-use exchange; both sides remove completed or abandoned files
Wisent session	macOS Keychain	Wisent Auth	Removed by sign-out or Keychain administration
Privileged daemon and filter preferences	macOS ServiceManagement and NetworkExtension	Explicit setup action	Removed by the uninstall procedure

No log, cache, or UI snapshot is authoritative policy state. Hook catalog checksum and release ID are the evidence used to compare the signed bundle, installed release, and live runtime.

#Configuration

Tama has no required environment variables for a supported binary installation. Maintainer-only overrides are:

Variable	Purpose	Safety rule
`TAMA_HOOK_ROOT`	Select the hook source during a maintainer build (`../tama` beside this checkout otherwise)	The path is not retained; runtime source override is compiled out of distributed builds
`TAMA_INSTALL_APP_PATH`	Select developer installation destination	Must not be used by the release workflow
`TAMA_NODE`	Select the Node.js the maintainer build exports the catalog with (the first `node` on `PATH` otherwise)	The build refuses a Node.js older than 20, and a path that is not an executable
`TAMA_CARGO`	Select the `cargo` the maintainer build compiles the bundled Tama backend with (the first on `PATH` otherwise)	The build refuses a path that is not an executable
`WISENT_CODESIGN_IDENTITY`	Select signing identity	Release credentials stay separate from runtime identity
`WISENT_APP_PROVISIONING_PROFILE`	App provisioning profile	Release operator only
`WISENT_NETWORK_FILTER_PROVISIONING_PROFILE`	Network Extension profile	Release operator only
`AC_API_KEY_ID`, `AC_API_ISSUER_ID`, `AC_API_KEY_P8`	The App Store Connect API key, kept in Skarbiec, that `stado product signing notarize` submits the signed app with	Required for every published preview or stable release; never available at runtime
`TAMA_TEST_IDENTITY`	Automated UI-test identity seam	Prohibited in distributed artifacts and ordinary use

Unknown UI configuration is rejected by construction: setup choices are explicit actions rather than free-form settings. Integration-specific configuration is documented in integrations.md.

#Permissions

Ordinary catalog inspection requires only read access to the app bundle and the user's Application Support directory.
Installing the per-user runtime writes to ~/.shared-hooks, ~/.claude/hooks, ~/.codex/hooks, ~/.local/bin, Git hook locations recorded by the catalog, and ~/Library/Application Support/Tama.
Registering the policy backend requests macOS approval for a privileged daemon, System Extension, Network Extension configuration, and Full Disk Access where required.
Repository scan is read-only. Cleanup requires write access to the selected working tree and launches the explicitly selected local agent.
Tama never requires an administrator credential for catalog inspection or per-user session override files.

#Observability

The Posture and Session screens expose:

desktop product version and source revision;
bundled and installed hook release IDs, plus the validated Node version and executable recorded by the installed runtime;
catalog checksum and registered/loaded hook counts;
daemon and kernel-policy readiness;
active agent identity, session ID, project path, and liveness mode;
semantic event sequence and the register of recent decisions, including the reason string of the last blocking decision;
unknown hooks, reload requirement or scheduled reload, and backend diagnostics;
the capability a session holds: lifetime, expiry, remaining uses, and every tool grant;
violation scan totals, skipped files, and per-file errors on Violations;
registry-declared provider coverage on Coverage, and scope target paths on Install plan.

Diagnostics must identify remediation without including access tokens, raw external payloads, or repository file contents beyond paths and rule messages.

#Failure and recovery

Catalog unavailable: the signed bundle is incomplete. Reinstall the same immutable app artifact and verify its digest.
Runtime integrity failure: installation stops before changing the active symlink. Reinstall from the signed app; do not edit files inside a release directory.
Partial runtime installation: the transaction restores original files and previous current symlink.
Backend approval pending: open the displayed macOS settings destination, approve the component, then refresh status.
Agent session unavailable: the operation does not write an override. Restart the supervised session and select its new session record.
Emergency disable partially fails: sessions are resumed by the exit trap; preserve emergency-backup and retry re-enable from the same app version.
Violation dependency unavailable: scanning or cleanup fails independently; catalog inspection and session control remain available.

Never repair installed.json, current, or emergency manifests manually as a normal recovery procedure.

#Backup and restore

Before an upgrade that changes stored-state schemas, back up ~/Library/Application Support/Tama. Version 0.2.0 preserves prior hook-release identity and reads existing v2 session state. It deliberately ignores legacy v1 session records and overrides because their provider identity cannot satisfy the v2 agentId contract; reinstall the verified bundled runtime, then stop or resume affected sessions to republish v2 state.

To restore after a failed compatible upgrade:

Quit Tama and stop supervised sessions.
Restore the Application Support backup.
Restore the exact prior signed Tama.app artifact and verify its digest.
Open Tama, confirm the product and hook release IDs, then resume agent sessions.

Do not run two Tama versions against the same Application Support directory concurrently.

#Reset and uninstall

A reset removes Tama-owned welcome or stopped-session override state without unregistering privileged components or deleting unrelated agent configuration. Deactivate local setup disables managed dispatchers and unregisters the daemon and Network Extension while deliberately preserving restoration evidence. Full removal then signs out, removes the app, confirms no Tama process or dispatcher remains active, and archives or removes dormant files named by the installed manifest.

Use the versioned procedure in onboarding.md; do not delete managed hook files blindly because existing non-Tama settings and dispatchers may need restoration.

Public CLI operations are demonstrated as runnable, commented shell scripts in ../examples/; mutation examples require explicit environment inputs before they act.