Audit: remove mock behaviors and unify local startup

.env.example

@@ -1,5 +1,4 @@
 DATABASE_URL="file:./db/custom.db"
-HELLO_MCP_URL="http://localhost:3030"
 HELLO_PUBLIC_URL="http://localhost:3000"
 HELLO_ALLOWED_ORIGINS="http://localhost:3000,http://127.0.0.1:3000,http://localhost:3030,http://127.0.0.1:3030"
 
@@ -12,7 +11,7 @@ HELLO_ALLOWED_ORIGINS="http://localhost:3000,http://127.0.0.1:3000,http://localh
 # HELLO_WEBHOOK_SECRET=""
 # Optional read-only GitHub token for the MCP connector.github.read tool (PR #7).
 # GITHUB_TOKEN=""
-# MCP service port override (PR #7). Default 3030.
+# Optional standalone MCP sidecar port. The app's in-process MCP endpoint needs no sidecar.
 # HELLO_MCP_PORT="3030"
 
 # AI provider (OpenAI-compatible). Unset = AI features return 503 NO_AI_PROVIDER.

AGENTS.md

@@ -3,7 +3,7 @@
 Guidance for coding agents (and crawlers) working on HELLO OS. Humans: see `README.md` and `CONTRIBUTING.md`.
 
 ## Project
-HELLO OS is an MIT-licensed, local-first agentic OS **prototype**. The web app is Next.js 16 / React / TypeScript, data is SQLite via Prisma, and the MCP server is a separate Bun service (`mini-services/hello-mcp`). Docker Compose runs both.
+HELLO OS is an MIT-licensed, local-first agentic OS **prototype**. The web app is Next.js 16 / React / TypeScript, data is SQLite via Prisma, and the MCP handler runs in-process in the Next.js app. An optional Bun sidecar (`mini-services/hello-mcp`) exposes the same handler on port 3030.
 
 ## Repo layout
 | Path | What lives there |
@@ -12,7 +12,7 @@ HELLO OS is an MIT-licensed, local-first agentic OS **prototype**. The web app i
 | `src/lib/` | Domain logic: `crypto.ts` (did:key + Ed25519), `gate.ts` (approvals, kill switch), `economy.ts` (wallets, caps), `aml.ts` (AML compiler), `forge.ts`, `failures.ts`, `snapshots.ts`, `sandbox.ts`, `consensus.ts`, `scheduler.ts`, `delegation.ts`, `mcp/connectors/` |
 | `src/components/` | UI (`hello/`, `hub/`, `ops/`, `ui/` shadcn primitives). Icons: `lucide-react` only |
 | `prisma/schema.prisma` | SQLite schema |
-| `mini-services/hello-mcp/` | MCP JSON-RPC server (Bun), default port 3030 |
+| `mini-services/hello-mcp/` | Optional MCP JSON-RPC sidecar (Bun), default port 3030 |
 | `tests/` | `node:test` suites (`*.test.mjs`); `register.mjs` maps the `@/` alias |
 | `scripts/` | Seed and helper scripts |
 | `docs/` | Static GitHub Pages guide (`https://codesbyfebin.github.io/Hello-OS/`); does not run the app |
@@ -21,22 +21,22 @@ HELLO OS is an MIT-licensed, local-first agentic OS **prototype**. The web app i
 ```sh
 npm ci
 cp .env.example .env
-npx prisma generate
-DATABASE_URL=file:/tmp/hello-dev.db npx prisma db push   # use a disposable DB
+npm run dev            # http://localhost:3000; fresh SQLite file is initialized automatically
 npm run build
-npm run dev            # http://localhost:3000
-npm run mcp            # MCP service on :3030 (needs Bun)
+npm start
+npm run mcp            # optional MCP service on :3030 (needs Bun)
 
 # tests: Node 22+ (use `npx -y node@22` if your node is older)
 export DATABASE_URL=file:/tmp/hello-test.db && npx prisma db push --skip-generate
 for f in tests/*.test.mjs; do node --experimental-strip-types --experimental-sqlite --import ./tests/register.mjs --test "$f"; done
 ```
