<!-- source: https://docs.dreamlake.ai/dev/notes/remote-session-permissions @ 0.1.192 b2f973b1 -->
# Remote session permission inspection and cancellation

## Released — 15 November 2026

The built-in agent's session list and detail tools now retain the permission
information already returned by the session API. The agent can also request
cancellation of a specific command through the existing caller-authorized route.
This is a bounded part of [master #247](https://github.com/dreamlake-ai/dreamlake-workspace/issues/247).
Source: [PR #1943](https://github.com/dreamlake-ai/dreamlake-workspace/pull/1943),
deployed as `a557f2cc702d8c3b2b4def1b9c1a5571bf6056a8`.
[Full main CI](https://github.com/dreamlake-ai/dreamlake-workspace/actions/runs/43709645131)
and the [EKS rollout](https://github.com/dreamlake-ai/dreamlake-workspace/actions/runs/43710951750)
passed. Live tool discovery, permission projection against the canonical API,
and one already-completed command cancellation passed with durable tool receipts.
The terminal command kept its completion status and finish time. This bounded
check does not establish interruption of a running process.

## Inspect permissions before acting

### Runtime permission GUI

The runtime permission GUI shipped on 16 November 2026 in
[UI PR #2053](https://github.com/dreamlake-ai/dreamlake-ai/pull/2053),
revision `ae8a83df40f3481477cce4bf80441cd38102ff2e`. The published production
panel passed read-only desktop/mobile acceptance against the canonical session
API. Save and refusal cases were verified with API fixtures.
In Sessions, open the shield labelled **Runtime permissions** beside the session's
existing actions. Opening it reads metadata only; it does not connect a terminal,
start an agent, or change a grant. Claude sessions also expose the shield beside
the Conversation and Terminal tabs.

The panel shows the exact session and machine, **Recorded policy**, and **Last
runtime report**. Missing owner policy remains **Not reported**; shared viewers
see **Owner only**, rather than being told the runner has failed to report. Matching
levels mean only that the last report matches; the report has no independent
freshness or process-generation attestation. A differing report remains visible
after a policy save.

Owners with a reported policy can choose Read only, Workspace write, or Full
access, then review and confirm the change. An increase has a separate **Confirm
increase** action. The server checks personal ownership, the runner's permission
ceiling, any parent-session ceiling, and its authority revision fences. The UI
rechecks metadata before saving to reject a review made against an old revision
or a changed runner, machine, account or working directory;
the existing PATCH endpoint does not accept a client-supplied revision condition.
A lost or invalid acknowledgement remains **Save outcome unknown**, disables
another save, and requires a fresh read. No automatic write retry occurs.

Saving changes the recorded policy only. It does not stop or restart a process,
including when the policy is lowered. **Apply on the original machine** provides
the exact session's existing CLI restart command. A restart can interrupt work;
inspect its final receipt and then refresh the permission panel. A policy label
is not proof of OS isolation.

### Host setup and recovery

In Compute's selected-machine details, **Execution setup** beside the capability
checks walks through three separate requirements: access to the exact enrollment,
local Nymph execution consent, and the session runner/provider login. It links to
host details and the local-policy guide. It does not infer local consent from a
heartbeat or advertised SSH capability, and it does not change local config.

The report requires Nymph 0.1.43 or later and a compatible deployed control plane and API. Publishing a daemon release does not upgrade an already-running enrollment by itself.

The **Daemon startup policy** report is a separate, owner-only read for the
selected enrollment. Supporting daemons report the upload and command-execution
settings already loaded in memory. The control plane records receipt time and the
authenticated signing key; the API requires that key to remain active and match
the exact enrollment. Reports expire after 60 seconds. Refresh reads another
observation; it does not run a probe or reload configuration.

**Managed local policy** means a local consent file supplied the startup settings.
**Legacy defaults** means no managed consent file was loaded; it is not evidence
of explicit consent. Missing reports, including older daemon/control-plane
versions, remain unknown. Stale reports, inactive daemons, unverified identities
and unavailable checks are shown separately. Enabled upload policy does not
enable every upload channel, and neither setting grants server access or attests
runtime isolation. Files changed after startup are not detected by this report.

The read-only endpoint is
`GET /namespaces/:namespace/hosts/:hostId/enrollments/:enrollmentId/local-policy`.
Its `status` is `reported` or `unknown`; `policy` is null unless a fresh verified
report is available. A reported policy contains `managed`, `upload` and
`commandExecution`, with `observedAt`, `ageSeconds` and `checkedAt` outside the
policy. It does not expose local paths or credentials. Host ownership and
enrollment authority are rechecked after the upstream read. Older servers may
not expose this endpoint; that does not establish a local-policy denial.

On the selected machine, the owner can inspect the daemon's real startup policy:

```sh
nymph access --config /absolute/path/to/udf-daemon.toml
```

Replace the path with the selected enrollment's actual configuration. This reads
startup configuration; it does not attest to an already-running daemon. Upload
and command-execution consent are separate, and changes require that enrollment
to restart. For agent execution, inspect the session runner in the owner's
personal namespace with `dl sessions runners --json`; sign in to the provider on
the original machine. Do not substitute another host when a binding is missing.

Capability checks distinguish check-access denial, an unavailable check, and
unknown or stale observations. Stale host metadata does not mean SSH is
unconfigured. A public session with unreported terminal authority stays closed
and offers a recheck rather than reporting a confirmed denial.

### Built-in tool projection

`dreamlake_sessions_list` and `dreamlake_session_get` include a `permissions`
object:

| Field | Meaning |
| --- | --- |
| `recordedLevel` | Recorded `read-only`, `workspace-write` or `full-access` policy, or `null`. |
| `observedLevel` | Last runtime permission level reported by the runner, or `null`. |
| `revision` | Recorded policy revision, or `null` when unavailable. |
| `changedAt` | Time the recorded policy changed, or `null`. This is not an observation timestamp. |
| `comparison` | `matches`, `differs` or `unknown`; unknown means either level is missing, invalid or hidden. |

The API hides owner policy from other session viewers. The tools preserve that
boundary and do not infer permission from visibility, a host binding or the
ability to read a transcript. They omit permission-history bodies.

A recorded permission change takes effect in the runtime on resume or restart.
A difference between recorded and observed levels should prompt inspection of
the exact session and its receipts. Matching values do not prove that a process
is currently running, that the observation is fresh, or that local Nymph policy,
host access and provider authentication allow execution. These tools do not
change grants, consent or runtime permissions.

## Cancel an exact command

`dreamlake_command_cancel({commandId})` requires the existing `sessions:control`
turn scope and calls `POST /namespaces/:namespace/session-commands/:id/cancel`
as the signed-in caller. The namespace comes from the current agent context;
there is no tool argument for broadening it. The API requires an active personal
owner and checks the command belongs to that principal.

Cancellation is available in foreground agent turns. It is excluded from the
durable background tool set and work-credential route allowlist; this change does
not extend background authority. Assistant delegations remain read-only.

- Pending commands can become `cancelled` before a runner claims them.
- Running commands receive a cancellation request. A `running` receipt with
  `cancelRequested: true` is not proof that a process has stopped.
- Already terminal commands retain their result. Cancellation does not undo
  effects, delete sessions or revoke grants.
- A race in which pending work starts may return `409 session_command_running`.
  Inspect the command before deciding whether another cancellation is needed.
- Lost responses, server failures and malformed or mismatched acknowledgements
  produce an uncertain tool receipt retaining the original command ID. Use
  `dreamlake_command_get` to inspect it; the tool does not automatically retry.

The existing API and registry remain the authority and audit boundaries. No new
grant path or background runtime is introduced. The GUI above exposes the existing
policy path and setup instructions; live Nymph configuration, durable contextual
approvals, and stronger runtime permission guarantees remain separate work.

## Validation

The focused tests cover permission mismatch, unknown/shared policy projection,
turn-scope refusal before API access, invalid and cross-namespace tool arguments,
pending/running/terminal receipts, denied and racing requests, lost responses,
mismatched receipts, and personal-owner enforcement at the HTTP route.
The generated tool inventory must match the registered catalog. Record actual
test, CI and release results in the linked implementation PR.
