@agentshouse/kit 0.1.0-alpha.37 → 0.1.0-alpha.39

package/README.md

@@ -13,13 +13,13 @@ The Skill set Kit installs is Matt Pocock's
 Linux (`amd64`, `arm64`) or macOS (Apple silicon, Intel):
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.37/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.39/connect-linux.sh)
 ```
 
 Windows 11 (`amd64`), in PowerShell:
 
 ```powershell
-& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.37/connect-windows.ps1)))
+& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.39/connect-windows.ps1)))
 ```
 
 The command sets up Docker if it is missing, creates `~/.house-kit` (Kit home)

package/bin/connect-linux.sh

@@ -21,6 +21,15 @@ RUNTIME='Docker Engine'
 OPENER=xdg-open
 NETWORK=(--network host)
 PUBLISHED=()
+AVAILABILITY=intermittent
+NATIVE=0
+NATIVE_RELEASE=26.04
+NATIVE_ARCHITECTURE=amd64
+NATIVE_PACKAGES=(git tmux)
+NATIVE_PREFIX=/opt/house-kit
+NATIVE_SERVICE=house-kit.service
+NATIVE_UNIT=/etc/systemd/system/house-kit.service
+NATIVE_WORKSPACE=/agents/house
 
 refuse() {
   printf 'kit_bootstrap_refused: %s\n' "$1" >&2
@@ -32,13 +41,25 @@ bind_mount() {
   printf 'type=bind,"src=%s",dst=%s' "$source" "$2"
 }
 
+native_kit() {
+  PATH="$NATIVE_PREFIX/bin:$PATH" HOUSE_KIT_HOME="$KIT_HOME" "$NATIVE_PREFIX/bin/node" "$NATIVE_PREFIX/bin/$1" "${@:2}"
+}
+
 login_kit() {
   if [[ " $* " == *' --manual '* ]]; then
-    "${DOCKER_RUN[@]:0:2}" -i "${DOCKER_RUN[@]:2}" login "$@"
+    if ((NATIVE)); then
+      native_kit kit login "$@"
+    else
+      "${DOCKER_RUN[@]:0:2}" -i "${DOCKER_RUN[@]:2}" login "$@"
+    fi
     return
   fi
   command -v "$OPENER" >/dev/null || refuse 'no host browser opener; rerun with --manual'
-  "${DOCKER_RUN[@]:0:2}" ${PUBLISHED[@]+"${PUBLISHED[@]}"} "${DOCKER_RUN[@]:2}" login "$@" --host-browser | while IFS= read -r line; do
+  if ((NATIVE)); then
+    native_kit kit login "$@" --host-browser
+  else
+    "${DOCKER_RUN[@]:0:2}" ${PUBLISHED[@]+"${PUBLISHED[@]}"} "${DOCKER_RUN[@]:2}" login "$@" --host-browser
+  fi | while IFS= read -r line; do
     if [[ "$line" == 'Open '* ]]; then
       printf 'Opening House Login in the host browser.\n'
       "$OPENER" "${line#Open }" >/dev/null 2>&1 || refuse 'host browser did not open; rerun with --manual'
@@ -169,6 +190,204 @@ establish_docker_engine() {
   docker_answers || refuse "Docker Engine does not answer: $(docker_cause)"
 }
 
+check_native_host() {
+  local distribution='' release='' described=macOS
+  if [[ "$RUNTIME" == 'Docker Engine' ]]; then
+    described=Linux
+    if [[ -r /etc/os-release ]]; then
+      distribution=$(. /etc/os-release && printf '%s' "${ID:-}")
+      release=$(. /etc/os-release && printf '%s' "${VERSION_ID:-}")
+      described=$(. /etc/os-release && printf '%s' "${PRETTY_NAME:-$described}")
+    fi
+  fi
+  [[ "$distribution" == ubuntu && "$release" == "$NATIVE_RELEASE" && "$ARCH" == "$NATIVE_ARCHITECTURE" ]] ||
+    refuse "--linux runs only on Ubuntu $NATIVE_RELEASE LTS on $NATIVE_ARCHITECTURE, not $described on $ARCH"
+}
+
+
+establish_native_packages() {
+  local present
+  present=$(installed_packages "${NATIVE_PACKAGES[@]}" | wc -l)
+  ((present == ${#NATIVE_PACKAGES[@]})) && return
+  printf 'Installing git and tmux from Ubuntu'\''s apt repository; sudo may ask for your password.\n'
+  elevated apt-get update -qq >/dev/null || refuse 'apt could not refresh its package lists'
+  elevated apt-get install -y -qq "${NATIVE_PACKAGES[@]}" >/dev/null || refuse 'apt could not install git and tmux'
+}
+
+stage_native_kit() {
+  local copy
+  NATIVE_STAGE=$(mktemp -d) || refuse 'no temporary directory for the Kit package'
+  trap 'rm -rf "$NATIVE_STAGE"' EXIT
+  docker pull --quiet --platform "linux/$ARCH" "$IMAGE" >/dev/null
+  copy=$(docker create --platform "linux/$ARCH" "$IMAGE") || refuse 'the Kit image could not be opened'
+  mkdir "$NATIVE_STAGE/bin" "$NATIVE_STAGE/lib"
+  if ! docker cp --quiet "$copy:/usr/local/bin/node" "$NATIVE_STAGE/bin/node" ||
+    ! docker cp --quiet "$copy:/usr/local/lib/node_modules" "$NATIVE_STAGE/lib/node_modules"; then
+    docker rm "$copy" >/dev/null 2>&1 || true
+    refuse 'the Kit package could not be copied from its image'
+  fi
+  docker rm "$copy" >/dev/null
+  ln -s ../lib/node_modules/@agentshouse/kit/bin/kit.js "$NATIVE_STAGE/bin/kit"
+  ln -s ../lib/node_modules/@agentshouse/kit/src/session-bin/house "$NATIVE_STAGE/bin/house"
+  ln -s ../lib/node_modules/npm/bin/npm-cli.js "$NATIVE_STAGE/bin/npm"
+  ln -s ../lib/node_modules/npm/bin/npx-cli.js "$NATIVE_STAGE/bin/npx"
+  printf '%s\n' "$IMAGE" > "$NATIVE_STAGE/image"
+  chmod 0755 "$NATIVE_STAGE" "$NATIVE_STAGE/bin" "$NATIVE_STAGE/lib"
+  chmod 0644 "$NATIVE_STAGE/image"
+}
+
+place_native_kit() {
+  printf 'Installing House Kit in %s; sudo may ask for your password.\n' "$NATIVE_PREFIX"
+  elevated rm -rf "$NATIVE_PREFIX" && elevated mv "$NATIVE_STAGE" "$NATIVE_PREFIX" && elevated chown -R root:root "$NATIVE_PREFIX" ||
+    refuse "House Kit could not be installed in $NATIVE_PREFIX"
+}
+
+start_native_service() {
+  printf '[Unit]\nDescription=House Kit\nWants=network-online.target\nAfter=network-online.target docker.service\n\n[Service]\nUser=%s\nWorkingDirectory=%s\nEnvironment=PATH=%s/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\nExecStart=%s/bin/node %s/bin/kit resident\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\n' \
+    "$(id -un)" "$NATIVE_WORKSPACE" "$NATIVE_PREFIX" "$NATIVE_PREFIX" "$NATIVE_PREFIX" | elevated tee "$NATIVE_UNIT" >/dev/null &&
+    elevated chmod 0644 "$NATIVE_UNIT" || refuse "$NATIVE_UNIT could not be written"
+  elevated systemctl daemon-reload || refuse 'systemd could not read the House Kit service'
+  elevated systemctl --quiet enable --now "$NATIVE_SERVICE" || refuse 'the House Kit service could not be started'
+}
+
+run_kit() {
+  if ((NATIVE)); then
+    native_kit kit "$@"
+  else
+    "${DOCKER_RUN[@]}" "$@"
+  fi
+}
+
+kit_running() {
+  if ((NATIVE)); then
+    systemctl is-active --quiet "$NATIVE_SERVICE"
+  else
+    [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]
+  fi
+}
+
+kit_installed() {
+  if ((NATIVE)); then
+    [[ -f "$NATIVE_UNIT" ]]
+  else
+    docker container inspect "$NAME" >/dev/null 2>&1
+  fi
+}
+
+installed_image() {
+  if ((NATIVE == 0)); then
+    docker inspect --format '{{.Config.Image}}' "$NAME"
+  elif [[ -f "$NATIVE_PREFIX/image" ]]; then
+    cat "$NATIVE_PREFIX/image"
+  fi
+}
+
+check_installation() {
+  if ((NATIVE)); then
+    grep -qx "User=$(id -un)" "$NATIVE_UNIT" || refuse 'House Kit runs natively on this host for another account'
+    return
+  fi
+  [[ "$(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'
+  [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/kit-home"}}{{.Type}}/{{.RW}}{{end}}{{end}}' "$NAME")" == bind/true ]] || refuse 'the installed Kit home is not a writable bind mount'
+  [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/agents/house"}}{{.Source}}{{end}}{{end}}' "$NAME")" == "$WORKSPACE" ]] || refuse 'the installed Kit uses another workspace root'
+  [[ "$(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'
+}
+
+forward_kit() {
+  if ((NATIVE)); then
+    native_kit "$FORWARDED" ${FORWARD[@]+"${FORWARD[@]}"}
+    return
+  fi
+  local placed=() entry=() terminal=() here
+  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
+  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 kit_running; then
+    docker exec -i ${terminal[@]+"${terminal[@]}"} ${placed[@]+"${placed[@]}"} "$NAME" "$FORWARDED" ${FORWARD[@]+"${FORWARD[@]}"}
+  else
+    "${DOCKER_RUN[@]:0:2}" -i ${terminal[@]+"${terminal[@]}"} ${placed[@]+"${placed[@]}"} ${entry[@]+"${entry[@]}"} "${DOCKER_RUN[@]:2}" ${FORWARD[@]+"${FORWARD[@]}"}
+  fi
+}
+
+start_kit() {
+  if ((NATIVE)); then
+    start_native_service
+  else
+    start_resident
+  fi
+}
+
+update_kit() {
+  local stopped=0
+  if ((NATIVE)); then
+    stage_native_kit
+  else
+    docker pull --quiet --platform "linux/$ARCH" "$IMAGE" >/dev/null
+  fi
+  if ! kit_running; then
+    stopped=1
+  elif ((NATIVE)); then
+    native_kit kit resident drain
+  else
+    docker exec "$NAME" kit resident drain
+  fi
+  if ((NATIVE)); then
+    elevated systemctl stop "$NATIVE_SERVICE" || refuse 'the House Kit service could not be stopped'
+    place_native_kit
+  else
+    docker rm -f "$NAME" >/dev/null
+  fi
+  rm -f "$KIT_HOME/state/update-drain"
+  ((stopped == 0)) || run_kit credential check
+  start_kit
+  printf 'House Kit updated for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+}
+
+resume_kit() {
+  run_kit credential check
+  if kit_running; then
+    printf 'House Kit is already running for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+    return
+  fi
+  if ((NATIVE)); then
+    elevated systemctl start "$NATIVE_SERVICE" || refuse 'the House Kit service could not be started'
+  else
+    docker start "$NAME" >/dev/null
+  fi
+  printf 'House Kit restarted for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+}
+
+connect_kit() {
+  if [[ -f "$KIT_HOME/credential" ]]; then
+    run_kit credential check
+  else
+    local login=()
+    if ((HOUSE_SELECTED)); then login+=(--house "$HOUSE"); fi
+    if ((MANUAL)); then login+=(--manual); fi
+    login_kit ${login[@]+"${login[@]}"}
+  fi
+  run_kit apply
+  start_kit
+  printf 'House Kit connected for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+}
+
+if [[ "${1:-}" == --linux && ( "${2:-}" == kit || "${2:-}" == house ) ]]; then
+  NATIVE=1
+  shift
+fi
+
 if [[ "${1:-}" == kit || "${1:-}" == house ]]; then
   FORWARDING=1
   FORWARDED="$1"
@@ -199,9 +418,20 @@ while (($#)); do
       SKILLS=false
       shift
       ;;
+    --linux)
+      NATIVE=1
+      shift
+      ;;
     *) refuse "unknown argument $1" ;;
   esac
 done
+if ((NATIVE)); then
+  ((WORKSPACE_SELECTED == 0)) || refuse "--linux keeps its workspace at $NATIVE_WORKSPACE; --workspace is for a container"
+  WORKSPACE=$NATIVE_WORKSPACE
+  AVAILABILITY=continuous
+elif [[ -e "$NATIVE_UNIT" ]]; then
+  refuse 'House Kit runs natively on this host; rerun this bootstrap with --linux'
+fi
 
 [[ "$IMAGE" =~ ^ghcr\.io/agentshouse/kit@sha256:[0-9a-f]{64}$ ]] || refuse 'this bootstrap has not been published with an immutable image digest'
 case "$(uname -s)" in
@@ -225,21 +455,36 @@ case "$(uname -s)" in
     ;;
   *) refuse "unsupported host $(uname -s); this bootstrap is for Linux and macOS" ;;
 esac
+((NATIVE == 0)) || check_native_host
 [[ "$WORKSPACE" == /* ]] || refuse 'workspace root must be an absolute path'
-if [[ "$RUNTIME" == 'Docker Desktop' ]]; then
-  establish_docker_desktop "$CHIP"
-  DOCKER_SYSTEM=$(docker info --format '{{.OperatingSystem}}' 2>/dev/null) || refuse "Docker Desktop does not answer: $(docker_cause)"
-  [[ "$DOCKER_SYSTEM" == 'Docker Desktop' ]] || refuse "Docker answers from $DOCKER_SYSTEM, not Docker Desktop; stop that engine or switch Docker to Docker Desktop, then rerun this bootstrap"
+if ((NATIVE && FORWARDING)); then
+  [[ -f "$NATIVE_UNIT" ]] || refuse 'House Kit is not installed; run this bootstrap with --linux first'
 else
-  establish_docker_engine
+  if [[ "$RUNTIME" == 'Docker Desktop' ]]; then
+    establish_docker_desktop "$CHIP"
+    DOCKER_SYSTEM=$(docker info --format '{{.OperatingSystem}}' 2>/dev/null) || refuse "Docker Desktop does not answer: $(docker_cause)"
+    [[ "$DOCKER_SYSTEM" == 'Docker Desktop' ]] || refuse "Docker answers from $DOCKER_SYSTEM, not Docker Desktop; stop that engine or switch Docker to Docker Desktop, then rerun this bootstrap"
+  else
+    establish_docker_engine
+  fi
+  case "$DOCKER_PLATFORM" in
+    linux/x86_64|linux/amd64) DOCKER_ARCH=amd64 ;;
+    linux/aarch64|linux/arm64) DOCKER_ARCH=arm64 ;;
+    *) refuse "unsupported $RUNTIME platform $DOCKER_PLATFORM" ;;
+  esac
+  [[ "$DOCKER_ARCH" == "$ARCH" ]] || refuse "host linux/$ARCH does not match $RUNTIME linux/$DOCKER_ARCH"
 fi
-case "$DOCKER_PLATFORM" in
-  linux/x86_64|linux/amd64) DOCKER_ARCH=amd64 ;;
-  linux/aarch64|linux/arm64) DOCKER_ARCH=arm64 ;;
-  *) refuse "unsupported $RUNTIME platform $DOCKER_PLATFORM" ;;
-esac
-[[ "$DOCKER_ARCH" == "$ARCH" ]] || refuse "host linux/$ARCH does not match $RUNTIME linux/$DOCKER_ARCH"
-if ((FORWARDING)); then
+if ((NATIVE)); then
+  if ((FORWARDING == 0)) && docker container inspect "$NAME" >/dev/null 2>&1; then
+    refuse "House Kit runs in the container $NAME on this computer; remove that container, then rerun this bootstrap with --linux"
+  fi
+  [[ ! -L "${NATIVE_WORKSPACE%/*}" ]] || refuse "${NATIVE_WORKSPACE%/*} is a symbolic link"
+  if [[ ! -e "$NATIVE_WORKSPACE" && ! -L "$NATIVE_WORKSPACE" ]]; then
+    printf 'Creating %s for the Agents on this host; sudo may ask for your password.\n' "$NATIVE_WORKSPACE"
+    { [[ -d "${NATIVE_WORKSPACE%/*}" ]] || elevated install -d -m 0755 "${NATIVE_WORKSPACE%/*}"; } &&
+      elevated install -d -m 0700 -o "$(id -u)" -g "$(id -g)" "$NATIVE_WORKSPACE" || refuse "$NATIVE_WORKSPACE could not be created"
+  fi
+elif ((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
@@ -270,92 +515,61 @@ fi
 [[ "$HOUSE" == https://* || "$HOUSE" == http://127.0.0.1:* || "$HOUSE" == http://localhost:* ]] || refuse 'House origin must use HTTPS or local loopback HTTP'
 if ((FORWARDING == 0)); then
   if [[ ! -f "$KIT_HOME/kit.json" ]]; then
-    printf '{"availability":"intermittent","execution_authority":"allow","migrators":[],"instances":[],"clients":[],"host":null,"skills":%s}\n' "$SKILLS" > "$KIT_HOME/kit.json"
+    printf '{"availability":"%s","execution_authority":"allow","migrators":[],"instances":[],"clients":[],"host":null,"skills":%s}\n' "$AVAILABILITY" "$SKILLS" > "$KIT_HOME/kit.json"
   elif grep -Eq '"skills"[[:space:]]*:' "$KIT_HOME/kit.json"; then
     sed -E -i.old "s/(\"skills\"[[:space:]]*:[[:space:]]*)(true|false)/\\1$SKILLS/" "$KIT_HOME/kit.json" || refuse 'kit.json could not be updated'
   else
     sed -E -i.old "1s/^([[:space:]]*)\\{/\\1{\"skills\":$SKILLS,/" "$KIT_HOME/kit.json" || refuse 'kit.json could not be updated'
   fi
+  if ((NATIVE)); then
+    sed -E -i.old "s/(\"availability\"[[:space:]]*:[[:space:]]*)\"[^\"]*\"/\\1\"$AVAILABILITY\"/" "$KIT_HOME/kit.json" || refuse 'kit.json could not be updated'
+  fi
   rm -f "$KIT_HOME/kit.json.old"
   grep -Eq "\"skills\"[[:space:]]*:[[:space:]]*$SKILLS" "$KIT_HOME/kit.json" || refuse 'kit.json could not be updated'
+  ((NATIVE == 0)) || grep -Eq "\"availability\"[[:space:]]*:[[:space:]]*\"$AVAILABILITY\"" "$KIT_HOME/kit.json" || refuse 'kit.json could not be updated'
 fi
-if [[ "$RUNTIME" == 'Docker Desktop' && "$HOUSE" == https://* ]]; then
-  NETWORK=()
-  LOGIN_PORT=$((49152 + RANDOM % 16384))
-  PUBLISHED=(--publish "127.0.0.1:$LOGIN_PORT:$LOGIN_PORT" --env "HOUSE_KIT_LOGIN_PORT=$LOGIN_PORT")
+
+if ((NATIVE)); then
+  RERUN='with --linux'
+else
+  RERUN='without arguments'
+  if [[ "$RUNTIME" == 'Docker Desktop' && "$HOUSE" == https://* ]]; then
+    NETWORK=()
+    LOGIN_PORT=$((49152 + RANDOM % 16384))
+    PUBLISHED=(--publish "127.0.0.1:$LOGIN_PORT:$LOGIN_PORT" --env "HOUSE_KIT_LOGIN_PORT=$LOGIN_PORT")
+  fi
+  DOCKER_RUN=(docker run --rm ${NETWORK[@]+"${NETWORK[@]}"} --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")
 fi
-DOCKER_RUN=(docker run --rm ${NETWORK[@]+"${NETWORK[@]}"} --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
-  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'
-  [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/kit-home"}}{{.Type}}/{{.RW}}{{end}}{{end}}' "$NAME")" == bind/true ]] || refuse 'the installed Kit home is not a writable bind mount'
-  [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/agents/house"}}{{.Source}}{{end}}{{end}}' "$NAME")" == "$WORKSPACE" ]] || refuse 'the installed Kit uses another workspace root'
-  [[ "$(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'
+if kit_installed; then
+  check_installation
   [[ -f "$KIT_HOME/credential" && -f "$KIT_HOME/environment" && -f "$KIT_HOME/house" ]] || refuse 'the installed Kit has no enrolled authority'
   if ((FORWARDING)); then
+    [[ "$(installed_image)" == "$IMAGE" ]] || refuse "an installed Kit uses a different image; rerun this bootstrap $RERUN to update it"
     if [[ "$FORWARDED" == kit && "${FORWARD[0]:-}" == login ]]; then
       login_kit ${FORWARD[@]+"${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[@]+"${TERMINAL[@]}"} ${PLACED[@]+"${PLACED[@]}"} "$NAME" "$FORWARDED" ${FORWARD[@]+"${FORWARD[@]}"}
-    else
-      "${DOCKER_RUN[@]:0:2}" -i ${TERMINAL[@]+"${TERMINAL[@]}"} ${PLACED[@]+"${PLACED[@]}"} ${ENTRY[@]+"${ENTRY[@]}"} "${DOCKER_RUN[@]:2}" ${FORWARD[@]+"${FORWARD[@]}"}
-    fi
+    forward_kit
     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
-  if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
-    printf 'House Kit is already running for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+  ((NATIVE == 0)) || establish_native_packages
+  if [[ "$(installed_image)" != "$IMAGE" ]]; then
+    update_kit
   else
-    docker start "$NAME" >/dev/null
-    printf 'House Kit restarted for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+    resume_kit
   fi
+  ((NATIVE == 0)) || native_kit kit workspace update
   exit 0
 fi
 
-docker pull --quiet --platform "linux/$ARCH" "$IMAGE" >/dev/null
-
-if [[ -f "$KIT_HOME/credential" ]]; then
-  "${DOCKER_RUN[@]}" credential check
+if ((NATIVE)); then
+  establish_native_packages
+  if [[ "$(installed_image)" != "$IMAGE" ]]; then
+    stage_native_kit
+    place_native_kit
+  fi
 else
-  LOGIN=()
-  if ((HOUSE_SELECTED)); then LOGIN+=(--house "$HOUSE"); fi
-  if ((MANUAL)); then LOGIN+=(--manual); fi
-  login_kit ${LOGIN[@]+"${LOGIN[@]}"}
+  docker pull --quiet --platform "linux/$ARCH" "$IMAGE" >/dev/null
 fi
-
-"${DOCKER_RUN[@]}" apply
-start_resident
-printf 'House Kit connected for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
+connect_kit

package/bin/connect-windows.ps1

@@ -364,7 +364,7 @@ function Connect-Kit {
         $entry = @('--entrypoint', 'house')
       }
       $terminal = @()
-      if (-not [Console]::IsInputRedirected -and -not [Console]::IsOutputRedirected) { $terminal = @('-t') }
+      if (-not [Console]::IsInputRedirected) { $terminal = @('-t') }
       if ((Read-Inspect '{{.State.Running}}') -ceq 'true') {
         & docker exec -i @terminal @placed $Name $Forwarded @Forward
       } else {

package/bin/kit.js

@@ -13,7 +13,7 @@ import { runResident, runWorkers } from "../src/worker.js";
 import { openSession, releaseControl, requestDrain } from "../src/house.js";
 import { reportHost } from "../src/host.js";
 import { signInAgent, updateAgents } from "../src/agents.js";
-import { serveWorkspaces } from "../src/workspace.js";
+import { serveWorkspaces, updateWorkspaces } from "../src/workspace.js";
 import { captureRepository } from "../src/repository.js";
 import { bootstrap, pull, rebootstrap, submit } from "../src/sync.js";
 import { formatMount, formatUnmount, mountPackage, unmountSubtree } from "../src/mount.js";
@@ -35,7 +35,7 @@ const LOGIN_USAGE =
 const HOST_USAGE = "usage: kit host report [--config <path>]";
 const AGENTS_USAGE =
   "usage: kit agents update [--config <path>] | kit agents sign-in <kind> [--config <path>]";
-const WORKSPACE_USAGE = "usage: kit workspace host [--config <path>] [--passes <count>]";
+const WORKSPACE_USAGE = "usage: kit workspace host [--config <path>] [--passes <count>] | kit workspace update";
 const SOURCE_USAGE =
   "usage: kit source <capture|status> <account|instance> [service] [--config <path>]\n" +
   "       kit source <reset|retry-files> <instance> [service] [--config <path>]\n" +
@@ -895,6 +895,21 @@ async function runWorkspaceHost(args, directory) {
   }
 }
 
+async function runWorkspaceUpdate(args, directory) {
+  declared(args, [], 0, { exact: true });
+  const answered = await updateWorkspaces({
+    house: await storedHouse(directory),
+    configuration: join(directory, "kit.json"),
+  });
+  for (const { workspace, running } of answered.updated) {
+    write(running ? `Updated workspace ${workspace}.` : `Updated workspace ${workspace}; it stays stopped.`);
+  }
+  for (const { workspace, cause } of answered.unchanged) {
+    write(`Workspace ${workspace} is unchanged: ${cause}`);
+  }
+  if (answered.unchanged.length > 0) process.exitCode = 1;
+}
+
 async function runTelegramConnect(args, directory) {
   declared(args, [], 0, { exact: true });
   const house = await storedHouse(directory);
@@ -1027,6 +1042,7 @@ async function main() {
   if (command === "workspace") {
     const [action, ...rest] = args;
     if (action === "host") return runWorkspaceHost(rest, directory);
+    if (action === "update") return runWorkspaceUpdate(rest, directory);
     throw new Error(WORKSPACE_USAGE);
   }
   if (command === "telegram") {

package/bootstrap.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.37",
+  "version": "0.1.0-alpha.39",
   "hosts": {
     "linux": {
-      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.37/connect-linux.sh)",
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.39/connect-linux.sh)",
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.37/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.39/connect-linux.sh"
       },
       "workspace": {
         "argument": "--workspace",
@@ -14,10 +14,10 @@
       }
     },
     "windows": {
-      "command": "& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.37/connect-windows.ps1)))",
+      "command": "& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.39/connect-windows.ps1)))",
       "asset": {
         "name": "connect-windows.ps1",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.37/connect-windows.ps1"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.39/connect-windows.ps1"
       },
       "workspace": {
         "argument": "--workspace",

package/docs/linux.md

@@ -44,3 +44,34 @@ bash <(curl -fsSL …/connect-linux.sh) house git push --owner
 
 `--house http://127.0.0.1:<port>` or `--house http://localhost:<port>` runs Kit
 on the host network so it can reach a House served on this computer.
