@agentshouse/kit 0.0.1 → 0.1.0-alpha.10

package/README.md

@@ -1,3 +1,1777 @@
-# @agentshouse/kit
+# House Kit
 
-Placeholder. Releases are published from https://github.com/agentshouse/kit.
+House Kit is a public package repository. Product development is planned and
+coordinated in the [Agents House repository](https://github.com/trof3039/agents.house);
+this repository contains only the package source and its operator documentation.
+
+## Connect a Linux computer
+
+On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
+versioned bootstrap once:
+
+```sh
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.10/connect-linux.sh)
+```
+
+The release asset pins one immutable multi-architecture image digest. It creates
+owner-protected `~/.house-kit` and `~/AgentsHouse`, mounts those as the complete
+Kit home and `/agents/house`, enrolls through House Login in the host browser,
+and starts the container with Docker's `unless-stopped` lifecycle. Pass
+`--workspace /absolute/path` for one other workspace root or `--manual` for
+the existing URL and one-time-code login route. `--house <origin>` selects
+another House and is retained in Kit home. A repeated invocation reuses the
+same container, credential and Environment; a different installed image is
+left for the explicit update journey.
+
+The versioned `bootstrap.json` is the machine-readable command source for this
+release. It is exported from the npm package as `@agentshouse/kit/bootstrap`
+(JSON import) and published byte-for-byte beside `connect-linux.sh` in the
+GitHub release. Its schema version is `1`, its `version` is the Kit package
+version, and `hosts` contains only bootstrap scripts published in that release.
+The package exports only the `./bootstrap` subpath; `./package.json` and source
+subpaths are not exported. For this release, only `hosts.linux` exists. In this
+schema example, `<version>` stands for the package's version:
+
+```json
+{
+  "schemaVersion": 1,
+  "version": "<version>",
+  "hosts": {
+    "linux": {
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v<version>/connect-linux.sh)",
+      "asset": {
+        "name": "connect-linux.sh",
+        "url": "https://github.com/agentshouse/kit/releases/download/v<version>/connect-linux.sh"
+      },
+      "workspace": { "argument": "--workspace", "quoting": "posix" }
+    }
+  }
+}
+```
+
+`command` is complete for the default workspace. To show a selected absolute
+workspace, append the declared `workspace.argument` and the path as one POSIX
+shell-quoted argument. For example, `/home/user/My Agents' House` becomes
+`--workspace '/home/user/My Agents'\'' House'`. Quote the entire path before
+adding it to a copyable shell command; never interpolate it as shell syntax.
+The bootstrap validates an absolute workspace root and encodes it as one Docker
+`--mount` CSV source field, including commas and double quotes in the name.
+The package manifest contains no image digest: the release workflow
+fills the immutable image digest into the published script after the package
+has been built.
+
+The bootstrap does not install native Kit on an ordinary computer. The native
+package remains for managed Nodes and an explicitly selected eligible Kit host.
+
+The same bootstrap is the host's entry point for the existing `kit` commands:
+append `kit` and the command to the connect command above, as in
+`bash <(curl -fsSL …/connect-linux.sh) kit apply` or
+`bash <(curl -fsSL …/connect-linux.sh) kit telegram connect`. It forwards the
+command and its arguments unchanged into the installed container through the
+host's Docker client and ends with the command's own output and exit status.
+Standard input stays attached and a terminal stays a terminal, so a hidden
+prompt such as the Telegram bot token is read inside the container and never
+becomes an argument or printed output. With the output redirected, the
+command's output and errors stay separate and the terminal stops echoing typed
+input until the command ends. A running container runs the command beside its
+resident Kit; a stopped one runs it in a one-off container over the same Kit
+home and workspace and stays stopped. `kit login` takes the bootstrap's own
+login route, a one-off container on the host network so the host browser can
+return to its loopback listener, or `--manual` for the URL and one-time code.
+Forwarding installs no host-native Kit and gives the container no Docker socket
+or further mount; it refuses when no Kit is installed or the installed one
+differs from this bootstrap's.
+
+## Building the package
+
+The repository checkout is the development source. Build the package
+that can be published by supplying House's dedicated installed-application
+Google OAuth client, its id and its client secret:
+
+```sh
+HOUSE_KIT_GOOGLE_OAUTH_CLIENT_ID=kit-client.apps.googleusercontent.com \
+HOUSE_KIT_GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-kit-installed-app \
+npm run build
+```
+
+The command writes the publishable package to `dist/package`. Both values are
+public instance content fixed into that package at build time: Google issues an
+installed application's client secret without treating it as confidential, and
+still requires it in every token request. The installed Kit does not read either
+from its runtime environment and never requests them from House.
+
+Runtime dependencies stay minimal and exactly pinned in `package.json` and
+`package-lock.json`: House's own `@agentshouse/mdmodel`, `yaml`, which reads
+House's text answers, and the Agent Client Protocol SDK
+`@agentclientprotocol/sdk` with its peer `zod`, which is this Kit's one protocol
+client for the compiled adapter contracts, and `ws` for the authenticated Kit
+control stream. The SDK's approval
+receipt is [`docs/agents/acp-sdk-dependency-approval.json`](docs/agents/acp-sdk-dependency-approval.json),
+which the User wrote once this adoption's proof had passed. The adapter
+packages themselves are Environment prerequisites, not Kit dependencies, and
+carry no record.
+
+The bootstrap invokes bare `kit login`. The first login names its new
+Environment after the host computer and stores its Environment id in Kit home;
+an explicit later login reconnects that retained id. `--environment <uuid>`
+selects a different retained Environment for explicit recovery. A malformed
+id or an answer naming a different Environment is refused before installation.
+
+Use `--manual` when the browser cannot reach the Kit's loopback listener. The
+command stores the issued Kit User credential in `$HOUSE_KIT_HOME/credential`
+or `~/.house-kit/credential` with owner-only permissions, replacing the previous
+file in one rename and leaving configuration, checkpoints, source state and
+Agent relationships untouched. Reconnecting installs authority only: it starts
+no Run and resumes no work, and the next `kit worker run` reconciles this
+installation's bound sessions under its ordinary control rules.
+
+If House never answers the exchange, the command refuses with
+`kit_credential_not_installed` and no credential is written; the remedy is a
+fresh owner-authorized `kit login` for the same Environment. The credential is
+never printed by Kit.
+
+## Configuration
+
+`$HOUSE_KIT_HOME/kit.json` is the one declarative configuration file. Use
+`--config <path>` to name it elsewhere.
+
+```json
+{
+  "availability": "continuous",
+  "execution_authority": "allow",
+  "migrators": [],
+  "instances": [
+    {
+      "id": "acme",
+      "preset": "custom",
+      "services": [
+        {
+          "service": "notes",
+          "source_ref": "src_acme_notes",
+          "rooms": ["work-room"],
+          "backfill": { "days": 30 },
+          "connector": {
+            "command": ["/usr/local/bin/acme-export", "--ndjson"],
+            "timeout_ms": 120000,
+            "environment": { "ACME_REGION": "eu" },
+            "secrets": {
+              "ACME_TOKEN": { "environment": "ACME_TOKEN_SOURCE" },
+              "ACME_KEY": { "file": "/run/secrets/acme-key" }
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "clients": [
+    {
+      "kind": "claude-code",
+      "settings": "/home/ada/.claude/settings.json"
+    }
+  ],
+  "host": null
+}
+```
+
+This file is the whole desired state, so every section it declares is
+reconciled and every section it omits is refused rather than assumed. The
+agent CLI list is not local configuration: House owns it for this Environment,
+and every controlled pass reads, installs, updates, signs in and reports exactly
+the kinds House names. House also owns every Agent, its Profile and its route,
+so this file declares neither Agents nor agent CLIs. The Kit runs whatever Agent
+House assigns on one of House's selected kinds and refuses any other kind. The required
+top-level `execution_authority` is this Environment's one answer to every agent
+permission request, `"allow"` or `"refuse"`; the Agents sharing the Environment
+share it. The
+required top-level `availability` declares this Environment's availability
+mode: `"intermittent"` for a laptop or other normally offline placement,
+`"continuous"` for a server expected to stay online. Omitting it or declaring
+any other value refuses as `kit_configuration_invalid`; `kit apply` sends the
+declared mode with the rest of the desired state. An
+instance declares one or more services, and under the `custom` preset each
+service owns the command that produces it.
+
+`host` declares the Linux host this installation measures for
+[host capacity reporting](#host-capacity). `null` declares that this Kit reports
+no capacity; the section is required like the others, so a host is measured only
+where the Environment owner says so.
+
+`clients` is the local Agent client catalogue and never leaves the installation.
+Each entry names one client whose lifecycle hook configuration this Kit
+reconciles: `kind` is `claude-code`, the one client this Kit installs a hook
+into, and `settings` is the absolute path of that client's own settings
+document. The section is required like the others and declares `[]` when this
+Environment runs no such client. An unknown `kind`, a relative path, and two
+entries naming the same document each refuse as `kit_configuration_invalid`.
+
+A secret is never written into this file. `secrets` names either an
+environment variable the Kit reads at run time or a mounted file it reads from
+disk; the resolved value reaches the connector's environment and nothing else.
+
+`backfill` is chosen once and honored on the first capture: `{ "days": 30 }`
+never delivers anything observed earlier, `{ "count": 500 }` bounds the first
+capture to 500 items and then continues from its cursor unbounded, and
+`{ "all": true }` takes every history the connector offers. The boundary is
+fixed when the service first captures, not each time a capture is attempted, so
+a run that fails and is repeated days later still starts where it would have.
+
+`timeout_ms` may shorten the connector's 120000 ms bound but never raise it. The
+Kit holds this installation's Environment control lease across the connector run
+and the batch it produces, and the lease has to outlive both.
+
+Apply the declared source state to House:
+
+```sh
+kit apply --house https://agents.house
+```
+
+Only the state House declares - instances, services, `source_ref`, and Room
+routes - leaves the installation. The connector, its secret references, and the
+backfill boundary stay local.
+
+## The SessionStart hook
+
+House answers `kit apply` with its current SessionStart hook: one
+`{id, version, event, instruction}` document whose `instruction` tells the Agent
+which Pulse and continuation reads to perform itself. The document is House's
+own text under a stable `id`, versioned with the Kit contract version, and it
+carries no Room content, open item, count, checkpoint, or identity.
+
+`kit apply` writes that instruction to
+`$HOUSE_KIT_HOME/state/hooks/<hook id>.txt` and installs one `SessionStart`
+command hook printing it in every declared client's settings document. The
+installed hook is that read and nothing else: it calls no House operation, marks
+nothing seen, embeds no Room material, and infers no chat Session, so the Agent
+decides what to read from the guidance it receives.
+
+`state/hooks.json` records exactly which settings documents this installation
+has written and the exact command it installed in each, so ownership is that
+record and the command it names rather than any resemblance to one. An entry
+whose command merely mentions the instruction is another owner's and is left
+alone. `clients` is the desired state of that record: applying the same served
+document again leaves each settings document byte-identical, dropping a client
+from the catalogue removes this installation's entry from the document it named,
+and an empty catalogue removes every entry, the record, and `state/hooks/`
+without touching a hook, group, or setting the installation does not own.
+
+One apply reaches every client or restores the ones it already wrote. Every
+declared and previously recorded document is canonicalized, checked, and parsed
+before House is contacted at all - including the `hooks` object and the
+`SessionStart` array this Kit edits, so a document shaped differently refuses as
+`kit_client_settings_unreadable` without changing anything remotely. The counters
+House answers with are validated before the first local change. Each write then
+re-resolves the whole declared path and re-checks the document it prepared,
+refusing as `kit_client_settings_refused` when any part of the path, or the
+document itself, was replaced meanwhile - a parent directory turned into a link
+after preparation receives no write at all. A failed write or a cancellation
+part-way restores every document already written to its previous bytes, removes
+one this installation created, and names as `kit_client_settings_unrestored` any
+it could not restore.
+The previous instruction stays readable until the last document is written and
+only then is it pruned, so a client left holding an older command still reads an
+instruction that is there.
+
+A path is canonicalized through `..` and symlinks before it is used: the Kit
+writes through a symlinked settings document instead of replacing the link, and
+refuses as `kit_client_settings_refused` a path that is not a regular document,
+that two entries share, that resolves into this installation's own directory,
+or - for a document already in the record - that no longer resolves to itself,
+rather than writing through a link that replaced it. An existing document keeps
+its file mode, one the client does not have yet is created owner-only, and one
+the Kit cannot parse refuses as `kit_client_settings_unreadable` rather than
+being replaced. Preparation reads before the Environment control lease is taken;
+every write happens under that renewed lease with the apply it belongs to.
+
+Continuity does not depend on the hook. An Agent working through any client
+receives the same guidance in the server instructions and the tool descriptions,
+and an installation whose catalogue is empty neither installs a hook nor needs
+one served. A declared client is the opposite: an absent or malformed document
+refuses as `kit_hook_rejected` instead of leaving whatever was installed before.
+
+## The Google preset
+
+The published Kit is built with one House-owned Google installed-application
+OAuth client. Its id and client secret are public build-time instance content,
+not House secrets and not values served by House at run time. Google refresh
+and access tokens remain in the installation's local credential store.
+
+Each Google instance represents one Google account, and one Kit installation
+may declare as many as the User has. Each instance owns its own local Google
+authorization, selectors, Source references, Room routes, checkpoints and
+health under `state/<instance>/`; the installation's one `kit login` covers
+them all, and no instance can read another's provider credential.
+
+```json
+{
+  "availability": "intermittent",
+  "execution_authority": "refuse",
+  "migrators": [],
+  "instances": [
+    {
+      "id": "google-account",
+      "preset": "google",
+      "scopes": ["https://www.googleapis.com/auth/contacts.readonly"],
+      "services": [
+        {
+          "service": "gmail",
+          "source_ref": "src_google_mail",
+          "rooms": ["work-room"],
+          "backfill": { "days": 30 },
+          "selection": { "labels": ["INBOX"] }
+        },
+        {
+          "service": "calendar",
+          "source_ref": "src_google_calendar",
+          "rooms": ["work-room"],
+          "backfill": { "all": true },
+          "selection": { "calendars": ["primary"] }
+        },
+        {
+          "service": "drive",
+          "source_ref": "src_google_drive",
+          "rooms": ["work-room"],
+          "backfill": { "count": 500 },
+          "selection": { "files": ["file-id"], "folders": ["folder-id"] }
+        }
+      ]
+    }
+  ],
+  "clients": [],
+  "host": null
+}
+```
+
+Google authorization is incremental. Enabling Gmail requests only Gmail's
+read-only scope; Calendar and Drive request their own read-only scopes only
+when enabled. Each service scope set has its own local provider grant, so a
+later authorization never widens or replaces a sibling service's grant.
+Additional Google API scopes are declared once on the preset instance and
+remain local; a declared service names only scopes that instance already
+holds. Drive requires at least one explicit file or folder selection and never
+defaults to the whole account.
+
+A Google API outside the three curated services may use the closed declared
+service schema. The declaration is data only: no script or executable transform
+is loaded. Its host must be a Google API domain and it runs under scopes the
+instance already holds.
+
+```json
+{
+  "service": "people",
+  "source_ref": "src_google_people",
+  "rooms": ["work-room"],
+  "backfill": { "all": true },
+  "declaration": {
+    "host": "people.googleapis.com",
+    "path": "/v1/people/me/connections",
+    "query": { "personFields": "names,emailAddresses,metadata" },
+    "page_size": "pageSize",
+    "scopes": ["https://www.googleapis.com/auth/contacts.readonly"],
+    "page_token": {
+      "request": "pageToken",
+      "response": "nextPageToken",
+      "checkpoint_request": "syncToken",
+      "checkpoint_response": "nextSyncToken"
+    },
+    "items": "connections",
+    "fields": {
+      "native_id": "resourceName",
+      "native_version": "etag",
+      "provider_modified_at": "metadata.sources.0.updateTime",
+      "observed_at": "metadata.sources.0.updateTime",
+      "body": ["names.0.displayName", "emailAddresses.0.value"],
+      "container": "metadata.sources.0.type"
+    }
+  }
+}
+```
+
+A Google instance signs in only through [Environment setup](#environment-setup),
+on House's owner-authenticated page, so the owner's browser never has to reach
+this Environment. For each enabled service whose scopes the instance does not
+hold yet, the page links to Google's consent for exactly that service's scopes.
+Google then sends the browser to a `http://127.0.0.1:<port>/` address that
+nothing answers: the owner copies that whole address from the address bar and
+pastes it into the page. The Kit accepts it only when it carries the state its
+own consent issued, exchanges the code with its PKCE verifier and the built
+client, and stores the grant locally. An address that answers another consent,
+or a code Google refuses to exchange, fails the login and stores nothing; a
+declined consent cancels it. Grants already completed for earlier services stay.
+
+`kit source sign-in <instance>` signs in a custom connector instance through
+its own command, described below. It skips an instance whose local
+authorization is already valid and answers `ready`, `skipped`, or
+`needs_attention`. A Google instance refuses it as `kit_connector_login_guided`
+and names House setup.
+
+## Environment setup
+
+House requests one setup when it creates a managed Environment and again when
+its owner asks it to renew what the Environment holds. The Kit acts on the
+request it acquires, never on its own:
+
+```sh
+kit setup --house https://agents.house
+```
+
+`kit worker run` performs the same step at the start of a pass, before it
+hands out any work, so a managed Environment needs no terminal. The walk first
+prepares the absolute `/agents/house` base, then visits every declared agent
+CLI and then every connector instance, in configuration order:
+
+- an agent CLI is installed or kept at its served release as
+  [the declared agent CLIs](#the-declared-agent-clis) describe; a kind no
+  release could be installed for needs attention as `install_failed`;
+- a module whose own status check already answers signed in reports
+  `authenticated` to `/kit/logins/report`, which closes any renewal episode an
+  earlier attempt left open, and is `skipped`;
+- otherwise the Kit runs the module's guided login. It reports the login to
+  House as `renewal_required` for `/kit/logins/report`, which opens or returns
+  one renewal episode, and presents the provider's steps on House's
+  owner-authenticated page by holding `/kit/secret-input/<episode>` until the
+  owner submits. Collected values go only to the waiting sign-in process; the
+  Kit sends none of them, and none of the sign-in's output, to any other act. A
+  sign-in whose status check then answers signed in reports `authenticated`
+  and is `ready`;
+- a module without a guided route in this Kit, or one House does not advertise
+  (`kit_login_renewal_unsupported`), needs attention as `login_unavailable`
+  and opens no ceremony; a sign-in that exits without authenticating needs
+  attention as `login_failed`, and one that outlives its ten-minute bound as
+  `login_cancelled`. Either leaves its renewal episode open.
+
+One module's failure never stops the walk. The Kit reports what it now holds
+for every declared agent CLI and then the whole summary, one entry per module
+with its `category`, `name`, `status` and `reason`, to `/kit/setup/report`
+under the request it served, and releases its control lease. A cancelled
+command reports no partial summary and releases its lease once the walk has
+stopped.
+
+Each compiled adapter contract carries the guided route its provider's own
+headless sign-in offers, read from that command's output:
+
+- `codex-acp` runs Codex's device sign-in. The page links to the provider's
+  device page and shows the one-time code the command printed; the owner signs
+  in with ChatGPT there and enters the code, and the command completes on its
+  own. Nothing is written back to it.
+- `claude-agent-acp` runs Claude Code's sign-in. The page links to the authorize
+  page the command printed and collects the authentication code Claude shows
+  afterwards, which the Kit writes to that command alone. Claude Code answers a
+  code it refuses by asking for another, so the Kit ends that sign-in as soon as
+  the command prints `Invalid code.` and it needs attention as `login_failed`
+  rather than waiting out its ten-minute bound.
+- `grok-build` runs Grok Build's device sign-in. The page links to the Grok
+  device URL and shows the anti-phishing one-time code printed by the command;
+  authorization completes in the browser and no secret is written back to the
+  process.
+
+House offers only a route its provider evidence qualifies; one it does not
+advertise stays `login_unavailable`.
+
+## The custom connector
+
+Each custom service names one User-owned command. The Kit invokes it through an
+argument vector, never a shell, with an environment holding only `PATH`, the
+declared `environment` entries, and the resolved secrets. No House credential
+and no Kit User credential is ever placed there. The request carries no service
+name because the command is the service.
+
+Stdin carries one JSON request line:
+
+```json
+{ "contract": "2026-08-22", "instance": "acme", "cursor": null, "limit": 100 }
+```
+
+`cursor` is the opaque cursor the connector last returned, or `null` on the
+first capture and after a reset. Stdout carries NDJSON: zero or more `item`
+lines and at most one terminal `cursor` line.
+
+```
+{"type":"item","namespace":"acme/notes","native_object_id":"note-91","native_version":"7","observed_at":"2026-08-20T09:15:00.000Z","body":"the note","author":"ada","url":"https://acme.example/notes/91","attachments":[{"url":"https://acme.example/files/1","name":"plan.pdf"}]}
+{"type":"cursor","cursor":"page-2"}
+```
+
+`namespace`, `native_object_id`, `observed_at`, and `body` are required;
+`native_version`, `author`, `url`, and `attachments` are optional. There is no
+metadata bag, no executable field, and no embedded credential. A malformed line
+anywhere rejects the whole run: nothing is delivered and no checkpoint moves. A
+non-zero exit status, a timeout, or output beyond the bound rejects the run the
+same way.
+
+An attachment names exactly one target. `url` is a verbatim reference House never
+fetches. `file` names one work file the connector already acquired into this
+Environment and declares its exact version:
+
+```
+{"file":{"path":"/srv/acme/files/plan.pdf","bytes":48213,"sha256":"<hex>","media_type":"application/pdf"},"name":"plan.pdf"}
+```
+
+`path` is absolute and never leaves the installation; `bytes` and `sha256`
+describe the accepted version even when the connector could not download it,
+and `media_type` is optional. The Kit publishes that descriptor as a retained
+original on the Capture item, under an accepted version derived from the
+delivery key, the attachment position and the descriptor, so reoffering the same
+item always names the same version and a different descriptor under the same
+delivery key is House's delivery-key conflict.
+
+The Kit derives each item's delivery key from the instance, the service, the
+declared namespace, the native object id, and the native version when present.
+An object whose content changes without its native version changing keeps its
+key and is refused by House as a delivery-key conflict rather than silently
+overwriting the earlier Record.
+
+The same command owns its module authorization. `kit source sign-in` and the
+setup walk's status check send one JSON line
+with `action: "authorization"` and `mode: "status"` or `mode: "login"`; the
+command returns exactly one JSON object such as `{ "authorized": true }`.
+
+## The Worker runtime
+
+```sh
+kit worker run --house https://agents.house
+```
+
+Worker-runtime readiness validates the tmux this Kit declares support for,
+reopens any already-bound live WorkerSession, brings every declared agent CLI
+to its current release, starts each installed declared kind's command adapter
+long enough to verify its compiled contract and read the options its own
+session offers, reports what it holds to House, and only then acquires another
+WorkerRun. This Kit compiles three MVP adapter kinds: `codex-acp` contract `2` selects
+`@agentclientprotocol/codex-acp` `1.12.0` or a later `1.x` release, and
+`claude-agent-acp` contract `1` selects
+`@agentclientprotocol/claude-agent-acp` `0.79.0` or a later `0.x` release, while
+`grok-build` contract `1` selects `@xai-official/grok` `1.0.41` or a later
+`1.x` release and launches its native supervised ACP stdio mode. Each
+contract names the adapter package, the minimum release the `initialize` answer
+must reach, the executable it installs, the install recipe's own settings, the
+CLI's headless sign-in command and the command that answers whether it is
+signed in, the Agent Client Protocol version it speaks, its capability
+descriptor - the admitted `elicitation/create` field kinds, whether the adapter
+admits a declined form, and the stop-reason table of that adapter - whether the
+adapter loads a session, and the identifiers of the session configuration
+options the route's model and effort reach, or `null` for a field whose
+adapter offers no such option. An acquired route carrying any other descriptor for
+that kind refuses as `kit_adapter_contract_mismatch` before any spawn
+commitment.
+The `codex-acp` and `grok-build` contracts pin session loading and the
+`claude-agent-acp` contract does not. The same readiness asserts that the initialize exchange Kit
+wrote carried its elicitation declaration, because without it Claude Code
+disables its question tool and Codex answers nothing.
+An adapter whose running release is older than the contract's minimum, of
+another major, mismatched, or unresponsive refuses `kit worker run` within 10
+seconds per installed kind and names what it found, after the pass has reported
+what it holds, and every other Kit command keeps working.
+
+Once `initialize` passes, the Kit opens one Agent Client Protocol session with
+`session/new` in its own home directory and no MCP server, reads that session's
+configuration options, and stops the adapter; no prompt is sent. For each field
+the contract names, it takes the `select` option carrying that identifier and
+reports every value it offers with the display name the adapter gave it,
+flattening option groups and keeping nothing else. A field whose identifier the
+contract declares `null`, or whose option the session does not expose as a
+`select`, reports none. An adapter that refuses the session with the Agent
+Client Protocol's `auth_required` error, as `codex-acp` does before it is signed
+in, reports no options at all and its kind stays served. A session that fails
+for any other reason, does not open within 30 seconds, answers without a session
+id, or offers options the Kit cannot read as values and names reports no options
+either and refuses `kit worker run` as `kit_adapter_contract_mismatch`, like any
+other contract failure. The Kit keeps no catalogue of these values and no copy
+of them between passes: every report reads them from the adapter again.
+
+## Agent working directories
+
+Connecting an installation creates `/agents/house`, the absolute base every
+default Agent working directory lives under. Connecting again keeps whatever is
+already under it. An installation that cannot create that directory refuses
+with `kit_launch_base_unprepared` and names it, rather than substituting a
+home-relative location: the Environment owner creates it once and gives the
+installation write access to it.
+
+Every acquired WorkerRun carries its Agent's absolute working directory and its
+Agent id in its execution plan, and Kit launches the supervised session and its
+adapter in exactly that directory. Kit recognises the Agent's own default
+directory by exact equality with `/agents/house/<agent id>`, never by a
+directory's mere position beneath the base: a sibling directory one level
+inside `/agents/house` is somebody else's default or an owner's own workspace,
+never this Agent's. Every path that is not this exact equality, one deeper
+inside `/agents/house` included, must
+already exist in this Environment as a directory the installation can enter;
+Kit never creates or seeds it.
+
+When the Agent's own default directory is absent, Kit builds the starter set in
+a temporary directory beneath the base and renames it into place as one atomic
+step, so a partly seeded directory is never visible at the default path. Two
+concurrent first launches race that rename; the loser discards its temporary
+directory and uses the directory the winner put there, so the pair still leaves
+one complete directory and nothing partial. A present default directory -
+including one whose starter files the owner edited or removed - launches
+exactly as it is, and a deleted default directory is recreated with a fresh
+starter set on its next launch.
+
+The starter set is `AGENTS.md` with the single line ``The agents.house `house`
+CLI is available: run `house --help`.``, `CLAUDE.md` as a relative symbolic link to it, `.agents/skills/grilling/`
+vendored from [`mattpocock/skills`](https://github.com/mattpocock/skills)
+`skills/productivity/grilling` at a pinned commit with its MIT license and a
+provenance header naming that commit, and `.claude/skills` as a relative
+symbolic link to `.agents/skills`. Once seeded the files belong to the owner:
+Kit never syncs, refreshes, or restores them, and refreshing the vendored skill
+for new Agents is an ordinary Kit release that never touches an already seeded
+directory.
+
+A relative, missing, inaccessible, or non-directory working directory refuses
+with `kit_launch_directory_unavailable` before any provider process starts. Kit falls back to no other location - not the
+base, not `$HOUSE_KIT_HOME`, and not its own current directory - and neither
+connecting an installation nor launching a session moves, copies, overwrites,
+or removes anything a working directory holds.
+
+## The declared agent CLIs
+
+The Environment owner installs no adapter binary by hand. `kit agents update`
+and every `kit worker run` bring each declared kind to the latest release its
+contract serves - no older than the contract's minimum and inside that
+minimum's major - under
+`$HOUSE_KIT_HOME/agents/<kind>/releases/<release>/`, never touching what the
+owner installed globally, and an acquired route's command is that installed
+executable rather than a path anyone writes into `kit.json`.
+The resident Kit also listens for an `agents` availability pointer on its
+control stream. It reads the whole wanted list from House over HTTPS, removes
+Kit-owned CLI directories that are no longer wanted, installs newly wanted
+kinds, and reports its held state immediately, including while another Agent
+run remains active. A newly wanted kind that needs provider authorization uses
+the existing guided House login ceremony; Kit reports readiness again when it
+ends. A reconnect reads the list again, so a pointer missed during a stream
+outage changes no authority.
+Removal waits for an active worker pass or any unresolved live WorkerSession
+binding to stop using a CLI directory; the Kit keeps reporting that kind until
+it removes the directory.
+
+Every candidate release is proved before it serves: the Kit installs it beside
+the current release, runs the contract's own conformance check - the protocol's
+`initialize` against the minimum release, the protocol version and the
+capability descriptor the contract requires, and no provider-billed turn - and
+switches to it only on green. On red it keeps the release it already has,
+removes the candidate, and holds that kind with the refused release named in
+its report until a newer candidate appears. Non-major releases advance this way
+on their own; a major release waits for a contract revision. The candidate
+check runs at most every six hours per kind, and `kit agents update` runs it at
+once. A kind whose release lookup or installation fails keeps the release it
+already has, or none, and is named with its failure; the other kinds go on,
+`kit agents update` then exits non-zero, and a worker pass verifies and serves only the kinds with an installed release, so
+one CLI the Kit could not install leaves only that kind's work unavailable.
+
+The install recipe carries what the CLI needs beside its binary: for
+`codex-acp` the Kit enables user-input questions in Codex's own configuration
+document, because a Codex that disables them raises no `elicitation/create` and
+answers nothing, and the Kit adds that setting only where the owner declared
+none.
+
+`kit agents sign-in <kind>` runs that CLI's own headless sign-in command in the
+terminal it was started from, so the owner only completes it; House opens that
+terminal and runs nothing itself. Both commands hold one control lease, release
+it once they are done, and report to House afterwards what
+this Environment now holds: per declared kind its compiled contract version,
+the installed release or none, whether the contract's native readiness evidence
+shows a signed-in provider, the candidate release a red conformance check refused, and the model and
+effort options the installed adapter's own session offered, or `null` when no
+release is installed or its session did not open. Every report, the worker pass's
+and `kit setup`'s included, reads those options the same way and goes to
+`POST /kit/agents/report` with one entry per declared kind:
+
+```json
+{"agents": [{"kind": "claude-agent-acp", "contract_version": "1", "release": "0.81.2",
+  "signed_in": true, "hold": null,
+  "options": {"model": [{"value": "haiku", "name": "Haiku 4.5"}], "effort": []}}]}
+```
+
+House knows about an agent CLI only
+what this Kit reported: it probes no binary, version or login of its own, and
+it refuses an Agent, an Agent Session and Agent-runtime acquisition for a kind
+this Environment does not declare or this Kit has not reported installed and
+signed in.
+
+This installation owns one private tmux server namespace derived from
+`$HOUSE_KIT_HOME`, so House never joins, lists, or destroys an ordinary tmux
+session. Each acquired WorkerRun becomes one WorkerSession in one opaque exact
+tmux session of that namespace, created from a Kit-owned configuration that
+disables terminal retention. tmux owns the terminal lifecycle and nothing else:
+the pane, its scrollback, and anything the adapter writes to its own stderr are
+never read, stored, parsed, or answered, and no key is ever injected into a
+pane.
+
+Inside that session the Kit starts the launcher for the acquired route's
+declared command adapter and hands it, over a Kit-private local channel, the
+canonical request House gave the Kit and the adapter argument vector. Routine assignments carry their Routine Request.
+Direct conversation assignments carry the sealed turn and its ordered messages,
+and the Kit seals the reply itself on its own ingress.
+An Agent resolves exactly one Execution route, so the acquisition envelope's
+execution plan carries one `route` object and this Kit selects, orders, and
+hands off nothing. The Kit launches that route as House admitted it and keeps
+no local copy of it: an acquired route naming a kind `agents` does not declare
+refuses as `kit_agent_undeclared`, and one whose kind has no installed release
+as `kit_agent_not_installed`. The route names `adapter.kind` and
+`adapter.contract_version`. The installed release of that kind plus the route's
+`arguments` are the exact argument vector, so no route names a binary path.
+The route's `model` and its `effort` or `null` are House-visible route facts in
+the CLI's own vocabulary, which House stores as given and never validates; the
+Kit hands them to the adapter at session start as its contract names, and a
+value the CLI refuses fails the attempt with the CLI's own cause as
+`kit_adapter_failed`. A route whose `effort` is `null` sets no effort, so the
+CLI's own default effort applies and a model that offers no effort option
+starts.
+The adapter inherits only `PATH` and `HOME`, so the provider's own local
+authorization stays in the Environment where its CLI already keeps it. The Kit
+adds the Session's `house` CLI in front of that `PATH` and names the Session's
+bridge socket and nonce in `HOUSE_KIT_BRIDGE` and `HOUSE_KIT_BRIDGE_NONCE`.
+
+The launcher speaks the Agent Client Protocol through the protocol's official
+TypeScript SDK, `@agentclientprotocol/sdk`, as this Kit's one protocol client;
+the Kit frames no protocol JSON-RPC of its own. It opens the session with `session/new`
+in the Environment's working directory with no MCP server, or reloads the
+retained one with `session/load`, then sets the
+route's model, and its effort when the route names one, through the protocol's
+`session/set_config_option` with the option identifiers the adapter contract
+names: `model` and
+`reasoning_effort` for `codex-acp`, `model` and `effort` for
+`claude-agent-acp`. Neither pinned adapter reads a model or effort flag of its
+own. It carries the turn with one `session/prompt`, and maps that
+prompt's stop reason through the contract's own table to one of four turn
+outcomes: completed, interrupted, refused by the provider, or exhausted. A stop
+reason the contract does not name, including a vendor-specific one a different
+contract names, fails the turn as `kit_adapter_contract_mismatch` rather than
+being guessed. It sends the request
+as the first prompt block, followed by current House guidance fetched through
+the Run connection. Missing or unreadable guidance refuses the turn; the
+launcher does not copy the private Routine instruction into the acquisition
+request. It forwards only adapter-classified User-visible assistant
+text back over the local channel, and leaves reasoning, tool traces, and
+terminal output where they are. The supervised process's own House calls travel
+that same channel through the `house` CLI. The Kit holds the WorkerRunToken, replaces it in place when
+it nears expiry without the child noticing, attaches a bridge-generated UUIDv7
+to every Session mutation it forwards, and never places a House
+credential in any child environment.
+
+The Kit is the single source of assistant text: it observes the adapter, streams
+what it has seen so far, and seals the turn itself. No Agent is asked to report
+text a deterministic observer already sees, and no agent-facing tool admits final
+text.
+
+While the adapter generates, the Kit posts the whole User-visible assistant text
+of the turn so far to `sessions/<session>/drafts` as an ephemeral draft. Only
+adapter-classified assistant message text enters that stream; reasoning, tool
+calls, plans, and terminal output never do. The Kit maps the structure it can
+read in that text - paragraphs, headings, fenced code, ordered and unordered
+lists, pipe tables, and `$$` formulas - into House's admitted blocks, and leaves
+anything it did not parse as the paragraph it observed. It invents no structure
+and renders nothing.
+
+The Kit coalesces and paces that stream rather than mirroring every chunk. It
+sends the first observed view at once, then at most one view every 500
+milliseconds, and one more the moment the adapter completes a message; one call
+is in flight at a time, so a newer view replaces the view it overtook and the
+view observed last is the view House sees last. A view whose text exceeds
+House's 4096-byte bound is not sent. A draft persists nowhere - not in this
+Kit's local state, not as House history - is never retried, and can neither
+delay nor prove turn completion: a refused, lost, or overtaken draft changes no
+Run, WorkerSession, or delivery state. Ending the stream waits for no draft the
+transport is still holding, so a slow or unanswered draft call cannot delay the
+seal or the Run behind it.
+
+When the adapter completes the turn, the Kit seals it with one
+`sessions/<session>/assistant-messages` call carrying the same blocks and a
+UUIDv7 `operation_id`. The exact request - that identity and those blocks - is
+written into the WorkerSession binding before the call leaves, so a recovered
+call returns the outcome House recorded and never seals a turn twice, and
+House's answer names the turn it closed and the delivery it queued. An answer
+the Kit never received leaves the Run unsettled with the request retained: the
+next `kit worker run` replays exactly that operation and those blocks before
+settling anything, rather than reporting a failure it cannot prove. A refusal
+House did decide is the Run's reported failure.
+
+That seal is the one durable record of the turn, and only a seal House accepted
+completes a turn: the Kit reports whole-turn completion to House after the seal
+succeeds and never otherwise. A turn whose adapter produced no User-visible text
+seals nothing and claims no completed turn; the Run's own terminal outcome still
+follows what the adapter reported.
+
+The Agent reaches House only through the `house` CLI. Its verbs are the Tools
+House lists to the Session, and its help is House's own: `house --help` prints
+each listed Tool's name and description, and `house <verb> --help` prints that
+Tool's description and input schema, all read from House's `tools/list` at the
+call, so a catalogue change needs no Kit release. `house <verb>
+'<arguments as one JSON object>'` calls that Tool, or `house <verb> -` with the
+object on standard input for arguments longer than one command-line argument
+holds. It prints House's text answer, or a refusal on standard error with a
+nonzero exit status. The CLI holds
+no credential: it calls over its Session's bridge, which attaches the Session
+credential and refuses a caller without that Session's nonce as
+`kit_bridge_unauthorized`. House network calls use only the selected
+`2026-07-28` profile.
+
+Two verbs name files on the Session's own computer: `upload_attachment` takes
+one `path`, and `append_record` takes `attachments` as local paths. The CLI
+resolves each path against its working directory. The bridge reads each regular
+file, computes its size and SHA-256 and the media type an image's leading bytes
+show, declares them beside the call, and uploads the exact bytes through the
+one-use grant House answers before the call completes, so the answer carries the
+attachment's `at_` reference. `append_record` uploads every file into its Room
+first and names their references in the Record; a file that cannot be read or
+saved appends nothing. The bridge reads House's YAML answers to
+`upload_attachment`. A Room or `/private` upload ends at the byte upload rather
+than at a House answer, so the bridge prints that saved answer in the same YAML;
+every other answer passes through as House wrote it. With `conversation: true`
+the file becomes the owner's conversation original, and the bridge calls again
+and waits for House's delivery outcome. House derives the presentation from the
+declared media type: an image is uploaded inline beside a link to the unmodified
+original, and every other file is offered as that link alone.
+
+The bridge retains the exact pending House request in memory before transfer.
+Within the same live Kit and supervised WorkerSession, a lost response or
+infrastructure failure resends that request with the same identifier. A local
+socket reconnect delivers the retained outcome to the process.
+A second deliberate call gets a new identifier; read-only calls carry none.
+House refusals pass through to the CLI without automatic resend. [R193](https://github.com/agentshouse/core/blob/main/docs/concept/implementation/08-routine-requests-human-notifications-and-workers.md#r193)
+owns recovery authority, lifetime, and refusal semantics.
+
+The launcher speaks only what the adapter contract fixes for this build. Every
+session initializes with the same fixed client capabilities: no file-system
+methods, no terminal methods, and elicitation in form mode and not in URL mode.
+It offers the adapter no filesystem or terminal surface of its own, so an adapter
+that needs a decision the Kit cannot carry fails its turn instead of receiving a
+guessed answer. Execution permission is the one decision the Environment already
+settled: `kit.json` declares the Environment's `execution_authority` as `allow`
+or `refuse`, and the launcher answers every adapter permission request with that
+declared outcome and nothing else. The authority is a local Environment fact - it never reaches
+House, and no permission request is ever projected to a human.
+
+A task question is the decision the Environment cannot settle, so the launcher
+carries it to the owner instead of answering it. The Interaction is the
+protocol's own form end to end: an adapter's `elicitation/create` request in
+form mode reaches House's interaction act as its `message` and its
+`requested_schema`, unchanged in meaning, with the exact correlation of the
+provider turn and of the adapter request that raised it. House alone judges
+whether the schema is inside the flat subset it can ask; a form it admits as
+unsupported, and a URL-mode request the Kit never forwards, cancel the
+adapter's request with the protocol's `cancel` and ask the owner nothing.
+
+Nothing of an adapter's native wire crosses: the Kit strips every native
+`_meta` from the request, the schema, its properties and their options, and
+gives a property the adapter left untitled its own name as title. Two facts
+cross as House-namespaced marks instead. The batch carries
+`_meta["agents.house/secret"]` when the adapter classifies the request as
+secret in its own meta, as `codex-acp` does with `isSecret`; House records it
+as unsupported and raises an interrupt rather than a card, so no secret prompt
+is projected to a human and no secret answer travels back through House. A
+choice carries `_meta["agents.house/free-text"]` when the adapter's own
+convention admits the owner's words beside the listed options:
+`claude-agent-acp` pairs a question with a `_askUserQuestionCustomAnswer`
+companion field, and `codex-acp` pairs it with a `"None of the above"` option
+and a `<id>_note` field tagged `user_note`. The companion field and the
+synthetic option never reach House.
+
+The owner's answer arrives as the `answer` command carrying the protocol's own
+response, `accept` with content keyed by property name or `decline` for the
+whole form, and is applied to that exact pending request; an answer naming
+another turn or another correlation has no effect, so a stale or cross-Session
+answer cannot reach a live adapter. A typed answer to a free-text choice goes
+back through the adapter's own convention: into the companion field for
+`claude-agent-acp`, and as `"None of the above"` with the typed text in the note
+field for `codex-acp`. The turn waits on the adapter's own request while the
+owner decides, and the Kit reports what became of each Interaction, so a
+Session that ends with one outstanding expires it instead of leaving it live.
+
+Before new execution, `kit worker run` reconciles House-authorized inbound cache
+cleanup and materializes every pending conversation file House offers, ten at a
+time, under `$HOUSE_KIT_HOME/conversation-inbound/<run>/<attachment>/<name>`.
+House seals due input itself. The Kit uses the existing Environment lease and
+byte endpoint, limits each file to 32 MiB, and reports materialization after
+receiving a complete byte stream, validating any reported size, and writing the
+file. A lost acknowledgement preserves the completed local file for House's
+idempotent admission and later cleanup. Failed files remain pending; House's
+all-files-ready gate keeps their turn unprocessed.
+The provider receives absolute local paths beside the owning messages, both in
+its initial prompt and in `session_get_request`. The cache persists across
+turns; only House-authorized terminal Run cleanup removes its Run directory.
+
+The accepted attachment's retained original is separate from that cache. The Kit
+records a local note for the attachment before it acknowledges materialization,
+then saves the exact bytes it received through House's conversation-original
+door, naming only the attachment; a download that fails reports
+`source_unavailable` for the same version.
+
+A save that fails leaves one note in `state/conversation-originals/` naming the
+attachment, its Run, the local file and the descriptor it declared. Each
+later `kit worker run` retries it from that file without materializing or
+acknowledging anything again, and reports `source_unavailable` when
+the file is gone or changed rather than saving different bytes. While a
+WorkerSession stays supervised the same retry runs at the heartbeat interval. The note leaves once
+House records the save, once House answers that the Run is over, or when House
+authorizes that Run's cache cleanup; House accepts no save for a Run that has
+settled, so an unsaved original keeps its failed outcome from then on. The owner
+reads every saved original through House afterwards, whether or not this
+Environment still exists. `kit worker run` prints every conversation original
+outcome it handled, and exits non-zero while any of them is unsaved.
+
+One `kit worker run` then takes one House-authorized resumption, or otherwise
+acquires one waiting Run, and supervises exactly that WorkerSession. A resumed
+conversation loads its retained native provider session through ACP
+`session/load`, receives the current input from House through
+`session_get_request`, and executes one turn. Historical output replayed during
+loading is not emitted as new assistant output. Missing or rejected provider
+continuation never starts a replacement provider conversation in the same Run.
+
+Continuation is per adapter. A contract that pins session loading retains the
+adapter's opaque session handle between turns and resumes through it, as
+`codex-acp` and `grok-build` do. A contract without it, as `claude-agent-acp`, retains nothing:
+its turn reports no provider continuation, the Agent Session ends with the
+reported cause `kit_provider_continuation_unavailable`, and the owner starts the
+next one.
+
+Between turns, Kit retains the opaque provider session identifier and the Run's
+Worker, working directory, and route references in an owner-only local record.
+The record carries no transcript or Session credential and grants no authority:
+House must authorize each successor WorkerSession. A reported terminal state and
+owner stops remove the record. [R199](https://github.com/agentshouse/core/blob/main/docs/concept/implementation/08-routine-requests-human-notifications-and-workers.md#r199)
+owns conversation continuity.
+
+Launcher exit is the terminal process observation. The Kit closes the local
+channel, grants the launcher a fixed local exit grace, destroys the exact tmux
+session if it is still there, and then reports one stopped Session at
+`POST /kit/sessions/:session/stopped` and the adapter's own continuation facts at
+`POST /kit/sessions/:session/continuation`, whose body is exactly
+`{"provider_continuation": <bool>, "provider_capacity_exhausted": <bool>}`. No
+adapter-supplied reset instant and no handoff availability is sent, and nothing
+schedules a wake.
+
+Kit, not the Agent, then reports the terminal state the execution reached at
+`POST /kit/runs/:run/outcome`. No agent-facing tool posts it, and settling writes
+no Record, Posting or Capture by itself: whatever the instruction wanted written
+is written through the ordinary authorized Run mutations first. The body is
+`{"operation_id": <uuidv7>, "outcome": "completed"}` or
+`{"operation_id": <uuidv7>, "outcome": "failed", "cause": "<1-200 chars>"}`, and
+the reported cause is exactly what the adapter gave. A finished turn that needed
+no further Provider continuation is `completed`. A known execution failure, a
+provider capacity exhaustion, a positively lost Provider continuation, and a
+rejected native resume command are each `failed` with their own cause; House
+notifies the owner and nothing is retried. A confirmed-stopped Session whose
+Provider continuation remains available reports no terminal state at all and
+leaves the Run active for an owner-originated resumption.
+
+The Kit decides that terminal state once, records it beside its stable operation
+identity before it reports it, and reports it from that record. A Run with a
+supervised session records it in that session's durable local binding; a Run
+whose terminal state was decided without one — a resume command this Kit rejects
+because it retains no Provider continuation for the Run, or an acquired Run it
+refuses before any provider process starts, which it commits and fails with the
+refusal as the cause so no Run stays acquired behind it — records it in a
+durable local settlement note of its own, named by the Run. A lost response is recovered by reporting that
+identical body under the same operation identity on the next `kit worker run`;
+House answers the committed settlement verbatim and the Agent is never executed
+again. A Run House has already settled answers `worker_run_settled`, which the
+Kit accepts as settled and drops the record for.
+
+Every other refusal leaves that record exactly as it is. The Run stays bound to
+this installation, `kit worker run` names the refusal House answered with and
+exits non-zero, and the same decided body is reported again before anything is
+acquired. Nothing is dropped locally that House did not accept, and a refused
+report is never presented to the owner as a delivered one.
+
+While a WorkerSession is supervised the Kit keeps one durable local binding
+naming this installation, the WorkerRun, the WorkerSession, the exact tmux
+session, and the local channel that reaches it. The binding carries no terminal
+content, no prompt, and no resolved secret, and Session authority is always
+reissued by House rather than recovered from disk. It is evidence for
+reconciliation, never permission to resume or recreate work, and nothing keeps
+it once House has answered for the Run: a settled terminal state, a confirmed
+owner stop, and a retained Provider continuation each drop it.
+
+A restarted `kit worker run` reconciles the records it kept before it acquires
+anything new. It reports every retained settlement note first, because those
+Runs have no session left to reconcile, and drops each note House accepts or
+already settled. It next consumes the durable commands House holds for this
+Environment, so a requested owner stop ends the exact tmux session before any
+local channel reopens. It then considers only sessions of its own namespace
+whose binding is complete, and never lists unknown sessions, scans host
+processes, searches another namespace, or adopts an arbitrary process. A session
+that is already gone is confirmed gone, reported as one stopped Session with no
+Provider continuation, and settled as a terminal execution failure. A session
+that is still running is restored only after House
+positively replaces the Session authority for the same Run and Session; the Kit
+then reconnects the typed adapter channel, refreshes the started observation,
+and supervises that session to settlement instead of acquiring another Run. An
+explicit House refusal destroys the stale tmux session and exposes no channel.
+House that cannot be reached leaves the binding and the session exactly as they
+are, invents no stopped, active, or authorized state, and acquires nothing.
+
+A restore of House's database starts a new log epoch. Until this Environment
+has reported in it, House refuses every act that touches a Run, acquisition and
+lease release included, as `epoch_report_required` naming the epoch. The first
+such refusal ends whatever the pass was doing. One raised inside a supervised
+Run's bridge, while it admits or settles a question, streams a draft, or
+replaces Session authority for a forwarded call, never becomes an answer to the
+Agent: it ends the bridge and the pass at once. The Kit then reports, under the
+lease it holds and at `POST /kit/sessions/report`, every Run it holds a spawn
+commitment or a terminal outcome for: each retained binding, settlement note,
+and Provider continuation, as `{"session": "<run>", "outcome": null}` while its
+process runs, while it holds only its continuation, or while its outcome is
+unknown, or with the held outcome it would have reported at
+`POST /kit/runs/:run/outcome`, `completed` or `failed` with its cause. One
+report carries at most 256 Runs, so the Kit sends as many as it needs, all
+before it acquires anything. House settles every reported Run and never offers
+it again, so once it has answered every report the Kit destroys each reported
+tmux session still running, drops each reported Run's binding, settlement note,
+and retained Provider continuation, and runs the pass again from its start. A
+refused act is never a Run failure, nothing is acquired in the new epoch before
+the report, and a refusal that follows the report ends the command naming it.
+
+The launcher inside the supervised session outlives the Kit process that started
+it. Its local channel reconnects to the same socket with a bounded backoff and
+announces that its adapter session already exists, so a restored bridge
+acknowledges the resumption instead of starting a second turn and the supervised
+process never sees a second request. A call already transferred when the Kit
+process ends is never automatically replayed by its successor, even when the
+same local channel reopens. Pending mutation requests and identifiers are not
+written into the durable binding. Reconciliation must obtain current House
+authority before the live process can make further calls.
+
+An owner stop requested through House reaches this Kit as a durable command,
+both at startup and while a Session is supervised. The Kit destroys the exact
+tmux session, confirms that it is gone, and reports the stopped Session. It
+reports no continuation for a Run stopped by its owner and never reopens the
+local channel for that Session.
+
+```sh
+kit worker attach            # the one supervised session
+kit worker attach <session>  # the exact session
+```
+
+Attachment is a read-only diagnostic for the Environment owner. It reaches only
+the exact tmux session of a live binding in this installation's namespace, gives
+the Worker no input, makes no House call, causes no lifecycle transition, and
+leaves the namespace configuration and its disabled terminal retention as they
+are. Once the Session has settled or its tmux session is gone, attaching is
+refused and names why.
+
+## Paired proof
+
+Paired installed-CLI proof against the merged House producer is a labelled
+validation build, not an npm release. From Linux Compose:
+
+```sh
+docker build -f test/pair/producer.dockerfile -t kit-original-pair:latest .
+HOUSE_CORE_ROOT=<agents.house checkout> \
+  docker compose -f test/pair/compose.yaml up --abort-on-container-exit --force-recreate producer
+```
+
+It boots the real producer against a real PostgreSQL, installs the exact
+candidate package, and runs `test/pair/*.vitest.ts`: the attachment doors,
+a Source adapter retaining a declared file into Rooms of two owners, and an
+installed Worker retaining an incoming attachment through failure, retry, Run
+settlement and cache disposal. `KIT_PAIR_SPECS`
+names the specs to run, and `HOUSE_CORE_REVISION` and `KIT_REVISION` are copied
+into the evidence each spec writes under `tmp/delivery-evidence/`.
+
+## Capturing
+
+```sh
+kit source capture acme --house https://agents.house        # every declared service
+kit source capture acme notes --house https://agents.house  # one service
+```
+
+Each run reads the checkpoint, acquires one bounded page, submits one batch,
+and advances the checkpoint only once every item in that batch is accepted or
+an idempotent duplicate at the House door. Every batch names the service's exact
+Source reference and its complete Room destination set, so House admits all of
+them or none: one destination the delivering User cannot currently write refuses
+the whole publication before any content changes. A refused item leaves the
+checkpoint where it was, so the next run reoffers the whole batch and converges
+on the door's own deduplication. When House stops a batch early, its answer
+settles only the prefix it reached, and the unsettled tail is reoffered with the
+rest. The loop repeats while the connector still returns items and no Room
+destination is blocked, and every run ends by writing the service's health into
+this installation's own state. House holds no preset, service, route, checkpoint
+or health of yours.
+
+A Capture item that declares a `file` attachment answers one Record per Room
+destination: Rooms of one owner share that owner's Record, and a Room of another
+owner holds its own Record of the same delivery. The Kit records one retained
+reference for every destination Room and attachment in
+`state/<instance>/originals/<service>.json` before it saves anything, then
+saves that batch's references through House's captured-original door before it
+asks the connector for the next page: it reads the declared path, and uploads
+the bytes only when they still match the declared descriptor. References still
+outstanding from earlier runs are retried once the run's pages are delivered.
+A missing or changed file reports `source_unavailable` instead, so House never
+receives a substitute version. House, not the Kit, chooses where each Room
+owner's copy is kept. Every run prints each reference's save outcome beside its
+Room and Record and exits non-zero while any stays unsaved; acquisition health
+stays about acquisition, so a failed save never changes it.
+
+```sh
+kit source retry-files acme --house https://agents.house        # every declared service
+kit source retry-files acme notes --house https://agents.house  # one service
+```
+
+`retry-files` saves only the references still outstanding. It runs no connector,
+submits no Capture, moves no checkpoint, and keeps each reference's Record and
+accepted version; with nothing outstanding it contacts no House at all. A saved
+reference, or one whose Posting House no longer holds, leaves the local state. A
+Room whose write authority is gone answers `room_not_found` and stays outstanding
+until that authority returns.
+
+```sh
+kit source status acme        # every declared service
+kit source status acme notes  # one service
+```
+
+`kit source status` reads only local state: the current health and its exact
+category, the stored cursor, every open coverage gap with the recovery reference
+House returned for it, the items this installation dropped permanently, and the
+retained references still waiting to be saved.
+
+Every command that changes or reads installation state takes this
+installation's exclusive Environment control lease for the length of its run
+and renews it before it expires, so two Kit commands never work against the
+same installation at once. A command that ends, or is interrupted once its work
+has stopped, releases that exact lease so the next command acquires at once; a
+refused command leaves it to expire. A `kit login` credential is presented only to take
+that lease.
+
+While `kit resident` holds that lease, a command runs through it instead: the
+command presents no credential, the resident confirms its current lease with
+House and sends the command's House requests under it, an interrupted command
+cancels its request there, and the lease stays held when the command ends. The
+resident serves one such command at a time and refuses another with
+`environment_control_lease_active`, so two commands still never work at once.
+A resident whose lease House refuses answers the command with that refusal; the
+command never acquires a lease of its own while a resident serves it.
+
+Interrupting the command cancels the running connector without advancing the
+checkpoint.
+
+## Repository capture
+
+Publish one local Git checkout as a Repository Source without giving House any
+Git credential:
+
+```sh
+kit repository capture /srv/acme \
+  --room work-room \
+  --source-handle acme-repository \
+  --house https://agents.house
+```
+
+The command runs ordinary `git pull` in the checkout with the local User's Git
+configuration, credential helper, and SSH agent. After pull succeeds, Kit asks
+Git for tracked files plus untracked non-ignored files, hashes each selected
+file, and opens a Publication by posting that manifest - every selected path
+with its content fingerprint and byte length - to the authenticated Kit door.
+Git remains the only ignore owner.
+
+House answers the Publication reference, the paths it needs, and the chunk
+bound it accepts. Kit delivers only those paths, in House's order, in chunks
+under that bound, streaming each file from disk at delivery time; it carries no
+bound, no delta, no counter and no retained archive of its own. House owns
+every tombstone, orders the Publication, and completes it in the request that
+leaves no needed path outstanding.
+
+A file whose bytes disagree with the manifest House holds is refused as that
+item and the rest of the chunk stands. When a delivery round ends with refused
+items and the Publication is still active, Kit opens a new manifest of the
+current checkout and delivers again, at most three manifests per run. An
+interrupted run is never resumed: the next run opens a new manifest and House
+answers with what is still needed. The command reports the Publication
+reference, the paths delivered, the items refused and the ending.
+
+## Explicit synchronization
+
+Beside the reconciling Working Copy, Kit has one explicit synchronization mode.
+It selects prefixes over the User root, materializes them into a named local
+directory, enumerates whole content and removals after the recorded positions,
+and submits a resolved exact-base change set the caller prepared. Kit does no
+local reconciliation. The mode shares no Working Copy manifest, never infers a
+removal from a locally absent file, and writes authored mutations only within
+House's declared write scopes: a selected Room's Library and, where granted,
+`ROOM.md`. `/private` selects the Private Room by its Room reference, records an independent Room
+position, and keeps its `agents/` cards and Room-specific private `AGENTS.md`
+beside `library/**`.
+
+```sh
+kit sync bootstrap ./replica \
+  --house https://agents.house \
+  --prefix /rooms/work/library \
+  --prefix /rooms/work/capture \
+  --prefix /private/library
+kit sync pull ./replica --house https://agents.house
+kit sync submit ./replica --house https://agents.house --changes ./changes.json
+kit sync rebootstrap ./replica --house https://agents.house
+```
+
+`bootstrap` writes `ROOM.md`, Library text, House-derived projections, and
+Capture text with its provenance sidecar, and records one position per selected
+authority from the bundle, with the log epoch House issued it in, together with
+the positive operation scopes House declared for it: `read`, `sync`, `write`,
+and `delete`, each a list of paths relative to the authority under which that
+operation is admitted. Managed replication needs `read` plus `sync` on a Room;
+a Room the User can only read answers `bootstrap`, `pull`, and `rebootstrap`
+with `operation_denied`. Generated `_provenance` files delivered beside authored
+Library paths are House metadata, not authored Library documents. `pull` presents
+each recorded position with its log epoch, applies each enumerated path's whole
+content or removal, and advances those positions. A position older than House's
+declared retention, or one of a log epoch before House's database was restored,
+is reported as `position_expired` with rematerialization as the remedy; only
+`rebootstrap` rebuilds the directory.
+
+`submit` sends field, section, and preamble operations with that value's prior
+content as base, and whole-file, rename, and removal operations with the file
+revision. A rename of a populated directory instead carries a `base` map from
+every relative member path to its exact revision, such as
+`{"plan.md": "<revision>", "deep/log.md": "<revision>"}`, and House refuses it
+unless the map names exactly the directory's current members at their current
+revisions. Kit admits the rename at its source and destination and each named
+member at both, as House does.
+House alone validates the resulting Library: a batch it refuses answers with
+House's own file path, field, rule, and version. A refusal is reported with the
+current material House returned and the local directory is left for the caller.
+An acceptance updates the recorded position, its log epoch, and the affected
+files from the returned final content.
+
+Pending submissions are written before transfer. A lost response, reconnect, or
+lease renewal recovers that exact request under the same identifier. A domain
+refusal is reported without automatic retry and without minting a replacement
+identifier. A second deliberate submit is a new identifier. After a restore of
+House's database, a request House holds no receipt for and whose identifier
+dates earlier than five minutes after the new log epoch began is answered
+`position_expired`: it wrote nothing and never will under that identifier, so
+the Kit drops it like any other refusal, `rebootstrap` rebuilds the directory,
+and a change still wanted is a new deliberate submit against the rebuilt bases.
+Once House has answered any request for a replica `position_expired`, the
+replica refuses `submit` as `position_expired` until `rebootstrap` rebuilds it.
+`rebootstrap` drops a submission still pending against the directory it
+replaces.
+
+`--changes` names a JSON array of exact-base operations, or an object with a
+`changes` array. Omitting it derives field, section, preamble, create, and whole-file
+operations from local writable files against the last confirmed snapshot and
+still never infers a removal. A local edit of a selected protected path is
+refused before House is contacted as `protected_path`; a change outside the
+authority's `write` scope, or a removal outside its `delete` scope, is refused
+before House is contacted as `operation_denied`, the same code House answers
+for a batch that reaches it.
+
+## Attachments
+
+Upload one local file as an attachment to a Room or to your Private Room. Name
+the place explicitly. Kit sends the descriptor and the selected bytes; it does
+not scan a directory, convert a URL, or attach sibling files, credentials, or
+absolute paths.
+
+```sh
+kit attachment upload ./notes.bin \
+  --house https://agents.house \
+  --room room:work \
+  --media-type application/pdf
+
+kit attachment upload ./notes.bin \
+  --house https://agents.house \
+  --private
+
+kit attachment get \
+  --house https://agents.house \
+  --attachment at_1x.q \
+  --room room:work \
+  --output ./notes.bin
+```
+
+`--room` and `--private` are mutually exclusive and one is required; `--name`
+defaults to the file's base name. The upload prints the attachment reference
+(`at_…`) House answered. That reference is what text links to: an attachment is
+meaningful only because a document links it, and House records those links from
+the accepted text. Retrying the same file after a lost response or failed upload
+reuses the stored version under the identical descriptor, so it completes the
+same attachment instead of creating a second one; uploading the same file to the
+same place again answers that same attachment. A changed file is a new
+attachment. HTTP 200 is not retention: only `save.status: saved` plus an
+independent download whose length and SHA-256 match counts. A failed local read
+or failed House save is not reported as saved. Transfer uses the current control
+lease and the one reusable byte client; the durable credential is presented only
+to `POST /kit/lease`. Sync commands do not fetch attachment bytes; Source and
+Worker retention save through the same byte client.
+
+The same paired installed-CLI proof covers these doors; see
+[Paired proof](#paired-proof) for the command that runs it.
+
+## Persistent container Environments
+
+An Always-on Linux host can run the persistent container Environments its owner
+creates in House. House owns the target: which host, the workspace name, and the
+CPU, memory and persistent-disk ceilings. This Kit owns the local lifecycle and
+reports only what it proved.
+
+The supported configuration is one Linux host with
+
+- cgroup v2 delegating the `cpu` and `memory` controllers, read from
+  `/sys/fs/cgroup/cgroup.controllers`;
+- a reachable Docker Engine daemon;
+- `/dev/loop-control` present, so a workspace disk can carry an enforced size;
+- `host.workspace` pointing at a directory this Kit may create workspaces under;
+- `host.image` naming an image that carries Node, this Kit, `mkfs.ext4` and
+  `nsenter`, and whose own entrypoint starts `kit worker run` from
+  `HOUSE_KIT_HOME`.
+
+Any missing prerequisite refuses the create before House ever presents the
+workspace as constrained, naming the exact missing piece.
+
+```sh
+kit workspace host --house https://agents.house
+```
+
+The command acquires this host's workspace work under its Environment control
+lease and settles each operation with what it observed:
+
+- **create** formats one ext4 image of exactly the configured disk ceiling,
+  mounts it as the workspace's only writable filesystem, writes that
+  Environment's own Kit credential and a `kit.json` declaring the selected agent
+  CLIs with `execution_authority` `allow` inside it, since nobody holds a
+  terminal there to answer otherwise, and creates the container with
+  `--cpus`, `--memory` and `--memory-swap` at the configured ceilings. The
+  workspace is reported `stopped` with the runtime and the enforcement it
+  proved. This host's own credential never enters the workspace: the only
+  credential written there belongs to the Environment running inside it.
+- **start** mounts the workspace disk if the host rebooted, refuses when
+  starting would leave less than the host reserve, starts the container, and
+  reports `ready` only after the exact workspace proved it accepts execution.
+- **stop** stops the container and keeps the disk mounted, so ordinary files,
+  installed tools and login state survive to the next start.
+- **delete** removes that exact container, unmounts that exact workspace disk and
+  removes that exact directory. No other workspace, and nothing else on this
+  host, is touched.
+
+Every operation names one workspace this Kit created. A workspace the runtime no
+longer has is reported `absent` rather than recreated, so House ends the
+Environment visibly instead of inventing a process observation. On every pass
+this Kit reconciles its own labelled containers against the exact inventory
+House authorizes: a managed workspace House no longer authorizes to run is
+stopped, and a container this Kit did not create is never adopted, started or
+removed.
+
+Ceilings are shared ceilings. The ceilings configured across one host may exceed
+that host, nothing is reserved for any workspace, and no workspace is promised
+its maximum while another one runs.
+
+## The Telegram gateway
+
+House can project one owner's conversations through that owner's own Telegram
+bot. In Kit mode the BotFather token stays in one installed Environment, and
+this Kit is the only thing that calls the Bot API. House never receives the
+token: it appears in no request body, no refusal and no printed summary.
+
+Exactly one Environment may be the gateway for one bot. House records that
+binding when the gateway registers, and refuses a second Environment claiming
+the same bot. Worker Environments stay unchanged: they still acquire Runs and
+materialize inbound conversation files.
+The gateway never runs a Worker's provider and a Worker never holds the token;
+the two exchange bytes only through House, which relays an inbound attachment
+from the gateway to the Worker that needs it and serves the gateway an outbound
+image from the original the Session stored.
+
+Bind the bot to this Environment:
+
+```sh
+kit telegram connect --house https://agents.house
+```
+
+The command asks for the token on a hidden terminal prompt, or reads one line
+from standard input when it is not attached to a terminal. It asks Telegram `getMe`, and
+refuses a bot whose Threaded Mode is off, because House projects each
+conversation into its own forum topic. It then asks House whether this
+Environment may become the gateway, before it writes anything locally. Once
+House admits the preflight it deletes any webhook, so long polling is the only
+receiver, and proves the owner by reading one ordinary private message outside
+any topic through `getUpdates`, advancing the stored offset past it. Only then
+is the token written, and only then is the gateway registered with House. A
+setup House refuses removes the written token again, so a refused connect leaves
+no custody behind. The command prints the bot username, the bot user id and the
+proven owner's Telegram user id.
+
+Run the gateway:
+
+```sh
+kit telegram serve --house https://agents.house
+```
+
+The command holds one Environment control lease for the whole run and performs
+three activities inside it, each paced on its own so none of them blocks
+another:
+
+- **ingress** reads updates from the stored offset, normalizes each one into the
+  update House accepts, submits it, and advances the stored offset only after
+  House has taken it. A submission that fails leaves the offset where it was, so
+  the same update is offered again rather than lost.
+- **inbound files** acquires the attachments House still needs, refuses anything
+  reported above the 20 MiB download ceiling before calling `getFile`, downloads
+  the file with the local token, and pushes the bytes to House for the Worker
+  Environment that will materialize them. That push waits for the Worker to pull
+  and a single failed fetch never ends the pass.
+- **outbound queue** acquires the per-bot queue in its exact order, marks each
+  delivery attempted before it sends, and reports what Telegram answered:
+  `delivered` with the exact message or topic Telegram returned, `failed` when
+  Telegram refuses outright, and `delivery_unknown` when
+  the answer is absent or unreadable. File items are pulled back from House,
+  refused as `file_too_large` above the 10 MiB image ceiling, uploaded as
+  `sendPhoto` with the caption House composed around the link to the retained
+  original, and reported the same way; a pull that fails reports
+  `transfer_failed` and an ambiguous upload answer reports `delivery_unknown`.
+  Only an image ever becomes a file item, because House offers every other file
+  as a `conversation_file_link` message this queue delivers like any other. Live drafts ride that same queue as their own item and are
+  never reported back, because a draft has no settlement: House has already
+  coalesced each conversation to its latest view, and the gateway sends the
+  drafts of a pass after its durable deliveries with the Bot API's native
+  `sendRichMessageDraft` on the bound forum topic thread, under the same bot-wide
+  `retry_after` gate. The gateway coalesces nothing again and holds no draft for
+  a later pass: a draft taken in a pass that gate closed is dropped, and the next
+  view House coalesces takes its place. Pacing lives here because this is where
+  the Bot API is called.
+
+Each serve run first asks House to settle the attempts an earlier run abandoned,
+so a restarted gateway never leaves a delivery attempted forever. A Telegram
+`retry_after` opens one bot-wide gate: nothing is sent, fetched or polled until
+the delay Telegram supplied has passed. `--passes <count>` bounds each activity
+to that many passes and is what tests and one-shot runs use; without it the
+command is resident and stops on SIGINT or SIGTERM, printing what it settled.
+
+Release the bot:
+
+```sh
+kit telegram disconnect --house https://agents.house
+```
+
+The command writes a local disconnect marker first, deletes the webhook, removes
+the token and the stored offset, tells House this Environment is no longer the
+gateway, and removes the marker last. Local custody is therefore always gone
+before House admits the change. A disconnect interrupted after the marker was
+written finishes on a later run even though the token is already gone, and a
+`kit telegram serve` that finds the marker refuses to act.
+
+## Local state
+
+```
+$HOUSE_KIT_HOME/
+  credential
+  kit.json
+  conversation-inbound/<run>/<attachment>/<name>
+  secrets/personal-telegram-bot.token
+  state/telegram/get-updates-offset.json
+  state/telegram/disconnecting.json
+  state/hooks.json
+  state/hooks/<hook id>.txt
+  state/repositories/<repository identity>.json
+  state/sync/<replica identity>.json
+  state/sync/<replica identity>.pending.json
+  state/attachments/<upload identity>.json
+  state/conversation-originals/<attachment identity>.json
+  state/sessions/<tmux session>.json
+  state/continuations/<run identity>.json
+  state/<instance>/credentials/google.json
+  state/<instance>/checkpoints/<service>.json
+  state/<instance>/health/<service>.json
+  state/<instance>/gaps/<service>.json
+  state/<instance>/dropped/<service>.json
+  state/<instance>/originals/<service>.json
+```
+
+Every file is written atomically and readable only by its owner. A file the Kit
+cannot read is refused rather than treated as a service that never captured.
+Disabling a service or an instance leaves its state in place, so re-enabling
+resumes from the stored cursor instead of importing again.
+
+```sh
+kit source reset acme --house https://agents.house        # every service
+kit source reset acme notes --house https://agents.house  # one service
+```
+
+Reset is the only deletion of captured state. It removes the named checkpoints
+and their outstanding retained references so the next capture restarts exactly at
+the configured backfill boundary. It takes the same
+Environment control lease a capture takes, so it cannot delete a checkpoint a
+running capture is about to write back.
+
+## Host capacity
+
+An owned Linux host can report what it actually has, so its owner reads real
+capacity instead of guessing from Run counts. Declare the host section:
+
+```json
+  "host": {
+    "workspace": "/var/lib/house-kit/workspaces",
+    "maxima": {
+      "cpu_millicores": 2000,
+      "memory_bytes": 4294967296,
+      "disk_bytes": 53687091200
+    },
+    "image": null
+  }
+```
+
+`image` is the workspace image this host runs persistent container Environments
+from, and is only read by `kit workspace host` below; leave it `null` on a host
+that reports capacity and hosts no container. `workspace` is the absolute path of the persistent workspace directory; the
+report measures the filesystem holding it, not the root filesystem by
+assumption. `maxima` are the ceilings this host is configured to apply to
+Kit-managed workloads, and House keeps them apart from what it measured. Declare
+`"maxima": null` when this host configures no ceiling; an empty object is
+refused rather than read as no limit. A ceiling is a shared ceiling, never a
+reservation, and House infers no supported Agent count from any of these values.
+
+```sh
+kit host report --house https://agents.house
+```
+
+The command reads `/proc/stat` twice a second apart, reads `/proc/meminfo`, and
+asks the kernel for the workspace filesystem's block counts. It sends the host
+totals, what is in use, and what is available for each of processors, memory and
+that filesystem, with the instant it measured them. Nothing else is collected:
+no process list, no command line, no environment value, and no credential. A
+native source this Kit cannot read or parse refuses as
+`kit_host_unmeasurable` and sends nothing, because a host that cannot be
+measured is unknown to its owner rather than empty.
+
+The report is one observation, not a stream. Run it on a timer the host owner
+owns:
+
+```
+[Unit]
+Description=Report measured host capacity to House
+
+[Service]
+Type=oneshot
+User=house-kit
+ExecStart=/usr/bin/kit host report --house https://agents.house
+```
+
+```
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=5min
+```
+
+House reads an observation as fresh only while three instants - the one this
+Kit says it measured, the one House received the report, and now - all fall
+inside one fifteen-minute window. A host that stops reporting reads as aged from
+then on, a report that was already stale when it arrived reads as aged
+immediately, and a host that never reported reads as unknown; none of them ever
+reads as a measured zero. Keep this host's clock in step with real time - a
+clock more than fifteen minutes out of step in either direction makes every
+report it sends read as aged, which is the honest answer House can give about a
+reading it cannot date, and dating a reading into the future buys no freshness
+because it widens the same window. A smaller skew is not free either: it is
+spent from the same fifteen minutes, so a clock a few minutes out of step leaves
+the timer above correspondingly less room to miss a run before House reads this
+host as aged.
+
+## Migrating authored text and linked originals
+
+`kit migrate` runs under the Environment User's control lease. Its module
+category is `migrator`, declared in the required `migrators` array in `kit.json`
+(use `"migrators": []` when none are installed):
+
+```json
+{
+  "id": "my-import",
+  "category": "migrator",
+  "command": ["/home/ada/tools/my-import"],
+  "timeout_ms": 600000,
+  "environment": { "EXPORT_REGION": "eu" },
+  "secrets": { "EXPORT_TOKEN": { "file": "/run/secrets/export-token" } }
+}
+```
+
+The example is a user-installed module. Kit ships no concrete external-system
+migrator. Secret references resolve only in the Environment and are passed only
+to that module's process environment. The module receives neither House's
+credential nor its lease. Module output and stderr are not published or echoed;
+a module must never write an external credential into its emitted content,
+manifest, URLs, or attachments.
+
+```sh
+kit migrate emit my-import --package /home/ada/exports/project
+kit migrate mount /home/ada/exports/project --house https://agents.house \
+  --subtree /rooms/work/library/project
+# Or emit and mount in one maintained mount session:
+kit migrate run my-import --package /home/ada/exports/another-project \
+  --house https://agents.house --subtree /private/library/another-project
+```
+
+Emission refuses an existing output directory. The module reads one JSON line
+on stdin: `{"contract":"kit-migrator/1","migrator":"my-import","package":"/absolute/output"}`.
+It must finish writing this tree before exiting successfully:
+
+```text
+project/
+  migrator.json
+  model/note.md          # optional independently prepared type definition
+  content/page.md        # UTF-8 authored Markdown
+  attachments/image.png # exact downloaded original bytes
+  attachments/notes.txt
+```
+
+The manifest is closed and versioned:
+
+```json
+{
+  "contract": "kit-migrator/1",
+  "category": "migrator",
+  "migrator": "my-import",
+  "attachments": [
+    {
+      "path": "image.png",
+      "source": "https://export.example/image.png",
+      "media_type": "image/png",
+      "download": "downloaded",
+      "referrers": ["page.md"]
+    },
+    {
+      "source": "https://export.example/unavailable",
+      "download": "unavailable",
+      "failure": "not_found",
+      "referrers": ["page.md"]
+    }
+  ]
+}
+```
+
+`path` is relative to `attachments/`; `referrers` are relative to `content/`.
+`name` optionally supplies the attachment's file name. Downloaded entries require a
+local path and forbid `failure`. Unavailable or skipped entries require
+`failure` and forbid a local path. Every downloaded attachment must be linked
+from a declared referring document, for example
+`![Image](../attachments/image.png)` in `content/page.md`. Unavailable ordinary
+Markdown URLs remain visible; they do not satisfy required typed references.
+Only Markdown enters the Library. Symlinks, invalid UTF-8, binary content, type
+aliases under `content/types/`, and generated `_provenance` are refused.
+`content/MIGRATION.md` is reserved for Kit's report.
+
+Before creating the text subtree, Kit checks the House-declared MD model version
+against its exact `@agentshouse/mdmodel` dependency, which rewrites the
+package's links. House alone validates the resulting Library: a mount it
+refuses answers with House's own file path, field, rule and version, and no
+content lands. Definitions in `model/` require their own write
+grant at `/rooms/<handle>/settings/model/<type>.md` or
+`/private/settings/model/<type>.md`; a content write grant cannot prepare them.
+Kit adopts an identical existing definition and refuses a different one.
+Preparation uses the existing authored batch producer before the empty-subtree
+mount, so a missing model grant leaves no partial content tree. Independently
+prepared model definitions survive a later content-mount refusal or unmount.
+
+The atomic text mount includes a report with pending transfer rows. Kit then
+uploads each downloaded file once as an attachment to the mount's Room or
+Private Room, independently retrieves and compares the saved bytes, and only
+after that proof succeeds rewrites every link to it, in every referring
+document, to its attachment reference, such as `at_1x.q`. The reference is an
+identity House resolves, not an HTTP download URL. A link's query and fragment
+are kept after the reference, as in `at_1x.q#page=3`. Failed or unverified
+uploads remain source links in the authored text; their failure details appear
+only in the report. Use `kit attachment get --attachment <at_ref> --room
+<room-ref> --output <file>` (or `--private`) to retrieve the exact bytes. Binary
+bytes never enter the text replica. Migrators create no Capture, Source
+instance, or provenance.
+
+The mounted `MIGRATION.md` separates local downloads from saved, pending,
+failed, and skipped attachment uploads, with source URLs, referring documents
+and the attachment reference of each saved upload.
+`MIGRATION.json` beside the emitted package preserves local pending and final
+outcomes. A failed upload leaves usable mounted text and returns a nonzero
+exit status. A failure to publish the final report also returns nonzero and
+leaves the pending mounted report plus the local outcomes. Re-migration is
+explicit unmount followed by mount.
+
+```sh
+kit migrate unmount /rooms/work/library/project --house https://agents.house
+kit migrate unmount /rooms/work/library/project --house https://agents.house \
+  --confirm /rooms/work/library/project
+```
+
+The first command shows the subtree destruction summary and removes nothing.
+Confirmation must repeat the exact subtree. Kit checks discovered write/delete
+authority and protected paths for every selected target, then makes House's one
+unmount call. House rechecks authority and subtree state at commit. Each
+command requires the ordinary available Kit control lease; an already held lease
+is refused by the existing Kit rail.
+
+### Linux Compose validation
+
+The test service uses the host Docker daemon, loop device availability and a
+shared `/tmp` mount because `npm test` includes Kit's real workspace-volume
+proof. It runs with an init process, because the supervised-path proofs kill a
+tmux pane whose adapter is then orphaned and has to be reaped rather than left
+as a zombie. Set `KIT_TEST_UID`, `KIT_TEST_GID`, and `KIT_TEST_DOCKER_GID` for
+the host when they differ from 1001, 1001, and 112. It starts only test-owned
+workspaces.
+
+```sh
+docker compose -f test/compose.yaml build kit
+docker compose -f test/compose.yaml run --rm kit npm test
+docker compose -f test/compose.yaml run --rm \
+  -e HOUSE_KIT_GOOGLE_OAUTH_CLIENT_ID=kit-client.apps.googleusercontent.com \
+  -e HOUSE_KIT_GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-kit-installed-app \
+  kit npm run build
+```
+
+`test/pair/run.sh` boots real Core, Auth and PostgreSQL and runs the installed
+package against them. `HOUSE_CORE_ROOT` names the Core checkout under proof and
+`HOUSE_AUTH_ROOT` names an Auth checkout; the run exports the exact Auth revision
+Core's own `scripts/auth-pair-source.mjs` pins into `tmp/auth-pinned` and pairs
+that revision rather than whatever the checkout's working tree carries. Set
+`HOUSE_AUTH_REVISION` to name another revision when Core's pin trails the Auth
+contract that Core revision already requires. Both producer databases are
+dropped and made again before either migrates, so a run never inherits the
+schema another Core revision left behind. Every run prints the three revisions
+it paired and writes them into each evidence document.
+
+The installed fixture in `test/fixtures/migrator.mjs` uses only local material
+and is excluded from the published package. Its paired proof runs from Kit:
+
+```sh
+HOUSE_CORE_ROOT=<committed-core-snapshot> HOUSE_AUTH_ROOT=<committed-auth-snapshot> \
+  KIT_PAIR_SPECS=/kit/test/pair/migrator.vitest.ts bash test/pair/run.sh
+```
+
+The pair boots real Core, Auth, and PostgreSQL. It covers Room and private
+mounts, separately authorized models, House's typed refusal, exact
+attachment retrieval, failed storage, mounted reports, occupied mounts and the
+confirmed unmount. As in the other installed-CLI pair tests, the fixture expires
+the previous control lease before starting the next isolated command. Evidence
+is written to `tmp/delivery-evidence/migrator-pair.json` with producer revisions
+and the installed package digest.
+
+The retained-original consumers have their own paired proofs:
+
+```sh
+HOUSE_CORE_ROOT=<core checkout> HOUSE_AUTH_ROOT=<auth checkout> \
+  KIT_PAIR_SPECS="/kit/test/pair/source-originals.vitest.ts \
+    /kit/test/pair/conversation-originals.vitest.ts \
+    /kit/test/pair/conversation-house-storage.vitest.ts" bash test/pair/run.sh
+```
+
+`source-originals` drives a controlled local Source adapter through one
+installed Kit: it proves that the connector receives its own authorization,
+selection and cursor and never a House credential, that an unreachable House
+leaves the checkpoint where it was and converges on reconnect, that two Room
+owners hold independently owned retained copies of one delivery while one
+owner's two Rooms share a Record, that a failed save is truthful and a later
+byte retry publishes no second Capture and no substitute version, that an
+unauthorized Room destination stays outstanding while acquisition health stays
+its own, that an explicit backfill bound still holds in the installed package,
+and that interrupting the Environment stops the receiver without advancing the
+checkpoint or being woken again. After the Environment's authority is revoked
+its next capture is refused.
+
+`conversation-originals` and `conversation-house-storage` drive the same
+installed personal-bot gateway and Worker over House storage. Both prove an
+incoming accepted attachment retained through the shared byte client
+independently of transport, a failed save and its retry leaving every accepted
+message identity unchanged, the Run settling and its temporary media cache being
+disposed, the owner downloading the exact original through House afterwards, and
+the Environment's next protected act being refused once its authority is gone.
+A file a Session sends to its owner's conversation through `house
+upload_attachment` is proven by Core's pair lane. Evidence is written
+to `tmp/delivery-evidence/source-originals-pair.json`,
+`conversation-originals-pair.json` and `conversation-house-storage-pair.json`.