feat(wrapper): serve cwd probe + readable fallback — fix OpenChamber HTTP 500 under UID separation

.github/workflows/e2e-ddev.yml

@@ -53,7 +53,7 @@ jobs:
         run: |
           chmod +x ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./tests/check-host.sh ./tests/test-wrapper-validation.sh ./tests/test-jsonc-parser.sh ./tests/test-git-config.sh ./tests/test-container-backend.sh ./tests/test-bypass-guard.sh ./tests/test-ddev-as-opencode.sh ./tests/test-ddev-migrate.sh ./tests/test-ddev-hosts.sh ./tests/test-mkcert-reuse.sh ./tests/test-wsl-exposure.sh ./tests/test-ui.sh ./tests/test-docs.sh ./tests/test-kit-cli.sh ./tests/test-project-paths.sh ./tests/test-workflows.sh ./tests/test-install-args.sh ./tests/test-kit-files.sh ./tests/test-tui-mode.sh ./tests/test-uninstall.sh ./tests/test-status.sh ./tests/test-update-flags.sh ./tests/test-fs-baseline.sh \
             ./files/config.sh ./files/update.sh ./files/install.sh ./files/uninstall.sh ./files/status.sh \
-            ./files/opencode-permissions-kit-lib/wrapper ./files/opencode-permissions-kit-lib/kit ./files/opencode-permissions-kit-lib/log.sh ./files/opencode-permissions-kit-lib/ui.sh ./files/opencode-permissions-kit-lib/shell-warn.sh ./files/opencode-permissions-kit-lib/setup-container-backend.sh ./files/opencode-permissions-kit-lib/bin/socket-check.sh ./files/opencode-permissions-kit-lib/ddev-as-opencode.sh ./files/opencode-permissions-kit-lib/ddev-handover.sh ./files/opencode-permissions-kit-lib/ddev-migrate.sh ./files/opencode-permissions-kit-lib/ddev-hosts.sh ./files/opencode-permissions-kit-lib/fs-baseline.sh ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
+            ./files/opencode-permissions-kit-lib/wrapper ./files/opencode-permissions-kit-lib/kit ./files/opencode-permissions-kit-lib/log.sh ./files/opencode-permissions-kit-lib/ui.sh ./files/opencode-permissions-kit-lib/shell-warn.sh ./files/opencode-permissions-kit-lib/setup-container-backend.sh ./files/opencode-permissions-kit-lib/bin/socket-check.sh ./files/opencode-permissions-kit-lib/bin/cwd-check.sh ./files/opencode-permissions-kit-lib/ddev-as-opencode.sh ./files/opencode-permissions-kit-lib/ddev-handover.sh ./files/opencode-permissions-kit-lib/ddev-migrate.sh ./files/opencode-permissions-kit-lib/ddev-hosts.sh ./files/opencode-permissions-kit-lib/fs-baseline.sh ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
           ./tests/e2e/run-ddev.sh
       - name: Summary
         if: always()

.github/workflows/e2e.yml

@@ -56,7 +56,7 @@ jobs:
         run: |
           chmod +x ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./tests/check-host.sh ./tests/test-wrapper-validation.sh ./tests/test-jsonc-parser.sh ./tests/test-git-config.sh ./tests/test-container-backend.sh ./tests/test-bypass-guard.sh ./tests/test-ddev-as-opencode.sh ./tests/test-ddev-migrate.sh ./tests/test-ddev-hosts.sh ./tests/test-mkcert-reuse.sh ./tests/test-wsl-exposure.sh ./tests/test-ui.sh ./tests/test-docs.sh ./tests/test-kit-cli.sh ./tests/test-project-paths.sh ./tests/test-workflows.sh ./tests/test-install-args.sh ./tests/test-kit-files.sh ./tests/test-tui-mode.sh ./tests/test-uninstall.sh ./tests/test-status.sh ./tests/test-update-flags.sh ./tests/test-fs-baseline.sh \
             ./files/config.sh ./files/update.sh ./files/install.sh ./files/uninstall.sh ./files/status.sh \
