granttap-mcp 0.8.2 → 0.8.4

package/README.md

@@ -82,7 +82,25 @@ committed state and leaving that work behind. Asked to checkpoint from the
 phone, the source computer commits everything to `granttap/checkpoint/<task>`
 from a temporary index, so HEAD, the current branch, and the working tree stay
 exactly as the agent left them, and the capsule carries that commit. Nothing is
-pushed; the destination says so if the commit has not reached it.
+pushed unless the phone asks for it per handoff: then the source publishes the
+branch the capsule names to the checkout's remote — never by force — before the
+capsule leaves, a push that fails blocks the move, and a destination that lacks
+the commit fetches that branch once before refusing. A handoff can also stay on
+one computer: the same Task continues with another agent there, in a worktree
+of its own from the same commit, taken up at once by the computer that
+prepared it.
+
+### Pause and resume
+
+A chat can be held from the phone. The hold is enforced where the work
+happens: every provider hook refuses every tool call from that chat — the
+agent reads "GrantTap paused this chat from the phone" and is told to wait —
+and a delivery already running for the chat is stopped. A message sent to a
+held chat is refused for the same reason. Resuming lifts the hold; asked to
+continue, the computer answers the phone at once and then delivers one
+continuation prompt in the background, so "start" is one tap. The hold lives
+in the runtime config as `pausedSessions` and is published on the session as
+`paused`.
 
 Claims do not wait for an agent to announce them. Every edit an agent makes is
 visible in its transcript, so the runtime derives an intent claim from each
@@ -205,6 +223,37 @@ The bounded encrypted protocol preserves:
 An optional bounded `errorClass` may describe an error category. Full tool
 error payloads are not copied into usage telemetry by default.
 
+A shell call is named by the command it ran — `npm`, `git`, `xcodebuild` —
+with the tool that ran it kept beside the name, so the usage screen can say
+which tool was slow or failing rather than listing every call as Bash.
+
+Machine load attributes to an agent everything the agent started — its
+shells, its node workers, the build a shell ran — found through the process
+tree, and names the heaviest kinds of process it runs (`node` ×19, `zsh` ×3)
+so the phone can say what an agent is doing, not only that it is. The
+executable path and the command line are read separately and joined by pid,
+because a path with a space in it (`~/Library/Application Support/Claude/…`)
+cannot be recovered from a command line split on whitespace.
+
+The number can be opened. Each agent's sample carries its heaviest forty
+processes one by one — pid, name, CPU, memory, and what the process was asked
+to do with the executable's own path and any secret removed — and the same
+load added up by chat. Claude Code hands every MCP server it starts the chat's
+id in `CLAUDE_CODE_SESSION_ID`, and `ps -E` shows a process's environment to
+its owner, so an agent's root process is named by its descendants; only that
+one variable is read, the answer is remembered for the root's lifetime, and a
+root that could not be named is asked about again after a minute. Each agent's
+own folders (`~/.claude`, `~/.codex`, `~/.cursor`, `~/.grok`, plus Claude's
+CLI cache) are measured with `du` in the background every ten minutes, top-level
+child by child, and carried on the sample; a sample never waits for `du`. The
+helper log says once in five minutes what each agent weighed, so a wrong
+number on the phone can be traced to the computer.
+
+A shell call is fingerprinted for Project policy by the command it runs —
+`git`, `rm`, `npm` — so a Project can allow one command and ask about another
+instead of deciding about the shell as a whole; a line with no command word
+is still plain `Shell`.
+
 ### One computer, whatever the network calls it
 
 The Mesh keys a computer by an identity written down once, on first use, in
@@ -229,11 +278,17 @@ Mesh show it. A `UserPromptSubmit` hook, installed beside the approval hook by
 `granttap setup`, adds the unread journal to the next prompt of the live
 session together with the Mesh brief — the other live Tasks in the Project,
 who is in the same file or module, the other side of the repository, and any
