devartifex
diff --git a/‎.env.example‎
Lines changed: 12 additions & 0 deletions b/‎.env.example‎
Lines changed: 12 additions & 0 deletions
diff --git a/‎.github/copilot-instructions.md‎
Lines changed: 57 additions & 8 deletions b/‎.github/copilot-instructions.md‎
Lines changed: 57 additions & 8 deletions
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 3 additions & 0 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 1 addition & 2 deletions b/‎CONTRIBUTING.md‎
Lines changed: 1 addition & 2 deletions
diff --git a/‎Dockerfile‎
Lines changed: 1 addition & 1 deletion b/‎Dockerfile‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎README.md‎
Lines changed: 120 additions & 4 deletions b/‎README.md‎
Lines changed: 120 additions & 4 deletions
@@ -11,3 +11,15 @@ SESSION_SECRET=
 # Set to share session state with the Copilot CLI.
 # Example: ~/.copilot (matches the CLI's default config directory)
 # COPILOT_CONFIG_DIR=~/.copilot
+
+# === Push Notifications (optional) ===
+# Generate keys with: node scripts/generate-vapid-keys.mjs
+# iOS push requires the app to be installed as a PWA (Add to Home Screen in Safari).
+VAPID_PUBLIC_KEY=
+VAPID_PRIVATE_KEY=
+VAPID_SUBJECT=mailto:admin@example.com
+
+# === Custom Data Paths (optional, defaults shown) ===
+# Override where chat history and push subscriptions are stored.
+# CHAT_STATE_PATH=.chat-state
+# PUSH_STORE_PATH=.push-subscriptions
@@ -17,6 +17,10 @@ Self-hosted multi-model AI chat platform powered by the official `@github/copilo
 - **Settings**: Persisted server-side via `/api/settings` and mirrored in `localStorage`
 - **Deployment**: Docker container → Azure Container Apps via `azd up`
 
+### Deployment
+- **Azure**: VNet with subnets, Key Vault for secrets, Premium ACR, NFS volume with private endpoints; `COPILOT_CONFIG_DIR=/data/copilot-home`
+- **Local Docker**: Bind mount `~/.copilot` preserved for CLI sync; `COPILOT_CONFIG_DIR` stays at `/home/node/.copilot`
+
 ## Tech Stack
 
 | Layer | Technology |
@@ -46,22 +50,53 @@ svelte.config.js                # SvelteKit config (adapter-node)
 vite.config.ts                  # Vite config
 vitest.config.ts                # Vitest config for colocated unit tests
 
+scripts/
+└── generate-vapid-keys.mjs     # VAPID key generation utility for push notifications
+static/
+├── manifest.json               # PWA manifest (name, icons, start_url, display: standalone)
+└── sw.js                       # Service worker: precaching, push handler, notification click
+infra/
+├── modules/
+│   ├── vnet.bicep              # Azure VNet with subnets for private endpoints
+│   └── key-vault.bicep         # Azure Key Vault for secrets management
+
 src/
 ├── app.html                    # SvelteKit shell (viewport, theme-color, PWA meta)
 ├── app.css                     # Global reset, design tokens, highlight.js theme
-├── hooks.server.ts             # Session bridge, CSP headers, rate limiting
+├── hooks.server.ts             # Session bridge, CSP headers, rate limiting, CSRF, token revalidation
 ├── hooks.server.test.ts        # Example colocated unit test pattern
 │
 ├── lib/
 │   ├── components/             # 20 Svelte 5 components (see ARCHITECTURE.md)
 │   ├── stores/                 # 4 rune stores: auth, chat, settings, ws
-│   ├── server/                 # 22 server files: auth, copilot, settings, skills, ws, security
+│   ├── server/                 # Server-only code
+│   │   ├── auth/
+│   │   │   ├── github.ts              # Device Flow OAuth (fetch-based)
+│   │   │   └── guard.ts               # Auth middleware + 30-min token revalidation
+│   │   ├── copilot/
+│   │   │   ├── client.ts              # CopilotClient factory
+│   │   │   └── session.ts             # Session config (model, reasoning, tools, hooks)
+│   │   ├── ws/
+│   │   │   ├── handler.ts             # WebSocket handler: 22+ message types, SDK events
+│   │   │   └── session-pool.ts        # Per-user session pool with TTL + buffer
+│   │   ├── push/
+│   │   │   ├── subscription-store.ts  # Push subscription CRUD per user (10 sub cap)
+│   │   │   └── sender.ts             # web-push wrapper with 60-min TTL, auto-cleanup
+│   │   ├── chat-state-store.ts        # Persistent chat state per user+tab (1000-msg cap, atomic writes)
+│   │   ├── session-watcher.ts         # fs.watch on session-state dir, 100ms debounce
+│   │   ├── init.ts                    # Server-side initialization (watcher + signal handlers)
+│   │   ├── config.ts                  # Env var validation (fail-fast)
+│   │   ├── security-log.ts            # Structured security event logging
+│   │   └── session-store.ts           # Express session ↔ SvelteKit bridge
 │   ├── types/index.ts          # All message types: 60 server + 18 client = 78 total
-│   └── utils/markdown.ts       # Shared markdown pipeline
+│   └── utils/
+│       ├── markdown.ts         # Shared markdown pipeline
+│       ├── push-client.ts      # Client-side push subscription management
+│       └── sw-register.ts      # Service worker registration
 │
 ├── routes/
 │   ├── +page.svelte            # Main page: login or full chat screen (1 page route)
-│   ├── +layout.svelte          # App shell layout
+│   ├── +layout.svelte          # App shell layout (registers service worker)
 │   ├── +layout.server.ts       # Root auth/session bootstrap
 │   ├── +error.svelte           # Route error boundary
 │   ├── auth/
@@ -76,8 +111,11 @@ src/
 │   │   ├── skills/+server.ts
 │   │   ├── upload/+server.ts
 │   │   ├── version/+server.ts
-│   │   └── sessions/sync/+server.ts
-│   └── health/+server.ts       # 12 +server.ts endpoint routes total
+│   │   ├── sessions/sync/+server.ts
+│   │   ├── push/subscribe/+server.ts     # POST: register push subscription
+│   │   ├── push/unsubscribe/+server.ts   # POST: remove push subscription
+│   │   └── push/vapid-key/+server.ts     # GET: public VAPID key
+│   └── health/+server.ts       # 18 +server.ts endpoint routes total
 │
 └── **/*.test.ts                # Vitest unit tests live next to source files
 ```
