@geohar/un-bien 0.8.0 → 0.14.0

package/docs/daemon.md

@@ -1,45 +1,44 @@
-# Daemon mode — troubleshooting
+# Remote launch & launcher daemon — troubleshooting
 
-Companion to the README's [Daemon mode](../README.md#daemon-mode) section.
+Companion to the README's [Remote launch](../README.md#remote-launch) section.
 Each scenario starts with the symptom you'd actually observe, followed by
-likely causes and how to fix.
+likely causes and how to fix it.
 
 ---
 
-## 1. `remote-pi install` fails
+## 1. `unbien install` fails
 
-### "supervisor script not found"
+### "launcher script not found"
 
-```
-[remote-pi] install failed: Error: supervisor script not found at
-/Users/x/dist/bin/supervisord.js. Run `pnpm build` (dev) or
-`npm install -g remote-pi` (prod) first.
+```text
+[un-bien] install failed: Error: launcher script not found at
+/Users/x/dist/bin/launcher.js. Run `pnpm build` (dev) or
+`npm install -g @geohar/un-bien` (prod) first.
 ```
 
-You're running `remote-pi install` from a dev clone where `dist/` doesn't
+You're running `unbien install` from a dev clone where `dist/` doesn't
 exist yet, or from a partial install.
 
 ```bash
 # Dev clone:
-cd pi-extension && pnpm build
+cd extension && pnpm build
 
 # Production install:
-npm install -g remote-pi      # or pnpm install -g remote-pi
-which pi-supervisord          # confirm bin is on PATH
-remote-pi install
+npm install -g @geohar/un-bien
+unbien install
 ```
 
 ### "launchctl: bootstrap … already running"
 
 A previous install left a stale entry. The fix is built into `install` —
-re-run it and the supervisor unloads the old entry before bootstrapping
-the new one. If it still fails:
+re-run it and the launcher unloads the old entry before bootstrapping the
+new one. If it still fails:
 
 ```bash
-launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/dev.remotepi.supervisord.plist
-launchctl unload ~/Library/LaunchAgents/dev.remotepi.supervisord.plist 2>/dev/null
-rm ~/Library/LaunchAgents/dev.remotepi.supervisord.plist
-remote-pi install
+launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/dev.unbien.launcher.plist
+launchctl unload ~/Library/LaunchAgents/dev.unbien.launcher.plist 2>/dev/null
+rm ~/Library/LaunchAgents/dev.unbien.launcher.plist
+unbien install
 ```
 
 ### "systemctl --user … No such file or directory"
@@ -51,239 +50,231 @@ the unit survives logout:
 ```bash
 loginctl enable-linger $USER
 systemctl --user daemon-reload
-remote-pi install
+unbien install
 ```
 
+### Windows: the UAC prompt fails or is declined
+
+`unbien install` needs elevation **once** — only the `schtasks /Create`
+that registers the task requires admin. Accept the prompt when it appears.
+Stopping/starting the task afterwards (`/End`, `/Run`) works un-elevated.
+
 ---
 
-## 2. Supervisor doesn't start at login
+## 2. The launcher doesn't start at login
 
 ### Check the service status
 
 ```bash
 # Linux
-systemctl --user status remote-pi-supervisord
-journalctl --user -u remote-pi-supervisord -n 50
+systemctl --user status unbien-launcher
+journalctl --user -u unbien-launcher -n 50
 
 # macOS
-launchctl list | grep remotepi
-tail -100 ~/.pi/remote/supervisord.log
+launchctl list | grep dev.unbien
+tail -100 ~/.local/state/un-bien/launcher.log
 ```
 
 ### Common failures
 
-- **`pi: command not found`** in the log — Pi's binary isn't on the
-  PATH that the unit inherited. `remote-pi install` captures
-  `process.env.PATH` at install time; if you installed Pi *after*
-  running install, re-run `remote-pi install` to refresh.
-- **`Cannot find module …`** — the path baked into the unit doesn't
-  match where `dist/bin/supervisord.js` actually lives. Happens if you
-  uninstalled then reinstalled the package to a different location.
-  Fix: `remote-pi uninstall && remote-pi install`.
-- **Permission denied on UDS** — `~/.pi/remote/` exists with wrong
-  perms (rare; only happens if you ran `pi` as `sudo` once). Delete
-  the dir and let it re-create: `rm -rf ~/.pi/remote && remote-pi install`.
+- **`node: cannot find module …`** or immediate exit — the absolute paths
+  baked into the unit/plist no longer match where the package lives. This
+  happens when you reinstall Node via a version manager (nvm/fnm) or
+  uninstall/reinstall the package to a different location. Fix:
+  `unbien uninstall && unbien install` (install snapshots the current
+  node binary and paths).
+- **`tmux: command not found`** (at launch time, not startup) — the PATH
+  captured at install time didn't include the remote-launch backend.
+  Install tmux (or herdr), then re-run `unbien install` to refresh PATH.
+- **First connect race** — the launcher logs `initial connect failed (…)
+— retrying every 3000ms` and retries on its own. This is normal when
+  the relay starts in the same breath; it clears once the relay is up.
 
-### Run the supervisor in the foreground for debugging
+### Run the launcher in the foreground for debugging
 
-Bypass systemd/launchd and run it directly so you can see startup
-errors live:
+Bypass systemd/launchd and run it directly so you can see startup errors
+live:
 
 ```bash
