@naswerks/periscope 1.0.0

package/docs/configuration.md

@@ -0,0 +1,187 @@
+# Configuration
+
+Everything the host reads at start, where it comes from, and what it prints. The short version: a
+paired host needs nothing set by hand. `periscope pair <code> --controller <origin>` writes the two
+addresses the controller answers with, and `periscope` reads them. Everything below is for a host
+set up by a supervisor's environment, for sessions that need a repository and a worktree each, and
+for the questions a running host answers.
+
+A setting arrives one of three ways, and the order is the rule:
+
+1. **The environment** always wins, per key.
+2. **The config file** (`<config dir>/config.json`) fills absences. `periscope config <key> <value>`
+   writes one key, `periscope config --unset <key>` removes it, `periscope config` lists the file and
+   marks every value the environment is currently overriding. On Windows this is the way to set a
+   value that should outlive the shell. Only the eight keys marked "config-file key" below may live
+   in the file; a value the host would refuse at start (an `https:` controller address, a `ws:`
+   decision address, a relative root) is refused by `periscope config` before it is written.
+3. **The controller, over the link** (`host_configure`) writes six of those keys to the file; see
+   [what a controller can set](#what-a-controller-can-set-over-the-link).
+
+## The two addresses
+
+`PERISCOPE_CONTROLLER_URL` is the WebSocket the host dials (`ws:` or `wss:`).
+`PERISCOPE_DECISION_URL` is the HTTP endpoint it POSTs every permission decision to (`http:` or
+`https:`). Both are required by `serve`; a host with nowhere to send a decision would be an open
+door or a session where nothing runs, so it refuses to start instead. `pair` writes both when the
+controller's answer names them, which every controller built on the reference does.
+
+A controller on a development certificate (a local build serving `https://localhost:…`) is refused by
+Node's certificate check like any other self-signed server: `pair` reports the certificate by its
+code (`DEPTH_ZERO_SELF_SIGNED_CERT`), and `serve` reports it on the link. Export the certificate
+as PEM and point Node at the file with `NODE_EXTRA_CA_CERTS`, set for the user so every new terminal
+carries it. For the ASP.NET Core development certificate:
+
+```powershell
+dotnet dev-certs https --export-path "$env:USERPROFILE\.periscope\aspnet-dev.pem" --format PEM --no-password
+[Environment]::SetEnvironmentVariable('NODE_EXTRA_CA_CERTS', "$env:USERPROFILE\.periscope\aspnet-dev.pem", 'User')
+```
+
+```sh
+dotnet dev-certs https --export-path ~/.periscope/aspnet-dev.pem --format PEM --no-password
+export NODE_EXTRA_CA_CERTS=~/.periscope/aspnet-dev.pem   # in the shell profile
+```
+
+The export writes the private key beside the certificate (`aspnet-dev.key`); delete it, only the
+certificate is read. Then run `pair` and `serve` in a new terminal. Node's `--use-system-ca` does not accept the
+development certificate even when the operating system trusts it. `NODE_TLS_REJECT_UNAUTHORIZED=0`
+also works and trusts every certificate the host meets; prefer the file.
+
+## Where sessions run
+
+Which directory a session runs in is the one choice worth making deliberately:
+
+| Roots set                                                | Where a session runs                                                                                                     |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| neither                                                  | the `cwd` the controller names, verbatim; a `session_new` with `cwd: null` is refused                                    |
+| `PERISCOPE_WORKSPACE_ROOT`                               | a plain directory beneath it, one per workspace key (the session key unless the controller names one)                    |
+| `PERISCOPE_WORKSPACE_ROOT` + `PERISCOPE_REPOSITORY_ROOT` | a linked git worktree of the repository on its own branch (`PERISCOPE_BRANCH_SCHEME`, default `{repo}/{key}`); needs git |
+
+From a terminal on the host:
+
+```sh
+periscope config PERISCOPE_REPOSITORY_ROOT /srv/checkouts/my-repo
+periscope config PERISCOPE_WORKSPACE_ROOT /srv/workspaces
+```
+
+Restart the host; `periscope status` reports `workspace git-worktree` and the branch scheme. A
+controller can set the same two keys over the link (`host_configure`) and the host rebuilds its
+workspace provider live, except while a session is open or opening.
+
+## Environment
+
+| Variable                             | Meaning                                                                                                                                                                                                                                                                      |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PERISCOPE_CONTROLLER_URL`           | Required by `serve`. The WebSocket URL the host dials (`ws:`/`wss:`). Config-file key; settable over the link, in effect at the next start.                                                                                                                                  |
+| `PERISCOPE_DECISION_URL`             | Required by `serve`. The HTTP endpoint the host POSTs each permission escalation to (`http:`/`https:`; settable over the link, in effect at the next start). Its origin is also where `pair` derives the redemption URL when `PERISCOPE_PAIR_URL` is unset. Config-file key. |
+| `PERISCOPE_HOST_ID`                  | The id announced in `link_hello`. Defaults to the machine hostname (an empty value counts as unset); a paired credential's host id overrides it, and the override is logged when the two differ. Config-file key.                                                            |
+| `PERISCOPE_WORKSPACE_ROOT`           | When set, every session gets a directory beneath it instead of the `cwd` the controller named. Config-file key.                                                                                                                                                              |
+| `PERISCOPE_REPOSITORY_ROOT`          | With `PERISCOPE_WORKSPACE_ROOT`, sessions get a linked git worktree of this repository on their own branch instead of a plain directory. Config-file key.                                                                                                                    |
+| `PERISCOPE_BRANCH_SCHEME`            | The branch-name template those worktrees use; placeholders are `{key}` and `{repo}` (the repository directory's name). Default `{repo}/{key}`. Needs both roots. Screened at start-up. Config-file key.                                                                      |
+| `PERISCOPE_WORKSPACE_KEY`            | The workspace key an unkeyed `session_new` provisions at. Needs `PERISCOPE_WORKSPACE_ROOT`. Screened at start-up. Config-file key.                                                                                                                                           |
+| `PERISCOPE_AGENT_HOME`               | The agent's home: the folder the agent CLI keeps its state in. Transcripts are read from `<home>/projects` (derived, reported in the hello, never set on its own). Default: the CLI's own, `<user home>/.claude`. Must be absolute. Config-file key.                         |
+| `PERISCOPE_CONFIG_DIR`               | The directory holding the token cache, the paired credential and the config file. Default `<home>/.periscope`, where home is `USERPROFILE` or `HOME`. The whole directory is in the gate's protected set. Deliberately not a config-file key.                                |
+| `PERISCOPE_PAIR_URL`                 | Where `periscope pair` redeems a code when no `--controller` is given. Default: the origin of `PERISCOPE_DECISION_URL` plus the controller's pair route.                                                                                                                     |
+| `PERISCOPE_MACHINE_LABEL`            | The label sent with a pair request when no `--label` is given, shown in the controller's listings. Default: the hostname.                                                                                                                                                    |
+| `PERISCOPE_IDENTITY_AUTHORITY`       | The OIDC issuer URL; https is required, `localhost` included. With `PERISCOPE_IDENTITY_CLIENT_ID` it enables identity; one without the other refuses start.                                                                                                                  |
+| `PERISCOPE_IDENTITY_CLIENT_ID`       | The public-client id registered with the provider.                                                                                                                                                                                                                           |
+| `PERISCOPE_IDENTITY_SCOPES`          | Space- or comma-separated scopes. Default `openid profile offline_access`. Set to nothing, it refuses start.                                                                                                                                                                 |
+| `PERISCOPE_IDENTITY_AUTHORIZE_URL`   | The authorization endpoint. Set together with `PERISCOPE_IDENTITY_TOKEN_URL` or not at all; when both are unset they are discovered from the authority.                                                                                                                      |
+| `PERISCOPE_IDENTITY_TOKEN_URL`       | The token endpoint. Same rule as above.                                                                                                                                                                                                                                      |
+| `PERISCOPE_IDENTITY_DEVICE_CODE_URL` | The device-authorization endpoint. Read only when the two endpoints above are set; on its own it is ignored.                                                                                                                                                                 |
+| `PERISCOPE_IDENTITY_REDIRECT_PORT`   | The loopback listener's port, an integer 0-65535. Default 0 (an ephemeral port).                                                                                                                                                                                             |
+| `PERISCOPE_IDENTITY_DEVICE_CODE`     | `1` enables the device-code fallback. Off otherwise, and never reached by falling back.                                                                                                                                                                                      |
+| `PERISCOPE_LIVE`                     | Tests only. `1` runs the probes that need a real agent (`npm run test:live`).                                                                                                                                                                                                |
+| `PERISCOPE_PROOF_OUT`                | Examples only. A file path the parallel-run proof writes its full report to.                                                                                                                                                                                                 |
+| `PERISCOPE_FC_SEED`                  | Tests only. The property-test seed: a number reproduces a reported failure, `random` explores.                                                                                                                                                                               |
+| `PERISCOPE_UPDATE_CONTRACTS`         | Tests only. Set by `npm run contracts:update` while it re-approves the snapshots under `contracts/`.                                                                                                                                                                         |
+
+`CLAUDE_CONFIG_DIR`, when set, and `PERISCOPE_AGENT_HOME`, when it is not the default, are added to
+the gate's protected paths; the full set is listed in [the gate](gate.md).
+
+## What a controller can set over the link
+
+`host_configure` accepts six of the config-file keys: `PERISCOPE_WORKSPACE_ROOT`,
+`PERISCOPE_REPOSITORY_ROOT`, `PERISCOPE_BRANCH_SCHEME`, `PERISCOPE_AGENT_HOME`,
+`PERISCOPE_CONTROLLER_URL`, `PERISCOPE_DECISION_URL`. The host screens the whole set before writing,
+refuses a change to a workspace root while any session is live or opening, and answers with the
+effective values plus the keys its environment shadows. The two addresses are written but never
+applied to the live link: the host keeps dialling what it dialled, names them as pending in its
+answer and in every hello, and the next start reads the file. The host id is never settable over the
+link. A controller can also list one directory or read the head of one text file under the
+repository root (`repository_list` / `repository_read`), jailed to that root and to the protected
+set, bounded, and text-only. [The wire protocol](protocol.md) states both doors.
+
+## What the host prints
+
+Every line of output is `<ISO timestamp> [channel] message`, with a detail after a dash when there
+is one. The first lines of a host with no identity configured look like this:
+
+```
+2026-09-08T12:00:00.000Z [host] periscope 1.0.0 · host build-box · credential absent · workspace none · config file /home/agent/.periscope/config.json
+2026-09-08T12:00:00.000Z [credential] absent - no identity is configured, so this host will dial without authentication
+2026-09-08T12:00:00.010Z [link] idle -> connecting (start_requested)
+2026-09-08T12:00:00.250Z [link] connecting -> open (socket_connected)
+2026-09-08T12:00:00.310Z [link] open -> accepted (hello_completed)
+```
+
+A paired host prints `[credential] paired as <hostId> - the paired credential is presented on every
+dial` instead; a host on a signed-in token prints its first `[credential]` line (`cache-hit`,
+`refreshed` or `refused`) when the first dial presents it. `open` is the socket; `accepted` is the
+controller's welcome, and the link stays there. A rejected handshake, a dropped socket or a missed
+heartbeat moves it to `backoff` with the cause named.
+
+`periscope status` prints the same posture whole, from the record `serve` keeps beside the
+credentials, so it answers even when the link is down and never dials: the version, the link's state
+and last transition, the credential kind and its expiry or none, the host id and whether the paired
+credential overrides the configured one, the workspace mode and branch scheme, the config file's
+path, and every setting with the source it came from (environment, config file, default, or unset).
+
+## Why the host refuses to start
+
+With the reason on stderr and a non-zero exit, when:
+
+- the effective uid is 0 (an unattended agent as root has the whole machine on every tool call, and
+  a container built the obvious way runs as root; refused by policy, before anything else is read);
+- the config file exists but is not usable (not JSON, not one object of strings, or carrying a key
+  outside the closed set);
+- `PERISCOPE_CONTROLLER_URL` is unset, or `PERISCOPE_DECISION_URL` is unset, or either carries a
+  scheme it cannot use;
+- the workspace posture is inconsistent: `PERISCOPE_WORKSPACE_KEY` without `PERISCOPE_WORKSPACE_ROOT`,
+  `PERISCOPE_BRANCH_SCHEME` without both roots, a scheme with an unknown placeholder or an unmatched
+  brace, a scheme whose literal text renders an illegal branch name, a relative root or agent home,
+  or a default key that fails the same screen a wire-supplied key must pass;
+- a paired-credential file exists but cannot be read;
+- the identity configuration is partial or wrong: one of the authority/client-id pair without the
+  other, a non-https authority, one of the authorize/token endpoints without the other, a redirect
+  port outside 0-65535, or a scopes variable set to nothing;
+- identity is configured but there is nowhere to keep the token cache (no home directory and no
+  `PERISCOPE_CONFIG_DIR`).
+
+After start-up, one link event is fatal: `credential_rejected`. The controller or its identity
+provider has refused the host's material, so the process stops its sessions, prints the remedy
+(`periscope pair <code>` for a paired host, `periscope login` otherwise) and exits non-zero.
+
+## Running unattended
+
+Run the host under a supervisor (systemd, a Windows service, a container's init) and let it restart.
+It exits 0 on SIGTERM or SIGINT after ending its sessions, and 1 when its credential is refused
+(`credential_rejected`, above) or when its configuration refuses at start; every other failure is
+retried with backoff, forever, and `periscope status` says where it is. In a container, do not run
+as root, `exec` the process so it receives SIGTERM, and keep the shebang LF (`SECURITY.md` says why
+each fails confusingly otherwise).
+
+## Two constraints, before you deploy
+
+**One controller, one replica.** The sequence and retention model assumes one controller process on
+the other end of the link: sequence numbers are dense per session per direction, a frame is held
+until that controller acks it, and the host-scoped channel is numbered per link. Two replicas behind
+one address would each see the other's frames as gaps. Run one controller instance per host.
+
+**The handshake is a protocol version window.** The host's `link_hello` carries `protocolRange`
+beside `protocolVersion`; the controller answers with the version it chose inside the overlap, and
+the host accepts any version in its own window. From the next protocol bump on, the version before
+the current one stays supported for one release, so a controller and a host one release apart still
+connect and either can upgrade first. A controller outside the window is refused by name
+(`protocol_version_rejected`, naming both windows) and the host retries with backoff, forever, until
+one side moves.

package/docs/gate.md

@@ -0,0 +1,219 @@
+# The gate
+
+The permission mechanism: `options.hooks.PreToolUse`, fail-closed on every path, an offline local
+refusal ahead of it, and a hold that makes "who is waiting on a decision" answerable. How the gate
+is composed onto a session is in [architecture.md](architecture.md); how a decision travels is in
+[protocol.md](protocol.md).
+
+The invariant is absolute: no answer, any error, any timeout, any outage, any unrecognised decision
+means the tool does not run. Everything downstream is designed around trusting that sentence, and
+the SDK's default falsifies it: a hook handler that throws is treated by the CLI as absent, not as
+a denial, so under `bypassPermissions` a bug in the gate's own code would be an open door.
+
+## Why `PreToolUse`, never `canUseTool`
+
+The hook fires on every tool call, MCP tools and subagent-internal calls included, carrying
+`agent_id` and `agent_type`. `canUseTool` is skipped whenever a settings-file allow rule,
+`options.allowedTools` or `bypassPermissions` covers the call, and those are embedder-chosen
+configurations, so a hold built on `canUseTool` silently does not fire on somebody else's setup.
+`Decision` is shaped as the SDK's `PermissionResult` field for field and the decider is an injected
+async function, so wiring the `canUseTool` durable-hold lane later is a wiring job, not a redesign.
+The SDK ships no `PermissionResultDeny` type; the deny shape is
+`{ behavior: 'deny'; message: string; interrupt?: boolean }`.
+
+## Fail-closed, in layers
+
+- Every handler path returns an explicit `permissionDecision: 'deny'` on error. That is the
+  difference between fail-closed and fail-open, not defensive style.
+- A recovery path must not use the thing that broke. `readRequest` is total and returns `null`
+  rather than a filled-in default: an unnameable call is not an authorizable one, so it blocks. A
+  catch that re-read the hook input would throw inside the catch when reading the input is what
+  threw, and the handler would escape as absent.
+- A negative control against this invariant must remove every defence, or write a case only the
+  outer one can satisfy. Removing one redundant defence leaves the suite green and measures the
+  redundancy, not the invariant. Validate such a control by which tests go red, never by how many.
+- An allow returns no opinion unless `grantOnAllow` is set (below). Without it the gate only ever
+  adds a refusal, and allow output exists solely to carry `updatedInput`.
+
+## What an explicit allow skips
+
+The Claude Code documentation states that deny and ask rules are evaluated regardless of a hook's
+allow, and that an explicit allow skips only the permission mode, the allow rules and `canUseTool`
+(<https://code.claude.com/docs/en/permissions#extend-permissions-with-hooks>). The operator's deny
+and ask rules survive it.
+
+That claim is documented, not measured, and the package's standing rule is that the runtime beats
+the documentation. The probe that would settle it is written in `gate.live.test.ts` (does a hook
+allow override an operator deny rule) and is not exercised: run from inside an agent session it is
+contaminated by the enclosing harness's tool surface, so it must be run on a machine that is not
+itself an agent session. Do not upgrade the claim without that receipt.
+
+## `grantOnAllow`
+
+`GateTimings.grantOnAllow` defaults to false, and leaving it there gives a gate that cannot say
+yes. Saying nothing leaves the agent's own permission mode as the decider, and an embedder loading
+no settings files (the package default, and the only posture under which this host can state what
+an agent's permissions are) has left nobody who can grant. On a real session the gate allowed a
+`Write`, the tool did not run, and the model was told it had requested a permission nobody had
+granted, in a host with no user to grant anything. The flag does not weaken the gate; it makes the
+decision the gate already took take effect, one call at a time.
+
+- `PeriscopeHost` sets it to true. By its own default it loads no settings files, so nothing sits
+  behind the gate a grant could override.
+- Setting it with `settingSources` non-empty is refused by name, `permission-grant-shadows-settings`,
+  before any process exists. Not because a grant is a bypass (deny and ask survive it), but because
+  two mechanisms then answer the same question from different places with no stated precedence.
+  The exception is `permissionMode: 'bypassPermissions'` (`isBypassMode`): under bypass the mode
+  already allows everything the grant skips, so the grant changes nothing and there is no second
+  authority to shadow. A hook deny survives every mode. Every other mode keeps the refusal, and the
+  refusal reaches the controller as a `spawning` to `ended` transition ([protocol.md](protocol.md),
+  the refused open).
+- That refusal is incomplete on its own logic, and says so: managed policy settings and
+  `~/.claude.json` load regardless of `settingSources`. An empty list is not proof that no operator
+  rule is live.
+- The residual an embedder hits: composing by hand and leaving the flag off yields a gate whose
+  every approval silently fails to happen. The first such allow raises a `gate-cannot-grant` degrade
+  if `onDegrade` is passed (`composeSession` wires it from `onRefusal`, so a `PeriscopeHost` embedder
+  gets it); a hand-composer who passes neither gets silence. The doc comment on the field is the
+  primary defence.
+
+## The host's own gate
+
+`localGate` (`src/gate/local.ts`) is consulted before the decider, and that ordering is the offline
+property: with the controller unreachable a locally refused call is refused immediately instead of
+after `DEFAULT_DECISION_TIMEOUT_MS` reported as an outage. It is synchronous and total by contract;
+an asynchronous local policy would be a second place a decision can hang.
+
+What refuses locally, and only locally: a path that escapes the session's workspace
+(`path-escapes-root`), a read of the protected set (`credential-path-denied`), and a git invocation
+whose verb is not on the allow-list. A boundary-crossing shell shape (`shell-boundary-command`: a
+push, a force, a remote change, a branch deletion, a merge) is classified locally and then
+escalated like any other call, because a controller may hold it for a person to answer; refusing it
+in-process would make that answer impossible to give. With the controller unreachable it refuses at
+the decision deadline.
+
+- It adds refusals and never removes one. No opinion returns `null` and the surrounding gate asks
+  whoever it was going to ask. A locally-decided refusal is `refusal/<reason>`, and the fix for one
+  lives with the embedder's policy.
+- A throwing local gate refuses; it must not fall through (`askLocalGate` in `src/gate/gate.ts`).
+- The vocabulary is owned locally, never received. The wire carries no policy in either direction;
+  the embedder chooses tool families and protected paths at construction.
+- Optional in the type, supplied by default by `PeriscopeHost`: jailed to the session's own
+  workspace, with `credentialPaths(env, { agentHome })` as the protected set. That set, stated once
+  (`src/host/paths.ts`): the host's own config directory (`PERISCOPE_CONFIG_DIR` or
+  `~/.periscope`, which holds the token cache, the paired credential and the config file);
+  `~/.claude` and `~/.claude.json`; `~/.aws`, `~/.config/gcloud`, `~/.azure`, `~/.ssh`;
+  `CLAUDE_CONFIG_DIR` when set; and the effective agent home when it is not the default. The
+  host's own cache location derives from the same function, so the two cannot disagree about what
+  is protected. The repository read doors honour the same set.
+- Shell commands are parsed before they are judged (`src/gate/command.ts`, `src/gate/shell.ts`):
+  the classifier sees a parsed shape, never text. An interpreter payload (`bash -c "..."`) is
+  scanned as the nested command it is, with the interpreter's own delimiter closing it, so a nested
+  quote of the other kind and a `#` inside the payload are the nested command's own syntax.
+  `src/gate/shell.property.test.ts` holds totality, determinism and monotone refusal under quoting
+  and composition.
+
+## The five outcomes that must never blur
+
+| Outcome                                                                                | Cause on the transition                                                        | Fix lives with                |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------- |
+| A deliberate denial                                                                    | `control/permission_denied`                                                    | nobody; it worked             |
+| A locally-decided refusal, taken before anyone was asked                               | `refusal/<reason>` (for example `path-escapes-root`, `credential-path-denied`) | the embedder's policy         |
+| An outage (the decider threw, the transport failed, a non-2xx status, a non-JSON body) | `refusal/permission-decision-unavailable`                                      | the controller's availability |
+| A decision this build does not know (valid JSON, unknown `behavior`)                   | `refusal/permission-decision-unrecognised`                                     | the controller's version      |
+| The host's own deadline passed                                                         | `timeout/hook_timed_out`                                                       | the configuration             |
+
+Beside them is one degrade, which reports on the gate's own configuration rather than on a request:
+`gate-cannot-grant`, raised at most once per gate on the first allow that does not take effect. It
+is a `RefusalReason` declared in `src/core/refusal.ts`, not a free string, so a degrade cannot be
+invented at a call site.
+
+The unknown decision is never an allow. Its raw payload is preserved into the emitted transition
+(bounded, marked when truncated) and it is refused by the gate, not the transport:
+`escalatingDecider` returns well-formed nonsense intact so the tool's fate is a policy act with a
+receipt, not a parse error. Malformed JSON is an outage because version skew produces a different
+decision, never a broken one. `cause.event` is `permission_denied` in `CONTROL_EVENTS`; naming the
+SDK's `PermissionDenied` hook would write into the trace the name of an event that does not fire.
+
+## Two deadlines, the inner one the host's
+
+- The matcher's `timeout` (per matcher, in seconds, fail-closed; `DEFAULT_MATCHER_TIMEOUT_SECONDS`)
+  is CLI-enforced; the handler never learns it fired, so a block would read as a hang.
+- The host's `decisionTimeoutMs` (`DEFAULT_DECISION_TIMEOUT_MS`) fires first, blocks, and names the
+  expiry; the matcher remains the backstop for the case where this code is what hung. A decision
+  still open after `holdAfterMs` (`DEFAULT_HOLD_AFTER_MS`) opens the hold described below. `permissionHooks()` throws at construction
+  when `decisionTimeoutMs >= matcherTimeoutSeconds * 1000`; equal is refused too, because two timers
+  racing at the same instant is a coin flip, not an ordering.
+- A controller that holds a decision for a person keeps its own budget strictly inside
+  `decisionTimeoutMs` and answers with a non-2xx status when the budget passes. An unanswered hold
+  that runs into the host's deadline reports as a timeout, and one that runs past the matcher's
+  reads as a hang.
+
+A per-session `gate` in `session_new` (`decisionTimeoutMs`, `holdAfterMs`, `matcherTimeoutSeconds`)
+overrides the host defaults; an inverted pair answers the named refusal `gate-deadlines-inverted`
+rather than a throw, enforced in two places from one declaration (`deadlineOrderRefusal`).
+
+## The hold
+
+A decision taking longer than `holdAfterMs` opens a `permission:<toolUseId>` entry through the
+state machine and closes it at resolution; a synchronous allow or deny opens nothing, because an
+entry opened and closed in one tick is noise in the one signal it carries. It is keyed by
+`tool_use_id`, so a second `PreToolUse` for the same tool name cannot close a live hold; the
+observer's `permission:<toolName>` lane is single-writer and effectively dormant (only the
+never-firing `PermissionRequest` opens it). Emission rides outside the deny path's `try/catch`: a
+gate that fails closed still says it did.
+
+The hold reaches the wire. `forwardSession` subscribes to `machine.onTransition` and emits every
+recorded transition whatever caused it, so a hold, a deny, an outage and an expiry are all visible
+off-box. That is also why `system/hook_started` and `system/hook_response` are declined in
+`MESSAGE_ROUTING`: the decision's transition already rides the wire, and forwarding the hook
+messages too would invite a consumer to count one decision twice.
+
+Register the gate after the observer: `mergeHooks(observationHooks(...), permissionHooks(...))`.
+Matchers are dispatched in array order but awaited concurrently, and a gate registered first would
+open a hold the observer closes in the same event. No test pins the order; it lives at both sites.
+
+## Escalation
+
+`escalatingDecider()` asks the controller over HTTP and discriminates the status before reading the
+body: a 500 with a parseable body must never impersonate a human "no". An `EscalationUnavailable`
+keeps its own detail so an outage says which lane failed.
+
+`DecisionRequest` carries `sessionKey`, the controller's handle for the session, so a decision can
+be correlated without re-deriving it from transport state. The POST presents a credential per
+request (`EscalationOptions.credential`, resolved at call time), and a refusing credential is an
+outage, the deliberate opposite of the link's posture: a prompt that cannot be delivered is
+retried; a gate that cannot authenticate must not proceed. Resolving per request makes this lane a
+second caller of `authorize()`, so a busy session reports one `cache-hit` per decision; read a
+stream of them as the gate working, never as a credential problem.
+
+## What is deliberately not covered
+
+- `bypassPermissions` is composable, as the SDK's own `permissionMode` vocabulary. It travels wire
+  to `readSessionRequest` to `src/host/agent-process.ts` and nowhere else, and
+  `pins/permission-config.test.ts` holds three things: no settings-file or rule-list option
+  anywhere, `permissionMode` only on that path, and `setPermissionMode` called from one module (by
+  `session_configure`) while the other mid-session mutators stay uncalled. The gate keeps its
+  authority through `PreToolUse` in every mode; the package's own measurement of a hook deny
+  surviving bypass is the unexercised probe above.
+- `permissionDecision: 'defer'` was evaluated and not adopted: it ends the query for a later
+  resume, a different lifecycle from "hold, then continue with everything you knew".
+- `outputFor` cannot render a hold: `holding` is excluded by the type, not by a branch. A branch
+  that returned `{}` for it would be no opinion, which the CLI reads as allow, so the one state that
+  could open the door is made unrepresentable rather than handled.
+
+## Where things live
+
+| Path                                       | What                                                                                                              |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `src/gate/gate.ts`                         | `permissionHooks()`: registration, the fail-closed wrappers, both deadlines, the hold                             |
+| `src/gate/decision.ts`                     | `Decision` (the SDK's `PermissionResult`) and `readDecision`, the total parser                                    |
+| `src/gate/outcome.ts`                      | `GateOutcome` (`holding`, `allow`, `deny`, `refused`, `expired`) to transitions, pure; `recordGateOutcome`        |
+| `src/gate/escalate.ts`                     | `escalatingDecider()`: status before body, `EscalationUnavailable`; the HTTP lane the link does not carry         |
+| `src/gate/local.ts`                        | `localGate()`: the host's own offline refusal; pure, synchronous, total                                           |
+| `src/gate/jail.ts`                         | The path jail and the protected-path check; `pathFromToolInput`, `commandFromToolInput`                           |
+| `src/gate/shell.ts`, `src/gate/command.ts` | `classifyShellCommand` over `parseCommand`'s parsed shape                                                         |
+| `src/host/paths.ts`                        | `credentialPaths(env)` and `nodePathResolver`: the one source of the protected set and the token cache's location |
+| `src/host/host.ts`                         | Where the gate is composed onto a session, and the `grantOnAllow` and `settingSources` refusal                    |
+| `src/pins/permission-config.test.ts`       | The shadowing-lane pin, compile and scan halves                                                                   |
+| `src/gate/gate.live.test.ts`               | The live probes, skipped unless `PERISCOPE_LIVE=1`                                                                |

package/docs/identity.md

@@ -0,0 +1,107 @@
+# Identity
+
+How a host proves who it is to a controller, and what protects the material it holds. The wire
+side of this (the credential on the three transports, pairing as a contract) is in
+[protocol.md](protocol.md); what the gate keeps the agent away from is in [gate.md](gate.md).
+
+A host presents one credential on every transport it uses, and there are three postures:
+
+| Posture       | What is presented                                                   | Choose it when                                                                                     |
+| ------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| **paired**    | a machine credential the controller minted (`p1.<hostId>.<secret>`) | the host runs unattended; the credential has no clock and dies only when the controller revokes it |
+| **signed-in** | a real user's own access token, refreshed by the host               | a person is at the machine and the controller wants a user identity, not a machine one             |
+| **none**      | nothing; the host connects without a header and says so at start-up | the controller is reachable only from inside a network that is itself the boundary                 |
+
+The daemon never signs anyone in. `periscope login` writes the token cache; `periscope pair <code>`
+writes the paired credential; `serve` presents what is already there and refuses by name when it is
+not. When both exist the paired credential wins: a refresh token can lapse after a period of
+inactivity, and a paired credential cannot.
+
+## The agent's own identity is separate
+
+The credential above authenticates the host to the controller. The agent the host spawns
+authenticates to its own provider separately, through the Claude Code CLI's ambient credential
+under the agent home (`~/.claude` by default). The spawn environment is an allow-list, so
+`ANTHROPIC_API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN` set on the host are not inherited by a session;
+sign the CLI in once, as the OS user that runs the host (`claude auth login`; `claude auth status`
+confirms), or pass a key to one session through `session_new.request.env.extraEnv`.
+
+## Pairing: the durable machine credential
+
+A signed-in user mints a short-lived single-use code from the controller, and
+`periscope pair <code> --controller <origin> --label <name>` trades it for this machine's own
+credential, written beside the token cache under the config directory, presented on every dial,
+preferred over the token cache when both exist.
+
+|                                  |                                                                                                                                                                                                                                                                                                                                                                                                            |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **What it is**                   | A controller-minted bearer shaped `p1.<hostId>.<secret>`, scoped to the user who minted the code. The shape is the contract: the host reads its own id out of it, and `pair` refuses an answer outside the shape before writing anything. A controller keeps only a hash of the secret; this machine holds the one copy                                                                                    |
+| **Where the redemption door is** | `--controller <origin>` when given (its origin plus the controller's pair route, `/api/periscope/pair`); else `PERISCOPE_PAIR_URL` when set; else the origin of `PERISCOPE_DECISION_URL` plus that route. A 404 at the door is named as a wrong door, not as a refused code                                                                                                                                |
+| **What else the answer carries** | The controller names the link and decision URLs this host should dial (`controllerUrl`, `decisionUrl`). When both arrive, `pair` writes `PERISCOPE_CONTROLLER_URL` and `PERISCOPE_DECISION_URL` to the config file beside the credential, so `serve` needs nothing else; the environment still wins per key, and the write says so when it is shadowed. A controller that names neither leaves both to you |
+| **Revocation**                   | The controller's, per machine: it refuses the bearer at the upgrade (401 or 403) and closes the link. The host reads that as `link-unauthorized`, which is terminal: it exits non-zero naming the remedy, a fresh `periscope pair <code>`                                                                                                                                                                  |
+| **The label**                    | `--label <name>` names this machine in the controller's listings; `PERISCOPE_MACHINE_LABEL` when the flag is absent; the hostname otherwise                                                                                                                                                                                                                                                                |
+
+## Signing in as a user
+
+The host signs in as a real user and presents that user's own access token. No provider hostname or
+tenant is baked in: the authority, client id, scopes and endpoints are configuration, and a test
+fails the build if a provider hostname appears in shipped code. One provider-specific error code is
+recognised (`AUTH_FLOW_BLOCKED_CODES` in `src/identity/device-code.ts`), so that material a
+provider's policy has blocked is discarded and named rather than refreshed forever.
+
+|                                 |                                                                                                                                                                                                                                                                                                       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Primary flow**                | Loopback authorization code + PKCE (`S256` only; `plain` is refused, not merely unused), the same shape `az`, `gh` and `kubectl` use. The listener binds `127.0.0.1` explicitly, accepts exactly one callback, and times out                                                                          |
+| **`state` is verified, always** | PKCE protects the code exchange; `state` protects the callback. They are not substitutes. The agent shares this host's OS user, so any local process can reach the loopback listener, and an unverified callback would let one hand this host a code it obtained itself                               |
+| **Fallback**                    | Device code, off unless `PERISCOPE_IDENTITY_DEVICE_CODE=1`. Never reached by falling back. Some providers class it as a high-risk flow and let organisations block it by policy, and a device-code sign-in can poison the cache for any other flow, so switching flows discards rather than refreshes |
+| **Cache**                       | One JSON file, written `0600`, verified after write. See the limit below                                                                                                                                                                                                                              |
+| **Configuration**               | `PERISCOPE_IDENTITY_AUTHORITY` + `PERISCOPE_IDENTITY_CLIENT_ID` are required together. Set neither and the host starts without identity. Set one wrongly and the host refuses to start: a typo must not degrade into "authenticating as nobody"                                                       |
+
+## What `0600` is, and what it is not
+
+It is not a boundary against the agent. The agent runs as the same OS user as this host, so an
+`0600` token file is readable by it exactly as it is by the host. What keeps the agent out is the
+gate's credential-path denial, and that denial covers this file because `credentialPaths()` and
+`tokenCachePath()` are derived from one function, not kept equal by hand.
+
+The improvement is still real, and it is a change of order rather than degree: what this replaces
+is a shared secret granting access as _every_ user. What it stores is _one user's own_ token,
+expiring by itself and revocable from the provider without touching this machine.
+
+On Windows the mode cannot be confirmed at all. Measured: a file written `0o600`, a file `chmod`ed
+to `0o600`, and a deliberately world-readable one all report `0o666`. So the host probes what the
+filesystem actually records and reports `credential-mode-unenforced` as a named degrade where
+privacy is unconfirmable. It does not claim a privacy it cannot verify.
+
+The probe proves it is alive before it reports a negative. `chmod 0444` _does_ read back as `444`
+on Windows (the write bit is the one real bit there), so the probe takes that reading as a positive
+control. Three outcomes, never two:
+
+|                  |                                                                                                                                                   |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enforced`       | POSIX modes are honoured; the file is verified, and one wider than requested is refused                                                           |
+| `write-bit-only` | Only writability is recorded, so privacy is unconfirmable. A finding                                                                              |
+| `unobservable`   | Not even clearing the write bit changed anything: inconclusive, and reported as a different reason. A probe that cannot fail is not a measurement |
+
+`0444` is the control, never the target: the cache stays owner-writable because refreshes are
+written to it.
+
+## Deployment: where the app registration lives
+
+One public-client registration with a loopback redirect, at any OIDC provider that supports the
+authorization-code flow with PKCE. The host consumes it; it never creates it.
+
+A tenant or organisation gets its own registration, and the host is pointed at it through
+`PERISCOPE_IDENTITY_AUTHORITY`. That is a deployment step, not a code path, which is the reason the
+authority is configuration. Some provider tenant types are single-tenant by construction, in which
+case one registration cannot be shared across tenants and each deployment registers its own.
+
+## Where things live
+
+| Path                                  | What                                                                                            |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `src/identity/`                       | The generic OIDC client: config, PKCE, the authorization and device-code flows, the token store |
+| `src/identity/paired-credential.ts`   | The paired credential's shape and the reader that refuses a file whose two copies disagree      |
+| `src/host/sign-in.ts`                 | The interactive flows the `login` verb runs; the refresher the daemon presents                  |
+| `src/host/paths.ts`                   | Where the cache, the paired credential and the config file live, and the protected set          |
+| `src/bin/login.ts`, `src/bin/pair.ts` | The two verbs                                                                                   |