@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.3

package/src/team-tools.js

@@ -0,0 +1,235 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+const text = (maxLength = 6e3) => ({ type: "string", minLength: 1, maxLength });
+const strings = (maxItems = 20) => ({ type: "array", maxItems, items: text(1e3) });
+const operationId = text(160);
+function tool(name, description, properties, required = []) {
+  return { name, description, inputSchema: { type: "object", properties, required, additionalProperties: false }, annotations: { readOnlyHint: name === "read_inbox" || name === "read_memory", destructiveHint: false, idempotentHint: true, openWorldHint: false } };
+}
+const TEAM_TOOLS = [
+  tool("send_message", "Send a fact to a teammate. Returns after persistence; delivery may be live or at their next turn. Keep operationId stable on retries.", { operationId, recipient: text(40), body: text(), evidence: strings(16) }, ["operationId", "recipient", "body"]),
+  tool("ask_member", "Ask a teammate or user. Returns a request ID immediately, never waits for an answer. If blocked, checkpoint and yield through your structured outcome.", { operationId, recipient: text(40), body: text(), blocking: { type: "boolean" }, deadlineMs: { type: "integer", minimum: 1e3, maximum: 36e5 }, evidence: strings(16) }, ["operationId", "recipient", "body"]),
+  tool("reply_request", "Answer an addressed request with evidence. This is agent data and cannot authorize user-only actions.", { operationId, requestId: text(200), body: text(), evidence: strings(16) }, ["operationId", "requestId", "body", "evidence"]),
+  tool("yield_task", "Persist a checkpoint and mark this task waiting. Then finish the current turn with a structured needs_info outcome so its process slot is released.", { operationId, checkpoint: text(12e3) }, ["operationId", "checkpoint"]),
+  tool("publish_finding", "Publish a team finding with source evidence; this does not promote project memory.", { operationId, title: text(200), body: text(), evidence: strings(16), paths: strings() }, ["operationId", "title", "body", "evidence"]),
+  tool("propose_contract", "Propose a team contract for coordinator validation. A proposal does not change user requirements or grant permissions.", { operationId, title: text(200), body: text(), evidence: strings(16) }, ["operationId", "body", "evidence"]),
+  tool("submit_task", "Record a submission checkpoint and artifacts. Finish with your structured outcome; only the engine's checks and independent review can complete the task.", { operationId, checkpoint: text(12e3), artifacts: strings() }, ["operationId", "checkpoint"]),
+  tool("request_help", "Ask the coordinator to resolve a blocker. Returns immediately; checkpoint and yield when no safe independent work remains.", { operationId, recipient: text(40), body: text(), evidence: strings(16) }, ["operationId", "body"]),
+  tool("read_inbox", "Read only messages addressed to this member or the team. An inbox read is not an answer or a claim of comprehension.", { afterId: text(200), limit: { type: "integer", minimum: 1, maximum: 50 } }),
+  tool("read_memory", "Read bounded memory selected for this member's current run and task. Private memory is restricted to this member; project entries retain provenance and applicability.", { scope: { enum: ["private", "team", "project"] }, query: text(1e3), limit: { type: "integer", minimum: 1, maximum: 20 } }, ["scope"]),
+  tool("write_memory", "Save private notes or propose team notes with run-derived provenance. Team proposals stay unaccepted; publish_finding shares immediate findings. This cannot create accepted project conventions or export private notes.", { operationId, scope: { enum: ["private", "team"] }, title: text(200), body: text(12e3), tags: strings(), paths: strings() }, ["operationId", "scope", "title", "body"]),
+  tool("propose_project_memory", "Propose a reusable project lesson for later review. Acceptance, trust, and repository applicability remain controlled by the server and user.", { operationId, title: text(200), body: text(12e3), tags: strings(), paths: strings() }, ["operationId", "title", "body"])
+];
+const definitions = new Map(TEAM_TOOLS.map((value) => [value.name, value]));
+const MAX_BODY = 64 * 1024;
+const MAX_RESPONSE = 128 * 1024;
+const MAX_TTL = 25 * 60 * 6e4;
+function teamMcpConfig(connection) {
+  if (!/^http:\/\/127\.0\.0\.1:\d+\/v1\/runs\/[^/]+\/members\/[^/]+\/attempts\/[^/]+$/.test(connection.endpoint) || !/^[\w-]{43}$/.test(connection.token) || !Number.isFinite(connection.expiresAt) || connection.expiresAt <= Date.now()) throw new Error("Invalid member tool connection");
+  return { serverUrl: `${connection.endpoint}/mcp`, headers: { Authorization: `Bearer ${connection.token}` }, tools: Object.fromEntries(TEAM_TOOLS.map((tool2) => [tool2.name, { eager: true }])) };
+}
+function validateTeamToolRequest(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid tool request");
+  const input = value;
+  if (Object.keys(input).some((key) => key !== "name" && key !== "arguments")) throw new Error("Unexpected tool request field");
+  const definition = definitions.get(input.name);
+  if (!definition) throw new Error("Unknown team tool");
+  const args = input.arguments ?? {};
+  if (!args || typeof args !== "object" || Array.isArray(args)) throw new Error("Tool arguments must be an object");
+  const schema = definition.inputSchema;
+  const fields = schema.properties;
+  for (const key of Object.keys(args)) if (!Object.hasOwn(fields, key)) throw new Error(`Unexpected argument: ${key}`);
+  for (const key of schema.required) if (!Object.hasOwn(args, key)) throw new Error(`Missing argument: ${key}`);
+  for (const [key, value2] of Object.entries(args)) {
+    const field = fields[key];
+    if (field.enum && !field.enum.includes(value2)) throw new Error(`Invalid argument: ${key}`);
+    if (field.type === "string" && (typeof value2 !== "string" || !value2.trim() || value2.length > field.maxLength)) throw new Error(`Invalid argument: ${key}`);
+    if (field.type === "boolean" && typeof value2 !== "boolean") throw new Error(`Invalid argument: ${key}`);
+    if (field.type === "integer" && (typeof value2 !== "number" || !Number.isSafeInteger(value2) || value2 < field.minimum || value2 > field.maximum)) throw new Error(`Invalid argument: ${key}`);
+    if (field.type === "array" && (!Array.isArray(value2) || value2.length > field.maxItems || value2.some((item) => typeof item !== "string" || !item.trim() || item.length > field.items.maxLength))) throw new Error(`Invalid argument: ${key}`);
+  }
+  return { name: definition.name, arguments: args };
+}
+class TeamToolBridge {
+  server;
+  listening;
+  grants = /* @__PURE__ */ new Map();
+  async issue(options) {
+    const { identity } = options;
+    if (!identity.runId || !identity.memberId || !identity.attemptId) throw new Error("A team capability requires a run, member and attempt");
+    if (options.signal?.aborted) throw new Error("Cannot issue a team capability for a stopped turn");
+    const base = await this.listen();
+    if (options.signal?.aborted) throw new Error("Cannot issue a team capability for a stopped turn");
+    const token = randomBytes(32).toString("base64url");
+    const key = digest(token);
+    const path = `/v1/runs/${encodeURIComponent(identity.runId)}/members/${encodeURIComponent(identity.memberId)}/attempts/${encodeURIComponent(identity.attemptId)}`;
+    const ttl = typeof options.ttlMs === "number" && Number.isFinite(options.ttlMs) ? Math.max(1, Math.min(MAX_TTL, options.ttlMs)) : 30 * 6e4;
+    const expiresAt = Date.now() + ttl;
+    this.grants.set(key, { identity: Object.freeze({ ...identity }), path, expiresAt, handler: options.handler, isActive: options.isActive, pending: 0 });
+    let timer;
+    const revoke = () => {
+      this.grants.delete(key);
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", revoke);
+    };
+    timer = setTimeout(revoke, ttl);
+    timer.unref();
+    options.signal?.addEventListener("abort", revoke, { once: true });
+    return { connection: { endpoint: base + path, token, expiresAt }, revoke };
+  }
+  async close() {
+    this.grants.clear();
+    const server = this.server;
+    this.server = void 0;
+    this.listening = void 0;
+    if (server) await new Promise((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections();
+    });
+  }
+  listen() {
+    if (this.listening) return this.listening;
+    const server = createServer((req, res) => {
+      void this.handle(req, res);
+    });
+    this.server = server;
+    server.requestTimeout = 1e4;
+    server.headersTimeout = 1e4;
+    server.maxHeadersCount = 30;
+    this.listening = new Promise((resolve, reject) => {
+      server.once("error", (error) => {
+        this.listening = void 0;
+        this.server = void 0;
+        reject(error);
+      });
+      server.listen(0, "127.0.0.1", () => {
+        server.unref();
+        const address = server.address();
+        if (!address || typeof address === "string") {
+          reject(new Error("Could not start team bridge"));
+          return;
+        }
+        resolve(`http://127.0.0.1:${address.port}`);
+      });
+    });
+    return this.listening;
+  }
+  async handle(req, res) {
+    const reply = (status, body) => {
+      if (res.destroyed || res.writableEnded) return;
+      const json = JSON.stringify(body ?? null);
+      res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", "x-content-type-options": "nosniff" });
+      res.end(json.length <= MAX_RESPONSE ? json : JSON.stringify({ error: "Tool response exceeded its context limit" }));
+    };
+    if (req.headers.origin) {
+      reply(403, { error: "Forbidden team bridge request" });
+      return;
+    }
+    const auth = req.headers.authorization;
+    const token = typeof auth === "string" && /^Bearer [A-Za-z0-9_-]{43}$/.test(auth) ? auth.slice(7) : "";
+    const grant = token ? this.grants.get(digest(token)) : void 0;
+    const mcp = !!grant && req.url === `${grant.path}/mcp`;
+    if (!grant || req.url !== grant.path && !mcp || grant.expiresAt <= Date.now() || grant.isActive?.() === false) {
+      reply(403, { error: "Invalid or expired member capability" });
+      return;
+    }
+    if (mcp && req.method === "GET") {
+      res.writeHead(405, { Allow: "POST" });
+      res.end();
+      return;
+    }
+    if (req.method !== "POST" || !/^application\/json(?:\s*;|$)/i.test(req.headers["content-type"] ?? "")) {
+      reply(403, { error: "Forbidden team bridge request" });
+      return;
+    }
+    if (grant.pending >= 4) {
+      reply(429, { error: "Too many active member commands" });
+      return;
+    }
+    grant.pending++;
+    let rpcId = null, toolCall = false;
+    const success = (value) => reply(200, mcp ? { jsonrpc: "2.0", id: rpcId, result: value } : value);
+    try {
+      const chunks = [];
+      let size = 0;
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY) {
+          reply(413, { error: "Team command is too large" });
+          return;
+        }
+        chunks.push(chunk);
+      }
+      if (this.grants.get(digest(token)) !== grant || grant.expiresAt <= Date.now() || grant.isActive?.() === false) {
+        reply(403, { error: "Invalid or expired member capability" });
+        return;
+      }
+      let body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      if (mcp) {
+        if (!body || typeof body !== "object" || Array.isArray(body) || body.jsonrpc !== "2.0" || typeof body.method !== "string" || body.id !== void 0 && typeof body.id !== "string" && !(typeof body.id === "number" && Number.isFinite(body.id))) {
+          reply(400, { jsonrpc: "2.0", id: null, error: { code: -32600, message: "Invalid request" } });
+          return;
+        }
+        if (body.id === void 0) {
+          res.writeHead(202);
+          res.end();
+          return;
+        }
+        rpcId = body.id;
+        if (body.method === "initialize") {
+          grant.initialized = true;
+          success({ protocolVersion: ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"].includes(body.params?.protocolVersion) ? body.params.protocolVersion : "2025-03-26", capabilities: { tools: {}, resources: {} }, serverInfo: { name: "code-flow-team", version: "1.0.0" } });
+          return;
+        }
+        if (!grant.initialized) throw new Error("Initialize the member bridge first");
+        if (body.method === "resources/list") {
+          success({ resources: [] });
+          return;
+        }
+        if (body.method === "resources/templates/list") {
+          success({ resourceTemplates: [] });
+          return;
+        }
+        if (body.method === "ping") {
+          success({});
+          return;
+        }
+        if (body.method === "tools/call") {
+          toolCall = true;
+          body = { name: body.params?.name, arguments: body.params?.arguments ?? {} };
+        } else if (body.method === "tools/list") {
+          success({ tools: TEAM_TOOLS });
+          return;
+        } else {
+          reply(200, { jsonrpc: "2.0", id: rpcId, error: { code: -32601, message: "Method not found" } });
+          return;
+        }
+      }
+      if (body?.method === "tools/list" && Object.keys(body).length === 1) {
+        success({ tools: TEAM_TOOLS });
+        return;
+      }
+      const request = validateTeamToolRequest(body);
+      const value = await grant.handler(request, grant.identity);
+      success(mcp ? { content: [{ type: "text", text: JSON.stringify(value ?? null) }] } : { result: value ?? null });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Team command failed";
+      const safe = message.replaceAll(token, "[redacted]").slice(0, 1e3);
+      if (mcp && toolCall) success({ isError: true, content: [{ type: "text", text: safe }] });
+      else reply(message.includes("no longer active") ? 403 : 400, mcp ? { jsonrpc: "2.0", id: rpcId, error: { code: -32603, message: safe } } : { error: safe });
+    } finally {
+      grant.pending--;
+    }
+  }
+}
+function digest(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+const teamToolBridge = new TeamToolBridge();
+export {
+  TEAM_TOOLS,
+  TeamToolBridge,
+  teamMcpConfig,
+  teamToolBridge,
+  validateTeamToolRequest
+};

package/src/templates.js

@@ -0,0 +1,62 @@
+const templates = [
+  {
+    id: "fix-issue",
+    name: "Fix an issue",
+    description: "Plan, build and review a fix for a GitHub issue; the PR closes it.",
+    pattern: "pipeline",
+    needs: "issue",
+    task: "Fix issue #{number}. Add a test that fails without the fix."
+  },
+  {
+    id: "fix-ci",
+    name: "Fix failing CI",
+    description: "Hand a PR's failing checks and their logs to an agent; push the fix to the PR.",
+    pattern: "pipeline",
+    needs: "pr",
+    ciLogs: true,
+    task: "Make CI pass on pull request #{number}. The failing checks and their logs are below. Fix the cause; don't disable, skip or weaken tests."
+  },
+  {
+    id: "review-pr",
+    name: "Review a PR as a council",
+    description: "Several agents review the PR independently; a chair merges their findings. You choose whether to post it.",
+    pattern: "council",
+    needs: "pr",
+    task: "Review pull request #{number}. Look for bugs, security problems, missing tests, and anything that doesn't match its description."
+  },
+  {
+    id: "upgrade-dependency",
+    name: "Upgrade a dependency",
+    description: "Bump a package, read its changelog for breaking changes, and keep the tests green.",
+    pattern: "pipeline",
+    task: "Upgrade PACKAGE to its latest version. Read its changelog for breaking changes, update every call site, and keep the tests passing."
+  },
+  {
+    id: "sweep-issues",
+    name: "Fix open issues",
+    description: "List the open issues, pick the ones to fix, and start one Plan \u2192 Build \u2192 Review run each. Results wait in your inbox.",
+    pattern: "pipeline",
+    sweep: "issues",
+    task: "Fix the GitHub issue below. Add a test that fails without the fix."
+  },
+  {
+    id: "sweep-dependabot",
+    name: "Fix Dependabot PRs",
+    description: "Every Dependabot PR whose CI fails gets a run that fixes it; approving pushes the fix to the PR. Green ones are left for you to merge.",
+    pattern: "pipeline",
+    sweep: "dependabot",
+    ciLogs: true,
+    task: "Make CI pass on the Dependabot pull request below by adapting the code to the new version. Don't pin it back, and don't disable, skip or weaken tests."
+  },
+  {
+    id: "sweep-alerts",
+    name: "Fix security alerts",
+    description: "Dependabot alerts (one run per package) and code scanning alerts (one per alert). Leaked secrets are listed for you to rotate; agents never get them.",
+    pattern: "pipeline",
+    sweep: "alerts",
+    task: "Fix the security alert below. Fix the cause rather than suppressing the alert, and keep the tests passing."
+  }
+];
+export {
+  templates
+};

package/src/transcript.js

@@ -0,0 +1,134 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { RUNS_DIR, waitForRunWrites } from "./store.js";
+const TRANSCRIPT_LIMITS = { events: 500, bytes: 1024 * 1024, recordBytes: 64 * 1024 * 1024, scanBytes: 16 * 1024 * 1024, fieldChars: 32 * 1024 };
+class TranscriptCursorError extends Error {
+}
+function transcriptPreview(event) {
+  const shorten = (value) => value.length > TRANSCRIPT_LIMITS.fieldChars ? value.slice(0, TRANSCRIPT_LIMITS.fieldChars) + "\n[Preview shortened; the complete event is in the run export.]" : value;
+  if (event.type === "log") return { ...event, text: shorten(event.text) };
+  if (event.type !== "agent") return event;
+  return { ...event, event: Object.fromEntries(Object.entries(event.event).map(([key, value]) => [key, typeof value === "string" ? shorten(value) : value])) };
+}
+async function* reverseLines(file, end) {
+  let position = end, pending = [], pendingBytes = 0;
+  while (position > 0) {
+    const size = Math.min(position, 64 * 1024);
+    position -= size;
+    const chunk = Buffer.allocUnsafe(size);
+    const { bytesRead } = await file.read(chunk, 0, size, position);
+    if (bytesRead !== size) throw new TranscriptCursorError("Transcript changed; reload its latest page");
+    let right = size;
+    for (let index = size - 1; index >= 0; index--) {
+      if (chunk[index] !== 10) continue;
+      const part = chunk.subarray(index + 1, right);
+      if (part.length + pendingBytes > TRANSCRIPT_LIMITS.recordBytes) throw new Error("Transcript record exceeds the 64 MiB bound");
+      if (part.length || pendingBytes) {
+        const text = pending.length ? Buffer.concat([part, ...pending.reverse()], part.length + pendingBytes).toString("utf8") : part.toString("utf8");
+        yield { text, offset: position + index + 1 };
+      } else {
+        while (index > 0 && chunk[index - 1] === 10) index--;
+        yield { text: "", offset: position === 0 && index === 0 ? 0 : position + index + 1 };
+      }
+      pending = [];
+      pendingBytes = 0;
+      right = index;
+    }
+    if (right) {
+      const part = chunk.subarray(0, right);
+      pending.push(part);
+      pendingBytes += part.length;
+    }
+    if (pendingBytes > TRANSCRIPT_LIMITS.recordBytes) throw new Error("Transcript record exceeds the 64 MiB bound");
+  }
+  if (pendingBytes) yield { text: Buffer.concat(pending.reverse(), pendingBytes).toString("utf8"), offset: 0 };
+}
+async function transcriptPage(id, input = {}, reader = reverseLines) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,199}$/.test(id)) throw new TranscriptCursorError("Invalid run ID");
+  const limit = input.limit ?? TRANSCRIPT_LIMITS.events;
+  if (!Number.isInteger(limit) || limit < 1 || limit > TRANSCRIPT_LIMITS.events) throw new TranscriptCursorError("Invalid transcript page size");
+  await waitForRunWrites(id);
+  input.signal?.throwIfAborted();
+  const file = await open(join(RUNS_DIR, `${id}.jsonl`), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const info = await file.stat({ bigint: true });
+    if (!info.isFile()) throw new Error("Transcript must be a regular file");
+    let end = Number(info.size);
+    if (input.before) {
+      let cursor;
+      try {
+        if (input.before.length > 1024) throw new Error();
+        cursor = JSON.parse(Buffer.from(input.before, "base64url").toString());
+      } catch {
+        throw new TranscriptCursorError("Invalid transcript cursor");
+      }
+      if (!cursor || cursor.run !== id || cursor.dev !== String(info.dev) || cursor.ino !== String(info.ino) || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || cursor.offset > end) throw new TranscriptCursorError("Transcript changed; reload its latest page");
+      end = cursor.offset;
+      if (end) {
+        const byte = Buffer.alloc(1);
+        await file.read(byte, 0, 1, end - 1);
+        if (byte[0] !== 10) throw new TranscriptCursorError("Invalid transcript boundary");
+      }
+    }
+    const events = [];
+    let bytes = 0, offset = end, latestSeq = 0, resumed = input.after === 0;
+    for await (const line of reader(file, end)) {
+      input.signal?.throwIfAborted();
+      const skip = () => {
+        offset = line.offset;
+        return end - offset >= TRANSCRIPT_LIMITS.scanBytes;
+      };
+      if (!line.text.trim()) {
+        if (skip()) break;
+        continue;
+      }
+      let event;
+      try {
+        event = JSON.parse(line.text);
+      } catch {
+        if (skip()) break;
+        continue;
+      }
+      if (!event || event.runId !== id || !Number.isSafeInteger(event.seq)) {
+        if (skip()) break;
+        continue;
+      }
+      latestSeq = Math.max(latestSeq, event.seq);
+      if (input.after !== void 0 && event.seq <= input.after) {
+        resumed = true;
+        break;
+      }
+      if ((event.type === "agent" || event.type === "log") && (!input.step || event.type === "agent" && event.stepId === input.step)) {
+        if (event.type === "agent" && (!event.event || typeof event.event !== "object") || event.type === "log" && typeof event.text !== "string") {
+          if (skip()) break;
+          continue;
+        }
+        let preview = transcriptPreview(event), size = Buffer.byteLength(JSON.stringify(preview));
+        if (size > TRANSCRIPT_LIMITS.bytes) {
+          const text = "[Preview omitted because this event exceeds the display limit; the complete event is in the run export.]";
+          const ts = Number.isFinite(event.ts) ? event.ts : 0;
+          preview = event.type === "agent" ? { type: "agent", runId: id, stepId: typeof event.stepId === "string" ? event.stepId.slice(0, 200) : "", seq: event.seq, ts, event: { kind: "status", text } } : { type: "log", runId: id, seq: event.seq, ts, level: "info", text };
+          size = Buffer.byteLength(JSON.stringify(preview));
+        }
+        if (events.length >= limit || bytes + size > TRANSCRIPT_LIMITS.bytes) break;
+        events.push(preview);
+        bytes += size;
+      }
+      offset = line.offset;
+      if (end - offset >= TRANSCRIPT_LIMITS.scanBytes) break;
+    }
+    const after = await file.stat({ bigint: true });
+    if (after.size < info.size) throw new TranscriptCursorError("Transcript changed; reload its latest page");
+    const before = offset > 0 ? Buffer.from(JSON.stringify({ run: id, dev: String(info.dev), ino: String(info.ino), offset })).toString("base64url") : void 0;
+    return { events: events.reverse(), before, latestSeq, bytes, scannedBytes: end - offset, resumed: input.after !== void 0 && input.after <= latestSeq && (resumed || !before) };
+  } finally {
+    await file.close();
+  }
+}
+export {
+  TRANSCRIPT_LIMITS,
+  TranscriptCursorError,
+  transcriptPage,
+  transcriptPreview
+};

