prism-mcp-server 20.21.17 → 20.21.19

package/README.md

@@ -158,6 +158,22 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.21.19
+
+- Prism Browser emulates phones and tablets. `--device iphone-17`, or one of
+  five other measured iPhones and iPads, turns on touch CSS, the pixel ratio,
+  and the iPhone safe area, so a layout that only breaks on the phone can be
+  caught in a test. `--touch`, `--device-scale-factor`, and `--safe-area` set
+  each part on its own.
+
+## What's New in v20.21.18
+
+- Fixed: when a save was refused with `context_not_loaded`, the instructions
+  Prism installs for Claude Code, Codex and Gemini CLI forbade the one call
+  that recovers. The refusal now prints that call, `session_load_context`
+  with the same project and conversation_id, and the installed instructions
+  allow it. First-turn startup is unchanged.
+
 ## What's New in v20.21.17
 
 - Fixed: the on-device screen refused some ordinary coding requests. With a
@@ -1396,7 +1412,7 @@ Prism exposes 40+ MCP tools. The core memory loop:
 | Tool | What it does |
 |---|---|
 | `session_bootstrap` | Hook-free first-turn greeting and dashboard-configured context |
-| `session_load_context` | Explicit project reload or older-server startup fallback |
+| `session_load_context` | Explicit project reload, recovery after a `context_not_loaded` save refusal, or older-server startup fallback |
 | `session_save_ledger` | Append an immutable session log entry |
 | `session_save_handoff` | Save live state for the next session |
 | `knowledge_search` | Semantic + keyword search over all memories |

package/dist/connect.js