-question still unanswered — and names the MCP resource
-`granttap://mesh/{capability}/map`, one page of markdown with the whole
-Project: Tasks, who edits which module, the other side of each repository,
-dependencies, and what just happened. Background runs themselves receive
-nothing from the hook; the journal is kept for the session a person is in.
+question still unanswered — and names the MCP resource `granttap://mesh/map`,
+one page of markdown with the whole Project: Tasks, who edits which module,
+the other side of each repository, dependencies, and what just happened. That
+resource is listed, because Claude Code reads only listed resources, and it is
+scoped without a token: Claude Code starts one MCP server per chat and hands
+it the chat's id in `CLAUDE_CODE_SESSION_ID`, which nothing said over the
+connection can change. `granttap://mesh/current` serves the same chat's scoped
+state there. Other providers keep the tokened `granttap://mesh/{capability}`
+and `…/map` forms from an attributed `notify`. Background runs themselves
+receive nothing from the hook; the journal is kept for the session a person
+is in.
 
 ### Tool versions and updates from the phone
 
@@ -291,6 +346,24 @@ capability kind, so the phone shows what is actually in force rather than what
 was sent. Revision zero is a Project with no policy yet, and it is reported so
 the first policy can be written.
 
+A refused edit is answered, not swallowed. When a computer cannot apply a
+policy — the phone built it on a revision the computer no longer holds, the
+engine is not running, the policy is invalid — it sends
+`project.policy.rejected` with the reason and the revision it actually holds,
+then the policy it holds, so the phone can say what happened, keep the edit,
+and offer it again on top of the current revision. The helper log carries the
+same line. What the engine leaves null is sent as absent: the phone reads a
+status strictly, and a `null` where a field was optional was read as a wrong
+value and the whole status dropped.
+
+A shell call is fingerprinted by the command it runs (`git`, `rm`), a deploy or
+network call by the phrase that made it one (`git push`, `curl`), so a named
+rule can forbid pushing or deleting while the rest of the shell stays allowed.
+A commit or pull request whose command carries a co-author or "generated with"
+trailer is fingerprinted as `co-authorship`, its own row in the phone's Shell
+table, so a Project whose history is authored by people can deny the trailer
+and leave git alone.
+
 Evaluation happens in the provider hook before the action runs, with a deadline
 long enough for a busy machine to answer. A missed answer falls back to the
 legacy GrantTap gate rather than to a silent allow, and content never crosses

package/apps/bridge/src/attachment-store.ts

@@ -0,0 +1,89 @@
+/**
+ * Attachments that arrived ahead of their message.
+ *
+ * A photo is most of a message's bytes and all of its wait on a slow link:
+ * the phone sends it as soon as it is picked, sealed like everything else,
+ * and the message that follows names it instead of carrying it. Each one is
+ * kept on disk under its id, for the message or for two hours, whichever
+ * comes first, and read exactly once.
+ */
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { UserAttachment, UserAttachmentUpload } from "../../../packages/protocol/schema";
+import { configDir } from "./config";
+
+export const ATTACHMENT_TTL_MS = 2 * 60 * 60_000;
+
+function directory(): string {
+  const dir = join(configDir(), "attachments");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+function safeId(attachmentId: string): string | undefined {
+  const id = attachmentId.trim();
+  return /^[A-Za-z0-9_-]{1,180}$/.test(id) ? id : undefined;
+}
+
+/**
+ * Keep one attachment for the message that names it; drop the stale ones.
+ * The pairing room it came through is kept with it, so a message from
+ * another pairing cannot name it.
+ */
+export function storeAttachment(upload: UserAttachmentUpload, room?: string, now = Date.now()): boolean {
+  const id = safeId(upload.attachmentId);
+  if (!id) return false;
+  const dir = directory();
+  pruneAttachments(now, dir);
+  const record = {
+    name: upload.name, mimeType: upload.mimeType, data: upload.data, receivedAt: now,
+    ...(room ? { room } : {}),
+  };
+  writeFileSync(join(dir, `${id}.json`), JSON.stringify(record), { mode: 0o600 });
+  return true;
+}
+
+/** The attachment the message named, taken off disk; nothing when it never came. */
+export function takeAttachment(attachmentId: string, room?: string, now = Date.now()): UserAttachment | undefined {
+  const id = safeId(attachmentId);
+  if (!id) return undefined;
+  const path = join(directory(), `${id}.json`);
+  try {
+    const record = JSON.parse(readFileSync(path, "utf8")) as {
+      name?: unknown; mimeType?: unknown; data?: unknown; receivedAt?: unknown; room?: unknown;
+    };
+    // Another pairing's attachment is left where it is, for its own message.
+    if (typeof record.room === "string" && room != null && record.room !== room) return undefined;
+    rmSync(path, { force: true });
+    if (typeof record.receivedAt === "number" && now - record.receivedAt > ATTACHMENT_TTL_MS) return undefined;
+    if (typeof record.name !== "string" || typeof record.mimeType !== "string" || typeof record.data !== "string") {
+      return undefined;
+    }
+    return { name: record.name, mimeType: record.mimeType, data: record.data };
+  } catch {
+    return undefined;
+  }
+}
+
+export function pruneAttachments(now = Date.now(), dir = directory()): number {
+  let removed = 0;
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return 0;
+  }
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const path = join(dir, name);
+    try {
+      if (now - statSync(path).mtimeMs > ATTACHMENT_TTL_MS) {
+        rmSync(path, { force: true });
+        removed += 1;
+      }
+    } catch {
+      // Gone already.
+    }
+  }
+  return removed;
+}

