Refactor: use compiled perry binary for container session discovery

- Add perry worker subcommand with sessions list/messages commands
- Compile perry to standalone binary during build (bun build --compile)
- Copy perry binary to containers during sync (/usr/local/bin/perry)
- Remove shell script approach (perry-session-reader.sh)
- Share opencode-storage.ts between host and worker modes
- Update AGENTS.md with manual testing instructions for port 7391
- Fix OpenCode sessions not showing up in web UI

This replaces the npm-based perry-worker package with a compiled binary
that gets synced to containers, eliminating the need to publish a
separate package and ensuring the container always has the latest code.

Author: gricha

AGENTS.md

@@ -91,6 +91,34 @@ Perry creates isolated Docker-in-Docker development environments. Distributed ar
 
 If modifying Dockerfile/init scripts, run `perry build` first.
 
+### Manual Agent Testing
+
+When manually testing agent changes, use a dedicated test port to avoid conflicts with any running production agent:
+
+```bash
+# Kill any existing agents and start test agent on port 7391
+pkill -f "perry agent" 2>/dev/null
+perry agent run --port 7391 &
+
+# Configure CLI to use test agent
+perry config worker localhost:7391
+
+# Test your changes
+perry list
+perry sync <workspace-name>
+
+# Verify in container (example: testing perry worker binary)
+docker exec -u workspace workspace-<name> perry --version
+docker exec -u workspace workspace-<name> perry worker sessions list
+
+# Test API directly
+curl -s -X POST "http://localhost:7391/rpc/sessions/list" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"workspaceName":"<name>"}}'
+```
+
+**Important**: Always kill the test agent when done, or it will conflict with automated tests.
+
 ### UI Testing
 
 **Critical**: UI (Web, mobile) MUST have e2e tests. Unit/integration tests miss rendering bugs, event binding issues, and framework regressions.

DESIGN.md

@@ -819,6 +819,75 @@ Currently none (Tailscale-trusted). Future options if needed:
 
 ---
 
+## Appendix: perry-worker Pattern
+
+### Overview
+
+`perry-worker` is a CLI tool that runs inside containers (and can also run on the host) to handle container-specific operations. It's designed to be updated independently of the Docker image, avoiding the need to rebuild images or recreate containers for bug fixes.
+
+### Architecture
+
+```
+packages/
+├── opencode-sessions/     # Shared library for OpenCode session reading
+│   └── src/index.ts       # listOpencodeSessions(), getOpencodeSessionMessages()
+│
+├── perry-worker/          # CLI that runs inside containers
+│   └── src/
+│       ├── index.ts       # Entry point
+│       ├── cli.ts         # Command router
+│       └── commands/
+│           └── sessions.ts  # Uses @gricha/opencode-sessions
+```
+
+### Key Principle: No Bifurcation
+
+The same code (`@gricha/opencode-sessions`) handles OpenCode session reading everywhere:
+- **Host**: Imported directly in router.ts
+- **Container**: Called via `perry-worker sessions list/messages`
+
+This eliminates duplicate implementations and ensures consistent behavior.
+
+### Installation
+
+perry-worker is installed via npm during container initialization (not baked into Docker image):
+
+```typescript
+// perry/internal/src/lib/devtools.ts
+const ensurePerryWorker = async () => {
+  const installResult = await runCommand("npm", ["install", "-g", "@gricha/perry-worker"]);
+  // ...
+}
+```
+
+### Usage
+
+```bash
+# List all OpenCode sessions
+perry-worker sessions list
+
+# Get messages for a session
+perry-worker sessions messages <session_id>
+```
+
+### Why This Pattern?
+
+1. **Independent Updates**: Fix bugs in session reading without rebuilding Docker images
+2. **Single Source of Truth**: Same `@gricha/opencode-sessions` code used everywhere
+3. **Smaller Docker Images**: Don't bake in tools that change frequently
+4. **Testing**: Can test the shared library independently
+
+### Adding New Commands
+
+To add new functionality to perry-worker:
+
+1. Add the core logic to a shared package (like `@gricha/opencode-sessions`)
+2. Create a command in `packages/perry-worker/src/commands/`
+3. Register the command in `packages/perry-worker/src/cli.ts`
+4. Import the shared package in the main perry codebase where needed
+
+---
+
 ## Appendix: Port Selection
 
 Default port: **7391**

bun.lock

@@ -10,8 +10,9 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf ./dist && bun run build:ts && bun run build:web && bun link",
+    "build": "rm -rf ./dist && bun run build:ts && bun run build:worker && bun run build:web && bun link",
     "build:ts": "tsc && chmod +x dist/index.js",
+    "build:worker": "bun build src/index.ts --compile --outfile dist/perry-worker --target=bun",
     "build:web": "cp src/shared/client-types.ts web/src/lib/types.ts && cd web && bun run build && cp -r dist ../dist/agent/web",
     "test": "vitest run",
     "test:web": "playwright test",

package.json

@@ -193,7 +193,6 @@ RUN cd /opt/workspace/internal && bun install --production
 COPY internal /opt/workspace/internal
 RUN chmod +x /opt/workspace/scripts/dockerd-entrypoint.sh \
   && install -m 0755 /opt/workspace/scripts/dockerd-entrypoint.sh /usr/local/bin/dockerd-entrypoint.sh \
-  && install -m 0755 /opt/workspace/scripts/perry-session-reader.sh /usr/local/bin/perry-session-reader \
   && chmod +x /opt/workspace/internal/src/index.ts \
   && printf '#!/bin/sh\nexec bun /opt/workspace/internal/src/index.ts "$@"\n' > /usr/local/bin/workspace-internal \
   && chmod +x /usr/local/bin/workspace-internal