@@ -4,6 +4,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32 as w
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { CONTEXT_RECOVERY_POLICY_LINES } from "./contextRecoveryPolicy.js";
 import { EVIDENCE_WORKFLOW_POLICY_LINES } from "./evidenceWorkflowPolicy.js";
 import { LOCAL_FIRST_POLICY_ID, LOCAL_FIRST_POLICY_LINES } from "./localFirstPolicy.js";
 export const CONNECT_HOSTS = [
@@ -44,11 +45,13 @@ const CODEX_STARTUP_BODY = [
     "reformat, or omit any returned section. Preserve its order and line content. For a greeting-only prompt, stop",
     "after the verbatim startup display. If `session_bootstrap` is deferred, use native tool discovery to load that",
     "exact tool, then invoke it. Do not use shell commands, file reads, subagents, or unrelated tool inspection as",
-    "a substitute. Do not call `session_load_context`. If discovery or invocation fails, report",
+    "a substitute, and do not use `session_load_context` in place of it. If discovery or invocation fails, report",
     "`Prism startup failure` and stop. Reuse the `conversation_id` returned on the `<prism_session />` line for every",
     "session_save_ledger, session_save_handoff, and session_detect_drift call in this conversation. This hook-free",
     "block is managed by `prism connect`; do not edit it manually.",
     "",
+    ...CONTEXT_RECOVERY_POLICY_LINES,
+    "",
     ...LOCAL_FIRST_POLICY_LINES,
     "",
     ...EVIDENCE_WORKFLOW_POLICY_LINES,
@@ -578,11 +581,13 @@ function serializeClaudeStartupBlock(newline) {
         "content. For a greeting-only prompt, stop after the verbatim startup display. If `session_bootstrap` is",
         "deferred, use native tool discovery/ToolSearch to load that",
         "exact tool, then invoke it. Do not use shell commands, file reads, subagents, or unrelated tool inspection",
-        "as a substitute. Do not call `session_load_context`. If discovery or invocation fails, report",
+        "as a substitute, and do not use `session_load_context` in place of it. If discovery or invocation fails, report",
         "`Prism startup failure` and stop. Reuse the `conversation_id` returned on the `<prism_session />` line for every",
         "session_save_ledger, session_save_handoff, and session_detect_drift call in this conversation. This block is",
         "managed by `prism connect`; do not edit it manually.",
         "",
+        ...CONTEXT_RECOVERY_POLICY_LINES,
+        "",
         ...LOCAL_FIRST_POLICY_LINES,
         "",
         ...EVIDENCE_WORKFLOW_POLICY_LINES,
@@ -671,10 +676,12 @@ function serializeGeminiStartupBlock(newline) {
         "reformat, or omit any returned section. Preserve its order and line content. For a greeting-only prompt, stop",
         "after the verbatim startup display. If `session_bootstrap` is deferred, use native tool discovery/ToolSearch",
         "to load that exact tool, then invoke it.",
-        "Do not use shell commands, file reads, subagents, or unrelated tool inspection as a substitute. Do not call",
-        "`session_load_context`. If discovery or invocation fails, report `Prism startup failure` and stop. Reuse the",
-        "`conversation_id` returned on the `<prism_session />` line for session_save_ledger, session_save_handoff, and",
-        "session_detect_drift calls. This block is managed by `prism connect`; do not edit it manually.",
+        "Do not use shell commands, file reads, subagents, or unrelated tool inspection as a substitute, and do not use",
+        "`session_load_context` in place of it. If discovery or invocation fails, report `Prism startup failure` and stop.",
+        "Reuse the `conversation_id` returned on the `<prism_session />` line for session_save_ledger, session_save_handoff,",
+        "and session_detect_drift calls. This block is managed by `prism connect`; do not edit it manually.",
+        "",
+        ...CONTEXT_RECOVERY_POLICY_LINES,
         "",
         ...LOCAL_FIRST_POLICY_LINES,
         "",

package/dist/contextRecoveryPolicy.js

@@ -0,0 +1,21 @@
+/**
+ * Canonical context-recovery contract shared by every host instruction file.
+ *
+ * Startup is one `session_bootstrap` call. A later save can still be refused
+ * with `context_not_loaded`, and the refusal names one remedy; the host block
+ * must say the same thing instead of forbidding it. Keep this host-neutral: the
+ * Claude Code, Gemini CLI and Codex blocks splice these lines unchanged, and
+ * the server instructions, tool descriptions and refusal text state the same
+ * rule in their own words (pinned by tests/startup-recovery-contract.test.ts).
+ */
+export const CONTEXT_RECOVERY_POLICY_LINES = [
+    "## Prism context recovery",
+    "Startup is the one turn-one `session_bootstrap` call. Prism can still refuse `session_save_ledger` or",
+    "`session_save_handoff` with `context_not_loaded`: it has no record that this conversation loaded that project",
+    "(after a restart, a long idle gap, or for a project startup did not load). That is a recovery step, not a second",
+    "startup. Call `session_load_context` with the same `project` and the same `conversation_id` as the refused save",
+    "(the refusal prints the exact call; discover the tool the same way if it is deferred), then retry the save once.",
+    "Do not repeat `session_bootstrap` or print a startup display for it. If the reload or the retry fails, tell the",
+    "user; a local note is a fallback after that, never a substitute for the reload.",
+];
+export const CONTEXT_RECOVERY_POLICY_TEXT = CONTEXT_RECOVERY_POLICY_LINES.join(" ");

package/dist/server.js

@@ -361,8 +361,10 @@ export const PRISM_SERVER_INSTRUCTIONS = `Prism MCP — The Mind Palace for AI A
     `Emit no preamble. Print the complete tool result verbatim as the entire first-turn startup display, before any optional ` +
     `answer. Do not summarize, paraphrase, rename headings, reformat, or omit any returned section. Preserve its order and ` +
     `line content. For a greeting-only prompt, stop after the verbatim startup display. ` +
-    `Do not substitute session_load_context while session_bootstrap is available; use session_load_context ` +
-    `only for an explicit project reload or as an older-server fallback. ` +
+    `Do not substitute session_load_context for the startup call while session_bootstrap is available. Use ` +
+    `session_load_context to recover when a save is refused with context_not_loaded (pass that save's project ` +
+    `and conversation_id, then retry the save once; recovery is not a second startup), for an explicit project ` +
+    `reload, or as an older-server fallback. ` +
     `Use session_save_ledger to log completed work and session_save_handoff to preserve state for the next session. ` +
     `Reuse the conversation_id from session_bootstrap's <prism_session /> line for those saves and for ` +
     `session_detect_drift, the 60-minute goal-alignment drift check. Do not add the id to the visible greeting.\n\n` +

package/dist/session/sessionContext.js

@@ -84,24 +84,75 @@ export function markContextLoaded(conversationId, project, boundariesVersion) {
     s.boundariesVersion = boundariesVersion;
     lastSeenConversationId = conversationId;
 }
+const ENFORCED = " (Enforced server-side — applies to every host.)";
+/**
+ * The one remedy every refusal names, so the three variants cannot drift apart
+ * and the host instruction blocks (src/contextRecoveryPolicy.ts), the server
+ * instructions and the tool descriptions can say the same thing. A block that
+ * forbids the call a refusal asks for leaves an agent with no way forward
+ * (tests/startup-recovery-contract.test.ts pins every surface).
+ */
+const CONTEXT_RECOVERY = " To recover, call session_load_context with the same project and the same conversation_id you " +
+    "passed to this save, then retry the save once. You do not need to repeat session_bootstrap (it " +
+    "reloads only the dashboard Auto-Load projects and reprints the startup display). A recovery load " +
+    "is not a second startup. If the retry is refused too, stop and tell the user.";
 function contextNotLoadedError(project) {
     const projectNote = project
         ? " the requested project was not loaded for this conversation."
-        : "";
+        : " no context is registered for this conversation.";
+    return {
+        blocked: true,
+        error: "context_not_loaded:" + projectNote + CONTEXT_RECOVERY +
+            " This project-scoped tool needs confirmed working context to act correctly." + ENFORCED,
+    };
+}
+/**
+ * A save whose conversation_id is the empty string can never be recovered by
+ * "the same conversation_id you passed": the load handler registers nothing for
+ * an empty id. Say what is actually wrong and where the real id comes from.
+ */
+function emptyConversationIdError() {
     return {
         blocked: true,
-        error: "context_not_loaded:" + projectNote + " Call session_bootstrap(conversation_id) or " +
-            "session_load_context(project, conversation_id) " +
-            "before this action. This project-scoped tool needs confirmed working context " +
-            "to act correctly. (Enforced server-side — applies to every host.)",
+        error: "context_not_loaded: conversation_id is empty, so no context can be registered for it." +
+            " Pass this conversation's conversation_id (the value on session_bootstrap's <prism_session /> line)," +
+            " call session_load_context with that conversation_id and this project, then retry the save once." +
+            " If the retry is refused too, stop and tell the user." + ENFORCED,
     };
 }
 function contextExpiredError() {
     return {
         blocked: true,
-        error: "context_not_loaded: session expired (6 h TTL). Call " +
-            "session_bootstrap(conversation_id) or session_load_context(project, conversation_id) again. " +
-            "(Enforced server-side — applies to every host.)",
+        error: "context_not_loaded: session expired (6 h TTL)." + CONTEXT_RECOVERY + ENFORCED,
+    };
+}
+/**
+ * Longest project or conversation_id a refusal echoes back. A longer value gets
+ * the remedy without a literal call: a clipped value would register the wrong
+ * project, and the retry would be refused again.
+ */
+const MAX_ECHOED_VALUE = 200;
+/**
+ * Print the literal recovery call, built from the arguments the refused save
+ * used, so "the same project and conversation_id" cannot be mistyped or
+ * replaced by a host session id. Values are JSON-escaped and echoed whole, only
+ * to the caller that just sent them; a value too long to echo gets no call.
+ */
+function withExactCall(gate, conversationId, project) {
+    if (!gate || !gate.blocked || !conversationId || !project.trim() || !gate.error.endsWith(ENFORCED)) {
+        return gate;
+    }
+    if (project.length > MAX_ECHOED_VALUE || conversationId.length > MAX_ECHOED_VALUE)
+        return gate;
+    const call = JSON.stringify({
+        project,
+        conversation_id: conversationId,
+        toolAction: "Reload context",
+        toolSummary: "Recover from context_not_loaded",
+    });
+    return {
+        blocked: true,
+        error: gate.error.slice(0, -ENFORCED.length) + ` Exact call: session_load_context(${call}).` + ENFORCED,
     };
 }
 function hashReceiptScope(kind, value) {
@@ -196,9 +247,15 @@ export function requireContextLoaded(conversationId) {
  * cross-project lookups remain fail-closed.
  */
 export async function requireContextLoadedForProject(conversationId, project) {
+    const gate = await evaluateContextGateForProject(conversationId, project);
+    return conversationId === undefined ? gate : withExactCall(gate, conversationId, project);
+}
+async function evaluateContextGateForProject(conversationId, project) {
     if (conversationId === undefined)
         return null;
-    if (!conversationId || !project.trim())
+    if (!conversationId)
+        return emptyConversationIdError();
+    if (!project.trim())
         return contextNotLoadedError(project || undefined);
     const memoryGate = requireContextLoaded(conversationId);
     const memoryState = sessions.get(conversationId);

package/dist/tools/prismInferHandler.js

@@ -256,7 +256,7 @@ export function _resetLayer1HistoryCacheForTest() { layer1HistoryCache.clear();
  *    probe and read races the time left, and no clearance is accepted after it. */
 export const LAYER1_SECOND_READ_MAX_CALLS = 48;
 export const LAYER1_SECOND_READ_DEADLINE_MS = 30_000;
-/** Reads in flight at once: ONE (owner decision 2026-09-26, after review).
+/** Reads in flight at once: ONE.
  *  Two at once made each classifier read about twice as slow and some reads
  *  abort at the classifier's first-attempt timeout (an aborted read keeps the
  *  hedge: refusal or cloud), for little clearance time gained. The per-read
@@ -1498,8 +1498,8 @@ function makeReservedRefusal(verdict, attempts, category = null, cloudWasAllowed
     });
     return new ReservedRefusalError(verdict, attempts, category, cloudWasAllowed);
 }
-/** Portal cap on the flattened conversation (`ROLE: content` lines) — see
- *  portal/src/app/api/v1/prism/inference/route.ts MAX_PROMPT_BYTES. */
+/** Server cap on the flattened conversation (`ROLE: content` lines): the
+ *  Synalux inference endpoint enforces the same limit. */
 export const CLOUD_HISTORY_CAP_BYTES = 32 * 1024;
 /** Exported for tests: the cap check must be provable without a portal. */
 export async function callSynaluxInference(prompt, maxTokens, timeoutMs, opts) {

package/dist/tools/sessionMemoryDefinitions.js

@@ -4,7 +4,10 @@ export const SESSION_SAVE_LEDGER_TOOL = {
     description: "Save an immutable session log entry to the session ledger. " +
         "Use this at the END of each work session to record what was accomplished. " +
         "The ledger is append-only — entries cannot be updated or deleted. " +
-        "This creates a permanent audit trail of all agent work sessions.",
+        "This creates a permanent audit trail of all agent work sessions. " +
+        "The save is refused with context_not_loaded until session_bootstrap or session_load_context has loaded " +
+        "this exact project for this conversation_id; on that refusal call session_load_context with the same " +
+        "project and conversation_id, then retry the save once.",
     inputSchema: {
         type: "object",
         properties: {
@@ -60,7 +63,11 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
         "Pass expected_version to enable concurrency control.\n\n" +
         "**v0.4.0 OCC**: If you received a version number from session_load_context, " +
         "/resume_session prompt, or memory resource attachment, you MUST pass it as " +
-        "expected_version to prevent overwriting another session's changes.",
+        "expected_version to prevent overwriting another session's changes.\n\n" +
+        "Pass the same conversation_id as session_save_ledger: the save is refused with context_not_loaded until " +
+        "session_bootstrap or session_load_context has loaded this exact project for it; on that refusal call " +
+        "session_load_context with the same project and conversation_id, then retry the save once, passing the " +
+        "version it shows as expected_version.",
     inputSchema: {
         type: "object",
         properties: {
@@ -101,7 +108,7 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
             },
             conversation_id: {
                 type: "string",
-                description: "Optional. Session key for this conversation (same id used in session_load_context). When provided, the server verifies that session_load_context was called for this conversation before accepting the write.",
+                description: "Optional. Session key for this conversation (same id used in session_load_context). When provided, the server verifies that session_bootstrap or session_load_context loaded this exact project for this conversation before accepting the write.",
             },
         },
         required: ["project"],
@@ -111,7 +118,9 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
 export const SESSION_LOAD_CONTEXT_TOOL = {
     name: "session_load_context",
     description: "Load session context for a project using progressive context loading. " +
-        "Use this for an explicit project reload, or as a startup fallback only when session_bootstrap is unavailable. " +
+        "Use this to recover when session_save_ledger or session_save_handoff is refused with context_not_loaded " +
+        "(pass that save's project and the same conversation_id, then retry the save once; a recovery load is not a " +
+        "second startup), for an explicit project reload, or as a startup fallback only when session_bootstrap is unavailable. " +
         "When session_bootstrap is available, do not substitute this tool for the first-turn bootstrap. " +
         "Three levels available:\n" +
         "- **quick**: Just the latest project state — keywords and open TODOs (~50 tokens)\n" +
@@ -148,7 +157,7 @@ export const SESSION_LOAD_CONTEXT_TOOL = {
             },
             conversation_id: {
                 type: "string",
-                description: "Optional. Session key for this conversation (same id used in session_save_ledger). When provided, marks the session as context-loaded server-side so project-scoped tools can verify working context without relying on hook-based enforcement. Required on non-Claude hosts.",
+                description: "Optional for a plain read. Pass it whenever this load is meant to unlock saves (startup fallback, or recovery from context_not_loaded), using the same conversation_id as the refused or upcoming save. When provided, marks this project as context-loaded server-side so project-scoped saves are accepted; without it nothing is registered.",
             },
             prompt: {
                 type: "string",
@@ -209,7 +218,7 @@ export const SESSION_BOOTSTRAP_TOOL = {
         "before any user-facing response, passing the user's verbatim first message as {prompt: \"<first user message>\"}. " +
         "The prompt is matched against prompt_keywords ON-DEVICE to load symptom-triggered skills on turn one; it is used " +
         "for routing only and never leaves the machine. Pass {} only when there is no user message. " +
-        "Do not substitute session_load_context when this tool is available. " +
+        "Do not substitute session_load_context for this startup call. " +
         "This starts a Prism-backed conversation without host hooks. " +
         "Prism reads the dashboard's Auto-Load Projects, Context Depth (quick/standard/deep), developer name, and default role, " +
         "then returns the greeting and correctly scoped prior-session context. Emit no preamble. Print the complete tool result " +
@@ -217,7 +226,10 @@ export const SESSION_BOOTSTRAP_TOOL = {
         "headings, reformat, or omit any returned section. Preserve its order and line content. For a greeting-only prompt, " +
         "stop after the verbatim startup display. Do not guess or pass a project or depth. Prism returns a stable " +
         "conversation_id on the trailing <prism_session /> line; reuse it for session_save_ledger, session_save_handoff, and " +
-        "session_detect_drift throughout this conversation without adding it to the visible greeting.",
+        "session_detect_drift throughout this conversation without adding it to the visible greeting. " +
+        "This is the first-turn startup call only: if a later save is refused with context_not_loaded, recover with " +
+        "session_load_context for that save's project and conversation_id, then retry the save once, rather than " +
+        "repeating this startup display.",
     annotations: {
         readOnlyHint: true,
         destructiveHint: false,

package/dist/tools/skillRouting.js

@@ -13,8 +13,8 @@
  * regexes match, and the regexes are already public. Sending the raw first
  * message bought nothing a local match could not compute — and free-tier
  * callers paid that privacy cost for literally zero routing benefit, since
- * the portal gates them to an empty set (resolve/route.ts: `tier === 'paid' ?
- * resolved : []`). Paid skill CONTENT stays gated server-side at
+ * the server returns no prompt-matched skills to the free tier. Paid skill
+ * CONTENT stays gated server-side at
  * /api/v1/prism/skill-manifest, which this change does not touch.
  *
  * Cache: portal keyed on (project,role) — no longer per-prompt, which never
@@ -464,8 +464,8 @@ export function stripQuotedEvidenceForRouting(prompt, promptKeywords = {}) {
     return units.join('');
 }
 /**
- * Verbatim port of portal resolve/route.ts prompt-matching block + the sort
- * that follows it. Parity is the whole point: any divergence silently changes
+ * Port of the server resolver's prompt-matching step and the sort that
+ * follows it. Parity is the whole point: any divergence silently changes
  * which skills load. Do not "improve" this — the reference implementation and
  * a scenario-level parity test both pin it.
  *

package/dist/utils/entitlements.js

@@ -14,9 +14,9 @@ import { debugLog } from "./logger.js";
 import { resolvePortalBaseUrl, usablePortalKey } from "./synaluxSearch.js";
 /** What a host with NO portal (unconfigured), a portal that says nothing
  *  (older deployment), or an assumed-free fallback gets: OFF. Multi-turn
- *  needs a Synalux account, and a free one is enough (owner decision
- *  2026-09-26): the answer check it depends on is served per account. The
- *  caps here are what an account gets when the portal omits them. */
+ *  needs a Synalux account, and a free one is enough: the answer check it
+ *  depends on is served per account. The caps here are what an account gets
+ *  when the portal omits them. */
 export const DEFAULT_MULTI_TURN = { enabled: false, max_turns: 12, max_chars: 32_000 };
 /** Structural ceiling no plan can exceed: the portal's own inference route
  *  takes at most 50 messages INCLUDING the current turn appended on
@@ -38,9 +38,8 @@ export function multiTurnPolicy(ent) {
 }
 // ── Free-tier defaults (no auth) ──────────────────────────────────
 /** No account: everything local, with no cap on the model the user's own
- *  machine can run (owner decision 2026-09-26). Anything that needs Synalux
- *  (multi-turn with the answer check, cloud answers) needs an account; a free
- *  one is enough. */
+ *  machine can run. Anything that needs Synalux (multi-turn with the answer
+ *  check, cloud answers) needs an account; a free one is enough. */
 export const FREE_ENTITLEMENTS = {
     plan: "free",
     model_ceiling: "27b",

package/docs/prism-browser.md

@@ -80,6 +80,39 @@ state carries between runs and makes them order dependent. For test runs use
 `--trace PATH`, `--video DIR`, and `--har PATH` record Playwright artifacts for
 a failing run.
 
+## Phones and tablets
+
+A desktop run never matches `(pointer: coarse)` and reads every
+`env(safe-area-inset-*)` as 0, so CSS written for touchscreens, and layouts
+that pad the iPhone status area and home indicator, cannot show up at a phone
+size alone. Emulate the device instead:
+
+- `--device NAME` — a measured iPhone or iPad in portrait: viewport, pixel
+  ratio, touch, and safe area. `iphone-se`, `iphone-17`, `iphone-air`,
+  `iphone-17-pro-max`, `ipad-a16`, `ipad-pro-13`. The values were read from a
+  full-screen web view on iOS 26.5 simulators.
+- `--touch` — a touchscreen: `(pointer: coarse)` and `(hover: none)` match,
+  touch events exist, and the page's meta viewport is honoured.
+- `--device-scale-factor N` — the device pixel ratio, for example `3`.
+- `--safe-area T,R,B,L` — `env(safe-area-inset-*)` in CSS pixels, for example
+  `62,0,34,0`. On iOS a page reads the insets only if its meta viewport sets
+  `viewport-fit=cover`; without it an iPhone 17 reports 0. Chromium applies
+  them either way, so check that your page sets it.
+
+Flags given explicitly override the preset, so a phone turned sideways is
+`--device iphone-17 --viewport 874x402 --safe-area 0,62,21,62`. Landscape
+insets are not part of the presets. The engine stays Chromium, and the user
+agent stays the desktop one, so pages that branch on the user-agent string
+still take their desktop path.
+
+```bash
+printf '%s\n' \
+  'open http://127.0.0.1:3000/app' \
+  'assert-eval matchMedia("(pointer: coarse)").matches' \
+  'screenshot phone.png' \
+  | prism browser --headless --fast --ephemeral-profile --local-only --device iphone-17 pipe
+```
+
 ## Multiple pages
 
 A popup (OAuth, payment, print preview) opens a new page. `pages` lists them,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.21.17",
+  "version": "20.21.19",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Persistent session memory for AI coding agents that never leaves your machine — including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
   "module": "index.ts",
@@ -22,7 +22,7 @@
     "prebuild": "npm run clean",
     "build": "tsc && npm run chmod-bins",
     "chmod-bins": "node -e \"['dist/cli.js','dist/server.js','dist/utils/universalImporter.js'].forEach(f => { try { require('fs').chmodSync(f, 0o755); } catch (e) { console.warn('chmod skipped', f, e.message); } })\"",
-    "prepublishOnly": "node scripts/check-no-private-content.mjs && node scripts/check-publish-clean.mjs && npm run build",
+    "prepublishOnly": "node scripts/check-no-private-content.mjs && node scripts/private-identifier-scan.mjs && node scripts/check-publish-clean.mjs && npm run build",
     "lint:dashboard": "node scripts/lint-dashboard-es5.cjs",
     "check:lockfile": "node scripts/check-lockfile-drift.mjs",
     "start": "node dist/server.js",
@@ -79,7 +79,7 @@
   "overrides": {
     "@hono/node-server": "^2.0.5",
     "body-parser": "^2.3.0",
-    "fast-uri": "^3.1.6",
+    "fast-uri": "^3.1.8",
     "hono": "^4.13.5",
     "ip-address": "^10.2.0",
     "protobufjs": "^7.6.5",

package/scripts/dev/browse.py

@@ -68,6 +68,19 @@ AUDIT_LOG_PATH = BROWSER_DATA_DIR / "audit.log"
 DEFAULT_PROFILE = "default"
 DEFAULT_TIMEOUT = 30000
 DEFAULT_VIEWPORT = (1440, 900)
+# iOS devices in portrait as a full-screen WKWebView page sees them: CSS
+# viewport, devicePixelRatio, and env(safe-area-inset-*) as (top, right,
+# bottom, left). Measured 2026-10-03 on iOS 26.5 simulators, each running a
+# full-screen WKWebView app whose page reported these values. Landscape was not
+# measured: pass --viewport and --safe-area for it.
+DEVICE_PRESETS: dict[str, dict] = {
+    'iphone-se': {'viewport': (375, 667), 'scale': 2.0, 'safe_area': (20, 0, 0, 0)},
+    'iphone-17': {'viewport': (402, 874), 'scale': 3.0, 'safe_area': (62, 0, 34, 0)},
+    'iphone-air': {'viewport': (420, 912), 'scale': 3.0, 'safe_area': (68, 0, 34, 0)},
+    'iphone-17-pro-max': {'viewport': (440, 956), 'scale': 3.0, 'safe_area': (62, 0, 34, 0)},
+    'ipad-a16': {'viewport': (820, 1180), 'scale': 2.0, 'safe_area': (32, 0, 20, 0)},
+    'ipad-pro-13': {'viewport': (1032, 1376), 'scale': 2.0, 'safe_area': (32, 0, 20, 0)},
+}
 REPL_IDLE_TIMEOUT = 600  # 10 minutes — auto-close to prevent zombie Chromium
 PIPE_IDLE_TIMEOUT = 600  # stdin held open with no commands — same protection
 MAX_INIT_SCRIPT_BYTES = 256 * 1024
@@ -796,7 +809,8 @@ class StealthBrowserSession:
                  allow_degraded_stealth=False, ephemeral_profile=False,
                  storage_state_path=None, trace_path=None, video_dir=None,
                  har_path=None, grant_permissions=None, geolocation=None,
-                 allow_http_error=False):
+                 allow_http_error=False, touch=False, device_scale_factor=None,
+                 safe_area=None):
         self.profile = validate_profile_name(profile)
         self.headless = headless
         self.timeout = timeout
@@ -814,6 +828,9 @@ class StealthBrowserSession:
         self.grant_permissions = list(grant_permissions or [])
         self.geolocation = geolocation
         self.allow_http_error = allow_http_error
+        self.touch = touch
+        self.device_scale_factor = device_scale_factor
+        self.safe_area = safe_area  # (top, right, bottom, left) CSS px, or None
         self.stealth_degraded: list[str] = []
         self.fingerprint: dict = {}
         self._fingerprint_reverified = False
@@ -895,6 +912,13 @@ class StealthBrowserSession:
                 'latitude': self.geolocation[0],
                 'longitude': self.geolocation[1],
             }
+        if self.touch:
+            # A phone or tablet: (pointer: coarse) and (hover: none) match, touch
+            # events exist, and the page's meta viewport is honoured.
+            launch_kwargs['has_touch'] = True
+            launch_kwargs['is_mobile'] = True
+        if self.device_scale_factor:
+            launch_kwargs['device_scale_factor'] = self.device_scale_factor
         if self.video_dir:
             launch_kwargs['record_video_dir'] = str(self.video_dir)
         if self.har_path:
@@ -950,7 +974,8 @@ class StealthBrowserSession:
         audit_log(
             "session_start", f"profile={self.profile}",
             f"stealth={self.stealth_level},headless={self.headless},"
-            f"local_only={self.local_only},degraded={len(self.stealth_degraded)}",
+            f"local_only={self.local_only},degraded={len(self.stealth_degraded)},"
+            f"touch={self.touch},scale={self.device_scale_factor},safe_area={self.safe_area}",
         )
 
     def _on_new_page(self, page):
@@ -990,6 +1015,29 @@ class StealthBrowserSession:
         self.diagnostics.attach(page)
         if self.stealth_level != "none":
             self._apply_cdp_user_agent(page)
+        # After the user-agent override, never before: Emulation.setUserAgentOverride
+        # resets an earlier safe-area override on the same page, and env() then
+        # reads 0 under --stealth full.
+        if self.safe_area:
+            self._apply_safe_area(page)
+
+    def _apply_safe_area(self, page):
+        """
+        Set env(safe-area-inset-*), which Playwright cannot emulate. Chromium
+        applies it whether or not the page sets viewport-fit=cover; iOS reports
+        0 without it. A runtime without the override fails the run: a silent 0
+        would test the wrong layout.
+        """
+        top, right, bottom, left = self.safe_area
+        try:
+            self._context.new_cdp_session(page).send('Emulation.setSafeAreaInsetsOverride', {
+                'insets': {'top': top, 'right': right, 'bottom': bottom, 'left': left},
+            })
+        except Exception as exc:
+            raise RuntimeError(
+                f"--safe-area could not be applied ({type(exc).__name__}: {exc}). "
+                "It needs a Chromium with Emulation.setSafeAreaInsetsOverride."
+            ) from exc
 
     def _apply_cdp_user_agent(self, page):
         """
@@ -2309,7 +2357,15 @@ def build_parser():
                    help='Delete screenshots captured in this run on exit (see --help notes)')
     p.add_argument('--sanitize', action='store_true', help='Mask PHI patterns in text output')
     p.add_argument('--timeout', type=int, default=DEFAULT_TIMEOUT, help='Timeout (ms)')
-    p.add_argument('--viewport', default='1440x900', help='Viewport WxH')
+    p.add_argument('--viewport', default=None, help='Viewport WxH (default 1440x900, or the --device size)')
+    p.add_argument('--device', choices=sorted(DEVICE_PRESETS),
+                   help='Emulate a measured iPhone or iPad in portrait: size, pixel ratio, touch and safe area')
+    p.add_argument('--touch', action='store_true',
+                   help='Emulate a touchscreen: (pointer: coarse), (hover: none), touch events, meta viewport')
+    p.add_argument('--device-scale-factor', metavar='N', help='Device pixel ratio, for example 3')
+    p.add_argument('--safe-area', metavar='T,R,B,L',
+                   help='env(safe-area-inset-*) in CSS pixels, for example 62,0,34,0; unlike iOS, '
+                        'applied even when the page omits viewport-fit=cover')
     p.add_argument('--stealth', choices=['full', 'light', 'none'], default='full',
                    help='Fingerprint level: full (stealth lib + CDP + JS), light (CDP + JS), none')
     p.add_argument('--allow-degraded-stealth', action='store_true',
@@ -2422,6 +2478,54 @@ def parse_viewport(value: str) -> tuple[int, int]:
     return int(match.group(1)), int(match.group(2))
 
 
+def parse_safe_area(value: str) -> tuple[int, int, int, int]:
+    """Parse T,R,B,L insets in CSS pixels, failing loudly like --viewport."""
+    match = re.fullmatch(r'\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*', value or '')
+    if not match:
+        raise ValueError(
+            f"Invalid --safe-area {value!r}. Expected T,R,B,L in CSS pixels, for example 62,0,34,0."
+        )
+    return tuple(int(group) for group in match.groups())
+
+
+def parse_device_scale_factor(value: str) -> float:
+    """Parse a device pixel ratio, failing loudly on anything outside 0.5 to 5."""
+    try:
+        scale = float(value)
+    except (TypeError, ValueError):
+        scale = 0.0
+    if not 0.5 <= scale <= 5:
+        raise ValueError(f"Invalid --device-scale-factor {value!r}. Expected a number from 0.5 to 5, for example 3.")
+    return scale
+
+
+def resolve_device_options(device, viewport, touch, scale, safe_area):
+    """
+    Combine --device with the individual flags. The preset supplies defaults;
+    any flag given explicitly wins, so --device iphone-17 --viewport 874x402
+    is the same phone turned sideways (pass its landscape --safe-area too).
+    """
+    # "Given" means not None: an empty value (an unset shell variable) must fail
+    # loudly, not quietly fall back to a desktop default.
+    preset = DEVICE_PRESETS.get(device) if device is not None else None
+    if device is not None and preset is None:
+        raise ValueError(f"Unknown --device {device!r}. Known: {', '.join(sorted(DEVICE_PRESETS))}.")
+    if viewport is not None:
+        size = parse_viewport(viewport)
+    elif preset:
+        size = tuple(preset['viewport'])
+    else:
+        size = DEFAULT_VIEWPORT
+    return {
+        'viewport': size,
+        'touch': bool(touch or preset),
+        'device_scale_factor': (parse_device_scale_factor(scale) if scale is not None
+                                else (preset['scale'] if preset else None)),
+        'safe_area': (parse_safe_area(safe_area) if safe_area is not None
+                      else (tuple(preset['safe_area']) if preset else None)),
+    }
+
+
 def parse_geolocation(value: str) -> tuple[float, float]:
     parts = (value or '').split(',')
     if len(parts) != 2:
@@ -2447,9 +2551,12 @@ def main():
         return 1
 
     try:
-        viewport = parse_viewport(args.viewport)
+        device = resolve_device_options(
+            args.device, args.viewport, args.touch, args.device_scale_factor, args.safe_area,
+        )
     except ValueError as exc:
         parser.error(str(exc))
+    viewport = device['viewport']
 
     geolocation = None
     if args.geolocation:
@@ -2488,6 +2595,9 @@ def main():
             grant_permissions=args.grant,
             geolocation=geolocation,
             allow_http_error=args.allow_http_error,
+            touch=device['touch'],
+            device_scale_factor=device['device_scale_factor'],
+            safe_area=device['safe_area'],
         )
     except (ValueError, StealthConfigurationError) as exc:
         print(json.dumps({"status": "error", "message": str(exc)}), file=sys.stderr)