+
+## An Always-on server that hosts containers
+
+An Always-on Ubuntu server that will run persistent container Environments
+connects natively instead of in a container. Run the command with `--linux`:
+
+```sh
+bash <(curl -fsSL …/connect-linux.sh) --linux
+```
+
+It needs Ubuntu 26.04 LTS on `amd64`; any other host is refused. Every other
+computer takes the ordinary command. It sets up:
+
+- Docker Engine, as above, and `git` and `tmux` from Ubuntu's apt repository.
+- `/opt/house-kit`: House Kit and the Node.js it runs on, copied from the
+  release's image and owned by root.
+- `~/.house-kit`: Kit home, readable only by you.
+- `/agents/house`: your Agents' workspace, readable only by you.
+- `house-kit.service`: the systemd service that runs Kit as you and starts it
+  with the server.
+
+The server connects as a continuous Environment. Put `--linux` before `kit` or
+`house` to run a Kit command, as in
+`bash <(curl -fsSL …/connect-linux.sh) --linux kit apply`, and run a newer
+release's command with `--linux` to update it, as above.
+
+The same run updates the container Environments the server hosts to that
+release. A running one waits, and is named, until its own Agent sessions end;
+run the command again then. A stopped one is updated and stays stopped. Each
+keeps its files, sign-ins and CPU, memory and disk limits; only what was
+installed outside its workspace and Kit home is not kept.

