Runbook

Something refused — which sentence are you holding, what does it mean, and what do you check next? Every heading below is an exact string from this repository's sources or a state you can reproduce; each entry says where the sentence comes from, what it is really telling you, and the first read-only command to run. Attribution tooling is in scripts; the executed evidence for the integrity entries is in the two walkthroughs.

#Bundled Tama hook release failed its integrity check

Raised by tama hooks install-release before any write, whenever the release tree no longer digests to its recorded releaseId (concepts/seal). You meet it during a runtime install, an emergency disable (which installs session controllers), or a re-enable. The message names no file on purpose — it is a gate, not a report.

First command:

tama hooks integrity --release <release-root>

It prints the sealed and actual digests and every file written after the seal (the suspects). A mismatch with no newer file is a permission change or a deletion — the digest covers mode bits (walkthrough-verify-release). Never repair a release tree in place: reinstall the same verified app artifact (operations).

#Installed Tama hook release failed its integrity check

The second, identically worded gate: after the content-addressed copy to hooks-runtime/releases/<id>, that tree must digest to <id>. The installer already deleted and recopied a stale pre-existing tree before checking, so meeting this sentence means the fresh copy failed — a filesystem-level problem (full disk, interference mid-copy), not stale state.

First command:

tama hooks integrity --home "$HOME"

It digests every installed tree against its directory name and marks current; a DRIFTED line is the tree an install or an enable would refuse.

#Installed and loaded releases disagree

Not an error string — a Posture reading: Installed release and Loaded release differ, or the Session screen warns The runtime is serving a stale registry. A live session keeps executing the release it loaded at start; installing a new one does not restart anybody (concepts/posture).

First command:

tama sessions

A lagging session shows a loaded count against a different registered count, or an old release id in --json. The repair is the session-scoped Enable all hooks, which binds an override to the installed release and checksum and schedules one runtime reload after the active turn settles (concepts/session-enable). The Session screen shows the pending state until the transition completes; rejection or session exit (The agent session ended before the session-control request completed.) is a reported failure, never assumed success.

#Tama found only legacy v1 session records. Reinstall the verified bundled runtime, then stop or resume the affected agent session to publish v2 state.

From SessionControlClient when discovery finds no live v2 record but a v1 record exists. v1 records cannot satisfy the v2 agentId contract and are deliberately not migrated (operations). Do what the sentence says, in that order — the reinstall updates the supervisor, the stop/resume republishes state.

#Unknown hook id '<id>'; the installed registry declares <N> hook ids, and the enforcement selection was not changed.

From tama enforcement only. The requested id is absent from the installed registry's unique agent-hook and Git-hook ids, so Tama refused the entire selection before writing state. The existing machine selection still applies.

First command:

tama list --json

Use the registry's exact ids, then retry the complete intended selection.

#Tama could not read the machine enforcement selection: <core error>. Falling back to all hooks.

From tama enforcement status. The state file was readable neither as a valid ai.wisent.tama.hook-enforcement.v1 document nor as its required shape. Dispatchers choose the safe all-hooks fallback; the status command reports that effective state and exits 1 rather than hiding the damaged record.

First command:

tama enforcement status --json

Inspect readError before replacing the operator-owned file through tama enforcement all or a corrected only command.

#enforcement: <OS/core error>

From a failed tama enforcement only or tama enforcement all write. The registry or atomic state transition failed, and no success is claimed.

First command:

tama enforcement status --json

Read the effective retained selection before retrying the operator mutation.

#At least one hook must remain selected. Choose Select all hooks, or add another hook first.

From the Hooks inspector when the selected row is the sole member of only mode. An empty only selection is invalid; the desktop leaves the machine state unchanged and offers the two valid directions named in the sentence.

First command:

tama enforcement status --json

Confirm the one selected id, then select all or add another id before removing it.

#Emergency-bypass evidence

The emergency switch has three observable evidence configurations under ~/Library/Application Support/Tama, separate from retained hook-enforcement.json:

The script's own sentences: a repeat disable prints Tama hooks are already disabled.; enable without evidence refuses with Tama has no emergency backup manifest to restore.; success prints Disabled hooks. Supervised agent sessions will resume without an editor restart. or Enabled approved hook release <first-12>. Supervised agent sessions will resume without an editor restart. The desktop trusts only re-read durable state: Tama could not persist the emergency hook state. means the switch did not stick. During the bypass, the retained machine selection does not run; tama sessions prints each session's explicit allowlist (allowlist: empty when nothing was re-enabled) (walkthrough-runtime-status).

