granttap-mcp 0.8.17 → 0.8.19

package/README.md

@@ -54,15 +54,38 @@ and completion events through the existing `notify` tool, and read state from a
 Mesh resource. Full transcripts and hidden reasoning are never mesh payloads.
 Claims have TTLs; a colliding claim is rejected before it is recorded so agents
 can choose different work or contact the owner before escalating to Needs You.
+Observed edit-tool requests are intent claims, not confirmed writes. Resource
+identity includes the repository; equal relative paths from separate repositories
+do not conflict, and another checkout is a coordination warning. The path
+matcher respects segment boundaries, so `src/auth.ts` and `src/auth.ts.bak`
+are distinct. A live repository reading refreshes HEAD after commit or checkout.
+
+When a separately distributed, verified GrantTap Engine is enabled on the
+computer, the bridge sends content-free Invocation events before its small Usage
+buffer is trimmed. Claude Code, Codex, and Cursor transcript scanners record
+native call identity, request, reported outcome, resource path, and explicit
+source gaps. The Engine owns the durable journal and bounded cursor history;
+the phone requests the latest or older page under the Project E2EE key. A
+reported successful tool call alone does not prove a filesystem change, and
+unavailable Engine history is reported as unavailable.
+The bridge does not yet produce verified filesystem-change events or attach
+revision-bound impact/consumer links to individual Invocations. It leaves that
+evidence unknown instead of treating an edit request or reported success as a
+confirmed content change.
+Claude Code and Codex denials with native call IDs are recorded as separate,
+metadata-only hook events with the applied rule and policy revision; an
+unidentified Cursor decision is not assigned to an invented call. Script and
+`SKILL.md` fingerprints include a content hash when the local file is readable,
+separate from their path identity. Missing content evidence remains unknown.
 
 <p align="center">
   <img src="docs/images/iphone-projects-shared.png" width="200" alt="Projects: one owned by this phone, one shared by another">
   <img src="docs/images/iphone-project-mesh.png" width="200" alt="A Project: Governance, members and computers, Mesh status, repositories, Tasks">
-  <img src="docs/images/iphone-task-route.png" width="200" alt="A Task: its executions, its claims, and who else is in its files">
+  <img src="docs/images/iphone-task-route.png" width="200" alt="A Task: executions, Runtime history, and resource claims">
   <img src="docs/images/iphone-handoff.png" width="200" alt="Task handoff: destination, push, and readiness checks">
 </p>
 
-<p align="center"><em>Projects, one of them shared by another phone · a Project with its Governance, members, computers, repositories, and Tasks · a Task with its executions and claims · a handoff with its readiness checks</em></p>
+<p align="center"><em>Projects, one of them shared by another phone · a Project with its Governance, members, computers, repositories, and Tasks · a Task with executions, Runtime history, and claims · a handoff with its readiness checks</em></p>
 
 For Claude Code, Codex, and Cursor, the provider hook runs inside the agent's
 own session and sees the exact call. GrantTap attributes every `notify` to the
@@ -162,6 +185,14 @@ and from then on that computer takes part in the mesh like any other: its
 chats are the Project's, its claims are seen by every other computer, and a
 Task can be handed to it.
 
+A Project can pin new tasks to one confirmed computer. The endpoint id is
+the stored computer identity, not the display name. Models offered on the
+phone come from that host's catalog. If the pinned host is offline, the
+Project either refuses the create or queues it until a deadline — it does
+not silently start the task elsewhere. A command issued for a previous
+instance of the computer (a restore or clone that kept pairing keys) is
+rejected. A pin is not a secure VM.
+
 ### A claim released by the person
 
 A claim outlives an agent that crashed or was closed, and the files it names