-CI (`.github/workflows/ci.yml`) runs exactly these steps on Node 22. Lint touched files with `npx eslint <files>`; the repo has some pre-existing lint/tsc errors, so don't add new ones. `next.config.ts` sets `typescript.ignoreBuildErrors`, so run `npx tsc --noEmit` yourself and check your files.
+CI (`.github/workflows/ci.yml`) runs exactly these steps on Node 22. Lint touched files with `npx eslint <files>`. `next.config.ts` sets `typescript.ignoreBuildErrors`, so run `npx tsc --noEmit` yourself; CI includes typechecking.
 
 ## MCP tools (real endpoints)
-- JSON-RPC 2.0 at `POST http://localhost:3030/mcp` (`initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`). Compatibility routes: `GET /tools`, `POST /tools/call`.
+- JSON-RPC 2.0 at `POST http://localhost:3000/api/hello/mcp` (`initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`). Compatibility routes: `GET /api/hello/mcp/tools`, `POST /api/hello/mcp/call`.
+- Optional Bun sidecar mirrors the same handler at `http://localhost:3030/mcp`; compatibility routes are `GET /tools`, `POST /tools/call`.
 - Web-app views of the same data: `GET /api/hello/mcp/tools`, `GET /api/hello/mcp/feed`, `POST /api/hello/mcp/call`, `GET /api/hello/handshake`.
-- Tools: `forge.listSymbols`, `forge.readSymbol`, `forge.typecheck`, `forge.patchSymbol`, `aml.compile`, `cortex.recall`, `cortex.recordDeadEnd`, `cortex.proposeContract`, `cortex.lockInterface`, `cortex.listContracts`, `memory.recall`, `memory.write`, `cloud.checkpoint`, `cloud.rollback`, and read-only connectors `connector.sql.query|schema|fingerprint`, `connector.github.read`, `connector.openapi.reflect`, `connector.webhook.transpile`. There are no write-capable connector tools.
+- Tools: `forge.listSymbols`, `forge.readSymbol`, `forge.typecheck`, `forge.patchSymbol`, `aml.compile`, `cortex.recall`, `cortex.recordDeadEnd`, `cortex.proposeContract`, `cortex.lockInterface`, `cortex.listContracts`, `memory.recall`, `memory.write`, `cloud.checkpoint` (metadata record only), and read-only connectors `connector.sql.query|schema|fingerprint`, `connector.github.read`, `connector.openapi.reflect`, `connector.webhook.transpile`. There are no write-capable connector tools or state-restore tool.
 - Discovery: `/.well-known/agent-card.json` (also served at `/.well-known/agent.json`) and `llms.txt`.
 
 ## How signing actually works

Dockerfile

@@ -15,8 +15,10 @@ COPY --from=build /app/.next/standalone ./
 COPY --from=build /app/.next/static ./.next/static
 COPY --from=build /app/public ./public
 COPY --from=build /app/db ./db
+COPY --from=build /app/scripts/runtime-db-init.mjs ./scripts/runtime-db-init.mjs
+COPY --from=build /app/prisma/turso/init.sql ./prisma/turso/init.sql
 EXPOSE 3000
-CMD ["node", "server.js"]
+CMD ["sh", "-c", "node scripts/runtime-db-init.mjs && node server.js"]
 
 FROM oven/bun:1 AS mcp
 WORKDIR /app

README.md

@@ -27,7 +27,7 @@
 
 ## What is HELLO OS?
 
-**HELLO OS is an experimental, MIT-licensed operating layer for AI agents. It gives each agent an Ed25519 identity, tiered memory, a dead-end registry, credit-budgeted wallets with operator approval gates, a non-executable AML compiler, and a 20-tool MCP server served inside the Next.js app. It is a prototype, not a production service.**
+**HELLO OS is an experimental, MIT-licensed operating layer for AI agents. It gives each agent an Ed25519 identity, tiered memory, a dead-end registry, credit-budgeted wallets with operator approval gates, a non-executable AML compiler, and an MCP server served inside the Next.js app. It is a prototype, not a production service.**
 
 > **Status:** experimental prototype, version `0.2.1` (from `package.json`). Every feature below is labelled **Implemented**, **Prototype** or **Vision**. No benchmarks have been published.
 