package/docs/windows.md

@@ -30,8 +30,7 @@ refused.
 
 - Append `kit` and a command to run it, as on [Linux](linux.md). Each run
   leaves its exit status in `$LASTEXITCODE`.
-- When a command asks for a secret, such as a Telegram bot token, keep its
-  output on the terminal: with output redirected, what you type is echoed.
+- A command whose output is redirected also writes its prompts and errors there.
 - A House on this computer needs host networking enabled in Docker Desktop's
   settings.
 - This bootstrap has not yet been run on a real Windows computer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.37",
+  "version": "0.1.0-alpha.39",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/configuration.js

@@ -160,12 +160,11 @@ function maximaOf(value, declaration) {
 
 function hostOf(value, declaration) {
   if (value === null) return null;
-  const host = closed(value, ["workspace", "maxima", "image"], declaration);
+  const host = closed(value, ["workspace", "maxima"], declaration);
   if (host.maxima === undefined) refuse(`${declaration}.maxima`);
   return {
     workspace: absolutePath(host.workspace, `${declaration}.workspace`),
     maxima: maximaOf(host.maxima, `${declaration}.maxima`),
-    image: host.image === undefined || host.image === null ? null : text(host.image, `${declaration}.image`, 255),
   };
 }
 

package/src/contract.js

@@ -276,16 +276,20 @@ export const KIT_WORKSPACES_ACQUIRE_PATH = "/kit/workspaces/acquire";
 export const WORKSPACE_ACQUIRE_MAX = 10;
 export const WORKSPACE_POLL_MS = 2_000;
 export const WORKSPACE_LABEL = "house-kit.workspace";
-export const WORKSPACE_MOUNT = "/workspace";
-export const WORKSPACE_KIT_HOME = "/workspace/.house-kit";
+export const WORKSPACE_KIT_HOME = "/kit-home";
 export const WORKSPACE_DISK_IMAGE = "disk.img";
 export const WORKSPACE_DISK_MOUNT = "mnt";
+export const WORKSPACE_DISK_KIT_HOME = "kit-home";
+export const WORKSPACE_DISK_HOUSE = "house";
+export const WORKSPACE_SELECTED_IMAGE = "/opt/house-kit/image";
+export const WORKSPACE_RELEASE_IMAGE = /^ghcr\.io\/agentshouse\/kit@sha256:[0-9a-f]{64}$/;
 export const WORKSPACE_MOUNT_OPTIONS = "loop,nosuid,nodev";
 export const HOST_MOUNT_INFO = "/proc/self/mountinfo";
 export const WORKSPACE_SYSTEM_RESERVE_BYTES = 512 * 1024 * 1024;
 export const WORKSPACE_COMMAND_TIMEOUT_MS = 120_000;
 export const WORKSPACE_READY_ATTEMPTS = 60;
 export const WORKSPACE_READY_POLL_MS = 1_000;
+export const WORKSPACE_LOCK_POLL_MS = 1_000;
 export const WORKSPACE_STOP_TIMEOUT_SECONDS = 10;
 export const WORKSPACE_OPERATION_WITHDRAWN = "hosted_environment_operation_not_found";
 export const CGROUP_CONTROLLERS = "/sys/fs/cgroup/cgroup.controllers";

package/src/workspace.js

@@ -1,22 +1,28 @@
 import { access, mkdir, readFile, rm } from "node:fs/promises";
+import { createServer } from "node:net";
 import { join } from "node:path";
 import { readConfiguration } from "./configuration.js";
 import {
   CGROUP_CONTROLLERS,
   HOST_MOUNT_INFO,
+  LAUNCH_DIRECTORY_BASE,
   LOOP_CONTROL,
   WORKSPACE_ACQUIRE_MAX,
   WORKSPACE_COMMAND_TIMEOUT_MS,
+  WORKSPACE_DISK_HOUSE,
   WORKSPACE_DISK_IMAGE,
+  WORKSPACE_DISK_KIT_HOME,
   WORKSPACE_DISK_MOUNT,
   WORKSPACE_KIT_HOME,
   WORKSPACE_MOUNT_OPTIONS,
   WORKSPACE_LABEL,
-  WORKSPACE_MOUNT,
+  WORKSPACE_LOCK_POLL_MS,
   WORKSPACE_OPERATION_WITHDRAWN,
   WORKSPACE_POLL_MS,
   WORKSPACE_READY_ATTEMPTS,
   WORKSPACE_READY_POLL_MS,
+  WORKSPACE_RELEASE_IMAGE,
+  WORKSPACE_SELECTED_IMAGE,
   WORKSPACE_STOP_TIMEOUT_SECONDS,
   WORKSPACE_SYSTEM_RESERVE_BYTES,
 } from "./contract.js";
@@ -27,10 +33,13 @@ import {
   openSession,
   releaseControl,
   reportWorkspaceOutcome,
+  updateDrain,
 } from "./house.js";
 import { houseFailed, KitRefusal } from "./refusal.js";
 
 const REQUIRED_CONTROLLERS = ["cpu", "memory"];
+const PROVISIONED_DISK = "/disk";
+const STOPPED_STATES = ["created", "exited"];
 const MEMINFO = "/proc/meminfo";
 const MEM_AVAILABLE = /^MemAvailable:\s+(\d+)\s+kB$/m;
 
@@ -106,30 +115,35 @@ export function mountedPaths(document) {
   );
 }
 