-pi-supervisord
-# or: node /path/to/remote-pi/dist/bin/supervisord.js
+unbien-launcher          # from @geohar/un-bien-launcher
+# or, from the extension package:
+node $(npm root -g)/@geohar/un-bien/dist/bin/launcher.js
 ```
 
-Ctrl-C to stop. If that works but the service doesn't, the problem is
-in the unit/plist environment (PATH, HOME) — re-run `remote-pi install`.
+If it prints `[un-bien launcher] listening on control room …` and stays
+up, the daemon itself is fine — the problem is in the unit/plist
+environment (PATH, node path). Re-run `unbien install`.
 
 ---
 
-## 3. A specific daemon stays `crashed`
-
-`remote-pi daemon status` shows one row with `state=crashed` and a
-restart count near 4 (the supervisor gives up after exponential
-backoff: 1s, 5s, 30s, 5min).
-
-### Step 1 — read the daemon's stderr
-
-The supervisor forwards each daemon's stderr with a `[<cwd>]` prefix:
-
-```bash
-# Linux
-journalctl --user -u remote-pi-supervisord -f | grep '\[/Users/x/Movies\]'
-
-# macOS
-tail -f ~/.pi/remote/supervisord.log | grep '\[/Users/x/Movies\]'
-```
-
-### Step 2 — run that daemon manually
-
-Reproduce the failure with full visibility:
+## 3. Remotely launched pis can't read the keychain (tmux security sessions)
+
+**Symptoms:** a remote launch opens the tmux window but pi dies silently (no
+output, no stderr), or fails with `No identity could be read, but N device(s)
+are already paired — refusing to generate a NEW one` (the
+`PairedIdentityMissingError` guard). An `identity.json.bogus-*` file appears
+in the state root. Everything works when you start pi yourself in Terminal.
+
+**Cause — macOS security sessions:** keychain access follows the _security
+session_ a process was spawned into, and every tmux pane inherits the tmux
+**server's** context — not the terminal that opened the window. With
+`launch.backend: "tmux"` the server is created by whichever process first
+needed it: the launcher. If the launcher was started from a detached or
+session-poor context (a daemon, a service manager like `sharedserver`, SSH),
+the tmux server it creates carries that context and **denies keychain access
+to every pane it ever hosts**. Worse, the server **outlives the launcher**:
+killing/restarting the launcher just attaches new windows to the orphaned
+server, so a bad creation context persists across launcher restarts.
+
+A second wrinkle: a keychain read can require an **ACL confirmation** when
+the reading binary differs from the one that created the item (e.g. after an
+nvm/npm reinstall swaps the node binary). A background process has no path to
+the Security Agent UI, so it gets `errSecInteractionNotAllowed` instead of a
+prompt — same symptom, same fixes.
+
+**Recovery:** kill the orphaned tmux server so the next launch recreates it
+from a healthy context:
 
 ```bash
