@agentshouse/kit 0.1.0-alpha.8 → 0.2.0

package/README.md

@@ -1,1749 +1,23 @@
 # House 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.
+House Kit connects an Environment, a Linux computer or server, to
+[agents.house](https://agents.house). It runs your Agents' conversations
+through the agent CLIs you chose and gives each Agent the `house` command.
 
-## Connect a Linux computer
+## Install
 
-On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
-versioned bootstrap once:
+Connect a computer from agents.house. It gives you the one command that
+installs House Kit on that computer and updates it when you run it again.
 
-```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.8/connect-linux.sh)
-```
+## Commands
 
-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.
+`kit login` opens a link you confirm in your browser and keeps the
+Environment's credential in `~/.house-kit`, or in `$HOUSE_KIT_HOME` when it is
+set. Pass `--manual` to paste the code by hand on a machine without a browser,
+and `--environment <id>` to reconnect an Environment you already have.
 
-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:
+`kit resident` keeps the Environment connected.
 
-```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" }
-    }
-  }
-}
-```
+## License
 
-`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.
-
-## 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.
-
-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`.
+MIT