granttap-mcp 0.8.99 → 0.8.101

package/apps/bridge/src/codex-questions/README.md

@@ -0,0 +1,27 @@
+# Codex desktop questions
+
+Public entry: `index.ts`. Native `request_user_input_async` questions are read
+from discovered Codex rollouts and sent to paired controllers as ordinary
+GrantTap question cards. Choice labels remain visible in the question; the
+person can type or speak the answer. The question, Task and native call retain
+their identities. No new provider, approval policy or pairing is created.
+
+The monitor checks only bounded tails of known chats every two seconds. Unchanged
+sources reuse their revision. Pending questions survive monitor restart and are
+replayed when the phone reconnects or refreshes; repeat scans do not send another
+wake notification. A native answer clears the corresponding card across devices.
+After a day, a GrantTap card expires without claiming the native question was
+answered. The Codex conversation remains the source of truth.
+
+Replies use the original host question item ID and normal scoped phone delivery,
+including current provider, pause and Task policy. Native admission uses one
+stable delivery ID per question, so concurrent controllers cannot submit two
+different answers. The phone's own message ID still receives its receipts.
+If the desktop owner is unavailable, question replies do not launch a separate
+CLI writer. An uncertain admission is not replayed or described as a confirmed
+native answer. Native transcript files are read without modification.
+
+Tests under `tests/` cover publication, reconnect replay, native acknowledgement,
+scope rejection, expiry and delivery through an isolated native IPC fixture.
+
+License: GrantTap Commercial Source License in the repository-root `LICENSE`.

package/apps/bridge/src/codex-questions/index.ts

@@ -0,0 +1,89 @@
+import type { RelayClient } from '../../../../packages/core/relay-client';
+import type { SessionInfo, UserMessage } from '../../../../packages/protocol/schema';
+import { nativeTranscriptSource } from '../sessions';
+import { handleInboundUserMessage } from '../monitor/message-delivery';
+import { sendDeliveryReceipt } from '../monitor/handlers/receipts';
+import { nativeAnswerEnvelope } from './observations';
+import { readQuestion, saveQuestion, storedQuestions, type QuestionRecord } from './records';
+import { observedQuestions } from './source';
+export { codexQuestionText } from './observations';
+
+const RETENTION_MS = 24 * 60 * 60_000;
+
+/** Phone questions travel as device-encrypted control events, independently of task-key grants. */
+export async function publishCodexQuestions(client: RelayClient, sessions: SessionInfo[],
+  options: { replay?: boolean; peerPublicKey?: string } = {}): Promise<void> {
+  for (const session of sessions.filter(s => s.agent === 'codex')) {
+    const path = nativeTranscriptSource(session);
+    if (!path) continue;
+    let observed;
+    try { observed = observedQuestions(session.sessionId, path); }
+    catch { continue; }
+    for (const question of observed.questions) {
+      if (Date.now() - question.createdAt > RETENTION_MS) continue;
+      const existing = readQuestion(question.requestId);
+      if (!existing) saveQuestion({ ...question, room: client.room });
+    }
+    const records = storedQuestions().filter(q => q.room === client.room && q.sessionId === session.sessionId)
+      .sort((a, b) => a.createdAt - b.createdAt || a.index - b.index);
+    for (const record of records) {
+      const expired = Date.now() - record.createdAt > RETENTION_MS;
+      if (observed.answered.has(record.requestId) && !record.answered) {
+        record.answered = true;
+        saveQuestion(record);
+      }
+      if (record.answered || expired) {
+        if (!record.resolvedSent || options.replay) {
+          await resolveQuestion(client, record, options.peerPublicKey, expired);
+          saveQuestion({ ...record, resolvedSent: true });
+        }
+      } else if (!record.announced || options.replay) {
+        const text = [record.question, ...record.options.map(value => '• ' + value)].join('\n');
+        await client.send({ type: 'agent.event', kind: 'question', requestId: record.requestId,
+          sessionId: session.sessionId, agent: 'codex', projectId: session.projectId,
+          taskId: session.taskId, computerId: session.computerId, text, createdAt: record.createdAt },
+        'phone', { ttlMs: Math.max(1, record.createdAt + RETENTION_MS - Date.now()),
+          wake: !record.announced, peerPublicKey: options.peerPublicKey,
+          deliveryId: 'native-question-' + record.requestId });
+        saveQuestion({ ...record, announced: true });
+      }
+    }
+  }
+}
+
+/** Reuse ordinary scoped delivery, policy and receipts; only the human's explicit answer is wrapped. */
+export async function handleCodexQuestionReply(client: RelayClient, message: UserMessage,
+  publish: () => Promise<void>, peerPublicKey?: string,
+  deliver = handleInboundUserMessage): Promise<boolean> {
+  if (!message.requestId || !peerPublicKey) return false;
+  const record = readQuestion(message.requestId);
+  if (!record || record.room !== client.room || record.sessionId !== message.sessionId) return false;
+  const path = nativeTranscriptSource({ sessionId: record.sessionId, agent: 'codex' });
+  if (!path) return false;
+  try {
+    if (observedQuestions(record.sessionId, path).answered.has(record.requestId)) {
+      record.answered = true;
+      saveQuestion(record);
+    }
+  } catch { return false; }
+  if (record.answered || Date.now() - record.createdAt > RETENTION_MS) {
+    if (message.messageId) await sendDeliveryReceipt(client, message.messageId, 'rejected',
+      record.answered ? 'This question was already answered in Codex.' : 'This question has expired. Open Codex.',
+      record.sessionId, peerPublicKey);
+    await resolveQuestion(client, record, peerPublicKey, !record.answered);
+    return true;
+  }
+  if (!message.text.trim() || message.text.length > 4_000 || message.attachments?.length
+    || message.attachmentRefs?.length) return false;
+  return deliver(client, { ...message, requestId: undefined,
+    messageId: message.messageId ?? 'codex-answer-' + record.requestId,
+    text: nativeAnswerEnvelope(record, message.text) }, publish, peerPublicKey,
+  { messageId: record.requestId, nativeOnly: true });
+}
+
+function resolveQuestion(client: RelayClient, record: QuestionRecord, peerPublicKey?: string, expired = false) {
+  return client.send({ type: 'approval.resolved', requestId: record.requestId,
+    sessionId: record.sessionId, status: expired ? 'expired' : 'applied',
+    nativeUiCleared: record.answered === true, resolvedAt: Date.now() },
+  'phone', { ttlMs: 15 * 60_000, wake: false, peerPublicKey });
+}