@@ -105,6 +143,10 @@ src/
 - **Try-catch** in route handlers and WebSocket — return JSON errors to client
 - **Message type whitelist** — WebSocket handler validates against `VALID_MESSAGE_TYPES` Set
 - **Session disconnect** — use `session.disconnect()` (not deprecated `destroy()`)
+- **Atomic file writes** — ChatStateStore (and settings-store) writes to `.tmp` then renames, preventing partial reads on crash
+- **Session watcher** — `fs.watch` on session-state directory with 100ms debounce, broadcasts state changes to all connected WS clients
+- **Push on disconnect** — Push notifications triggered in `poolSend()` when the target user's WS is disconnected
+- **Cold resume** — Load persisted chat state from disk, resume SDK session via `client.resumeSession()`, replay messages to the client
 
 ### Security
 - CSP in hooks.server.ts: self + unsafe-inline (Svelte) + ws/wss + GitHub avatars
@@ -113,8 +155,11 @@ src/
 - XSS prevention: DOMPurify sanitizes all rendered markdown
 - Max message length: 10,000 chars (server-enforced)
 - Upload limits: 10MB per file, 5 files max, extension allowlist
-- SSRF prevention: internal IP range blocklist for custom webhook tools
+- SSRF prevention: internal IP range blocklist for custom webhook tools; `redirect:'manual'` on all outbound fetches
 - Token revalidation on WebSocket connect (catches revoked tokens)
