granttap-mcp 0.7.1 → 0.7.6

package/README.md

@@ -51,12 +51,11 @@ 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.
 
-Both directions are scoped to the calling execution. The provider hook already
-runs inside the agent's own session and sees the exact call, so GrantTap
-attributes every `notify` to the session that really made it and publishes the
-event only for that execution — a model that learned another session's id
-cannot act in its name. `granttap://mesh/current` therefore carries no Project
-data: an attributed call returns this execution's opaque
+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
+session that really made it and publishes the event only for that execution —
+a model that learned another session's id cannot act in its name.
+`granttap://mesh/current` therefore carries no Project data: an attributed call returns this execution's opaque
 `granttap://mesh/<capability>` URI, and only that URI serves its Project, Task,
 owners, claims, dependencies, and relevant events. Ownership transfer stays out
 of the tool surface entirely: `HANDOFF_ACCEPTED` and `HANDOFF_REJECTED` are
@@ -66,8 +65,11 @@ The first executable handoff path is Claude Code ↔ Codex across linked
 computers. GrantTap builds a bounded Task Capsule from explicit task/git facts,
 requires local phone authorization, creates a separate target branch/worktree,
 starts the target execution, and returns a receipt bound to the exact capsule.
-Cursor and Grok Build use the same provider-neutral schema and discovery model;
-unsupported remote-start paths fail closed instead of claiming parity.
+Cursor uses the same provider-neutral schema and trusted caller attribution.
+Grok Build remains Experimental and observable where available, but does not
+yet expose a trusted caller hook, so agent-authored scoped Mesh events are not
+offered for it. Unsupported remote-start paths fail closed instead of claiming
+parity.
 
 A capsule carries facts, not files. A handoff from a checkout with uncommitted
 changes is refused — "This task has uncommitted changes. Commit or checkpoint

package/SECURITY.md

@@ -20,6 +20,24 @@ credential used for authenticated WebSocket and APNs registration.
 Provider credentials remain in each provider's own local authentication flow.
 GrantTap does not send them to the relay.
 
+Installed Claude Code, Codex, and Cursor hooks deny direct agent tool calls
+that name GrantTap's local pairing, key, or policy files, including calls that
+would otherwise be auto-accepted or run in provider bypass mode. The denial
+covers the config directory itself, any glob over it, and every file not on a
+short access-mode list, so a file added later is protected the day it appears.
+Only helper logs and bounded runtime diagnostics are agent-readable, and they
+remain read-only. Raw Mesh state and hook-attribution records are never exposed
+to agent tools; `workspaces/` and `worktrees/` remain normal editable agent
+workspace. The guard denies only what it positively recognised as a path into
+that directory, and a fault inside the guard itself is printed and allowed
+through instead of blocking every tool call on the machine: an outage of every
+agent is a worse failure than the file it was watching. This is
+best-effort self-protection, not an operating-system security boundary: a
+process running as the same macOS user can use an unobserved tool, shell
+obfuscation, or direct filesystem access outside those hooks. Protect the user
+account and disk; use a trusted terminal for intentional maintenance. Moving
+remaining local secret material into Keychain is the stronger future boundary.
+
 ## Cryptographic boundary
 
 - Every computer pairing is generated locally with unique Curve25519 keys.
@@ -67,6 +85,10 @@ acceptance includes a SHA-256 receipt over a canonical capsule and the source,
 target, Task identity, and acceptance time. Stale claims expire, replayed event
 IDs are ignored, and destination routing is explicit.
 
+Repository remotes included in Project snapshots are reduced to lowercase
+host/path form. Userinfo, passwords or tokens, query strings, fragments, and
+local-path remotes are never persisted as `baseRemote`.
+
 ## Runtime controls
 
 Provider hooks enforce policy on the computer. Global provider deny always
@@ -87,5 +109,16 @@ expiry, actor, Project scope, and operation, and a revoked or disabled endpoint
 fails closed. Invite creation, actor enablement, Project scope, and revocation
 stay in the iPhone UI and the trusted CLI, never in a model-callable tool.
 
