git:20261005.a2e17df to git:20261005.20bab2d

# host

## Purpose

Shared operating-system primitives for the daemon and terminal launcher.

Shared endpoint policy stays in Gleam; this package owns its typed private

record and the filesystem, lock, process, clock, and cryptographic operations

beneath it. The shared WebSocket transport owns socket startup and lifetime;

callers own launch timing, authentication policy, and application messages.

## Key Types

- `host/skill.Catalogue` captures canonical skill documents and discovery

warnings. Each `Skill` keeps its name, description, argument hint, invocation

modes, source path, body and complete document together. `discover` suppresses

directory/file aliases and reports distinct name collisions; `expand` discloses

the complete captured document only at activation, with bounded substitution.

- `host/bootstrap.LaunchLock` holds the original lock-helper port.

`try_launch_lock` acquires it, `lock_monitor` observes its death, and

`release_launch_lock` closes it. The calling process owns its lifetime.

- `host/bootstrap.ServerProcess` retains a paused wrapper's port.

`spawn_server` returns it with the OS PID; `release_server_process` lets

the wrapper exec the server after its identity has been published.

`spawn_server` waits for one byte the wrapper's shell writes before it

parks, so the PID it returns already leads its own process group: OTP

reports a forked child's PID before the child calls `setsid`.

- `host/bootstrap.ProcessIdentity` distinguishes `ProcessPresent(birth)`

from confirmed `ProcessAbsent`. Observation errors remain errors. The Erlang

side returns exactly this shape, so nothing translates between the

observation and the caller.

On Linux, only `ENOENT` and `ESRCH` from the target `/proc/<pid>/stat`

read establish absence; boot-id, self-stat and other read errors stay errors.

- `host/endpoint.{Paths, Fence, Endpoint}` defines fixed state-root paths and

`Starting`/`Ready` discovery. `availability` permits replacement only for

fresh state or an observed departed native identity. `claim` adopts only

the matching paused-wrapper reservation; `publish_ready` replaces that exact

reservation with the actual listener port and daemon epoch.

- Private-file operations validate ownership and permissions, bound reads,

and atomically replace a file after flushing its complete contents.

- `host/claim` is the shape of a claim token (protocol-change/053) shared by

the daemon that mints claims, `loomd access` that prints them and `loom

claim` that redeems them: `prefix` (`loomclaim_`), `validate_token` (the

prefix and 64 lowercase hex, nothing else), `is_claim_shaped`,

`mint_token(entropy)`, `random_credential` (32 bytes of

`crypto:strong_rand_bytes`), and `digest` (lowercase SHA-256 hex). It also

owns `remote_address`, the rule that a bearer or a claim crosses cleartext

`ws` only to a literal loopback address, and `endpoint`, which turns a

`/v2/control` address into its `/v2/claim` twin.

- `host/access` is the owner's access command (protocol-change/053), one

implementation behind `loomd access` and `loom access`. `parse(arguments,

program)` turns the positional grammar (`list`, `show`, `members`, `invite`,

`set-role`, `revoke`, `rotate`, `revoke-credentials`, `isolate`) into an

opaque `Request` whose target is `Local` (the state directory's endpoint

record and `owner.token`) or `Remote` (`--addr` with `--token-file`, which

only `Loom` accepts). `run(arguments, program, check)` prints through a

`Console` and answers `Succeeded` or `Failed`; the binary turns that into

its exit status, and `check` lets `loomd` add the daemon's own decoder as a