package/apps/bridge/src/codex-questions/observations.ts

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { safeParse, ts } from '../sessions/support/common';
+
+const Questions = z.object({ questions: z.array(z.object({ title: z.string().trim().min(1).max(2_000),
+  options: z.array(z.string().trim().min(1).max(512)).max(8).nullish() })).min(1).max(4) });
+const Answer = z.object({ questionItemId: z.string(), answer: z.string().trim().min(1) });
+
+export type NativeQuestion = { requestId: string; sessionId: string; callId: string; index: number;
+  question: string; options: string[]; createdAt: number };
+
+export function questionId(sessionId: string, callId: string, index: number): string {
+  return 'codex-question-' + createHash('sha256').update(JSON.stringify([sessionId, callId, index]))
+    .digest('hex').slice(0, 32);
+}
+
+export function nativeQuestionObservations(sessionId: string, lines: string[]) {
+  const questions: NativeQuestion[] = [];
+  const answered = new Set<string>();
+  for (const line of lines) {
+    const row = safeParse(line);
+    const p = row?.payload;
+    if (!p) continue;
+    if (row.type === 'response_item' && p.type === 'function_call' && p.name === 'request_user_input_async'
+      && typeof p.call_id === 'string' && /^[a-zA-Z0-9_-]{1,180}$/.test(p.call_id)) {
+      const data = Questions.safeParse(typeof p.arguments === 'string' ? safeParse(p.arguments) : p.arguments);
+      const at = ts(row.timestamp);
+      if (!data.success || !at) continue;
+      data.data.questions.forEach((q, index) => questions.push({ requestId: questionId(sessionId, p.call_id, index),
+        sessionId, callId: p.call_id, index, question: q.title, options: q.options ?? [], createdAt: at }));
+    }
+    const texts = row.type === 'response_item' && p.type === 'message' && p.role === 'user'
+      ? (p.content ?? []).filter((b: any) => ['input_text', 'text'].includes(b.type)).map((b: any) => b.text)
+      : row.type === 'event_msg' && p.type === 'user_message' ? [p.message ?? p.text] : [];
+    for (const text of texts) {
+      if (typeof text !== 'string') continue;
+      const envelope = /^<send_user_message_question_reply>\s*([\s\S]*?)\s*<\/send_user_message_question_reply>$/.exec(text.trim());
+      if (!envelope) continue;
+      const replies = z.array(Answer).safeParse(safeParse(envelope[1]!));
+      if (!replies.success) continue;
+      for (const reply of replies.data) {
+        const id = z.tuple([z.literal('request_user_input_async'), z.string(), z.number().int().min(0).max(3)])
+          .safeParse(safeParse(reply.questionItemId));
+        if (id.success) answered.add(questionId(sessionId, id.data[1], id.data[2]));
+      }
+    }
+  }
+  return { questions, answered };
+}
+
+export function nativeAnswerEnvelope(question: NativeQuestion, answer: string): string {
+  return '<send_user_message_question_reply>\n' + JSON.stringify([{
+    questionItemId: JSON.stringify(['request_user_input_async', question.callId, question.index]),
+    question: question.question, answer,
+  }]) + '\n</send_user_message_question_reply>';
+}
+
+export function codexQuestionText(input: unknown): string | undefined {
+  const parsed = Questions.safeParse(input);
+  if (!parsed.success) return undefined;
+  return parsed.data.questions.map(q => [q.title, ...(q.options ?? []).map(option => '• ' + option)]
+    .join('\n')).join('\n\n');
+}

