@stigmer/runner 3.1.3 → 3.1.4

package/src/shared/filereview/cas-substrate.ts

@@ -189,6 +189,66 @@ export async function snapshotCasChangeSet(opts: {
   };
 }
 
+/**
+ * The display-facing classification of one CAS path's before/after bytes: the
+ * change kind, whether either side is binary, and the `+N −M` line counts.
+ */
+export interface CasChangeClassification {
+  /** Path before the change (workspace-relative). Empty for ADD. */
+  readonly pathBefore: string;
+  /** Path after the change. Empty for DELETE. */
+  readonly pathAfter: string;
+  readonly kind: FileChangeKind;
+  /** A NUL byte on either side — the diff cannot render as text. */
+  readonly isBinary: boolean;
+  /** `+N −M` from the in-memory bytes; absent for a binary or oversized side. */
+  readonly lineCounts?: LineChangeCounts;
+}
+
+/**
+ * Classify one CAS path's before/after bytes. Returns `undefined` for a
+ * non-change — both sides absent, or a touch that left the bytes unchanged —
+ * exactly as the git substrate's diff omits unchanged files.
+ *
+ * This is the SINGLE classification authority for a CAS before/after pair: the
+ * turn-boundary capture ({@link buildCasCapturedFile}) and the mid-run progress
+ * producer ({@link ./cas-progress.js}) both route through it, so the live "N
+ * files changed so far" strip and the reviewed change set can never disagree on
+ * an edge case (the trailing-newline class of bug {@link ./line-counts.js}
+ * warns about). Kind, no-op detection, binary detection, and counting live here
+ * and nowhere else.
+ */
+export function classifyCasChange(
+  path: string,
+  beforeBuf: Buffer | null,
+  afterBuf: Buffer | null,
+): CasChangeClassification | undefined {
+  if (beforeBuf === null && afterBuf === null) return undefined;
+  // A touch that did not change the bytes is not a reviewable change.
+  if (beforeBuf && afterBuf && beforeBuf.equals(afterBuf)) return undefined;
+
+  const kind =
+    beforeBuf === null
+      ? FileChangeKind.ADD
+      : afterBuf === null
+        ? FileChangeKind.DELETE
+        : FileChangeKind.MODIFY;
+  const isBinary =
+    (beforeBuf !== null && bytesLookBinary(beforeBuf)) ||
+    (afterBuf !== null && bytesLookBinary(afterBuf));
+
+  return {
+    pathBefore: kind === FileChangeKind.ADD ? "" : path,
+    pathAfter: kind === FileChangeKind.DELETE ? "" : path,
+    kind,
+    isBinary,
+    // A binary change has no text line diff to count.
+    lineCounts: isBinary
+      ? undefined
+      : countLineChanges(beforeBuf?.toString("utf8"), afterBuf?.toString("utf8")),
+  };
+}
+
 /**
  * Store one path's before/after blobs and classify the change. Returns
  * `undefined` for a no-op (both sides absent, or an unchanged touch).
@@ -199,44 +259,29 @@ async function buildCasCapturedFile(
   capture: CasPathCapture,
 ): Promise<CasCapturedFile | undefined> {
   const { path, before, after, captureClass } = capture;
-  if (before === null && after === null) return undefined;
-
   const beforeBuf = before === null ? null : Buffer.from(before);
   const afterBuf = after === null ? null : Buffer.from(after);
 
-  // A touch that did not change the bytes is not a reviewable change.
-  if (beforeBuf && afterBuf && beforeBuf.equals(afterBuf)) return undefined;
+  const classification = classifyCasChange(path, beforeBuf, afterBuf);
+  if (!classification) return undefined;
 
   const beforeRef = beforeBuf ? await storeBlob(storage, executionId, beforeBuf) : undefined;
   const afterRef = afterBuf ? await storeBlob(storage, executionId, afterBuf) : undefined;
 
-  const kind =
-    beforeRef === undefined
-      ? FileChangeKind.ADD
-      : afterRef === undefined
-        ? FileChangeKind.DELETE
-        : FileChangeKind.MODIFY;
-
-  const isCreate = kind === FileChangeKind.ADD;
-  const isDelete = kind === FileChangeKind.DELETE;
-  const isBinary = beforeRef?.isBinary || afterRef?.isBinary;
-
   return {
-    pathBefore: isCreate ? "" : path,
-    pathAfter: isDelete ? "" : path,
-    kind,
+    pathBefore: classification.pathBefore,
+    pathAfter: classification.pathAfter,
+    kind: classification.kind,
     captureClass,
     before: beforeRef,
     after: afterRef,
     // Binary on either side means the diff cannot render as text; the change set
     // then cannot be approved as complete (parity with the git substrate).
-    diffComplete: !isBinary,
+    diffComplete: !classification.isBinary,
     // Display counts are taken NOW, while the text bytes are still in memory —
-    // after this they exist only as offloaded blobs. A binary change has no
-    // line diff to count.
-    lineCounts: isBinary
-      ? undefined
-      : countLineChanges(beforeBuf?.toString("utf8"), afterBuf?.toString("utf8")),
+    // after this they exist only as offloaded blobs (the same counts the mid-run
+    // progress producer derives via classifyCasChange).
+    lineCounts: classification.lineCounts,
   };
 }
 

package/src/shared/filereview/command-provenance.ts

@@ -0,0 +1,180 @@
+/**
+ * The DD-28 approved-command turn qualification rule — the harness-agnostic core
+ * of the auto-keep policy's runner-side facts.
+ *
+ * A turn whose ONLY mutation source was shell commands the human had already
+ * authorized should not re-gate its file effects at the turn-boundary review —
+ * the user consented to the command, and the command's file effects are the
+ * consented outcome. The server cannot derive this itself (tool calls carry no
+ * turn marker), so the runner — the only component that owns turn scoping —
+ * derives the facts and attaches them to the CANDIDATE_CAPTURED event as
+ * {@link TurnCommandProvenance}.
+ *
+ * This module owns the *qualification rule* both harnesses share; each harness
+ * supplies only what genuinely differs — how "this turn's tool calls" are scoped,
+ * and how a single executed command's DIRECT consent row is identified — via
+ * {@link CommandProvenanceCoreInputs}. Keeping the rule in one place is what makes
+ * the Cursor and deep-agent qualifications provably identical (a second copy would
+ * drift on edge cases — the divergence the AI-Engineer role warns against).
+ *
+ * TRUST BOUNDARY. This module asserts turn FACTS (which tools ran this turn),
+ * the same trust level as the captured bytes themselves. It never asserts
+ * CONSENT: a resolved consent id merely POINTS at a transcript row whose
+ * `approval_action` was authored by the server's SubmitApproval (and is
+ * preserved against runner writes) — the backend re-verifies every claimed row
+ * against that server-owned record before authoring the policy decision, so a
+ * runner cannot mint authorization it was never given.
+ *
+ * FAIL-CLOSED. Every uncertainty disqualifies (returns undefined → the set
+ * reviews manually, exactly as before DD-28): a file-tool call, an MCP tool, a
+ * sub-agent delegation, an unrecognized tool name, or an executed shell command
+ * with no provable consent source. Being conservative here costs only an extra
+ * review; being permissive would silently waive one.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { TurnCommandProvenanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { ApprovalAction, ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyTool, toolApprovalCategory } from "../tool-kind.js";
+import { isToolCallRowHidden } from "../tool-row.js";
+
+/**
+ * Tool kinds that can never mutate the workspace: their presence in a turn is
+ * irrelevant to change-set provenance. Everything OUTSIDE this set is either a
+ * consent-mapped shell command or a disqualifier — never silently ignored.
+ */
+export const NON_MUTATING_KINDS: ReadonlySet<ToolKind> = new Set([
+  ToolKind.FILE_READ,
+  ToolKind.SEARCH,
+  ToolKind.LIST,
+  ToolKind.FETCH,
+  ToolKind.WEB_SEARCH,
+  ToolKind.THINK,
+  ToolKind.TODO,
+]);
+
+/**
+ * The harness-supplied inputs to the shared DD-28 qualification rule. The two
+ * function inputs are exactly the two things that differ between harnesses
+ * (turn scoping is expressed by which calls appear in {@link turnToolCalls}).
+ */
+export interface CommandProvenanceCoreInputs {
+  /**
+   * This turn's tool calls, already scoped by the harness (Cursor: the positional
+   * slice from the turn's first streamed message; deep-agent: the calls whose id
+   * is new since a pre-stream settled snapshot). Order is preserved but irrelevant.
+   */
+  readonly turnToolCalls: readonly ToolCall[];
+  /**
+   * The WHOLE transcript, for the APPROVE_ALL lease lookup — a lease is
+   * run-lifetime and its granting row usually lives in a prior turn.
+   */
+  readonly messages: readonly AgentMessage[];
+  /**
+   * Whether a (shell) tool call actually EXECUTED this turn, as opposed to being
+   * a pending/denied gate that produced no mutation. A non-executed shell neither
+   * needs consent nor disqualifies (Cursor: not in the denial ledger; deep-agent:
+   * status is COMPLETED).
+   */
+  readonly isExecutedCommand: (tc: ToolCall) => boolean;
+  /**
+   * The tool-call id of the row whose server-authored `approval_action` DIRECTLY
+   * authorized this executed command, or undefined when none does (then the lease
+   * / global-bypass fallbacks apply). Cursor maps a reinvocation grant token back
+   * to its consent row; the deep-agent's gated command IS its own consent row
+   * (same id, `approval_action` written in place).
+   */
+  readonly resolveDirectConsent: (tc: ToolCall) => string | undefined;
+  /** True when the pre-armed spec.auto_approve_all bypassed the gate. */
+  readonly globalBypass: boolean;
+}
+
+/**
+ * Apply the DD-28 qualification rule to a harness-scoped turn, returning the
+ * {@link TurnCommandProvenance} to attach to the candidate — or undefined when
+ * the turn does not qualify (any non-shell mutation-capable call, any unknown
+ * tool, any executed command without a provable consent source, or no executed
+ * consented command at all).
+ */
+export function qualifyTurnCommandProvenance(
+  inputs: CommandProvenanceCoreInputs,
+): TurnCommandProvenance | undefined {
+  const { turnToolCalls, messages, isExecutedCommand, resolveDirectConsent, globalBypass } = inputs;
+
+  const consentIds = new Set<string>();
+  let authorizedByAutoApproveAll = false;
+  let executedCommandCount = 0;
+
+  for (const tc of turnToolCalls) {
+    // A hidden row is a collapsed twin/reaction — it never executed.
+    if (isToolCallRowHidden(tc)) continue;
+
+    const kind = classifyTool(tc.name, tc.mcpServerSlug);
+    if (NON_MUTATING_KINDS.has(kind)) continue;
+
+    if (kind !== ToolKind.SHELL) {
+      // A file tool (mixed turn), a sub-agent (unattributable mutations), an
+      // MCP tool (opaque side effects), or an unrecognized name — the turn's
+      // mutations cannot be attributed to consented commands. Fail closed.
+      return undefined;
+    }
+
+    if (!isExecutedCommand(tc)) {
+      // A pending / denied shell — this turn's gate, not a mutation source.
+      continue;
+    }
+    executedCommandCount++;
+
+    const consentId = resolveDirectConsent(tc);
+    if (consentId) {
+      consentIds.add(consentId);
+      continue;
+    }
+    const leaseConsentId = findLeaseConsentId(messages, tc.name);
+    if (leaseConsentId) {
+      consentIds.add(leaseConsentId);
+      continue;
+    }
+    if (globalBypass) {
+      authorizedByAutoApproveAll = true;
+      continue;
+    }
+    // An executed shell command with no grant, no lease, and no bypass should
+    // be impossible (every un-consented shell is gated); if it ever happens,
+    // the honest answer is a manual review, not a waived one.
+    return undefined;
+  }
+
+  // A turn that executed no consented command has nothing to attribute the
+  // change set to — whatever changed came from somewhere else. Manual review.
+  if (executedCommandCount === 0) return undefined;
+
+  return create(TurnCommandProvenanceSchema, {
+    consentToolCallIds: [...consentIds],
+    authorizedByAutoApproveAll,
+  });
+}
+
+/**
+ * Find the transcript row whose APPROVE_ALL authored the run-lifetime lease
+ * covering `toolName`'s category — the consent row a lease-executed command
+ * cites. Searched across the whole transcript (a lease usually originates in a
+ * prior turn); the first (earliest) APPROVE_ALL of the category is the lease's
+ * origin. Returns undefined when no lease row exists for the category.
+ */
+export function findLeaseConsentId(
+  messages: readonly AgentMessage[],
+  toolName: string,
+): string | undefined {
+  const category = toolApprovalCategory(toolName);
+  if (!category) return undefined;
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      if (tc.approvalAction !== ApprovalAction.APPROVE_ALL) continue;
+      if (toolApprovalCategory(tc.name) === category) return tc.id;
+    }
+  }
+  return undefined;
+}

