@agentshouse/kit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/README.md

@@ -10,7 +10,7 @@ On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
 versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.2/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.21/connect-linux.sh)
 ```
 
 The release asset pins one immutable multi-architecture image digest. It creates
@@ -20,12 +20,99 @@ 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.
+same container, credential and Environment.
+
+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 and agent CLI work, while the
+Sessions it supervises keep their renewal, owner stops, answers and reports.
+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
@@ -48,7 +135,8 @@ 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
@@ -575,6 +663,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 +768,13 @@ 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. 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
@@ -736,7 +837,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
@@ -819,8 +922,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
@@ -845,8 +948,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.
 
@@ -913,7 +1016,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
@@ -1062,10 +1170,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.
@@ -1104,15 +1229,161 @@ 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` when it starts, 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. On each pass, 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, 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 for the next pass. 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.
+
+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 \
@@ -1137,8 +1408,7 @@ Library paths are House metadata, not authored Library documents. `pull` present
 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.
+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
@@ -1179,7 +1449,7 @@ 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.
@@ -1386,9 +1656,12 @@ $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/continuations/<run identity>.json
   state/<instance>/credentials/google.json
   state/<instance>/checkpoints/<service>.json
@@ -1583,7 +1856,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

package/bin/connect-linux.sh

@@ -8,12 +8,47 @@ WORKSPACE="$HOME/AgentsHouse"
 MANUAL=0
 WORKSPACE_SELECTED=0
 HOUSE_SELECTED=0
+FORWARDING=0
+FORWARDED=kit
+FORWARD=()
 
 refuse() {
   printf 'kit_bootstrap_refused: %s\n' "$1" >&2
   exit 1
 }
 