package/apps/bridge/src/codex-questions/records.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { configDir, writePrivateFile } from '../config';
+import { questionId } from './observations';
+
+const Record = z.object({ requestId: z.string(), sessionId: z.string(), callId: z.string(),
+  index: z.number().int().min(0).max(3), question: z.string().max(2_000),
+  options: z.array(z.string().max(512)).max(8), createdAt: z.number(), room: z.string(),
+  announced: z.boolean().optional(), answered: z.boolean().optional(), resolvedSent: z.boolean().optional() });
+export type QuestionRecord = z.infer<typeof Record>;
+const directory = () => join(configDir(), 'codex-question-records');
+
+export function readQuestion(requestId: string): QuestionRecord | undefined {
+  if (!/^codex-question-[a-f0-9]{32}$/.test(requestId)) return undefined;
+  try {
+    const path = join(directory(), requestId + '.json');
+    if (statSync(path).size > 16_384) return undefined;
+    const record = Record.parse(JSON.parse(readFileSync(path, 'utf8')));
+    return record.requestId === requestId && questionId(record.sessionId, record.callId, record.index) === requestId
+      ? record : undefined;
+  } catch { return undefined; }
+}
+
+export function saveQuestion(record: QuestionRecord): void {
+  if (!/^codex-question-[a-f0-9]{32}$/.test(record.requestId)) throw new Error('Invalid native question identity');
+  writePrivateFile(join(directory(), record.requestId + '.json'), JSON.stringify(record));
+}
+
+export function storedQuestions(): QuestionRecord[] {
+  if (!existsSync(directory())) return [];
+  return readdirSync(directory()).filter(name => /^codex-question-[a-f0-9]{32}\.json$/.test(name))
+    .slice(-300).flatMap(name => {
+      const record = readQuestion(name.slice(0, -5));
+      return record ? [record] : [];
+    });
+}

package/apps/bridge/src/codex-questions/source.ts

@@ -0,0 +1,19 @@
+import { statSync } from 'node:fs';
+import { readCodexLogWindow } from '../sessions/scan/codex';
+import { nativeQuestionObservations } from './observations';
+
+type Cached = { revision: string; observation: ReturnType<typeof nativeQuestionObservations> };
+const sources = new Map<string, Cached>();
+
+/** Read only a discovered source's bounded tail; idle conversations cost one stat. */
+export function observedQuestions(sessionId: string, path: string) {
+  const stat = statSync(path);
+  const key = JSON.stringify([sessionId, path]);
+  const revision = `${stat.mtimeMs}:${stat.size}`;
+  const cached = sources.get(key);
+  if (cached?.revision === revision) return cached.observation;
+  const observation = nativeQuestionObservations(sessionId, readCodexLogWindow(path, 0, 2 * 1024 * 1024));
+  if (sources.size >= 64) sources.clear();
+  sources.set(key, { revision, observation });
+  return observation;
+}

package/apps/bridge/src/monitor/handlers/inbound.ts

@@ -45,6 +45,8 @@ import { handleControllerPairRequest, handleInboundKnowledgeWrite } from "../con
 import { acceptPhoneAccountLink } from "../../account-recovery/phone-link";
 import { approvalsStatus } from '../../approvals/state';
 import { handleDeliveryReceiptQuery } from '../message-delivery/status-query';