package/src/verification-integrity.js

@@ -0,0 +1,27 @@
+import { git } from "./git.js";
+class VerificationIntegrityError extends Error {
+}
+async function verificationIntegrity(repo, signal) {
+  const options = { signal, timeoutMs: 1e4 };
+  const initial = await git(["rev-parse", "--verify", "HEAD^{commit}"], repo, options);
+  const tree = await git(["rev-parse", "--verify", "HEAD^{tree}"], repo, options);
+  if (initial.code || tree.code) throw new VerificationIntegrityError("Cannot pin the verification checkout commit");
+  const assert = async (stage) => {
+    if (signal?.aborted) throw new VerificationIntegrityError("Verification was cancelled");
+    const [head, index, unstaged, flags] = await Promise.all([
+      git(["rev-parse", "--verify", "HEAD^{commit}"], repo, options),
+      git(["write-tree"], repo, options),
+      git(["diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--quiet", "--exit-code", "--"], repo, options),
+      git(["ls-files", "-v", "-z"], repo, options)
+    ]);
+    if (signal?.aborted) throw new VerificationIntegrityError("Verification was cancelled");
+    const hiddenFiles = flags.stdout.split("\0").some((file) => /^[a-zS] /.test(file));
+    if (head.code || index.code || unstaged.code || flags.code || hiddenFiles || head.stdout.trim() !== initial.stdout.trim() || index.stdout.trim() !== tree.stdout.trim()) throw new VerificationIntegrityError(`Verification ${stage} changed tracked files, the staged tree or the checkout commit, or hid tracked files from comparison. The original commit was not verified.`);
+  };
+  await assert("starting checkout");
+  return { head: initial.stdout.trim(), assert };
+}
+export {
+  VerificationIntegrityError,
+  verificationIntegrity
+};