-            ./files/opencode-permissions-kit-lib/wrapper ./files/opencode-permissions-kit-lib/kit ./files/opencode-permissions-kit-lib/log.sh ./files/opencode-permissions-kit-lib/ui.sh ./files/opencode-permissions-kit-lib/shell-warn.sh ./files/opencode-permissions-kit-lib/setup-container-backend.sh ./files/opencode-permissions-kit-lib/bin/socket-check.sh ./files/opencode-permissions-kit-lib/ddev-as-opencode.sh ./files/opencode-permissions-kit-lib/ddev-handover.sh ./files/opencode-permissions-kit-lib/ddev-migrate.sh ./files/opencode-permissions-kit-lib/ddev-hosts.sh ./files/opencode-permissions-kit-lib/fs-baseline.sh ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
+            ./files/opencode-permissions-kit-lib/wrapper ./files/opencode-permissions-kit-lib/kit ./files/opencode-permissions-kit-lib/log.sh ./files/opencode-permissions-kit-lib/ui.sh ./files/opencode-permissions-kit-lib/shell-warn.sh ./files/opencode-permissions-kit-lib/setup-container-backend.sh ./files/opencode-permissions-kit-lib/bin/socket-check.sh ./files/opencode-permissions-kit-lib/bin/cwd-check.sh ./files/opencode-permissions-kit-lib/ddev-as-opencode.sh ./files/opencode-permissions-kit-lib/ddev-handover.sh ./files/opencode-permissions-kit-lib/ddev-migrate.sh ./files/opencode-permissions-kit-lib/ddev-hosts.sh ./files/opencode-permissions-kit-lib/fs-baseline.sh ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
           ./tests/e2e/run.sh
 
   # docker-rootless daemon e2e (Phase 3). Same triggers + shared binary cache;
@@ -86,5 +86,5 @@ jobs:
           chmod +x ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./tests/check-host.sh ./tests/test-update-flags.sh \
             ./tests/test-wrapper-validation.sh ./tests/test-jsonc-parser.sh ./tests/test-git-config.sh ./tests/test-container-backend.sh ./tests/test-bypass-guard.sh ./tests/test-ddev-as-opencode.sh ./tests/test-ddev-migrate.sh ./tests/test-ddev-hosts.sh ./tests/test-mkcert-reuse.sh ./tests/test-wsl-exposure.sh ./tests/test-ui.sh ./tests/test-docs.sh ./tests/test-kit-cli.sh ./tests/test-project-paths.sh ./tests/test-workflows.sh ./tests/test-install-args.sh ./tests/test-kit-files.sh ./tests/test-tui-mode.sh ./tests/test-uninstall.sh ./tests/test-status.sh ./tests/test-fs-baseline.sh \
             ./files/config.sh ./files/update.sh ./files/install.sh ./files/uninstall.sh ./files/status.sh \
-            ./files/opencode-permissions-kit-lib/wrapper ./files/opencode-permissions-kit-lib/kit ./files/opencode-permissions-kit-lib/log.sh ./files/opencode-permissions-kit-lib/ui.sh ./files/opencode-permissions-kit-lib/shell-warn.sh ./files/opencode-permissions-kit-lib/setup-container-backend.sh ./files/opencode-permissions-kit-lib/bin/socket-check.sh ./files/opencode-permissions-kit-lib/ddev-as-opencode.sh ./files/opencode-permissions-kit-lib/ddev-handover.sh ./files/opencode-permissions-kit-lib/ddev-migrate.sh ./files/opencode-permissions-kit-lib/ddev-hosts.sh ./files/opencode-permissions-kit-lib/fs-baseline.sh ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
+            ./files/opencode-permissions-kit-lib/wrapper ./files/opencode-permissions-kit-lib/kit ./files/opencode-permissions-kit-lib/log.sh ./files/opencode-permissions-kit-lib/ui.sh ./files/opencode-permissions-kit-lib/shell-warn.sh ./files/opencode-permissions-kit-lib/setup-container-backend.sh ./files/opencode-permissions-kit-lib/bin/socket-check.sh ./files/opencode-permissions-kit-lib/bin/cwd-check.sh ./files/opencode-permissions-kit-lib/ddev-as-opencode.sh ./files/opencode-permissions-kit-lib/ddev-handover.sh ./files/opencode-permissions-kit-lib/ddev-migrate.sh ./files/opencode-permissions-kit-lib/ddev-hosts.sh ./files/opencode-permissions-kit-lib/fs-baseline.sh ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
           E2E_STRICT="${{ inputs.strict == true && '1' || '0' }}" ./tests/e2e/run-docker-rootless.sh