+import { handleCodexQuestionReply, publishCodexQuestions } from '../../codex-questions';
+import { publishedCatalog } from '../../session-catalog';
 
 export async function handleMonitorMessage(
   client: RelayClient,
@@ -70,7 +72,7 @@ export async function handleMonitorMessage(
       return handleInboundKnowledgeWrite(client, payload, input.peerPublicKey, publish);
     }
     if (payload.type === "user.message") {
-      return handleInboundUserMessage(client, payload, publish, input.peerPublicKey);
+      return handlePhoneUserMessage(client, payload, publish, input.peerPublicKey);
     } else if (payload.type === 'delivery.receipt.query') {
       return handleDeliveryReceiptQuery(client, payload, input.peerPublicKey);
     } else if (payload.type === "user.attachment") {
@@ -145,6 +147,13 @@ export async function handleMonitorMessage(
     return false;
 }
 
+function handlePhoneUserMessage(client: RelayClient, payload: Extract<Payload, { type: 'user.message' }>,
+  publish: (forceHistory?: boolean) => Promise<void>, peerPublicKey?: string) {
+  return payload.requestId?.startsWith('codex-question-')
+    ? handleCodexQuestionReply(client, payload, () => publish(), peerPublicKey)
+    : handleInboundUserMessage(client, payload, publish, peerPublicKey);
+}
+
 function handlePeerConfiguration(client: RelayClient, payload: Payload, peerPublicKey: string | undefined,
   publish: (forceHistory?: boolean) => Promise<void>): Promise<boolean> | undefined {
   if (payload.type === 'project.transport.set') {
@@ -192,6 +201,9 @@ async function handleInboundRefresh(
   // Notification actions must not wait behind provider scans or graph analysis.
   await client.send(approvalsStatus(), 'phone', { peerPublicKey, reliable: false, ttlMs: 90_000 })
     .catch(() => {});
+  const known = publishedCatalog(client);
+  if (known) await publishCodexQuestions(client, [...known.sessions, ...(known.history ?? [])],
+    { replay: true, peerPublicKey }).catch(() => {});
   // An explicit refresh may pay for the full history scan; routine Mesh
   // snapshots use the cached history and fresh live sessions.
   invalidateMeshSessionHistory();

package/apps/bridge/src/monitor/handlers/user-message.ts

@@ -120,6 +120,7 @@ export async function handleUserMessage(
   message: UserMessage,
   onProcessing?: () => Promise<void>,
   peerPublicKey?: string,
+  native?: { messageId: string; nativeOnly: true },
 ): Promise<"accepted" | "rejected"> {
   const say = (text: string, sessionId?: string, wake = false, kind: "status" | "response" = "response") => {
     const payload = agentEventForUserMessage(message, text, sessionId, kind);
@@ -172,7 +173,8 @@ export async function handleUserMessage(
   await onProcessing?.();
   const startedAt = Date.now();
   const run = deliverToSession(target, message.text, PHONE_RUN_LIMIT_MS, attachments, {
-    messageId: message.messageId,
+    messageId: native?.messageId ?? message.messageId,
+    nativeOnly: native?.nativeOnly,
     onAgentActivity: () => reportMessageAgentActivity(client, message, peerPublicKey),
     preferredMcp: message.preferredMcp,
     skill: message.skill,

package/apps/bridge/src/monitor/message-delivery/index.ts

@@ -10,6 +10,7 @@ export async function handleInboundUserMessage(
   client: RelayClient, payload: Extract<Payload, { type: "user.message" }>,
   publish: (forceHistory?: boolean) => Promise<void>,
   peerPublicKey?: string,
+  native?: { messageId: string; nativeOnly: true },
 ): Promise<boolean> {
   if (payload.requestId) return false;
   let deliveryStarted = false;
@@ -33,7 +34,7 @@ export async function handleInboundUserMessage(
       if (!payload.messageId) return;
       acknowledgeProcessingDelivery(payload.messageId);
       await sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId, peerPublicKey);
-    }, peerPublicKey);
+    }, peerPublicKey, native);
     if (payload.messageId && deliveryStarted) {
       if (outcome === "rejected") abandonDelivery(payload.messageId);
       else {

package/apps/bridge/src/monitor/support/runtime.ts

@@ -28,6 +28,7 @@ import { boundedCatalogHistory, INTERVAL_MS, publishSessionEvents } from "../han
 import { sweepAttachments } from "../handlers/receipts";
 import { handleMonitorMessage } from "../handlers/inbound";
 import { decorateTaskOriginCatalog } from '../../task-origins';
+import { publishCodexQuestions } from '../../codex-questions';
 
 const HISTORY_INTERVAL_MS = 60_000;
 const resumedHeads = new WeakSet<RelayClient>();
@@ -215,6 +216,7 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
       if (leadership.acquire()) {
         await client.send(approvalsStatus(), 'phone', { peerPublicKey, reliable: false, ttlMs: 90_000 })
           .catch(() => {});
+        await replayNativeQuestions(client, peerPublicKey);
       }
     }
     return handleMonitorMessage(client, payload, { leadership, subscriptions, publish, peerPublicKey });
@@ -237,6 +239,7 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     immediate: true,
     publish: () => publishHeartbeat(client).catch(() => {}),
   });
+  const stopQuestions = startQuestionLoop(client, leadership, subscriptions);
 
   return {
     publish: () => publish(false),
@@ -249,6 +252,7 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
       stopMonitorCapabilities(client);
       stopMonitorMeshes(client);
       stopHeartbeat();
+      stopQuestions();
       loadLoop.stop();
       off();
       subscriptions.clear();
@@ -256,3 +260,22 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     },
   };
 }
+
+function startQuestionLoop(client: RelayClient, leadership: { acquire: () => boolean }, subscriptions: Set<string>) {
+  return startPublishLoop({
+    connected: () => client.isConnected,
+    intervalMs: 2_000,
+    immediate: true,
+    publish: async () => {
+      if (!leadership.acquire()) return;
+      const known = publishedCatalog(client);
+      if (known) await publishCodexQuestions(client, [...known.sessions,
+        ...(known.history ?? []).filter(s => subscriptions.has(s.sessionId))]).catch(() => {});
+    },
+  });
+}
+
+async function replayNativeQuestions(client: RelayClient, peerPublicKey: string) {
+  const known = publishedCatalog(client);
+  if (known) await publishCodexQuestions(client, known.sessions, { replay: true, peerPublicKey }).catch(() => {});
+}

package/apps/bridge/src/reply/payload/types.ts

@@ -7,6 +7,8 @@ export type DeliveryOptions = {
   onAgentActivity?: (nativeSessionId: string) => void;
   /** Stable controller delivery ID, also used by the provider's native admission. */
   messageId?: string;
+  /** Native host questions must never fall back to a second CLI conversation. */
+  nativeOnly?: boolean;
   /** Computer-generated identity before temporary attachment paths are inserted. */
   intentDigest?: string;
   preferredMcp?: string;

package/apps/bridge/src/reply/process/codex-headless.ts

@@ -54,6 +54,7 @@ export async function runCodex(
 ): Promise<ReplyResult> {
   const native = await deliverToCodexDesktop({ session, text, images, options, timeoutMs });
   if (native) return native;
+  if (options.nativeOnly) return { ok: false, error: 'Open this conversation in Codex to answer its question.' };
   const configured = loadRuntimeConfig().sessionAccess[session.sessionId];
   const disabledMcp = loadRuntimeConfig().sessionMcpDisabled[session.sessionId] ?? [];
   const sandbox = configured === "read-only"

package/apps/bridge/src/sessions/host-heartbeat/README.md

@@ -0,0 +1,14 @@
+# Host heartbeat presentation
+
+Public entry: `heartbeatDisplayText` in `index.ts`. Complete host heartbeat
+instructions and quiet `DONT_NOTIFY` responses do not appear as human messages,
+conversation titles or status previews. `NOTIFY` responses retain their message
+text and Markdown. Native files and IDs are unchanged. Projection happens before
+the live transcript's text limit is applied.
+
+Unknown fields, decisions, malformed XML, quoted examples and ordinary messages
+remain visible. XML text accepts only the predefined entities and valid numeric
+character references; it never resolves external resources.
+
+Behavioral tests live in `tests/`. License: GrantTap Commercial Source License in
+the repository-root `LICENSE`.

package/apps/bridge/src/sessions/host-heartbeat/index.ts

@@ -0,0 +1,47 @@
+/** Only complete host envelopes are metadata. Quoted or unknown XML stays visible. */
+export function heartbeatDisplayText(value: unknown, kind: string): string | undefined {
+  if (typeof value !== 'string' || !['user', 'message', 'final'].includes(kind)) return undefined;
+  const root = /^<heartbeat>([\s\S]*)<\/heartbeat>$/.exec(value.trim());
+  if (!root) return undefined;
+  const body = root[1]!;
+  const fields = new Map<string, string>();
+  let offset = 0;
+  for (const match of body.matchAll(/<([a-z_]+)>([^<]*)<\/\1>/g)) {
+    if (body.slice(offset, match.index).trim() || fields.has(match[1]!)) return undefined;
+    const decoded = xmlText(match[2]!);
+    if (decoded === undefined) return undefined;
+    fields.set(match[1]!, decoded.trim());
+    offset = match.index + match[0].length;
+  }
+  if (body.slice(offset).trim() || !fields.get('automation_id')) return undefined;
+  if (kind === 'user') {
+    if ([...fields.keys()].some(key => !['automation_id', 'current_time_iso', 'instructions'].includes(key))
+      || !fields.get('instructions') || fields.get('current_time_iso') === '') return undefined;
+    return '';
+  }
+  if (fields.size !== 3 || !fields.has('decision') || !fields.get('message')) return undefined;
+  if (fields.get('decision') === 'DONT_NOTIFY') return '';
+  return fields.get('decision') === 'NOTIFY' ? fields.get('message') : undefined;
+}
+
+function xmlText(value: string): string | undefined {
+  const entities: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+  if ([...value].some(character => !xmlCharacter(character.codePointAt(0)!))) return undefined;
+  if (/&(?!(?:amp|lt|gt|quot|apos|#\d+|#x[\da-fA-F]+);)/.test(value)) return undefined;
+  let valid = true;
+  const decoded = value.replace(/&(amp|lt|gt|quot|apos|#\d+|#x[\da-fA-F]+);/g, (_all, entity: string) => {
+    if (entities[entity] !== undefined) return entities[entity];
+    const number = entity.startsWith('#x') ? Number.parseInt(entity.slice(2), 16) : Number(entity.slice(1));
+    if (xmlCharacter(number)) {
+      return String.fromCodePoint(number);
+    }
+    valid = false;
+    return '';
+  });
+  return valid ? decoded : undefined;
+}
+
+function xmlCharacter(number: number): boolean {
+  return number === 9 || number === 10 || number === 13 || number >= 0x20 && number <= 0xd7ff
+    || number >= 0xe000 && number <= 0xfffd || number >= 0x10000 && number <= 0x10ffff;
+}

package/apps/bridge/src/sessions/native-source.ts

@@ -10,7 +10,7 @@ export function nativeTranscriptRoots(): { claude: string; codex: string } {
 }
 
 /** Native paths come only from discovery; a phone never supplies one. */
-export function nativeTranscriptSource(session: SessionInfo): string | undefined {
+export function nativeTranscriptSource(session: Pick<SessionInfo, 'agent' | 'sessionId'>): string | undefined {
   if (session.agent === "claude") return claudeLogPathBySession.get(session.sessionId);
   if (session.agent === "codex") return codexLogPathBySession.get(session.sessionId);
   return undefined;

package/apps/bridge/src/sessions/scan/codex/activity/rows.ts

@@ -8,6 +8,7 @@ import { redactSecrets } from "../../../telemetry/command-preview";
 import { activityTelemetry, pendingCapabilityObservation, type CapabilityObservation, type PendingCapabilityTool } from "../../../telemetry";
 import type { RecordedFileChange } from "../../../../transcript-history/changes";
 import type { ToolCallDetail } from "../../../../transcript-history/tool-details";
+import { codexQuestionText } from '../../../../codex-questions';
 
 function codexToolInput(payload: any): unknown {
   const input = payload.arguments ?? payload.input ?? payload.action;
@@ -82,6 +83,7 @@ export function appendCodexActivity(input: {
       const toolName = String(p.name ?? p.type);
       const callId = String(p.call_id ?? p.id ?? `${createdAt}:${index}`);
       const sourceId = `${sourceThreadId}:${callId}`;
+      if (appendQuestionIfPresent(input, toolName, args, createdAt, sourceId)) return;
       const pending: PendingCapabilityTool = {
         sourceId,
         sessionId: session.sessionId,
@@ -111,3 +113,13 @@ export function appendCodexActivity(input: {
     }
   });
 }
+
+function appendQuestionIfPresent(input: Parameters<typeof appendCodexActivity>[0], toolName: string,
+  args: unknown, createdAt: number, sourceId: string): boolean {
+  const question = toolName === 'request_user_input_async' ? codexQuestionText(args) : undefined;
+  if (!question) return false;
+  appendEntry({ out: input.out, seen: input.seen, sessionId: input.session.sessionId,
+    kind: 'message', text: question, createdAt, ordinal: 0, idOverride: sourceId,
+    fullText: input.fullText, extras: input.child ? childEntryFields(input.child) : {} });
+  return true;
+}

package/apps/bridge/src/sessions/scan/codex/parse.ts

@@ -16,6 +16,7 @@ import type { SessionInfo } from "../../../../../../packages/protocol/schema";
 import { childTitle } from "../../support/child-threads";
 import { visibleUserText } from "../../support/activity-helpers";
 import { codexHeadRequest, isProvisionalPageTitle } from "../../support/codex-head";
+import { heartbeatDisplayText } from '../../host-heartbeat';
 
 type CodexParseState = {
   sessionId: string;
@@ -107,7 +108,9 @@ function applyCodexLine(d: any, state: CodexParseState): void {
   }
 
   if (d.type === "event_msg" && d.payload?.type === "agent_message") {
-    state.summary = childTitle(d.payload.message ?? d.payload.text)?.slice(0, 180);
+    const raw = d.payload.message ?? d.payload.text;
+    const visible = heartbeatDisplayText(raw, 'message') ?? raw;
+    if (visible) state.summary = childTitle(visible)?.slice(0, 180);
   }
   if (
     d.type === "response_item" &&
@@ -117,7 +120,8 @@ function applyCodexLine(d: any, state: CodexParseState): void {
   ) {
     for (const block of d.payload.content) {
       if (["output_text", "text"].includes(block?.type) && typeof block.text === "string") {
-        state.summary = childTitle(block.text)?.slice(0, 180);
+        const visible = heartbeatDisplayText(block.text, 'message') ?? block.text;
+        if (visible) state.summary = childTitle(visible)?.slice(0, 180);
       }
     }
   }

package/apps/bridge/src/sessions/support/activity-helpers.ts

@@ -4,6 +4,7 @@
  * Provider-specific thinking/reasoning blocks are deliberately ignored.
  */
 import type { ActivityEntry } from "../../../../../packages/protocol/schema";
+import { heartbeatDisplayText } from '../host-heartbeat';
 import {
   parseMcpToolName,
   skillNameFromInput,
@@ -61,6 +62,8 @@ export function stripAttachmentNote(text: string): string {
 }
 
 export function visibleUserText(value: unknown): string {
+  const heartbeat = heartbeatDisplayText(value, 'user');
+  if (heartbeat !== undefined) return heartbeat;
   // Codex records the selected Page as a user row, including a null selection.
   // Remove the host-owned block, retaining any real request alongside it.
   const contextFree = String(value ?? "").replace(
@@ -246,7 +249,8 @@ export function pushEntry(input: PushEntryInput): void {
   const shownKind: ActivityEntry["kind"] = notification ? "status" : kind;
   const limit = shownKind === "tool" || shownKind === "status" ? MAX_ACTIVITY_TEXT
     : input.fullText ? Infinity : MAX_MESSAGE_TEXT;
-  const clean = activityText(notification ?? (kind === "user" ? visibleUserText(text) : text), limit);
+  const presented = heartbeatDisplayText(text, kind) ?? text;
+  const clean = activityText(notification ?? (kind === "user" ? visibleUserText(text) : presented), limit);
   if (!clean) return;
   const duplicateKey = idOverride ? `${idOverride}:${shownKind}`
     : `${createdAt}:${extras.childThreadId ?? "root"}:${shownKind}:${extras.toolName ?? ""}:${clean}`;

package/apps/bridge/src/transcript-history/index.ts

@@ -8,6 +8,7 @@ import { recordedFileChanges } from "./changes";
 import { recordedToolDetails } from "./tool-details";
 import { completedTurnChanges } from "./turn-changes";
 import { cursorActivity, cursorConversationHistory } from "../sessions/cursor";
+import { parseCodexFile } from '../sessions/scan/codex/parse';
 export { nativeImageLines } from "./images";
 export { nativeTranscriptImage } from './images/native';
 export { nativeTranscriptEntry } from './images/advertised-entry';
@@ -93,7 +94,8 @@ export function readTranscriptHistory(input: SessionInfo, cursor?: string): Sess
     : window.lines[0]?.offset ?? window.start;
   const prior = input.sessionId !== session.sessionId && offset === 0 ? transferHistory(input) : undefined;
   return { type: "session.activity", sessionId: input.sessionId, agent: session.agent,
-    state: session.state, entries, generatedAt: Date.now(), history: {
+    state: session.agent === 'codex' ? parseCodexFile(path)?.session.state ?? session.state : session.state,
+    entries, generatedAt: Date.now(), history: {
       hasMore: offset > 0 || Boolean(prior?.entries.length),
       ...(offset > 0 ? { cursor: window.cursorAt(offset) }
         : prior?.entries.length ? { cursor: `transfer-context:${prior.entries.length + (prior.history?.hasMore ? Number(prior.history.cursor?.split(':')[1]) : 0)}` } : {}),

package/cursor-plugin/README.md

@@ -10,7 +10,7 @@ keeps each phone response tied to the exact originating chat and prompt.
 Install the supported CLI on this computer, then run:
 
 ```bash
-npm install -g granttap-mcp@0.8.99
+npm install -g granttap-mcp@0.8.101
 granttap setup
 granttap status
 ```

package/cursor-plugin/mcp.json

@@ -4,7 +4,7 @@
       "command": "node",
       "args": [
         "-e",
-        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.99\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 22.13.0+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
+        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.101\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 22.13.0+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
       ]
     }
   }

package/cursor-plugin/stdio-bootstrap.cjs

@@ -7,7 +7,7 @@ const { spawn } = require("node:child_process");
 const { existsSync } = require("node:fs");
 const { delimiter, dirname, join } = require("node:path");
 
-const PACKAGE = "granttap-mcp@0.8.99";
+const PACKAGE = "granttap-mcp@0.8.101";
 const dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === "1";
 const platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM
   ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granttap-mcp",
-  "version": "0.8.99",
+  "version": "0.8.101",
   "description": "Commercial computer runtime connecting local coding agents to GrantTap on Mac, iPhone, iPad and Apple Watch.",
   "type": "module",
   "bin": {

package/packages/core/outbound-scheduler/README.md

@@ -26,3 +26,9 @@ controller, with priority over queued periodic snapshots. Older callers without
 a requester retain the complete authorized recipient set. Every explicit target
 passes the pairing and controller authorization checks. Routing never deletes a
 pairing or changes approval policy.
+
+Requested image chunks retain their local scheduling priority through task
+encryption and precede background transcript backfill. The local `urgent` send
+hint is never serialized into relay routing metadata and does not request APNs.
+The image-priority test receives and decrypts both layers and verifies ordering
+while preserving every background frame and the existing six-millisecond pace.

package/packages/core/outbound-scheduler/index.ts

@@ -71,7 +71,7 @@ export class OutboundFrameQueue {
   }
 }
 
-export const priorityControlPayload = (type: Payload["type"]) => type === "hello" || type.startsWith("approval.")
+export const priorityControlPayload = (type: Payload["type"]) => type === "hello" || type === "session.image.chunk" || type.startsWith("approval.")
   || type.startsWith("config.") || type.startsWith("pairing.") || type === "session.key.grant"
   || type === "delivery.receipt" || type === "sessions.status" || type === "machine.heartbeat" || type === "approvals.status";
 
@@ -83,6 +83,6 @@ export async function sendEncryptedPayload(queue: OutboundFrameQueue, config: Pe
   if (!peers.length) throw new Error("no authorized pairing peers");
   for (const peerPublicKey of peers) {
     await queue.send(sealEnvelope({ ...config, peerPublicKey }, payload, to,
-      peers.length === 1 ? options : { ...options, deliveryId: undefined }), priorityControlPayload(payload.type) || options.wake === true);
+      peers.length === 1 ? options : { ...options, deliveryId: undefined }), priorityControlPayload(payload.type) || options.urgent === true || options.wake === true);
   }
 }

package/packages/core/relay-client-types.ts

@@ -46,6 +46,8 @@ export type RelayClientOptions = {
 };
 
 export type SendOptions = {
+  /** Local scheduling only; never serialized into relay routing metadata. */
+  urgent?: boolean;
   /** Negotiated opaque latest-state replay, independent of delivery ACKs. */
   retainedState?: boolean;
   stateKey?: string;

package/packages/core/relay-client.ts

@@ -214,7 +214,7 @@ export class RelayClient {
       || !this.peerIsAllowed(peerPublicKey)) throw new Error("controller peer is not authorized");
     if (!this.frames) throw new Error("relay not connected");
     await this.frames.send(sealEnvelope({ ...this.cfg, peerPublicKey }, payload, this.otherRole(), { ...retainedPayloadOptions(payload), ...options, retainedState: this.retainedState, recipientRouting: this.recipientRouting }),
-      priorityControlPayload(payload.type) || options.wake === true);
+      priorityControlPayload(payload.type) || options.urgent === true || options.wake === true);
   }
 
   setSessionKey(sessionId: string, key: string): void {
@@ -232,7 +232,8 @@ export class RelayClient {
     to: Role | "all" = this.otherRole(),
     options: SendOptions = {},
   ): Promise<void> {
-    await this.send(sealSessionPayload(payload, sessionId, this.sessionKeys.get(sessionId)), to, { ...retainedPayloadOptions(payload), ...options });
+    await this.send(sealSessionPayload(payload, sessionId, this.sessionKeys.get(sessionId)), to, { ...retainedPayloadOptions(payload), ...options,
+      urgent: options.urgent === true || priorityControlPayload(payload.type) });
   }
 
   /** Register before connect so only durable receivers advertise task-job support. */