+- All API endpoints require `checkAuth()` except `/health`
+- CSRF: Origin header required on mutation requests in production
+- Periodic token revalidation every 30 minutes (server-side interval)
 
 ### Environment Variables
 | Variable | Required | Default | Purpose |
@@ -126,6 +171,11 @@ src/
 | `NODE_ENV` | No | development | Dev vs prod behavior |
 | `ALLOWED_GITHUB_USERS` | No | — | Comma-separated GitHub usernames |
 | `TOKEN_MAX_AGE_MS` | No | 86400000 | Force re-auth interval (24h) |
+| `CHAT_STATE_PATH` | No | ./data/chat-state | Directory for persisted chat state files |
+| `VAPID_PUBLIC_KEY` | No | — | VAPID public key for web push (generate with `scripts/generate-vapid-keys.mjs`) |
+| `VAPID_PRIVATE_KEY` | No | — | VAPID private key for web push |
+| `VAPID_SUBJECT` | No | — | VAPID subject (mailto: or https: URL) |
+| `PUSH_STORE_PATH` | No | ./data/push-subscriptions | Directory for push subscription storage |
 
 ## Build & Run
 
@@ -138,7 +188,6 @@ npm install && npm run build && npm start
 
 # Development
 npm run dev                      # Docker Compose development stack
-npm run dev:local                # Local Vite dev server after building server-side TypeScript
 
 # Type check
 npm run check                    # svelte-check
 
@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main, master]
 
+permissions:
+  contents: read
+
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
 
@@ -7,13 +7,12 @@ Thank you for your interest in contributing! This project is a self-hosted, mult
 1. Fork the repo and clone it
 2. Install dependencies: `npm install`
 3. Create a `.env` file (see README for required variables)
-4. Run in development mode: `npm run dev:local`
+4. Run in development mode: `npm run dev`
 
 ## Development
 
 | Command | Purpose |
 |---------|---------|
-| `npm run dev:local` | Start Vite dev server |
 | `npm run dev` | Start via Docker Compose |
 | `npm run build` | Production build |
 | `npm run check` | Type check with svelte-check |
 
@@ -25,7 +25,7 @@ ENV PORT=3000
 ENV HOME=/home/node
 
 RUN npm install -g @github/copilot
-RUN mkdir -p /home/node/.copilot/session-state /data/sessions /data/settings && chown -R node:node /home/node /data
+RUN mkdir -p /home/node/.copilot/session-state /data/sessions /data/settings /data/chat-state /data/push-subscriptions /data/copilot-home && chown -R node:node /home/node /data
 
 # Copy bundled CLI session data if it was prepared with scripts/bundle-sessions.mjs
 COPY --from=builder --chown=node:node /tmp/copilot-config/ /home/node/.copilot/
 
@@ -51,8 +51,9 @@ Your Copilot subscription already gives you access to Claude Opus 4.6, GPT-5.4,
 - **Image vision** — attach images alongside code and documents; vision-capable models analyze them inline
 - **File & directory attachments** — drop in code files, images, CSVs, or whole directories with `@` mention autocomplete
 - **Issue & PR references** — type `#` to search and reference GitHub issues/PRs across all your repos
-- **Persistent sessions** — resume any conversation, on any device, with full checkpoint history
-- **CLI ↔ Browser sync** — sessions started in the Copilot CLI appear in the browser and vice versa
+- **Persistent sessions** — resume any conversation on any device with full checkpoint history; chat state survives browser close via server-side storage with cold resume from disk
+- **CLI ↔ Browser sync** — sessions started in the Copilot CLI appear in the browser and vice versa, with automatic filesystem watcher and Docker bind mount for real-time sync
+- **Push notifications** — Web Push alerts when the browser is closed; triggers on response ready, errors, permission prompts, and user input; full PWA support (iOS 16.4+ requires "Add to Home Screen" from Safari)
 - **Plan mode** — agent creates an editable execution plan before acting; bidirectional sync with `plan.md` on disk
 - **Fleet mode** — launch multi-agent parallel execution with per-agent status tracking
 - **Quota tracking** — see premium request usage, remaining balance, and reset date at a glance