@@ -68,7 +68,7 @@ Agents today mostly run inside tools built for people. HELLO OS tries a differen
 | 3 | **HELLO Cortex** | Tiered memory, dead-end registry, contract locks, semantic cache, knowledge docs | `/api/hello/cortex/*`, `/api/failures`, `/api/cache`, `/api/knowledge` | Implemented |
 | 4 | **HELLO Mesh** | In-process MCP server, A2A messages and tasks, delegation trees, consensus | `POST /api/hello/mcp`, `/api/a2a`, `/api/delegation`, `/api/consensus` | Implemented (single node); federation is Vision |
 | 5 | **HELLO Ledger** | Wallets and spend in credits (H), treasury, approvals, operator gate | `/api/economy/*`, `/api/treasury`, `/api/gate`, `/api/approvals` | Implemented (credits only, no money or tokens) |
-| 6 | **HELLO Cloud** | Checkpoints, snapshots and resume, QuickJS sandbox | `/api/hello/cloud/checkpoints`, `/api/snapshots`, `/api/sandbox` | Prototype: records are real, copy-on-write fork is simulated; microVMs are Vision |
+| 6 | **HELLO Cloud** | Checkpoint request records and QuickJS sandbox | `/api/hello/cloud/checkpoints`, `/api/sandbox` | Metadata only; no database or VM snapshots or rollback |
 | 7 | **HELLO Evolve and AI** | Deterministic evolution runs; AI provider (OpenRouter, Kilo Code gateway, any OpenAI-compatible API) for golden replay | `/api/evolution/runs`, `/api/ai/status`, `/api/traces/golden-replay` | Prototype: `/evolve` page is a labelled simulation; AI calls need a key |
 
 ```mermaid
@@ -103,7 +103,7 @@ mission review_patch {
     if $symbol.valid {
       emit: verification_receipt
     } else {
-      rollback: checkpoint("before_patch")
+      emit: review_required
     }
   }
 }
@@ -114,7 +114,7 @@ Compile it:
 ```bash
 curl -s http://localhost:3000/api/aml/compile \
   -H 'Content-Type: application/json' \
-  -d '{"source":"mission review_patch {\n  input: $patch_id\n  budget: 5 H\n  steps {\n    fetch: forge.readSymbol($patch_id) → $symbol\n    if $symbol.valid {\n      emit: verification_receipt\n    } else {\n      rollback: checkpoint(\"before_patch\")\n    }\n  }\n}"}'
+  -d '{"source":"mission review_patch {\n  input: $patch_id\n  budget: 5 H\n  steps {\n    fetch: forge.readSymbol($patch_id) → $symbol\n    if $symbol.valid {\n      emit: verification_receipt\n    } else {\n      emit: review_required\n    }\n  }\n}"}'
 ```
 
 The response includes `"ok": true`, `"executable": false`, `"budgets": [{"declaration":"review_patch","amount":5,"unit":"H"}]` and a `tokenMetrics` object.
@@ -146,7 +146,7 @@ docker compose up --build     # web on 127.0.0.1:3000
 
 ### Option 3: Vercel + Turso
 
-The live app is at **https://hello-os-bice.vercel.app/**. Serverless hosts don't keep a local SQLite file, so Vercel needs a hosted database. Turso support is in **open PR #30** and is not on `main` yet. Once #30 merges:
+The live app is at **https://hello-os-bice.vercel.app/**. Serverless hosts don't keep a local SQLite file, so Vercel needs a hosted database. Turso is supported through Prisma's libSQL adapter:
 
 ```bash
 turso auth login
