@agentshouse/kit 0.1.0-alpha.3 → 0.1.0-alpha.31

package/README.md

@@ -4,61 +4,184 @@ 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.
 
+The Skill set Kit installs is Matt Pocock's
+[`mattpocock/skills`](https://github.com/mattpocock/skills); thank you, Matt.
+
 ## Connect a Linux computer
 
-On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
-versioned bootstrap once:
+On Linux `amd64` or `arm64`, run the published, versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.3/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.31/connect-linux.sh)
 ```
 
+The bootstrap first establishes Docker Engine from what it observes on the
+computer. A Docker Engine that already answers is used as it is, on any
+distribution. On Ubuntu 22.04, 24.04 or 26.04 LTS it follows Docker's
+[apt repository recipe](https://docs.docker.com/engine/install/ubuntu/) for
+whatever is missing: it installs `docker-ce`, `docker-ce-cli`,
+`containerd.io`, `docker-buildx-plugin` and `docker-compose-plugin` from
+`download.docker.com`, starts the `docker` service when it is stopped and adds
+the account to the `docker` group. Every such step runs through `sudo`, which
+asks for the password as it ordinarily does. A new group membership applies
+from the account's next sign-in, so the invocation that grants it reaches
+Docker Engine through `sudo` for the rest of its own run; a later invocation
+from a session older than the membership is refused until the account signs
+out and back in. The bootstrap refuses an Ubuntu computer whose installed
+`docker.io`, `docker-compose`, `docker-compose-v2`, `docker-doc`,
+`docker-buildx`, `podman-docker`, `containerd` or `runc` package conflicts with
+that recipe rather than removing it. Any other distribution needs a working
+Docker Engine supplied by its owner, and without one the bootstrap stops with
+that missing prerequisite. A step that fails names its cause and changes
+nothing further; running the same bootstrap again continues from the state it
+left, including after a restart.
+
 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.
+another House and is retained in Kit home. A local loopback House,
+`http://127.0.0.1:<port>` or `http://localhost:<port>`, runs the resident
+container on the host network, as the one-shot login, credential check and
+apply containers always run, so the resident reaches the House the host serves;
+an HTTPS House leaves it on Docker's own network. A repeated invocation reuses the
+same container, credential and Environment. Every invocation that is not a
+forwarded command also sets `skills` in Kit's configuration: `--no-skills`
+declines [the Skill set](#the-skill-set) and an invocation without it accepts
+the set again.
+
+Running a newer release's bootstrap the same way is the only update. When the
+installed container runs another image, the bootstrap pulls this release's
+image and asks the running resident Kit to drain with `kit resident drain`. The
+resident stops acquiring Runs, resumptions, setup, agent CLI work, Google
+sign-ins and scheduled Google captures, while the Sessions it supervises keep
+their renewal, owner stops, answers and reports and a capture already running
+finishes.
+While any Agent Session is still running or unreported, including one whose Run
+was being acquired when the drain began, the bootstrap names it and leaves the
+container as it is; rerun it once they end. Once nothing remains,
+the resident stops renewing, releases its exact lease and stays quiescent, and
+the bootstrap replaces the container with one on this release's image over the
+same Kit home and workspace. The credential, Environment, Kit-home state and
+everything under the workspace are kept; anything installed elsewhere in the old
+container is not. A stopped container is replaced without a drain.
+
+If House refuses the installed Kit with `kit_upgrade_required`, including in
+its answer to a command the resident serves, the resident calls House no more,
+neither to release nor to report. It keeps supervising
+every running Session locally and never stops one to make progress. A Session
+that ends keeps its exact binding, stop observation and outcome in Kit home,
+and the drain answers ready once no supervised process runs. The updated Kit
+waits for the old lease to expire, acquires the next one and reports each held
+Session before it acquires any work, restoring no process and inventing no
+outcome.
+
+The versioned `bootstrap.json` is the machine-readable command source for this
+release. It is exported from the npm package as `@agentshouse/kit/bootstrap`
+(JSON import) and published byte-for-byte beside `connect-linux.sh` in the
+GitHub release. Its schema version is `1`, its `version` is the Kit package
+version, and `hosts` contains only bootstrap scripts published in that release.
+The package exports only the `./bootstrap` subpath; `./package.json` and source
+subpaths are not exported. For this release, only `hosts.linux` exists. In this
+schema example, `<version>` stands for the package's version:
+
+```json
+{
+  "schemaVersion": 1,
+  "version": "<version>",
+  "hosts": {
+    "linux": {
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v<version>/connect-linux.sh)",
+      "asset": {
+        "name": "connect-linux.sh",
+        "url": "https://github.com/agentshouse/kit/releases/download/v<version>/connect-linux.sh"
+      },
+      "workspace": { "argument": "--workspace", "quoting": "posix" }
+    }
+  }
+}
+```
+
+`command` is complete for the default workspace. To show a selected absolute
+workspace, append the declared `workspace.argument` and the path as one POSIX
+shell-quoted argument. For example, `/home/user/My Agents' House` becomes
+`--workspace '/home/user/My Agents'\'' House'`. Quote the entire path before
+adding it to a copyable shell command; never interpolate it as shell syntax.
+The bootstrap validates an absolute workspace root and encodes it as one Docker
+`--mount` CSV source field, including commas and double quotes in the name.
+The package manifest contains no image digest: the release workflow
+fills the immutable image digest into the published script after the package
+has been built.
 
 The bootstrap does not install native Kit on an ordinary computer. The native
 package remains for managed Nodes and an explicitly selected eligible Kit host.
 
+The same bootstrap is the host's entry point for the existing `kit` commands:
+append `kit` and the command to the connect command above, as in
+`bash <(curl -fsSL …/connect-linux.sh) kit apply` or
+`bash <(curl -fsSL …/connect-linux.sh) kit telegram connect`. It forwards the
+command and its arguments unchanged into the installed container through the
+host's Docker client and ends with the command's own output and exit status.
+Standard input stays attached and a terminal stays a terminal, so a hidden
+prompt such as the Telegram bot token is read inside the container and never
+becomes an argument or printed output. With the output redirected, the
+command's output and errors stay separate and the terminal stops echoing typed
+input until the command ends. A running container runs the command beside its
+resident Kit; a stopped one runs it in a one-off container over the same Kit
+home and workspace and stays stopped. `kit login` takes the bootstrap's own
+login route, a one-off container on the host network so the host browser can
+return to its loopback listener, or `--manual` for the URL and one-time code.
+Forwarding installs no host-native Kit and gives the container no Docker socket
+or further mount; it refuses when no Kit is installed or the installed one
+differs from this bootstrap's.
+
+The owner's working copy push is forwarded the same way: run
+`bash <(curl -fsSL …/connect-linux.sh) house git push [commit] --owner` from a
+directory beneath the workspace root, such as a Room copy under
+`working-copies/rooms/`. The bootstrap runs the container's `house` in the
+matching directory beneath `/agents/house`, through the resident's lease when
+the container runs, and refuses a directory outside the workspace before
+anything reaches House.
+
 ## 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:
+The repository checkout is the development source. Build the package that can
+be published:
 
 ```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.
+The command writes the publishable package to `dist/package`. It reads no
+environment and ships no provider OAuth client: each Google account signs in
+with the User's own client, as [the Google preset](#the-google-preset)
+describes.
 
 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. The SDK's approval
+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
+The bootstrap invokes bare `kit login`, which connects to `https://agents.house`;
+`--house <origin>` names another House. Login records the House in Kit home
+beside the credential. Every House-bound command talks to that recorded House,
+and every command but login refuses `--house` as an unknown argument. 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.
+the panel renames it. An explicit later login reconnects that retained id, and
+`--environment <uuid>` reconnects the Environment it names instead, whether or
+not Kit home records one, and Kit home then records that id. Reconnecting issues the next credential for the same Environment
+and ends the previous one, including one `envs/revoke` ended; House refuses an
+Environment it no longer holds with its cause and never creates a replacement.
+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`
@@ -112,7 +235,8 @@ never printed by Kit.
       "settings": "/home/ada/.claude/settings.json"
     }
   ],
-  "host": null
+  "host": null,
+  "skills": true
 }
 ```
 
@@ -132,13 +256,19 @@ mode: `"intermittent"` for a laptop or other normally offline placement,
 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.
+service owns the command that produces it. The Kit reads only `custom` instances
+and passes over any other entry of `instances`.
 
 `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.
 
+`skills` is this Environment's choice of [the Skill set](#the-skill-set):
+`true` accepts it and `false` declines it. A configuration that omits it
+accepts the set. The bootstrap writes it on every invocation that is not a
+forwarded command.
+
 `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
@@ -165,7 +295,7 @@ 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
+kit apply
 ```
 
 Only the state House declares - instances, services, `source_ref`, and Room
@@ -233,119 +363,81 @@ 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.
+House holds this Environment's Google Sources, and its owner sets them in the
+App. Each entry names an account name the owner chooses, one service -
+`gmail`, `calendar` or `drive` - the Rooms it goes to, and what its first
+capture takes: `{ "new": true }` for new activity only, `{ "days": n }`,
+`{ "items": n }` or `{ "all": true }`. Neither the configuration file nor any
+command on this computer declares one.
+
+Each service captures a fixed corpus under its own read-only scope: Gmail every
+message but Spam and Trash, Calendar the account's primary calendar, and Drive
+the files the account owns.
+
+The resident reads the list from `/kit/sources/desired` each time its Kit
+control stream connects and each time House signals `sources` on it, then
+reconciles:
+
+- a new entry gets its local state and is captured once its account is signed
+  in for its service;
+- a changed entry's Rooms take effect on its next capture;
+- an entry House no longer lists stops, and its checkpoint, health, gaps,
+  dropped items and unsaved originals are deleted;
+- an account left with no entry has each of its grants revoked at Google's
+  revocation endpoint and its credentials, its OAuth client included, deleted.
+  Google's revocation ends every grant the Google user gave the client's
+  project, so when another listed account is signed in to the same Google user,
+  the Kit deletes the local credentials and revokes nothing.
+
+It then reports every entry to `/kit/sources/report`, and reports an entry
+again after each sign-in and each capture: `signed_out` while its
+account holds no grant for its service, `failed` with its cause code when its
+last capture failed, and `ready` otherwise, each with the account's signed-in
+email once the Kit knows it.
+
+The Kit ships no Google OAuth client. Each account signs in with the User's
+own: an OAuth client of type Desktop app in the User's Google Cloud project,
+with the service's API enabled there. An entry whose account holds no grant for
+its service opens a login renewal for integration `google`, instance the
+account name and service the entry's service, and presents its ceremony on
+House's owner-authenticated page, so the owner's browser never has to reach
+this Environment. When the account has no client yet, the page first collects
+the client id and secret. It then links to Google's consent for that service's
+scope only; Google sends the browser to a `http://127.0.0.1:<port>/` address
+that nothing answers, and the owner pastes that whole address 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 account's client, and stores
+the grant beside the client in `state/google/credentials/<account>.json`. The
+collected values pass through House's live relay only; neither they nor any
+token enter a report, a log or anything House stores. Adding a
+service to a signed-in account asks only for that service's consent, and each
+service keeps its own grant. An address that answers another consent, or a code
+Google refuses to exchange, stores nothing; a declined consent or a ceremony
+that outlives its ten-minute bound cancels the sign-in, and the Kit tries again
+at the next reconciliation.
+
+The resident captures each signed-in entry every 15 minutes, with no command.
+An occurrence never overlaps its entry's previous one, and one missed while the
+resident was stopped is not replayed: the next resumes from the checkpoint. The
+first capture fixes the initial choice's boundary, so `new` captures nothing
+that existed then and everything that arrives after.
 
-```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
-}
+```sh
+kit source capture work        # one occurrence of every entry of the account now
+kit source capture work gmail  # one occurrence of one entry now
+kit source status work
 ```
 
-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"
-    }
-  }
-}
-```
+`kit source capture` and `kit source status` take the account name where a
+custom connector takes its instance; a name House lists as an account is read
+as the account. While the resident runs, it performs the requested occurrence
+itself, after any occurrence of that entry already running.
 
-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.
+A failed occurrence records its cause. A Google 403 for an API disabled in the
+client's project fails as `api_disabled`, and `kit source status` names the API
+to enable; a revoked scope (`google_scope_revoked`), an expired or revoked grant
+(`google_authority_revoked`) and a provider failure
+(`google_provider_unavailable`) keep their own codes.
 
 ## Environment setup
 
@@ -354,11 +446,13 @@ 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 setup
 ```
 
 `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
+hands out any work, so a managed Environment needs no terminal; the resident
+Kit performs it each time its control stream connects and on each `runs`
+signal, which House also sends for every setup request. The walk first
 prepares the absolute `/agents/house` base, then visits every declared agent
 CLI and then every connector instance, in configuration order:
 
@@ -462,15 +556,54 @@ 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
+The same command owns its module authorization. `kit source sign-in <instance>`
+skips an instance whose local authorization is already valid and answers
+`ready`, `skipped`, or `needs_attention`. It 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 Kit control stream
+
+The resident Kit holds one `/kit/stream` WebSocket for its Environment,
+authenticated with its Environment control lease and the Kit contract header,
+for as long as it holds that lease; `kit worker run` holds one for the length
+of its pass to receive its owner's commands, and `kit telegram serve` holds one
+while it serves the gateway under a lease of its own. The Kit sends no
+subscribe frame and accepts every frame House sends. What it writes there is
+the live view of the turns it runs, as draft and plan frames the
+[Worker runtime](#the-worker-runtime) describes, and a `gap` frame when the
+[Telegram gateway](#the-telegram-gateway) needs a turn's whole view again.
+
+Each time the socket connects, the resident acquires everything a signal could
+have named, because a signal House sent while the socket was down is lost: its
+Runs and resumptions with their setup and conversation files, the owner's
+pending commands, the agent CLI list, the saved working copy choice and its
+Google Sources. After that it acquires only what House names. A
+`work_available` frame for `agents`, `working_copy` or `sources` acquires that
+subject alone. `runs` takes a resumption or else a waiting Run, readying the
+agent CLIs, a requested setup and conversation files first. `commands` hands
+the supervised Session its stops, interrupts and answers and takes a
+resumption the same way, without acquiring a Run. An `entries` frame, a change
+in a Room the lease admits, delivers the working copies. A pass that took a Run
+acquires again once that Run ends, and a pass that found nothing waits for the
+next signal. A Run outcome House did not take is reported again every 30
+seconds until House answers. The Kit has no idle acquisition cycle, no command
+poll and no Session heartbeat: a Session is observed when its process starts
+and when its supervisor sees it stop.
+
+A socket that closes or never opens reconnects after a delay drawn between half
+and all of one second, doubled for each consecutive failure up to 30 seconds.
+An `authority_changed` close reconnects after a delay drawn between 0 and 2
+seconds, with no error backoff. A `replaced` close, which means a newer
+connection holds the Environment, ends the resident with `kit_stream_replaced`,
+and an upgrade House refuses with `kit_upgrade_required` stops every House call
+as [above](#connect-a-linux-computer) describes; neither is retried.
+
 ## The Worker runtime
 
 ```sh
-kit worker run --house https://agents.house
+kit worker run
 ```
 
 Worker-runtime readiness validates the tmux this Kit declares support for,
@@ -538,27 +671,12 @@ 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.
+Kit never creates it.
+
+When the Agent's own default directory is absent, Kit creates it empty; two
+concurrent first launches create the same directory. A present default
+directory launches exactly as it is, and a deleted one is created empty again
+on its next launch. Kit writes no file into any working 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
@@ -566,6 +684,52 @@ 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 Skill set
+
+The Skill set is every skill the `mattpocock/skills` plugin manifest names at
+one pinned commit but `setup-matt-pocock-skills`, `triage` and `wizard`. Each
+is vendored under `src/skill-set/<name>/` with every file it ships, the
+upstream MIT `LICENSE` and a provenance header in `SKILL.md` naming the commit
+and upstream path. Nothing else is edited but two lines: a
+`disable-model-invocation: true` frontmatter line in `SKILL.md` and an
+`allow_implicit_invocation: false` line in `agents/openai.yaml` are removed, so
+an agent reaches every skill without being told its name.
+
+Kit installs the Skill set once for the Environment, for every Agent whatever
+its working directory, under the home it launches agent CLIs with: each skill
+as the directory `$HOME/.agents/skills/<name>`, which Codex and Grok Build
+read, and a relative symbolic link `$HOME/.claude/skills/<name>` to it, which
+Claude Code reads; when `$HOME/.claude/skills` already resolves to
+`$HOME/.agents/skills`, Claude Code reads the directory there and Kit makes no
+link. In a container that home is Kit home, so the set survives
+container recreation; on a native host it is the host user's home.
+
+`$HOUSE_KIT_HOME/state/skill-set.json` records the names Kit installed and the
+Kit version that installed them, and Kit owns exactly those names: the
+directory and the link of each. At start and on every resident pass, when
+the set is accepted and the record names another version or none, Kit deletes
+every recorded name, installs the current Skill set and rewrites the record. A
+name whose directory or link exists without being recorded is the owner's: Kit
+leaves it untouched and installs nothing under it. Kit never compares, merges
+or restores a file, so an edit to an installed skill is lost at the next
+release and a copy under another name is kept. When `skills` is `false`, Kit
+deletes every recorded name and the record and installs nothing.
+
+After Kit first installs the Skill set, the first Session it launches whose
+Profile ceiling lets it write the owner's How-we-work document
+`/private/library/how-we-work.md` creates it, when it is absent, with the text
+Kit ships in `src/how-we-work.md`, over the Session's own bridge before its
+first prompt is built. Kit then notes in `$HOUSE_KIT_HOME/state/how-we-work`,
+apart from the record, that the document exists, and a present document is
+noted the same way without being touched. Nothing ever creates it again: a
+release, a declined Skill set and a later acceptance leave the note, so an
+owner's edit stands and a deleted document stays deleted. A Session whose
+ceiling cannot write the document launches without it and leaves it for the
+next one; any other refused creation refuses the attempt as
+`kit_how_we_work_unwritable` with House's answer before a prompt is sent. A
+Skill set Kit cannot install or remove refuses the pass as
+`kit_skill_set_unavailable` and names the path.
+
 ## The declared agent CLIs
 
 The Environment owner installs no adapter binary by hand. `kit agents update`
@@ -575,6 +739,17 @@ 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
@@ -669,11 +844,24 @@ 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
+being guessed. After committing the Run, and again on every resumption, the
+Kit reads what the Session was started for from House's
+`/kit/runs/<run>/request` with the Session credential: the Routine Request with
+its input, references, requester and the pinned revision's instruction, or the
+sealed conversation turn. It sends that as the first prompt block, followed by
+current House guidance fetched through the Run connection, so the Agent calls
+nothing to learn it. An unreadable request or guidance refuses the turn.
+A session opened with `session/new` gets one more text block ahead of those,
+the same for every adapter kind: the line
+`The agents.house house CLI is available: run house --help.`, the base
+instructions of the Execution attempt plan House acquired, and the current text
+of the owner's How-we-work document `/private/library/how-we-work.md`, which the
+launcher reads with the `shell` tool over the Session's own bridge, following
+House's cursor to the whole text. An absent document, one the Session's ceiling
+cannot read, and empty base instructions add nothing. Any other failed read
+refuses the attempt as `kit_how_we_work_unreadable` with the bridge's cause
+before a prompt is sent. A session reloaded with `session/load` already holds
+the block and gets none. 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
@@ -686,37 +874,55 @@ 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
+While the adapter generates, the supervisor writes the whole User-visible
+assistant text of the turn so far as `draft` frames on the Environment's
+[control stream](#the-kit-control-stream); it calls no draft route. 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.
+calls, 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 blocks, and leaves anything it did not
+parse as the paragraph it observed. It invents no structure, renders nothing,
+and holds back or refuses no draft for its length: a frame carries every block
+of the text however long it is.
+
+A frame names the turn it belongs to, as House answered the Session's `started`
+observation with the turn's `conversation_id` and `turn_id`, together with the
+Execution attempt as `attempt_id`. It carries a `sequence` that grows by one
+with each paced view of the turn, and replaces the turn's view from the block
+index `from` onward with the `blocks` it carries, so a frame for text that only
+grew carries the blocks from the first one that changed, and a view that
+changed no block is a frame that replaces nothing. The launcher numbers the
+views, so a Kit that restarts mid-turn continues the turn's sequence. The Kit
+coalesces and paces that stream rather than mirroring every chunk: it writes
+the first observed view at once and then at most one view in each
+500-millisecond pacing window, the latest one, even when the adapter completes
+a message inside a window. A frame written while the socket is down is lost,
+so the first frame after each reconnect, and after any frame the socket could not carry, replaces the view
+from block 0. A Session House names no conversation turn for gets no frames. 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 `plan` session update is one snapshot of the agent's steps. The Kit writes
+each snapshot as a `plan` frame paced by the same rule, carrying every step's
+`label`, `priority` and `status` exactly as the adapter gave them, its own
+`sequence`, and the step index `from` it replaces the plan onward. The act that
+ends the turn carries the last snapshot the Kit saw as its final `plan`: the
+seal, the observed stop, the Run outcome and an `interrupted` interrupt outcome
+each name the provider turn and every step's `label` and `status`, however many
+steps and however long their text, and a turn that never planned carries none.
+There is no per-snapshot plan route.
 
 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.
+`sessions/<session>/assistant-messages` call carrying the same blocks, the final
+plan, and a UUIDv7 `operation_id`. The exact request - that identity, those
+blocks and that plan - 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, those blocks and that plan 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
@@ -736,7 +942,9 @@ 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.
+`2026-07-28` profile. `house git push` is the one local verb House does not list;
+[working copies](#working-copies) describe it, and `house --help` and
+`house git push --help` explain it.
 
 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
@@ -760,7 +968,7 @@ 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)
+House refusals pass through to the CLI without automatic resend. [R193](https://github.com/agentshouse/core/blob/main/docs/concept/implementation/14-agents-profiles-sessions-and-runs.md#r193)
 owns recovery authority, lifetime, and refusal semantics.
 
 The launcher speaks only what the adapter contract fixes for this build. Every
@@ -819,8 +1027,8 @@ 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
+The provider receives absolute local paths beside the owning messages in its
+first prompt. 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
@@ -833,8 +1041,9 @@ 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
+the file is gone or changed rather than saving different bytes. When a
+supervised WorkerSession ends, the same retry runs once more before its Run is
+reported. 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
@@ -845,8 +1054,8 @@ 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
+`session/load`, receives the current input House answers for the Run in its
+first prompt, 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.
 
@@ -861,7 +1070,7 @@ 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)
+owner stops remove the record. [R199](https://github.com/agentshouse/core/blob/main/docs/concept/implementation/14-agents-profiles-sessions-and-runs.md#r199)
 owns conversation continuity.
 
 Launcher exit is the terminal process observation. The Kit closes the local
@@ -913,7 +1122,12 @@ 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.
+owner stop, and a retained Provider continuation each drop it. When the
+supervised process ends, the binding first records what the Kit observed: the
+sealed final text, whether the turn completed, the capacity or provider refusal,
+the execution failure and whether a Provider continuation is retained. The Kit
+then reports that stop, and a restarted Kit reports the same recorded stop
+instead of treating the session as lost.
 
 A restarted `kit worker run` reconciles the records it kept before it acquires
 anything new. It reports every retained settlement note first, because those
@@ -937,7 +1151,7 @@ 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
+Run's bridge, while it admits or settles a question, reports an interrupt, 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
@@ -965,7 +1179,10 @@ 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
+both at startup and while a Session is supervised: House signals `commands` on
+the Kit control stream and the supervisor acquires the pending stops,
+interrupts and answers at once, so a stop reaches the process within a second.
+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.
@@ -1004,8 +1221,8 @@ 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
+kit source capture acme        # every declared service
+kit source capture acme notes  # one service
 ```
 
 Each run reads the checkpoint, acquires one bounded page, submits one batch,
@@ -1019,8 +1236,8 @@ 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.
+this installation's own state. House holds no custom connector's service, route,
+checkpoint or health, and no Google entry's checkpoint or health.
 
 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
@@ -1038,8 +1255,8 @@ 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
+kit source retry-files acme        # every declared service
+kit source retry-files acme notes  # one service
 ```
 
 `retry-files` saves only the references still outstanding. It runs no connector,
@@ -1062,10 +1279,27 @@ 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.
+same installation at once. A command that ends, is refused, or is interrupted
+once its work has stopped releases that exact lease so the next command acquires
+at once. A `kit login` credential is presented only to take that lease.
+
+While `kit resident` holds that lease, a command runs through it instead: the
+command presents no credential, the resident confirms its current lease with
+House and sends the command's House requests under it, an interrupted command
+cancels its request there, and the lease stays held when the command ends. The
+resident serves one such command at a time and refuses another with
+`environment_control_lease_active`, so two commands still never work at once.
+A resident whose lease House refuses answers the command with that refusal; the
+command never acquires a lease of its own while a resident serves it. While an
+update drains, `state/update-drain` refuses every such command, `kit login` and
+`kit worker run` with `kit_update_draining` before it enrolls, acquires or
+delegates anything. A command already served keeps the resident's lease until
+it ends, while the resident refuses its acquisition of new work and its
+Telegram updates with `kit_update_draining`, which ends a served
+`kit telegram serve` once each of its activities reports the deliveries and
+files it already acquired; until it ends, the drain answers that it waits for
+that command and the bootstrap leaves the container as it is. The bootstrap
+removes the file when it replaces the container.
 
 Interrupting the command cancels the running connector without advancing the
 checkpoint.
@@ -1078,8 +1312,7 @@ Git credential:
 ```sh
 kit repository capture /srv/acme \
   --room work-room \
-  --source-handle acme-repository \
-  --house https://agents.house
+  --source-handle acme-repository
 ```
 
 The command runs ordinary `git pull` in the checkout with the local User's Git
@@ -1104,25 +1337,186 @@ 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.
 
+## Working copies
+
+The Environment owner chooses in House which Rooms this Environment keeps
+locally, and whether it keeps `/private`. An Environment whose owner never chose
+copies nothing, and a Room joined later stays uncopied until the owner selects
+it. The resident Kit reads the saved choice through
+`POST /kit/working-copy/selection` whenever its control stream connects or
+reconnects and whenever House points it there after a save;
+`kit worker run` reads it once before its pass.
+
+Each selected Room becomes one ordinary Git repository at
+`/agents/house/working-copies/rooms/<room_ref>`, and `/private` one at
+`/agents/house/working-copies/private`. The Room reference names the location,
+so a Room handle change moves nothing. Every Agent launched afterwards receives
+the House path and local repository of each active copy in its context, one
+line each, such as `/rooms/work: /agents/house/working-copies/rooms/r_1x.q`.
+
+A Room repository holds the Room's complete readable content: `ROOM.md`,
+`library/`, `capture/` with its provenance sidecars, and `collaboration/`. The
+`/private` repository holds its Library, collaboration, each Room's private
+`AGENTS.md`, the `agents/` cards and `house/`. Attached settings and attachment
+bytes are not copied. The branch `main` starts at the commit House served, which
+tracks exactly the files House declares writable under the Environment's
+current grant. Every other file is read-only House content: the generated
+`.gitignore` names and explains it, so Git never tracks it, and the matching
+`.ignore` keeps it visible to ripgrep and other native search. Neither file
+grants anything, and House refuses a change to a read-only path however it is
+committed.
+
+Local edits, staging and commits change nothing in House until a commit is
+pushed. `refs/house/received` records the House content last received; each
+commit Kit wrote there, and each commit it acknowledged for a push, is a House
+state. The House revision of every file content Kit received, keyed by path,
+Git blob and the House state that received it, stays in Kit home under
+`state/working-copies/`, outside the repository. A local commit is a local tree, never a House revision.
+
+The resident Kit keeps every active copy current. Whenever its control stream
+carries a Room change, and whenever it reads the saved choice, one
+`POST /kit/door/discover` tells it where each
+copied Room stands, and for a Room that moved on it reads the changes after the
+copy's recorded position through `POST /kit/door/enumerate`. A changed, new or
+removed authored file becomes a commit on `refs/house/received`, its House
+revision kept in Kit home; changed, new or removed read-only content, such as
+Capture with its provenance sidecar or a House projection, is written into or
+removed from the ignored local tree, with each directory a removal leaves empty,
+and `.gitignore` and `.ignore` follow it.
+Delivery never touches the branch, the index or a tracked file, and a push
+waiting for its outcome or its local integration keeps its record. A push takes
+each file's revision from the newest House state in its own base's history that
+received that content, so a local commit keeps the base it was made on even when
+House returns to the same text under a newer revision. A file new to the copy is tracked when a write scope
+House declares for the Room covers it more closely than a declared protected
+path, and a local file already sitting where new read-only content arrives
+stays yours: Kit neither overwrites nor later removes it. When the write scopes
+or protected paths House declares for the Room change, Kit reads the Room again
+as a reselection does. A position older than House
+retains, or from before House's database was restored, makes Kit read the Room
+again as a reselection does; while House's replica has not reached the position
+the copy waits, and the resident delivers again 30 seconds later. A Room House
+no longer answers under its
+recorded handle makes Kit read the saved choice again, which follows a handle
+change or marks the copy inactive, and a Room that lost sync is named on
+standard error as `operation_denied` and keeps what it holds. `kit worker run`
+delivers once, after reading the saved choice.
+
+`house git push [commit]`, run anywhere inside a copy or one of its linked
+worktrees, submits one commit, `HEAD` by default, resolved once. Kit compares
+that commit's tree with the newest House state in its history, so every linked
+worktree keeps its own base, and sends the difference as one ordinary House edit:
+a changed field, section or preamble against its own prior value, any other
+change as the whole file against its exact revision, a new file as a create and
+a committed deletion as a removal. Staged and unstaged work, and files absent
+only from the working tree, are never sent. Native `git push` reaches no House
+remote. Inside an Agent Session the push goes through that Session's bridge,
+under its own authority and provenance; outside one it needs
+`house git push [commit] --owner`, which the resident Kit carries out under its
+control lease when a resident runs, and which otherwise acquires and releases
+its own. A Session refuses `--owner`, and a missing bridge is never replaced by
+owner authority.
+
+A Session's edit too large for one MCP request of 4 MiB goes through House's
+`prepare_edit_upload` Command on that Session's bridge, naming every changed
+path, the byte count and the SHA-256 of the bytes to upload under the push's
+operation. Those bytes are the serialized changes, padded with trailing spaces
+to one byte over 4 MiB when only the request around them passed the bound,
+because House takes no smaller upload. Kit sends them to the upload address
+House returns and then calls `edit` with the paths and the returned upload
+instead of the changes, so House applies them as the same one edit. The upload
+is recorded in Kit home before the edit is sent, so a push whose answer was lost
+resends that same edit; when House no longer holds the uploaded bytes and has
+not applied the edit, the push uploads them again once under the same operation.
+A change set beyond House's batch bounds is refused whole and never split.
+
+Inside an Agent Session `git` is Kit's shim in front of the installed Git, and
+every command runs exactly as that Git runs it. In a copy or one of its linked
+worktrees the shim compares that worktree's index before and after each
+command. When `git mv` succeeds, Git's own dry run of the same command names
+which path went where, and the shim hands each move to the resident Kit, which
+keeps every moved document's successive paths in Kit home. A staged move
+belongs to its worktree's index: a command there that takes its path out of the
+index or brings it in anew, such as `git reset`, `git restore --staged`,
+`git rm`, `git stash` or `git switch`, takes it back, and so does removing the
+worktree. A `git commit` whose commit carries the move ties it to that commit.
+A tied move counts for every pushed commit whose history holds one of its
+commits, whatever the index does meanwhile. `git commit --amend` and
+`git rebase`, Kit's own rebase onto House's result included, also tie it to
+their result when the rewritten branch still carries it, so aborting the rebase
+or resetting back to the original commit keeps it as well. A `git reset` that
+leaves every commit of the move behind without touching its latest path in the
+index returns it to that worktree's index, where the next commit ties it again.
+Any other rewrite, such as a cherry-pick, leaves the move tied to its earlier
+commits. A push sends House's rename of the same document from the path its
+House base holds to the latest of its counted paths the pushed commit holds,
+when the commit no longer has the first and the base did not have the second;
+a moved file whose content also changed follows as a
+whole-file replacement at its destination. House keeps the document's identity
+and rewrites the links and references that name it; Kit reads those rewrites
+through `POST /kit/door/enumerate` and records them in the acknowledgment.
+Anything else records no move and the push sends an ordinary removal and
+creation, which House refuses while another document still refers to the
+removed one: a failed `git mv`, one undone or never committed through the
+shim, and a move made with Git outside the shim such as in the owner's own
+shell. An accepted push drops the moves its commit's history holds.
+
+House decides before any local Git step. A refusal changes nothing in House;
+after `edit_conflict` Kit records the current content House names for the
+refused paths in `refs/house/received`, reading by revision any content the
+refusal does not carry, so the agent merges or rebases onto it with native Git,
+commits, and pushes again. After acceptance Kit records House's result for the
+pushed paths, the contents an owner push receives or each accepted revision
+read by name, in a commit that covers the pushed one and in
+`refs/house/received`; a read-only path House regenerates, such as the Wiki
+index, stays out of Git. The copy's recorded position goes back to where it
+stood when the push was sent, so the next delivery brings again anything House
+changed after the push's result, including what delivery received while the
+push awaited its answer. Kit then
+fast-forwards a clean branch still at the pushed commit, or rebases only its
+later commits. A result not yet readable, uncommitted tracked changes,
+a moved branch or a rebase conflict leave the branch as it was, with no stash or
+reset, and the push answers that House accepted it while local integration is
+pending; the next `house git push` finishes that integration without another
+House edit. A push whose answer was lost is recorded in Kit home before it is
+sent, and the next push by the same Session, or by the owner for an owner push,
+resends it under its original operation. Another caller cannot
+recover it: while the pushing Session lives it is refused as
+`kit_working_copy_push_pending`, and once that Session has ended Kit reads House
+again and drops it. When a retained push's operation has expired, Kit reads the
+Room again: if House holds the pushed content the push finishes as accepted,
+otherwise it is dropped and the next push submits it as a new operation.
+
+Deselecting a Room, or losing read access to it, marks its copy inactive:
+launches omit it, delivery stops, a new push is refused as
+`kit_working_copy_inactive`, and nothing local is deleted; a push already sent still settles and integrates. Selecting it again reads the Room
+again, advances `refs/house/received`, and replaces only the read-only content
+Kit wrote, never the branch, the index or a tracked file. A Room the owner may
+read without sync is refused as `operation_denied` and stays uncopied, while its
+ordinary remote reads are unaffected. Kit names each refused copy on its
+standard error.
+
 ## Explicit synchronization
 
-Beside the reconciling Working Copy, Kit has one explicit synchronization mode.
+Beside [working copies](#working-copies), 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 for the
-two Libraries and `ROOM.md`.
+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
+kit sync pull ./replica
+kit sync submit ./replica --changes ./changes.json
+kit sync rebootstrap ./replica
 ```
 
 `bootstrap` writes `ROOM.md`, Library text, House-derived projections, and
@@ -1135,10 +1529,12 @@ 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
+content or removal, and advances those positions. A removal, pulled or accepted
+from `submit`, also removes each directory it leaves empty up to the authority,
+so a later file can take that path; a directory still holding a file, such as a
+local draft, stays. 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.
+is reported as `position_expired`; 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
@@ -1152,7 +1548,12 @@ 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.
+files from the returned final content. It also reads House's own provenance
+for those files by enumerating from the position the batch started at, and
+writes each served sidecar whose revision is the accepted one, so a submit,
+answered or recovered after a lost answer, leaves each file's `_provenance`
+sidecar at the revision House recorded. Kit never composes that metadata
+itself.
 
 Pending submissions are written before transfer. A lost response, reconnect, or
 lease renewal recovers that exact request under the same identifier. A domain
@@ -1165,6 +1566,10 @@ 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.
+A pending submission House answers `operation_expired` is uncertain, so the
+Kit first pulls confirmed state. If House already holds the pending change,
+the Kit drops the pending copy and sends nothing more; only if it does not
+does the Kit send that change again under a new identifier.
 `rebootstrap` drops a submission still pending against the directory it
 replaces.
 
@@ -1179,23 +1584,20 @@ for a batch that reaches it.
 
 ## Attachments
 
-Upload one local file as an attachment to a Room or to your private tree. Name
+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
@@ -1241,7 +1643,7 @@ 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
+kit workspace host
 ```
 
 The command acquires this host's workspace work under its Environment control
@@ -1273,6 +1675,13 @@ 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.
 
+A pass House does not answer, such as one during a House restart, ends that
+pass only, and the host tries again on the next one; a pass House refuses ends
+the host. Without `--passes` the host serves until SIGINT or SIGTERM. It
+asks House to release its control lease when it ends, after its passes, a
+refusal, SIGINT or SIGTERM; once House has released it, a restarted host is
+admitted at once.
+
 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.
@@ -1296,7 +1705,7 @@ image from the original the Session stored.
 Bind the bot to this Environment:
 
 ```sh
-kit telegram connect --house https://agents.house
+kit telegram connect
 ```
 
 The command asks for the token on a hidden terminal prompt, or reads one line
@@ -1315,12 +1724,12 @@ proven owner's Telegram user id.
 Run the gateway:
 
 ```sh
-kit telegram serve --house https://agents.house
+kit telegram serve
 ```
 
 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:
+another, beside the live drafts described below:
 
 - **ingress** reads updates from the stored offset, normalizes each one into the
   update House accepts, submits it, and advances the stored offset only after
@@ -1341,15 +1750,39 @@ another:
   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.
+  as a `conversation_file_link` message this queue delivers like any other. The
+  queue carries no draft: an answer holding a draft item is refused as
+  `kit_telegram_response_invalid`. House caps no message, so the gateway alone
+  fits one to Telegram's rich message limits, 32,768 characters and 500 blocks:
+  a rich message past them is sent as consecutive messages in order, split
+  between blocks and inside a block only when that block alone exceeds them,
+  and reported once, `delivered` with the first message's id when every part
+  was delivered and otherwise with the answer of the first part that was not.
+  Each answer also names the `threads` the bot's topics carry, a
+  `conversation_id` with its `chat_id` and `topic_id`, which is where live
+  drafts go.
+
+Live drafts come from the control stream, not from House's queue. Run on its
+own, the command holds the Environment's [control stream](#the-kit-control-stream)
+for its lease; served by `kit resident`, it receives the draft and plan frames
+the resident's socket receives, through the resident, and never opens a second
+socket. The gateway Environment's socket carries every conversation bound to a
+topic of the bot, with no subscribe frame. The gateway keeps the latest view of
+each such conversation's turn: a frame that starts at block 0 replaces a view,
+the next frame in sequence applies from its `from`, and a frame after a gap in
+the sequence, or one for a turn it holds no view of, is applied nowhere and
+answered with one `gap` frame naming the conversation and turn, so House sends
+the whole view again. It renders each view as one Telegram draft per turn with
+`sendRichMessageDraft` on the bound topic, the live plan above the assistant
+text, under one draft id derived from the turn, because Telegram shows one bot
+draft per topic and a second id would replace the first. A view past the rich
+message limits is shortened inside that one draft, never split into a second.
+A live plan is part of the draft and never a sent message; the frozen plan
+House queues at the turn's end is the turn's one plan message. Drafts coalesce
+to the latest view, one Bot API call at a time, and are never reported back:
+the same bot-wide `retry_after` gate drops a draft while it is closed, and a
+draft answered with `retry_after` closes it. A closed gate drops a preview,
+never a durable delivery.
 
 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
@@ -1357,11 +1790,14 @@ so a restarted gateway never leaves a delivery attempted forever. A Telegram
 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.
+Each refused pass is printed as it happens, naming its activity, item and
+refusal code, so a gateway refused on every pass says so while it runs; the
+summary printed when it stops still lists each of them.
 
 Release the bot:
 
 ```sh
-kit telegram disconnect --house https://agents.house
+kit telegram disconnect
 ```
 
 The command writes a local disconnect marker first, deletes the webhook, removes
@@ -1386,11 +1822,22 @@ $HOUSE_KIT_HOME/
   state/repositories/<repository identity>.json
   state/sync/<replica identity>.json
   state/sync/<replica identity>.pending.json
+  state/working-copies/rooms/<room ref>.json
+  state/working-copies/private.json
   state/attachments/<upload identity>.json
   state/conversation-originals/<attachment identity>.json
   state/sessions/<tmux session>.json
+  state/update-drain
+  state/skill-set.json
+  state/how-we-work
   state/continuations/<run identity>.json
-  state/<instance>/credentials/google.json
+  state/google/entries/<source>.json
+  state/google/credentials/<account>.json
+  state/google/checkpoints/<source>.json
+  state/google/health/<source>.json
+  state/google/gaps/<source>.json
+  state/google/dropped/<source>.json
+  state/google/originals/<source>.json
   state/<instance>/checkpoints/<service>.json
   state/<instance>/health/<service>.json
   state/<instance>/gaps/<service>.json
@@ -1400,15 +1847,18 @@ $HOUSE_KIT_HOME/
 
 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.
+A Google entry's state is keyed by its Source reference and lives only while
+House lists the entry. Disabling a custom service or 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
+kit source reset acme        # every service
+kit source reset acme notes  # one service
 ```
 
-Reset is the only deletion of captured state. It removes the named checkpoints
+Reset serves custom connectors, and is the only deletion of their 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
@@ -1442,7 +1892,7 @@ 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
+kit host report
 ```
 
 The command reads `/proc/stat` twice a second apart, reads `/proc/meminfo`, and
@@ -1464,7 +1914,7 @@ Description=Report measured host capacity to House
 [Service]
 Type=oneshot
 User=house-kit
-ExecStart=/usr/bin/kit host report --house https://agents.house
+ExecStart=/usr/bin/kit host report
 ```
 
 ```
@@ -1513,11 +1963,10 @@ 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
+kit migrate mount /home/ada/exports/project --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
+  --subtree /private/library/another-project
 ```
 
 Emission refuses an existing output directory. The module reads one JSON line
@@ -1583,7 +2032,7 @@ 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 tree, independently retrieves and compares the saved bytes, and only
+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
@@ -1604,8 +2053,8 @@ 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 \
+kit migrate unmount /rooms/work/library/project
+kit migrate unmount /rooms/work/library/project \
   --confirm /rooms/work/library/project
 ```
 
@@ -1629,10 +2078,7 @@ 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
+docker compose -f test/compose.yaml run --rm kit npm run build
 ```
 
 `test/pair/run.sh` boots real Core, Auth and PostgreSQL and runs the installed
@@ -1662,6 +2108,19 @@ 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.
 
+Explicit sync has its own paired proof:
+
+```sh
+HOUSE_CORE_ROOT=<core checkout> HOUSE_AUTH_ROOT=<auth checkout> \
+  KIT_PAIR_SPECS=/kit/test/pair/sync.vitest.ts bash test/pair/run.sh
+```
+
+It proves that an accepted `submit`, answered or recovered after a lost answer,
+leaves each file's `_provenance` sidecar equal to the provenance House serves,
+and that a pending submission House answers `operation_expired` is pulled first,
+then sent again under a new identifier only if it never landed. Evidence is
+written to `tmp/delivery-evidence/sync-pair.json`.
+
 The retained-original consumers have their own paired proofs:
 
 ```sh