tama sessions

Reports every recorded live agent session and the hook state projected into its session-control record.

#Invocation

tama sessions [--json] [--home <path>]
tama sessions reload --session <ID> [--json]
tama sessions capability show --session <ID> --agent <omp|claude|codex> [--json]
tama sessions capability revoke --session <ID> --agent <omp|claude|codex> [--json]

capability show prints the capability the session's override holds, as the build gate reads it; capability revoke withdraws it at once (see capability). Both require --agent: a session id read under another harness names another control file.

--home selects the home containing both Library/Application Support/Tama/session-control and the machine enforcement state; otherwise Tama uses HOME. --json prints the structured machine status and session array.

#Output and state

Text mode begins machine enforcement mode=<mode> selected=<n>/<N> ids=<all or comma ids> emergency-disabled=<bool>, then one row per record: <agent id> <first 12 session-id characters> <process state> <hook state>, and a closing session records <count> running=<n> gone=<n> no-usable-pid=<n> no-runtime-report=<n>. A record that names no agentId or sessionId is not listed as ?: stderr says a session record names no agentId or sessionId: <record>. A hook count the runtime did not report reads no count, and an allowlist it did not record reads allowlist: not recorded.

The process state is running when the recorded process id still answers kill(pid, 0), gone when it does not, and no usable pid when the record carries no process id a kernel could accept. That last case is its own answer rather than running: an out-of-range identifier cast down to -1 asks about every process the caller may signal, which succeeds and said nothing true.

The hook state is <loaded>/<registered> for a session whose runtime published its counts, allowlist: <ids> while hooks are globally disabled and the session enabled some by name, and no runtime report for a record whose runtime never published any hook state. A session that has not reported is not a session with broken hooks, and the row says which one it is.

JSON is {"machineEnforcement": <status>, "sessions": [...]}; the machine object has the same fields as enforcement status, and each session includes status, working directory, process id, liveness mode, processAlive (null when no usable process id was recorded), runtimeReported, counts, enabled and disabled ids, update time, adapterDigest, adapterReloadSupported and lastReloadError. Missing adapter fields mean the loaded adapter does not report them; a matching policy release does not prove that its JavaScript adapter is current. Listing sessions only reads state.

#Reload an existing OMP adapter

tama sessions reload --session "$SESSION_ID" --json sends a reload-adapter request to that session's control directory and waits for the running process's receipt. It changes neither the session nor its process. It does not enable or disable policies. The directory comes from TAMA_SESSION_CONTROL_ROOT when set, otherwise Tama's platform state directory; --home is a listing option, not a reload option.

A successful receipt carries ok: true, changed, and state.runtime.adapterDigest. The adapter publishes that digest after its replacement has registered and activated. Repeating the command when the same adapter is loaded returns changed: false. The CLI checks that the receipt still names the requested session and process. Concurrent requests through the extension's reload entry share one adoption.

The command refuses a missing session record, a dead process, a mismatched receipt, a failed adapter import or activation, and a loaded entry that does not support remote reload. Older already-open entries are not upgraded by changing files on disk: use their tama_reload_hook_runtime tool or slash command where supported. An entry loaded before the reload shell cannot adopt that shell in place. No refusal is reported as a recovered session.

Tama Desktop exposes the same operation as Session → Reload adapter, alongside the loaded digest and the last reload failure. Adapter siblings already imported by OMP are not reloaded by this operation.

#Real reload journey

tests/enforcement/live-reload.mjs in the Tama repository runs real OMP RPC processes with sealed releases installed into isolated homes under the checkout's ignored build directory. Supply a baseline that supports remote reload, a candidate with a different real adapter revision, and an older release that lacks remote reload:

node tests/enforcement/live-reload.mjs --tama "$TAMA" --omp "$OMP" \
  --baseline "$BASELINE_RELEASE" --candidate "$CANDIDATE_RELEASE" \
  --legacy "$LEGACY_RELEASE" --artifacts "$PWD/.build/live-reload-run"

The journey verifies replacement in the same process and session, the persisted digest, unchanged reload, missing-session refusal, unknown-operation refusal and legacy-entry refusal. Installing the candidate must also rewrite a global Git dispatcher Tama wrote for an earlier release, leave a hook that is not Tama's byte-identical, and connect no hook that was not connected. It retains source revision, release manifests, command exit statuses, RPC recordings and report.json. It does not prove model requests or recovery in the operator's existing terminals; those flows need their own observed results.

#Refusals and failures

For listing, a missing control directory means no session has published itself: an empty result and exit 0. A control directory that exists and cannot be listed is refused with cannot list <directory>: <cause> and exit 1. An invalid individual JSON file is retained as a row whose parseError is the parser's sentence; an unreadable file becomes a row whose readError is the system's cause. These records are surfaced rather than causing a command-wide refusal.

An unknown session command is a usage error, not a successful listing. For reload, a missing session, a dead process, an unsupported loaded entry or a rejected or invalid receipt is an unsuccessful operation. A process that exits after publishing its receipt is not reported as a live reload.

Return to the complete CLI command tree.