@@ -162,11 +162,11 @@ Then set `DATABASE_URL`, `TURSO_AUTH_TOKEN`, `HELLO_AI_PROVIDER` and `HELLO_AI_A
 
 | Variable | Purpose |
 |---|---|
-| `DATABASE_URL` | SQLite file (`file:./db/custom.db`), or a `libsql://` URL with #30 |
-| `TURSO_AUTH_TOKEN` | Turso token (#30) |
+| `DATABASE_URL` | SQLite file (`file:./db/custom.db`), or a `libsql://` URL |
+| `TURSO_AUTH_TOKEN` | Turso auth token |
 | `HELLO_PUBLIC_URL` | Public base URL used in the handshake and agent card |
 | `HELLO_ALLOWED_ORIGINS` | Comma-separated origins allowed to call MCP |
-| `HELLO_OPERATOR_TOKEN` | Protects approvals, kill switch, scheduler, sandbox. If unset, the app runs in dev mode |
+| `HELLO_OPERATOR_TOKEN` | Protects approvals, kill switch, scheduler, sandbox. Required in production; local development can use dev mode |
 | `HELLO_WEBHOOK_SECRET` | HMAC secret for `POST /api/integrations/webhook` |
 | `GITHUB_TOKEN` | Optional read-only token for `connector.github.read` |
 | `HELLO_AI_PROVIDER` | `openrouter`, `kilo`, or `custom`. If unset, AI routes return `503 NO_AI_PROVIDER` |
@@ -198,7 +198,7 @@ curl -s https://hello-os-bice.vercel.app/api/hello/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}'
 ```
 
-### The 20 MCP tools
+### MCP tools
 
 | Tool | What it does |
 |---|---|
@@ -214,15 +214,18 @@ curl -s https://hello-os-bice.vercel.app/api/hello/mcp \
 | `cortex.listContracts` | List active contract locks |
 | `memory.recall` | Search one agent's tiered memory within a token budget |
 | `memory.write` | Write a memory to CORE, RECALL or ARCHIVE with a lifetime |
-| `cloud.checkpoint` | Record a checkpoint before a risky change (copy-on-write fork is simulated) |
-| `cloud.rollback` | Roll back to a checkpoint |
+| `cloud.checkpoint` | Record a checkpoint request for audit; captures no state and cannot be rolled back |
 | `connector.sql.query` | Read-only single SELECT/WITH against the HELLO datasource |
 | `connector.sql.schema` | Reflect tables and columns |
 | `connector.sql.fingerprint` | SHA-256 schema fingerprint for drift checks |
 | `connector.github.read` | Read-only GitHub repo, issue and PR metadata |
 | `connector.openapi.reflect` | Turn an OpenAPI 3 document into candidate tool definitions (never calls it) |
 | `connector.webhook.transpile` | Map a webhook payload to a typed, observe-only intent record |
 
+## Session portability
+
+The optional local CLI/TUI discovers Claude Code, Codex, and OpenCode sessions and ports selected text transcripts between them. It runs on your computer; the HELLO OS web app never reads local harness files. Install Bun, then run `npm run sessions:install`, `npm run sessions -- detect`, or `npm run sessions -- tui`. Transfers are manual; tool calls, reasoning blocks, and attachments are not preserved. See the [session guide](/sessions) and [third-party notices](THIRD_PARTY_NOTICES.md).
+
 ## Downloads
 
 **No binaries have been published yet.** There are no installers (APK, EXE, DEB, DMG) and no release checksums. Run from source or Docker.
@@ -242,7 +245,7 @@ No. Credits (H) are prototype numbers in the database. There is no on-chain ledg
 Yes. Retire the agent or use the kill switch. Identities can be revoked by the operator, and gated actions above the approval threshold wait for a human.
 
 ### Does it run agents in microVMs?
-No. Firecracker microVMs and copy-on-write (CoW) checkpoints are **not built**; they are Vision. Code runs in a QuickJS sandbox, and checkpoint forks are simulated and labelled as simulations.
+No. Firecracker microVMs and copy-on-write checkpoints are **not built**; they are Vision. Code runs in a QuickJS sandbox. Checkpoint calls create metadata-only audit records; they capture no state and cannot restore or roll back anything.
 
 ### Are Evolution Lab and HELLO EVOLVE real training?
 No. HELLO Evolve scores are a **deterministic simulation**: they measure the distance of candidate gene vectors to fixed target gene vectors (a candidate matching the target scores 100). They do **not** measure whether an agent got better at real tasks. The `/evolve` page is a labelled browser simulation.
@@ -263,7 +266,7 @@ Yes: [`/llms.txt`](https://codesbyfebin.github.io/Hello-OS/llms.txt), [`AGENTS.m
 
 These items are proposed, not done, and have no committed dates. The full list is in `src/lib/roadmap/steps.ts` and on the `/roadmap` page.
 
-- Turso database for serverless hosting (PR #30, open)
+- Production-grade hosted database operations and deployment hardening
 - Real file and SQLite checkpoints with restore and SHA-256 receipts
 - `/evolve` driven by stored evolution runs and golden-set replay
 - Real evolution evaluation loop: a small set of pinned, versioned agent tasks; per-candidate results reported separately for task success, policy violations, latency and token usage; stored model/provider, prompt version, test revision and traces; promotion only when recorded tests pass and a reviewer approves

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third-party notices
+
+## Session portability utility
+
+The local session-portability utility adapts code from [`mem0ai/openmemory`](https://github.com/mem0ai/openmemory), upstream commit `2df78cc48e5f688a771fee5b39899325accc2450` (MIT License). The command, interface, metadata, storage namespace, and HELLO OS integration have been adapted for this repository. No upstream logos or user-facing product branding are included.
+
+Copyright (c) 2026 Howard Gil
+
+The full upstream MIT license text is retained at [`tools/session-portability/UPSTREAM-LICENSE`](tools/session-portability/UPSTREAM-LICENSE).

compose.yaml

@@ -7,41 +7,11 @@ services:
       - "127.0.0.1:3000:3000"
     environment:
       DATABASE_URL: file:/app/db/custom.db
-      HELLO_MCP_URL: http://mcp:3030
       HELLO_PUBLIC_URL: ${HELLO_PUBLIC_URL:-http://localhost:3000}
-      # Operator auth: containers run with NODE_ENV=production, so operator actions fail closed
-      # unless you set a token, or HELLO_OPERATOR_DEV_MODE=1 for a local-only instance.
       HELLO_OPERATOR_TOKEN: ${HELLO_OPERATOR_TOKEN:-}
       HELLO_OPERATOR_DEV_MODE: ${HELLO_OPERATOR_DEV_MODE:-}
     volumes:
       - hello-data:/app/db
-    depends_on:
-      mcp:
-        condition: service_healthy
-    restart: unless-stopped
-
-  mcp:
-    build:
-      context: .
-      target: mcp
-    ports:
-      - "127.0.0.1:3030:3030"
-    environment:
-      DATABASE_URL: file:/app/db/custom.db
-      HELLO_PUBLIC_URL: ${HELLO_PUBLIC_URL:-http://localhost:3000}
-      HELLO_ALLOWED_ORIGINS: http://localhost:3000,http://127.0.0.1:3000,http://localhost:3030,http://127.0.0.1:3030
-      # Operator auth: containers run with NODE_ENV=production, so operator actions fail closed
-      # unless you set a token, or HELLO_OPERATOR_DEV_MODE=1 for a local-only instance.
-      HELLO_OPERATOR_TOKEN: ${HELLO_OPERATOR_TOKEN:-}
-      HELLO_OPERATOR_DEV_MODE: ${HELLO_OPERATOR_DEV_MODE:-}
-    volumes:
-      - hello-data:/app/db
-    healthcheck:
-      test: ["CMD", "bun", "-e", "fetch('http://127.0.0.1:3030/').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 15s
     restart: unless-stopped
 
 volumes: