[cold-review] feat: session-attached long-running jobs (#1404)

.github/workflows/android.yml

@@ -0,0 +1,42 @@
+name: android
+
+on:
+    push:
+        branches:
+            - main
+        paths:
+            - 'android/**'
+            - 'shared/fixtures/**'
+            - '.github/workflows/android.yml'
+    pull_request:
+        paths:
+            - 'android/**'
+            - 'shared/fixtures/**'
+            - '.github/workflows/android.yml'
+
+permissions:
+    contents: read
+
+concurrency:
+    group: android-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        defaults:
+            run:
+                working-directory: android
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-java@v4
+              with:
+                  distribution: temurin
+                  java-version: '21'
+            # Android SDK is preinstalled on GitHub ubuntu runners (licenses
+            # accepted); AGP auto-installs any missing platform/build-tools.
+            - uses: gradle/actions/setup-gradle@v4
+            - name: Protocol tests (pure JVM, fixtures-driven)
+              run: ./gradlew :core:protocol:test
+            - name: Assemble debug APK
+              run: ./gradlew :app:assembleDebug

.github/workflows/fixtures.yml

@@ -0,0 +1,58 @@
+name: fixtures
+
+on:
+    push:
+        branches:
+            - main
+        paths:
+            - 'web/src/chat/**'
+            - 'web/src/lib/message-window-store.ts'
+            - 'web/src/lib/sessionPatch.ts'
+            - 'web/src/lib/messages.ts'
+            - 'shared/src/**'
+            - 'web/scripts/**'
+            - 'shared/fixtures/**'
+            - '.github/workflows/fixtures.yml'
+    pull_request:
+        paths:
+            - 'web/src/chat/**'
+            - 'web/src/lib/message-window-store.ts'
+            - 'web/src/lib/sessionPatch.ts'
+            - 'web/src/lib/messages.ts'
+            - 'shared/src/**'
+            - 'web/scripts/**'
+            - 'shared/fixtures/**'
+            - '.github/workflows/fixtures.yml'
+
+permissions:
+    contents: read
+
+concurrency:
+    group: fixtures-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    drift-gate:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: oven-sh/setup-bun@v2
+              with:
+                  bun-version: 1.3.14
+            - run: bun install
+            - name: Regenerate fixtures from the web pipeline
+              run: bun run gen:fixtures
+            - name: Fail on fixtures drift
+              id: drift
+              # --intent-to-add makes brand-new fixture files (new cases) visible
+              # to git diff; deletions of stale files are visible either way.
+              run: |
+                  git add --intent-to-add shared/fixtures
+                  git diff --exit-code -- shared/fixtures
+            - name: Explain drift
+              if: failure() && steps.drift.conclusion == 'failure'
+              run: echo '::error::web pipeline behavior changed — run `bun run gen:fixtures` and commit the updated fixtures so native ports see the diff'
+            - name: Web self-conformance (fixture-related tests)
+              # src/lib/sessionPatch matches nothing until K7 lands its tests;
+              # vitest unions filters, so the extra filter is future-proof, not fatal.
+              run: cd web && bun run test -- src/chat/fixtures.test.ts src/lib/message-window-store.test.ts src/lib/messages.test.ts src/lib/sessionPatch

.github/workflows/ios.yml

@@ -0,0 +1,40 @@
+name: ios
+
+on:
+    push:
+        branches:
+            - main
+        paths:
+            - 'ios/**'
+            - 'shared/fixtures/**'
+            - '.github/workflows/ios.yml'
+    pull_request:
+        paths:
+            - 'ios/**'
+            - 'shared/fixtures/**'
+            - '.github/workflows/ios.yml'
+
+concurrency:
+    group: ios-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    package-tests:
+        runs-on: macos-15
+        steps:
+            - uses: actions/checkout@v4
+            - name: Show toolchain versions
+              run: |
+                  xcodebuild -version
+                  swift --version
+            - name: Run HapiKit package tests
+              run: swift test --package-path ios/Packages/HapiKit
+
+    app-build:
+        runs-on: macos-15
+        steps:
+            - uses: actions/checkout@v4
+            - name: Show toolchain versions
+              run: xcodebuild -version
+            - name: Build Hapi app for iOS Simulator
+              run: xcodebuild build -project ios/Hapi.xcodeproj -scheme Hapi -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO

.gitignore

@@ -36,6 +36,7 @@ coverage/
 
 # Claude local settings
 .claude/settings.local.json
+.claude/worktrees/
 localdocs/
 execplan/
 
@@ -50,3 +51,26 @@ e2e-output/
 .xyz-harness
 .agents/
 .pi/
+
+# Xcode / iOS build artifacts
+ios/**/xcuserdata/
+# Standalone projects recreate this workspace wrapper; keep Package.resolved trackable.
+ios/**/*.xcodeproj/project.xcworkspace/contents.xcworkspacedata
+ios/**/.build/
+ios/**/.swiftpm/
+**/*.xcresult
+**/DerivedData/
+
+# Android (android/)
+android/**/build/
+android/.gradle/
+android/.kotlin/
+android/local.properties
+android/captures/
+*.keystore
+*.jks
+
+# Firebase config is per-operator (official builds inject via CI; self-builds
+# drop in their own) — never commit a real one. The committed placeholder is
+# android/app/google-services.json.example.
+android/app/google-services.json

AGENTS.md

@@ -11,15 +11,18 @@ Local-first platform for running AI coding agents (Claude Code, Codex, Gemini) w
 ## Repo layout
 
 ```
-cli/     - CLI binary, agent wrappers, runner daemon
-hub/     - HTTP API + Socket.IO + SSE + Telegram bot
-web/     - React PWA for remote control
-shared/  - Common types, schemas, utilities
-docs/    - VitePress documentation site
-website/ - Marketing site
+cli/             - CLI binary, agent wrappers, runner daemon
+hub/             - HTTP API + Socket.IO + SSE + Telegram bot
+web/             - React PWA for remote control
+ios/             - Native SwiftUI app (in development)
+android/         - Native Kotlin Compose app (in development)
+shared/          - Common types, schemas, utilities
+shared/fixtures/ - Golden chat fixtures, generated from web pipeline (never hand-edit)
+docs/            - VitePress documentation site
+website/         - Marketing site
 ```
 
-Bun workspaces; `shared` consumed by cli, hub, web.
+Bun workspaces; `shared` consumed by cli, hub, web. `ios`/`android` outside workspaces (Xcode / Gradle toolchains).
 
 ## Architecture overview
 
@@ -64,11 +67,15 @@ Bun workspaces; `shared` consumed by cli, hub, web.
 
 ```bash
 bun typecheck           # All packages
-bun run test            # cli + hub tests
+bun run test            # cli + hub + web + shared tests
 bun run dev             # hub + web concurrently
 bun run build:single-exe # All-in-one binary
+bun run gen:fixtures    # Regenerate shared/fixtures/ from web pipeline
+cd android && ./gradlew :core:protocol:test  # Android protocol conformance
 ```
 
+iOS tests run in CI (`ios.yml`: macOS `swift test`); no local Xcode/Swift toolchain assumed.
+
 ## Key source dirs
 
 ### CLI (`cli/src/`)
@@ -109,6 +116,22 @@ bun run build:single-exe # All-in-one binary
 - `messages.ts` - Message parsing utilities
 - `modes.ts` - Permission/model mode definitions
 
+### iOS (`ios/`)
+- `Packages/HapiKit/` - local SPM package: `HapiProtocol` (wire models + chat pipeline, fixtures-verified), `HapiClient` (API/auth/SSE/stores)
+- `Hapi/` + `Hapi.xcodeproj` - thin SwiftUI app target
+
+### Android (`android/`)
+- `:core:protocol` - pure JVM wire types + chat pipeline (fixtures-verified)
+- `:core:data` - transport (OkHttp/SSE), auth, stores
+- `:app` - Compose UI, navigation, deep links, FCM
+
+## Protocol conformance (native apps)
+
+- `shared/fixtures/**` machine-generated from the web chat pipeline (source of truth). NEVER hand-edit; edit `web/scripts/fixtures/cases/` + regenerate.
+- Changing `web/src/chat/**`, `web/src/lib/message-window-store.ts`, or `web/src/lib/sessionPatch.ts`: run `bun run gen:fixtures`, commit the diff. CI enforces (`.github/workflows/fixtures.yml`); fixture diffs auto-trigger iOS/Android conformance suites (`ios.yml`/`android.yml`).
+- Native client contract docs: `docs/api/client-contract/` (auth, rest, sse, pagination, messages, errors).
+- Tracks: `ios/` (SwiftUI, iOS 17+) + `android/` (Kotlin Compose, minSdk 26) — independent codebases, share only contract + fixtures. Plan: `~/.claude/plans/web-pwa-abundant-yeti.md`.
+
 ## Pre-push self-review (agents)
 
 Before commit/push/PR: use the **`pre-push-review`** skill (`~/.cursor/skills/pre-push-review/`).
@@ -124,7 +147,7 @@ Before commit/push/PR: use the **`pre-push-review`** skill (`~/.cursor/skills/pr
 - Run: `bun run test` (from root) or `bun run test` (from package)
 - Hub tests: `hub/src/**/*.test.ts`
 - CLI tests: `cli/src/**/*.test.ts`
-- No web tests currently
+- Web tests: `web/src/**/*.test.{ts,tsx}` (fixtures self-check: `web/src/chat/fixtures.test.ts`)
 
 ## Common tasks
 
@@ -139,6 +162,7 @@ Before commit/push/PR: use the **`pre-push-review`** skill (`~/.cursor/skills/pr
 | Modify message handling | `hub/src/sync/messageService.ts` |
 | Add notification type | `hub/src/notifications/` |
 | Add shared type | `shared/src/types.ts`, `shared/src/schemas.ts` |
+| Attach outliving job | `cli/src/commands/job.ts`, `docs/guide/session-jobs.md` |
 
 ## Important patterns
 
@@ -148,6 +172,20 @@ Before commit/push/PR: use the **`pre-push-review`** skill (`~/.cursor/skills/pr
 - **Permission modes**: `default`, `acceptEdits`, `auto`, `bypassPermissions`, `plan`
 - **Namespaces**: Multi-user isolation via `CLI_API_TOKEN:<namespace>` suffix
 
+## Session-attached jobs (outliving work)
+
+When an agent starts process-shaped work that will keep running after the agent goes idle (`nohup`, batch imports, long scripts, external daemons), attach it so the session list stays truthful while `active: false`. This is **not** thinking progress / todos / in-agent background tools. It is also **not** an A2A Layer 1 `work_ad` ([#1332](https://github.com/tiann/hapi/discussions/1332)) — jobs enrich Layer 0 `SessionSummary`; leave collaboration claims / handoffs to the work-graph ledger.
+
+Agent contract (idle agents cannot heartbeat — bare set + nohup freezes the bar):
+
+1. **Required for process-shaped work:** Shell `hapi job run <session-id> <key> --label … -- <cmd>` (auto-heartbeat + exit status). Use `"$HAPI_SESSION_ID"` only when it matches the operator chat row (`/sessions/<id>` in the web URL); for remote Cursor runner, pass that URL UUID explicitly (shell env can point at a worker row — see `docs/guide/session-jobs.md`).
+2. MCP `session_job` **refuses `action=set`**. Use it only for `update` / `clear` / `list` on a job the supervisor already created
+3. Manual CLI `set` only with a self-heartbeating wrapper (`update` ≥~10m); never MCP set + nohup
+4. Prefer honest `--remaining` or `--done`/`--total`; omit counts if unknown — never invent a percent
+5. Elapsed wall clock is always shown from `startedAt` (not an ETA); correct late attach with CLI `set --started-at` (or clear+set)
+
+Full guide: `docs/guide/session-jobs.md`. CLI: `hapi job --help`.
+
 ## Adding new web features — consider an FUE
 
 When you ship a non-essential feature (the 20% of sessions, not the 80%), consider wrapping its affordance in the generic First-User-Experience primitive so existing users discover it without a giant always-visible UI block.

README.md

@@ -42,6 +42,10 @@ For self-hosted options (Cloudflare Tunnel, Tailscale), see [Installation](docs/
 - [Why HAPI](docs/guide/why-hapi.md)
 - [FAQ](docs/guide/faq.md)
 
+## Native apps (iOS / Android)
+
+Fully native SwiftUI and Kotlin Compose clients are in development under `ios/` and `android/`. They pair with your hub by scanning the same terminal QR code as the web app, and follow the same protocol — see the [client contract docs](docs/api/client-contract/index.md).
+
 ## Build from source
 
 ```bash