package/src/verification.js

@@ -0,0 +1,183 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cantRunReason, detectCheckCommand, failureExcerpt, failureFingerprint, runCheck } from "./checks.js";
+const KINDS = /* @__PURE__ */ new Set(["build", "typecheck", "lint", "unit", "integration", "browser", "mutation", "visual", "accessibility", "custom"]);
+const DEFAULT_CHECK_TIMEOUT = 5 * 6e4;
+const MAX_CHECK_TIMEOUT = 30 * 6e4;
+const MAX_SUITE_TIMEOUT = 60 * 6e4;
+function validateVerificationProfile(value) {
+  if (!value || typeof value !== "object") throw new Error("A verification profile is required");
+  const p = value;
+  if (typeof p.name !== "string" || !p.name.trim() || p.name.length > 120) throw new Error("Verification profile needs a name of at most 120 characters");
+  if (!Array.isArray(p.checks) || p.checks.length > 12) throw new Error("Verification profiles support at most 12 checks");
+  const ids = /* @__PURE__ */ new Set();
+  const checks = p.checks.map((raw) => {
+    if (!raw || typeof raw !== "object") throw new Error("Invalid verification check");
+    const c = raw;
+    if (typeof c.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(c.id) || ids.has(c.id)) throw new Error("Verification check IDs must be unique and contain letters, digits, underscores or hyphens");
+    ids.add(c.id);
+    if (!KINDS.has(c.kind)) throw new Error(`Unknown verification kind for ${c.id}`);
+    if (typeof c.command !== "string" || !c.command.trim() || c.command.length > 4e3 || c.command.includes("\0")) throw new Error(`Invalid command for ${c.id}`);
+    const timeoutMs = c.timeoutMs ?? DEFAULT_CHECK_TIMEOUT;
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_CHECK_TIMEOUT) throw new Error(`Check timeout must be between 1 ms and ${MAX_CHECK_TIMEOUT} ms`);
+    if (c.required !== void 0 && typeof c.required !== "boolean") throw new Error(`Invalid required flag for ${c.id}`);
+    return { id: c.id, ...typeof c.title === "string" && c.title.trim() ? { title: c.title.trim().slice(0, 120) } : {}, kind: c.kind, command: c.command.trim(), required: c.required !== false, timeoutMs };
+  });
+  let requirements;
+  if (p.requirements !== void 0) {
+    if (!Array.isArray(p.requirements) || p.requirements.length > 48) throw new Error("Verification supports at most 48 requirement mappings");
+    const requirementIds = /* @__PURE__ */ new Set();
+    requirements = p.requirements.map((raw) => {
+      if (!raw || typeof raw !== "object") throw new Error("Invalid requirement mapping");
+      const requirement = raw;
+      if (typeof requirement.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(requirement.id) || requirementIds.has(requirement.id) || typeof requirement.description !== "string" || !requirement.description.trim() || requirement.description.length > 4e3 || !Array.isArray(requirement.checks) || requirement.checks.some((id) => typeof id !== "string" || !ids.has(id)) || new Set(requirement.checks).size !== requirement.checks.length) throw new Error("Requirements need unique IDs, descriptions, and references to configured checks");
+      requirementIds.add(requirement.id);
+      return { id: requirement.id, description: requirement.description.trim(), checks: [...requirement.checks] };
+    });
+  }
+  return { name: p.name.trim(), checks, ...requirements ? { requirements } : {}, ...typeof p.source === "string" ? { source: p.source.slice(0, 500) } : {}, ...typeof p.setup === "string" && p.setup.trim() ? { setup: p.setup.trim().slice(0, 4e3) } : {} };
+}
+async function detectVerificationProfile(repo, preset = "standard") {
+  if (!["lightweight", "standard", "thorough"].includes(preset)) throw new Error("Unknown verification preset");
+  const include = preset === "lightweight" ? ["typecheck", "lint", "unit"] : preset === "standard" ? ["build", "typecheck", "lint", "unit"] : ["build", "typecheck", "lint", "unit", "integration", "browser", "mutation", "visual", "accessibility"];
+  const has = (path) => existsSync(join(repo, path));
+  const checks = [];
+  if (has("package.json")) {
+    let pkg;
+    try {
+      pkg = JSON.parse(await readFile(join(repo, "package.json"), "utf8"));
+    } catch {
+      throw new Error("Cannot detect verification: package.json is not valid JSON");
+    }
+    const runner = has("pnpm-lock.yaml") ? "pnpm run" : has("yarn.lock") ? "yarn run" : has("bun.lock") || has("bun.lockb") ? "bun run" : "npm run";
+    const scripts = [["build", ["build"]], ["typecheck", ["typecheck", "check:types"]], ["lint", ["lint"]], ["unit", ["test:unit", "test"]], ["integration", ["test:integration"]], ["browser", ["test:e2e", "test:browser"]], ["mutation", ["test:mutation", "mutation"]], ["visual", ["test:visual"]], ["accessibility", ["test:a11y", "test:accessibility"]]];
+    for (const [kind, candidates] of scripts) {
+      if (!include.includes(kind)) continue;
+      const script = candidates.find((name) => typeof pkg.scripts?.[name] === "string" && String(pkg.scripts[name]).trim() && !/no test specified/i.test(String(pkg.scripts[name])));
+      if (script) checks.push({ id: kind, kind, command: `${runner} ${script}`, required: true, timeoutMs: DEFAULT_CHECK_TIMEOUT });
+    }
+    if (checks.length) return { name: preset, checks, source: "package.json" };
+  }
+  const detected = await detectCheckCommand(repo);
+  if (detected) checks.push({ id: "unit", kind: "unit", command: detected.command, required: true, timeoutMs: DEFAULT_CHECK_TIMEOUT });
+  return { name: preset, checks, source: detected?.source, setup: detected?.setup };
+}
+function diagnoseChecks(attempts, baseline) {
+  if (!attempts.length) return { diagnosis: "failed", reason: "No check attempt completed" };
+  if (attempts.some((a) => a.ok) && attempts.some((a) => !a.ok)) return { diagnosis: "flaky", reason: "The same command both passed and failed on this revision" };
+  if (attempts.every((a) => a.ok)) return { diagnosis: "passed" };
+  const reason = attempts.map(cantRunReason).find(Boolean);
+  if (reason) return { diagnosis: "environment", reason };
+  if (baseline?.ok) return { diagnosis: "regression", reason: "This check passed on the baseline revision" };
+  if (baseline && !baseline.ok && attempts.every((a) => failureFingerprint(a) === failureFingerprint(baseline))) return { diagnosis: "pre-existing", reason: "The baseline reports the same failure; this check still requires attention" };
+  return { diagnosis: "failed" };
+}
+function resultState(checks, skipped = []) {
+  if (skipped.some((c) => c.check.required)) return "blocked";
+  const required = checks.filter((c) => c.check.required);
+  if (required.some((c) => c.diagnosis === "environment")) return "blocked";
+  if (required.some((c) => c.diagnosis !== "passed")) return "needs-changes";
+  return required.length ? "verified" : "unchecked";
+}
+async function runVerification(cwd, input, opts = {}) {
+  const profile = validateVerificationProfile(input);
+  const repeats = opts.repeats ?? 1;
+  if (!Number.isInteger(repeats) || repeats < 1 || repeats > 3) throw new Error("Verification repeats must be between 1 and 3");
+  const timeoutMs = opts.timeoutMs ?? 15 * 6e4;
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_SUITE_TIMEOUT) throw new Error("Verification deadline must be between 1 ms and one hour");
+  const startedAt = Date.now();
+  const checks = [];
+  const skipped = [];
+  for (const check of profile.checks) {
+    if (opts.signal?.aborted || Date.now() - startedAt >= timeoutMs) {
+      skipped.push({ check, reason: opts.signal?.aborted ? "Verification was cancelled" : "The verification deadline was reached" });
+      continue;
+    }
+    const attempts = [];
+    for (let i = 0; i < repeats; i++) {
+      const remaining = timeoutMs - (Date.now() - startedAt);
+      if (opts.signal?.aborted || remaining <= 0) break;
+      const execution = { timeoutMs: Math.min(check.timeoutMs, remaining), signal: opts.signal, container: opts.container };
+      attempts.push(await (opts.execute ? opts.execute(check, execution) : runCheck(cwd, check.command, execution)));
+    }
+    const baseline = opts.baseline?.[check.id];
+    const diagnosis = diagnoseChecks(attempts, baseline);
+    if (["unit", "integration", "browser"].includes(check.kind) && attempts.some((attempt) => attempt.tests === 0)) {
+      diagnosis.diagnosis = "failed";
+      diagnosis.reason = "The test runner reported zero executed tests";
+    }
+    checks.push({ check, attempts, baseline, ...diagnosis });
+    if (attempts.length < repeats || opts.signal?.aborted) skipped.push({ check, reason: opts.signal?.aborted ? "Verification was cancelled" : "Repeated verification did not complete before the deadline" });
+  }
+  const requirements = (opts.requirements ?? profile.requirements)?.map((r) => {
+    const missing = r.checks.filter((id) => !checks.some((c) => c.check.id === id && c.diagnosis === "passed"));
+    return { id: r.id, description: r.description, covered: r.checks.length > 0 && !missing.length, missing };
+  });
+  let state = resultState(checks, skipped);
+  if (state === "verified" && requirements?.some((r) => !r.covered)) state = "needs-changes";
+  return {
+    version: 1,
+    profile: profile.name,
+    state,
+    startedAt,
+    endedAt: Date.now(),
+    checks,
+    skipped,
+    requirements,
+    ...opts.changedFiles ? { risk: assessChangeRisk(opts.changedFiles), review: reviewCoverage(opts.changedFiles.map((f) => f.path), opts.reviewedFiles ?? []) } : {}
+  };
+}
+function assessChangeRisk(files) {
+  const reasons = /* @__PURE__ */ new Set();
+  const sensitiveFiles = [];
+  for (const f of files) {
+    const path = f.path.replaceAll("\\", "/");
+    let sensitive = false;
+    for (const [pattern, reason] of [
+      [/(^|\/)(migrations?|schema)(\/|\.)|\.sql$/i, "Database or schema changes require migration review"],
+      [/(^|[\/_-])(auth|permissions?|security|secrets?|credentials?|crypto)([\/_.-]|$)/i, "Authentication, permissions or sensitive data handling changed"],
+      [/(^|\/)(\.github\/workflows|Dockerfile|\.env)|(^|\/)(deploy|infra|terraform)(\/|\.)/i, "Execution or deployment configuration changed"]
+    ]) if (pattern.test(path)) {
+      reasons.add(reason);
+      sensitive = true;
+    }
+    if (sensitive) sensitiveFiles.push(f.path);
+  }
+  const lines = files.reduce((n, f) => n + (f.additions ?? 0) + (f.deletions ?? 0), 0);
+  if (files.length > 20 || lines > 1e3) reasons.add("Large change surface needs broader verification");
+  return { level: sensitiveFiles.length ? "high" : reasons.size || files.length > 5 ? "medium" : "low", reasons: [...reasons], sensitiveFiles };
+}
+function reviewCoverage(changed, reviewed) {
+  const normalize = (p) => p.replaceAll("\\", "/").replace(/^\.\//, "");
+  const files = [...new Set(changed.map(normalize))];
+  const seen = new Set(reviewed.map(normalize));
+  const unreviewed = files.filter((f) => !seen.has(f));
+  return { changed: files.length, reviewed: files.length - unreviewed.length, percent: files.length ? Math.round(100 * (files.length - unreviewed.length) / files.length) : 100, unreviewed };
+}
+function renderVerificationReport(report) {
+  const cell = (s) => s.replaceAll("|", "\\|").replaceAll("\n", " ");
+  const parts = [`# Verification: ${report.state}`, "", `Profile: ${cell(report.profile)} \xB7 Duration: ${((report.endedAt - report.startedAt) / 1e3).toFixed(1)}s`, "", "| Check | Required | Result | Attempts |", "| --- | --- | --- | --- |"];
+  for (const c of report.checks) parts.push(`| ${cell(c.check.title ?? c.check.id)} | ${c.check.required ? "yes" : "no"} | ${c.diagnosis} | ${c.attempts.length} |`);
+  for (const s of report.skipped) parts.push(`| ${cell(s.check.id)} | ${s.check.required ? "yes" : "no"} | skipped: ${cell(s.reason)} | 0 |`);
+  for (const c of report.checks.filter((c2) => c2.diagnosis !== "passed")) {
+    const output = failureExcerpt(c.attempts.find((a) => !a.ok)?.output ?? c.reason ?? "No output");
+    const fence = "`".repeat(Math.max(3, ...[...output.matchAll(/`+/g)].map((m) => m[0].length + 1)));
+    parts.push("", `## ${cell(c.check.id)}: ${c.diagnosis}`, "", c.reason ?? "The check did not pass.", "", fence, output, fence);
+  }
+  if (report.risk) parts.push("", `Change risk: ${report.risk.level}`, ...report.risk.reasons.map((r) => `- ${r}`));
+  if (report.review) parts.push("", `Review coverage: ${report.review.reviewed}/${report.review.changed} files (${report.review.percent}%)`, ...report.review.unreviewed.map((p) => `- Unreviewed: ${p}`));
+  if (report.requirements) parts.push("", "Requirements:", ...report.requirements.map((r) => `- ${r.covered ? "[x]" : "[ ]"} ${r.id}: ${r.description}${r.missing.length ? ` (missing: ${r.missing.join(", ")})` : ""}`));
+  return `${parts.join("\n")}
+`;
+}
+export {
+  assessChangeRisk,
+  detectVerificationProfile,
+  diagnoseChecks,
+  renderVerificationReport,
+  resultState,
+  reviewCoverage,
+  runVerification,
+  validateVerificationProfile
+};