@etiquekit/etq 1.0.11 → 1.0.13

package/packages/control/src/session/runbook.ts

@@ -0,0 +1,431 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { assertSessionProject, ensureProjectBinding } from '../engagement/project';
+import { assertSharedMemoryScopeId, assertSharedMemoryText } from '../shared/sanitize';
+
+export const SESSION_NOTE_SECTIONS = ['plan', 'tool', 'retry', 'evidence', 'note'] as const;
+
+export type SessionNoteSection = (typeof SESSION_NOTE_SECTIONS)[number];
+
+export interface SessionRunbookManifest {
+  schema: 'session-runbook.v0';
+  session_id: string;
+  created_at: string;
+  updated_at: string;
+  creation_mode: 'explicit' | 'dynamic';
+  project_id: string;
+  project_ref: '.';
+  task_ref: string;
+  seat: string;
+  operator_principal: string | null;
+  owner_principal: string | null;
+  target_ref: string | null;
+  runbook_ref: string;
+  manifest_ref: string;
+  note_count: number;
+  ledger_boundary: {
+    global_governance_ledger: 'receipt_ref_only';
+    repo_local_session_ledger: 'runbook_and_manifest';
+    ephemeral_workspace: 'summarized_only';
+  };
+  authority_boundary: {
+    can_authorize: false;
+    can_merge: false;
+    can_close: false;
+    can_write_global_ledger: false;
+    session_record_is_authority: false;
+  };
+}
+
+export interface CreateSessionRunbookOptions {
+  projectRoot: string;
+  seat: string;
+  taskRef: string;
+  sessionId?: string;
+  operatorPrincipal?: string;
+  ownerPrincipal?: string;
+  targetRef?: string;
+  creationMode?: 'explicit' | 'dynamic';
+  at?: string;
+}
+
+export interface AppendSessionRunbookNoteOptions {
+  projectRoot: string;
+  sessionId: string;
+  section: SessionNoteSection;
+  message: string;
+  at?: string;
+}
+
+export interface SessionRunbookResult {
+  manifest: SessionRunbookManifest;
+  manifestPath: string;
+  runbookPath: string;
+}
+
+export interface SessionRunbookNoteResult extends SessionRunbookResult {
+  section: SessionNoteSection;
+  appended_at: string;
+}
+
+export interface MigrateSessionProjectBindingsOptions {
+  projectRoot: string;
+  dryRun?: boolean;
+  at?: string;
+}
+
+export interface MigrateSessionProjectBindingsResult {
+  schema: 'session-project-binding-migration.v0';
+  project_id: string;
+  project_ref: '.etiquette/project.yaml';
+  dry_run: boolean;
+  migrated: string[];
+  unchanged: string[];
+  authority_boundary: {
+    can_authorize: false;
+    can_merge: false;
+    can_close: false;
+    can_write_global_ledger: false;
+  };
+}
+
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$/;
+
+function assertIsoTimestamp(value: string): void {
+  if (!Number.isFinite(Date.parse(value))) {
+    throw new Error('--at must be an ISO-8601 timestamp');
+  }
+}
+
+function isoNow(at?: string): string {
+  const value = at ?? new Date().toISOString();
+  assertIsoTimestamp(value);
+  return new Date(value).toISOString();
+}
+
+function compactTimestamp(value: string): string {
+  return value.replace(/[-:.]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+
+function generateSessionId(createdAt: string): string {
+  return `session-${compactTimestamp(createdAt)}-${randomUUID().slice(0, 8)}`;
+}
+
+function assertSessionId(value: string): void {
+  if (!SESSION_ID_RE.test(value)) {
+    throw new Error('session id must be an opaque id using letters, numbers, _, ., or -');
+  }
+}
+
+function assertOptionalScopeId(value: string | undefined, fieldName: string): string | null {
+  if (value === undefined) return null;
+  assertSharedMemoryScopeId(value, fieldName);
+  return value;
+}
+
+function projectRelative(projectRoot: string, path: string): string {
+  const resolvedRoot = resolve(projectRoot);
+  const resolvedPath = resolve(path);
+  const rel = relative(resolvedRoot, resolvedPath);
+  if (rel.length === 0 || rel.startsWith('..') || rel.includes('\\')) {
+    throw new Error(`path must stay inside project root: ${path}`);
+  }
+  return rel;
+}
+
+function sessionDir(projectRoot: string, sessionId: string): string {
+  return join(projectRoot, 'docs', 'work', 'sessions', sessionId);
+}
+
+function manifestPath(projectRoot: string, sessionId: string): string {
+  return join(sessionDir(projectRoot, sessionId), 'session.json');
+}
+
+function runbookPath(projectRoot: string, sessionId: string): string {
+  return join(sessionDir(projectRoot, sessionId), 'RUNBOOK.md');
+}
+
+async function listSessionManifestFiles(projectRoot: string): Promise<string[]> {
+  const root = join(projectRoot, 'docs', 'work', 'sessions');
+  if (!existsSync(root)) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(root, entry.name, 'session.json'))
+    .filter((path) => existsSync(path));
+}
+
+function renderNullable(value: string | null): string {
+  return value ?? 'none';
+}
+
+function renderRunbook(manifest: SessionRunbookManifest): string {
+  return [
+    `# Session Runbook: ${manifest.session_id}`,
+    '',
+    `- Schema: \`${manifest.schema}\``,
+    `- Project ID: \`${manifest.project_id}\``,
+    `- Seat: \`${manifest.seat}\``,
+    `- Operator Principal: \`${renderNullable(manifest.operator_principal)}\``,
+    `- Owner Principal: \`${renderNullable(manifest.owner_principal)}\``,
+    `- Task: \`${manifest.task_ref}\``,
+    `- Target Ref: \`${renderNullable(manifest.target_ref)}\``,
+    `- Created At: \`${manifest.created_at}\``,
+    `- Creation Mode: \`${manifest.creation_mode}\``,
+    `- Manifest Ref: \`${manifest.manifest_ref}\``,
+    `- Runbook Ref: \`${manifest.runbook_ref}\``,
+    '',
+    '## Ledger Boundary',
+    '',
+    '- Global governance ledger: receipt/ref only.',
+    '- Repo-local session ledger: this runbook and `session.json` manifest.',
+    '- Ephemeral workspace logs: summarize outcomes; do not paste raw prompts, secrets, or full tool output.',
+    '- Authority: this session record is evidence only; it cannot authorize, merge, close, promote, or write global ledger truth.',
+    '',
+    '## Assumptions & Plan',
+    '',
+    '- _No entries yet._',
+    '',
+    '## Tool Summary',
+    '',
+    '- _No entries yet._',
+    '',
+    '## Retries & Corrections',
+    '',
+    '- _No entries yet._',
+    '',
+    '## Exit Evidence',
+    '',
+    '- _No entries yet._',
+    '',
+    '## Notes',
+    '',
+    '- _No entries yet._',
+    '',
+  ].join('\n');
+}
+
+function sectionHeading(section: SessionNoteSection): string {
+  switch (section) {
+    case 'plan':
+      return 'Assumptions & Plan';
+    case 'tool':
+      return 'Tool Summary';
+    case 'retry':
+      return 'Retries & Corrections';
+    case 'evidence':
+      return 'Exit Evidence';
+    case 'note':
+      return 'Notes';
+  }
+}
+
+function appendToSection(content: string, section: SessionNoteSection, line: string): string {
+  const marker = `## ${sectionHeading(section)}\n\n`;
+  const start = content.indexOf(marker);
+  if (start < 0) throw new Error(`runbook missing section: ${section}`);
+  const bodyStart = start + marker.length;
+  const nextSection = content.indexOf('\n## ', bodyStart);
+  const end = nextSection < 0 ? content.length : nextSection;
+  let body = content.slice(bodyStart, end);
+  body = body.replace('- _No entries yet._\n', '');
+  if (body.length > 0 && !body.endsWith('\n')) body = `${body}\n`;
+  body = `${body}${line}\n`;
+  return `${content.slice(0, bodyStart)}${body}${content.slice(end)}`;
+}
+
+async function writeManifest(path: string, manifest: SessionRunbookManifest): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+async function readManifest(path: string): Promise<SessionRunbookManifest> {
+  const parsed = JSON.parse(await readFile(path, 'utf-8')) as SessionRunbookManifest;
+  if (parsed.schema !== 'session-runbook.v0') {
+    throw new Error('session manifest schema must be session-runbook.v0');
+  }
+  return parsed;
+}
+
+function withRunbookProjectLine(content: string, projectId: string): string {
+  if (content.includes('- Project ID:')) return content;
+  const schemaLine = '- Schema: `session-runbook.v0`';
+  const index = content.indexOf(schemaLine);
+  if (index < 0) return content;
+  const lineEnd = content.indexOf('\n', index);
+  if (lineEnd < 0) return content;
+  return `${content.slice(0, lineEnd + 1)}- Project ID: \`${projectId}\`\n${content.slice(lineEnd + 1)}`;
+}
+
+export async function migrateSessionProjectBindings(
+  options: MigrateSessionProjectBindingsOptions,
+): Promise<MigrateSessionProjectBindingsResult> {
+  const projectRoot = resolve(options.projectRoot);
+  const project = await ensureProjectBinding(projectRoot, options.at);
+  const manifestFiles = await listSessionManifestFiles(projectRoot);
+  const migrated: string[] = [];
+  const unchanged: string[] = [];
+  const mismatched: string[] = [];
+
+  for (const manifestFile of manifestFiles) {
+    const raw = JSON.parse(await readFile(manifestFile, 'utf-8')) as Record<string, unknown>;
+    if (raw.schema !== 'session-runbook.v0') {
+      throw new Error(`session manifest schema must be session-runbook.v0: ${projectRelative(projectRoot, manifestFile)}`);
+    }
+    const sessionId = typeof raw.session_id === 'string' ? raw.session_id : projectRelative(projectRoot, manifestFile);
+    if (typeof raw.project_id === 'string') {
+      if (raw.project_id === project.project_id) unchanged.push(sessionId);
+      else mismatched.push(`${sessionId}=${raw.project_id}`);
+      continue;
+    }
+    migrated.push(sessionId);
+  }
+
+  if (mismatched.length > 0) {
+    throw new Error(
+      `session project_id mismatch; refusing migration: ${mismatched.join(', ')}; inspect or recreate those sessions`,
+    );
+  }
+
+  if (!options.dryRun) {
+    for (const manifestFile of manifestFiles) {
+      const raw = JSON.parse(await readFile(manifestFile, 'utf-8')) as Record<string, unknown>;
+      if (typeof raw.project_id === 'string') continue;
+      const updated = {
+        ...raw,
+        project_id: project.project_id,
+        project_ref: '.',
+      };
+      await writeFile(manifestFile, `${JSON.stringify(updated, null, 2)}\n`);
+      const runbookFile = join(dirname(manifestFile), 'RUNBOOK.md');
+      if (existsSync(runbookFile)) {
+        const runbook = await readFile(runbookFile, 'utf-8');
+        await writeFile(runbookFile, withRunbookProjectLine(runbook, project.project_id));
+      }
+    }
+  }
+
+  return {
+    schema: 'session-project-binding-migration.v0',
+    project_id: project.project_id,
+    project_ref: '.etiquette/project.yaml',
+    dry_run: Boolean(options.dryRun),
+    migrated,
+    unchanged,
+    authority_boundary: {
+      can_authorize: false,
+      can_merge: false,
+      can_close: false,
+      can_write_global_ledger: false,
+    },
+  };
+}
+
+export async function createSessionRunbook(options: CreateSessionRunbookOptions): Promise<SessionRunbookResult> {
+  const projectRoot = resolve(options.projectRoot);
+  const project = await ensureProjectBinding(projectRoot, options.at);
+  const createdAt = isoNow(options.at);
+  const sessionId = options.sessionId ?? generateSessionId(createdAt);
+  assertSessionId(sessionId);
+  assertSharedMemoryScopeId(options.seat, '--seat');
+  assertSharedMemoryScopeId(options.taskRef, '--task');
+
+  const operatorPrincipal = assertOptionalScopeId(options.operatorPrincipal, '--operator');
+  const ownerPrincipal = assertOptionalScopeId(options.ownerPrincipal, '--owner');
+  const targetRef = assertOptionalScopeId(options.targetRef, '--target-ref');
+  const creationMode = options.creationMode ?? 'explicit';
+
+  if (creationMode !== 'explicit' && creationMode !== 'dynamic') {
+    throw new Error('--creation-mode must be explicit or dynamic');
+  }
+
+  const manifestFile = manifestPath(projectRoot, sessionId);
+  const runbookFile = runbookPath(projectRoot, sessionId);
+  if (existsSync(manifestFile) || existsSync(runbookFile)) {
+    throw new Error(`session already exists: ${sessionId}`);
+  }
+
+  const manifest: SessionRunbookManifest = {
+    schema: 'session-runbook.v0',
+    session_id: sessionId,
+    created_at: createdAt,
+    updated_at: createdAt,
+    creation_mode: creationMode,
+    project_id: project.project_id,
+    project_ref: '.',
+    task_ref: options.taskRef,
+    seat: options.seat,
+    operator_principal: operatorPrincipal,
+    owner_principal: ownerPrincipal,
+    target_ref: targetRef,
+    runbook_ref: projectRelative(projectRoot, runbookFile),
+    manifest_ref: projectRelative(projectRoot, manifestFile),
+    note_count: 0,
+    ledger_boundary: {
+      global_governance_ledger: 'receipt_ref_only',
+      repo_local_session_ledger: 'runbook_and_manifest',
+      ephemeral_workspace: 'summarized_only',
+    },
+    authority_boundary: {
+      can_authorize: false,
+      can_merge: false,
+      can_close: false,
+      can_write_global_ledger: false,
+      session_record_is_authority: false,
+    },
+  };
+
+  await mkdir(dirname(runbookFile), { recursive: true });
+  await writeFile(runbookFile, renderRunbook(manifest));
+  await writeManifest(manifestFile, manifest);
+
+  return { manifest, manifestPath: manifestFile, runbookPath: runbookFile };
+}
+
+export async function appendSessionRunbookNote(options: AppendSessionRunbookNoteOptions): Promise<SessionRunbookNoteResult> {
+  const projectRoot = resolve(options.projectRoot);
+  const project = await ensureProjectBinding(projectRoot, options.at);
+  assertSessionId(options.sessionId);
+  if (!(SESSION_NOTE_SECTIONS as readonly string[]).includes(options.section)) {
+    throw new Error(`--section must be one of: ${SESSION_NOTE_SECTIONS.join(', ')}`);
+  }
+  assertSharedMemoryText(options.message, '--message');
+
+  const appendedAt = isoNow(options.at);
+  const manifestFile = manifestPath(projectRoot, options.sessionId);
+  const runbookFile = runbookPath(projectRoot, options.sessionId);
+  const manifest = await readManifest(manifestFile);
+  assertSessionProject(manifest.project_id, project.project_id, `session ${options.sessionId}`);
+  const runbook = await readFile(runbookFile, 'utf-8');
+  const line = `- ${appendedAt} - ${options.message}`;
+  await writeFile(runbookFile, appendToSection(runbook, options.section, line));
+
+  const updated: SessionRunbookManifest = {
+    ...manifest,
+    updated_at: appendedAt,
+    note_count: manifest.note_count + 1,
+  };
+  await writeManifest(manifestFile, updated);
+  await appendFile(join(sessionDir(projectRoot, options.sessionId), 'events.ndjson'), `${JSON.stringify({
+    schema: 'session-note-event.v0',
+    session_id: options.sessionId,
+    project_id: project.project_id,
+    at: appendedAt,
+    section: options.section,
+    message: options.message,
+    authority_boundary: {
+      can_authorize: false,
+      can_write_global_ledger: false,
+    },
+  })}\n`);
+
+  return {
+    manifest: updated,
+    manifestPath: manifestFile,
+    runbookPath: runbookFile,
+    section: options.section,
+    appended_at: appendedAt,
+  };
+}

package/packages/control/src/shared/sanitize.ts

@@ -0,0 +1,49 @@
+export const SHARED_RISK_FLAGS = [
+  'no_durable_evidence',
+  'stale',
+  'contains_private_context',
+  'contradicts_current_ledger',
+  'contains_raw_prompt',
+  'contains_raw_tool_output',
+  'contains_source_snippet',
+  'contains_local_path',
+  'contains_hostname',
+  'contains_credential',
+  'confidence_low_for_shared_export',
+] as const;
+
+export type SharedRiskFlag = (typeof SHARED_RISK_FLAGS)[number];
+
+const LOCAL_PATH_RE = /(?:\/Users\/|\/home\/|\/private\/|\/tmp\/|\$HOME|~\/|[A-Za-z]:\\)/;
+const HOSTNAME_RE = /\b[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*\.(?:local|lan|internal|intranet|localdomain)\b/i;
+const IPV4_RE = /\b\d{1,3}(?:\.\d{1,3}){3}\b/;
+const IPV6_RE = /\b(?:[0-9a-f]{1,4}:){2,}[0-9a-f]{0,4}\b/i;
+const CREDENTIAL_RE = /\b(?:ANTHROPIC_API_KEY|OPENAI_API_KEY|GEMINI_API_KEY|api[_-]?key|token|secret)\b\s*[:=]|sk-[A-Za-z0-9_-]{12,}/i;
+const RAW_PROMPT_RE = /\b(raw prompt|user prompt|prompt transcript|UserPromptSubmit)\b/i;
+const RAW_TOOL_RE = /\b(raw tool output|tool transcript|PostToolUse output|stdout:|stderr:)\b/i;
+const CODE_FENCE_RE = /```/;
+
+export function detectMemoryRiskFlags(value: string): SharedRiskFlag[] {
+  const flags = new Set<SharedRiskFlag>();
+  if (LOCAL_PATH_RE.test(value)) flags.add('contains_local_path');
+  if (HOSTNAME_RE.test(value) || IPV4_RE.test(value) || IPV6_RE.test(value)) flags.add('contains_hostname');
+  if (CREDENTIAL_RE.test(value)) flags.add('contains_credential');
+  if (RAW_PROMPT_RE.test(value)) flags.add('contains_raw_prompt');
+  if (RAW_TOOL_RE.test(value)) flags.add('contains_raw_tool_output');
+  if (CODE_FENCE_RE.test(value)) flags.add('contains_source_snippet');
+  return [...flags];
+}
+
+export function assertSharedMemoryText(value: string, fieldName: string): void {
+  const flags = detectMemoryRiskFlags(value);
+  if (flags.length > 0) {
+    throw new Error(`${fieldName} contains restricted shared-memory content: ${flags.join(', ')}`);
+  }
+}
+
+export function assertSharedMemoryScopeId(value: string, fieldName: string): void {
+  assertSharedMemoryText(value, fieldName);
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,79}$/.test(value)) {
+    throw new Error(`${fieldName} must be an opaque id using only letters, numbers, _, ., :, or -`);
+  }
+}

package/packages/control/src/supervision/action-classes.ts

@@ -0,0 +1,192 @@
+import type {
+  ActionClass,
+  AllowedCommandId,
+  SeatCapabilityManifest,
+  SupervisionTurn,
+} from '../../../protocol/src/index';
+
+export class ActionClassViolation extends Error {
+  constructor(
+    readonly actionClass: ActionClass,
+    readonly issues: string[],
+  ) {
+    super(`action class ${actionClass} violated: ${issues.join('; ')}`);
+    this.name = 'ActionClassViolation';
+  }
+}
+
+export interface TurnBoundsProposal {
+  allowedActionClass: ActionClass;
+  maxDurationMinutes: number;
+  allowedCommands: AllowedCommandId[];
+  repoRoots: string[];
+  ownedPaths: string[];
+  forbiddenPaths: string[];
+  verifyCommands: string[];
+  requiresHumanApproval: boolean;
+}
+
+function isSubset<T>(subset: readonly T[], universe: readonly T[]): boolean {
+  const set = new Set(universe);
+  return subset.every((v) => set.has(v));
+}
+
+/**
+ * Validate a turn bounds proposal against the charter's class rules.
+ * Does NOT validate seat capabilities — use `authorizeTurnForSeat` for that.
+ * Throws `ActionClassViolation` with every issue; returns silently on pass.
+ */
+export function validateTurnBounds(bounds: TurnBoundsProposal): void {
+  const issues: string[] = [];
+
+  if (!Number.isInteger(bounds.maxDurationMinutes) || bounds.maxDurationMinutes <= 0) {
+    issues.push('maxDurationMinutes must be a positive integer');
+  }
+
+  switch (bounds.allowedActionClass) {
+    case 'coordination_only': {
+      if (!isSubset(bounds.allowedCommands, ['write_projection', 'append_evidence'])) {
+        issues.push('allowedCommands must be a subset of {write_projection, append_evidence}');
+      }
+      if (bounds.repoRoots.length > 0) issues.push('repoRoots must be empty');
+      if (bounds.ownedPaths.length > 0) issues.push('ownedPaths must be empty');
+      if (bounds.forbiddenPaths.length > 0) issues.push('forbiddenPaths must be empty');
+      if (bounds.verifyCommands.length > 0) issues.push('verifyCommands must be empty');
+      break;
+    }
+    case 'read_only_local': {
+      if (!isSubset(bounds.allowedCommands, ['inspect_repo', 'write_projection', 'append_evidence'])) {
+        issues.push('allowedCommands must be a subset of {inspect_repo, write_projection, append_evidence}');
+      }
+      if (bounds.repoRoots.length === 0) issues.push('repoRoots must be non-empty');
+      if (bounds.ownedPaths.length > 0) issues.push('ownedPaths must be empty');
+      if (bounds.forbiddenPaths.length > 0) issues.push('forbiddenPaths must be empty');
+      if (bounds.verifyCommands.length > 0) issues.push('verifyCommands must be empty');
+      break;
+    }
+    case 'bounded_verification': {
+      if (!bounds.allowedCommands.includes('run_verify')) {
+        issues.push('allowedCommands must include run_verify');
+      }
+      if (
+        !isSubset(bounds.allowedCommands, [
+          'inspect_repo',
+          'run_verify',
+          'write_projection',
+          'append_evidence',
+        ])
+      ) {
+        issues.push('allowedCommands may only include {inspect_repo, run_verify, write_projection, append_evidence}');
+      }
+      if (bounds.repoRoots.length === 0) issues.push('repoRoots must be non-empty');
+      if (bounds.verifyCommands.length === 0) issues.push('verifyCommands must be non-empty');
+      if (bounds.ownedPaths.length > 0) issues.push('ownedPaths must be empty');
+      break;
+    }
+    case 'bounded_product_mutation': {
+      if (!bounds.allowedCommands.includes('write_product_files')) {
+        issues.push('allowedCommands must include write_product_files');
+      }
+      if (bounds.repoRoots.length === 0) issues.push('repoRoots must be non-empty');
+      if (bounds.ownedPaths.length === 0) issues.push('ownedPaths must be non-empty');
+      if (bounds.verifyCommands.length === 0) issues.push('verifyCommands must be non-empty');
+      if (!bounds.requiresHumanApproval) {
+        issues.push('requiresHumanApproval must be true for bounded_product_mutation');
+      }
+      break;
+    }
+    case 'human_only': {
+      issues.push('human_only turns may not be opened by automation');
+      break;
+    }
+    default: {
+      issues.push(`unknown action class: ${bounds.allowedActionClass satisfies never}`);
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new ActionClassViolation(bounds.allowedActionClass, issues);
+  }
+}
+
+/**
+ * Check that a seat manifest permits opening a turn of the proposed class.
+ * Per doctrine, `bounded_product_mutation` additionally requires an approval
+ * blob on the session; that check is caller's responsibility here.
+ */
+export function authorizeTurnForSeat(
+  bounds: TurnBoundsProposal,
+  seat: SeatCapabilityManifest,
+): void {
+  const issues: string[] = [];
+
+  if (!seat.allowedActionClasses.includes(bounds.allowedActionClass)) {
+    issues.push(
+      `seat ${seat.seatId} does not allow action class ${bounds.allowedActionClass}`,
+    );
+  }
+
+  if (bounds.allowedCommands.includes('run_verify') && !seat.canRunBuilds) {
+    issues.push(`seat ${seat.seatId} lacks canRunBuilds for run_verify`);
+  }
+
+  if (bounds.allowedCommands.includes('write_product_files') && !seat.canWriteProductRepo) {
+    issues.push(`seat ${seat.seatId} lacks canWriteProductRepo for write_product_files`);
+  }
+
+  if (bounds.allowedCommands.includes('launch_runtime_target') && !seat.canLaunchRuntimeTargets) {
+    issues.push(`seat ${seat.seatId} lacks canLaunchRuntimeTargets for launch_runtime_target`);
+  }
+
+  if (bounds.allowedActionClass === 'bounded_product_mutation' && !bounds.requiresHumanApproval) {
+    issues.push('bounded_product_mutation requires requiresHumanApproval=true');
+  }
+
+  if (issues.length > 0) {
+    throw new ActionClassViolation(bounds.allowedActionClass, issues);
+  }
+}
+
+/**
+ * Exact-match comparison between a requested turn and a previously stored
+ * approval blob. Used for `approve_next_turn` enforcement: opening a turn
+ * while an approval is present requires all bounds to match exactly.
+ */
+export function turnMatchesApproval(
+  requested: TurnBoundsProposal & { ownerSeat: string; projectionPolicy: SupervisionTurn['projectionPolicy'] },
+  approval: {
+    ownerSeat: string;
+    allowedActionClass: ActionClass;
+    maxDurationMinutes: number;
+    allowedCommands: AllowedCommandId[];
+    repoRoots: string[];
+    ownedPaths: string[];
+    forbiddenPaths: string[];
+    verifyCommands: string[];
+    requiresHumanApproval: boolean;
+    projectionPolicy: SupervisionTurn['projectionPolicy'];
+  },
+): { matches: boolean; diffs: string[] } {
+  const diffs: string[] = [];
+  const eq = <T>(a: T, b: T, label: string): void => {
+    if (a !== b) diffs.push(`${label}: requested=${String(a)} vs approved=${String(b)}`);
+  };
+  const eqList = (a: readonly string[], b: readonly string[], label: string): void => {
+    const sa = [...a].sort();
+    const sb = [...b].sort();
+    if (sa.length !== sb.length || sa.some((v, i) => v !== sb[i])) {
+      diffs.push(`${label}: requested=[${sa.join(',')}] vs approved=[${sb.join(',')}]`);
+    }
+  };
+  eq(requested.ownerSeat, approval.ownerSeat, 'ownerSeat');
+  eq(requested.allowedActionClass, approval.allowedActionClass, 'allowedActionClass');
+  eq(requested.maxDurationMinutes, approval.maxDurationMinutes, 'maxDurationMinutes');
+  eq(requested.requiresHumanApproval, approval.requiresHumanApproval, 'requiresHumanApproval');
+  eq(requested.projectionPolicy, approval.projectionPolicy, 'projectionPolicy');
+  eqList(requested.allowedCommands, approval.allowedCommands, 'allowedCommands');
+  eqList(requested.repoRoots, approval.repoRoots, 'repoRoots');
+  eqList(requested.ownedPaths, approval.ownedPaths, 'ownedPaths');
+  eqList(requested.forbiddenPaths, approval.forbiddenPaths, 'forbiddenPaths');
+  eqList(requested.verifyCommands, approval.verifyCommands, 'verifyCommands');
+  return { matches: diffs.length === 0, diffs };
+}