further refusal. `principal_lines`, `membership_lines` and `member_lines` (a

session's members, `loom access members SESSION [--after PRINCIPAL]`) are the

listing checks on their own, and `invite_line` and `rotate_line` render the `loom

access` lines the terminal's `/access` overlay shows in place of granting

(phase 3). Replies are re-encoded from checked fields: a listing row

keeps a 16-hex fingerprint and never a longer value, a claim is printed only

for an invitation or rotation that asked for one, and any other field the

daemon sent is dropped. `raw_request`, `discover` and `exchange` are the

seam the peer commands share.

- `host/websocket.Connection` retains the original socket subject.

`connect_mapped` maps every lifecycle event in the existing socket owner, so

terminal adapters need no forwarding process. `Connected` is minted in the

Stratus initialiser, which runs after the upgrade and before the actor's

first loop pass, so it cannot arrive behind an `Incoming` or `Closed` the

socket delivered while startup was still returning.

## Relationships

- **Depends on**: `glaml`/`yamerl` for YAML skill frontmatter and `gleam_regexp`

for Unicode skill names; `core/json` for the bounded total endpoint codec;

`gleam_stdlib` for typed results; `gleam_erlang` for the whole of

`gleam/erlang/process` that `host/websocket` runs on — monitors, selectors,

links, trapped exits — and for the lock monitor type; `gleam_http` and

`stratus` for the existing WebSocket transport; `weft` for guarded startup,

socket custody and the monotonic clock; and `gleam_crypto`, `gleam_time`,

`envoy`, `simplifile` and `filepath` for the facts that used to be

hand-written Erlang. These transport dependencies moved from the TUI; no

second WebSocket implementation was added.

- **Depended on by**: `client` for daemon state-root ownership, the claim

token shape and `loomd access`; `tui` for local server bootstrap, its own

bounded file reads, the remote-address rule, `loom claim` and `loom access`. Terminal logger suppression,

stdout forwarding, and VM exit remain in `tui`.

- **FFI**: `host/internal/ffi_zlib` exposes the shared bounded gzip inflater

in `host_zlib_ffi.erl`. Extension installation retains its original client

adapter, while release installation calls the shared primitive directly.

OTP zlib produces bounded chunks; the shim rejects excess output before

retaining another chunk. `host/bootstrap` and `host_bootstrap_ffi.erl` hold

the remaining operations no Gleam package reaches: cross-process advisory locking through a helper port,

`open_port` process launch and release, a positioned bounded read

(`read_prefix`/`read_bounded`), an exclusive-create atomic rename,

`realpath`, `os:find_executable`, `os:getpid`, `id -u`, procfs and Darwin

`ps` birth identity, and the loopback-port reservation the legacy v1

launcher still uses. Clocks, digests, the environment, `stat`, directory

listing and permission bits are Gleam over the packages above. OTP's port

monitor is called directly from `host/bootstrap` because `gleam_erlang`

exposes `process.PortDown` but no public port-monitor constructor.

## Traffic

- **Actor messages**: `websocket.Message` delivers `Connected`, `Incoming`,

`Closed`, and `NetworkFault` to the original reader-owned inbox.

`Outbound.SendText` and `Stop` reach the existing Stratus socket actor.

Its guardian monitors the reader and startup attempt; Erlang ports separately

deliver data and exit status, and `lock_monitor` delivers `process.PortDown`.

- **Commits and registers**: none. Conversation databases are outside this package.

- **OS boundary**: lock helpers use `lockf` on Darwin and `flock` on Linux.

A paused server wrapper waits for one release line before exec, and its

environment is this VM's plus `LOOM_LOG` rather than a replacement for it,

so the daemon inherits provider credentials and locale. Birth identity uses

Linux procfs or Darwin `ps`; canonical paths use `realpath`, and

`ensure_private_directory`/`read_private_bounded` use `/usr/bin/id` for the

one fact `stat` cannot give them. `host/endpoint` therefore needs a platform

`realpath` and `/usr/bin/id` on the startup path.

## Invariants

- Skill discovery reads at most 256 direct entries per configured location and

64 KiB per document. Metadata and body share one capture; model context gets

only selection metadata until invocation. No skill frontmatter or shell

snippet executes in the host, and expansion grants no tool permissions.

- The lock owner must outlive readiness. Port loss can release the kernel

lock even if a pathname still exists; the pathname alone proves nothing.

- Darwin uses `lockf -k` to preserve one inode across releases. Competing

owners must never lock different inodes through the same pathname.

- Paths cross the Erlang boundary as Unicode characters, never UTF-8 bytes

expanded into separate codepoints.

- A wrapper starts paused. Its caller publishes PID and birth identity before

release. Closing its port after exec does not prove that the server stopped.

- Failure to observe a process is not confirmed absence. Startup policy must

not infer safe replacement from an observation error.

- Birth identity is not equally strong on both platforms. Linux pairs the

kernel boot id with `/proc/<pid>/stat`'s `starttime`, which is jiffy-grained;

Darwin's `ps -o lstart=` has one-second resolution, so two processes born

within the same second under one recycled pid are indistinguishable there.

Nothing in the design closes that gap; it bounds how much a Darwin birth

marker proves.

- A daemon log is arbitrary child output, so `current_log_tail` returns bytes

and `host/bootstrap` decodes them. A byte offset can land inside a codepoint,

and a `String` minted from such a slice breaks the type's invariant for every

later `string.*` call on the one path that reports why startup failed.

- A failed probe, root death, or released lifetime lock never replaces a

still-live VM. Missing discovery beside existing catalogue state and malformed

records fail closed. Endpoint removal is not part of normal shutdown.

- The launcher releases `launch.lock` before waiting for a child which must

reacquire it. `daemon.lock` independently bounds the root's live resources.

- Guarded WebSocket startup retains its links until the guardian acknowledges

ownership. Abnormal attempt loss or reader death closes the original socket;

normal startup-worker exit does not close a successfully returned handle.

A guardian that fails to start is the one exit that would otherwise leave a

socket with no owner — the worker exits normally and a normal exit over a

link is ignored — so that path kills the socket explicitly.

- The transport does not implement application credits or bound an arbitrary

reader's inbox. Callers enforce their protocol's frame and outstanding-work

limits; moving the transport does not establish a new memory bound.

- A claim token and a bearer are told apart by shape alone: a claim always

carries the prefix and a bearer never does. Every place that accepts one

refuses the other, and no function here logs, formats or echoes either;

`validate_token`'s refusal is a fixed sentence that does not repeat its

input.

## Deep Docs

- [Skills](../../docs/skills.md) describes discovery and progressive disclosure.

- [Client architecture](../../docs/architecture/client.md) explains local startup.

- [Root CLAUDE.md](../../CLAUDE.md) contains repository rules and the doc graph.