.github/workflows/test.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Check version consistency
         run: make check-version
       - name: Make scripts executable
-        run: chmod +x ./tests/test-ui.sh ./tests/test-wrapper-validation.sh ./tests/test-jsonc-parser.sh ./tests/test-git-config.sh ./tests/test-container-backend.sh ./tests/test-bypass-guard.sh ./tests/test-ddev-as-opencode.sh ./tests/test-ddev-migrate.sh ./tests/test-ddev-hosts.sh ./tests/test-mkcert-reuse.sh ./tests/test-wsl-exposure.sh ./tests/test-docs.sh ./tests/test-kit-cli.sh ./tests/test-project-paths.sh ./tests/test-workflows.sh ./tests/test-install-args.sh ./tests/test-kit-files.sh ./tests/test-tui-mode.sh ./tests/test-uninstall.sh ./tests/test-status.sh ./tests/test-update-flags.sh ./tests/test-fs-baseline.sh ./tests/check-host.sh ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./files/config.sh ./files/update.sh ./files/install.sh ./files/uninstall.sh ./files/status.sh ./files/opencode-permissions-kit-lib/wrapper ./files/opencode-permissions-kit-lib/kit ./files/opencode-permissions-kit-lib/log.sh ./files/opencode-permissions-kit-lib/ui.sh ./files/opencode-permissions-kit-lib/shell-warn.sh ./files/opencode-permissions-kit-lib/setup-container-backend.sh ./files/opencode-permissions-kit-lib/bin/socket-check.sh ./files/opencode-permissions-kit-lib/ddev-as-opencode.sh ./files/opencode-permissions-kit-lib/ddev-handover.sh ./files/opencode-permissions-kit-lib/ddev-migrate.sh ./files/opencode-permissions-kit-lib/ddev-hosts.sh ./files/opencode-permissions-kit-lib/fs-baseline.sh ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
+        run: chmod +x ./tests/test-ui.sh ./tests/test-wrapper-validation.sh ./tests/test-jsonc-parser.sh ./tests/test-git-config.sh ./tests/test-container-backend.sh ./tests/test-bypass-guard.sh ./tests/test-ddev-as-opencode.sh ./tests/test-ddev-migrate.sh ./tests/test-ddev-hosts.sh ./tests/test-mkcert-reuse.sh ./tests/test-wsl-exposure.sh ./tests/test-docs.sh ./tests/test-kit-cli.sh ./tests/test-project-paths.sh ./tests/test-workflows.sh ./tests/test-install-args.sh ./tests/test-kit-files.sh ./tests/test-tui-mode.sh ./tests/test-uninstall.sh ./tests/test-status.sh ./tests/test-update-flags.sh ./tests/test-fs-baseline.sh ./tests/check-host.sh ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./files/config.sh ./files/update.sh ./files/install.sh ./files/uninstall.sh ./files/status.sh ./files/opencode-permissions-kit-lib/wrapper ./files/opencode-permissions-kit-lib/kit ./files/opencode-permissions-kit-lib/log.sh ./files/opencode-permissions-kit-lib/ui.sh ./files/opencode-permissions-kit-lib/shell-warn.sh ./files/opencode-permissions-kit-lib/setup-container-backend.sh ./files/opencode-permissions-kit-lib/bin/socket-check.sh ./files/opencode-permissions-kit-lib/bin/cwd-check.sh ./files/opencode-permissions-kit-lib/ddev-as-opencode.sh ./files/opencode-permissions-kit-lib/ddev-handover.sh ./files/opencode-permissions-kit-lib/ddev-migrate.sh ./files/opencode-permissions-kit-lib/ddev-hosts.sh ./files/opencode-permissions-kit-lib/fs-baseline.sh ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
       - name: Install shellcheck
         run: sudo apt-get update -qq && sudo apt-get install -y shellcheck
       - name: Check contributor host tools

Makefile

@@ -9,7 +9,7 @@ SHELLCHECK_FILES = files/install.sh files/config.sh files/update.sh files/status
 	files/opencode-permissions-kit-lib/ddev-migrate.sh \
 	files/opencode-permissions-kit-lib/ddev-hosts.sh \
 	files/opencode-permissions-kit-lib/migrate-denies.sh \