+## Local helper installation
+
+The background helper is a user LaunchAgent, and `launchctl bootstrap` replaces
+whatever job already holds that label. GrantTap therefore refuses to load a
+LaunchAgent whose plist lives under the operating system's temporary directory:
+a test, probe, or agent run with a temporary `HOME` must never evict the
+installed helper and leave launchd restarting a program whose files were already
+cleaned up. Only `GRANTTAP_TEST_FAKE_LAUNCHCTL=1`, which states that `launchctl`
+on `PATH` is a stub, lifts that refusal.
+
+
 Relay vulnerabilities should be reported through the
 [GrantTap relay advisory form](https://github.com/sergii-ziborov/granttap-relay/security/advisories/new).

package/apps/bridge/src/bin/claude-hook.ts

@@ -25,6 +25,7 @@ import {
 } from "../config";
 import { recordAttributedCall } from "../mesh/call-scope";
 import { classifyAction } from "../policy";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -50,6 +51,18 @@ async function main(): Promise<void> {
     return;
   }
 
+  const protectedAccess = protectedGrantTapAccess(input.tool_name, input.tool_input);
+  if (protectedAccess) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: protectedAccess.reason,
+      },
+    }));
+    return;
+  }
+
   if (!isProviderEnabled("claude")) return;
 
   // Attribute this exact GrantTap call to the session that made it. The MCP

package/apps/bridge/src/bin/codex-hook.ts

@@ -25,6 +25,7 @@ import {
 } from "../config";
 import { recordAttributedCall } from "../mesh/call-scope";
 import { classifyAction } from "../policy";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -51,6 +52,12 @@ async function main(): Promise<void> {
     return;
   }
 
+  const protectedAccess = protectedGrantTapAccess(input.tool_name, input.tool_input);
+  if (protectedAccess) {
+    process.stdout.write(denyOutput(protectedAccess.reason));
+    return;
+  }
+
   if (!isProviderEnabled("codex")) return;
 
   // See claude-hook.ts: the MCP server trusts this attribution, never the model.

package/apps/bridge/src/bin/codex-policy-hook.ts

@@ -2,6 +2,7 @@
 /** Deny-only Codex PreToolUse policy for exact per-chat capability switches. */
 import type { HookInput } from "../adapters";
 import { blockedSessionCapability, isProviderEnabled } from "../config";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -10,13 +11,24 @@ async function readStdin(): Promise<string> {
 }
 
 async function main(): Promise<void> {
-  if (!isProviderEnabled("codex")) return;
   let input: HookInput;
   try {
     input = JSON.parse(await readStdin()) as HookInput;
   } catch {
     return;
   }
+  const protectedAccess = protectedGrantTapAccess(input.tool_name, input.tool_input);
+  if (protectedAccess) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: protectedAccess.reason,
+      },
+    }));
+    return;
+  }
+  if (!isProviderEnabled("codex")) return;
   const blocked = blockedSessionCapability(
     input.session_id,
     input.tool_name,

package/apps/bridge/src/bin/cursor-hook.ts

@@ -16,6 +16,7 @@ import {
   shouldAutoAcceptCursorShell,
 } from "../config";
 import { cursorRootSessionId } from "../sessions/cursor";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -31,6 +32,14 @@ function nativeAsk(message: string): void {
   }));
 }
 