+bind_mount() {
+  local source=${1//\"/\"\"}
+  printf 'type=bind,"src=%s",dst=%s' "$source" "$2"
+}
+
+login_kit() {
+  if [[ " $* " == *' --manual '* ]]; then
+    "${DOCKER_RUN[@]:0:2}" -i "${DOCKER_RUN[@]:2}" login "$@"
+    return
+  fi
+  command -v xdg-open >/dev/null || refuse 'no host browser opener; rerun with --manual'
+  "${DOCKER_RUN[@]}" login "$@" --host-browser | while IFS= read -r line; do
+    if [[ "$line" == 'Open '* ]]; then
+      printf 'Opening House Login in the host browser.\n'
+      xdg-open "${line#Open }" >/dev/null 2>&1 || refuse 'host browser did not open; rerun with --manual'
+    else
+      printf '%s\n' "$line"
+    fi
+  done
+}
+
+start_resident() {
+  docker run -d --name "$NAME" --restart unless-stopped --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --label "agentshouse.house=$HOUSE" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 "$IMAGE" resident --house "$HOUSE" >/dev/null
+}
+
+if [[ "${1:-}" == kit || "${1:-}" == house ]]; then
+  FORWARDING=1
+  FORWARDED="$1"
+  FORWARD=("${@:2}")
+  set --
+fi
+
 while (($#)); do
   case "$1" in
     --workspace|--house)
@@ -53,6 +88,10 @@ case "$DOCKER_PLATFORM" in
   *) refuse "unsupported Docker Engine platform $DOCKER_PLATFORM" ;;
 esac
 [[ "$DOCKER_ARCH" == "$ARCH" ]] || refuse "host linux/$ARCH does not match Docker Engine linux/$DOCKER_ARCH"
+if ((FORWARDING)); then
+  docker container inspect "$NAME" >/dev/null 2>&1 || refuse 'House Kit is not installed; run this bootstrap without arguments first'
+  WORKSPACE=$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/agents/house"}}{{.Source}}{{end}}{{end}}' "$NAME")
+fi
 
 umask 077
 KIT_HOME="$HOME/.house-kit"
@@ -65,6 +104,8 @@ for path in "$KIT_HOME" "$WORKSPACE"; do
 done
 KIT_HOME=$(cd "$KIT_HOME" && pwd -P)
 WORKSPACE=$(cd "$WORKSPACE" && pwd -P)
+KIT_HOME_MOUNT=$(bind_mount "$KIT_HOME" /kit-home)
+WORKSPACE_MOUNT=$(bind_mount "$WORKSPACE" /agents/house)
 if [[ -f "$KIT_HOME/credential" || -f "$KIT_HOME/environment" ]] && [[ ! -f "$KIT_HOME/house" ]]; then
   refuse 'stored House origin is missing for an enrolled Environment'
 fi
@@ -76,10 +117,11 @@ if [[ -f "$KIT_HOME/house" ]]; then
   HOUSE="$BOUND_HOUSE"
 fi
 [[ "$HOUSE" == https://* || "$HOUSE" == http://127.0.0.1:* || "$HOUSE" == http://localhost:* ]] || refuse 'House origin must use HTTPS or local loopback HTTP'
-DOCKER_RUN=(docker run --rm --network host --user "$(id -u):$(id -g)" --mount "type=bind,src=$KIT_HOME,dst=/kit-home" --mount "type=bind,src=$WORKSPACE,dst=/agents/house" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 --env "HOUSE_KIT_HOSTNAME=$(hostname)" "$IMAGE")
+DOCKER_RUN=(docker run --rm --network host --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 --env "HOUSE_KIT_HOSTNAME=$(hostname)" "$IMAGE")
 
 if docker container inspect "$NAME" >/dev/null 2>&1; then
-  [[ "$(docker inspect --format '{{.Config.Image}}' "$NAME")" == "$IMAGE" ]] || refuse 'an installed Kit uses a different image; update it explicitly'
+  INSTALLED_IMAGE=$(docker inspect --format '{{.Config.Image}}' "$NAME")
+  ((FORWARDING == 0)) || [[ "$INSTALLED_IMAGE" == "$IMAGE" ]] || refuse 'an installed Kit uses a different image; rerun this bootstrap without arguments to update it'
   [[ "$(docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' "$NAME")" == unless-stopped ]] || refuse 'the installed Kit has a different lifecycle'
   [[ "$(docker inspect --format '{{len .Mounts}}' "$NAME")" == 2 ]] || refuse 'the installed Kit has unexpected mounts'
   [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/kit-home"}}{{.Source}}{{end}}{{end}}' "$NAME")" == "$KIT_HOME" ]] || refuse 'the installed Kit uses another Kit home'
@@ -88,6 +130,44 @@ if docker container inspect "$NAME" >/dev/null 2>&1; then
   [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/agents/house"}}{{.Type}}/{{.RW}}{{end}}{{end}}' "$NAME")" == bind/true ]] || refuse 'the installed workspace is not a writable bind mount'
   [[ "$(docker inspect --format '{{index .Config.Labels "agentshouse.house"}}' "$NAME")" == "$HOUSE" ]] || refuse 'the installed Kit uses another House origin'
   [[ -f "$KIT_HOME/credential" && -f "$KIT_HOME/environment" && -f "$KIT_HOME/house" ]] || refuse 'the installed Kit has no enrolled authority'
+  if ((FORWARDING)); then
+    if [[ "$FORWARDED" == kit && "${FORWARD[0]:-}" == login ]]; then
+      login_kit "${FORWARD[@]:1}"
+      exit 0
+    fi
+    PLACED=()
+    ENTRY=()
+    if [[ "$FORWARDED" == house ]]; then
+      HERE=$(pwd -P)
+      [[ "$HERE" == "$WORKSPACE" || "$HERE" == "$WORKSPACE"/* ]] || refuse "the current directory is outside the workspace $WORKSPACE"
+      PLACED=(--workdir "/agents/house${HERE#"$WORKSPACE"}")
+      ENTRY=(--entrypoint house)
+    fi
+    TERMINAL=()
+    if [[ -t 0 && -t 1 ]]; then TERMINAL=(-t); fi
+    if [[ -t 0 && ! -t 1 ]]; then
+      ECHOED=$(stty -g)
+      trap 'stty "$ECHOED"' EXIT
+      stty -echo
+    fi
+    if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
+      docker exec -i "${TERMINAL[@]}" "${PLACED[@]}" "$NAME" "$FORWARDED" "${FORWARD[@]}"
+    else
+      "${DOCKER_RUN[@]:0:2}" -i "${TERMINAL[@]}" "${PLACED[@]}" "${ENTRY[@]}" "${DOCKER_RUN[@]:2}" "${FORWARD[@]}"
+    fi
+    exit
+  fi
+  if [[ "$INSTALLED_IMAGE" != "$IMAGE" ]]; then
+    docker pull --quiet --platform "linux/$ARCH" "$IMAGE" >/dev/null
+    if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
+      docker exec "$NAME" kit resident drain
+    fi
+    docker rm -f "$NAME" >/dev/null
+    rm -f "$KIT_HOME/state/update-drain"
+    start_resident
+    printf 'House Kit updated for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+    exit 0
+  fi
   "${DOCKER_RUN[@]}" credential check --house "$HOUSE"
   if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
     printf 'House Kit is already running for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
@@ -108,20 +188,12 @@ if [[ -f "$KIT_HOME/credential" ]]; then
   "${DOCKER_RUN[@]}" credential check --house "$HOUSE"
 else
   if ((MANUAL)); then
-    "${DOCKER_RUN[@]:0:2}" -i "${DOCKER_RUN[@]:2}" login --house "$HOUSE" --manual
+    login_kit --house "$HOUSE" --manual
   else
-    command -v xdg-open >/dev/null || refuse 'no host browser opener; rerun with --manual'
-    "${DOCKER_RUN[@]}" login --house "$HOUSE" --host-browser | while IFS= read -r line; do
-      if [[ "$line" == 'Open '* ]]; then
-        printf 'Opening House Login in the host browser.\n'
-        xdg-open "${line#Open }" >/dev/null 2>&1 || refuse 'host browser did not open; rerun with --manual'
-      else
-        printf '%s\n' "$line"
-      fi
-    done
+    login_kit --house "$HOUSE"
   fi
 fi
 
 "${DOCKER_RUN[@]}" apply --house "$HOUSE"
-docker run -d --name "$NAME" --restart unless-stopped --user "$(id -u):$(id -g)" --mount "type=bind,src=$KIT_HOME,dst=/kit-home" --mount "type=bind,src=$WORKSPACE,dst=/agents/house" --label "agentshouse.house=$HOUSE" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 "$IMAGE" resident --house "$HOUSE" >/dev/null
+start_resident
 printf 'House Kit connected for Environment %s.\n' "$(cat "$KIT_HOME/environment")"

package/bin/kit.js

@@ -9,7 +9,7 @@ import { setupEnvironment } from "../src/setup.js";
 import { signInConnector } from "../src/connector-login.js";
 import { attachSession } from "../src/attach.js";
 import { runResident, runWorkers } from "../src/worker.js";
-import { openSession, releaseControl } from "../src/house.js";
+import { openSession, releaseControl, requestDrain } from "../src/house.js";
 import { GOOGLE_OAUTH_CLIENT } from "../src/instance/google.js";
 import { reportHost } from "../src/host.js";
 import { signInAgent, updateAgents } from "../src/agents.js";
@@ -140,7 +140,7 @@ async function runCredentialCheck(args, directory) {
   const house = await selectedHouse(values, directory);
   let session;
   try {
-    session = await openSession({ house, directory });
+    session = await openSession({ house, directory, acquire: true });
   } catch (error) {
     if (error instanceof KitRefusal && error.code === "environment_control_lease_active") {
       write("Stored Kit authority is accepted; its Environment already has an active control lease.");
@@ -167,6 +167,23 @@ async function runResidentCommand(args, directory) {
   }
 }
 
+async function runResidentDrain(args, directory) {
+  declared(args, [], 0, { exact: true });
+  const answer = await requestDrain(directory);
+  if (answer.ready === true) {
+    write("House Kit is ready for its update.");
+    return;
+  }
+  write(
+    answer.sessions.length > 0
+      ? `House Kit is draining for its update and waits for Agent Sessions ${answer.sessions.join(", ")}.`
+      : answer.serving === true
+        ? "House Kit is draining for its update and waits for the Kit command it serves."
+        : `House Kit is draining for its update; House refused its lease release (${answer.refused}).`,
+  );
+  process.exitCode = 1;
+}
+
 async function runSetup(args, directory) {
   const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
   const house = await selectedHouse(values, directory);
@@ -965,7 +982,10 @@ async function main() {
   const directory = process.env.HOUSE_KIT_HOME ?? join(homedir(), ".house-kit");
   if (command === "login") return runLogin(args, directory);
   if (command === "credential" && args[0] === "check") return runCredentialCheck(args.slice(1), directory);
-  if (command === "resident") return runResidentCommand(args, directory);
+  if (command === "resident") {
+    if (args[0] === "drain") return runResidentDrain(args.slice(1), directory);
+    return runResidentCommand(args, directory);
+  }
   if (command === "setup") return runSetup(args, directory);
   if (command === "apply") return runApply(args, directory);
   if (command === "worker") {