granttap-mcp 0.8.106 → 0.8.109

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

@@ -34,3 +34,8 @@ Document staging for a native-only question keeps the file note inside its
 original answer envelope. The host's native question and all paired controllers
 therefore observe the same question item as answered; document paths remain
 available to the admitted turn. Ordinary chat text is unchanged.
+
+The bounded native admission deadline leaves time for the installed router’s
+ten-second owner discovery window. A five-second client cap otherwise reports
+healthy CLI conversations unavailable before discovery can finish. Missing-owner
+confirmation preserves CLI continuation; uncertain dispatch remains unreplayed.

package/apps/bridge/src/codex-desktop/connection.ts

@@ -17,7 +17,9 @@ export class DesktopConnection {
   private readonly deadline: number;
 
   constructor(path: string, timeoutMs: number) {
-    this.deadline = Date.now() + Math.min(5_000, timeoutMs);
+    // The native router allows ten seconds for owner discovery. Keep time
+    // for initialization, discovery and its routed response within the turn.
+    this.deadline = Date.now() + Math.min(30_000, timeoutMs);
     this.socket = connect(path);
     this.socket.on('error', () => this.close());
     this.socket.on('close', () => this.close());

package/apps/bridge/src/device-management/cache.ts

@@ -0,0 +1,73 @@
+import { lstat, readdir, rm, mkdir, open, unlink } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { readState, stableVersion } from '../runtime-updates/selection.mjs';
+import { configDir } from '../config/runtime/paths';
+
+type Category = { id: string; name: string; bytes: number; reclaimableBytes: number; paths: string[] };
+const exec = promisify(execFile);
+
+async function bytes(path: string): Promise<number> {
+  try {
+    const s = await lstat(path);
+    if (s.isSymbolicLink()) return 0;
+    if (!s.isDirectory()) return s.isFile() ? s.size : 0;
+    let total = 0;
+    for (const name of await readdir(path)) total += await bytes(join(path, name));
+    return total;
+  } catch { return 0; }
+}
+
+/** Only disposable indexes and obsolete immutable runtime packages. Never chats, credentials or projects. */
+export async function computerCache(root: string, directory = configDir(), processes?: string): Promise<Category[]> {
+  const graph = join(directory, 'repository-graph-cache');
+  const graphBytes = await bytes(graph);
+  const categories: Category[] = [{ id: 'graph', name: 'Project indexes', bytes: graphBytes, reclaimableBytes: graphBytes, paths: [graph] }];
+  const runtimeDirectory = join(directory, 'runtime-updates');
+  const state = readState(runtimeDirectory);
+  const protectedRoots = [root, state.root, state.previous?.root].filter((v): v is string => typeof v === 'string').map(v => resolve(v));
+  // If process inspection is unavailable, retain every runtime rather than guess.
+  if (processes == null) {
+    try { processes = (await exec('/bin/ps', ['-axo', 'command='], { maxBuffer: 8 * 1024 * 1024, timeout: 3_000 })).stdout; }
+    catch { processes = undefined; }
+  }
+  const runtime: Category = { id: 'runtimes', name: 'Previous MCP downloads', bytes: 0, reclaimableBytes: 0, paths: [] };
+  const versions = join(runtimeDirectory, 'versions');
+  for (const entry of await readdir(versions, { withFileTypes: true }).catch(() => [])) {
+    if (!entry.isDirectory() || !stableVersion(entry.name)) continue;
+    const path = join(versions, entry.name), packageRoot = join(path, 'node_modules', 'granttap-mcp');
+    const size = await bytes(path); runtime.bytes += size;
+    if (processes != null && !protectedRoots.includes(resolve(packageRoot)) && !processes.includes(path)) {
+      runtime.paths.push(path); runtime.reclaimableBytes += size;
+    }
+  }
+  categories.push(runtime);
+  return categories;
+}
+
+export async function clearComputerCache(root: string, directory = configDir()): Promise<number> {
+  const lockPath = join(directory, 'runtime-updates', 'install.lock');
+  await mkdir(join(directory, 'runtime-updates'), { recursive: true, mode: 0o700 });
+  let lock;
+  try { lock = await open(lockPath, 'wx', 0o600); }
+  catch { throw Error('An MCP install or cache cleanup is in progress. Wait for it to finish.'); }
+  try { return await removeCaches(root, directory); }
+  finally { await lock.close(); await unlink(lockPath); }
+}
+
+async function removeCaches(root: string, directory: string): Promise<number> {
+  // Re-read selection/process ownership immediately before each deletion.
+  const first = await computerCache(root, directory);
+  let removed = 0;
+  for (const category of first) for (const path of category.paths) {
+    const current = await computerCache(root, directory);
+    if (!current.some(c => c.paths.includes(path))) continue;
+    try {
+      if ((await lstat(path)).isSymbolicLink()) continue;
+      const size = await bytes(path);
+      await rm(path, { recursive: true, force: true }); removed += size;
+    } catch { /* A locked cache stays; remaining categories can still be cleared. */ }
+  }
+  return removed;
+}

package/apps/bridge/src/device-management/index.ts

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+import type { RelayClient } from '../../../../packages/core/relay-client';
+import type { DeviceManagementRequest, DeviceManagementResult } from '../../../../packages/protocol/schema';
+import { loadConfig, machineConfigPath } from '../config';
+import { observedComputerId } from '../mesh/identity/computer';
+import { clearComputerCache } from './cache';
+import { providerLogins } from './login';
+import { managementSnapshot, maintenanceIdle, restartProvider, restartRuntime, runtimeRoot, updateRuntime } from './maintenance';
+
+type Send = (result: DeviceManagementResult) => Promise<void>;
+type Entry = { fingerprint: string; result?: DeviceManagementResult; pending?: Promise<void>; at: number; ttl: number };
+const requests = new Map<string, Entry>();
+let mutating = false;
+export function deviceManagementWorkActive(): boolean { return [...requests.values()].some(entry => entry.pending != null); }
+
+export async function handleDeviceManagement(client: RelayClient, request: DeviceManagementRequest,
+  peer: string | undefined): Promise<boolean> {
+  if (!peer) return false;
+  if (!Number.isFinite(request.createdAt) || Math.abs(Date.now() - request.createdAt) > 120_000) return false;
+  const machine = loadConfig(machineConfigPath());
+  if (machine.role !== 'machine' || machine.room !== client.room
+    || (machine.peerPublicKey !== peer && !machine.extraPeerPublicKeys?.includes(peer))) return false;
+  const computerId = observedComputerId();
+  if (request.computerId != null && request.computerId !== computerId) return false;
+  // Sign-in material is deliberately non-durable and addressed only to the requesting paired controller.
+  const send: Send = value => client.sendToPeer(value, peer, { reliable: false, ttlMs: 60_000 });
+  const key = client.room + ':' + peer + ':' + request.requestId;
+  const fingerprint = createHash('sha256').update(JSON.stringify(request)).digest('hex');
+  for (const [k, value] of requests) if (Date.now() - value.at > value.ttl && !value.pending) requests.delete(k);
+  const previous = requests.get(key);
+  if (previous) {
+    if (previous.fingerprint !== fingerprint) return false;
+    if (previous.pending) await previous.pending;
+    if (previous.result) await send(previous.result);
+    return true;
+  }
+  if (requests.size >= 128) return false;
+  const entry: Entry = { fingerprint, at: Date.now(), ttl: request.action === 'status' ? 60_000 : 15 * 60_000 };
+  requests.set(key, entry);
+  const report: Send = async result => { entry.result = result; await send(result); };
+  entry.pending = execute(request, client.room + ':' + peer, computerId, report)
+    .catch(async () => { /* disconnected phones recover with a new status request */ })
+    .finally(() => { entry.pending = undefined; });
+  // Commands run independently of message delivery; repeated taps reuse their operation.
+  return true;
+}
+
+async function execute(request: DeviceManagementRequest, scope: string, computerId: string, send: Send): Promise<void> {
+  const base = { type: 'device.manage.result' as const, requestId: request.requestId, computerId,
+    action: request.action, agent: request.agent };
+  const result = (phase: DeviceManagementResult['phase'], message: string): DeviceManagementResult =>
+    ({ ...base, phase, message, createdAt: Date.now() });
+  const exclusive = request.action !== 'status' && !request.action.startsWith('provider-login');
+  if (exclusive && mutating) { await send(result('failed', 'Another computer maintenance action is in progress.')); return; }
+  if (exclusive) mutating = true;
+  try {
+    if (request.action.startsWith('provider-login')) {
+      const emit = (login: NonNullable<DeviceManagementResult['login']>) => {
+        const phase = login.phase === 'signed-in' || login.phase === 'cancelled' ? 'completed'
+          : login.phase === 'failed' || login.phase === 'expired' ? 'failed' : 'waiting';
+        void send({ ...result(phase, login.message), login }).catch(() => {});
+      };
+      const login = request.action === 'provider-login' ? providerLogins.start(scope, request.agent!, emit)
+        : request.action === 'provider-login-code' ? providerLogins.code(scope, request.agent!, request.operationId!, request.code!)
+        : providerLogins.cancel(scope, request.agent!, request.operationId ?? '');
+      await send({ ...result('waiting', login.message), login }); return;
+    }
+    await send(result('running', request.action === 'status' ? 'Reading this computer…' : 'Working on this computer…'));
+    let message = 'Computer status refreshed.';
+    if (request.action === 'clear-cache') {
+      if (!maintenanceIdle()) throw Error('Finish active requests and sign-in before clearing computer caches.');
+      const bytes = await clearComputerCache(runtimeRoot);
+      message = `Cleared ${(bytes / 1024 / 1024).toFixed(1)} MB of disposable cache.`;
+    } else if (request.action === 'runtime-update' || request.action === 'runtime-install') {
+      message = await updateRuntime();
+    } else if (request.action === 'provider-restart') {
+      message = await restartProvider(request.agent!, request.interruptActiveTasks);
+    } else if (request.action === 'runtime-restart') {
+      // The phone waits for a different runtimeEpoch, rather than treating this acknowledgement as a restart.
+      if (!maintenanceIdle()) throw Error('Finish active requests and sign-in before restarting MCP.');
+      await send(result('waiting', 'Restart requested. Waiting for MCP to reconnect…'));
+      restartRuntime(); return;
+    }
+    await send({ ...result('completed', message), snapshot: await managementSnapshot() });
+  } catch (error) {
+    await send(result('failed', error instanceof Error ? error.message.slice(0, 512) : 'This action failed on the computer.'));
+  } finally { if (exclusive) mutating = false; }
+}

package/apps/bridge/src/device-management/login.ts

@@ -0,0 +1,110 @@
+import { randomUUID } from 'node:crypto';
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { CodingAgent, ProviderLoginProgress } from '../../../../packages/protocol/schema';
+import { signalOwnedProcess } from '../reply/process';
+import { stripAnsi } from '../tools/version';
+import { allowedLoginURL, installedProvider, loginArguments, providerCommand, providerEnvironment } from './provider-command';
+
+type Flow = { scope: string; child: ChildProcess; progress: ProviderLoginProgress; output: string;
+  timer: NodeJS.Timeout; emit: (value: ProviderLoginProgress) => void };
+const terminal = new Set(['signed-in', 'failed', 'cancelled', 'expired']);
+
+/** Authentication stays in the provider CLI. Only its temporary browser challenge crosses E2EE. */
+export class ProviderLogins {
+  private flows = new Map<string, Flow>();
+  constructor(private launch = spawn, private command = providerCommand, private now = Date.now) {}
+
+  active(): boolean { return [...this.flows.values()].some(f => !terminal.has(f.progress.phase)); }
+
+  start(scope: string, agent: CodingAgent, emit: Flow['emit']): ProviderLoginProgress {
+    const existing = [...this.flows.values()].find(f => f.scope === scope && f.progress.agent === agent
+      && !terminal.has(f.progress.phase));
+    if (existing) { existing.emit = emit; return existing.progress; }
+    if (this.activeFor(agent)) throw Error('A sign-in for this provider is already open on another controller.');
+    const command = this.command(agent);
+    if (!installedProvider(command)) throw Error('Install this provider on the computer before signing in.');
+    this.prune();
+    if (this.flows.size >= 8) throw Error('Too many sign-in requests. Wait for an existing sign-in to expire.');
+    const progress: ProviderLoginProgress = { operationId: randomUUID(), agent, phase: 'starting',
+      expiresAt: this.now() + 10 * 60_000, message: 'Starting provider sign-in on this computer…' };
+    const child = this.launch(command, loginArguments(agent), { env: { ...providerEnvironment(), BROWSER: '/usr/bin/false' },
+      stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+    const timer = setTimeout(() => this.finish(progress.operationId, 'expired', 'Sign-in expired. Start again.'), 10 * 60_000);
+    timer.unref();
+    const flow: Flow = { scope, child, progress, output: '', timer, emit };
+    this.flows.set(progress.operationId, flow);
+    child.stdout?.setEncoding('utf8'); child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', value => this.output(flow, String(value)));
+    child.stderr?.on('data', value => this.output(flow, String(value)));
+    child.stdin?.on('error', () => this.finish(progress.operationId, 'failed', 'The provider closed sign-in input. Start again.'));
+    child.on('error', () => this.finish(progress.operationId, 'failed', 'The provider could not start sign-in.'));
+    child.on('close', code => this.finish(progress.operationId, code === 0 ? 'signed-in' : 'failed',
+      code === 0 ? 'Signed in on this computer.' : 'The provider did not complete sign-in. Start again.'));
+    return progress;
+  }
+
+  private activeFor(agent: CodingAgent): boolean {
+    return [...this.flows.values()].some(f => f.progress.agent === agent && !terminal.has(f.progress.phase));
+  }
+
+  private output(flow: Flow, value: string): void {
+    if (terminal.has(flow.progress.phase)) return;
+    flow.output = stripAnsi(flow.output + value).slice(-65_536);
+    const urls = flow.output.match(/https:\/\/[^\s<>"\u001b]+/g) ?? [];
+    const verificationURL = urls.map(url => allowedLoginURL(flow.progress.agent, url.replace(/[).,]+$/, ''))).find(Boolean);
+    if (!verificationURL) return;
+    const queryCode = new URL(verificationURL).searchParams.get('user_code');
+    const userCode = queryCode && /^[A-Z0-9-]{3,128}$/i.test(queryCode) ? queryCode
+      : /(?:user|device|verification|one.time|enter(?:\s+the)?)?\s*code\s*[:\n]\s*([A-Z0-9]{3,8}(?:-[A-Z0-9]{3,8})?)/i.exec(flow.output)?.[1]
+      ?? /\bcode\b[^\r\n]{0,100}\r?\n\s*([A-Z0-9]{3,8}(?:-[A-Z0-9]{3,8}){1,3})\b/i.exec(flow.output)?.[1];
+    const phase = flow.progress.agent === 'claude' ? 'awaiting-code' : 'awaiting-browser';
+    if (flow.progress.verificationURL === verificationURL && flow.progress.userCode === userCode && flow.progress.phase === phase) return;
+    flow.progress = { ...flow.progress, phase, verificationURL, userCode,
+      message: phase === 'awaiting-code' ? 'Open the provider, then paste its authorization code here.'
+        : 'Open the provider and approve sign-in. This computer will finish automatically.' };
+    flow.emit(flow.progress);
+  }
+
+  code(scope: string, agent: CodingAgent, operationId: string, code: string): ProviderLoginProgress {
+    const flow = this.owned(scope, agent, operationId);
+    if (flow.progress.phase !== 'awaiting-code') throw Error('This sign-in is not waiting for an authorization code.');
+    if (/[\r\n\u0000]/.test(code) || !code.trim() || code.length > 4_096) throw Error('Paste a single authorization code.');
+    flow.child.stdin?.write(code.trim() + '\n');
+    return flow.progress;
+  }
+
+  cancel(scope: string, agent: CodingAgent, operationId: string): ProviderLoginProgress {
+    const flow = this.owned(scope, agent, operationId);
+    this.finish(operationId, 'cancelled', 'Sign-in cancelled. Existing credentials were not removed.');
+    return flow.progress;
+  }
+
+  private owned(scope: string, agent: CodingAgent, operationId: string): Flow {
+    const flow = this.flows.get(operationId);
+    if (!flow || flow.scope !== scope || flow.progress.agent !== agent) throw Error('This sign-in belongs to another controller or has expired.');
+    if (this.now() >= flow.progress.expiresAt) this.finish(operationId, 'expired', 'Sign-in expired. Start again.');
+    if (terminal.has(flow.progress.phase)) throw Error('This sign-in has ended.');
+    return flow;
+  }
+
+  private finish(id: string, phase: ProviderLoginProgress['phase'], message: string): void {
+    const flow = this.flows.get(id);
+    if (!flow || terminal.has(flow.progress.phase)) return;
+    clearTimeout(flow.timer);
+    if (phase !== 'signed-in') {
+      signalOwnedProcess(flow.child, 'SIGTERM');
+      const kill = setTimeout(() => {
+        if (flow.child.exitCode == null && flow.child.signalCode == null) signalOwnedProcess(flow.child, 'SIGKILL');
+      }, 1_000);
+      kill.unref();
+    }
+    flow.output = '';
+    flow.progress = { operationId: id, agent: flow.progress.agent, phase, message, expiresAt: flow.progress.expiresAt };
+    flow.emit(flow.progress);
+  }
+
+  private prune(): void {
+    for (const [id, f] of this.flows) if (terminal.has(f.progress.phase)) this.flows.delete(id);
+  }
+}
+export const providerLogins = new ProviderLogins();

package/apps/bridge/src/device-management/maintenance.ts

@@ -0,0 +1,91 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { CodingAgent, DeviceManagementSnapshot } from '../../../../packages/protocol/schema';
+import { configDir } from '../config/runtime/paths';
+import { observedComputerId } from '../mesh/identity/computer';
+import { automaticUpdatesAllowed } from '../runtime-updates/preferences/storage.mjs';
+import { readState, runtimeVersion } from '../runtime-updates/selection.mjs';
+import { checkForRuntimeUpdate } from '../runtime-updates';
+import { binaryVersion } from '../tools/version';
+import { providerCommand, providerAuthentication, installedProvider, providerEnvironment } from './provider-command';
+import { computerCache } from './cache';
+import { providerLogins } from './login';
+import { ownedProviderProcesses, signalOwnedProcess } from '../reply/process';
+import { approvalsStatus } from '../approvals/state';
+
+export const runtimeRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+const runtimeEpoch = randomUUID();
+const agents: CodingAgent[] = ['grok', 'claude', 'codex', 'cursor'];
+
+export function runtimeRestartSupported(): boolean {
+  if (process.platform !== 'darwin' || !process.getuid || !runtimeRoot.includes('/node_modules/')) return false;
+  return ['com.granttap.monitor', 'com.granttap.mcp-http'].every(label => {
+    try {
+      const plist = readFileSync(join(homedir(), 'Library', 'LaunchAgents', label + '.plist'), 'utf8');
+      return plist.includes('<string>' + label + '</string>') && plist.includes('/granttap-mcp/bin/granttap-mcp.mjs')
+        && plist.includes('<key>KeepAlive</key>');
+    } catch { return false; }
+  });
+}
+
+export function maintenanceIdle(): boolean {
+  return !providerLogins.active() && approvalsStatus().pending.length === 0
+    && agents.every(agent => ownedProviderProcesses(providerCommand(agent)).length === 0);
+}
+
+export async function managementSnapshot(): Promise<DeviceManagementSnapshot> {
+  const directory = join(configDir(), 'runtime-updates');
+  const selected = readState(directory);
+  const providers = await Promise.all(agents.map(async agent => {
+    const command = providerCommand(agent), installed = installedProvider(command);
+    return { agent, installed, version: binaryVersion(command), authentication: await providerAuthentication(agent, command),
+      loginSupported: installed, restartSupported: installed,
+      activeRequests: ownedProviderProcesses(command).length };
+  }));
+  return { computerId: observedComputerId(), computerName: hostname(), observedAt: Date.now(),
+    runtimeVersion: runtimeVersion(runtimeRoot), runtimeEpoch, selectedRuntimeVersion: selected.version,
+    automaticUpdatesEnabled: automaticUpdatesAllowed(directory),
+    runtimeUpdateSupported: runtimeRoot.includes('/node_modules/'), runtimeRestartSupported: runtimeRestartSupported(),
+    cache: (await computerCache(runtimeRoot)).map(({ paths: _paths, ...category }) => category), providers };
+}
+
+export async function updateRuntime(): Promise<string> {
+  if (!runtimeRoot.includes('/node_modules/')) throw Error('This is a development checkout. Update the installed MCP instead.');
+  const candidate = await checkForRuntimeUpdate({ root: runtimeRoot, stateDirectory: join(configDir(), 'runtime-updates'),
+    idle: maintenanceIdle, manual: true });
+  return candidate ? 'MCP update verified and selected. Restart MCP to activate it.'
+    : 'No newer published MCP is available, or activation is waiting for active work. The current MCP is retained.';
+}
+
+/** A detached, fixed command survives the monitor exiting. No phone-supplied command or path is executed. */
+export function restartRuntime(): void {
+  if (!runtimeRestartSupported()) throw Error('Managed MCP services are not installed on this computer.');
+  if (!maintenanceIdle()) throw Error('Finish active requests, decisions and sign-in before restarting MCP.');
+  const domain = 'gui/' + process.getuid!();
+  const script = `setTimeout(() => { const { spawnSync } = require('node:child_process');
+    for (const label of ['com.granttap.mcp-http','com.granttap.monitor'])
+      spawnSync('/bin/launchctl',['kickstart','-k',${JSON.stringify(domain)}+'/'+label],{stdio:'ignore',timeout:10000}); }, 1200);`;
+  const child = spawn(process.execPath, ['-e', script], { detached: true, stdio: 'ignore' });
+  child.unref();
+}
+
+export async function restartProvider(agent: CodingAgent, interrupt = false): Promise<string> {
+  const command = providerCommand(agent);
+  if (!installedProvider(command)) throw Error('This provider is not installed on the computer.');
+  if (providerLogins.active()) throw Error('Finish sign-in before restarting a provider.');
+  const children = ownedProviderProcesses(command);
+  if (children.length && !interrupt) throw Error('This provider has active GrantTap requests. Confirm interruption before restarting.');
+  await Promise.all(children.map(child => new Promise<void>(resolve => {
+    const timer = setTimeout(() => { signalOwnedProcess(child, 'SIGKILL'); resolve(); }, 2_000);
+    child.once('close', () => { clearTimeout(timer); resolve(); });
+    (child as typeof child & { granttapStopped?: boolean }).granttapStopped = true;
+    signalOwnedProcess(child, 'SIGTERM');
+  })));
+  await promisify(execFile)(command, ['--version'], { env: providerEnvironment(), timeout: 15_000, maxBuffer: 16_384 });
+  return 'A fresh provider CLI started successfully. The next message starts a new GrantTap connection to it.';
+}

package/apps/bridge/src/device-management/provider-command.ts

@@ -0,0 +1,89 @@
+import { accessSync, constants, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import type { CodingAgent } from '../../../../packages/protocol/schema';
+import { executableOnPath, resolveClaudeBinary } from '../providers/claude-bin';
+import { resolveCodexBinary } from '../providers/codex-bin';
+import { resolveGrokBinary } from '../providers/grok-bin';
+import { resolveCursorAgentBin } from '../reply/process/cursor-agent-bin';
+
+export function providerCommand(agent: CodingAgent): string {
+  switch (agent) {
+    case 'claude': return resolveClaudeBinary().path;
+    case 'codex': return resolveCodexBinary();
+    case 'grok': return resolveGrokBinary();
+    case 'cursor': return resolveCursorAgentBin();
+  }
+}
+
+export function providerEnvironment(): NodeJS.ProcessEnv {
+  const node = dirname(process.execPath);
+  return { ...process.env, PATH: [node, process.env.PATH ?? ''].join(delimiter),
+    NO_COLOR: '1', FORCE_COLOR: '0', DISABLE_AUTOUPDATER: '1', GROK_DISABLE_AUTOUPDATER: '1' };
+}
+
+export function loginArguments(agent: CodingAgent): string[] {
+  if (agent === 'grok' || agent === 'codex') return ['login', '--device-auth'];
+  return agent === 'claude' ? ['auth', 'login'] : ['login'];
+}
+
+/** Only known provider entry points are offered; loopback callbacks and token URLs are never relayed. */
+export function allowedLoginURL(agent: CodingAgent, value: string): string | undefined {
+  try {
+    const u = new URL(value);
+    if (u.protocol !== 'https:' || u.username || u.password) return;
+    if ([...u.searchParams.keys()].some(k => /^(access_token|refresh_token|id_token|client_secret)$/i.test(k))) return;
+    const domains: Record<CodingAgent, string[]> = {
+      grok: ['grok.com', 'x.ai'], codex: ['openai.com', 'chatgpt.com'],
+      claude: ['claude.ai', 'claude.com', 'anthropic.com'], cursor: ['cursor.com', 'cursor.sh'],
+    };
+    if (domains[agent].some(domain => u.hostname === domain || u.hostname.endsWith('.' + domain))) return u.href;
+    if (agent === 'grok' && process.env.GROK_OIDC_ISSUER
+      && new URL(process.env.GROK_OIDC_ISSUER).hostname === u.hostname) return u.href;
+  } catch { /* malformed or non-provider output */ }
+}
+
+export function installedProvider(command: string): boolean {
+  try { accessSync(command.includes('/') ? command : executableOnPath(command, process.env) ?? command, constants.X_OK); return true; } catch { return false; }
+}
+
+type Authentication = 'signed-in' | 'signed-out' | 'unknown' | 'not-installed';
+
+/** Presence is reported separately from a successful agent turn; credentials never leave their native store. */
+export async function providerAuthentication(agent: CodingAgent, command = providerCommand(agent)): Promise<Authentication> {
+  if (!installedProvider(command)) return 'not-installed';
+  if (agent === 'grok') {
+    try {
+      const file = join(process.env.GRANTTAP_GROK_DIR ?? process.env.GROK_HOME ?? join(homedir(), '.grok'), 'auth.json');
+      const data = JSON.parse(readFileSync(file, 'utf8'));
+      return Object.values(data).some(value => value && typeof value === 'object'
+        && typeof (value as { key?: unknown }).key === 'string') ? 'signed-in' : 'signed-out';
+    } catch { return process.env.XAI_API_KEY ? 'signed-in' : 'unknown'; }
+  }
+  const args = agent === 'claude' ? ['auth', 'status', '--json']
+    : agent === 'codex' ? ['login', 'status'] : ['status'];
+  return new Promise(resolve => {
+    let done = false, output = '';
+    const child = spawn(command, args, { env: providerEnvironment(), stdio: ['ignore', 'pipe', 'pipe'] });
+    const finish = (value: Authentication) => {
+      if (done) return; done = true; clearTimeout(timer); resolve(value);
+    };
+    const timer = setTimeout(() => { child.kill('SIGTERM'); finish('unknown'); }, 8_000);
+    child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
+    child.stdout.on('data', chunk => { output = (output + chunk).slice(-16_384); });
+    child.stderr.on('data', chunk => { output = (output + chunk).slice(-16_384); });
+    child.on('error', () => finish('unknown'));
+    child.on('close', code => {
+      if (agent === 'claude') {
+        try {
+          const value = JSON.parse(output);
+          if (typeof value.loggedIn === 'boolean') return finish(value.loggedIn ? 'signed-in' : 'signed-out');
+        } catch { /* an old CLI can only provide unknown status */ }
+      }
+      if (agent === 'codex') return finish(code === 0 ? 'signed-in' : /not logged|not signed/i.test(output) ? 'signed-out' : 'unknown');
+      if (/not logged|not signed|unauthenticated/i.test(output)) return finish('signed-out');
+      finish(code === 0 && /logged in|authenticated|signed in/i.test(output) ? 'signed-in' : 'unknown');
+    });
+  });
+}

package/apps/bridge/src/engine/README.md

@@ -29,7 +29,8 @@ Explicit Graph builds also invoke the Engine's `graph.analyze_project` for two
 to eight admitted local repositories. The projection labels these shared static
 contracts and keeps their runtime destination unverified. They do not become
 verified Backbone dependencies or merge Project grants. The Apple Silicon
-artifact pins Engine 0.1.4 with Weavatrix 2.17.5 and injective package import identities; unsupported Engine operations
+artifact pins Engine 0.1.5 with Weavatrix 2.17.5, injective package import identities
+and per-file function extent reuse during metrics analysis; unsupported Engine operations
 leave this analysis unavailable. See `runtime/project-relationships/README.md`.
 
 Claude, Codex, and Cursor hooks can evaluate the engine's local Project

package/apps/bridge/src/engine/distribution/artifacts.ts

@@ -8,8 +8,8 @@ export type EngineArtifact = {
 
 /** Release hashes are part of the reviewed MCP, never supplied by a remote manifest. */
 export const ENGINE_ARTIFACTS: readonly EngineArtifact[] = [
-  { version: "0.1.4", platform: "darwin", arch: "arm64",
-    sha256: "0eda3a158b84305802342cff77af7a7c24fecd5eafb25fad394e61edad53fbec", bytes: 12202064 },
+  { version: "0.1.5", platform: "darwin", arch: "arm64",
+    sha256: "bd16babf11fd3d7e65b9713797b977deba1670ba41230a0e6607ce938b847455", bytes: 12202080 },
   { version: "0.1.2", platform: "darwin", arch: "x64",
     sha256: "b3235a15936a77ec323d5ecbc54a0bc19994fe6e5a36044da964b68524b4c1dd", bytes: 13944984 },
   { version: "0.1.2", platform: "linux", arch: "x64",

package/apps/bridge/src/mesh/restrictions/check.ts

@@ -1,6 +1,7 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import type { ProjectRestrictionSet } from "../../../../../packages/protocol/schema";
+import { hasGuidance } from "./guidance";
 import { evaluateContent, type RestrictionViolation } from "./evaluate";
 
 const SKIP_DIR = new Set([
@@ -62,12 +63,12 @@ function isTextish(name: string): boolean {
 }
 
 export function restrictionSummary(restrictions: ProjectRestrictionSet | undefined): string {
-  if (!restrictions || restrictions.rules.length === 0) return "No restrictions";
+  if (!restrictions || (restrictions.rules.length === 0 && !hasGuidance(restrictions.guidance))) return "No restrictions";
   const count = restrictions.rules.length;
   const scope = restrictions.scope === "sync_from_repo"
     ? "from the repository"
     : restrictions.scope === "project_and_repo"
       ? "Project and repository"
       : "this Project";
-  return `${count} rule${count === 1 ? "" : "s"} · ${scope}`;
+  return `${count} rule${count === 1 ? "" : "s"}${hasGuidance(restrictions.guidance) ? " + agent guidance" : ""} · ${scope}`;
 }

package/apps/bridge/src/mesh/restrictions/cli.ts

@@ -1,3 +1,4 @@
+import { hasGuidance } from "./guidance";
 import { inspectRepository } from "../catalog";
 import { computerId } from "../identity/computer";
 import { localMeshStore } from "../local-remote/local";
@@ -19,7 +20,10 @@ export function runRestrictionsCheck(root: string): RestrictionsCheckResult {
   const restrictions = readRepoRestrictions(root, projectId ?? "ci")
     ?? (projectId ? loadRestrictions(projectId) : undefined);
 
+  const advisory = hasGuidance(restrictions?.guidance)
+    ? "Agent guidance is advisory and not machine-checked by this command.\n" : "";
   if (!restrictions || restrictions.rules.length === 0) {
+    if (advisory) return { exitCode: 0, stdout: advisory, stderr: "" };
     return { exitCode: 0, stdout: "GrantTap restrictions: none configured.\n", stderr: "" };
   }
 
@@ -27,7 +31,7 @@ export function runRestrictionsCheck(root: string): RestrictionsCheckResult {
   if (violations.length === 0) {
     return {
       exitCode: 0,
-      stdout: `GrantTap restrictions: ${restrictions.rules.length} rule(s) clean.\n`,
+      stdout: `GrantTap restrictions: ${restrictions.rules.length} rule(s) clean.\n${advisory}`,
       stderr: "",
     };
   }
@@ -36,5 +40,5 @@ export function runRestrictionsCheck(root: string): RestrictionsCheckResult {
     .map((item) => `${item.effect.toUpperCase()} ${item.reason}\n`)
     .join("");
   const denied = violations.some((item) => item.effect === "deny");
-  return { exitCode: denied ? 1 : 0, stdout: "", stderr };
+  return { exitCode: denied ? 1 : 0, stdout: advisory, stderr };
 }

package/apps/bridge/src/mesh/restrictions/evaluate.ts

@@ -38,7 +38,7 @@ export function functionLineCounts(source: string): number[] {
 
 function unparsedFunctionForm(filePath: string, content: string): boolean {
   const extension = filePath.split(".").at(-1)?.toLowerCase();
-  if (extension === "py") return /^\s*(?:async\s+)?def\s+\w+/m.test(content);
+  if (["py", "rb"].includes(extension ?? "")) return /^\s*(?:async\s+)?def\s+\w+/m.test(content);
   if (!["ts", "tsx", "js", "jsx", "mjs", "cjs"].includes(extension ?? "")) return false;
   if (/=>/.test(content)) return true;
   return /^\s*(?:async\s+)?(?!(?:if|while|for|switch|catch)\b)[A-Za-z_$][\w$]*\s*\([^;\n]*\)\s*\{/m

package/apps/bridge/src/mesh/restrictions/guidance/README.md

@@ -0,0 +1,27 @@
+# Project coding guidance
+
+`projectGuidancePrompt(projectId, text)` is the public prompt boundary. It loads
+only the accepted local restriction set for the named Project, adds its
+advisory principles, architecture preference, design targets and exact Markdown,
+then preserves the original request. Empty guidance is a no-op. It never edits
+provider configuration or raises tool permissions.
+
+Continuation delivery calls this through the existing routing prompt for all
+supported providers. New phone Tasks use the Project returned by validated
+workspace admission. Transfer starts use the existing Task's Project scope.
+A loose cwd or unvalidated message Project ID does not supply instruction scope.
+Original delivery identities, origin records and run journals retain the person's
+original request; attached guidance is not a separately delivered prompt.
+
+The optional protocol field is backward compatible for reading old sets. A Mac
+that predates this contract must be upgraded before a phone sends guidance;
+strict old protocol receivers cannot honestly acknowledge a field they reject.
+The canonical policy receipt proves local acceptance, not semantic compliance.
+
+The private store and `.granttap/restrictions.json` export preserve all guidance.
+The explicit repository check reports guidance as advisory and never claims to
+machine-check Clean Code, architecture, class or parameter targets. Existing
+write checks own numeric enforcement; Ruby/Python function forms outside the
+brace scanner request parser review.
+
+License: GrantTap Commercial Source License, in the repository-root `LICENSE`.