@@ -223,16 +254,21 @@ grok plugin marketplace add sergii-ziborov/granttap-mcp
 grok plugin install granttap --trust
 ```
 
-Import `sergii-ziborov/granttap-mcp` as a private Git plugin in Cursor. The
-MIT-licensed plugin is ready for Cursor's public review. Reload Cursor, then open
-**Cursor Customize → MCPs → GrantTap → Authenticate**. Complete authorization
-and any one-time QR pairing on `https://granttap.com/connect`.
-
-Open GrantTap from the plugin page or ask `Show my GrantTap pairing QR.` Codex
-renders an interactive connection card with pairing status, a one-time QR,
-copy-link fallback, and confirmed reconnect controls. The same tools still
-return readable MCP content in clients that do not render app UI. Detailed
-plugin instructions are in
+For Cursor, use the reviewed **GrantTap** Marketplace listing when it is visible
+to your account. Reload Cursor. On this computer, run `granttap setup`. Pair
+and change settings on [granttap.com/connect](https://granttap.com/connect)
+and in the GrantTap app. Authenticate opens that page even when this Mac is
+already paired — Approve the coding app, Reconnect, or Add another. A scan in
+GrantTap authorizes a new device; a saved pairing does not skip the page.
+Do not add GrantTap in Cursor Customize → MCPs. Cloud **Error · fetch
+failed** is leftover HTTP at `http://127.0.0.1:17342/mcp` — a user MCP row
+or an old plugin `mcp.json`. The Cursor plugin is stdio (`node -e`).
+
+Open GrantTap from the plugin connection card. Pairing status, a one-time QR
+when needed, and confirmed reconnect stay on that card, on
+`granttap.com/connect`, and in the GrantTap app. Do not ask an agent to print
+a pairing QR in chat. The same tools still return readable MCP content in
+clients that do not render app UI. Detailed plugin instructions are in
 [`plugins/granttap/README.md`](plugins/granttap/README.md).
 
 For the full background helper and provider hooks, install the CLI and run
@@ -244,8 +280,8 @@ granttap setup
 ```
 
 `granttap setup` detects supported local agents, installs or repairs their
-hooks, installs the background helper, configures Cursor's persistent local
-OAuth service when Cursor is present, and starts phone pairing when run in an
+hooks, installs the background helper, removes a leftover user GrantTap MCP
+entry when Cursor is present, and starts phone pairing when run in an
 interactive terminal. It ends with one exact next action.
 
 Setup also declares the separately distributed GrantTap Engine, which Project

package/apps/bridge/src/approvals/api.ts

@@ -0,0 +1,306 @@
+import { randomUUID } from "node:crypto";
+import type { RelayClient } from "../../../../packages/core/relay-client";
+import {
+  approvalAction,
+  type ApprovalDecision,
+  type ApprovalRequest,
+  type ApprovalResolved,
+  type ApprovalsStatus,
+} from "../../../../packages/protocol/schema";
+import {
+  MAX_PENDING_AGE_MS,
+  MAX_RECORDS,
+  TERMINAL_RETENTION_MS,
+  claimApprovalWinner,
+  effectiveFingerprint,
+  matchesRegistration,
+  normalizedSessionId,
+  pruneRecords,
+  readRawRecord,
+  readRecordPath,
+  recordFiles,
+  recordOutcome,
+  recordWinner,
+  registrationHandle,
+  requestDigest,
+  requestFingerprint,
+  terminalApproval,
+  writeRecord,
+  type ApprovalAcceptance,
+  type ApprovalOutcome,
+  type ApprovalRecord,
+  type ApprovalRegistration,
+  type ApprovalRegistrationHandle,
+  type ApprovalTerminalState,
+  type PendingApprovalRegistration,
+} from "./records";
+
+export function registerPendingApproval(
+  request: ApprovalRequest,
+  now = Date.now(),
+): ApprovalRegistration {
+  const fingerprint = requestFingerprint(request);
+  const existing = readRawRecord(request.requestId);
+  const existingWinner = existing ? recordWinner(existing) : null;
+  const effectiveAt = existingWinner?.acceptedAt ?? existing?.updatedAt;
+  if (existing && effectiveAt != null && now - effectiveAt <= TERMINAL_RETENTION_MS) {
+    if (effectiveFingerprint(existing) !== fingerprint) {
+      return {
+        matched: false,
+        newlyRegistered: false,
+        reason: "conflicting_request",
+      };
+    }
+    return {
+      matched: true,
+      newlyRegistered: false,
+      handle: registrationHandle(existing),
+    };
+  }
+  const record: ApprovalRecord = {
+    request,
+    state: "pending",
+    updatedAt: now,
+    generation: randomUUID(),
+    fingerprint,
+  };
+  writeRecord(record);
+  return {
+    matched: true,
+    newlyRegistered: true,
+    handle: registrationHandle(record),
+  };
+}
+
+export function acceptApprovalDecision(
+  decision: ApprovalDecision,
+  now = Date.now(),
+  expectedRegistration?: ApprovalRegistrationHandle,
+): ApprovalAcceptance {
+  const record = readRawRecord(decision.requestId);
+  if (!record || !matchesRegistration(record, expectedRegistration)) {
+    return { matched: false, newlyResolved: false };
+  }
+  const requestSessionId = normalizedSessionId(record.request.sessionId);
+  const decisionSessionId = normalizedSessionId(decision.sessionId);
+  if (requestSessionId !== decisionSessionId) {
+    return { matched: false, newlyResolved: false };
+  }
+  const existingOutcome = recordOutcome(record);
+  if (existingOutcome) return acceptance(record, existingOutcome, false);
+  if (record.state !== "pending") return { matched: false, newlyResolved: false };
+  if (now - record.updatedAt > MAX_PENDING_AGE_MS) {
+    return markApprovalTerminal(
+      decision.requestId,
+      "expired",
+      {
+        decision: "deny",
+        decidedBy: "system",
+        note: "Approval request expired before the decision arrived",
+        sessionId: requestSessionId,
+      },
+      now,
+      expectedRegistration,
+    );
+  }
+  const storedDecision: ApprovalDecision = {
+    ...decision,
+    sessionId: requestSessionId,
+    decidedAt: decision.decidedAt || now,
+  };
+  const outcome: ApprovalOutcome = { kind: "decision", decision: storedDecision };
+  const claim = claimApprovalWinner(record, outcome, now);
+  if (!claim.winner) {
+    // A corrupt/unreadable winner is fail-closed: do not ACK either contender.
+    return { matched: false, newlyResolved: false };
+  }
+  if (!claim.won) {
+    return acceptance(record, claim.winner.outcome, false);
+  }
+  return acceptance(record, claim.winner.outcome, true);
+}
+
+function acceptance(
+  record: ApprovalRecord,
+  outcome: ApprovalOutcome,
+  newlyResolved: boolean,
+): ApprovalAcceptance {
+  return {
+    matched: true,
+    newlyResolved,
+    request: record.request,
+    outcome,
+    decision: outcome.kind === "decision" ? outcome.decision : undefined,
+  };
+}
+
+/** Read the exact-scope outcome durably accepted by another process. */
+export function resolvedApprovalOutcome(
+  requestId: string,
+  expectedSessionId: string | null | undefined,
+  expectedRegistration?: ApprovalRegistrationHandle,
+): ApprovalOutcome | null {
+  const record = readRawRecord(requestId);
+  if (
+    !record ||
+    normalizedSessionId(record.request.sessionId) !== normalizedSessionId(expectedSessionId) ||
+    !matchesRegistration(record, expectedRegistration)
+  ) {
+    return null;
+  }
+  return recordOutcome(record);
+}
+
+/** Read a decision only when the current request generation and exact scope match. */
+export function resolvedApprovalDecision(
+  requestId: string,
+  expectedSessionId: string | null | undefined,
+  expectedRegistration?: ApprovalRegistrationHandle,
+): ApprovalDecision | null {
+  const outcome = resolvedApprovalOutcome(
+    requestId,
+    expectedSessionId,
+    expectedRegistration,
+  );
+  return outcome?.kind === "decision" ? outcome.decision : null;
+}
+
+export function markApprovalTerminal(
+  requestId: string,
+  state: ApprovalTerminalState,
+  options: {
+    decision?: ApprovalDecision["decision"] | null;
+    decidedBy?: string | null;
+    note?: string | null;
+    sessionId?: string | null;
+    resolvedAt?: number;
+  } = {},
+  now = Date.now(),
+  expectedRegistration?: ApprovalRegistrationHandle,
+): ApprovalAcceptance {
+  const record = readRawRecord(requestId);
+  if (!record || !matchesRegistration(record, expectedRegistration)) {
+    return { matched: false, newlyResolved: false };
+  }
+  const requestSessionId = normalizedSessionId(record.request.sessionId);
+  if (requestSessionId !== normalizedSessionId(options.sessionId)) {
+    return { matched: false, newlyResolved: false };
+  }
+  const existingOutcome = recordOutcome(record);
+  if (existingOutcome) return acceptance(record, existingOutcome, false);
+  if (record.state !== "pending") return { matched: false, newlyResolved: false };
+  const resolved = terminalApproval(requestId, state, {
+    ...options,
+    sessionId: requestSessionId,
+    resolvedAt: options.resolvedAt ?? now,
+  });
+  const outcome: ApprovalOutcome = { kind: "terminal", status: state, resolved };
+  const claim = claimApprovalWinner(record, outcome, now);
+  if (!claim.winner) return { matched: false, newlyResolved: false };
+  if (!claim.won) return acceptance(record, claim.winner.outcome, false);
+  return acceptance(record, claim.winner.outcome, true);
+}
+
+export function pendingApprovalRegistrations(
+  now = Date.now(),
+): PendingApprovalRegistration[] {
+  return recordFiles()
+    .map(readRecordPath)
+    .filter((record): record is ApprovalRecord =>
+      record != null &&
+      record.state === "pending" &&
+      now - record.updatedAt <= MAX_PENDING_AGE_MS &&
+      recordWinner(record) == null,
+    )
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .slice(0, 100)
+    .map((record) => ({
+      request: record.request,
+      handle: registrationHandle(record),
+    }));
+}
+
+/** Compatibility wrapper for callers that only render pending requests. */
+export function pendingApprovalRequests(now = Date.now()): ApprovalRequest[] {
+  return pendingApprovalRegistrations(now).map((item) => item.request);
+}
+
+function approvalScopeKey(request: Pick<ApprovalRequest, "requestId" | "sessionId">): string {
+  return `${request.requestId}\u0000${normalizedSessionId(request.sessionId) ?? ""}`;
+}
+
+function coveredApprovalScopes(
+  pending: ApprovalRequest[],
+  now: number,
+): Array<{ requestId: string; sessionId?: string }> {
+  const includedPending = new Set(pending.map(approvalScopeKey));
+  const covered = new Map<string, { requestId: string; sessionId?: string }>();
+  for (const path of recordFiles()) {
+    const record = readRecordPath(path);
+    if (!record) continue;
+    const winner = recordWinner(record);
+    if (now - (winner?.acceptedAt ?? record.updatedAt) > TERMINAL_RETENTION_MS) continue;
+    const isLivePending =
+      record.state === "pending" &&
+      winner == null &&
+      now - record.updatedAt <= MAX_PENDING_AGE_MS;
+    // Never claim an omitted live request as closed when the wire cap is hit.
+    if (isLivePending && !includedPending.has(approvalScopeKey(record.request))) continue;
+    const scope = {
+      requestId: record.request.requestId,
+      sessionId: normalizedSessionId(record.request.sessionId),
+    };
+    covered.set(approvalScopeKey(record.request), scope);
+  }
+  return [...covered.values()].slice(0, MAX_RECORDS);
+}
+
+let lastStatusGeneratedAt = 0;
+
+export function approvalsStatus(now = Date.now()): ApprovalsStatus {
+  pruneRecords(now);
+  const pending = pendingApprovalRequests(now);
+  const generatedAt = Math.max(Math.trunc(now), lastStatusGeneratedAt + 1);
+  lastStatusGeneratedAt = generatedAt;
+  return {
+    type: "approvals.status",
+    pending,
+    complete: false,
+    covered: coveredApprovalScopes(pending, now),
+    actions: pending.map(approvalAction),
+    generatedAt,
+  };
+}
+
+export function resolvedFromDecision(
+  decision: ApprovalDecision,
+  request?: ApprovalRequest,
+): ApprovalResolved {
+  return terminalApproval(decision.requestId, "applied", {
+    decision: decision.decision,
+    decidedBy: decision.decidedBy,
+    note: decision.note,
+    sessionId: request?.sessionId ?? decision.sessionId,
+    resolvedAt: decision.decidedAt,
+  });
+}
+
+export function resolvedFromOutcome(
+  outcome: ApprovalOutcome,
+  request?: ApprovalRequest,
+): ApprovalResolved {
+  return outcome.kind === "decision"
+    ? resolvedFromDecision(outcome.decision, request)
+    : outcome.resolved;
+}
+
+export async function sendApprovalResolved(
+  client: RelayClient,
+  payload: ApprovalResolved,
+): Promise<void> {
+  await client.send(payload, "phone", {
+    ttlMs: 15 * 60_000,
+    wake: false,
+    deliveryId: `approval-resolved-${requestDigest(payload.requestId)}`,
+  });
+}

package/apps/bridge/src/{approval.ts → approvals/index.ts}

@@ -5,9 +5,9 @@
  * replies with a matching ApprovalDecision (or the timeout fires — fail closed,
  * i.e. deny). This is what makes a phone tap gate a real tool call.
  */
-import type { PeerConfig } from "../../../packages/core/relay-client";
-import { RelayClient } from "../../../packages/core/relay-client";
-import type { ApprovalDecision, ApprovalRequest, Payload } from "../../../packages/protocol/schema";
+import type { PeerConfig } from "../../../../packages/core/relay-client";
+import { RelayClient } from "../../../../packages/core/relay-client";
+import type { ApprovalDecision, ApprovalRequest, Payload } from "../../../../packages/protocol/schema";
 import {
   acceptApprovalDecision,
   markApprovalTerminal,
@@ -16,8 +16,9 @@ import {
   resolvedFromOutcome,
   sendApprovalResolved,
   type ApprovalOutcome,
-} from "./approval-state";
-import { primeSessionKeys, sendSessionPayload } from "./session-keys";
+  type ApprovalRegistrationHandle,
+} from "./state";
+import { primeSessionKeys, sendSessionPayload } from "../host/session-keys";
 
 /**
  * Nobody answered — relay unreachable, or the phone never responded before the
@@ -77,7 +78,72 @@ export async function requestApproval(
             };
       }
     }
-    const decisionP = new Promise<ApprovalDecision | null>((resolve) => {
+    const waiting = waitForDecision(client, req, timeoutMs, registrationHandle);
+    cancelDecisionWait = waiting.cancel;
+    await sendRequest(client, req, timeoutMs);
+    const decision = await waiting.promise;
+
+    if (decision) return decision;
+    // `expired`, not `system`: nobody denied anything — the phone was asleep,
+    // offline, or the app was killed. Hooks hand `expired` back to the agent's
+    // own permission prompt. Reporting it as a plain deny bricks the agent:
+    // every tool call stalls for the full timeout and then fails.
+    const expired = markApprovalTerminal(req.requestId, "expired", {
+      decision: "deny",
+      decidedBy: "expired",
+      note: "No response from phone before timeout",
+      sessionId: req.sessionId,
+    }, Date.now(), registrationHandle);
+    if (!expired.outcome) {
+      return {
+        ...failClosed(req, "No response from phone before timeout"),
+        decidedBy: "expired",
+      };
+    }
+    await sendApprovalResolved(
+      client,
+      resolvedFromOutcome(expired.outcome, expired.request),
+    ).catch(() => {});
+    return decisionFromOutcome(expired.outcome, req);
+  } catch (err) {
+    // Transport blew up mid-flight (socket dropped, peer never attached). Like a
+    // failed connect this is `unreachable`: no human ever saw the request.
+    const expired = markApprovalTerminal(req.requestId, "expired", {
+      decision: "deny",
+      decidedBy: "unreachable",
+      note: "Approval channel error",
+      sessionId: req.sessionId,
+    }, Date.now(), registrationHandle);
+    if (!expired.outcome) {
+      return {
+        ...failClosed(req, `Approval channel error: ${(err as Error).message}`),
+        decidedBy: "unreachable",
+      };
+    }
+    await sendApprovalResolved(
+      client,
+      resolvedFromOutcome(expired.outcome, expired.request),
+    ).catch(() => {});
+    return decisionFromOutcome(expired.outcome, req);
+  } finally {
+    cancelDecisionWait();
+    if (ownsClient) client.close();
+  }
+}
+
+async function sendRequest(client: RelayClient, req: ApprovalRequest, timeoutMs: number): Promise<void> {
+  // The id carries no task content and lets APNs answer before iOS decrypts the card.
+  const options = { ttlMs: timeoutMs, wake: true, deliveryId: req.requestId };
+  if (req.sessionId) await sendSessionPayload(client, req, req.sessionId, "phone", options);
+  else await client.send(req, "phone", options);
+}
+
+function waitForDecision(
+  client: RelayClient, req: ApprovalRequest, timeoutMs: number,
+  registrationHandle?: ApprovalRegistrationHandle,
+): { promise: Promise<ApprovalDecision | null>; cancel: () => void } {
+  let cancel = () => {};
+  const promise = new Promise<ApprovalDecision | null>((resolve) => {
       let settled = false;
       let durablePoll: NodeJS.Timeout | undefined;
       let off = () => {};
@@ -89,7 +155,7 @@ export async function requestApproval(
         off();
         resolve(decision);
       };
-      cancelDecisionWait = () => finish(null);
+      cancel = () => finish(null);
       const timer = setTimeout(() => finish(null), timeoutMs);
       // The long-running desktop monitor may receive and durably accept the
       // same relay envelope first. Poll the shared registry so this one-shot
@@ -127,67 +193,7 @@ export async function requestApproval(
         return terminalSent;
       });
     });
-    // The request id is random and carries no task content. Reusing it as the
-    // opaque delivery id lets a generic APNs action answer the request even if
-    // iOS has not yet pulled and decrypted the full card.
-    const sendOptions = {
-      ttlMs: timeoutMs,
-      wake: true,
-      deliveryId: req.requestId,
-    };
-    if (req.sessionId) {
-      await sendSessionPayload(client, req, req.sessionId, "phone", sendOptions);
-    } else {
-      await client.send(req, "phone", sendOptions);
-    }
-    const decision = await decisionP;
-
-    if (decision) return decision;
-    // `expired`, not `system`: nobody denied anything — the phone was asleep,
-    // offline, or the app was killed. Hooks hand `expired` back to the agent's
-    // own permission prompt. Reporting it as a plain deny bricks the agent:
-    // every tool call stalls for the full timeout and then fails.
-    const expired = markApprovalTerminal(req.requestId, "expired", {
-      decision: "deny",
-      decidedBy: "expired",
-      note: "No response from phone before timeout",
-      sessionId: req.sessionId,
-    }, Date.now(), registrationHandle);
-    if (!expired.outcome) {
-      return {
-        ...failClosed(req, "No response from phone before timeout"),
-        decidedBy: "expired",
-      };
-    }
-    await sendApprovalResolved(
-      client,
-      resolvedFromOutcome(expired.outcome, expired.request),
-    ).catch(() => {});
-    return decisionFromOutcome(expired.outcome, req);
-  } catch (err) {
-    // Transport blew up mid-flight (socket dropped, peer never attached). Like a
-    // failed connect this is `unreachable`: no human ever saw the request.
-    const expired = markApprovalTerminal(req.requestId, "expired", {
-      decision: "deny",
-      decidedBy: "unreachable",
-      note: "Approval channel error",
-      sessionId: req.sessionId,
-    }, Date.now(), registrationHandle);
-    if (!expired.outcome) {
-      return {
-        ...failClosed(req, `Approval channel error: ${(err as Error).message}`),
-        decidedBy: "unreachable",
-      };
-    }
-    await sendApprovalResolved(
-      client,
-      resolvedFromOutcome(expired.outcome, expired.request),
-    ).catch(() => {});
-    return decisionFromOutcome(expired.outcome, req);
-  } finally {
-    cancelDecisionWait();
-    if (ownsClient) client.close();
-  }
+  return { promise, cancel };
 }
 
 function decisionFromOutcome(