package/apps/bridge/src/config/capability-policy.ts

@@ -52,11 +52,43 @@ export function setSessionShellAllowed(rawSessionId: string, allowed: boolean):
 }
 
 export type SessionCapabilityBlock = {
-  kind: "mcp" | "skill" | "cli";
+  kind: "mcp" | "skill" | "cli" | "session";
   name: string;
   reason: string;
 };
 
+/** What the agent reads when its chat is held from the phone. */
+export const PAUSED_SESSION_REASON =
+  "GrantTap paused this chat from the phone. Do not retry the call or work around it: stop and wait until the chat is resumed.";
+
+export function setSessionPaused(rawSessionId: string, paused: boolean): void {
+  const sessionId = capabilitySessionId(rawSessionId);
+  if (!sessionId) throw new TypeError("invalid session pause toggle");
+  const runtime = loadRuntimeConfig();
+  const held = new Set(runtime.pausedSessions);
+  if (paused) held.add(sessionId);
+  else held.delete(sessionId);
+  runtime.pausedSessions = [...held].sort();
+  saveRuntimeConfig(runtime);
+}
+
+export function isSessionPaused(rawSessionId: string | null | undefined): boolean {
+  const sessionId = capabilitySessionId(rawSessionId);
+  return sessionId != null && loadRuntimeConfig().pausedSessions.includes(sessionId);
+}
+
+/**
+ * A held chat is refused every tool, whatever the tool: the hold is the
+ * person's, and no capability rule of the chat's own may outrank it.
+ */
+export function pausedSessionBlock(
+  rawSessionId: string | null | undefined,
+): SessionCapabilityBlock | null {
+  return isSessionPaused(rawSessionId)
+    ? { kind: "session", name: "paused", reason: PAUSED_SESSION_REASON }
+    : null;
+}
+
 function mcpBlock(server: string): SessionCapabilityBlock {
   return {
     kind: "mcp",
@@ -140,6 +172,9 @@ export function blockedSessionCapability(
   const toolName = boundedIdentifier(rawToolName, 240);
   if (!sessionId || !toolName) return null;
   const runtime = loadRuntimeConfig();
+  if (runtime.pausedSessions.includes(sessionId)) {
+    return { kind: "session", name: "paused", reason: PAUSED_SESSION_REASON };
+  }
 
   const server = mcpServerFromTool(toolName);
   if (server && (runtime.sessionMcpDisabled[sessionId] ?? []).includes(server)) {

package/apps/bridge/src/config/runtime.ts

@@ -23,6 +23,8 @@ export type RuntimeConfig = {
   sessionMcpDisabled: Record<string, string[]>;
   sessionSkillsDisabled: Record<string, string[]>;
   sessionShellDisabled: string[];
+  /** Chats held from the phone: every tool call is refused until resumed. */
+  pausedSessions: string[];
   providerSettings: ProviderRuntimeSettings;
   meshEnabled: boolean;
   /** Absolute path to the separately distributed GrantTap Engine binary. */
@@ -41,6 +43,7 @@ const DEFAULT_RUNTIME: RuntimeConfig = {
   sessionMcpDisabled: {},
   sessionSkillsDisabled: {},
   sessionShellDisabled: [],
+  pausedSessions: [],
   providerSettings: { claude: true, codex: true, cursor: true, grok: true },
   meshEnabled: true,
   enginePath: null,
@@ -97,6 +100,15 @@ function parseDisabledCapabilities(raw: unknown): Record<string, string[]> {
   return result;
 }
 
+function parseSessionList(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  return [...new Set<string>(
+    (raw as unknown[])
+      .map(capabilitySessionId)
+      .filter((sessionId): sessionId is string => sessionId != null),
+  )];
+}
+
 /** Only an absolute path can be verified, so a relative one is not kept. */
 function parseEnginePath(raw: unknown): string | null {
   return typeof raw === "string" && raw.startsWith("/") && raw.length <= 1024 ? raw : null;
@@ -134,13 +146,8 @@ export function loadRuntimeConfig(): RuntimeConfig {
       autoAcceptPaused: raw.autoAcceptPaused === true,
       sessionMcpDisabled: parseDisabledCapabilities(raw.sessionMcpDisabled),
       sessionSkillsDisabled: parseDisabledCapabilities(raw.sessionSkillsDisabled),
-      sessionShellDisabled: Array.isArray(raw.sessionShellDisabled)
-        ? [...new Set<string>(
-            (raw.sessionShellDisabled as unknown[])
-              .map(capabilitySessionId)
-              .filter((sessionId): sessionId is string => sessionId != null),
-          )]
-        : [],
+      sessionShellDisabled: parseSessionList(raw.sessionShellDisabled),
+      pausedSessions: parseSessionList(raw.pausedSessions),
       providerSettings: parseProviderSettings(raw.providerSettings),
       meshEnabled: raw.meshEnabled !== false,
       enginePath: parseEnginePath(raw.enginePath),
@@ -154,6 +161,7 @@ export function loadRuntimeConfig(): RuntimeConfig {
       sessionMcpDisabled: {},
       sessionSkillsDisabled: {},
       sessionShellDisabled: [],
+      pausedSessions: [],
       providerSettings: { ...DEFAULT_RUNTIME.providerSettings },
       meshEnabled: true,
     };

package/apps/bridge/src/machine-load/disk-usage.ts

@@ -0,0 +1,144 @@
+/**
+ * What each agent keeps on the disk.
+ *
+ * Every agent has a folder of its own — `~/.claude`, `~/.codex` — that grows
+ * with transcripts, caches and installed skills and that nothing on the phone
+ * could see. The numbers come from `du`, which is slow on a folder with a
+ * year of transcripts, so a measurement is kept for ten minutes and refreshed
+ * in the background: a load sample never waits for it.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+export type DiskUsageEntry = { path: string; bytes: number };
+export type AgentDiskUsage = {
+  measuredAt: number;
+  totalBytes: number;
+  /** The heaviest places inside the agent's folders, heaviest first, then the rest as one. */
+  entries: DiskUsageEntry[];
+};
+
+export const DISK_TTL_MS = 10 * 60_000;
+const MAX_ENTRIES = 8;
+
+/** Where each agent keeps its state, relative to the home folder. */
+export const AGENT_LOCATIONS: Readonly<Record<string, readonly string[]>> = {
+  claude: [".claude", "Library/Caches/claude-cli-nodejs"],
+  codex: [".codex"],
+  cursor: [".cursor"],
+  grok: [".grok"],
+};
+
+export type DuRunner = (paths: string[]) => Promise<string>;
+
+const defaultDu: DuRunner = async (paths) => {
+  const { stdout } = await run("du", ["-sk", ...paths], {
+    encoding: "utf8", maxBuffer: 1_000_000, timeout: 120_000,
+  });
+  return String(stdout);
+};
+
+/** Parse `du -sk` lines (`<kilobytes>\t<path>`) into bytes by path. */
+export function parseDuOutput(stdout: string): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const line of stdout.split("\n")) {
+    const match = line.match(/^\s*(\d+)\s+(.+?)\s*$/);
+    if (match) out.set(match[2]!, Number(match[1]) * 1024);
+  }
+  return out;
+}
+
+/** A path shown as the person would type it: `~/.claude/projects`. */
+export function displayPath(path: string, home: string): string {
+  return path.startsWith(`${home}/`) ? `~/${path.slice(home.length + 1)}` : path === home ? "~" : path;
+}
+
+/** The heaviest entries, with everything else folded into one line. */
+export function summarize(
+  sizes: ReadonlyMap<string, number>, home: string, measuredAt: number,
+): AgentDiskUsage {
+  const sorted = [...sizes.entries()].sort((a, b) => b[1] - a[1]);
+  const totalBytes = sorted.reduce((sum, [, bytes]) => sum + bytes, 0);
+  const shown = sorted.slice(0, MAX_ENTRIES).map(([path, bytes]) => ({ path: displayPath(path, home), bytes }));
+  const rest = sorted.slice(MAX_ENTRIES).reduce((sum, [, bytes]) => sum + bytes, 0);
+  if (rest > 0) shown.push({ path: "…", bytes: rest });
+  return { measuredAt, totalBytes, entries: shown };
+}
+
+/** Measure one agent's folders now: each top-level child of each location. */
+export async function measureAgentDisk(
+  agent: string,
+  options: { home?: string; du?: DuRunner; now?: () => number } = {},
+): Promise<AgentDiskUsage | undefined> {
+  const home = options.home ?? homedir();
+  const du = options.du ?? defaultDu;
+  const targets: string[] = [];
+  for (const location of AGENT_LOCATIONS[agent] ?? []) {
+    const root = join(home, location);
+    if (!existsSync(root)) continue;
+    let children: string[] = [];
+    try {
+      children = readdirSync(root);
+    } catch {
+      continue;
+    }
+    if (children.length === 0) targets.push(root);
+    for (const child of children) targets.push(join(root, child));
+  }
+  if (targets.length === 0) return undefined;
+  try {
+    const sizes = parseDuOutput(await du(targets));
+    return summarize(sizes, home, (options.now ?? Date.now)());
+  } catch {
+    return undefined;
+  }
+}
+
+type CacheEntry = { usage?: AgentDiskUsage; measuredAt: number; pending?: Promise<void> };
+
+/**
+ * The last measurement per agent, refreshed in the background once it is
+ * ten minutes old. Returns nothing for an agent that has never been measured;
+ * the first sample kicks the measurement off and a later one carries it.
+ */
+export function createDiskUsageSampler(
+  options: { home?: string; du?: DuRunner; now?: () => number; ttlMs?: number } = {},
+) {
+  const now = options.now ?? Date.now;
+  const ttl = options.ttlMs ?? DISK_TTL_MS;
+  const cache = new Map<string, CacheEntry>();
+  const refresh = (agent: string): void => {
+    const entry = cache.get(agent) ?? { measuredAt: 0 };
+    if (entry.pending) return;
+    entry.pending = measureAgentDisk(agent, options)
+      .then((usage) => {
+        cache.set(agent, { usage: usage ?? entry.usage, measuredAt: now() });
+      })
+      .catch(() => {
+        cache.set(agent, { usage: entry.usage, measuredAt: now() });
+      });
+    cache.set(agent, entry);
+  };
+  return {
+    sample(agents: readonly string[]): Record<string, AgentDiskUsage> {
+      const out: Record<string, AgentDiskUsage> = {};
+      for (const agent of agents) {
+        if (!(agent in AGENT_LOCATIONS)) continue;
+        const entry = cache.get(agent);
+        if (!entry || now() - entry.measuredAt >= ttl) refresh(agent);
+        const usage = cache.get(agent)?.usage;
+        if (usage) out[agent] = usage;
+      }
+      return out;
+    },
+    /** For tests: wait for any measurement in flight. */
+    async settle(): Promise<void> {
+      await Promise.all([...cache.values()].map((entry) => entry.pending ?? Promise.resolve()));
+    },
+  };
+}

package/apps/bridge/src/machine-load/index.ts

@@ -3,6 +3,7 @@ import type {
   MachineLoad,
   SessionsStatus,
 } from "../../../../packages/protocol/schema";
+import { createDiskUsageSampler, type AgentDiskUsage } from "./disk-usage";
 import type { AgentProcessLoad } from "./process-sampler";
 import { sampleAgentProcesses } from "./process-sampler";
 import { providerScanCost, type ProviderScanSample } from "./scan-cost";
@@ -44,6 +45,7 @@ export function buildMachineLoad(input: {
   processes: Record<string, AgentProcessLoad>;
   self: MonitorSelfLoad;
   scanCost?: Record<string, ProviderScanSample>;
+  disk?: Record<string, AgentDiskUsage>;
   machine?: string;
   now?: number;
 }): MachineLoad {
@@ -84,6 +86,10 @@ export function buildMachineLoad(input: {
         processes: input.processes[agent]?.processes ?? 0,
         cpuPercent: input.processes[agent]?.cpuPercent ?? 0,
         memoryBytes: input.processes[agent]?.memoryBytes ?? 0,
+        topProcesses: input.processes[agent]?.groups ?? [],
+        processList: input.processes[agent]?.rows ?? [],
+        chats: input.processes[agent]?.chats ?? [],
+        ...(input.disk?.[agent] ? { disk: input.disk[agent] } : {}),
         sessions: sessionsByAgent.get(agent) ?? 0,
         scanMs: scanCost[agent]?.durationMs ?? 0,
         tokensRecent: tokensByAgent.get(agent) ?? 0,
@@ -103,13 +109,32 @@ type LoadRelay = {
   ): Promise<void>;
 };
 
+/** One line a person can grep in the helper log: what each agent weighed. */
+export function describeLoad(load: MachineLoad): string {
+  const agents = load.agents.map((agent) => {
+    const memory = `${Math.round(agent.memoryBytes / 1_000_000)} MB`;
+    const chats = agent.chats?.length ? ` in ${agent.chats.length} chats` : "";
+    return `${agent.agent} ${agent.processes} procs ${agent.cpuPercent}% ${memory}${chats}`;
+  });
+  return `[load] ${agents.length > 0 ? agents.join(" · ") : "no agent processes"}`;
+}
+
+export const LOAD_LOG_INTERVAL_MS = 5 * 60_000;
+
 /** Create one publisher so its monitor CPU baseline survives between reports. */
 export function createMachineLoadPublisher(dependencies: {
   sampleProcesses?: typeof sampleAgentProcesses;
   sampleSelf?: () => MonitorSelfLoad;
+  sampleDisk?: (agents: readonly string[]) => Record<string, AgentDiskUsage>;
+  /** Told about a sample now and then, so the helper log says what was measured. */
+  log?: (line: string) => void;
+  now?: () => number;
 } = {}) {
   const sampleProcesses = dependencies.sampleProcesses ?? sampleAgentProcesses;
   const sampleSelf = dependencies.sampleSelf ?? monitorLoadSampler();
+  const sampleDisk = dependencies.sampleDisk ?? createDiskUsageSampler().sample;
+  const now = dependencies.now ?? Date.now;
+  let loggedAt: number | undefined;
   let active: Promise<MachineLoad> | undefined;
   return (
     client: LoadRelay,
@@ -119,7 +144,12 @@ export function createMachineLoadPublisher(dependencies: {
     if (active) return active;
     active = (async () => {
       const processes = await sampleProcesses();
-      const load = buildMachineLoad({ status, processes, self: sampleSelf() });
+      const disk = sampleDisk(Object.keys(processes));
+      const load = buildMachineLoad({ status, processes, self: sampleSelf(), disk });
+      if (dependencies.log && (loggedAt === undefined || now() - loggedAt >= LOAD_LOG_INTERVAL_MS)) {
+        loggedAt = now();
+        dependencies.log(describeLoad(load));
+      }
       await client.send(load, "phone", { ttlMs: intervalMs * 3, reliable: false });
       return load;
     })().finally(() => {