-	files/opencode-permissions-kit-lib/bin/socket-check.sh files/opencode-permissions-kit-lib/bin/ddev-as-opencode
+	files/opencode-permissions-kit-lib/bin/socket-check.sh files/opencode-permissions-kit-lib/bin/cwd-check.sh files/opencode-permissions-kit-lib/bin/ddev-as-opencode
 
 # Intentional deviations, excluded repo-wide:
 #   SC1090/SC1091 — kit scripts source helpers/configs via variables

VERSION

@@ -1 +1 @@
-0.0.22
+0.0.23

docs/concepts/wrapper.md

@@ -66,6 +66,16 @@ stdin is piped. Interactive TUI starts (no subcommand, flags-only
 starts, `tui`, `attach`, or `opencode run` on a terminal without a
 message) keep the banner and the project-directory check.
 
+`serve` additionally sanity-checks its working directory: UIs like
+OpenChamber default it to the developer's `$HOME`, which the `opencode`
+user cannot read (UID separation) — the server would boot but answer
+HTTP 500 on every config load for that directory. The wrapper probes
+readability from the `opencode` user's context (`cwd-check.sh`, gated
+by its own sudoers rule), warns on stderr and starts the server from a
+readable fallback (the matching projects root, else the first readable
+configured root, else the `opencode` home) — see the
+[OpenChamber how-to](../how-to/openchamber.md#server-working-directory).
+
 Which ecosystem tools use which invocation — and the verified status of
 each — is tracked in the [compatibility
 matrix](../reference/compatibility.md) (issue #42 research). Tools that

docs/how-to/openchamber.md

@@ -58,8 +58,64 @@ rules keep the deny. If no backend is configured or its socket is not
 reachable, the server starts without container tools and says so on
 stderr.
 
+## Server working directory
+
+OpenChamber starts the managed server with a working directory of its
+own choosing — by default **your home directory**. Under the kit the
+server runs as the `opencode` user, which usually cannot read your
+`$HOME` (that is the UID separation doing its job). The server still
+boots, but every request that loads config for its working directory —
+`/session`, `/config`, `/project` — answers HTTP 500
+(`Unexpected server error`): accessing `$HOME/opencode.jsonc` fails with
+`EACCES`, and opencode treats that as a hard error instead of "no config
+file".
+
+Point OpenChamber at a directory the `opencode` user can read — your
+projects root (the parent of the paths in `projects.conf`) — and persist
+it in your shell:
+
+```bash
+echo 'export OPENCHAMBER_OPENCODE_CWD=/var/www/vhosts' >> ~/.bashrc
+```
+
+OpenChamber reads the variable at startup only; restart it after
+changing it. Note that directory-scoped requests follow the directory
+selected in the UI — pick your actual project there, otherwise they
+fall back to the home directory and hit the same wall.
+
+If you don't set the variable, the wrapper still catches the case at
+`serve` start: it probes the server working directory from the
+`opencode` user's context (`cwd-check.sh`) and, when unreadable, warns
+on **stderr** and starts the server from a readable fallback — the
+projects root containing the directory, else the first readable
+configured root, else the `opencode` user's home. The 500s disappear,
+but the warning only reaches the terminal OpenChamber was started
+from (its web UI swallows server stderr) — setting
+`OPENCHAMBER_OPENCODE_CWD` keeps the server directory deterministic
+and silences the warning.
+
 ## Troubleshooting
 
+- **HTTP 500 on `/api/*` requests (Unexpected server error)** — the
+  managed server's working directory (your `$HOME`) is not readable by
+  the `opencode` user. Set `OPENCHAMBER_OPENCODE_CWD` to a readable
+  projects root — see
+  [Server working directory](#server-working-directory). (The wrapper's
+  automatic fallback covers this only when the kit's `cwd-check.sh`
+  sudoers rule is present — run `update.sh` if the warning stays away
+  but the 500s don't.)
+
+- **Projectless chats fail (HTTP 500 on `/api/session` with a
+  `…/.config/openchamber/chats/…` directory)** — OpenChamber hard-pins
+  these chat worktrees to `$HOME/.config/openchamber/chats` (no
+  configuration moves them) and re-chmods its config root to `0700` on
+  every settings write, revoking any granted group access. Under the
+  kit's UID separation the `opencode` user therefore cannot work in
+  them. This is an upstream limitation
+  ([openchamber#3130](https://github.com/openchamber/openchamber/issues/3130)) —
+  work in project directories until OpenChamber ships a relocatable
+  chats root.
+
 - **"OpenCode process exited before serving"** — usually a self-installed
   opencode shadowing the wrapper: check for `~/.opencode/bin/opencode`
   (remove it, see [the wrapper](../concepts/wrapper.md)) or point

files/install.sh

@@ -51,7 +51,7 @@ fetch_kit() {
              opencode-deny-all.jsonc \
              sudoers.template umask.sh VERSION \
              opencode-permissions-kit-lib/wrapper opencode-permissions-kit-lib/kit opencode-permissions-kit-lib/jsonc-parser.py \
-             opencode-permissions-kit-lib/log.sh opencode-permissions-kit-lib/ui.sh opencode-permissions-kit-lib/shell-warn.sh opencode-permissions-kit-lib/setup-container-backend.sh opencode-permissions-kit-lib/bin/socket-check.sh opencode-permissions-kit-lib/ddev-as-opencode.sh opencode-permissions-kit-lib/bin/ddev-as-opencode opencode-permissions-kit-lib/ddev-handover.sh opencode-permissions-kit-lib/ddev-migrate.sh opencode-permissions-kit-lib/ddev-hosts.sh opencode-permissions-kit-lib/fs-baseline.sh \
+             opencode-permissions-kit-lib/log.sh opencode-permissions-kit-lib/ui.sh opencode-permissions-kit-lib/shell-warn.sh opencode-permissions-kit-lib/setup-container-backend.sh opencode-permissions-kit-lib/bin/socket-check.sh opencode-permissions-kit-lib/bin/cwd-check.sh opencode-permissions-kit-lib/ddev-as-opencode.sh opencode-permissions-kit-lib/bin/ddev-as-opencode opencode-permissions-kit-lib/ddev-handover.sh opencode-permissions-kit-lib/ddev-migrate.sh opencode-permissions-kit-lib/ddev-hosts.sh opencode-permissions-kit-lib/fs-baseline.sh \
              opencode-permissions-kit-lib/tui/kit-mode.tsx opencode-permissions-kit-lib/tui/opencode-danger.theme.json opencode-permissions-kit-lib/tui/tui.json opencode-permissions-kit-lib/tui/tui-danger.json; do
         echo "  fetching $f ..." >&2
         if [ "$f" = "VERSION" ]; then
@@ -1232,6 +1232,8 @@ sudo cp "$SCRIPT_DIR/opencode-deny-all.jsonc"          "$LIBDIR/opencode-deny-al
 sudo cp "$SCRIPT_DIR/uninstall.sh"                     "$LIBDIR/uninstall.sh"
 # rootless socket probe helper
 sudo cp "$SCRIPT_DIR/opencode-permissions-kit-lib/bin/socket-check.sh" "$LIBDIR/bin/socket-check.sh"
+# headless serve cwd probe helper (readable-for-opencode check + fallback)
+sudo cp "$SCRIPT_DIR/opencode-permissions-kit-lib/bin/cwd-check.sh" "$LIBDIR/bin/cwd-check.sh"
 # ddev always runs as the opencode user: the sourced shell function (hooked
 # into the developer's rc files) + the sudoers helper that execs the real ddev.
 sudo cp "$SCRIPT_DIR/opencode-permissions-kit-lib/ddev-as-opencode.sh" "$LIBDIR/ddev-as-opencode.sh"
@@ -1251,7 +1253,7 @@ sudo chmod 644 "$LIBDIR/ddev-as-opencode.sh" "$LIBDIR/ddev-handover.sh" "$LIBDIR
 sudo chmod 755 "$LIBDIR/wrapper" "$LIBDIR/kit" "$LIBDIR/jsonc-parser.py" \
                "$LIBDIR/log.sh" "$LIBDIR/ui.sh" "$LIBDIR/shell-warn.sh" "$LIBDIR/setup-container-backend.sh" \
                "$LIBDIR/config.sh" "$LIBDIR/update.sh" "$LIBDIR/status.sh" "$LIBDIR/uninstall.sh" \
-               "$LIBDIR/bin/socket-check.sh" "$LIBDIR/bin/ddev-as-opencode"
+               "$LIBDIR/bin/socket-check.sh" "$LIBDIR/bin/cwd-check.sh" "$LIBDIR/bin/ddev-as-opencode"
 log "library deployed to $LIBDIR"
 ui_success "kit library deployed: $LIBDIR"