+function deny(message: string): void {
+  process.stdout.write(JSON.stringify({
+    permission: "deny", continue: false,
+    user_message: message, agent_message: message,
+    userMessage: message, agentMessage: message,
+  }));
+}
+
 async function main(): Promise<void> {
   let input: CursorHookInput;
   try {
@@ -39,6 +48,13 @@ async function main(): Promise<void> {
     nativeAsk("GrantTap could not read this shell call; use Cursor approval.");
     return;
   }
+  const protectedAccess = protectedGrantTapAccess(
+    input.tool_name, input.tool_input, input.command,
+  );
+  if (protectedAccess) {
+    deny(protectedAccess.reason);
+    return;
+  }
   if (!isProviderEnabled("cursor")) {
     nativeAsk("GrantTap monitoring for Cursor is disabled; use Cursor approval.");
     return;
@@ -51,14 +67,7 @@ async function main(): Promise<void> {
     input.tool_input ?? { command: input.command },
   );
   if (blocked) {
-    process.stdout.write(JSON.stringify({
-      permission: "deny",
-      continue: false,
-      user_message: blocked.reason,
-      agent_message: blocked.reason,
-      userMessage: blocked.reason,
-      agentMessage: blocked.reason,
-    }));
+    deny(blocked.reason);
     return;
   }
   if (!sessionId || isGatingSkipped(sessionId)) {

package/apps/bridge/src/bin/cursor-mcp-hook.ts

@@ -19,6 +19,7 @@ import {
 } from "../cursor-mcp-policy";
 import { recordAttributedCall } from "../mesh/call-scope";
 import { cursorRootSessionId } from "../sessions/cursor";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -42,6 +43,17 @@ async function main(): Promise<void> {
     nativeAsk("GrantTap could not correlate this MCP call; use Cursor approval.");
     return;
   }
+  const protectedAccess = protectedGrantTapAccess(
+    input.tool_name, input.tool_input, input.command,
+  );
+  if (protectedAccess) {
+    process.stdout.write(JSON.stringify({
+      permission: "deny",
+      user_message: protectedAccess.reason,
+      agent_message: protectedAccess.reason,
+    }));
+    return;
+  }
   if (!isProviderEnabled("cursor")) {
     nativeAsk("GrantTap monitoring for Cursor is disabled; use Cursor approval.");
     return;

package/apps/bridge/src/install.ts

@@ -23,6 +23,7 @@ import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import type { CodingAgent } from "../../../packages/protocol/schema";
+import { refusesLiveLaunchd } from "./launchd-safety";
 import { configDir } from "./config";
 
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
@@ -299,18 +300,15 @@ export function inspectMonitorHelper(): MonitorIntegrationStatus {
   return { configured: true, running: active.status === 0 };
 }
 
-/** Absolute pin for this machine — LaunchAgent must never drift to granttap-mcp + Cursor helpers. */
-export const DEFAULT_PINNED_MONITOR_BIN = "/Users/serhiirihgt/dev/nodvox/bin/granttap.mjs";
-export const DEFAULT_PINNED_MONITOR_ROOT = "/Users/serhiirihgt/dev/nodvox";
-
-export function pinnedMonitorBin(): string {
+/** Optional explicit development pin; public installs use this package by default. */
+export function pinnedMonitorBin(): string | undefined {
   const override = process.env.GRANTTAP_PINNED_MONITOR_BIN?.trim();
-  return override && override.length > 0 ? override : DEFAULT_PINNED_MONITOR_BIN;
+  return override && override.length > 0 ? override : undefined;
 }
 
-export function pinnedMonitorRoot(): string {
+export function pinnedMonitorRoot(): string | undefined {
   const override = process.env.GRANTTAP_PINNED_MONITOR_ROOT?.trim();
-  return override && override.length > 0 ? override : DEFAULT_PINNED_MONITOR_ROOT;
+  return override && override.length > 0 ? override : undefined;
 }
 
 function xml(value: string): string {
@@ -326,15 +324,12 @@ export function isCursorHelperNode(nodePath: string): boolean {
   return nodePath.includes("Cursor.app") || nodePath.includes("/helpers/node");
 }
 
-/** True when plist already runs the nodvox monitor without Cursor/mcp clobber. */
+/** True when a plist uses the caller's explicit development monitor pin. */
 export function isNodvoxPinnedPlist(contents: string): boolean {
   const pin = pinnedMonitorBin();
-  const hasNodvoxBin =
-    contents.includes(pin) ||
-    contents.includes("/dev/nodvox/bin/granttap.mjs") ||
-    contents.includes("/nodvox/bin/granttap.mjs");
+  if (!pin) return false;
   return (
-    hasNodvoxBin &&
+    contents.includes(pin) &&
     !contents.includes("granttap-mcp.mjs") &&
     !contents.includes("Cursor.app") &&
     !contents.includes("/helpers/node")
@@ -364,8 +359,8 @@ export function resolveMonitorNodeBin(): string | null {
  * Keep task/session sync alive without a terminal or a newly opened MCP chat.
  *
  * Hard rules:
- * - Never overwrite a healthy nodvox-pinned LaunchAgent with granttap-mcp / Cursor helpers.
- * - When `/Users/serhiirihgt/dev/nodvox/bin/granttap.mjs` exists, pin to it (not this package's bin).
+ * - Never overwrite a healthy explicitly pinned LaunchAgent with package / Cursor helpers.
+ * - Development pins are opt-in through `GRANTTAP_PINNED_MONITOR_BIN`.
  * - Never put Cursor.app helpers/node in ProgramArguments.
  */
 export function installMonitorHelper(): InstallResult {
@@ -383,11 +378,12 @@ export function installMonitorHelper(): InstallResult {
     }
   }
 
-  const pinBin = pinnedMonitorBin();
-  const usePin = existsSync(pinBin);
-  const executable = usePin ? pinBin : join(repoRoot, "bin", "granttap-mcp.mjs");
-  const workingDirectory = usePin
-    ? pinnedMonitorRoot()
+  const explicitPin = pinnedMonitorBin();
+  const pinBin = explicitPin && existsSync(explicitPin) ? explicitPin : undefined;
+  const usePin = pinBin != null;
+  const executable = pinBin ?? join(repoRoot, "bin", "granttap-mcp.mjs");
+  const workingDirectory = pinBin
+    ? (pinnedMonitorRoot() ?? dirname(pinBin))
     : (process.env.GRANTTAP_MONITOR_CWD ?? process.cwd());
   const nodeBin = resolveMonitorNodeBin();
   if (!nodeBin) {
@@ -473,6 +469,8 @@ export function installMonitorHelper(): InstallResult {
     return { status: already ? "already" : "installed", detail };
   }
 
+  const sandboxed = refusesLiveLaunchd(path);
+  if (sandboxed) return { status: "manual", detail: sandboxed };
   const uid = process.getuid?.();
   if (uid == null) return { status: "manual", detail: `${path}: could not determine user id` };
   const domain = `gui/${uid}`;

package/apps/bridge/src/launchd-safety.ts

@@ -0,0 +1,53 @@
+/**
+ * A LaunchAgent is user-global: `launchctl bootstrap` replaces whatever job
+ * already holds that label. A sandboxed run — a test, a probe, anything with a
+ * temporary `HOME` or config directory — therefore evicts the real GrantTap
+ * helper and installs a job whose plist, node modules, and log file vanish with
+ * the temporary directory. launchd then keeps restarting a program it can no
+ * longer load, which reads to the user as GrantTap crashing in a loop.
+ *
+ * A real installation always writes into the user's own Library. A plist under
+ * the operating system's temporary directory is a sandbox by definition, so it
+ * never reaches the live domain.
+ */
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve, sep } from "node:path";
+
+const TEMPORARY_ROOTS = ["/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
+
+function canonical(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+export function insideTemporaryDirectory(path: string): boolean {
+  if (process.env.GRANTTAP_TEST_FAKE_LAUNCHCTL === "1") return false;
+  const target = canonical(path);
+  const roots = new Set<string>();
+  for (const root of [tmpdir(), ...TEMPORARY_ROOTS]) {
+    roots.add(resolve(root));
+    roots.add(canonical(root));
+  }
+  return [...roots].some((root) => target === root || target.startsWith(root + sep));
+}
+
+export const SANDBOXED_LAUNCH_AGENT_DETAIL =
+  "refusing to load a LaunchAgent from a temporary directory; "
+  + "a sandboxed run must not replace the installed GrantTap helper";
+
+/**
+ * Whether this plist may be handed to `launchctl` in the live user domain.
+ *
+ * `GRANTTAP_TEST_FAKE_LAUNCHCTL=1` states that the `launchctl` on PATH is a
+ * stub, so the whole install path can be exercised without a live domain to
+ * damage. It is an explicit, greppable opt-in; nothing in the shipped product
+ * sets it.
+ */
+export function refusesLiveLaunchd(path: string): string | null {
+  if (process.env.GRANTTAP_TEST_FAKE_LAUNCHCTL === "1") return null;
+  return insideTemporaryDirectory(path) ? `${path}: ${SANDBOXED_LAUNCH_AGENT_DETAIL}` : null;
+}

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

@@ -9,12 +9,13 @@ identity without replacing provider-native session discovery. `store.ts`
 deduplicates replayed events and expires stale claims. `capsule.ts` reads only
 explicit git and task facts; transcripts and hidden reasoning are never copied.
 `worktree.ts` creates a separate target branch/worktree before Claude Code or
-Codex is started. The provider abstraction already admits Cursor and Grok Build
-without changing the core contract, while their unsupported phase-one start
-paths fail closed.
+Codex is started. Cursor has trusted caller attribution but no phase-one remote
+start. Grok Build remains observable and Experimental; because it has no
+trusted caller hook, agent-authored scoped Mesh events are not offered for it.
+Unsupported paths fail closed.
 
 `call-scope.ts` and `capability.ts` own caller identity. The MCP server cannot
-see which agent called it, so each provider hook records a single-use
+see which agent called it, so supported provider hooks record a single-use
 attribution for the exact call it observed inside its own session, and the
 runtime derives the publishing execution from that instead of from anything the
 model supplied. `capability.ts` mints the opaque per-execution token that
@@ -28,6 +29,20 @@ CLI-only.
 committed facts, so uncommitted work blocks the handoff instead of silently
 staying behind, and the destination refuses just as explicitly when it lacks the
 named commit or when the capsule's resource claims overlap another execution.
+"Uncommitted" is read from `git status` including untracked files, because an
+untracked file is work no commit would carry. A probe that cannot answer
+publishes `unknown`, and only an explicit `clean` releases the handoff.
+
+`convergence.ts` and `task-state.ts` keep one Task identity while snapshots and
+events arrive late, twice, and from several computers. Every writer raises the
+Task `revision`, a merge keeps the higher one, and a tie resolves the same way
+on every device. Ownership only moves forward: to an unowned Task, back to the
+session that already owns it, or through a receipt from the current owner —
+and a computer that already watched a session hand the Task on refuses that
+session's later receipt. Completed and failed Tasks absorb events instead of
+reopening, an execution closed by a receipt stays closed even while its native
+session keeps reporting itself, and the local catalog may refresh a Task's
+description but never take it back from the agent that owns it now.
 
 Every event is schema-bounded and sent under an independent task key; snapshots
 use an independent project key. Resource claims are advisory, expire without a

package/apps/bridge/src/mesh/call-scope.ts

@@ -96,7 +96,7 @@ export function recordAttributedCall(input: {
 }): void {
   const tool = grantTapToolName(input.toolName);
   const sessionId = String(input.sessionId ?? "").trim();
-  if (tool !== "notify" || !sessionId || sessionId.length > 256) return;
+  if (!tool || tool === "connect" || !sessionId || sessionId.length > 256) return;
   const now = input.now ?? Date.now();
   try {
     const call = AttributedCall.parse({

package/apps/bridge/src/mesh/capsule.ts

@@ -6,6 +6,7 @@ import {
   type SessionInfo,
   type TaskCapsule as CapsuleValue,
 } from "../../../../packages/protocol/schema";
+import { workingTreeState } from "./catalog";
 import type { MeshStore } from "./store";
 
 function git(cwd: string, args: string[]): string | undefined {
@@ -72,6 +73,7 @@ export function buildTaskCapsule(
     branch: session.branch ?? git(cwd, ["branch", "--show-current"]),
     latestCommit: head,
     dirtyDiffHash: dirtyDiffHash(cwd),
+    workingTree: workingTreeState(cwd),
     filesChanged: changedFiles(cwd),
     dependencies: snapshot.dependencies
       .filter((item) => item.taskId === request.taskId).map((item) => item.dependsOnTaskId).slice(0, 32),

package/apps/bridge/src/mesh/catalog.ts

@@ -7,7 +7,12 @@ import type {
   SessionInfo,
   TaskState,
 } from "../../../../packages/protocol/schema";
-import { canonicalRepositoryIdentity, projectIdentity, taskIdentity } from "./identity";
+import {
+  canonicalRepositoryIdentity,
+  projectIdentity,
+  sanitizedRepositoryRemote,
+  taskIdentity,
+} from "./identity";
 import type { MeshStore } from "./store";
 
 export type RepositoryFacts = {
@@ -30,30 +35,44 @@ function git(cwd: string, args: string[]): string | undefined {
 }
 
 /**
- * Whether this checkout has changes that a commit-based handoff would leave
- * behind. `undefined` means the probe could not answer, which callers must not
- * read as "clean".
+ * Whether this checkout has anything a commit-based handoff would leave behind.
+ *
+ * `git status` rather than `git diff HEAD`, because an untracked file is work
+ * the Task Capsule cannot carry just as surely as a modified tracked one.
+ * `undefined` means the probe could not answer, which callers must not read as
+ * "clean".
  */
 export function hasUncommittedWork(cwd: string): boolean | undefined {
   try {
-    execFileSync("git", ["-C", cwd, "diff", "--quiet", "HEAD"], {
-      stdio: "ignore", timeout: 2_000,
-    });
-    return false;
-  } catch (error) {
-    return (error as { status?: number }).status === 1 ? true : undefined;
+    const status = execFileSync(
+      "git",
+      ["-C", cwd, "status", "--porcelain=v1", "--untracked-files=normal", "-z"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
+        maxBuffer: 4 * 1_024 * 1_024 },
+    );
+    return status.trim().length > 0;
+  } catch {
+    return undefined;
   }
 }
 
+/** The same reading in the explicit form a Task Capsule publishes. */
+export function workingTreeState(cwd: string): "clean" | "dirty" | "unknown" {
+  const uncommitted = hasUncommittedWork(cwd);
+  if (uncommitted === undefined) return "unknown";
+  return uncommitted ? "dirty" : "clean";
+}
+
 export function inspectRepository(cwd: string): RepositoryFacts {
   const cached = repositoryCache.get(cwd);
   if (cached) return cached;
   const root = git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
-  const baseRemote = git(root, ["remote", "get-url", "origin"]);
+  const rawRemote = git(root, ["remote", "get-url", "origin"]);
+  const baseRemote = rawRemote ? sanitizedRepositoryRemote(rawRemote) : undefined;
   const facts = {
     root,
     baseRemote,
-    canonicalRepositoryId: canonicalRepositoryIdentity(baseRemote, root),
+    canonicalRepositoryId: canonicalRepositoryIdentity(rawRemote, root),
     worktree: git(root, ["rev-parse", "--show-toplevel"]),
   };
   repositoryCache.set(cwd, facts);
@@ -89,7 +108,9 @@ export function linkSessionsToProjects(
       name: basename(repository.root) || "Project",
       repositoryRoot: repository.root,
       canonicalRepositoryId: repository.canonicalRepositoryId,
-      baseRemote: repository.baseRemote,
+      baseRemote: repository.baseRemote
+        ? sanitizedRepositoryRemote(repository.baseRemote)
+        : undefined,
       createdAt: session.startedAt,
     };
     store.upsertProject(project);

package/apps/bridge/src/mesh/convergence.ts

@@ -0,0 +1,82 @@
+/**
+ * Ordered convergence for Task state.
+ *
+ * Mesh state travels through delayed relays, background wakes, and reconnects,
+ * so the same Task arrives out of order, more than once, and from several
+ * computers. Blind last-writer-wins made a stale snapshot able to restore a
+ * previous owner or turn finished work back into working. Every writer raises
+ * `revision`, and these rules decide which version survives — identically on
+ * every computer, so the Task converges instead of oscillating.
+ */
+import type {
+  ExecutionSessionLink as ExecutionValue,
+  MeshTask as TaskValue,
+} from "../../../../packages/protocol/schema";
+
+/** States a Task only leaves through an explicit newer decision. */
+const TERMINAL_STATES = new Set(["completed", "failed"]);
+
+export function isTerminalTaskState(state: string): boolean {
+  return TERMINAL_STATES.has(state);
+}
+
+export function taskRevision(task: TaskValue): number {
+  return task.revision ?? 0;
+}
+
+export function nextTaskRevision(task: TaskValue): number {
+  return Math.min(taskRevision(task) + 1, Number.MAX_SAFE_INTEGER);
+}
+
+/** A total order, so both sides of a merge choose the same winner. */
+export function preferTask(current: TaskValue, incoming: TaskValue): TaskValue {
+  if (taskRevision(current) !== taskRevision(incoming)) {
+    return taskRevision(incoming) > taskRevision(current) ? incoming : current;
+  }
+  if (current.updatedAt !== incoming.updatedAt) {
+    return incoming.updatedAt > current.updatedAt ? incoming : current;
+  }
+  if (isTerminalTaskState(current.state) !== isTerminalTaskState(incoming.state)) {
+    return isTerminalTaskState(incoming.state) ? incoming : current;
+  }
+  return taskOrderKey(incoming) > taskOrderKey(current) ? incoming : current;
+}
+
+function taskOrderKey(task: TaskValue): string {
+  return `${task.state}\0${task.ownerSessionId ?? ""}\0${task.title}\0${task.goal}`;
+}
+
+/** An execution that has ended stays ended; otherwise the newer reading wins. */
+export function preferExecution(
+  current: ExecutionValue,
+  incoming: ExecutionValue,
+): ExecutionValue {
+  if ((current.endedAt != null) !== (incoming.endedAt != null)) {
+    const ended = current.endedAt != null ? current : incoming;
+    const live = current.endedAt != null ? incoming : current;
+    return { ...live, endedAt: ended.endedAt };
+  }
+  const currentAt = current.updatedAt ?? current.startedAt;
+  const incomingAt = incoming.updatedAt ?? incoming.startedAt;
+  if (currentAt !== incomingAt) return incomingAt > currentAt ? incoming : current;
+  return JSON.stringify(incoming) > JSON.stringify(current) ? incoming : current;
+}
+
+/**
+ * Whether `sessionId` may become the owner of `task`.
+ *
+ * Ownership moves forward only: to an unowned Task, back to the session that
+ * already owns it, or away from an owner whose execution this computer can see
+ * has ended. An owner this computer cannot see is treated as still working,
+ * because guessing would be exactly the split brain this prevents.
+ */
+export function mayOwnTask(
+  task: TaskValue,
+  sessionId: string,
+  executions: readonly ExecutionValue[],
+): boolean {
+  if (task.ownerSessionId == null || task.ownerSessionId === sessionId) return true;
+  const owner = executions.find((item) =>
+    item.taskId === task.taskId && item.sessionId === task.ownerSessionId);
+  return owner?.endedAt != null;
+}

package/apps/bridge/src/mesh/identity.ts

@@ -5,23 +5,29 @@ function digest(prefix: string, value: string): string {
   return `${prefix}-${createHash("sha256").update(value).digest("base64url").slice(0, 24)}`;
 }
 
-function normalizedRemote(remote: string): string | undefined {
+/** A public repository hint: host/path only, never credentials or URL query data. */
+export function sanitizedRepositoryRemote(remote: string): string | undefined {
   const trimmed = remote.trim().replace(/\/+$/, "");
   if (!trimmed) return undefined;
   const scp = trimmed.match(/^(?:[^@]+@)?([^:]+):(.+)$/);
   if (scp && !trimmed.includes("://")) {
-    return `${scp[1]}/${scp[2]}`.replace(/\.git$/i, "").toLowerCase();
+    return `${scp[1]}/${scp[2]?.split(/[?#]/, 1)[0]}`
+      .replace(/\.git$/i, "").toLowerCase();
   }
   try {
     const parsed = new URL(trimmed);
+    if (!parsed.hostname) return undefined;
     return `${parsed.hostname}${parsed.pathname}`.replace(/\.git$/i, "").toLowerCase();
   } catch {
-    return trimmed.replace(/\.git$/i, "").toLowerCase();
+    if (/^[a-z0-9.-]+\/[a-z0-9._/-]+(?:\.git)?$/i.test(trimmed)) {
+      return trimmed.replace(/\.git$/i, "").toLowerCase();
+    }
+    return undefined;
   }
 }
 
 export function canonicalRepositoryIdentity(remote: string | undefined, root: string): string {
-  const normalized = remote ? normalizedRemote(remote) : undefined;
+  const normalized = remote ? sanitizedRepositoryRemote(remote) : undefined;
   if (normalized) return normalized;
   try {
     return `local:${realpathSync(root)}`;