-cd /Users/x/Movies
-REMOTE_PI_DAEMON=1 pi --mode rpc -e $(npm root -g)/remote-pi/dist/index.js
+tmux kill-session -t un-bien    # or tmux kill-server (kills ALL sessions)
 ```
 
-Common reasons a daemon won't start:
+**Lasting fixes (any one of these):**
 
-- **Local config missing.** `cd` into the daemon's folder and check
-  `.pi/remote-pi/config.json` exists with `auto_start_relay: true`.
-  Recreate via `remote-pi create <cwd>` (it provisions a default config
-  when missing).
-- **Pi extension config drift.** Pi's own settings (model, API keys)
-  reset → daemon fails to authenticate to the provider. Run
-  `cd <cwd> && pi` interactively to fix.
-- **Port/UDS collision.** Another Pi process is already running in
-  that cwd. The cwd-lock should reject the second one, but stale UDS
-  sockets sometimes linger; check `lsof ~/.pi/remote/locks/<roomId>.sock`.
-
-### Step 3 — force a re-spawn
-
-After fixing the underlying problem, kick the supervisor:
-
-```bash
-remote-pi daemon restart      # bounces every daemon
-```
+1. **Pre-seed the tmux session from your own Terminal** — the server then
+   lives in your GUI login session for good, and the launcher only ever adds
+   windows to it:
 
----
+   ```bash
+   tmux new-session -d -s un-bien
+   ```
 
-## 4. `daemon send` says "daemon not running"
+2. **Run the launcher as a login service** (`unbien install` — launchd
+   LaunchAgent / systemd `--user`), not from a detached daemon: the launcher
+   — and any tmux server it creates — stays inside your login session where
+   the keychain just works.
 
-The supervisor has the registry entry but no live child for that id.
-Most common cause: the daemon never started OR it crashed past the
-retry budget.
+3. **The context-proof option — seed the file identity fallback.** The
+   resolver reads `~/.local/state/un-bien/identity.json` automatically
+   whenever the keychain throws (no prompt, no re-pairing, any security
+   session):
 
-```bash
-remote-pi daemon status       # is state running?
-remote-pi daemon start        # spawn any that aren't running
-# Then retry send.
-```
+   ```bash
+   security find-generic-password -s dev.unbien.pi -a longterm-ed25519 -w \
+     > ~/.local/state/un-bien/identity.json
+   chmod 600 ~/.local/state/un-bien/identity.json
+   ```
 
-If `daemon start` shows `started=0, already_running=N`, the supervisor
-isn't actually spawning. Possible reasons:
-- Registry empty: `remote-pi daemons` to verify.
-- Child crashes faster than the status check: `daemon status` immediately
-  after start may still show `running` for a few seconds before the
-  exit event marks it crashed. Re-check 2-3 seconds later.
+**Related:** the launcher needs your env (`PI_CODING_AGENT_DIR`, and
+`UNBIEN_RELAY`/`UNBIEN_STATE_DIR` if you use them) in its spawn context. If
+you run it under a service manager, pin them explicitly in the server
+definition's env map instead of relying on ambient shell env — a daemon's
+children inherit the _daemon's_ environment, not your shell's.
 
 ---
 
-## 5. Mobile app doesn't connect to a daemon
+## 4. The app can't launch a session on this machine
 
-The daemon is up but the app doesn't see it.
+The launcher is running and the app sees the machine's control room, but
+launch requests do nothing.
 
-### Confirm the daemon is paired
+### Remote launch is not enabled for that directory
 
-`pair_request` must have happened **before** the folder became a daemon
-(daemons don't show QRs themselves):
+The launcher only honors `session_launch` where it's opted in:
 
-```bash
-cd <daemon-cwd>
-pi
-> /remote-pi devices         # confirm the device is listed
-> /remote-pi stop            # stop interactive session — daemon takes over
-remote-pi daemon restart
+```jsonc
+// <cwd>/.pi/un-bien/config.json — per directory
+{ "allow_remote_launch": true }
 ```
 
-### Confirm the relay URL matches
+or machine-wide, in `~/.pi/extensions/un-bien.json`:
 
-The daemon uses the cwd's local config (`<cwd>/.pi/remote-pi/config.json`
-agent_name + `~/.pi/remote/config.json` relay). Verify with:
-
-```bash
-cd <daemon-cwd>
-pi
-> /remote-pi status
+```jsonc
+{ "defaults": { "allow_remote_launch": true } }
 ```
 
-The relay line should match what the mobile app is connecting to. If
-not, update the relay URL and bounce the daemon:
+### Turn on the diagnostic log
 
-```bash
-remote-pi set-relay https://relay.example.tld
-remote-pi daemon restart
+The launcher writes its decisions to the envelope debug log. Enable it in
+`~/.pi/extensions/un-bien.json`:
+
+```jsonc
+{ "debug": { "envelope": true } }
 ```
 
----
+then reproduce and read
+`~/.local/state/un-bien/envelope-debug.log` — look for
+`remote launch disabled on this machine` (the opt-in above) or
+`session_launch error: …` (the backend failing to spawn).
 
-## 6. Registry corrupted / partial
+### The backend is missing or misconfigured
 
-Symptom: `remote-pi daemons` errors out or shows nothing despite
-having created entries.
+`launch.backend` in the global config picks the spawn mechanism — `tmux`
+(default) or `herdr`. The chosen binary must be on the PATH the service
+inherited (see §2). Verify what the launcher will use from any Pi
+session: `/unbien config`.
 
-```bash
-cat ~/.pi/remote/daemons.json    # inspect
-```
+### "Peer not paired — re-scan QR"
 