package/src/shared/filereview/git-substrate.ts

@@ -325,8 +325,14 @@ export interface GitProgressEntry {
   readonly linesRemoved: number;
 }
 
-/** Result of {@link captureProgressDelta}. */
-export interface ProgressDelta {
+/**
+ * Result of {@link captureProgressDelta} — the git-numstat delta. Distinct from
+ * the substrate-neutral `ProgressDelta` (in {@link ./progress.js}) that the
+ * git/cas/hybrid substrates emit: this carries the working-tree sha (for the
+ * short-circuit) and git's `FileChangeType` entries; the neutral one carries
+ * proto `FileChangeKind` entries and an honest total.
+ */
+export interface GitProgressDelta {
   /** The post-diff working-tree sha, for the caller's short-circuit cache. */
   readonly afterTree: string;
   /** One count-only entry per changed file (no content). */
@@ -357,7 +363,7 @@ export async function captureProgressDelta(
   baselineTree: string,
   excludePaths: readonly string[] = [],
   lastTreeSha?: string,
-): Promise<ProgressDelta | undefined> {
+): Promise<GitProgressDelta | undefined> {
   const gitDir = await resolveGitDir(gitRoot);
   const afterTree = await writeWorkingTree(gitRoot, gitDir, "progress", executionId, excludePaths);
   if (lastTreeSha !== undefined && afterTree === lastTreeSha) return undefined;

package/src/shared/filereview/index.ts

@@ -36,20 +36,32 @@ export {
 export {
   captureProgressDelta,
   isGitWorkTree,
+  type GitProgressDelta,
   type GitProgressEntry,
-  type ProgressDelta,
 } from "./git-substrate.js";
 
 export {
   buildFileChangeProgress,
   captureFileChangeProgress,
+  createGitProgressSubstrate,
+  createHybridProgressSubstrate,
   newProgressCaptureState,
   PROGRESS_CAPTURE_MIN_INTERVAL_MS,
   PROGRESS_MAX_ENTRIES,
   shouldCaptureProgress,
+  type ProgressCapture,
   type ProgressCaptureState,
+  type ProgressDelta,
+  type ProgressEntry,
+  type ProgressSubstrate,
 } from "./progress.js";
 
+export {
+  createCasProgressSubstrate,
+  type CasTouchedReader,
+  type CasTouchedSnapshot,
+} from "./cas-progress.js";
+
 export {
   countLineChanges,
   LINE_COUNT_MAX_BYTES,
@@ -61,12 +73,14 @@ export {
   casBlobKey,
   casBlobReader,
   casManifestKey,
+  classifyCasChange,
   loadCasManifest,
   restoreCasToBaseline,
   snapshotCasChangeSet,
   type BlobReader,
   type CasBlobRef,
   type CasCapturedFile,
+  type CasChangeClassification,
   type CasManifest,
   type CasPathCapture,
   type CasSnapshotRef,