granttap-mcp 0.8.17 → 0.8.18

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
@@ -223,8 +246,9 @@ 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
+For Cursor, use the reviewed **GrantTap** Marketplace listing when it is visible
+to your account, or import the public `sergii-ziborov/granttap-mcp` repository
+once. Reload Cursor, then open
 **Cursor Customize → MCPs → GrantTap → Authenticate**. Complete authorization
 and any one-time QR pairing on `https://granttap.com/connect`.
 

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

@@ -88,6 +88,9 @@ async function handlePreToolUse(input: HookInput): Promise<void> {
       recordProjectDecision(input.session_id, {
         at: Date.now(), toolName: input.tool_name ?? "tool", reason: projectDecision.reason,
         ruleId: projectDecision.rule_id,
+        provider: "claude", nativeCallId: input.tool_use_id,
+        policyRevision: projectDecision.policy_revision,
+        artifactHash: projectDecision.artifactHash,
       });
     }
     writePermission("deny", projectDecision.reason);

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

@@ -43,6 +43,9 @@ async function main(): Promise<void> {
     if (input.session_id) {
       recordProjectDecision(input.session_id, {
         at: Date.now(), toolName: input.tool_name ?? "tool", reason: decision.reason, ruleId: decision.rule_id,
+        provider: "codex", nativeCallId: input.tool_use_id,
+        policyRevision: decision.policy_revision,
+        artifactHash: decision.artifactHash,
       });
     }
     deny(decision.reason);

package/apps/bridge/src/capabilities/skills.ts

@@ -7,6 +7,30 @@ import { ancestors } from "./descriptors";
 /** Skills available globally and along the task's repository path. */
 export function workspaceSkills(cwd: string | undefined): SkillInfo[] {
   const found = new Map<string, SkillInfo>();
+  for (const root of skillRoots(cwd)) {
+    for (const skill of skillsIn(root)) {
+      if (!found.has(skill.name)) found.set(skill.name, skill);
+    }
+  }
+  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** The source file behind a named skill, in the same precedence as the catalog. */
+export function skillDefinitionPath(name: string, cwd: string | undefined): string | undefined {
+  for (const root of skillRoots(cwd)) {
+    let entries: string[];
+    try { entries = readdirSync(root); }
+    catch { continue; }
+    for (const entry of entries) {
+      if (entry.startsWith(".")) continue;
+      const path = join(root, entry, "SKILL.md");
+      if (frontmatter(path)?.name === name) return path;
+    }
+  }
+  return undefined;
+}
+
+function skillRoots(cwd: string | undefined): string[] {
   const roots = [
     join(homedir(), ".cursor", "skills-cursor"),
     join(homedir(), ".agents", "skills"),
@@ -21,12 +45,7 @@ export function workspaceSkills(cwd: string | undefined): SkillInfo[] {
       );
     }
   }
-  for (const root of roots) {
-    for (const skill of skillsIn(root)) {
-      if (!found.has(skill.name)) found.set(skill.name, skill);
-    }
-  }
-  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return roots;
 }
 
 function skillsIn(root: string): SkillInfo[] {

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

@@ -17,7 +17,17 @@ bypass, paused gating, and auto-accept. Codex carries ASK from `PreToolUse` to
 `PermissionRequest` with a single-use exact-call marker; Cursor evaluates shell
 and redacted MCP fingerprints directly. A disabled or unavailable engine
 preserves the established GrantTap flow, and no hook request is retried inside
-its 50 ms policy budget.
+its 2,000 ms policy budget. Repository impact is not computed synchronously in
+the hook; unavailable impact remains explicitly unavailable.
+
+`invocation-ingest.ts` reads bounded complete transcript lines and exact-call
+hook denial metadata without forwarding tool arguments, output, or reason text.
+Cursor decisions without a native call ID stay unattributed. Events are replayed
+with stable IDs after an IPC failure. `invocation-query.ts` returns bounded
+Engine history to the phone under the Project key, while
+`invocation-scope.ts` exposes one Task slice through the caller's existing
+opaque Mesh capability. The Engine, not this bridge or Usage telemetry, owns
+the durable journal.
 
 The proprietary engine source and Project database do not live in this package.
 

package/apps/bridge/src/engine/engine-client.ts

@@ -196,6 +196,8 @@ function expectedResultOperation(
   if (operation === "project.get") return "project.found";
   if (operation === "project.list_bindings") return "project.bindings";
   if (operation === "project.upsert_binding") return "project.binding_upserted";
+  if (operation === "invocation.observe") return "invocation.observed";
+  if (operation === "invocation.history") return "invocation.history";
   if (operation === "policy.get") return "policy.found";
   if (operation === "policy.apply") return "policy.applied";
   if (operation === "policy.coverage") return "policy.coverage";

package/apps/bridge/src/engine/engine-invocation-protocol.ts

@@ -0,0 +1,117 @@
+/** The Engine's content-free, durable per-call evidence wire contract. */
+export type InvocationPhase =
+  | "requested" | "reported_success" | "reported_failure" | "reported_unknown"
+  | "denied" | "change_observed" | "source_gap";
+export type InvocationSource = "transcript" | "hook" | "filesystem" | "scanner";
+
+export type InvocationEvent = {
+  event_id: string;
+  invocation_id: string;
+  project_id: string;
+  task_id: string;
+  execution_id: string;
+  provider: string;
+  native_call_id: string;
+  session_id?: string | null;
+  tool_name: string;
+  phase: InvocationPhase;
+  source: InvocationSource;
+  occurred_at: number;
+  repository_id?: string | null;
+  worktree?: string | null;
+  resource?: string | null;
+  revision?: string | null;
+  content_hash?: string | null;
+  capability_artifact_hash?: string | null;
+  policy_revision?: number | null;
+  policy_rule_id?: string | null;
+};
+
+export type InvocationHistoryQuery = {
+  project_id: string;
+  task_id?: string | null;
+  after_sequence?: number | null;
+  limit?: number | null;
+  tail?: boolean;
+  before_sequence?: number | null;
+};
+
+export type SequencedInvocationEvent = { sequence: number; event: InvocationEvent };
+export type InvocationHistoryPage = {
+  events: SequencedInvocationEvent[];
+  next_sequence: number;
+  has_more: boolean;
+  previous_sequence: number;
+  has_older: boolean;
+};
+
+export type InvocationEngineOperation =
+  | { operation: "invocation.observe"; input: InvocationEvent }
+  | { operation: "invocation.history"; input: InvocationHistoryQuery };
+export type InvocationEngineResult =
+  | { operation: "invocation.observed"; sequence: number }
+  | { operation: "invocation.history"; page: InvocationHistoryPage };
+
+const phases = new Set<InvocationPhase>([
+  "requested", "reported_success", "reported_failure", "reported_unknown",
+  "denied", "change_observed", "source_gap",
+]);
+const sources = new Set<InvocationSource>(["transcript", "hook", "filesystem", "scanner"]);
+
+export function parseInvocationResult(result: Record<string, unknown>, invalid: () => never): boolean {
+  if (result.operation === "invocation.observed") {
+    if (!positiveInteger(result.sequence)) invalid();
+    return true;
+  }
+  if (result.operation !== "invocation.history") return false;
+  const page = record(result.page, invalid);
+  if (!Array.isArray(page.events) || page.events.length > 32
+    || !safeInteger(page.next_sequence) || typeof page.has_more !== "boolean"
+    || !safeInteger(page.previous_sequence) || typeof page.has_older !== "boolean") invalid();
+  let prior = 0;
+  for (const raw of page.events as unknown[]) {
+    const row = record(raw, invalid);
+    if (!positiveInteger(row.sequence) || row.sequence <= prior || row.sequence > page.next_sequence) invalid();
+    prior = row.sequence;
+    parseInvocationEvent(row.event, invalid);
+  }
+  return true;
+}
+
+function parseInvocationEvent(value: unknown, invalid: () => never): void {
+  const event = record(value, invalid);
+  for (const [key, max] of [
+    ["event_id", 128], ["invocation_id", 128], ["project_id", 128], ["task_id", 128],
+    ["execution_id", 128], ["provider", 32], ["native_call_id", 128], ["tool_name", 160],
+  ] as const) boundedString(event[key], max, invalid);
+  if (!phases.has(event.phase as InvocationPhase) || !sources.has(event.source as InvocationSource)
+    || !safeInteger(event.occurred_at)) invalid();
+  for (const key of ["repository_id", "worktree", "resource", "revision"] as const) {
+    if (event[key] != null) boundedString(event[key], 512, invalid);
+  }
+  if (event.session_id != null) boundedString(event.session_id, 128, invalid);
+  for (const key of ["content_hash", "capability_artifact_hash"] as const) {
+    if (event[key] != null && (typeof event[key] !== "string" || !/^[a-f0-9]{64}$/i.test(event[key]))) invalid();
+  }
+  if (event.policy_revision != null && !safeInteger(event.policy_revision)) invalid();
+  if (event.policy_rule_id != null) boundedString(event.policy_rule_id, 128, invalid);
+  if (event.phase === "change_observed" && (event.source !== "filesystem"
+    || !event.repository_id || !event.resource || !event.revision || !event.content_hash)) invalid();
+}
+
+function record(value: unknown, invalid: () => never): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid();
+  return value as Record<string, unknown>;
+}
+
+function safeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function positiveInteger(value: unknown): value is number {
+  return safeInteger(value) && value > 0;
+}
+
+function boundedString(value: unknown, max: number, invalid: () => never): void {
+  if (typeof value !== "string" || value.trim() === "" || value.length > max || /[\u0000-\u001f]/.test(value)) invalid();
+}

package/apps/bridge/src/engine/engine-protocol.ts

@@ -3,6 +3,15 @@ import {
   type EnginePolicyOperation,
   type EnginePolicyResult,
 } from "./engine-policy-protocol";
+import {
+  parseInvocationResult,
+  type InvocationEngineOperation,
+  type InvocationEngineResult,
+} from "./engine-invocation-protocol";
+
+export type {
+  InvocationEvent, InvocationHistoryPage, InvocationHistoryQuery, InvocationPhase, InvocationSource,
+} from "./engine-invocation-protocol";
 
 export const ENGINE_PROTOCOL_VERSION = 1 as const;
 export const MAX_ENGINE_FRAME_BYTES = 64 * 1024;
@@ -53,7 +62,7 @@ export type EngineProjectBinding = {
   last_seen_at: number;
 };
 
-export type EngineOperation = EnginePolicyOperation
+export type EngineOperation = EnginePolicyOperation | InvocationEngineOperation
   | { operation: "engine.ping" }
   | { operation: "engine.version" }
   | {
@@ -77,7 +86,7 @@ export type EngineRequest = {
   request_id: string;
 } & EngineOperation;
 
-export type EngineResult = EnginePolicyResult
+export type EngineResult = EnginePolicyResult | InvocationEngineResult
   | { operation: "engine.pong"; engine_version: string }
   | {
     operation: "engine.version";
@@ -202,7 +211,8 @@ function parseResult(value: unknown): EngineResult {
     result.bindings.forEach(parseBinding);
   } else if (operation === "project.binding_upserted") {
     parseBinding(result.binding);
-  } else if (!parsePolicyResult(result, invalidResult)) {
+  } else if (!parsePolicyResult(result, invalidResult)
+    && !parseInvocationResult(result, invalidResult)) {
     throw new EngineProtocolError("engine result operation is unsupported");
   }
   return result as EngineResult;

package/apps/bridge/src/engine/invocation-decision-parse.ts

@@ -0,0 +1,35 @@
+import { sourceGapFact, type InvocationFact } from "./invocation-parse";
+
+/** Metadata-only hook refusal. No arguments, outputs, or explanation text. */
+export function parseInvocationDecision(
+  line: string, provider: "claude" | "codex" | "cursor", offset: number,
+): InvocationFact[] {
+  let value: unknown;
+  try { value = JSON.parse(line) as unknown; }
+  catch { return [sourceGapFact(offset)]; }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return [sourceGapFact(offset)];
+  }
+  const record = value as Record<string, unknown>;
+  if (record.provider !== provider) return [];
+  if (typeof record.nativeCallId !== "string" || !record.nativeCallId.trim()
+    || record.nativeCallId.length > 128 || /[\u0000-\u001f]/.test(record.nativeCallId)
+    || typeof record.toolName !== "string" || !record.toolName.trim()
+    || record.toolName.length > 160 || /[\u0000-\u001f]/.test(record.toolName)
+    || typeof record.at !== "number" || !Number.isSafeInteger(record.at) || record.at < 0) {
+    return [sourceGapFact(offset)];
+  }
+  const revision = record.policyRevision;
+  const rule = record.ruleId;
+  const artifact = record.artifactHash;
+  return [{
+    callId: record.nativeCallId, toolName: record.toolName, phase: "denied",
+    source: "hook", occurredAt: record.at,
+    ...(typeof revision === "number" && Number.isSafeInteger(revision) && revision >= 0
+      ? { policyRevision: revision } : {}),
+    ...(typeof rule === "string" && rule.trim() && rule.length <= 128
+      && !/[\u0000-\u001f]/.test(rule) ? { policyRuleId: rule } : {}),
+    ...(typeof artifact === "string" && /^[a-f0-9]{64}$/i.test(artifact)
+      ? { capabilityArtifactHash: artifact.toLowerCase() } : {}),
+  }];
+}

package/apps/bridge/src/engine/invocation-ingest.ts

@@ -0,0 +1,167 @@
+import { createHash } from "node:crypto";
+import type { SessionInfo } from "../../../../packages/protocol/schema";
+import { inspectRepository, type RepositoryFacts } from "../mesh/catalog";
+import { computerId } from "../mesh/computer-identity";
+import { repositoryRelative } from "../mesh/observed-claims";
+import { claudeTranscriptPaths } from "../sessions/claude";
+import { codexTranscriptPaths } from "../sessions/codex";
+import { cursorFiles } from "../sessions/cursor/scan";
+import { configDir } from "../config/paths";
+import { join } from "node:path";
+import { invocationDecisionPath } from "../policy/decision-log";
+import { EngineClient } from "./engine-client";
+import { engineFeatureEnabled } from "./engine-supervisor";
+import { readInvocationBatch, type InvocationLogCursor } from "./invocation-log-reader";
+import {
+  parseInvocationLine, sourceGapFact, type InvocationFact, type InvocationParseState,
+} from "./invocation-parse";
+import type { InvocationEvent } from "./engine-invocation-protocol";
+import { parseInvocationDecision } from "./invocation-decision-parse";
+
+type Provider = "claude" | "codex" | "cursor";
+type SourceState = { cursor: InvocationLogCursor; parse: InvocationParseState };
+type Client = Pick<EngineClient, "request">;
+
+export type InvocationIngestOptions = {
+  client: Client;
+  enabled: () => boolean;
+  computer: () => string;
+  paths: (session: SessionInfo) => string[];
+  inspect: (cwd: string) => RepositoryFacts;
+  decisionPath?: (session: SessionInfo) => string;
+};
+
+function transcriptPaths(session: SessionInfo): string[] {
+  if (session.agent === "claude") return claudeTranscriptPaths(session.sessionId);
+  if (session.agent === "codex") return codexTranscriptPaths(session.sessionId);
+  if (session.agent === "cursor") return cursorFiles(session.sessionId)?.map((file) => file.path) ?? [];
+  return [];
+}
+
+export function createInvocationIngestor(options: InvocationIngestOptions) {
+  const states = new Map<string, SourceState>();
+  const decisionStates = new Map<string, InvocationLogCursor>();
+  return {
+    async ingest(sessions: readonly SessionInfo[]): Promise<number> {
+      if (!options.enabled()) return 0;
+      const candidates = sessions.filter((session) => session.projectId && session.taskId
+        && ["claude", "codex", "cursor"].includes(session.agent));
+      if (candidates.length === 0) return 0;
+      try { await options.client.request({ operation: "engine.ping" }, { timeoutMs: 200 }); }
+      catch { return 0; }
+      let accepted = 0;
+      for (const session of candidates) {
+        const provider = session.agent as Provider;
+        const facts = session.cwd ? options.inspect(session.cwd) : undefined;
+        for (const path of options.paths(session)) {
+          const key = `${provider}\0${session.sessionId}\0${path}`;
+          const known = states.get(key);
+          let batch;
+          try { batch = readInvocationBatch(path, known?.cursor); }
+          catch { continue; }
+          const parse: InvocationParseState = {
+            pending: new Map(known?.parse.pending ?? []),
+          };
+          const records = [
+            ...batch.gaps.map((offset) => ({ offset, gap: true as const })),
+            ...batch.lines.map((row) => ({ ...row, gap: false as const })),
+          ].sort((a, b) => a.offset - b.offset || Number(b.gap) - Number(a.gap));
+          const thread = hash([path]);
+          const events: InvocationEvent[] = [];
+          for (const record of records) {
+            if (record.gap) parse.pending.clear();
+            const observed = record.gap
+              ? [sourceGapFact(record.offset)]
+              : parseInvocationLine(provider, record.line, parse, record.offset);
+            for (const fact of observed) {
+              events.push(eventFor(session, provider, options.computer(), thread, record.offset, fact, facts));
+            }
+          }
+          try {
+            for (const event of events) {
+              await options.client.request({ operation: "invocation.observe", input: event });
+              accepted += 1;
+            }
+          } catch {
+            // No cursor advance: the next pass replays this batch under stable
+            // event IDs. Engine deduplicates already committed evidence.
+            return accepted;
+          }
+          states.set(key, { cursor: batch.next, parse });
+        }
+        const decisionPath = options.decisionPath?.(session);
+        if (decisionPath) {
+          const key = `${provider}\0${session.sessionId}\0${decisionPath}`;
+          let batch;
+          try { batch = readInvocationBatch(decisionPath, decisionStates.get(key)); }
+          catch { continue; }
+          const thread = hash([decisionPath]);
+          const events = [
+            ...batch.gaps.map((offset) => ({ offset, gap: true as const })),
+            ...batch.lines.map((row) => ({ ...row, gap: false as const })),
+          ].sort((a, b) => a.offset - b.offset).flatMap((record) =>
+            (record.gap ? [sourceGapFact(record.offset)]
+              : parseInvocationDecision(record.line, provider, record.offset))
+              .map((fact) => eventFor(session, provider, options.computer(), thread, record.offset, fact, facts)));
+          try {
+            for (const event of events) {
+              await options.client.request({ operation: "invocation.observe", input: event });
+              accepted += 1;
+            }
+          } catch { return accepted; }
+          decisionStates.set(key, batch.next);
+        }
+      }
+      return accepted;
+    },
+  };
+}
+
+function eventFor(
+  session: SessionInfo, provider: Provider, computer: string,
+  thread: string, offset: number, fact: InvocationFact, repository?: RepositoryFacts,
+): InvocationEvent {
+  // A native session may be observed again after handoff. The computer is part
+  // of the Execution identity, while Cursor child transcripts also need their
+  // thread path to avoid reusing a call ID from a sibling conversation.
+  const invocationId = hash([computer, provider, session.sessionId,
+    provider === "cursor" || fact.phase === "source_gap" ? thread : "", fact.callId]);
+  const resource = fact.resource && repository
+    ? repositoryRelative(fact.resource, repository.root) : undefined;
+  return {
+    event_id: hash([invocationId, thread, String(offset), fact.phase, fact.source,
+      resource ?? "", String(fact.occurredAt)]),
+    invocation_id: invocationId,
+    project_id: session.projectId!,
+    task_id: session.taskId!,
+    execution_id: hash([computer, provider, session.sessionId]),
+    provider, native_call_id: fact.callId, session_id: session.sessionId,
+    tool_name: fact.toolName,
+    phase: fact.phase, source: fact.source, occurred_at: fact.occurredAt,
+    repository_id: repository?.canonicalRepositoryId,
+    worktree: session.worktree ?? repository?.worktree,
+    resource,
+    policy_revision: fact.policyRevision,
+    policy_rule_id: fact.policyRuleId,
+    capability_artifact_hash: fact.capabilityArtifactHash,
+  };
+}
+
+function hash(parts: string[]): string {
+  return createHash("sha256").update(parts.join("\0")).digest("hex");
+}
+
+const defaultClient = new EngineClient({ socketPath: join(configDir(), "engine.sock") });
+const defaultIngestor = createInvocationIngestor({
+  client: defaultClient, enabled: engineFeatureEnabled, computer: computerId,
+  paths: transcriptPaths, inspect: inspectRepository,
+  decisionPath: (session) => invocationDecisionPath(session.sessionId),
+});
+
+let ongoing: Promise<number> | undefined;
+
+export function ingestRuntimeInvocations(sessions: readonly SessionInfo[]): Promise<number> {
+  if (ongoing) return ongoing;
+  ongoing = defaultIngestor.ingest(sessions).finally(() => { ongoing = undefined; });
+  return ongoing;
+}

package/apps/bridge/src/engine/invocation-log-reader.ts

@@ -0,0 +1,71 @@
+import { closeSync, lstatSync, openSync, readSync } from "node:fs";
+
+const MAX_INITIAL_BYTES = 8 * 1024 * 1024;
+const MAX_BATCH_BYTES = 1024 * 1024;
+const MAX_LINE_BYTES = 256 * 1024;
+
+export type InvocationLogCursor = {
+  dev: number;
+  ino: number;
+  offset: number;
+  lineStart: number;
+  partial: Buffer;
+  skipping: boolean;
+};
+
+export type InvocationLogBatch = {
+  lines: Array<{ line: string; offset: number }>;
+  gaps: number[];
+  next: InvocationLogCursor;
+};
+
+/** A bounded, resumable JSONL read; the caller commits `next` only after Engine accepts the batch. */
+export function readInvocationBatch(path: string, cursor?: InvocationLogCursor): InvocationLogBatch {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("transcript is not a regular file");
+  const rotated = cursor && (cursor.dev !== stat.dev || cursor.ino !== stat.ino || stat.size < cursor.offset);
+  const reuse = cursor && !rotated;
+  const initial = reuse ? cursor.offset : Math.max(0, stat.size - MAX_INITIAL_BYTES);
+  const gaps = rotated ? [cursor.offset] : initial > 0 ? [initial] : [];
+  const start = initial;
+  const length = Math.min(MAX_BATCH_BYTES, Math.max(0, stat.size - start));
+  const chunk = Buffer.allocUnsafe(length);
+  let read = 0;
+  if (length > 0) {
+    const fd = openSync(path, "r");
+    try { read = readSync(fd, chunk, 0, length, start); }
+    finally { closeSync(fd); }
+  }
+  const offset = start + read;
+  const prior = reuse ? cursor.partial : Buffer.alloc(0);
+  const combined = Buffer.concat([prior, chunk.subarray(0, read)]);
+  const base = start - prior.length;
+  const lines: InvocationLogBatch["lines"] = [];
+  let lineStart = reuse ? cursor.lineStart : start;
+  let skipping = reuse ? cursor.skipping : initial > 0;
+  let segmentStart = 0;
+  for (let index = 0; index < combined.length; index += 1) {
+    if (combined[index] !== 10) continue;
+    const size = index - segmentStart;
+    if (!skipping && size <= MAX_LINE_BYTES) {
+      const line = combined.subarray(segmentStart, index).toString("utf8");
+      lines.push({ line, offset: lineStart });
+    } else if (!skipping) {
+      gaps.push(lineStart);
+    }
+    segmentStart = index + 1;
+    lineStart = base + segmentStart;
+    skipping = false;
+  }
+  const trailing = combined.subarray(segmentStart);
+  let partial = skipping ? Buffer.alloc(0) : Buffer.from(trailing);
+  if (!skipping && partial.length > MAX_LINE_BYTES) {
+    gaps.push(lineStart);
+    skipping = true;
+    partial = Buffer.alloc(0);
+  }
+  return {
+    lines, gaps,
+    next: { dev: stat.dev, ino: stat.ino, offset, lineStart, partial, skipping },
+  };
+}