-export function workspaceCreateArguments(identity, operation, image, house, root) {
+export function workspaceCreateArguments(identity, workspace, image, house, root) {
+  const disk = workspaceMountPath(root, identity);
   return [
     "create",
     "--name",
     identity,
     "--label",
-    `${WORKSPACE_LABEL}=${operation.environment}`,
+    `${WORKSPACE_LABEL}=${workspace.environment}`,
     "--cpus",
-    (operation.maxima.cpu_millicores / 1000).toFixed(3),
+    (workspace.maxima.cpu_millicores / 1000).toFixed(3),
     "--memory",
-    `${operation.maxima.memory_bytes}b`,
+    `${workspace.maxima.memory_bytes}b`,
     "--memory-swap",
-    `${operation.maxima.memory_bytes}b`,
+    `${workspace.maxima.memory_bytes}b`,
     "--restart",
     "no",
+    ...(new URL(house).protocol === "https:" ? [] : ["--network", "host"]),
     "--mount",
-    `type=bind,source=${workspaceMountPath(root, identity)},target=${WORKSPACE_MOUNT}`,
+    `type=bind,source=${disk}/${WORKSPACE_DISK_KIT_HOME},target=${WORKSPACE_KIT_HOME}`,
+    "--mount",
+    `type=bind,source=${disk}/${WORKSPACE_DISK_HOUSE},target=${LAUNCH_DIRECTORY_BASE}`,
+    "--env",
+    `HOME=${WORKSPACE_KIT_HOME}`,
     "--env",
     `HOUSE_KIT_HOME=${WORKSPACE_KIT_HOME}`,
     "--env",
-    `HOUSE_KIT_HOUSE=${house}`,
-    "--workdir",
-    WORKSPACE_MOUNT,
+    "HOUSE_KIT_CONTAINER=1",
     image,
+    "resident",
   ];
 }
 
@@ -198,7 +212,7 @@ export async function workspacePrerequisites(host, image) {
   if (formatter.status !== 0) {
     return {
       supported: false,
-      refusal: `the declared workspace image ${image} carries no mkfs.ext4, so no volume ceiling can be created`,
+      refusal: `the selected Kit image ${image} carries no mkfs.ext4, so no volume ceiling can be created`,
     };
   }
   return { supported: true, runtime: `docker ${version.stdout.trim()}` };
@@ -215,34 +229,45 @@ function bootstrapConfiguration() {
   });
 }
 