#The installer refuses

Without --release or --home the command prints its usage line and exits 2, the status of every Tama usage error, before anything is read. Each sentence from tama hooks install-release, surfaced verbatim behind Tama hook release installation failed: <reason> (exit 1):

One refusal comes from the other side, before an install writes anything: Tama hooks are disabled and <path>.tama-disabled is the entrypoint the bypass is holding. Installing <name> here would leave both files in place, which a re-enable refuses. Re-enable policy first, then install. That is tama install declining to recreate a global Git dispatcher while a bypass holds it aside — leaving both files in place is a state a machine cannot be restored from. Re-enable, then install.

Every failure rolls the transaction back: originals restored, current re-pointed, the OMP extensions change reverted (hook-releases).

#The emergency switch refuses

From the desktop wrapper (HookEmergencySwitch), each verbatim:

• The Tama bundle does not contain the emergency hook controller. — the bundled script is missing; the app bundle is incomplete, reinstall the verified artifact.
• The Tama bundle does not contain the agent session-controller installer. / The Tama bundle does not contain an approved hook release for agent session control. — same class, for the installer and release.
• The local policy command exceeded its bounded runtime and was terminated. Inspect local policy state before retrying. — the 300 s bound fired; the process tree got SIGTERM then SIGKILL. Check the global-disable state table above before retrying.
• The local policy command exceeded Tama's bounded output limit. Inspect local policy state before retrying. — more than 64 KiB of output; same inspection.
• Tama could not read bounded local policy output: <reason> — the output pipe failed; the command's own result is unknown, inspect state.
• Tama could not update the installed hook configuration. — the script exited non-zero without printing anything.

From the script itself: Unsupported Tama emergency action: <value> (exit 2), Tama session supervisor is missing: <path> (exit 66), Tama could not resume one or more supervised agent sessions. (the exit trap's resume failed — sessions may still be paused; resume them via the supervisor).

#The backend refuses a repository

The Violations surface validates before anything runs, each sentence from ViolationsClient:

• Enter a repository path first.
• Choose an existing absolute Git repository directory: <path> — not absolute, not a directory, or no .git.
• Tama refuses to mutate a repository not owned by the current user: <path> — UID mismatch; scanning and cleanup are owner-only.
• A repair round asks Brama for a patch and applies it through Git. A Brama refusal or a patch-application failure is reported with its cause; installing Codex is not a prerequisite.
• The clean command was cancelled. Partial working-tree edits remain visible; inspect them and complete a read-only scan before retrying.

Refusals from tama request arrive verbatim in {"error": "…"} envelopes on its one response event: an unknown operation is status 404 with unknown operation: <operation>, and a scan of a path that does not exist is status 400 with repo not found: <path> (tama request). A request process that cannot start reports The Tama backend did not start. (with the launch error when there is one); one that ends without answering reports The Tama backend ended with status <status> before it answered. followed by its stderr; a build without the sealed binary reports The Tama backend is missing from this build at <path>. Rebuild with Scripts/build-app.sh.

#The privileged backend is not Enabled

Statuses are macOS's answers, mapped verbatim by SystemPolicyServiceManager: Requires administrator approval, Network filter requires approval, Not registered, Partial setup: daemon enabled; System Extension not installed, Partial setup: <daemon-status>; network policy remains configured, System Extension status unavailable: <error>, and Restart required to finish System Extension activation. Approval-pending is never treated as success. The repair is in Settings: Register privileged backend, then the macOS Approval settings and Full Disk Access shortcuts (desktop/settings). Deactivation failures aggregate as Tama could not fully deactivate local policy components: <message> — each component is attempted independently, so fix the named one and deactivate again.

#The generated launcher refuses (exit 66)

~/.local/bin/tama-agent fails closed before starting a session: Tama Node.js runtime preflight is missing: <path>, Tama requires its validated Node.js executable: <path>, Tama session supervisor is missing: <path>, or Tama requires Python 3 for the universal session runtime. The first two mean the installed runtime under hooks-runtime/current moved or a pinned Node was removed — reinstall the runtime rather than editing the launcher; the pinning contract is in hook-releases.

The refusals about copying a repository — git worktree add, a local git clone, a recursive copy of a checkout, and tama worktrees remove — are in Runbook: repository copies.