forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/agent-adapters/types.ts

@@ -9,8 +9,16 @@ export type AgentSubcommand =
   | "export"
   | "check"
   | "doctor"
+  | "onboard"
   | "print-context"
-  | "clean";
+  | "clean"
+  | "prepare"
+  | "hooks"
+  | "install"
+  | "ingest"
+  | "context"
+  | "memory"
+  | "timeline";
 
 export interface AgentCommandOptions {
   subcommand: AgentSubcommand;
@@ -19,9 +27,22 @@ export interface AgentCommandOptions {
   target: AgentAdapterTarget;
   dryRun: boolean;
   force: boolean;
+  mcpServer?: string;
   preserveUserSections: boolean;
   skills: boolean;
   rules: boolean;
+  eventName?: string;
+  hookAction?: "smoke" | "status" | string;
+  input?: unknown;
+  entry?: string;
+  change?: string;
+  proof?: string;
+  handoff?: boolean;
+  current?: boolean;
+  limit?: number;
+  watch?: boolean;
+  file?: string;
+  pollIntervalMs?: number;
 }
 
 export interface AgentExportFile {
@@ -119,9 +140,212 @@ export interface AgentPrintContextResult {
   exitCode: 0 | 1;
 }
 
+export type AgentHookBridgeState = "ready" | "missing" | "not-supported" | "waiting-for-user-trust" | "memory-unavailable";
+export type AgentHookApprovalStatus = "not-required" | "waiting-for-user-trust" | "unverified" | "trusted" | "memory-unavailable";
+export type AgentHookNativeTrustStatus = "not-required" | "waiting-for-native-signal" | "trusted" | "memory-unavailable";
+export type AgentHookReadinessLevel = "none" | "canary" | "trusted-native";
+
 export interface AgentDoctorResult {
   ok: boolean;
+  target: AgentAdapterTarget;
+  summary: {
+    adapter: "ready" | "missing" | "stale";
+    hookBridge: AgentHookBridgeState;
+    approvalRequired: boolean;
+    approvalStatus: AgentHookApprovalStatus;
+    nativeTrustStatus: AgentHookNativeTrustStatus;
+    recentEvents: number;
+    queuedEvents?: number;
+    usefulSignals: number;
+    nativeSignals: number;
+    canarySignals: number;
+    lastEventAt?: string;
+  };
+  checks: Array<{ name: string; ok: boolean; message?: string; evidence?: unknown }>;
+  nextActions: string[];
+  diagnostics: Diagnostic[];
+  exitCode: 0 | 1;
+}
+
+export interface AgentPrepareResult {
+  ok: boolean;
+  target: AgentAdapterTarget;
+  exportResult: AgentExportResult;
+  checkResult: AgentCheckResult;
+  installResult?: unknown;
+  commands: {
+    context: string;
+    export: string;
+    check: string;
+    install?: string;
+    hooksStatus?: string;
+    hooksSmoke?: string;
+    open?: string;
+  };
+  diagnostics: Diagnostic[];
+  exitCode: 0 | 1;
+}
+
+export interface AgentOnboardResult {
+  schemaVersion: "0.1.0";
+  ok: boolean;
+  target: AgentAdapterTarget;
+  readyToEdit: boolean;
+  summary: {
+    adapter: "ready" | "missing" | "stale";
+    hookBridge: AgentHookBridgeState;
+    approvalRequired: boolean;
+    approvalStatus: AgentHookApprovalStatus;
+    nativeTrustStatus: AgentHookNativeTrustStatus;
+    memorySignals: number;
+    nativeSignals: number;
+    canarySignals: number;
+    generatedFresh: boolean;
+    generatedChanged: boolean;
+    generatedChangedFiles: number;
+    safeToEdit: boolean;
+    changedFiles: number;
+    primaryAction?: string;
+  };
+  steps: Array<{
+    name: string;
+    ok: boolean;
+    message: string;
+  }>;
+  recommendedReadFiles: string[];
+  commands: {
+    changed: string;
+    dev: string;
+    context: string;
+    verify: string;
+    hooksStatus?: string;
+    hooksSmoke?: string;
+    open?: string;
+  };
+  nextActions: string[];
+  diagnostics: Diagnostic[];
+  exitCode: 0 | 1;
+}
+
+export interface AgentHooksSmokeResult {
+  ok: boolean;
+  target: AgentAdapterTarget;
+  installTarget?: string;
+  smokeReady: boolean;
+  trustedNativeReady: boolean;
+  readinessLevel: AgentHookReadinessLevel;
+  installed: boolean;
+  bridgeWritable: boolean;
+  deltaWritable: boolean;
+  visibleInMemory: boolean;
+  usefulSignals: number;
+  nativeSignals: number;
+  canarySignals: number;
+  approvalRequired: boolean;
+  approvalStatus: AgentHookApprovalStatus;
+  nativeTrustStatus: AgentHookNativeTrustStatus;
+  lastSignal?: {
+    kind: string;
+    summary?: string;
+    capturedAt: string;
+    workspaceRoot?: string;
+  };
+  canary?: {
+    marker: string;
+    source: string;
+    eventName: string;
+    ingestedEventId?: string;
+    memoryEventsChecked: number;
+    visible: boolean;
+  };
+  hookRunnerProbe?: {
+    ok: boolean;
+    durationMs: number;
+    exitCode: number | null;
+    queued: boolean;
+    stdinHangSafe: boolean;
+    stdinHangDurationMs?: number;
+    error?: string;
+  };
   checks: Array<{ name: string; ok: boolean; message?: string }>;
+  nextActions: string[];
+  installResult?: unknown;
+  ingestResult?: unknown;
+  diagnostics: Diagnostic[];
+  exitCode: 0 | 1;
+}
+
+export interface AgentHooksStatusResult {
+  ok: boolean;
+  target: AgentAdapterTarget;
+  installTarget?: string;
+  installed: boolean;
+  bridgeWritable: boolean;
+  deltaWritable: boolean;
+  visibleInMemory: boolean;
+  recentEvents: number;
+  queuedEvents?: number;
+  usefulSignals: number;
+  nativeSignals: number;
+  canarySignals: number;
+  approvalRequired: boolean;
+  approvalStatus: AgentHookApprovalStatus;
+  nativeTrustStatus: AgentHookNativeTrustStatus;
+  lastSignal?: {
+    kind: string;
+    summary?: string;
+    capturedAt: string;
+    workspaceRoot?: string;
+  };
+  workspaceRoot?: string;
+  ignoredOutOfWorkspaceEvents?: number;
+  checks: Array<{ name: string; ok: boolean; message?: string; evidence?: unknown }>;
+  nextActions: string[];
+  installResult?: unknown;
+  diagnostics: Diagnostic[];
+  exitCode: 0 | 1;
+}
+
+export interface AgentTimelineItem {
+  id: string;
+  source: string;
+  integration: string;
+  trustLevel: string;
+  kind: string;
+  capturedAt: string;
+  sessionId?: string;
+  turnId?: string;
+  summary?: string;
+  toolName?: string;
+  command?: string;
+  status?: string;
+  files: string[];
+  entries: string[];
+  proofs: string[];
+  confidence: number;
+}
+
+export interface AgentTimelineResult {
+  schemaVersion: "0.1.0";
+  ok: boolean;
+  timeline: "agent";
+  target: AgentAdapterTarget;
+  sourceFilter?: string;
+  summary: {
+    events: number;
+    sessions: number;
+    files: number;
+    entries: number;
+    proofs: number;
+    tools: number;
+    latestEventAt?: string;
+  };
+  events: AgentTimelineItem[];
+  files: string[];
+  entries: string[];
+  proofs: string[];
+  sessions: string[];
+  nextActions: string[];
   diagnostics: Diagnostic[];
   exitCode: 0 | 1;
 }

package/src/forge/agent-fabric/adapter.ts

@@ -0,0 +1,131 @@
+import { AgentFabricError } from "./errors.ts";
+import type {
+  AdapterManifest,
+  AdapterOutcomeResult,
+  AdapterStartResult,
+  AgentAdapter,
+  AttemptExecutionPermit,
+  Digest,
+  RuntimeObservation,
+  WorkerResultReport,
+} from "./types.ts";
+
+export interface DeterministicAdapterFixture {
+  effectiveRunSpecDigest: Digest;
+  outcomeStatus: "succeeded" | "failed";
+  resultDigest: Digest;
+  evidenceDigests?: readonly Digest[];
+}
+
+interface AttemptRecord {
+  permit: AttemptExecutionPermit;
+  startedAt: number;
+  cancelled: boolean;
+}
+
+export class DeterministicTestAdapter implements AgentAdapter {
+  private readonly fixtures = new Map<Digest, DeterministicAdapterFixture>();
+  private readonly attempts = new Map<string, AttemptRecord>();
+
+  constructor(
+    fixtures: readonly DeterministicAdapterFixture[],
+    private readonly now: () => number,
+  ) {
+    for (const fixture of fixtures) this.fixtures.set(fixture.effectiveRunSpecDigest, fixture);
+  }
+
+  manifest(): AdapterManifest {
+    return {
+      adapterId: "forge-agent-fabric/deterministic-test-adapter",
+      version: "0.1.0",
+      capabilities: ["deterministic_fixture_execution", "observation", "cancellation"],
+      supportsCancellation: true,
+      supportsObservation: true,
+    };
+  }
+
+  async startAttempt(permit: AttemptExecutionPermit): Promise<AdapterStartResult> {
+    const existing = this.attempts.get(permit.attemptId);
+    if (existing) {
+      if (existing.permit.permitId !== permit.permitId) {
+        throw new AgentFabricError(
+          "AF_CONFLICT",
+          `Attempt ${permit.attemptId} was started with a different permit`,
+        );
+      }
+      return {
+        status: "started",
+        report: {
+          startupReportId: `startup:${permit.attemptId}`,
+          attemptId: permit.attemptId,
+          observedSpecDigest: permit.effectiveRunSpecDigest,
+          startedAt: existing.startedAt,
+        },
+      };
+    }
+    if (!this.fixtures.has(permit.effectiveRunSpecDigest)) {
+      return { status: "unknown", reason: "fixture_not_found" };
+    }
+    const startedAt = this.now();
+    this.attempts.set(permit.attemptId, { permit, startedAt, cancelled: false });
+    return {
+      status: "started",
+      report: {
+        startupReportId: `startup:${permit.attemptId}`,
+        attemptId: permit.attemptId,
+        observedSpecDigest: permit.effectiveRunSpecDigest,
+        startedAt,
+      },
+    };
+  }
+
+  async observeAttempt(attemptId: string): Promise<readonly RuntimeObservation[]> {
+    const attempt = this.attempts.get(attemptId);
+    if (!attempt) return [];
+    return [
+      {
+        observationId: `observation:${attemptId}:adapter-state`,
+        attemptId,
+        sourceClass: "adapter_observation",
+        claim: attempt.cancelled ? "cancelled" : "running_or_completed",
+        observedAt: this.now(),
+      },
+    ];
+  }
+
+  async collectOutcome(attemptId: string): Promise<AdapterOutcomeResult> {
+    const attempt = this.attempts.get(attemptId);
+    if (!attempt) return { status: "unknown", reason: "attempt_not_observed" };
+    if (attempt.cancelled) return { status: "unknown", reason: "attempt_cancelled" };
+    const fixture = this.fixtures.get(attempt.permit.effectiveRunSpecDigest);
+    if (!fixture) return { status: "unknown", reason: "fixture_not_found" };
+    const permit = attempt.permit;
+    const report: WorkerResultReport = {
+      reportId: `report:${attemptId}`,
+      attemptId,
+      permitId: permit.permitId,
+      intentId: permit.intentId,
+      planRevisionId: permit.planRevisionId,
+      effectiveRunSpecDigest: permit.effectiveRunSpecDigest,
+      fencingToken: permit.fencingToken,
+      status: fixture.outcomeStatus,
+      resultDigest: fixture.resultDigest,
+      evidenceDigests: fixture.evidenceDigests ?? [],
+      reportedAt: this.now(),
+    };
+    return { status: "reported", report };
+  }
+
+  async requestCancellation(attemptId: string): Promise<{ acknowledged: boolean }> {
+    const attempt = this.attempts.get(attemptId);
+    if (!attempt) return { acknowledged: false };
+    attempt.cancelled = true;
+    return { acknowledged: true };
+  }
+
+  async observeTermination(attemptId: string): Promise<"terminated" | "running" | "unknown"> {
+    const attempt = this.attempts.get(attemptId);
+    if (!attempt) return "unknown";
+    return attempt.cancelled ? "terminated" : "running";
+  }
+}

package/src/forge/agent-fabric/attached-snapshot.ts

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { lstat, readFile } from "node:fs/promises";
+import { join, resolve, relative } from "node:path";
+import { promisify } from "node:util";
+import { stableStringify } from "./canonical.ts";
+import { attachedFail, attachedScope, type AttachedSnapshot } from "./attached-task-contract.ts";
+
+const exec = promisify(execFile);
+export function attachedDigest(value: string | Buffer): string { return createHash("sha256").update(value).digest("hex"); }
+async function git(root: string, args: string[]): Promise<string> {
+  const result = await exec("git", args, { cwd: root, windowsHide: true, encoding: "utf8", maxBuffer: 8 * 1024 * 1024, timeout: 10000 });
+  return result.stdout;
+}
+export async function attachedHead(root: string): Promise<string> { return (await git(root, ["rev-parse", "HEAD"])).trim(); }
+export async function assertAttachedSafePath(root: string, target: string): Promise<void> {
+  const rel = relative(resolve(root), resolve(target));
+  if (rel.startsWith("..") || resolve(target) === resolve(root)) attachedFail("AF_ATTACHED_PATH", "Path escapes repository");
+  let path = resolve(root);
+  for (const part of rel.split(/[\\/]/u)) {
+    path = join(path, part);
+    try { if ((await lstat(path)).isSymbolicLink()) attachedFail("AF_ATTACHED_PATH", "Symlink paths are unsupported"); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+}
+/** Hashes actual working files, including nonignored untracked files and deletions. */
+export async function captureAttachedSnapshot(root: string, scopeInput: string[], baseHead: string): Promise<AttachedSnapshot> {
+  const scope = attachedScope(scopeInput);
+  const currentHead = await attachedHead(root);
+  const listing = await git(root, ["--literal-pathspecs", "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...scope]);
+  const paths = [...new Set(listing.split("\0").filter(Boolean))].filter((path) => !path.startsWith(".forge/local/")).sort();
+  if (paths.length > 4000) attachedFail("AF_ATTACHED_SNAPSHOT_LIMIT", "Scope exceeds 4000 files");
+  let size = 0;
+  const files: AttachedSnapshot["files"] = [];
+  for (const path of paths) {
+    const absolute = join(root, path);
+    await assertAttachedSafePath(root, absolute);
+    try {
+      const stat = await lstat(absolute);
+      if (!stat.isFile()) attachedFail("AF_ATTACHED_PATH", `Unsupported snapshot entry: ${path}`);
+      size += stat.size;
+      if (stat.size > 16 * 1024 * 1024 || size > 128 * 1024 * 1024) attachedFail("AF_ATTACHED_SNAPSHOT_LIMIT", "Snapshot byte limit exceeded");
+      const bytes = await readFile(absolute);
+      const after = await lstat(absolute);
+      if (after.isSymbolicLink() || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) attachedFail("AF_ATTACHED_SNAPSHOT_CHANGED", `File changed during capture: ${path}`);
+      files.push({ path, digest: attachedDigest(bytes), mode: stat.mode & 0o111 });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      files.push({ path, digest: null, mode: null });
+    }
+  }
+  if (currentHead !== await attachedHead(root)) attachedFail("AF_ATTACHED_SNAPSHOT_CHANGED", "Git HEAD changed during capture");
+  const content = { baseHead, currentHead, scope, files };
+  return { ...content, digest: attachedDigest(stableStringify(content)) };
+}

package/src/forge/agent-fabric/attached-task-contract.ts

@@ -0,0 +1,105 @@
+import { stableStringify } from "./canonical.ts";
+import { validateWorkflowState, type WorkflowState } from "./workflow-engine.ts";
+
+export interface AttachedSnapshot {
+  digest: string;
+  baseHead: string;
+  currentHead: string;
+  scope: string[];
+  files: { path: string; digest: string | null; mode: number | null }[];
+}
+export interface AttachedAssignment { assignmentId: string; role: "implementer" | "reviewer"; sessionId: string; agentId: string }
+export interface AttachedAttempt { attemptId: string; assignmentId: string; status: "running" | "succeeded" | "failed" | "uncertain" }
+export interface AttachedReview {
+  reviewToken: string; snapshotDigest: string; reviewerAttemptId: string; implementationAttemptId: string;
+  verdict: "approved" | "changes_requested";
+  findings: { findingId: string; description: string; resolved: boolean }[];
+  provenance: "agent_reported";
+}
+export interface AttachedTaskState {
+  schemaVersion: 1; taskId: string; version: number; goal: string;
+  criteria: { criterionId: string; description: string }[];
+  scope: string[]; baseHead: string; requiredChecks: string[];
+  sessions: { sessionId: string; agentId: string }[];
+  assignments: AttachedAssignment[]; attempts: AttachedAttempt[];
+  preparedReviews: { reviewToken: string; snapshot: AttachedSnapshot; reviewerAttemptId: string; implementationAttemptId: string }[];
+  review?: AttachedReview;
+  verifications: { checkId: string; snapshotDigest: string; outcome: "passed" | "failed" | "inconclusive"; command: string; summary: string; provenance: "agent_reported" }[];
+  coverage: { criterionId: string; snapshotDigest: string; evidence: string; provenance: "agent_reported" }[];
+  workflow?: import("./workflow-task-actions.ts").WorkflowState;
+  workflowSnapshots?: { nodeId: string; attemptId: string; snapshotDigest: string }[];
+}
+export class AttachedTaskError extends Error {
+  constructor(public readonly code: string, message: string) { super(message); this.name = "AttachedTaskError"; }
+}
+export function attachedFail(code: string, message: string): never { throw new AttachedTaskError(code, message); }
+export function attachedObject(value: unknown, keys: string[], maxBytes = 128 * 1024): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) attachedFail("AF_ATTACHED_INPUT", "Expected a plain object");
+  const body = value as Record<string, unknown>;
+  stableStringify(body);
+  if (Buffer.byteLength(stableStringify(body)) > maxBytes) attachedFail("AF_ATTACHED_INPUT", "Payload exceeds size limit");
+  for (const key of Object.keys(body)) if (!keys.includes(key)) attachedFail("AF_ATTACHED_INPUT", `Unknown field: ${key}`);
+  return body;
+}
+export function attachedText(value: unknown, label: string, max = 4096): string {
+  if (typeof value !== "string" || !value.trim() || value.length > max || value.includes("\0")) attachedFail("AF_ATTACHED_INPUT", `Invalid ${label}`);
+  return value;
+}
+export function attachedId(value: unknown, label: string): string {
+  const text = attachedText(value, label, 128);
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/u.test(text) || ["__proto__", "constructor", "prototype"].includes(text)) attachedFail("AF_ATTACHED_INPUT", `Invalid ${label}`);
+  return text;
+}
+export function attachedList(value: unknown, label: string, max = 128): unknown[] {
+  if (!Array.isArray(value) || value.length > max) attachedFail("AF_ATTACHED_INPUT", `Invalid ${label}`);
+  return value;
+}
+export function attachedUnique(values: string[], label: string): void {
+  if (new Set(values).size !== values.length) attachedFail("AF_ATTACHED_INPUT", `Duplicate ${label}`);
+}
+export function attachedScope(value: unknown): string[] {
+  const scope = attachedList(value, "scope").map((item) => {
+    const path = attachedText(item, "scope path", 512).replace(/\\/gu, "/");
+    if (path !== "." && (path.startsWith("/") || path.split("/").some((part) => !part || part === ".." || part === "." || part === ".git") || path.includes(":"))) attachedFail("AF_ATTACHED_INPUT", "Scope must contain repository relative paths");
+    if (path.startsWith(".forge/local")) attachedFail("AF_ATTACHED_INPUT", "Runtime store cannot be task scope");
+    return path;
+  });
+  if (!scope.length) attachedFail("AF_ATTACHED_INPUT", "Scope cannot be empty");
+  attachedUnique(scope, "scope"); return scope.sort();
+}
+
+/** Validate persisted JSON before it participates in transitions. */
+export function validateAttachedTaskState(value: unknown): AttachedTaskState {
+  const state = attachedObject(value, ["schemaVersion", "taskId", "version", "goal", "criteria", "scope", "baseHead", "requiredChecks", "sessions", "assignments", "attempts", "preparedReviews", "review", "verifications", "coverage", "workflow", "workflowSnapshots"], 16 * 1024 * 1024);
+  if (state.schemaVersion !== 1 || !Number.isSafeInteger(state.version) || (state.version as number) < 1) attachedFail("AF_ATTACHED_STORE", "Invalid task version");
+  attachedId(state.taskId, "taskId"); attachedText(state.goal, "goal"); attachedScope(state.scope);
+  if (!/^[0-9a-f]{40,64}$/u.test(attachedText(state.baseHead, "baseHead", 64))) attachedFail("AF_ATTACHED_STORE", "Invalid baseHead");
+  const criteria = attachedList(state.criteria, "criteria"); if (!criteria.length) attachedFail("AF_ATTACHED_STORE", "Missing criteria");
+  const criterionIds = criteria.map((item) => { const c = attachedObject(item, ["criterionId", "description"]); attachedText(c.description, "description"); return attachedId(c.criterionId, "criterionId"); }); attachedUnique(criterionIds, "criteria");
+  const checks = attachedList(state.requiredChecks, "checks").map((item) => attachedId(item, "checkId")); attachedUnique(checks, "checks");
+  const sessions = attachedList(state.sessions, "sessions", 2048).map((item) => { const s = attachedObject(item, ["sessionId", "agentId"]); return { sessionId: attachedId(s.sessionId, "sessionId"), agentId: attachedId(s.agentId, "agentId") }; });
+  const assignments = attachedList(state.assignments, "assignments", 2048).map((item) => { const a = attachedObject(item, ["assignmentId", "role", "sessionId", "agentId"]); attachedId(a.sessionId, "sessionId"); attachedId(a.agentId, "agentId"); if (!["implementer", "reviewer"].includes(a.role as string) || !sessions.some((s) => s.sessionId === a.sessionId && s.agentId === a.agentId)) attachedFail("AF_ATTACHED_STORE", "Invalid assignment"); return attachedId(a.assignmentId, "assignmentId"); }); attachedUnique(assignments, "assignments");
+  const attempts = attachedList(state.attempts, "attempts", 4096).map((item) => { const a = attachedObject(item, ["attemptId", "assignmentId", "status"]); if (!assignments.includes(attachedId(a.assignmentId, "assignmentId")) || !["running", "succeeded", "failed", "uncertain"].includes(a.status as string)) attachedFail("AF_ATTACHED_STORE", "Invalid attempt"); return attachedId(a.attemptId, "attemptId"); }); attachedUnique(attempts, "attempts");
+  const digest = (value: unknown) => { if (!/^[0-9a-f]{64}$/u.test(attachedText(value, "digest", 64))) attachedFail("AF_ATTACHED_STORE", "Invalid digest"); };
+  for (const item of attachedList(state.preparedReviews, "preparedReviews", 4096)) {
+    const r = attachedObject(item, ["reviewToken", "snapshot", "reviewerAttemptId", "implementationAttemptId"], 4 * 1024 * 1024);
+    attachedText(r.reviewToken, "reviewToken", 128);
+    if (!attempts.includes(attachedId(r.reviewerAttemptId, "reviewerAttemptId")) || !attempts.includes(attachedId(r.implementationAttemptId, "implementationAttemptId"))) attachedFail("AF_ATTACHED_STORE", "Unknown review attempt");
+    const s = attachedObject(r.snapshot, ["digest", "baseHead", "currentHead", "scope", "files"], 4 * 1024 * 1024);
+    digest(s.digest); attachedText(s.baseHead, "baseHead", 64); attachedText(s.currentHead, "currentHead", 64); attachedScope(s.scope);
+    const paths = attachedList(s.files, "snapshot files", 4000).map((item) => {
+      const f = attachedObject(item, ["path", "digest", "mode"]);
+      const path = attachedScope([f.path])[0]!;
+      if (f.digest !== null) digest(f.digest);
+      if ((f.digest === null) !== (f.mode === null) || (f.mode !== null && (!Number.isInteger(f.mode) || (f.mode as number) < 0 || (f.mode as number) > 0o111))) attachedFail("AF_ATTACHED_STORE", "Invalid snapshot file mode");
+      return path;
+    });
+    attachedUnique(paths, "snapshot paths");
+  }
+  if (state.review !== undefined) { const r = attachedObject(state.review, ["reviewToken", "snapshotDigest", "reviewerAttemptId", "implementationAttemptId", "verdict", "findings", "provenance"]); digest(r.snapshotDigest); attachedText(r.reviewToken, "reviewToken", 128); if (!attempts.includes(attachedId(r.reviewerAttemptId, "reviewerAttemptId")) || !attempts.includes(attachedId(r.implementationAttemptId, "implementationAttemptId")) || !["approved", "changes_requested"].includes(r.verdict as string) || r.provenance !== "agent_reported") attachedFail("AF_ATTACHED_STORE", "Invalid review"); for (const item of attachedList(r.findings, "findings")) { const f = attachedObject(item, ["findingId", "description", "resolved"]); attachedId(f.findingId, "findingId"); attachedText(f.description, "description"); if (typeof f.resolved !== "boolean") attachedFail("AF_ATTACHED_STORE", "Invalid finding"); } }
+  for (const item of attachedList(state.verifications, "verifications", 4096)) { const v = attachedObject(item, ["checkId", "snapshotDigest", "outcome", "command", "summary", "provenance"]); if (!checks.includes(attachedId(v.checkId, "checkId")) || !["passed", "failed", "inconclusive"].includes(v.outcome as string) || v.provenance !== "agent_reported") attachedFail("AF_ATTACHED_STORE", "Invalid verification"); digest(v.snapshotDigest); attachedText(v.command, "command"); attachedText(v.summary, "summary"); }
+  for (const item of attachedList(state.coverage, "coverage", 4096)) { const c = attachedObject(item, ["criterionId", "snapshotDigest", "evidence", "provenance"]); if (!criterionIds.includes(attachedId(c.criterionId, "criterionId")) || c.provenance !== "agent_reported") attachedFail("AF_ATTACHED_STORE", "Invalid coverage"); digest(c.snapshotDigest); attachedText(c.evidence, "evidence"); }
+  if (state.workflow !== undefined) validateWorkflowState(state.workflow as WorkflowState);
+  if (state.workflowSnapshots !== undefined) for (const item of attachedList(state.workflowSnapshots, "workflowSnapshots", 4096)) { const entry = attachedObject(item, ["nodeId", "attemptId", "snapshotDigest"]); attachedId(entry.nodeId, "nodeId"); attachedId(entry.attemptId, "attemptId"); digest(entry.snapshotDigest); }
+  return state as unknown as AttachedTaskState;
+}