-The file should be:
+The app's device key isn't in this machine's `peers.json` (never paired
+here, or revoked). Pairing is interactive: run `/unbien pair` in any Pi
+session on the machine and scan the QR from the app.
 
-```json
-{
-  "daemons": [
-    { "cwd": "/Users/x/Movies" },
-    { "cwd": "/Users/x/Projects/backend" }
-  ]
-}
-```
+---
 
-Fix manually if needed (it's a JSON list of `{cwd}` entries), or wipe
-and re-create:
+## 5. The app can't see the machine at all
 
-```bash
-rm ~/.pi/remote/daemons.json
-remote-pi create ~/Movies --name "Video Editor"
-remote-pi create ~/Projects/backend --name "Backend"
-remote-pi daemon restart
-```
+- **Relay mismatch.** The launcher uses the same global relay config as
+  the extension — check `/unbien config` and make sure the app is pointed
+  at the same URL.
+- **Launcher not running.** Check §2; the control room only exists while
+  the launcher is connected.
 
 ---
 
-## 7. Uninstall cleanly + re-install from scratch
+## 6. Uninstall cleanly + re-install from scratch
 
 When you suspect everything is misconfigured:
 
 ```bash
-remote-pi uninstall              # removes service, keeps registry
-rm -rf ~/.pi/remote               # nukes registry + paired devices + keys
-npm uninstall -g remote-pi
-npm install -g remote-pi
-remote-pi install
-# Then re-pair + re-create daemons from scratch.
+unbien uninstall                    # removes the service, keeps config + pairing
+rm -rf ~/.local/state/un-bien       # nukes pairing + identity (re-pair after this)
+npm uninstall -g @geohar/un-bien
+npm install -g @geohar/un-bien
+unbien install
+# Then re-pair from scratch: pi → /unbien pair
 ```
 
-This is the "nuke everything" path. After this, the only state left is
-each cwd's `<cwd>/.pi/remote-pi/config.json` — which you can either
-keep (re-create restores the daemon) or delete (full reset).
+This is the "nuke everything" path. After it, the only state left is each
+cwd's `<cwd>/.pi/un-bien/config.json`, which you can keep or delete for a
+full reset.
 
 ---
 
-## 8. Diagnostic commands cheat-sheet
+## 7. Diagnostic commands cheat-sheet
 
 ```bash
-# Where is the supervisor's UDS?
-ls -la ~/.pi/remote/supervisor.sock
-
-# Talk to the supervisor manually (raw JSONL):
-echo '{"op":"list"}' | nc -U ~/.pi/remote/supervisor.sock
-
-# Where are the daemon configs?
-find ~/Projects -name "config.json" -path "*/.pi/remote-pi/*" 2>/dev/null
+# Service status
+systemctl --user status unbien-launcher          # Linux
+launchctl list | grep dev.unbien                 # macOS
+schtasks /Query /TN RemotePiLauncher             # Windows
 
-# Where are the cwd locks?
-ls ~/.pi/remote/locks/
+# Logs
+journalctl --user -u unbien-launcher -f          # Linux
+tail -f ~/.local/state/un-bien/launcher.log      # macOS / Windows
 
-# Where are the paired devices?
-cat ~/.pi/remote/peers.json
+# Global config the launcher reads (relay, launch backend, defaults)
+cat ~/.pi/extensions/un-bien.json
 
-# What Pi binary is the supervisor about to spawn?
-remote-pi install --dry-run      # (not implemented; check ~/Library/LaunchAgents or systemd unit manually)
+# Paired devices (per machine)
+cat ~/.local/state/un-bien/peers.json
 
-# Quick liveness check
-remote-pi daemon status
+# What the extension thinks (from any Pi session, in pi):
+#   /unbien config
+#   /unbien status
+#   /unbien devices
 ```
 
 If after walking the list you're still stuck, file an issue with the
-output of `remote-pi daemon status`, the recent supervisor log, and
-the contents of `~/.pi/remote/daemons.json`.
+output of the service status, the launcher log, and the contents of
+`~/.pi/extensions/un-bien.json`.

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "@geohar/un-bien",
-  "version": "0.8.0",
+  "version": "0.14.0",
   "description": "Mobile remote control and local agent mesh for the Pi coding agent. Pair your phone via QR over a relay, watch tool calls in real time, run multi-Pi sessions over a local Unix Domain Socket broker, and let agents talk to each other through structured request/reply. Derived from remote-pi by Jacob Moura (https://github.com/jacobaraujo7/remote_pi), MIT.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "unbien": "dist/index.js",
-    "pi-supervisord": "dist/bin/supervisord.js"
+    "unbien": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./launcher": {
+      "types": "./dist/bin/launcher.d.ts",
+      "default": "./dist/bin/launcher.js"
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -61,14 +71,6 @@
   "engines": {
     "node": ">=20.0.0"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "@google/genai",
-      "esbuild",
-      "koffi",
-      "protobufjs"
-    ]
-  },
   "devDependencies": {
     "@types/node": "^25.8.0",
     "@types/ws": "^8.18.1",

package/service-templates/launchd.plist.template

@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<!-- un-bien daemon supervisor (plan/26). Generated by `unbien install`. -->
+<!-- un-bien launcher daemon. Generated by `unbien install`. -->
 <plist version="1.0">
 <dict>
   <key>Label</key>
-  <string>dev.unbien.supervisord</string>
+  <string>dev.unbien.launcher</string>
 
   <key>ProgramArguments</key>
   <array>
     <string>{NODE}</string>
-    <string>{SUPERVISOR}</string>
+    <string>{PRESENCE}</string>
   </array>
 
   <key>RunAtLoad</key>
@@ -18,14 +18,15 @@
   <true/>
 
   <key>StandardOutPath</key>
-  <string>{HOME}/.pi/un-bien/supervisord.log</string>
+  <string>{LOG}</string>
   <key>StandardErrorPath</key>
-  <string>{HOME}/.pi/un-bien/supervisord.log</string>
+  <string>{LOG}</string>
 
   <key>EnvironmentVariables</key>
   <dict>
-    <!-- Inherit the user's shell PATH so `pi --mode rpc` resolves to the
-         same binary it would in Terminal.app (Homebrew / npm-global / etc.). -->
+    <!-- Inherit the user's shell PATH so `tmux`/`herdr` (the remote-launch
+         backends) and `pi` resolve the same way they would in Terminal.app
+         (Homebrew / npm-global / etc.). -->
     <key>PATH</key>
     <string>{PATH}</string>
     <key>HOME</key>