@@ -143,7 +144,81 @@ Open [localhost:3000](http://localhost:3000). Log in with GitHub. Done.
 azd up
 ```
 
-That's it. Container Apps, ACR, managed identity, TLS, monitoring — all provisioned automatically.
+That's it. Container Apps, ACR, Key Vault, managed identity, VNet, TLS, and monitoring — all provisioned automatically.
+
+### Required parameters
+
+`azd up` will prompt for these if not already set:
+
+| Parameter | How to set | Notes |
+|-----------|-----------|-------|
+| `GITHUB_CLIENT_ID` | `azd env set GITHUB_CLIENT_ID <id>` | Your GitHub OAuth App client ID |
+| `SESSION_SECRET` | auto-generated as `newGuid()` if omitted | 32+ char random string |
+
+### Deployer IP (required for `azd deploy` with private ACR)
+
+The default infrastructure uses a **Premium ACR with public network access disabled** and a private endpoint. This blocks `azd deploy` pushes from your local machine. Set your current public IP before deploying:
+
+```bash
+azd env set DEPLOYER_IP_ADDRESS "$(curl -s https://api.ipify.org)"
+azd up
+```
+
+The ACR firewall will allow only that IP (`defaultAction: Deny`, single `Allow` rule). All other public access remains blocked. For CI/CD pipelines, set `DEPLOYER_IP_ADDRESS` to the runner's outbound IP in the same way.
+
+### Optional: VAPID keys for push notifications
+
+```bash
+node scripts/generate-vapid-keys.mjs
+azd env set VAPID_PUBLIC_KEY  "<key>"
+azd env set VAPID_PRIVATE_KEY "<key>"
+azd env set VAPID_SUBJECT     "mailto:you@example.com"
+```
+
+### Bootstrapping secrets in Key Vault
+
+`azd provision` stores `GITHUB_CLIENT_ID`, `SESSION_SECRET`, and (optionally) VAPID keys as secrets in Azure Key Vault. The Container App reads them at runtime via the managed identity — no secrets in environment variables or container image.
+
+### Troubleshooting `azd up`
+
+<details>
+<summary>Container App fails with MANIFEST_UNKNOWN image tag</summary>
+
+If provisioning fails mid-run, the `.azure/<env>/.env` may hold a stale `SERVICE_WEB_IMAGE_NAME` pointing to a tag that no longer exists in a newly-recreated ACR. Clear it before retrying:
+
+```bash
+azd env set SERVICE_WEB_IMAGE_NAME ""
+azd up
+```
+
+`azd provision` will deploy with the placeholder image; `azd deploy` pushes the real image immediately after.
+
+</details>
+
+<details>
+<summary>ACR push fails with 403 Forbidden / IP not allowed</summary>
+
+Set your public IP and re-provision to open the ACR firewall:
+
+```bash
+azd env set DEPLOYER_IP_ADDRESS "$(curl -s https://api.ipify.org)"
+azd provision   # updates ACR network rules
+azd deploy      # push succeeds
+```
+
+</details>
+
+<details>
+<summary>Container App fails: unable to fetch secret from Key Vault</summary>
+
+This means the Key Vault secret doesn't exist yet (typically on a fresh deploy). Ensure `GITHUB_CLIENT_ID` is set and run `azd provision` again — it will create the secrets in Key Vault as part of infra creation.
+
+```bash
+azd env set GITHUB_CLIENT_ID "<your-id>"
+azd provision
+```
+
+</details>
 
 ---
 
@@ -170,16 +245,29 @@ That's it. Container Apps, ACR, managed identity, TLS, monitoring — all provis
 | `SESSION_STORE_PATH` | `/data/sessions` | Persistent session directory |
 | `SETTINGS_STORE_PATH` | `/data/settings` | Per-user settings directory |
 | `COPILOT_CONFIG_DIR` | `~/.copilot` | Copilot session-state directory (share with CLI for bidirectional sync) |
+| `CHAT_STATE_PATH` | `.chat-state` (dev) / `/data/chat-state` (prod) | Persisted chat state storage |
+| `VAPID_PUBLIC_KEY` | — | VAPID public key (base64url) — required for push notifications |
+| `VAPID_PRIVATE_KEY` | — | VAPID private key (base64url) — required for push notifications |
+| `VAPID_SUBJECT` | `mailto:admin@example.com` | VAPID subject identifier |
+| `PUSH_STORE_PATH` | `/data/push-subscriptions` | Push subscription storage path |
 
 </details>
 
+### Generate VAPID keys (for push notifications)
+
+```bash
+node scripts/generate-vapid-keys.mjs
+```
+
+Copy the output into your `.env` file. Push notifications require all three VAPID variables (`VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT`).
+
 ---
 
 ## CLI ↔ Browser session sync
 
 Copilot Unleashed and the GitHub Copilot CLI share the same session-state directory (`~/.copilot/session-state/`). By default, the app reads from the same location the CLI uses — so any session started in the terminal is available in the browser the moment you open the Sessions panel.
 
-> **Note:** When running via Docker (`npm run dev`), the `docker-compose.yml` mounts `~/.copilot` read-only into the container. If you use `npm run dev:local` (no Docker), the app reads directly from your host `~/.copilot` with no extra config needed.
+> **Note:** When running via Docker (`npm run dev`), the `docker-compose.yml` mounts `~/.copilot` read-only into the container.
 
 ### How it works
 
@@ -303,11 +391,39 @@ Scopes: `copilot` (API access) + `read:user` (avatar) + `repo` (SDK tools need i
 - Structured security event logging
 - Optional user allowlist via `ALLOWED_GITHUB_USERS`
 - CodeQL scanning + secret scanning via GitHub Advanced Security
+- All API endpoints require GitHub authentication — no anonymous access
+- Periodic token revalidation ensures revoked tokens are caught promptly
+- **Azure**: VNet isolation for Container Apps, Key Vault for secrets management, Premium ACR with private endpoints
 
 </details>
 
 ---
 
+## Data Persistence
+
+All stateful data survives container restarts when volumes are configured correctly.
+
+| Data | Path (default) | Survives restart? |
+|------|----------------|:-:|
+| SDK sessions & checkpoints | `COPILOT_CONFIG_DIR` (`~/.copilot`) | ✅ with volume |
+| App session metadata | `SESSION_STORE_PATH` (`/data/sessions`) | ✅ with volume |
+| Per-user settings | `SETTINGS_STORE_PATH` (`/data/settings`) | ✅ with volume |
+| Chat history | `CHAT_STATE_PATH` (`/data/chat-state`) | ✅ with volume |
+| Push subscriptions | `PUSH_STORE_PATH` (`/data/push-subscriptions`) | ✅ with volume |
+
+**Local Docker:** Use a named volume for `/data` and a bind mount for `~/.copilot` (enables CLI ↔ Browser sync).
+
+```yaml
+# docker-compose.yml
+volumes:
+  - app-data:/data                          # sessions, settings, chat state, push subs
+  - ~/.copilot:/home/node/.copilot          # SDK session-state (shared with CLI)
+```
+
+**Azure Container Apps:** Use an NFS-backed Azure Files mount at `/data`. The Bicep infrastructure provisions this automatically via `azd up`.
+
+---
+
 ## Built with
 
 SvelteKit 5 · Svelte 5 runes · TypeScript 5.7 · Node.js 24 · `@github/copilot-sdk` · Vite · `ws` · Vitest · Playwright · Docker · Bicep