osborn 0.9.48 → 0.9.50

package/.claude/skills/ground-assumptions/SKILL.md

@@ -0,0 +1,247 @@
+# Ground Assumptions
+
+## SKILL IDENTITY
+Name: ground-assumptions
+Install path: ~/.claude/skills/ground-assumptions/SKILL.md
+Portable: yes — drops into any agent's skills dir (Claude Code, osborn on Fly, other Claude Agent SDK hosts)
+
+## WHEN THIS SKILL ACTIVATES
+This skill applies whenever the conversation enters a **planning / design / architecture phase**.
+Specifically, if the user says or asks any of:
+
+- "let's plan / design / architect..."
+- "how should we..."
+- "what's the best way to..."
+- "I'm thinking we..."
+- "what do you recommend..."
+- "approach", "architecture", "design", "should we"
+- Any time I am about to recommend an implementation strategy, performance characteristic,
+  behavioral guarantee, or comparative judgment ("X is faster than Y", "this propagates", "this scales")
+
+Also activates explicitly with:
+- "ground assumptions"
+- "verify before planning"
+- "check that hypothesis"
+
+## CORE PRINCIPLE
+When you're **planning new work — a new feature, a new integration, or fitting
+a change into the existing architecture** — every load-bearing assumption is a
+**hypothesis until verified against real evidence.** Training-data intuition and
+"it should work" do not count.
+
+The canonical situation this skill is for: *we're about to implement something
+new (e.g. add OpenAI Codex as an agent option alongside Claude Code), and we
+need to know it actually fits our architecture one-to-one — does Codex's session
+model, SDK, and data storage map to what we already do — BEFORE we build on that
+assumption.* That's the shape: a new piece must slot into the existing system,
+and we confirm the fit with evidence, not hope.
+
+**What counts as verification** (in priority order):
+1. **Existing tests / previous test runs** — has this already been proven? check first.
+2. **Authoritative documentation / source code** — does the doc or the actual code confirm the behavior?
+3. **A newly-created, targeted test** — if nothing above answers it, build a
+   specific test (or several) that exercises exactly the assumption, run it on
+   real infrastructure, and read the result.
+
+**The main agent does NOT do the verification work itself.** Spawn subagents
+(Agent tool) to run the tests / read the docs / check prior results, so the main
+agent stays free to keep the planning conversation moving and react to results
+as they land. **Delegation rule (hard):** when verification is needed, ALWAYS
+delegate to a subagent — don't call Bash/WebSearch/Grep inline yourself. Spawn
+multiple subagents in parallel when there are several independent assumptions to
+check. (Exception: the user explicitly asks you to run something inline — then
+say you're breaking the delegation pattern.)
+
+Why this matters — past sessions shipped plans on unverified assumptions and
+paid for it: a "small" change broke an unrelated subsystem; a behavior we
+*assumed* ("this propagates", "this auto-updates") silently failed; an
+integration we *assumed* was 1:1 wasn't. The expensive surprises live in
+**architectural fit and integration**, not in micro-benchmarks. (Timing claims
+matter too — don't say "fast"/"Xs" without measuring — but they are the *least*
+of it. Lead with "does this fit / does this actually work", not "how fast".)
+
+The discipline: **verify against evidence — existing tests, docs, or a new
+delegated test — before the assumption is surfaced as fact or built upon.**
+
+## ASSUMPTION PRIORITY ORDER (verify highest first)
+
+When verification budget is limited, ALWAYS verify in this order:
+
+1. **ARCHITECTURAL IMPACT** — does this change break or alter existing flows / subsystems?
+   - "Does the new entrypoint affect the OAuth flow?"
+   - "If we move osborn off the volume, does session resume still work?"
+   - "Does the bind-mount conflict with Fly's shutdown umount?"
+2. **INTEGRATION** — does this work with all the connected pieces (auth, network, sessions, data, persistence, MCP, recording, etc.)?
+   - "Does Claude Code's `setup-token` pty work inside chroot?"
+   - "Does the frontend's `/api/sandbox` fetch-log still read the right path?"
+3. **BEHAVIORAL** — does the system actually do what we claim it does?
+   - "Does image-swap actually replace the running osborn binary?"
+4. **TIMING** — is the speed claim true under real conditions?
+   - "Is the seed tarball really 5s to extract?"
+5. **COSMETIC** — minor polish items that don't gate the architecture.
+
+Timing claims are the LOWEST priority. We've burned multiple cycles on timing measurements
+while missing that the architecture itself had subtle bugs that broke other parts of the system.
+Architectural and integration assumptions are where the expensive surprises live.
+
+## THE WORKFLOW (followed strictly during planning)
+
+### 1. PLAN DRAFT
+State the proposed plan as usual — fully, with intent and reasoning.
+
+### 2. ASSUMPTION EXTRACTION
+Before presenting the plan as a recommendation, **list every load-bearing assumption**.
+A load-bearing assumption is anything where, if it's wrong, the plan stops working.
+
+For each assumption, **also identify its second/third-order implications** —
+what else in the system depends on it being true?
+
+Format:
+```
+ASSUMPTIONS (must be verified before plan ships):
+1. <claim that the plan depends on>
+   → implications: <what else breaks if 1 is false>
+2. <claim that the plan depends on>
+   → implications: <what else breaks if 2 is false>
+3. ...
+```
+
+If an assumption can't be stated cleanly in one sentence, it isn't ready to be tested.
+Break it down further.
+
+**Ripple-effect check** (do this once for every plan that touches existing architecture):
+
+Ask explicitly:
+- What existing flows touch the system we're changing?
+  (auth, network, sessions, MCP, recording, persistence, log-fetch, dashboard, voice loop)
+- For each connected flow, can the change break it in a non-obvious way?
+- Is there a code path that USED to work without our knowledge that depends on the old behavior?
+
+If yes to any of those, add the affected flow as a new assumption that needs verification.
+This is where the expensive surprises hide.
+
+### 3. ASYNC VERIFIER SPAWN (parallel, non-blocking)
+For EACH assumption, spawn an Agent subagent **immediately**, in a SINGLE message
+with multiple Agent tool calls so they run concurrently.
+
+Choose verifier type by the nature of the assumption. **Architectural and integration verifiers come first** — they catch the expensive surprises.
+
+| Assumption type | Verifier type | What it does |
+|---|---|---|
+| **Architectural impact** (`does X break flow Y?`) | **Ripple agent** | Traces all callers/consumers of the changed component, checks each for breakage |
+| **Integration** (`does X work with subsystem Y?`) | **Integration agent** | Spawns end-to-end test exercising the connection between subsystems |
+| Behavioral (`does X`, `propagates`, `survives Y`) | Test agent | Triggers the behavior, observes outcome |
+| Documented (`API supports X`, `library does Y`) | Research agent | Fetches docs/code/sources, returns citation with quote |
+| Derivable (`X+Y → Z`) | Reasoning agent | Derives from established facts, returns chain |
+| Timing (`Xs`, `fast`, `slow`) | Test agent | Runs the actual operation on real infra, measures under stated conditions |
+| Empirical (`users typically do X`) | Research agent | Cites surveys/data/observations |
+
+Each verifier returns one of:
+- **MEASURED**: empirical observation with conditions documented
+- **SOURCED**: cited from authoritative source with quote
+- **DERIVED**: chain from established facts
+- **CONTRADICTED**: evidence that the assumption is false
+- **UNVERIFIABLE**: cannot be determined in available time/resources
+
+### 4. CONTINUE PLANNING (don't block on verifiers)
+Keep talking with the user through design tradeoffs, edge cases, etc.
+**Main agent is NOT in the test loop.** Verifiers run in the background.
+DO NOT commit to a recommendation until verifiers report.
+
+**Main agent's role while verifiers run:**
+- Stay in conversation with the user
+- Sketch more of the plan / explore tradeoffs / answer questions
+- Track which verifiers are still in flight, which returned, which contradicted
+- React to verifier results as they arrive — don't poll, don't wait silently
+
+**Things the main agent should NOT do while verifiers are in flight:**
+- Run a Bash command that performs the same test (defeats delegation)
+- Read files the verifier is already reading (duplicative)
+- "Just check one quick thing myself" — that's how delegation collapses
+- Block the conversation until results come back
+
+### 5. INTEGRATE RESULTS
+When a verifier returns:
+- **MEASURED / SOURCED / DERIVED** → mark assumption ✓, keep going
+- **CONTRADICTED** → STOP, mark assumption ✗, announce: "Assumption N contradicted by <evidence>. Replanning." → restart at step 1 with revised approach
+- **UNVERIFIABLE** → mark ⚠️, ask user: "Cannot verify <assumption>. Proceed with explicit risk, or pivot to a verifiable approach?"
+
+### 6. COMMITTED PLAN
+Only present a plan as the recommended approach when every assumption is
+✓ MEASURED, ✓ SOURCED, ✓ DERIVED, or explicitly accepted as ⚠️ UNVERIFIABLE.
+
+## OUTPUT FORMAT
+
+While verifiers are in flight:
+```
+PLAN: <draft summary>
+
+ASSUMPTIONS (verifiers running in parallel):
+☐ A1: <assumption>
+☐ A2: <assumption>
+☐ A3: <assumption>
+```
+
+As verifiers return:
+```
+✓ A1 MEASURED: <result> (conditions: <where/when/setup>)
+✓ A2 SOURCED: <URL> — "<quote>"
+✗ A3 CONTRADICTED: <evidence>
+   → STOPPING. Replanning around A3.
+```
+
+Final state:
+```
+VERIFIED PLAN:
+<plan with every assumption marked ✓ or explicitly ⚠️>
+```
+
+## HARD RULES (no exceptions)
+
+1. **No naked "it fits / it works" claims.** Never assert that a new piece integrates with the existing architecture — "Codex maps 1:1 to our session model", "this slots into the existing flow", "the SDK stores data the same way" — without backing from an existing test, the actual docs/source, or a new delegated test.
+2. **No naked behavioral claims.** Never write "auto-updates", "propagates", "survives", "rolls back", "X just works" without MEASURED or SOURCED backing.
+3. **Check for existing evidence FIRST.** Before commissioning a new test, have a subagent check whether a previous test run, doc, or the source already answers it. Don't re-test what's already proven.
+4. **CONTRADICTED stops everything.** When a verifier contradicts an assumption, NO new content is written about the plan until the plan is revised and the verifier rerun.
+5. **UNVERIFIABLE is loud.** Mark it ⚠️ in the output AND ask the user for explicit acceptance. Don't hide unverified parts in prose.
+6. **Training-data intuition is forbidden as evidence.** "X typically works this way" is not a citation. Verify against a test, doc, or source — or skip.
+7. **Timing/comparative claims are the least of it, but still bound:** don't write "fast"/"slow"/"X seconds"/"faster than Y" without a measurement + conditions. Just don't let speed-benchmarking crowd out the architectural-fit and integration checks, which are where the expensive surprises actually live.
+
+## SUBAGENT SPAWNING PATTERNS
+
+For timing/behavioral tests on real infra:
+> Spawn Agent subagent with prompt: "Run <specific command> on <specific target>. Measure <specific metric>. Report back the measurement and the conditions (machine type, memory, network state, cold/warm cache). Do not attempt the broader task — only verify this one assumption."
+
+For documentation lookups:
+> Spawn Agent subagent with prompt: "Find authoritative source for <specific claim>. Return URL + verbatim quote. If multiple sources, prefer official docs > vendor blogs > Stack Overflow. If no source exists, return UNVERIFIABLE with reasoning."
+
+For derivation:
+> Spawn Agent subagent with prompt: "Given these established facts: <list>, can we derive <claim>? Return either the derivation chain OR 'cannot derive — gap at: <step>'."
+
+For ripple-effect / architectural impact (HIGHEST priority):
+> Spawn Agent subagent with prompt: "Trace all consumers / callers / dependencies of `<component being changed>` in the codebase. For each consumer, check whether the proposed change would break it. Report each potential break with file:line and the specific failure mode. Do not propose fixes — only enumerate breaks."
+
+For integration testing (HIGH priority):
+> Spawn Agent subagent with prompt: "End-to-end test: after the proposed change, exercise the connection between `<subsystem A>` and `<subsystem B>` on real infra. Specifically, verify `<concrete cross-system flow>`. Report MEASURED behavior and any divergence from the expected flow."
+
+**Pattern**: invoke all Agent tools in a single response message so they run concurrently rather than sequentially. The Agent tool's `subagent_type` should be `general-purpose` or `Explore` (read-only) depending on what the verifier needs.
+
+## PORTABILITY NOTES
+
+This skill works in any Claude Agent SDK environment because:
+- It only requires the Agent tool (standard SDK feature)
+- The trigger logic is prose, not code
+- No host-specific paths, IDs, or APIs
+
+To deploy on another agent (e.g. osborn on a Fly machine), copy this SKILL.md to that agent's skills dir:
+- Claude Code: `~/.claude/skills/ground-assumptions/SKILL.md`
+- osborn on Fly: `/workspace/root-chroot/root/.claude/skills/ground-assumptions/SKILL.md`
+- Other Claude Agent SDK hosts: their configured skills path
+
+## EXIT CRITERIA
+
+The skill releases its grip on a conversation when:
+- All assumptions are verified and a committed plan exists, OR
+- The user explicitly asks to skip verification ("just give me your best guess"), OR
+- The conversation shifts away from planning to execution of an already-verified plan
+
+In the second case, mark the response with "WARNING: Skipping verification at user request. The following is unverified intuition." so the lack of grounding is visible.

package/.claude/skills/voice-native-sync/SKILL.md

@@ -0,0 +1,229 @@
+# Voice Native Sync Skill
+
+## SKILL IDENTITY
+Name: voice-native-sync
+Install path: ~/.claude/skills/voice-native-sync/SKILL.md
+
+## TRIGGER PHRASES
+This skill activates when the user says any of:
+- "upload to voice native"
+- "download from voice native"
+- "sync to voice native"
+- "push sessions to voice native"
+- "pull sessions from voice native"
+- "sync my sessions"
+
+When triggered, follow the instructions below immediately without asking for clarification,
+unless credentials are missing (see CREDENTIALS section).
+
+---
+
+## SELF-INSTALL
+If the user asks you to install this skill or you fetched this file from a URL,
+save it to: ~/.claude/skills/voice-native-sync/SKILL.md
+
+```bash
+mkdir -p ~/.claude/skills/voice-native-sync
+# then write this file's content to ~/.claude/skills/voice-native-sync/SKILL.md
+```
+
+After saving, confirm: "Voice Native sync skill installed. Use 'upload to voice native' or 'download from voice native' any time."
+
+---
+
+## CREDENTIALS
+Credentials are stored at: ~/.claude/skills/voice-native-sync/config
+
+Config file format:
+```
+CLOUD_URL=https://osborn-XXXX.fly.dev
+TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+If the config file doesn't exist:
+1. Tell the user: "I need your Voice Native sync credentials. Go to voice-native.com → Settings → Copy sync info, then paste it here."
+2. Parse the pasted block for CLOUD_URL (the "Server:" line) and TOKEN (the "Token:" line)
+3. Save to ~/.claude/skills/voice-native-sync/config
+4. Proceed with the requested operation
+
+---
+
+## UPLOAD (Local → Voice Native Cloud)
+
+Uploads all local Claude session files to the Voice Native fly machine.
+Uses chunked upload + finalize. Safe to re-run — mtime-newer-wins per file.
+
+### Execute as a single script (one permission prompt):
+
+```bash
+set -e
+
+# Load credentials
+source ~/.claude/skills/voice-native-sync/config
+
+TARGET_PATH="/workspace"
+
+rm -f /tmp/vn-sync.tar.gz /tmp/vn-chunk-*
+
+# Archive local Claude projects (exclude macOS AppleDouble files)
+tar -czf /tmp/vn-sync.tar.gz \
+  $(uname | grep -qi darwin && echo '--exclude=._*') \
+  -C "$HOME/.claude" projects
+
+echo "archive: $(du -sh /tmp/vn-sync.tar.gz | cut -f1)"
+
+# Split into 50MB chunks
+split -b 50m /tmp/vn-sync.tar.gz /tmp/vn-chunk-
+CHUNKS=(/tmp/vn-chunk-*)
+TOTAL=${#CHUNKS[@]}
+echo "chunks: $TOTAL"
+
+# Generate upload ID (works on Linux and macOS)
+if command -v uuidgen &>/dev/null; then
+  UPLOAD_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+else
+  UPLOAD_ID=$(cat /proc/sys/kernel/random/uuid 2>/dev/null || python3 -c "import uuid; print(uuid.uuid4())")
+fi
+echo "upload id: $UPLOAD_ID"
+
+# Upload chunks
+idx=0
+for chunk in "${CHUNKS[@]}"; do
+  echo "uploading chunk $idx / $((TOTAL-1))..."
+  STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/octet-stream" \
+    --data-binary "@${chunk}" \
+    "${CLOUD_URL}/sessions/import-chunk?uploadId=${UPLOAD_ID}&chunk=${idx}")
+  echo "  chunk $idx → HTTP $STATUS"
+  idx=$((idx+1))
+done
+
+# Finalize — merges chunks and extracts WITHOUT slug remapping.
+# IMPORTANT: do NOT pass `targetWorkDir`. The server-side remap collapses every
+# source slug into the target work dir's slug, which causes session-resume to
+# silently break when sessions are uploaded from different hosts (Mac, Codespace,
+# Sprite) — they all end up in -workspace, the JSONLs internally still reference
+# their original cwd, the slug↔cwd no longer match, and Claude Code's resume
+# can't find the file. Confirmed 2026-05-27: a codespace upload remapped
+# -workspaces-codespaces-blank → -workspace and every codespace session went
+# silent on resume. The fix is to preserve each upload's original slug structure.
+echo "finalizing..."
+RESULT=$(curl -s -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  "${CLOUD_URL}/sessions/import-finalize?uploadId=${UPLOAD_ID}&total=${TOTAL}")
+echo "finalize result: $RESULT"
+
+# Cleanup
+rm -f /tmp/vn-sync.tar.gz /tmp/vn-chunk-*
+
+# Verify
+echo "verifying manifest..."
+curl -s -H "Authorization: Bearer $TOKEN" "${CLOUD_URL}/sessions/manifest" | \
+  python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+slugs=d.get('slugs',{})
+total=sum(len(v.get('files',{})) for v in slugs.values())
+print(f'  cloud now has {len(slugs)} slug(s), {total} total files')
+for slug,info in slugs.items():
+  files=info.get('files',{})
+  print(f'  {slug}: {len(files)} files')
+"
+```
+
+---
+
+## DOWNLOAD (Voice Native Cloud → Local)
+
+Downloads all sessions from the Voice Native fly machine and merges into local ~/.claude/projects/.
+Mtime-newer-wins — local files newer than cloud are preserved.
+
+### Execute as a single script:
+
+```bash
+set -e
+
+# Load credentials
+source ~/.claude/skills/voice-native-sync/config
+
+# Get local working directory for slug remapping
+LOCAL_CWD="$(pwd)"
+echo "local target cwd: $LOCAL_CWD"
+
+rm -f /tmp/vn-download.tar.gz
+
+# Download full export from fly machine
+echo "downloading from $CLOUD_URL..."
+curl -f -L \
+  -H "Authorization: Bearer $TOKEN" \
+  "${CLOUD_URL}/sessions/export" \
+  -o /tmp/vn-download.tar.gz
+echo "downloaded: $(du -sh /tmp/vn-download.tar.gz | cut -f1)"
+
+# Import with slug remapping to local cwd
+echo "importing..."
+# Same fix as upload: no targetWorkDir, preserve original slug structure.
+RESULT=$(curl -s -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/octet-stream" \
+  --data-binary "@/tmp/vn-download.tar.gz" \
+  "${CLOUD_URL}/sessions/import")
+echo "import result: $RESULT"
+
+rm -f /tmp/vn-download.tar.gz
+
+echo "done — sessions merged into ~/.claude/projects/"
+```
+
+Wait — the DOWNLOAD direction means pulling from cloud to THIS local machine.
+The import endpoint runs on the cloud. For download to local, use this instead:
+
+```bash
+set -e
+source ~/.claude/skills/voice-native-sync/config
+
+LOCAL_CWD="$(pwd)"
+rm -f /tmp/vn-download.tar.gz
+
+echo "downloading export from $CLOUD_URL..."
+curl -f -H "Authorization: Bearer $TOKEN" \
+  "${CLOUD_URL}/sessions/export" \
+  -o /tmp/vn-download.tar.gz
+echo "downloaded: $(du -sh /tmp/vn-download.tar.gz | cut -f1)"
+
+# Extract archive
+mkdir -p /tmp/vn-extract
+tar -xzf /tmp/vn-download.tar.gz -C /tmp/vn-extract
+
+# Remap and merge into local ~/.claude/projects/
+LOCAL_SLUG=$(echo "$LOCAL_CWD" | sed 's|/|-|g')
+PROJECTS_DIR="$HOME/.claude/projects"
+mkdir -p "${PROJECTS_DIR}/${LOCAL_SLUG}"
+
+echo "merging into ${PROJECTS_DIR}/${LOCAL_SLUG}..."
+for slug_dir in /tmp/vn-extract/projects/*/; do
+  slug=$(basename "$slug_dir")
+  for f in "${slug_dir}"*.jsonl "${slug_dir}"*.jsonl.* 2>/dev/null; do
+    [ -f "$f" ] || continue
+    fname=$(basename "$f")
+    dest="${PROJECTS_DIR}/${LOCAL_SLUG}/${fname}"
+    if [ ! -f "$dest" ] || [ "$f" -nt "$dest" ]; then
+      cp "$f" "$dest"
+      echo "  wrote $fname"
+    fi
+  done
+done
+
+rm -rf /tmp/vn-download.tar.gz /tmp/vn-extract
+echo "done — sessions available at ${PROJECTS_DIR}/${LOCAL_SLUG}/"
+```
+
+---
+
+## TECHNICAL NOTES
+- Cloud target path is always `/workspace` (Fly.io machines)
+- Slug remapping is automatic on upload (source slug → /workspace slug)
+- Mtime-newer-wins: re-syncing is always safe, newer file wins per-file
+- gzip only — never use zstd (server doesn't support it)
+- macOS: always pass `--exclude='._*'` to tar (BSD tar emits AppleDouble files)

package/Dockerfile.sandbox

@@ -31,7 +31,7 @@
 #   - Path layout:        chroot /workspace/root-chroot/root/...  vs  /workspace/home/...
 # Subagent research confirmed chroot in our codebase solves only HOME-and-persistence
 # layout, NOT library access (Linux dynamic linker is mount-agnostic per ld.so(8)).
-# Since HOME=/workspace/home achieves the same persistence with ~100 fewer LOC and
+# Since HOME=/workspace achieves the same persistence with ~100 fewer LOC and
 # no bind-mount complexity, the chroot version was retired.
 # Archive: docs/archive/Dockerfile.sandbox.chroot-2026-05-28.md
 
@@ -63,14 +63,45 @@ ENV OSBORN_API_PORT=8741
 ENV NODE_ENV=production
 ENV OSBORN_IMAGE_VERSION=${OSBORN_VERSION}
 
-# THE KEY DIFFERENCE FROM CHROOT VARIANT:
-# HOME and OSBORN_CWD are set as IMAGE-LEVEL ENV here. The entrypoint reads
-# them, ensures the dirs exist on the volume, and execs osborn. No bind-mount
-# trickery — HOME just IS on the volume because the path resolves to a volume
-# subdir.
-ENV HOME=/workspace/home
+# HOME=/workspace — the volume mount point itself is the home directory.
+# This means ~/.claude resolves to /workspace/.claude, which is EXACTLY where
+# the legacy symlink architecture (/root/.claude -> /workspace/.claude) already
+# put credentials and sessions. So there is ZERO migration: an existing machine
+# updating to this image finds its data already at ~/.claude with no file moves.
+#
+# Why not /workspace/home (the earlier Option D choice)? That required MOVING
+# legacy data from /workspace/.claude into /workspace/home/.claude — an `mv`
+# loop that is destructive (deletes source as it goes), non-atomic across
+# multiple files (interruption = split state), and catastrophic if HOME ever
+# resolved off-volume (mv would send data to the ephemeral overlay). Pointing
+# HOME at /workspace eliminates the migration entirely: nothing moves, so
+# nothing can be lost in a move. The only cosmetic cost is dotfiles sitting at
+# the volume root — identical to what the legacy symlink effectively did.
+#
+# NOTE on overrides: these are Dockerfile ENV *defaults*. A Fly machine-config
+# `env.HOME` (or app secret) OVERRIDES them at runtime. updateOsborn strips
+# HOME/OSBORN_CWD from existing machine configs during image-swap so this
+# default actually takes effect on migrated machines — without that, a stale
+# HOME=/root from an older provisioning would silently win. See
+# frontend/src/lib/machines.ts updateOsbornImpl.
+ENV HOME=/workspace
 ENV OSBORN_CWD=/workspace
 
+# HYBRID: user-installed global npm packages persist on the volume.
+# osborn itself was already installed above into the DEFAULT prefix (/usr/local,
+# image layer) — that RUN happened BEFORE this ENV, so osborn stays in the image
+# and updates via image-swap (atomic, no runtime OOM, toolchain present at build).
+# Setting NPM_CONFIG_PREFIX here only affects RUNTIME `npm install -g <x>` the
+# user/agent runs: those land in /workspace/.npm-global on the persistent volume
+# and survive restarts + image-swaps. PATH puts that bin dir first so installed
+# CLIs are immediately runnable. Verified end-to-end on real Fly 2026-06-01:
+# pure-JS (cowsay) AND native-compiled (node-pty via node-gyp) both install at
+# runtime, persist across restart, no OOM (toolchain is in the image).
+# Caveat: native user modules are tied to the image's Node ABI (currently 22) —
+# a future Node-major image bump would need an `npm rebuild` of volume globals.
+ENV NPM_CONFIG_PREFIX=/workspace/.npm-global
+ENV PATH=/workspace/.npm-global/bin:$PATH
+
 WORKDIR /workspace
 EXPOSE 8741
 
@@ -95,34 +126,23 @@ exec > >(tee -a "$LOGFILE") 2>&1
 ONBOARDING_JSON='{"numStartups":10,"installMethod":"npm","autoUpdates":false,"hasCompletedOnboarding":true,"hasTrustDialogAccepted":true,"hasTrustDialogHooksAccepted":true,"hasCompletedProjectOnboarding":true,"hasAcknowledgedCostThreshold":true,"effortCalloutV2Dismissed":true,"theme":"dark","projects":{"/workspace":{"hasTrustDialogAccepted":true,"hasTrustDialogHooksAccepted":true,"hasCompletedProjectOnboarding":true}}}'
 
 # ============================================================
-# === HOME-on-volume seed ===
+# === HOME-on-volume setup (HOME=/workspace) ===
 # ============================================================
-# HOME=/workspace/home, set via ENV in Dockerfile. Ensure the dir exists on
-# the volume and seed Claude/onboarding/skills on first boot. Idempotent.
-echo "[sandbox-d] HOME=$HOME OSBORN_CWD=$OSBORN_CWD"
+# HOME=/workspace, set via ENV in Dockerfile (and enforced by updateOsborn
+# stripping any stale HOME from existing machine configs). Because HOME is the
+# volume mount itself, ~/.claude == /workspace/.claude — which is exactly where
+# the legacy symlink architecture already stored credentials + sessions.
+#
+# THEREFORE: NO MIGRATION. An existing machine's data is already at ~/.claude
+# the instant HOME points at /workspace. We removed the old `mv` migration
+# block entirely (it was destructive + non-atomic + catastrophic if HOME ever
+# resolved off-volume). Nothing moves, so nothing can be lost in a move.
+echo "[sandbox-d] HOME=$HOME OSBORN_CWD=$OSBORN_CWD NPM_CONFIG_PREFIX=$NPM_CONFIG_PREFIX"
 mkdir -p "$HOME" "$HOME/.claude" "$HOME/.osborn"
-
-# === Legacy migration ===
-# Existing production sandboxes have credentials at /workspace/.claude/
-# (the pre-D legacy symlink architecture). Migrate to HOME=/workspace/home/.claude/
-# on first boot of the D image. Atomic mv — safe.
-if [ -d /workspace/.claude ] && [ ! -d "$HOME/.claude/projects" ] && [ ! -f "$HOME/.claude/.credentials.json" ]; then
-  echo "[sandbox-d] migrating legacy /workspace/.claude → \$HOME/.claude"
-  # Move CONTENTS, not the dir itself (target may already exist with seeded skills)
-  for item in /workspace/.claude/.* /workspace/.claude/*; do
-    [ -e "$item" ] || continue
-    BASENAME=$(basename "$item")
-    [ "$BASENAME" = "." ] && continue
-    [ "$BASENAME" = ".." ] && continue
-    [ -e "$HOME/.claude/$BASENAME" ] && continue
-    mv "$item" "$HOME/.claude/$BASENAME" 2>/dev/null || true
-  done
-  rmdir /workspace/.claude 2>/dev/null || true
-fi
-if [ -f /workspace/.claude.json ] && [ ! -f "$HOME/.claude.json" ]; then
-  echo "[sandbox-d] migrating legacy /workspace/.claude.json → \$HOME/.claude.json"
-  mv /workspace/.claude.json "$HOME/.claude.json"
-fi
+# HYBRID: ensure the volume-backed npm global prefix exists so user
+# `npm install -g <x>` has a target on first use (npm would create it anyway,
+# but pre-making it keeps perms predictable + visible in the boot log).
+mkdir -p /workspace/.npm-global
 
 # Onboarding config (overwrites every boot — intentional, deterministic state)
 echo "$ONBOARDING_JSON" > "$HOME/.claude.json"

package/dist/index.js

@@ -2527,6 +2527,30 @@ async function main() {
         currentLLM = null;
         clearFastBrainSession();
         clearPipelineFastBrainSession();
+        // ── Ghost-agent fix (2026-06-01) ──
+        // When LiveKit Cloud evicts our WebSocket (idle, network blip, or quota window),
+        // the previous code stopped here — agent process kept running but no longer in
+        // any room. /health continued returning "livekit.status:connected" because the
+        // status was never written back. Frontend's checkOsbornHealth only validates
+        // HTTP 200, so the ghost state was invisible. Users got stuck in "Connecting..."
+        // forever because their LiveKit-token-minted room had no agent in it.
+        //
+        // Fix: re-arm the retry loop. connectWithRetry() will try to reconnect with
+        // the same room name (so the room code stays stable for any in-flight frontend
+        // token requests), backing off 5s → 60s. If the disconnect was permanent
+        // (e.g. JWT expired — they're 24h), the retry will fail and surface
+        // livekit.status=failed, which the (also-fixed) frontend health check will
+        // see and trigger restartService.
+        //
+        // Note: we mark status='retrying' immediately so /health reflects the real
+        // state — closing the lie window between Disconnected and the next attempt.
+        livekitState.status = 'retrying';
+        livekitState.error = 'LiveKit room disconnected; attempting to rejoin';
+        livekitState.errorCode = 'disconnected';
+        console.log('🔄 Rejoining LiveKit room after disconnect...');
+        connectWithRetry().catch(err => {
+            console.error('❌ Reconnect attempt threw (should not happen — connectWithRetry loops):', err);
+        });
     });
     room.on(RoomEvent.ParticipantConnected, async (participant) => {
         console.log(`\n👤 User joined: ${participant.identity}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osborn",
-  "version": "0.9.48",
+  "version": "0.9.50",
   "description": "Voice AI coding assistant - local agent that connects to Osborn frontend",
   "type": "module",
   "bin": {