-function provisionArguments(root, identity, image, target, mode) {
+function diskArguments(root, identity, image, script) {
   return [
     "run",
     "--rm",
     "--interactive",
     "--mount",
-    `type=bind,source=${workspaceMountPath(root, identity)},target=${WORKSPACE_MOUNT}`,
+    `type=bind,source=${workspaceMountPath(root, identity)},target=${PROVISIONED_DISK}`,
     "--entrypoint",
     "sh",
     image,
     "-c",
-    `set -e; mkdir -p ${WORKSPACE_KIT_HOME}; chmod 700 ${WORKSPACE_KIT_HOME}; cat > ${target}; chmod ${mode} ${target}`,
+    script,
   ];
 }
 
-async function provisionWorkspaceState(host, root, identity, image, authority) {
-  for (const [target, mode, content] of [
-    [`${WORKSPACE_KIT_HOME}/credential`, "600", `${authority.credential}\n`],
-    [`${WORKSPACE_KIT_HOME}/kit.json`, "600", `${bootstrapConfiguration()}\n`],
-  ]) {
-    const written = await docker(
+async function onDisk(host, settings, identity, script, stdin = "") {
+  const written = await docker(host, diskArguments(settings.root, identity, settings.image, script), stdin);
+  if (written.status !== 0) {
+    throw new KitRefusal("kit_workspace_unprovisioned", written.stderr.trim() || identity);
+  }
+}
+
+async function provisionWorkspaceState(host, settings, identity, operation) {
+  const home = `${PROVISIONED_DISK}/${WORKSPACE_DISK_KIT_HOME}`;
+  const house = `${PROVISIONED_DISK}/${WORKSPACE_DISK_HOUSE}`;
+  const files = [
+    ...(operation.authority === undefined ? [] : [["credential", operation.authority.credential]]),
+    ["kit.json", bootstrapConfiguration()],
+    ["house", settings.house],
+    ["environment", operation.environment],
+  ];
+  for (const [name, content] of files) {
+    await onDisk(
       host,
-      provisionArguments(root, identity, image, target, mode),
-      content,
+      settings,
+      identity,
+      `set -e; mkdir -p ${home} ${house}; chmod 700 ${home} ${house}; cat > ${home}/${name}; chmod 600 ${home}/${name}`,
+      `${content}\n`,
     );
-    if (written.status !== 0) {
-      throw new KitRefusal("kit_workspace_unprovisioned", written.stderr.trim() || identity);
-    }
   }
 }
 
@@ -289,9 +314,7 @@ export async function createWorkspace(host, settings, operation) {
   }
   const mountRefusal = await mountWorkspace(host, settings, identity);
   if (mountRefusal !== null) return { outcome: "unsupported", refusal: mountRefusal };
-  if (operation.authority !== undefined) {
-    await provisionWorkspaceState(host, settings.root, identity, settings.image, operation.authority);
-  }
+  await provisionWorkspaceState(host, settings, identity, operation);
   const created = await docker(
     host,
     workspaceCreateArguments(identity, operation, settings.image, settings.house, settings.root),
@@ -312,9 +335,42 @@ async function workspacePresent(host, identity) {
   return inspected.status === 0 ? inspected.stdout.trim() : null;
 }
 
+async function heldWorkspace(host, identity) {
+  const inspected = await docker(host, [
+    "container",
+    "inspect",
+    "--format",
+    `{{.State.Status}} {{.Config.Image}} {{index .Config.Labels "${WORKSPACE_LABEL}"}} {{.HostConfig.NanoCpus}} {{.HostConfig.Memory}}`,
+    identity,
+  ]);
+  if (inspected.status !== 0) return null;
+  const [state, image, environment, nanoCpus, memory] = inspected.stdout.trim().split(/\s+/);
+  return {
+    state,
+    image,
+    environment,
+    maxima: { cpu_millicores: Number(nanoCpus) / 1_000_000, memory_bytes: Number(memory) },
+  };
+}
+
+async function replaceWorkspace(host, settings, identity, held) {
+  const mountRefusal = await mountWorkspace(host, settings, identity);
+  if (mountRefusal !== null) return mountRefusal;
+  await onDisk(host, settings, identity, `rm -f ${updateDrain(`${PROVISIONED_DISK}/${WORKSPACE_DISK_KIT_HOME}`)}`);
+  const removed = await docker(host, ["rm", "--force", identity]);
+  if (removed.status !== 0) return `the workspace was not replaced: ${removed.stderr.trim()}`;
+  const created = await docker(
+    host,
+    workspaceCreateArguments(identity, held, settings.image, settings.house, settings.root),
+  );
+  if (created.status !== 0) return `the workspace was not recreated: ${created.stderr.trim()}`;
+  return null;
+}
+
 export async function startWorkspace(host, settings, operation) {
   const identity = operation.workspace ?? workspaceIdentity(operation);
-  if ((await workspacePresent(host, identity)) === null) return { outcome: "absent" };
+  const held = await heldWorkspace(host, identity);
+  if (held === null) return { outcome: "absent" };
   const available = memoryAvailable(await host.read(MEMINFO));
   if (available - operation.maxima.memory_bytes < WORKSPACE_SYSTEM_RESERVE_BYTES) {
     return {
@@ -324,6 +380,10 @@ export async function startWorkspace(host, settings, operation) {
   }
   const mountRefusal = await mountWorkspace(host, settings, identity);
   if (mountRefusal !== null) return { outcome: "unsupported", refusal: mountRefusal };
+  if (STOPPED_STATES.includes(held.state) && held.image !== settings.image) {
+    const refusal = await replaceWorkspace(host, settings, identity, held);
+    if (refusal !== null) return { outcome: "failed", refusal };
+  }
   const started = await docker(host, ["start", identity]);
   if (started.status !== 0) {
     return { outcome: "failed", refusal: `the workspace did not start: ${started.stderr.trim()}` };
@@ -425,37 +485,123 @@ export async function reconcileWorkspaces(host, authorized) {
   );
   const stopped = [];
   for (const managed of await managedWorkspaces(host)) {
-    if (managed.state !== "running") continue;
     if (expected.get(managed.environment) === "running") continue;
-    const settled = await docker(host, [
-      "stop",
-      "--timeout",
-      String(WORKSPACE_STOP_TIMEOUT_SECONDS),
-      managed.name,
-    ]);
-    if (settled.status === 0) stopped.push(managed.name);
+    const settled = await exclusively(host, managed.name, async () => {
+      if ((await workspacePresent(host, managed.name)) !== "running") return false;
+      const stopping = await docker(host, [
+        "stop",
+        "--timeout",
+        String(WORKSPACE_STOP_TIMEOUT_SECONDS),
+        managed.name,
+      ]);
+      return stopping.status === 0;
+    });
+    if (settled) stopped.push(managed.name);
   }
   return stopped;
 }
 
+function workspaceLock(identity) {
+  return new Promise((resolve, reject) => {
+    const lock = createServer();
+    lock.once("error", reject);
+    lock.listen({ path: `\0${WORKSPACE_LABEL}/${identity}` }, () => resolve(lock));
+  });
+}
+
+async function exclusively(host, identity, act) {
+  let lock = null;
+  while (lock === null) {
+    try {
+      lock = await workspaceLock(identity);
+    } catch (error) {
+      if (error.code !== "EADDRINUSE") throw error;
+      await host.wait(WORKSPACE_LOCK_POLL_MS);
+    }
+  }
+  try {
+    return await act();
+  } finally {
+    await new Promise((resolve) => lock.close(resolve));
+  }
+}
+
 export async function performOperation(host, settings, operation) {
-  if (operation.kind === "create") return createWorkspace(host, settings, operation);
-  if (operation.kind === "start") return startWorkspace(host, settings, operation);
-  if (operation.kind === "stop") return stopWorkspace(host, operation);
-  return deleteWorkspace(host, settings, operation);
+  const selected = operation.kind === "stop" ? settings : { ...settings, image: await selectedImage(host) };
+  return exclusively(host, operation.workspace ?? workspaceIdentity(operation), () => {
+    if (operation.kind === "stop") return stopWorkspace(host, operation);
+    if (operation.kind === "create") return createWorkspace(host, selected, operation);
+    if (operation.kind === "start") return startWorkspace(host, selected, operation);
+    return deleteWorkspace(host, selected, operation);
+  });
 }
 
-export async function serveWorkspaces(options, dependencies = {}) {
+async function selectedImage(host) {
+  let image;
+  try {
+    image = (await host.read(WORKSPACE_SELECTED_IMAGE)).trim();
+  } catch {
+    image = null;
+  }
+  if (image === null || !WORKSPACE_RELEASE_IMAGE.test(image)) {
+    throw new KitRefusal("kit_workspace_host_unconfigured", WORKSPACE_SELECTED_IMAGE);
+  }
+  return image;
+}
+
+async function hostSettings(options) {
   const configuration = await readConfiguration(options.configuration);
-  if (configuration.host === null || configuration.host.image === null) {
+  if (configuration.host === null) {
     throw new KitRefusal("kit_workspace_host_unconfigured", options.configuration);
   }
+  return { root: configuration.host.workspace, house: options.house };
+}
+
+async function updateWorkspace(host, settings, name) {
+  try {
+    const held = await heldWorkspace(host, name);
+    if (held === null || held.image === settings.image) return null;
+    const running = !STOPPED_STATES.includes(held.state);
+    if (running) {
+      const drained = await docker(host, ["exec", name, "kit", "resident", "drain"]);
+      if (drained.status !== 0) {
+        return { workspace: name, cause: drained.stdout.trim() || drained.stderr.trim() };
+      }
+    }
+    const refusal = await replaceWorkspace(host, settings, name, held);
+    if (refusal !== null) return { workspace: name, cause: refusal };
+    if (running) {
+      const started = await docker(host, ["start", name]);
+      if (started.status !== 0) {
+        return { workspace: name, cause: `the workspace did not start: ${started.stderr.trim()}` };
+      }
+    }
+    return { workspace: name, running };
+  } catch (error) {
+    if (!(error instanceof KitRefusal)) throw error;
+    return { workspace: name, cause: error.message };
+  }
+}
+
+export async function updateWorkspaces(options, dependencies = {}) {
   const host = adapter(dependencies);
-  const settings = {
-    root: configuration.host.workspace,
-    image: configuration.host.image,
-    house: options.house,
-  };
+  const updated = [];
+  const unchanged = [];
+  const managed = await managedWorkspaces(host);
+  if (managed.length === 0) return { updated, unchanged };
+  const settings = { ...(await hostSettings(options)), image: await selectedImage(host) };
+  for (const { name } of managed) {
+    const answer = await exclusively(host, name, () => updateWorkspace(host, settings, name));
+    if (answer === null) continue;
+    if (answer.cause === undefined) updated.push(answer);
+    else unchanged.push(answer);
+  }
+  return { updated, unchanged };
+}
+
+export async function serveWorkspaces(options, dependencies = {}) {
+  const host = adapter(dependencies);
+  const settings = await hostSettings(options);
   const session = await openSession(options, dependencies);
   const settled = [];
   const withdrawn = [];