package/service-templates/systemd.service.template

@@ -1,17 +1,18 @@
 [Unit]
-Description=Remote Pi daemon supervisor (plan/26)
+Description=un-bien launcher daemon
 Documentation=https://docs.georgeharker.com/un-bien
 After=default.target
 
 [Service]
 Type=simple
-ExecStart={NODE} {SUPERVISOR}
+ExecStart={NODE} {PRESENCE}
 Restart=on-failure
 RestartSec=5s
 StandardOutput=journal
 StandardError=journal
-# Inherit the user's shell PATH so `pi --mode rpc` resolves to the same
-# binary it would in an interactive shell (npm-global / Homebrew / etc.).
+# Inherit the user's shell PATH so `tmux`/`herdr` (remote-launch backends)
+# and `pi` resolve to the same binaries they would in an interactive shell
+# (npm-global / Homebrew / etc.).
 Environment="PATH={PATH}"
 Environment="HOME={HOME}"
 

package/service-templates/task-launcher.vbs.template

@@ -1,10 +1,10 @@
-' Remote Pi supervisor launcher — runs node hidden (no console window) and tees
-' stdout+stderr to {LOG} so crashes are diagnosable (Task Scheduler gives the
-' hidden process no console, mirroring launchd/systemd log redirection).
+' un-bien launcher daemon launcher — runs node hidden (no console window) and
+' tees stdout+stderr to {LOG} so crashes are diagnosable (Task Scheduler gives
+' the hidden process no console, mirroring launchd/systemd log redirection).
 ' `cmd /c` is required for the `>>` redirection. Run(cmd, 0, True): window
 ' style 0 = hidden, wait = True so wscript stays alive for node's lifetime →
-' Task Scheduler's RestartOnFailure still monitors the supervisor.
+' Task Scheduler's RestartOnFailure still monitors the launcher daemon.
 ' WScript.Quit propagates node's exit code.
 Dim rc
-rc = CreateObject("Wscript.Shell").Run("cmd /c """"{NODE}"" ""{SUPERVISOR}"" >> ""{LOG}"" 2>&1""", 0, True)
+rc = CreateObject("Wscript.Shell").Run("cmd /c """"{NODE}"" ""{PRESENCE}"" >> ""{LOG}"" 2>&1""", 0, True)
 WScript.Quit rc

package/service-templates/task-scheduler.xml.template

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-16"?>
 <Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
   <RegistrationInfo>
-    <Description>Remote Pi daemon supervisor (pi-supervisord) — keeps background Pi agents running.</Description>
+    <Description>un-bien launcher daemon — keeps the machine reachable on the mesh.</Description>
   </RegistrationInfo>
   <Triggers>
     <LogonTrigger>