Docs
Grants and sessions
A grant is a time-boxed permission set bound to one unit of work. A session is the workspace that grant opens. When the grant ends, the session ends with it.
A grant
| Element | Content |
|---|---|
| Purpose | One sentence: the ticket, the pull request, the agent's plan |
| Scope | The file set, resolved from a profile plus the task's declared output paths |
| Time box | A time to live. Expiry revokes everything. No standing grant to clean up |
| Risk at declaration | Counted, not guessed: this task's scope touches N Occluded paths and M Absent paths. Any Absent path holds the grant for approval |
| Revocation | Automatic at the end or at expiry; manual from the console, which closes a live session |
A session's scope is the per-path minimum of three things: the profile, the grant, and the granting admin's own access. Nobody grants what they do not hold.
Lifecycle
| State | Meaning | Next |
|---|---|---|
declared | Purpose, scope and time box submitted | held if any Absent path is in scope, otherwise approved by policy |
held | Waiting on the named approver, shown to the requester | approved or refused |
approved | The manifest is signed | active when a workspace accepts it |
active | The workspace is running; doors may attach | expired, revoked or ended |
amending | A live session reached an Absent path, or the admin widened the scope | Approval signs a new manifest and the workspace reloads; refusal leaves the session as it was |
expired, revoked, ended | The workspace is destroyed; the visible changes are kept for the export | Final |
A grant is revoked from the console, by a change to the repository's policy, or by your SSO provider: when someone is deprovisioned, every grant they hold ends, including the sessions of agents running under their grants.
The Absent hold, and reload
When a live session reaches for an Absent path, the process gets ENOENT, because the path was never mounted. The request is surfaced inline on the door it came from, an agent run pauses, and the named approver is asked.
If they approve, the grant is amended, a new manifest is signed, and the workspace applies it in place: the person's processes keep running, build jobs restart, and the newly permitted path is mounted. If they refuse, nothing changes. Both outcomes are on the record.
From declaration to close
- A grant is declared: by an admin, from a contractor's ticket, or from an agent's plan. Risk is counted.
- If it is held, the named approver answers.
- Occlude resolves the profile, the grant and the grantor's access into a manifest, and signs it.
- A workspace starts and verifies the signature.
- The workspace mounts the real tree minus Absent paths, prepares stubs, and opens the person's side.
- A door attaches. It is authenticated against the grant; a door never holds the workspace's own credentials.
- Every decision is buffered and flushed to the record.
- At the time limit, on revocation, or when the last door has detached and an idle timeout passes, the person's processes stop, then the build's jobs, then the workspace is destroyed. The export is ready.
What fails closed
| What fails | What happens |
|---|---|
| The manifest is invalid, expired or unsigned | No person's side is ever created |
| A secret the build needs is missing | The job that needs it fails with a named error; nothing falls back to a file |
| The Occlude service is unreachable mid-session | The session runs until its time limit and the record buffers; a full buffer pauses the person's side |
| The file view fails | The person's processes are stopped before the mount can be reused, and the session ends as faulted |
| The time limit | Enforced by the workspace's own clock. Revocation from the service is a second path, not the only one |