@anuraghq/mobius 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # Mobius
 
-**Let AI agents use a real phone, safely.**
+**Let AI agents use a real phone, safely.** · Website: https://anu-code07.github.io/mobius/
 
 Mobius is an open-source [MCP](https://modelcontextprotocol.io) server that lets Claude Code, Cursor or any MCP client operate Android and iOS devices. The agent sees a clean, masked view of the screen, every action is checked, and anything that spends money or sends something needs a human's approval.
 
@@ -279,7 +279,8 @@ Everything an operator needs to let agents loose on phones, in the open-source e
 | **No test-mode backdoor** | `MOBIUS_TEST_APPROVAL=approved` only ever approves on emulators and simulators; on a physical phone it rejects. |
 | **Tamper-evident audit** | Each entry records the agent (MCP client), session, decision, rule id, action class and amount, hash-chained to the previous one. `mobius audit verify` detects any edit; `mobius audit export` gives JSONL for your SIEM. |
 | **Kill switch + quotas** | `mobius stop` halts every agent's state-changing actions instantly (`mobius resume` to undo). `MOBIUS_MAX_ACTIONS` (default 1000) and `MOBIUS_MAX_SESSION_MIN` cap a session. |
-| **Secrets vault** | `type` with `secret_ref: "env:NAME"` or `"keychain:service/account"`: the host fetches the secret and types it; the model never sees it and it's never logged. |
+| **Secrets vault** | `type` with `secret_ref: "env:NAME"` or `"keychain:service/account"`: the host fetches the secret and types it; the model never sees it and it's never logged. Only refs listed in `MOBIUS_SECRETS` (comma-separated, e.g. `env:SHOP_PASS,keychain:shop/riya`) can be used. |
+| **Contained file output** | Screenshots, recordings, pulled files and reports are written only under `MOBIUS_OUTPUT_DIR` (default `~/.mobius/outputs`); an agent can't write anywhere else on your machine. |
 | **Attack corpus + Break Mobius** | [`attacks.test.ts`](https://github.com/Anu-Code07/mobius/blob/main/packages/host/test/attacks.test.ts) (45 policy cases) and the **[Break Mobius benchmark](https://github.com/Anu-Code07/mobius/blob/main/docs/benchmark/README.md)**: 44 end-to-end attacks scored on what actually happened on the device (all 44 defended) plus 9 must-not-annoy controls. Both run on every `npm test` as a release gate. `npm run bench` prints the scorecard. |
 
 | **REST API** | `mobius serve` exposes the same engine over HTTP for agents that don't speak MCP: `POST /v1/actions`, `GET /v1/tools`, `GET /v1/audit[/export\|/verify]`. Same policy, approvals and audit as MCP. Bearer token, localhost by default. |

package/dist/cli.js

@@ -13,7 +13,8 @@ import { driverBuilt, driverPath, iosAgentReady, MobiusAgentConnector, MobiusAge
 /** Every online device through the Mobius driver. iOS devices also need the Mobius Agent runner set up once. */
 const connectors = (driver) => async () => {
     if (!driverBuilt())
-        throw new Error(`Mobius driver not built: run \`cargo build --release\` in drivers/mobiusagent-driver (expected ${driverPath()})`);
+        throw new Error(`No Mobius driver for ${process.platform}-${process.arch} in this install (looked for ${driverPath()}). ` +
+            'Build it from https://github.com/Anu-Code07/mobius (`cargo build --release` in drivers/mobiusagent-driver) and point MOBIUS_DRIVER_BIN at the binary.');
     const ios = iosAgentReady();
     return (await driver.devices()).filter(d => d.state === 'online' && (d.platform === 'android' || ios)).map(d => new MobiusAgentConnector(driver, d));
 };

package/dist/execution/drivers/mobiusagent.d.ts

@@ -24,6 +24,8 @@ export declare class MobiusAgentDriver {
     devices(): Promise<AgentDevice[]>;
     close(): void;
 }
+/** How long a driver op may take: sessions (`seconds`), routes, installs, waits and the first OCR build get their own budget. */
+export declare function extraTimeoutMs(op: string, args?: Record<string, unknown>): number;
 export declare class MobiusAgentConnector implements Connector {
     readonly platform: 'android' | 'ios';
     readonly deviceId: string;

package/dist/execution/drivers/mobiusagent.js

@@ -32,7 +32,15 @@ export class MobiusAgentDriver {
     next = 1;
     waiting = new Map();
     start() {
-        const p = spawn(driverPath(), [], { stdio: ['pipe', 'pipe', 'pipe'] });
+        // stderr is not read: a full pipe would stall the driver.
+        const p = spawn(driverPath(), [], { stdio: ['pipe', 'pipe', 'ignore'] });
+        // Every call in flight when the driver dies (killed after a timeout, crashed) may or may not have reached the device.
+        const failAll = (e) => { for (const w of this.waiting.values())
+            w.fail(e); this.waiting.clear(); if (this.proc === p)
+            this.proc = null; };
+        // A binary that can't start (missing, not executable) must not crash the server.
+        p.on('error', e => failAll(new MobiusError('INTERNAL', `mobiusagent-driver could not run: ${e.message}`)));
+        p.stdin.on('error', () => { });
         createInterface({ input: p.stdout }).on('line', line => {
             let r;
             try {
@@ -47,12 +55,7 @@ export class MobiusAgentDriver {
             this.waiting.delete(r.id);
             r.ok ? w.ok(r.data) : w.fail(new MobiusError('INTERNAL', String(r.error)));
         });
-        p.on('exit', () => {
-            for (const w of this.waiting.values())
-                w.fail(new MobiusError('INTERNAL', 'mobiusagent-driver exited', { retryable: true }));
-            this.waiting.clear();
-            this.proc = null;
-        });
+        p.on('exit', () => failAll(new MobiusError('OUTCOME_UNKNOWN', 'mobiusagent-driver exited during the call; it may or may not have happened', { retryable: true, hint: 'Call observe before retrying.' })));
         this.proc = p;
         return p;
     }
@@ -65,7 +68,7 @@ export class MobiusAgentDriver {
                 this.waiting.delete(id);
                 // ponytail: a wedged adb call blocks the one driver process; restart it rather than queue behind it.
                 this.proc?.kill();
-                fail(new MobiusError('TIMEOUT', `mobiusagent-driver ${op} timed out`, { retryable: true }));
+                fail(new MobiusError('OUTCOME_UNKNOWN', `mobiusagent-driver ${op} did not answer within ${timeoutMs} ms; it may or may not have happened`, { retryable: true, hint: 'Call observe before retrying.' }));
             }, timeoutMs);
             this.waiting.set(id, { ok: v => { clearTimeout(t); ok(v); }, fail: e => { clearTimeout(t); fail(e); } });
             p.stdin.write(JSON.stringify({ id, op, ...args }) + '\n');
@@ -74,7 +77,14 @@ export class MobiusAgentDriver {
     async devices() { return (await this.call('devices')).devices; }
     close() { this.proc?.kill(); this.proc = null; }
 }
-const KEYS = { back: 'back', home: 'home', recents: 'recents', enter: 'enter' };
+const KEYS = { back: 'back', home: 'home', recents: 'recents', enter: 'enter', notifications: 'notifications' };
+/** How long a driver op may take: sessions (`seconds`), routes, installs, waits and the first OCR build get their own budget. */
+export function extraTimeoutMs(op, args = {}) {
+    const secs = Number(args.seconds ?? 0);
+    return op === 'gps_route' ? 3_700_000 : op === 'install' ? 300_000
+        : ['perf_report', 'watch_crashes'].includes(op) ? (secs + 120) * 1000 : ['ocr', 'bug_report', 'replay'].includes(op) ? 180_000
+            : op === 'wait_idle' ? Number(args.timeout_ms ?? 5000) + 30_000 : 60_000;
+}
 export class MobiusAgentConnector {
     platform;
     deviceId;
@@ -106,7 +116,10 @@ export class MobiusAgentConnector {
     }
     async dump() {
         const r = await this.drv.call('dump', this.d).catch(e => {
-            throw new MobiusError('DEVICE_LOCKED', `Could not read the screen: ${e.message}`, { retryable: true, hint: 'Ask the user to wake and unlock the phone.' });
+            const msg = e.message;
+            if (/\block(ed)?\b|unlock|passcode/i.test(msg))
+                throw new MobiusError('DEVICE_LOCKED', `Could not read the screen: ${msg}`, { retryable: true, hint: 'Ask the user to wake and unlock the phone.' });
+            throw new MobiusError('DEVICE_OFFLINE', `Could not read the screen: ${msg}`, { retryable: true, hint: this.platform === 'ios' ? 'Check the device is connected and WebDriverAgent is running (mobius setup-ios).' : 'Check the device is connected (adb devices).' });
         });
         this.size = { width: r.width, height: r.height };
         const root = { cls: 'hierarchy', pkg: '', text: '', desc: '', resourceId: '', clickable: false, longClickable: false,
@@ -144,22 +157,23 @@ export class MobiusAgentConnector {
     }
     async key(key) {
         const k = KEYS[key];
-        if (!k || (this.platform === 'ios' && (key === 'back' || key === 'recents')))
+        if (!k || (this.platform === 'ios' && key !== 'home' && key !== 'enter'))
             throw new MobiusError('UNSUPPORTED_CAPABILITY', `Key "${key}" is not available on this device`);
         await this.drv.call('key', { ...this.d, key: k });
     }
     async openApp(appId) {
         await this.drv.call('launch', { ...this.d, app: appId }).catch(e => {
-            throw new MobiusError('APP_NOT_INSTALLED', e.message, { hint: 'Call list_apps to see installed apps.' });
+            const msg = e.message;
+            // iOS refuses launches on a locked phone (FBSOpenApplicationErrorDomain code 7, "Locked"): not a missing app.
+            if (/\block(ed)?\b|FBSOpenApplicationErrorDomain Code=7\b|unlock/i.test(msg)) {
+                throw new MobiusError('DEVICE_LOCKED', `The phone is locked, so ${appId} could not be opened`, { retryable: true, hint: 'Ask the user to unlock the phone, then retry.' });
+            }
+            throw new MobiusError('APP_NOT_INSTALLED', msg, { hint: 'Call list_apps to see installed apps.' });
         });
     }
     async openUrl(url) { await this.drv.call('url', { ...this.d, url }); }
     async listApps() { return (await this.drv.call('apps', this.d)).apps; }
     async extra(op, args = {}) {
-        // Long-running ops get their own budget: sessions (`seconds`), routes, installs, first OCR build.
-        const secs = Number(args.seconds ?? 0);
-        const timeout = op === 'gps_route' ? 3_700_000 : op === 'install' ? 300_000
-            : ['perf_report', 'watch_crashes'].includes(op) ? (secs + 120) * 1000 : ['ocr', 'bug_report', 'replay'].includes(op) ? 180_000 : 60_000;
-        return this.drv.call(op, { ...this.d, ...args }, timeout);
+        return this.drv.call(op, { ...this.d, ...args }, extraTimeoutMs(op, args));
     }
 }

package/dist/execution/observe.d.ts

@@ -27,6 +27,8 @@ export declare function normalize(screen: RawScreen, obsId: string): Normalized
  *  an earlier Mobius process still resolves against the live screen (same identity rules, same ambiguity checks). */
 export declare class ObservationStore {
     private seq;
+    /** The observation the agent was last shown: never evicted, so its refs resolve (by identity) or fail as stale. */
+    shown: string | null;
     private history;
     private saved;
     private readonly file;

package/dist/execution/observe.js

@@ -34,9 +34,11 @@ function roleOf(n) {
 const REDACTED = '[redacted]';
 const CARD_LIKE = /\b(?:\d[ -]?){12,18}\d\b/g;
 // Digits may be spaced or dashed ("4 8 2 9 1 3", "482-913") to dodge a plain \d{6} match.
-const OTP_LIKE = /\b(otp|one[- ]?time|verification code|security code|passcode|pin|cvv|cvc)\b([^\d]{0,25})\d(?:[ -]?\d){2,7}\b/gi;
+const OTP_LIKE = /\b(otp|one[- ]?time|verification code|security code|passcode|code|pin|cvv|cvc)\b([^\d]{0,25})\d(?:[ -]?\d){2,7}\b/gi;
+// The other common order: "482913 is your OTP", "4829 is the code for login". Never an amount ("₹1499 · Enter PIN").
+const OTP_FIRST = /(?<!(?:₹|rs\.?|inr|\$|€|£)\s?[\d,]*)\b\d(?:[ -]?\d){3,7}\b(?=[^\d]{0,30}\b(?:otp|one[- ]?time|verification code|security code|passcode|code|pin)\b)/gi;
 export function scrub(s) {
-    return s.replace(CARD_LIKE, REDACTED).replace(OTP_LIKE, (_m, kw, mid) => `${kw}${mid}${REDACTED}`);
+    return s.replace(CARD_LIKE, REDACTED).replace(OTP_LIKE, (_m, kw, mid) => `${kw}${mid}${REDACTED}`).replace(OTP_FIRST, REDACTED);
 }
 /** A field asking for a secret, whatever the driver reported (an app may not set the password flag on a PIN box). */
 const SECRET_FIELD = /\b(password|passcode|passwd|pin|mpin|upi pin|otp|cvv|cvc|secret)\b|one[- ]?time/i;
@@ -64,13 +66,25 @@ export const MAX_ELEMENTS = 400;
 export function normalize(screen, obsId) {
     const picked = [];
     let kb = null;
+    // The IME window is often full-screen and transparent above the keys (Android 15 edge-to-edge), so it must not
+    // count as covering the app. No keyboard is taller than 60% of the screen: descend through such wrappers and take
+    // the first keyboard-sized node (the key panel, suggestion strip included) whole.
+    const keys = (n) => {
+        if (!visible(n))
+            return;
+        if (n.bounds.height > screen.height * 0.6) {
+            n.children.forEach(keys);
+            return;
+        }
+        const b = n.bounds;
+        kb = kb ? { x1: Math.min(kb.x1, b.x), y1: Math.min(kb.y1, b.y), x2: Math.max(kb.x2, b.x + b.width), y2: Math.max(kb.y2, b.y + b.height) }
+            : { x1: b.x, y1: b.y, x2: b.x + b.width, y2: b.y + b.height };
+    };
     const walk = (n, insideClickable) => {
         if (isKeyboard(n) && visible(n)) {
-            const b = n.bounds;
-            kb = kb ? { x1: Math.min(kb.x1, b.x), y1: Math.min(kb.y1, b.y), x2: Math.max(kb.x2, b.x + b.width), y2: Math.max(kb.y2, b.y + b.height) }
-                : { x1: b.x, y1: b.y, x2: b.x + b.width, y2: b.y + b.height };
-            return; // keys are noise for the agent; the area is reported as `keyboard`
-        }
+            keys(n);
+            return;
+        } // keys are noise for the agent; the area is reported as `keyboard`
         if (!visible(n) && n.cls !== 'hierarchy') {
             // Zero-size containers (common on iOS) can still hold visible children.
             for (const c of n.children)
@@ -135,6 +149,8 @@ const identityHash = (f) => createHash('sha256').update(JSON.stringify([f.role,
  *  an earlier Mobius process still resolves against the live screen (same identity rules, same ambiguity checks). */
 export class ObservationStore {
     seq = 0;
+    /** The observation the agent was last shown: never evicted, so its refs resolve (by identity) or fail as stale. */
+    shown = null;
     history = [];
     saved = [];
     file;
@@ -152,8 +168,10 @@ export class ObservationStore {
     nextId() { return `o${++this.seq}`; }
     add(obs, fps) {
         this.history.push({ obs, fps });
-        if (this.history.length > 5)
-            this.history.shift();
+        // ponytail: settle/verify polls add an observation every ~100 ms, so a small window evicts the ids the agent
+        // just got from observe after one slow action. 64 covers a full verify timeout; the on-disk copy stays at 5.
+        if (this.history.length > 64)
+            this.history.splice(this.history.findIndex(h => h.obs.observation_id !== this.shown), 1);
         if (!this.file)
             return;
         this.saved.push([...fps].map(([id, f]) => ({ id, hash: identityHash(f), dup: f.dup_index, rid: !!f.resource_id })));

package/dist/execution/session.d.ts

@@ -23,7 +23,16 @@ export declare const LAUNCH_EXPECT_TIMEOUT_MS = 20000;
 /** Where to touch an element: the center of its on-screen part (an element partly above/left of the screen has negative
  *  bounds; its raw center can be off-screen). Given the screen, a point not covered by a smaller clickable element inside
  *  it: tapping a big card's center must not hit the item drawn there (live run: Swiggy's restaurant card opened a burger). */
-export declare const center: (e: Element, screen?: readonly Element[]) => {
+type Box = Element['bounds'];
+/**
+ * Where to tap an element: inside its on-screen part, off its own clickable children (a card's inner button),
+ * and off anything drawn over it (a floating toolbar, tab bar or sheet: a later element that isn't its ancestor).
+ * Throws when no point of it is visibly tappable, so a covered or off-screen target is never tapped "successfully".
+ */
+export declare const center: (e: Element, screen?: readonly Element[], size?: {
+    width: number;
+    height: number;
+}, keyboard?: Box | null) => {
     x: number;
     y: number;
 };
@@ -32,21 +41,41 @@ export declare function expectationMet(obs: Observation, ex: Expect): boolean;
 export declare class DeviceSession {
     readonly connector: Connector;
     readonly store: ObservationStore;
+    /** The observation last shown to the agent (observe / list / snapshot): short refs like @e5 point into it, not into internal polls. */
+    get shown(): string | null;
+    set shown(id: string | null);
     private readonly audit;
     private readonly policy;
     private readonly approver;
     private queue;
+    /** Device work that outlived its action's timeout: the next action waits for it (no tap while typing still runs). */
+    private inflight;
+    /** Set when an audit write failed: every later action is refused (no unaudited actions). */
+    private auditBroken;
     private recent;
     private readonly plane;
     private verdict;
     constructor(connector: Connector, audit: AuditLog, policy: Policy, approver: Approver, plane?: PlaneContext, persistIds?: boolean);
     isBlockedApp(app: string | null): boolean;
+    /** Who is asking may act at all: a rejected, revoked or expired session can't read the screen either. */
+    checkAgent(): void;
+    /** Kill switch, audit health and the agent's session, for every gated action; the quota for state changes. */
+    private checkPlane;
+    /** Where the finger lands for an element on the latest screen (on screen, off overlays and the keyboard). */
+    pointOf(el: Element): {
+        x: number;
+        y: number;
+    };
     /** Policy + approval gate. Returns the (re-resolved) target to act on. Throws MobiusError to stop. */
     private gate;
     /** Serialize work per device: one action at a time, no interleaved taps. */
     private exclusive;
     observe(): Promise<Observation>;
-    /** Re-observe until two consecutive screens hash the same (UI settled), bounded. State-based, no fixed sleeps. */
+    /**
+     * Re-observe until two consecutive screens hash the same (UI settled), bounded. State-based, no fixed sleeps.
+     * Two identical frames of the *pre-action* screen only count after a grace window: a tap that launches an
+     * activity takes a beat before the window changes, and settling early reports the old screen as the result.
+     */
     private settle;
     /** Every element containing the point on the latest screen (overlays, the button below them, its labels). */
     elementsAt(x: number, y: number): Element[];
@@ -99,3 +128,4 @@ export declare class DeviceSession {
         check?: (obs: Observation) => string | null;
     }): Promise<ActionResult>;
 }
+export {};

package/dist/execution/session.js

@@ -10,32 +10,53 @@ export const DEFAULT_EXPECT_TIMEOUT_MS = 6_000;
 export const LAUNCH_EXPECT_TIMEOUT_MS = 20_000;
 /** Pause between re-reads while waiting for the screen. */
 const POLL_MS = 100;
+/** How long an unchanged pre-action screen is waited on before settle accepts it (see settle). */
+const SETTLE_GRACE_MS = 600;
 /** Text read from pixels, as an element the policy can judge like any label. */
 const drawnText = (text, bounds) => ({ id: 'drawn', role: 'text', text, label: null, resource_id: null,
     clickable: false, long_clickable: false, enabled: true, focused: false, scrollable: false, editable: false, checked: null, selected: false,
     sensitive: false, bounds, dup_index: 0 });
-/** Where to touch an element: the center of its on-screen part (an element partly above/left of the screen has negative
- *  bounds; its raw center can be off-screen). Given the screen, a point not covered by a smaller clickable element inside
- *  it: tapping a big card's center must not hit the item drawn there (live run: Swiggy's restaurant card opened a burger). */
-export const center = (e, screen) => {
+const has = (b, p) => p.x >= b.x && p.x <= b.x + b.width && p.y >= b.y && p.y <= b.y + b.height;
+const holds = (o, i) => o.x <= i.x && o.y <= i.y && o.x + o.width >= i.x + i.width && o.y + o.height >= i.y + i.height;
+/**
+ * Where to tap an element: inside its on-screen part, off its own clickable children (a card's inner button),
+ * and off anything drawn over it (a floating toolbar, tab bar or sheet: a later element that isn't its ancestor).
+ * Throws when no point of it is visibly tappable, so a covered or off-screen target is never tapped "successfully".
+ */
+export const center = (e, screen, size, keyboard) => {
+    const W = size?.width || Infinity, H = size?.height || Infinity;
     const x1 = Math.max(e.bounds.x, 0), y1 = Math.max(e.bounds.y, 0);
-    const x2 = Math.max(e.bounds.x + e.bounds.width, x1), y2 = Math.max(e.bounds.y + e.bounds.height, y1);
+    const x2 = Math.min(e.bounds.x + e.bounds.width, W), y2 = Math.min(e.bounds.y + e.bounds.height, H);
+    if (x2 <= x1 || y2 <= y1) {
+        if (size)
+            throw new MobiusError('ELEMENT_NOT_FOUND', `${e.id} is off screen`, { hint: 'Scroll it into view, observe, then tap.' });
+        return { x: Math.max(x1, Math.min(x2, (x1 + x2) / 2)), y: Math.max(y1, Math.min(y2, (y1 + y2) / 2)) };
+    }
     const mid = { x: (x1 + x2) / 2, y: (y1 + y2) / 2 };
     if (!screen)
         return mid;
-    const inside = (o) => o.bounds.x >= e.bounds.x && o.bounds.y >= e.bounds.y && o.bounds.x + o.bounds.width <= e.bounds.x + e.bounds.width
-        && o.bounds.y + o.bounds.height <= e.bounds.y + e.bounds.height && o.bounds.width * o.bounds.height < e.bounds.width * e.bounds.height;
-    const kids = screen.filter(o => o !== e && o.id !== e.id && (o.clickable || o.editable) && inside(o));
-    if (!kids.length)
-        return mid;
-    const hit = (p) => kids.some(k => p.x >= k.bounds.x && p.x <= k.bounds.x + k.bounds.width && p.y >= k.bounds.y && p.y <= k.bounds.y + k.bounds.height);
+    const idx = screen.findIndex(o => o === e || o.id === e.id);
+    const area = (b) => b.width * b.height;
+    const kids = screen.filter(o => o !== e && o.id !== e.id && (o.clickable || o.editable) && holds(e.bounds, o.bounds) && area(o.bounds) < area(e.bounds));
+    // Drawn on top: later in tree order, overlapping, neither its ancestor nor its descendant, and not a decoration
+    // that passes touches through (plain text/images inside the overlap still block a tap on what's below).
+    const over = idx < 0 ? [] : screen.slice(idx + 1).filter(o => !holds(o.bounds, e.bounds) && !holds(e.bounds, o.bounds)
+        && (o.clickable || o.editable || o.scrollable || /toolbar|tab ?bar|navigation bar|sheet/i.test(`${o.label ?? ''} ${o.text ?? ''}`)));
+    // The soft keyboard is drawn over the app too (its keys aren't in `screen`): a tap there types a letter.
+    const covers = keyboard ? [...over.map(o => o.bounds), keyboard] : over.map(o => o.bounds);
+    const covered = (p) => covers.some(b => has(b, p));
+    const blocked = (p) => kids.some(k => has(k.bounds, p)) || covered(p);
     const at = (fx, fy) => ({ x: x1 + (x2 - x1) * fx, y: y1 + (y2 - y1) * fy });
     for (const [fx, fy] of [[0.5, 0.5], [0.5, 0.12], [0.12, 0.5], [0.88, 0.5], [0.5, 0.88], [0.12, 0.12], [0.88, 0.12], [0.12, 0.88], [0.88, 0.88], [0.3, 0.12], [0.7, 0.12]]) {
         const p = at(fx, fy);
-        if (!hit(p))
+        if (!blocked(p))
             return p;
     }
-    return mid; // fully covered: the children are the target in practice
+    if (covered(mid)) {
+        const by = [...over.filter(o => has(o.bounds, mid)).map(o => o.label || o.text || o.role), ...(keyboard && has(keyboard, mid) ? ['the keyboard'] : [])];
+        throw new MobiusError('ELEMENT_NOT_FOUND', `${e.id} is covered by ${by.slice(0, 2).join(', ')}`, { hint: by.includes('the keyboard') ? 'Hide the keyboard (mobius_hide_keyboard), observe, then tap.' : 'Scroll it into view, observe, then tap.' });
+    }
+    return mid; // covered only by its own children: the children are the target in practice
 };
 function withTimeout(p, ms, what) {
     let timer;
@@ -62,10 +83,17 @@ export function expectationMet(obs, ex) {
 export class DeviceSession {
     connector;
     store;
+    /** The observation last shown to the agent (observe / list / snapshot): short refs like @e5 point into it, not into internal polls. */
+    get shown() { return this.store.shown; }
+    set shown(id) { this.store.shown = id; }
     audit;
     policy;
     approver;
     queue = Promise.resolve();
+    /** Device work that outlived its action's timeout: the next action waits for it (no tap while typing still runs). */
+    inflight = Promise.resolve();
+    /** Set when an audit write failed: every later action is refused (no unaudited actions). */
+    auditBroken = null;
     recent = [];
     plane;
     verdict = null;
@@ -78,15 +106,51 @@ export class DeviceSession {
         this.approver = approver;
     }
     isBlockedApp(app) { return this.policy.appBlocked(app); }
+    /** Who is asking may act at all: a rejected, revoked or expired session can't read the screen either. */
+    checkAgent() {
+        const pl = this.plane;
+        const ses = pl.session();
+        if (ses && 'invalid' in ses)
+            throw new MobiusError('POLICY_BLOCKED', `Agent session token rejected: ${ses.invalid}`, { hint: 'Ask the operator for a fresh session token.' });
+        if (!ses && pl.require_session)
+            throw new MobiusError('POLICY_BLOCKED', 'This Mobius requires a signed agent session', { hint: 'Ask the operator for a session token (mobius session issue).' });
+        if (ses && isRevoked(ses.jti))
+            throw new MobiusError('POLICY_BLOCKED', 'Agent session revoked by the operator', { hint: 'Stop and tell the user.' });
+        if (ses && ses.exp <= Date.now() / 1000)
+            throw new MobiusError('POLICY_BLOCKED', 'Agent session expired', { hint: 'Ask the operator for a fresh session token.' });
+        if (ses?.policy_version && ses.policy_version !== this.policy.config.version) {
+            throw new MobiusError('POLICY_BLOCKED', `Session was issued for policy ${ses.policy_version}, but Mobius runs ${this.policy.config.version}`, { hint: 'The operator must re-issue the session for the current policy.' });
+        }
+        if (pl.max_minutes && Date.now() - pl.started > pl.max_minutes * 60_000)
+            throw new MobiusError('POLICY_BLOCKED', `Session time limit reached (${pl.max_minutes} min)`, { hint: 'Stop and report progress to the user.' });
+    }
+    /** Kill switch, audit health and the agent's session, for every gated action; the quota for state changes. */
+    checkPlane(mutating) {
+        if (existsSync(killSwitchPath()))
+            throw new MobiusError('POLICY_BLOCKED', 'Kill switch engaged: all agent actions are stopped', { hint: 'A human ran `mobius stop`. Stop and tell the user.' });
+        if (this.auditBroken)
+            throw new MobiusError('POLICY_BLOCKED', `Audit log unavailable (${this.auditBroken}), so actions are refused`, { hint: 'Tell the user: the audit database needs attention.' });
+        this.checkAgent();
+        const pl = this.plane;
+        if (mutating && pl.actions >= pl.max_actions)
+            throw new MobiusError('POLICY_BLOCKED', `Action quota reached (${pl.max_actions} per session)`, { hint: 'Stop and report progress to the user.' });
+    }
+    /** Where the finger lands for an element on the latest screen (on screen, off overlays and the keyboard). */
+    pointOf(el) {
+        const l = this.store.latest();
+        return center(el, l?.elements, l?.screen, l?.keyboard);
+    }
     /** Policy + approval gate. Returns the (re-resolved) target to act on. Throws MobiusError to stop. */
     async gate(tool, guard) {
         // Time of check = time of use: the app may have changed the screen since the agent read it ("Add to cart" becomes
         // "Pay ₹999"). Re-read now and decide on what the finger will actually hit. A changed target is refused as stale.
-        if (guard.ctx.mutating && (guard.targetId || guard.point))
+        // Reads re-read too: a read is judged on the app in front now (a banking app may have opened since the last look).
+        this.checkPlane(guard.ctx.mutating);
+        if (!guard.ctx.mutating || guard.targetId || guard.point)
             await this.observe();
         const latest = this.store.latest();
         let target = guard.targetId ? this.store.resolve(guard.targetId) : guard.point ? this.elementAt(guard.point.x, guard.point.y) : null;
-        const p = guard.point ?? (target ? center(target, latest?.elements) : null);
+        const p = guard.point ?? (target ? this.pointOf(target) : null);
         const under = p ? this.elementsAt(p.x, p.y) : [];
         // Pixels, not just labels: on a screen showing an amount due, read the text actually drawn where the finger lands
         // (OCR), so a Pay button can't hide behind an accessibility label that says "Close".
@@ -102,27 +166,6 @@ export class DeviceSession {
                     under.push(drawnText(String(t.text), { x, y, width: w, height: h }));
             }
         }
-        if (guard.ctx.mutating) {
-            if (existsSync(killSwitchPath()))
-                throw new MobiusError('POLICY_BLOCKED', 'Kill switch engaged: all agent actions are stopped', { hint: 'A human ran `mobius stop`. Stop and tell the user.' });
-            const pl = this.plane;
-            if (pl.actions >= pl.max_actions)
-                throw new MobiusError('POLICY_BLOCKED', `Action quota reached (${pl.max_actions} per session)`, { hint: 'Stop and report progress to the user.' });
-            const ses = pl.session();
-            if (ses && 'invalid' in ses)
-                throw new MobiusError('POLICY_BLOCKED', `Agent session token rejected: ${ses.invalid}`, { hint: 'Ask the operator for a fresh session token.' });
-            if (!ses && pl.require_session)
-                throw new MobiusError('POLICY_BLOCKED', 'This Mobius requires a signed agent session', { hint: 'Ask the operator for a session token (mobius session issue).' });
-            if (ses && isRevoked(ses.jti))
-                throw new MobiusError('POLICY_BLOCKED', 'Agent session revoked by the operator', { hint: 'Stop and tell the user.' });
-            if (ses && ses.exp <= Date.now() / 1000)
-                throw new MobiusError('POLICY_BLOCKED', 'Agent session expired', { hint: 'Ask the operator for a fresh session token.' });
-            if (ses?.policy_version && ses.policy_version !== this.policy.config.version) {
-                throw new MobiusError('POLICY_BLOCKED', `Session was issued for policy ${ses.policy_version}, but Mobius runs ${this.policy.config.version}`, { hint: 'The operator must re-issue the session for the current policy.' });
-            }
-            if (pl.max_minutes && Date.now() - pl.started > pl.max_minutes * 60_000)
-                throw new MobiusError('POLICY_BLOCKED', `Session time limit reached (${pl.max_minutes} min)`, { hint: 'Stop and report progress to the user.' });
-        }
         const v = this.policy.evaluate({ ...guard.ctx, tool, app: latest?.foreground_app ?? null, target, screen: latest?.elements, under });
         this.verdict = v;
         const { decision, reason, action_class } = v;
@@ -136,10 +179,12 @@ export class DeviceSession {
             throw new MobiusError('APPROVAL_REJECTED', `User rejected: ${req.summary}`, { hint: 'Do not retry. Ask the user what they want instead.' });
         if (outcome === 'expired')
             throw new MobiusError('APPROVAL_EXPIRED', `No decision within ${this.policy.config.approval_timeout_s}s: ${req.summary}`, { retryable: true });
-        // Time passed while the human decided: confirm the approved target is still the one on screen.
-        if (guard.targetId) {
+        // Time passed while the human decided (up to minutes): the operator may have stopped Mobius or revoked the agent,
+        // and the screen may have moved. Re-check, and confirm what the finger will hit is still what was approved.
+        this.checkPlane(guard.ctx.mutating);
+        if (guard.targetId || guard.point) {
             await this.observe();
-            target = this.store.resolve(guard.targetId);
+            target = guard.targetId ? this.store.resolve(guard.targetId) : this.elementAt(guard.point.x, guard.point.y);
             if (guard.describe(target) !== req.summary) {
                 throw new MobiusError('STALE_ELEMENT', 'Screen changed after approval; the approved target is no longer the same', { retryable: true, hint: 'Observe again; a new approval will be requested.' });
             }
@@ -149,7 +194,7 @@ export class DeviceSession {
     /** Serialize work per device: one action at a time, no interleaved taps. */
     exclusive(fn) {
         const next = this.queue.then(fn, fn);
-        this.queue = next.catch(() => undefined);
+        this.queue = next.catch(() => undefined).then(() => this.inflight);
         return next;
     }
     async observe() {
@@ -159,13 +204,18 @@ export class DeviceSession {
         this.store.add(obs, fps);
         return obs;
     }
-    /** Re-observe until two consecutive screens hash the same (UI settled), bounded. State-based, no fixed sleeps. */
-    async settle(deadline) {
+    /**
+     * Re-observe until two consecutive screens hash the same (UI settled), bounded. State-based, no fixed sleeps.
+     * Two identical frames of the *pre-action* screen only count after a grace window: a tap that launches an
+     * activity takes a beat before the window changes, and settling early reports the old screen as the result.
+     */
+    async settle(deadline, preHash = null) {
+        const graceEnd = Date.now() + SETTLE_GRACE_MS;
         let prev = await this.observe();
         while (Date.now() < deadline) {
             await new Promise(r => setTimeout(r, POLL_MS));
             const next = await this.observe();
-            if (next.screen_hash === prev.screen_hash)
+            if (next.screen_hash === prev.screen_hash && (next.screen_hash !== preHash || Date.now() >= graceEnd))
                 return next;
             prev = next;
         }
@@ -199,7 +249,7 @@ export class DeviceSession {
             const el = this.store.resolve(element_id);
             if (!el.enabled)
                 throw new MobiusError('ELEMENT_NOT_FOUND', `${element_id} is disabled`, { hint: 'Wait for it to enable or pick another element.' });
-            return { ...center(el, this.store.latest()?.elements), el };
+            return { ...this.pointOf(el), el };
         }
         if (x !== undefined && y !== undefined) {
             const s = this.store.latest()?.screen;
@@ -232,10 +282,14 @@ export class DeviceSession {
                 if (opts.guard?.ctx.mutating)
                     this.plane.actions++;
                 preHash = this.store.latest()?.screen_hash ?? preHash;
-                const message = await withTimeout(exec(target), opts.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS, tool);
+                const work = exec(target);
+                this.inflight = work.catch(() => undefined);
+                const message = await withTimeout(work, opts.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS, tool);
                 const verifying = !!opts.expect || !!opts.check;
                 const deadline = Date.now() + (verifying ? opts.verifyMs ?? DEFAULT_EXPECT_TIMEOUT_MS : 2_500);
-                let obs = await this.settle(Math.min(deadline, Date.now() + 2_500));
+                // A read changes nothing: no need to wait for the screen to settle (that costs the settle grace window).
+                const read = opts.guard && !opts.guard.ctx.mutating && !verifying;
+                let obs = read ? this.store.latest() ?? await this.observe() : await this.settle(Math.min(deadline, Date.now() + 2_500), preHash);
                 let verified = null;
                 let why = '';
                 const evaluate = (o) => {
@@ -296,7 +350,10 @@ export class DeviceSession {
                 });
             }
             catch (e) {
-                process.stderr.write(JSON.stringify({ level: 'error', msg: 'audit write failed', err: String(e) }) + '\n');
+                // Fail closed: this action already ran, so report it, but nothing more happens without an audit trail.
+                this.auditBroken = String(e).slice(0, 200);
+                process.stderr.write(JSON.stringify({ level: 'error', msg: 'audit write failed; refusing further actions', err: String(e) }) + '\n');
+                result = { ...result, message: `${result.message} (warning: the audit write failed, so Mobius refuses further actions)` };
             }
             return result;
         });

package/dist/interface/http.js

@@ -36,7 +36,8 @@ const send = (res, code, body, type = 'application/json') => {
     res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' });
     res.end(typeof body === 'string' ? body : JSON.stringify(body));
 };
-const sameToken = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+// Compare bytes, not characters: equal-length strings with different UTF-8 sizes would make timingSafeEqual throw.
+const sameToken = (a, b) => { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && timingSafeEqual(x, y); };
 export function createHttpServer(engine, audit, token, sessionKey) {
     if (!token || token.length < 16)
         throw new Error('MOBIUS_API_TOKEN must be at least 16 characters');