@etiquekit/etq 1.0.11 → 1.0.13

package/packages/control/src/seat/readiness.ts

@@ -0,0 +1,834 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { writeJson } from '../fs';
+
+export const SEAT_READINESS_SCHEMA = 'seat-readiness.v0.1';
+export const SEAT_READINESS_EVENT_SCHEMA = 'seat-readiness-event.v0.1';
+export const SEAT_PROFILE_SCHEMA = 'seat_profile.v0';
+export const SEAT_PREFLIGHT_SCHEMA = 'seat_preflight.v0';
+export const SEAT_PREFLIGHT_RESULT_SCHEMA = 'seat_preflight_result.v0';
+export const CODEX_PERMISSIONS_ADAPTER_SCHEMA = 'codex_permissions_adapter.v0';
+
+export const SEAT_TYPES = [
+  'control_seat',
+  'execution_seat',
+  'review_seat',
+  'seat_maintainer',
+] as const;
+export const OPERATIONAL_STATUSES = ['operational', 'degraded', 'blocked', 'offline'] as const;
+export const CAPABILITY_SOURCES = [
+  'config',
+  'local_validation',
+  'seat_doctor',
+  'agent_self_declared',
+] as const;
+export const MODEL_TIERS = [
+  'lite_fast',
+  'balanced',
+  'frontier_high_reasoning',
+  'local_unknown',
+] as const;
+export const SEAT_PROFILE_ROLES = [
+  'implementation',
+  'review',
+  'orchestration',
+  'satellite',
+  'advisory',
+] as const;
+export const SEAT_MONITOR_MODES = ['pull', 'push'] as const;
+export const CODEX_PERMISSION_ACCESS = ['read', 'write', 'deny'] as const;
+export const SEAT_PREFLIGHT_REQUIRED_CHECKS = [
+  'identity',
+  'workflow_binding',
+  'routing_surface',
+  'evidence_surface',
+  'monitor_skill',
+  'authority_boundary',
+] as const;
+
+export type SeatType = typeof SEAT_TYPES[number];
+export type OperationalStatus = typeof OPERATIONAL_STATUSES[number];
+export type CapabilitySource = typeof CAPABILITY_SOURCES[number];
+export type ModelTier = typeof MODEL_TIERS[number];
+export type SeatProfileRole = typeof SEAT_PROFILE_ROLES[number];
+export type SeatMonitorMode = typeof SEAT_MONITOR_MODES[number];
+export type CodexPermissionAccess = typeof CODEX_PERMISSION_ACCESS[number];
+export type SeatPreflightRequiredCheck = typeof SEAT_PREFLIGHT_REQUIRED_CHECKS[number];
+
+type JsonRecord = Record<string, unknown>;
+
+export interface CodexFilesystemPermissionRule {
+  path: string;
+  access: CodexPermissionAccess;
+}
+
+export interface CodexNetworkPermissionRule {
+  host: string;
+  access: 'allow' | 'deny';
+}
+
+export interface CodexPermissionsAdapter {
+  schema: typeof CODEX_PERMISSIONS_ADAPTER_SCHEMA;
+  profile_ref: string;
+  filesystem: CodexFilesystemPermissionRule[];
+  network: {
+    enabled: boolean;
+    domains: CodexNetworkPermissionRule[];
+    allow_local_binding: boolean;
+  };
+  authority_boundary: {
+    permissions_grant_authority: false;
+    mutates_codex_config: false;
+    installs_profile: false;
+  };
+}
+
+export interface SeatProfile {
+  schema: typeof SEAT_PROFILE_SCHEMA;
+  profile_id: string;
+  permission_profile_ref?: string;
+  seat_role: SeatProfileRole;
+  monitor_mode: SeatMonitorMode;
+  preloaded_skills: string[];
+  manuals: string[];
+  required_preflight: SeatPreflightRequiredCheck[];
+  forbidden_defaults: string[];
+  authority_defaults: {
+    grants_authority: false;
+    can_merge: false;
+    can_close: false;
+    can_push: false;
+    can_mutate_global_agent_config: false;
+    can_auto_start_monitor: false;
+  };
+}
+
+export interface SeatPreflight {
+  schema: typeof SEAT_PREFLIGHT_SCHEMA;
+  seat_id?: string;
+  operator_principal?: string;
+  profile_id?: string;
+  project_id?: string;
+  workflow_id?: string;
+  task_ref?: string;
+  routing_surface?: string;
+  evidence_surface?: string;
+  monitor_mode?: SeatMonitorMode;
+  allowed_writes?: string[];
+  network_required?: boolean;
+  network_domains?: string[];
+  codex_permissions?: CodexPermissionsAdapter;
+  checks?: Partial<Record<SeatPreflightRequiredCheck, boolean>>;
+  authority_boundary?: {
+    defaults_grant_authority?: boolean;
+    task_packet_required?: boolean;
+    can_merge?: boolean;
+    can_close?: boolean;
+    can_push?: boolean;
+    can_mutate_global_agent_config?: boolean;
+    can_auto_start_monitor?: boolean;
+  };
+}
+
+export interface SeatPreflightResult {
+  schema: typeof SEAT_PREFLIGHT_RESULT_SCHEMA;
+  seat_id: string | null;
+  profile_id: string;
+  ready: boolean;
+  monitor_mode: SeatMonitorMode;
+  missing: string[];
+  failed: string[];
+  warnings: string[];
+  permission_profile_ref: string | null;
+  authority_boundary: {
+    defaults_grant_authority: false;
+    profile_grants_authority: false;
+    permissions_grant_authority: false;
+    monitor_autostart: false;
+    mutates_global_agent_config: false;
+    mutates_codex_config: false;
+    installs_permission_profile: false;
+    can_merge: false;
+    can_close: false;
+    can_push: false;
+  };
+}
+
+export interface SeatReadinessRecord {
+  schema_version: typeof SEAT_READINESS_SCHEMA;
+  seat: string;
+  seat_type: SeatType;
+  execution_surface: string;
+  declared_by: 'operator_principal' | 'config';
+  capability_source: CapabilitySource;
+  capability_trusted: boolean;
+  operational_status: OperationalStatus;
+  model_tier: ModelTier;
+  model_id?: string;
+  active_workers: number;
+  max_recommended_workers: number;
+  supports_parallel: boolean;
+  supported_strategies: string[];
+  unsupported_strategies: string[];
+  constraints: string[];
+  last_checked_at: string;
+  last_heartbeat_at: string;
+  ttl_seconds: number;
+  stale_after: string;
+}
+
+export interface SeatReadinessStatus extends SeatReadinessRecord {
+  checked_at: string;
+  is_stale: boolean;
+  effective_model_tier: ModelTier;
+  routing_recommendation:
+    | 'route_if_policy_allows'
+    | 'seek_validation'
+    | 'reject_or_refresh'
+    | 'defer_with_reason';
+}
+
+export interface ReadinessInput {
+  projectRoot: string;
+  statePath?: string;
+  seat: string;
+  seatType: SeatType;
+  executionSurface: string;
+  declaredBy: 'operator_principal' | 'config';
+  capabilitySource: CapabilitySource;
+  operationalStatus: OperationalStatus;
+  modelTier: ModelTier;
+  modelId?: string;
+  activeWorkers: number;
+  maxRecommendedWorkers: number;
+  supportsParallel: boolean;
+  supportedStrategies: string[];
+  unsupportedStrategies: string[];
+  constraints: string[];
+  at?: string;
+}
+
+export interface HeartbeatInput {
+  projectRoot: string;
+  statePath?: string;
+  seat?: string;
+  operationalStatus?: OperationalStatus;
+  activeWorkers?: number;
+  constraints?: string[];
+  at?: string;
+}
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function requireRecord(value: unknown, name: string): JsonRecord {
+  if (!isRecord(value)) throw new Error(`${name} must be an object`);
+  return value;
+}
+
+function requireString(record: JsonRecord, key: string): string {
+  const value = record[key];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${key} is required`);
+  }
+  return value.trim();
+}
+
+function optionalString(record: JsonRecord, key: string): string | undefined {
+  const value = record[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${key} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalStringArray(record: JsonRecord, key: string): string[] {
+  const value = record[key];
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${key} must be a string array`);
+  return value.map((item, index) => {
+    if (typeof item !== 'string' || item.trim().length === 0) {
+      throw new Error(`${key}[${index}] must be a non-empty string`);
+    }
+    return item.trim();
+  });
+}
+
+function assertSafeRef(value: string, name: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,127}$/.test(value)) {
+    throw new Error(`${name} must be an opaque ref using letters, numbers, hyphen, underscore, dot, colon, or at-sign`);
+  }
+}
+
+function assertRelativeTaskPath(value: string, name: string): void {
+  if (value.startsWith('/') || value.startsWith('~') || value.includes('\\')) {
+    throw new Error(`${name} must be a workspace-relative path`);
+  }
+  const parts = value.split('/').filter(Boolean);
+  if (parts.length === 0 || parts.includes('..')) throw new Error(`${name} must be a workspace-relative path`);
+  if (/[\u0000-\u001f]/.test(value)) throw new Error(`${name} must not contain control characters`);
+}
+
+function optionalBoolean(record: JsonRecord, key: string, fallback: boolean): boolean {
+  const value = record[key];
+  if (value === undefined) return fallback;
+  if (typeof value !== 'boolean') throw new Error(`${key} must be a boolean`);
+  return value;
+}
+
+function assertFalseValue(value: unknown, name: string): void {
+  if (value !== false) throw new Error(`${name} must be false`);
+}
+
+function optionalFalseValue(record: JsonRecord, key: string): false {
+  if (record[key] === undefined) return false;
+  assertFalseValue(record[key], key);
+  return false;
+}
+
+function requireBooleanTrue(value: unknown, name: string): boolean {
+  if (value !== true) throw new Error(`${name} must be true`);
+  return true;
+}
+
+function parseFilesystemRule(raw: unknown, index: number): CodexFilesystemPermissionRule {
+  const record = requireRecord(raw, `filesystem[${index}]`);
+  const path = requireString(record, 'path');
+  if (!['.', ':workspace_roots'].includes(path) && !path.startsWith(':') && !path.includes('*')) {
+    assertRelativeTaskPath(path, `filesystem[${index}].path`);
+  }
+  const access = requireString(record, 'access');
+  assertKnown(CODEX_PERMISSION_ACCESS, access, `filesystem[${index}].access`);
+  return { path, access };
+}
+
+function parseDomainRule(raw: unknown, index: number): CodexNetworkPermissionRule {
+  const record = requireRecord(raw, `network.domains[${index}]`);
+  const host = requireString(record, 'host');
+  if (host !== '*' && !/^(?:\*\.|\*\*\.)?[A-Za-z0-9][A-Za-z0-9.-]{0,252}$/.test(host)) {
+    throw new Error(`network.domains[${index}].host must be a host, scoped wildcard, or *`);
+  }
+  const access = requireString(record, 'access');
+  assertKnown(['allow', 'deny'] as const, access, `network.domains[${index}].access`);
+  return { host, access };
+}
+
+export function normalizeCodexPermissionsAdapter(raw: unknown): CodexPermissionsAdapter {
+  const record = requireRecord(raw, 'codex permissions adapter');
+  if (record.schema !== CODEX_PERMISSIONS_ADAPTER_SCHEMA) {
+    throw new Error(`schema must be ${CODEX_PERMISSIONS_ADAPTER_SCHEMA}`);
+  }
+  const profileRef = requireString(record, 'profile_ref');
+  assertSafeRef(profileRef, 'profile_ref');
+  const filesystemRaw = record.filesystem;
+  if (!Array.isArray(filesystemRaw) || filesystemRaw.length === 0) {
+    throw new Error('filesystem must contain at least one permission rule');
+  }
+  const network = requireRecord(record.network, 'network');
+  const domainsRaw = network.domains;
+  const domains = domainsRaw === undefined ? [] : (() => {
+    if (!Array.isArray(domainsRaw)) throw new Error('network.domains must be an array');
+    return domainsRaw.map(parseDomainRule);
+  })();
+  const authority = requireRecord(record.authority_boundary, 'authority_boundary');
+  return {
+    schema: CODEX_PERMISSIONS_ADAPTER_SCHEMA,
+    profile_ref: profileRef,
+    filesystem: filesystemRaw.map(parseFilesystemRule),
+    network: {
+      enabled: optionalBoolean(network, 'enabled', false),
+      domains,
+      allow_local_binding: optionalBoolean(network, 'allow_local_binding', false),
+    },
+    authority_boundary: {
+      permissions_grant_authority: optionalFalseValue(authority, 'permissions_grant_authority'),
+      mutates_codex_config: optionalFalseValue(authority, 'mutates_codex_config'),
+      installs_profile: optionalFalseValue(authority, 'installs_profile'),
+    },
+  };
+}
+
+function permissionAccessRank(access: CodexPermissionAccess): number {
+  if (access === 'deny') return 3;
+  if (access === 'write') return 2;
+  return 1;
+}
+
+function globPatternToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\u0000/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function filesystemRuleMatches(rulePath: string, taskPath: string): boolean {
+  if (rulePath === '.' || rulePath === ':workspace_roots') return true;
+  if (rulePath.endsWith('/**')) return taskPath === rulePath.slice(0, -3) || taskPath.startsWith(rulePath.slice(0, -2));
+  if (rulePath.includes('*')) return globPatternToRegex(rulePath).test(taskPath);
+  return taskPath === rulePath || taskPath.startsWith(`${rulePath}/`);
+}
+
+function filesystemRuleSpecificity(rulePath: string): number {
+  if (rulePath === '.' || rulePath === ':workspace_roots') return 0;
+  return rulePath.replace(/\*/g, '').length;
+}
+
+export function codexFilesystemAccessForPath(adapterRaw: unknown, taskPath: string): CodexPermissionAccess | 'none' {
+  assertRelativeTaskPath(taskPath, 'taskPath');
+  const adapter = normalizeCodexPermissionsAdapter(adapterRaw);
+  const matches = adapter.filesystem.filter((rule) => filesystemRuleMatches(rule.path, taskPath));
+  if (matches.length === 0) return 'none';
+  matches.sort((a, b) => {
+    const specificity = filesystemRuleSpecificity(b.path) - filesystemRuleSpecificity(a.path);
+    if (specificity !== 0) return specificity;
+    return permissionAccessRank(b.access) - permissionAccessRank(a.access);
+  });
+  return matches[0].access;
+}
+
+function domainRuleMatches(ruleHost: string, host: string): boolean {
+  if (ruleHost === '*') return true;
+  if (ruleHost.startsWith('**.')) {
+    const suffix = ruleHost.slice(3);
+    return host === suffix || host.endsWith(`.${suffix}`);
+  }
+  if (ruleHost.startsWith('*.')) {
+    const suffix = ruleHost.slice(2);
+    return host.endsWith(`.${suffix}`) && host !== suffix;
+  }
+  return host === ruleHost;
+}
+
+function hostAllowed(adapter: CodexPermissionsAdapter, host: string): boolean {
+  const matches = adapter.network.domains.filter((rule) => domainRuleMatches(rule.host, host));
+  if (matches.some((rule) => rule.access === 'deny')) return false;
+  return matches.some((rule) => rule.access === 'allow');
+}
+
+function networkIsDomainScoped(adapter: CodexPermissionsAdapter): boolean {
+  return adapter.network.domains.some((rule) => rule.access === 'allow' && rule.host !== '*');
+}
+
+export function createDefaultSeatProfile(role: SeatProfileRole = 'review'): SeatProfile {
+  assertKnown(SEAT_PROFILE_ROLES, role, 'seat_role');
+  const profileId = `${role}-seat`;
+  return normalizeSeatProfile({
+    schema: SEAT_PROFILE_SCHEMA,
+    profile_id: profileId,
+    seat_role: role,
+    preloaded_skills: [
+      'etiquette-seat-pickup',
+    ],
+    manuals: [
+      'AGENTS.md',
+      'RUNBOOK.md',
+    ],
+    required_preflight: [...SEAT_PREFLIGHT_REQUIRED_CHECKS],
+    forbidden_defaults: [
+      'grant_authority',
+      'auto_start_monitor',
+      'mutate_global_agent_config',
+      'merge',
+      'close',
+      'push',
+    ],
+    authority_defaults: {
+      grants_authority: false,
+      can_merge: false,
+      can_close: false,
+      can_push: false,
+      can_mutate_global_agent_config: false,
+      can_auto_start_monitor: false,
+    },
+  });
+}
+
+export function normalizeSeatProfile(raw: unknown): SeatProfile {
+  const record = requireRecord(raw, 'seat profile');
+  if (record.schema !== SEAT_PROFILE_SCHEMA) throw new Error(`schema must be ${SEAT_PROFILE_SCHEMA}`);
+  const profileId = requireString(record, 'profile_id');
+  assertOpaqueId(profileId, 'profile_id');
+  const permissionProfileRef = optionalString(record, 'permission_profile_ref');
+  if (permissionProfileRef) assertSafeRef(permissionProfileRef, 'permission_profile_ref');
+  const seatRole = requireString(record, 'seat_role');
+  assertKnown(SEAT_PROFILE_ROLES, seatRole, 'seat_role');
+  const rawMonitorMode = optionalString(record, 'monitor_mode') ?? 'pull';
+  assertKnown(SEAT_MONITOR_MODES, rawMonitorMode, 'monitor_mode');
+
+  const authorityDefaults = requireRecord(record.authority_defaults, 'authority_defaults');
+  const normalizedAuthority = {
+    grants_authority: optionalFalseValue(authorityDefaults, 'grants_authority'),
+    can_merge: optionalFalseValue(authorityDefaults, 'can_merge'),
+    can_close: optionalFalseValue(authorityDefaults, 'can_close'),
+    can_push: optionalFalseValue(authorityDefaults, 'can_push'),
+    can_mutate_global_agent_config: optionalFalseValue(authorityDefaults, 'can_mutate_global_agent_config'),
+    can_auto_start_monitor: optionalFalseValue(authorityDefaults, 'can_auto_start_monitor'),
+  };
+
+  const preloadedSkills = optionalStringArray(record, 'preloaded_skills');
+  const manuals = optionalStringArray(record, 'manuals');
+  const requiredPreflight = optionalStringArray(record, 'required_preflight');
+  const forbiddenDefaults = optionalStringArray(record, 'forbidden_defaults');
+  if (requiredPreflight.length === 0) throw new Error('required_preflight must contain at least one check');
+  for (const [index, skill] of preloadedSkills.entries()) assertSafeRef(skill, `preloaded_skills[${index}]`);
+  for (const [index, manual] of manuals.entries()) assertSafeRef(manual, `manuals[${index}]`);
+  for (const [index, item] of forbiddenDefaults.entries()) assertSafeRef(item, `forbidden_defaults[${index}]`);
+  const checks = requiredPreflight.map((item, index) => {
+    assertKnown(SEAT_PREFLIGHT_REQUIRED_CHECKS, item, `required_preflight[${index}]`);
+    return item;
+  });
+  const missingRequired = SEAT_PREFLIGHT_REQUIRED_CHECKS.filter((item) => !checks.includes(item));
+  if (missingRequired.length > 0) {
+    throw new Error(`required_preflight missing required checks: ${missingRequired.join(', ')}`);
+  }
+  for (const required of ['grant_authority', 'auto_start_monitor', 'mutate_global_agent_config']) {
+    if (!forbiddenDefaults.includes(required)) {
+      throw new Error(`forbidden_defaults must include ${required}`);
+    }
+  }
+
+  return {
+    schema: SEAT_PROFILE_SCHEMA,
+    profile_id: profileId,
+    ...(permissionProfileRef ? { permission_profile_ref: permissionProfileRef } : {}),
+    seat_role: seatRole,
+    monitor_mode: rawMonitorMode,
+    preloaded_skills: preloadedSkills,
+    manuals,
+    required_preflight: checks,
+    forbidden_defaults: forbiddenDefaults,
+    authority_defaults: normalizedAuthority,
+  };
+}
+
+export function evaluateSeatPreflight(profileRaw: unknown, preflightRaw: unknown): SeatPreflightResult {
+  const profile = normalizeSeatProfile(profileRaw);
+  const record = requireRecord(preflightRaw, 'seat preflight');
+  if (record.schema !== SEAT_PREFLIGHT_SCHEMA) throw new Error(`schema must be ${SEAT_PREFLIGHT_SCHEMA}`);
+  const seatId = optionalString(record, 'seat_id');
+  if (seatId) assertOpaqueId(seatId, 'seat_id');
+  const profileId = optionalString(record, 'profile_id');
+  if (profileId && profileId !== profile.profile_id) {
+    throw new Error(`profile_id mismatch: expected ${profile.profile_id}, got ${profileId}`);
+  }
+  const monitorMode = optionalString(record, 'monitor_mode') ?? profile.monitor_mode;
+  assertKnown(SEAT_MONITOR_MODES, monitorMode, 'monitor_mode');
+  const allowedWrites = optionalStringArray(record, 'allowed_writes');
+  for (const [index, path] of allowedWrites.entries()) assertRelativeTaskPath(path, `allowed_writes[${index}]`);
+  const networkRequired = optionalBoolean(record, 'network_required', false);
+  const networkDomains = optionalStringArray(record, 'network_domains');
+  for (const [index, host] of networkDomains.entries()) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9.-]{0,252}$/.test(host)) {
+      throw new Error(`network_domains[${index}] must be a host`);
+    }
+  }
+
+  const missing: string[] = [];
+  for (const key of ['seat_id', 'operator_principal', 'project_id', 'workflow_id', 'task_ref', 'routing_surface', 'evidence_surface'] as const) {
+    const value = optionalString(record, key);
+    if (!value) missing.push(key);
+    else if (key === 'seat_id' || key === 'operator_principal' || key === 'project_id' || key === 'workflow_id') {
+      assertOpaqueId(value, key);
+    } else {
+      assertSafeRef(value, key);
+    }
+  }
+
+  const checks = isRecord(record.checks) ? record.checks : {};
+  const failed: string[] = [];
+  for (const check of profile.required_preflight) {
+    if (checks[check] !== true) failed.push(check);
+  }
+  const boundary = isRecord(record.authority_boundary) ? record.authority_boundary : {};
+  if (boundary.defaults_grant_authority !== false) failed.push('authority_boundary.defaults_grant_authority');
+  if (boundary.can_auto_start_monitor !== false) failed.push('authority_boundary.can_auto_start_monitor');
+  if (boundary.can_mutate_global_agent_config !== false) failed.push('authority_boundary.can_mutate_global_agent_config');
+  if (boundary.can_merge !== false) failed.push('authority_boundary.can_merge');
+  if (boundary.can_close !== false) failed.push('authority_boundary.can_close');
+  if (boundary.can_push !== false) failed.push('authority_boundary.can_push');
+  try {
+    requireBooleanTrue(boundary.task_packet_required, 'authority_boundary.task_packet_required');
+  } catch {
+    failed.push('authority_boundary.task_packet_required');
+  }
+
+  const warnings: string[] = [];
+  const codexPermissions = record.codex_permissions === undefined ? null : normalizeCodexPermissionsAdapter(record.codex_permissions);
+  if (profile.permission_profile_ref) {
+    if (!codexPermissions) {
+      failed.push('codex_permissions.missing');
+    } else if (codexPermissions.profile_ref !== profile.permission_profile_ref) {
+      failed.push('codex_permissions.profile_ref_mismatch');
+    }
+  } else if (codexPermissions) {
+    warnings.push('codex_permissions_present_without_profile_ref');
+  }
+  if (codexPermissions) {
+    for (const path of allowedWrites) {
+      const access = codexFilesystemAccessForPath(codexPermissions, path);
+      if (access !== 'write') failed.push(`codex_permissions.allowed_writes:${path}`);
+    }
+    if (networkRequired) {
+      if (!codexPermissions.network.enabled) failed.push('codex_permissions.network_disabled');
+      if (networkDomains.length === 0) failed.push('codex_permissions.network_domains_missing');
+      for (const host of networkDomains) {
+        if (!hostAllowed(codexPermissions, host)) failed.push(`codex_permissions.network_domain:${host}`);
+      }
+    } else if (codexPermissions.network.enabled && !networkIsDomainScoped(codexPermissions)) {
+      failed.push('codex_permissions.network_unscoped');
+    }
+    if (codexPermissions.authority_boundary.permissions_grant_authority !== false) {
+      failed.push('codex_permissions.permissions_grant_authority');
+    }
+    if (codexPermissions.authority_boundary.mutates_codex_config !== false) {
+      failed.push('codex_permissions.mutates_codex_config');
+    }
+    if (codexPermissions.authority_boundary.installs_profile !== false) {
+      failed.push('codex_permissions.installs_profile');
+    }
+  }
+  if (monitorMode === 'push') warnings.push('push_monitor_requires_explicit_wait_window');
+  return {
+    schema: SEAT_PREFLIGHT_RESULT_SCHEMA,
+    seat_id: seatId ?? null,
+    profile_id: profile.profile_id,
+    ready: missing.length === 0 && failed.length === 0,
+    monitor_mode: monitorMode,
+    missing,
+    failed,
+    warnings,
+    permission_profile_ref: profile.permission_profile_ref ?? null,
+    authority_boundary: {
+      defaults_grant_authority: false,
+      profile_grants_authority: false,
+      permissions_grant_authority: false,
+      monitor_autostart: false,
+      mutates_global_agent_config: false,
+      mutates_codex_config: false,
+      installs_permission_profile: false,
+      can_merge: false,
+      can_close: false,
+      can_push: false,
+    },
+  };
+}
+
+export function defaultSeatReadinessPath(projectRoot: string): string {
+  return join(resolve(projectRoot), '.etiquette', 'state', 'seat-readiness.json');
+}
+
+export function defaultSeatReadinessEventsPath(projectRoot: string): string {
+  return join(resolve(projectRoot), '.etiquette', 'state', 'seat-readiness-events.ndjson');
+}
+
+function resolveStatePath(projectRoot: string, statePath?: string): string {
+  return statePath ? resolve(statePath) : defaultSeatReadinessPath(projectRoot);
+}
+
+function eventsPathForState(projectRoot: string, statePath?: string): string {
+  if (!statePath) return defaultSeatReadinessEventsPath(projectRoot);
+  return join(dirname(resolve(statePath)), 'seat-readiness-events.ndjson');
+}
+
+function assertKnown<T extends readonly string[]>(values: T, value: string, name: string): asserts value is T[number] {
+  if (!(values as readonly string[]).includes(value)) {
+    throw new Error(`${name} must be one of: ${values.join(', ')}`);
+  }
+}
+
+function assertNonNegativeInteger(value: number, name: string): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative integer`);
+  }
+}
+
+function assertPositiveInteger(value: number, name: string): void {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function assertOpaqueId(value: string, name: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) {
+    throw new Error(`${name} must be an opaque id using letters, numbers, hyphen, or underscore`);
+  }
+}
+
+function assertStrategy(value: string, name: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) {
+    throw new Error(`${name} must contain only letters, numbers, hyphen, or underscore`);
+  }
+}
+
+function assertModelId(value: string, name: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) {
+    throw new Error(`${name} must be an opaque model id without whitespace, paths, or hostnames`);
+  }
+}
+
+function assertIsoTimestamp(value: string, name: string): void {
+  if (!Number.isFinite(Date.parse(value))) {
+    throw new Error(`${name} must be an ISO-8601 timestamp`);
+  }
+}
+
+function nowIso(at?: string): string {
+  if (!at) return new Date().toISOString();
+  assertIsoTimestamp(at, '--at');
+  return new Date(at).toISOString();
+}
+
+export function ttlSecondsForModelTier(tier: ModelTier): number {
+  void tier;
+  // Heartbeat freshness tracks local seat posture, not theoretical model class stability.
+  // Model switches are common enough that every tier must refresh daily in V0.1.
+  return 24 * 60 * 60;
+}
+
+function staleAfter(at: string, ttlSeconds: number): string {
+  return new Date(Date.parse(at) + ttlSeconds * 1000).toISOString();
+}
+
+function capabilityTrusted(source: CapabilitySource): boolean {
+  return source !== 'agent_self_declared';
+}
+
+function validateRecord(record: SeatReadinessRecord): void {
+  assertKnown(SEAT_TYPES, record.seat_type, 'seat_type');
+  assertKnown(OPERATIONAL_STATUSES, record.operational_status, 'operational_status');
+  assertKnown(CAPABILITY_SOURCES, record.capability_source, 'capability_source');
+  assertKnown(MODEL_TIERS, record.model_tier, 'model_tier');
+  assertKnown(['operator_principal', 'config'] as const, record.declared_by, 'declared_by');
+  assertOpaqueId(record.seat, 'seat');
+  assertOpaqueId(record.execution_surface, 'execution_surface');
+  if (record.model_id) assertModelId(record.model_id, 'model_id');
+  assertNonNegativeInteger(record.active_workers, 'active_workers');
+  assertPositiveInteger(record.max_recommended_workers, 'max_recommended_workers');
+  for (const strategy of record.supported_strategies) assertStrategy(strategy, 'supported_strategies[]');
+  for (const strategy of record.unsupported_strategies) assertStrategy(strategy, 'unsupported_strategies[]');
+  for (const constraint of record.constraints) assertStrategy(constraint, 'constraints[]');
+  assertIsoTimestamp(record.last_checked_at, 'last_checked_at');
+  assertIsoTimestamp(record.last_heartbeat_at, 'last_heartbeat_at');
+  assertIsoTimestamp(record.stale_after, 'stale_after');
+}
+
+async function appendReadinessEvent(
+  projectRoot: string,
+  statePath: string | undefined,
+  event: Record<string, unknown>,
+): Promise<void> {
+  const path = eventsPathForState(projectRoot, statePath);
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify({
+    schema_version: SEAT_READINESS_EVENT_SCHEMA,
+    ...event,
+  })}\n`);
+}
+
+async function writeRecord(projectRoot: string, statePath: string | undefined, record: SeatReadinessRecord): Promise<void> {
+  validateRecord(record);
+  await writeJson(resolveStatePath(projectRoot, statePath), record);
+}
+
+export async function readSeatReadiness(projectRoot: string, statePath?: string): Promise<SeatReadinessRecord> {
+  const path = resolveStatePath(projectRoot, statePath);
+  let parsed: SeatReadinessRecord;
+  try {
+    parsed = JSON.parse(await readFile(path, 'utf-8')) as SeatReadinessRecord;
+  } catch (err) {
+    throw new Error(`seat readiness state could not be read at ${path}: ${(err as NodeJS.ErrnoException).code ?? String(err)}`);
+  }
+  validateRecord(parsed);
+  return parsed;
+}
+
+export async function reportSeatReadiness(input: ReadinessInput): Promise<SeatReadinessRecord> {
+  const at = nowIso(input.at);
+  const ttl = ttlSecondsForModelTier(input.modelTier);
+  const record: SeatReadinessRecord = {
+    schema_version: SEAT_READINESS_SCHEMA,
+    seat: input.seat,
+    seat_type: input.seatType,
+    execution_surface: input.executionSurface,
+    declared_by: input.declaredBy,
+    capability_source: input.capabilitySource,
+    capability_trusted: capabilityTrusted(input.capabilitySource),
+    operational_status: input.operationalStatus,
+    model_tier: input.modelTier,
+    ...(input.modelId ? { model_id: input.modelId } : {}),
+    active_workers: input.activeWorkers,
+    max_recommended_workers: input.maxRecommendedWorkers,
+    supports_parallel: input.supportsParallel,
+    supported_strategies: input.supportedStrategies,
+    unsupported_strategies: input.unsupportedStrategies,
+    constraints: input.constraints,
+    last_checked_at: at,
+    last_heartbeat_at: at,
+    ttl_seconds: ttl,
+    stale_after: staleAfter(at, ttl),
+  };
+  await writeRecord(input.projectRoot, input.statePath, record);
+  await appendReadinessEvent(input.projectRoot, input.statePath, {
+    event_type: 'seat_readiness_reported',
+    at,
+    seat: record.seat,
+    operational_status: record.operational_status,
+    model_tier: record.model_tier,
+    capability_source: record.capability_source,
+    capability_trusted: record.capability_trusted,
+    active_workers: record.active_workers,
+    max_recommended_workers: record.max_recommended_workers,
+  });
+  return record;
+}
+
+export async function heartbeatSeat(input: HeartbeatInput): Promise<SeatReadinessRecord> {
+  const previous = await readSeatReadiness(input.projectRoot, input.statePath);
+  if (input.seat && input.seat !== previous.seat) {
+    throw new Error(`heartbeat seat mismatch: expected ${previous.seat}, got ${input.seat}`);
+  }
+  const at = nowIso(input.at);
+  const activeWorkers = input.activeWorkers ?? previous.active_workers;
+  assertNonNegativeInteger(activeWorkers, 'active_workers');
+  const record: SeatReadinessRecord = {
+    ...previous,
+    operational_status: input.operationalStatus ?? previous.operational_status,
+    active_workers: activeWorkers,
+    constraints: input.constraints ?? previous.constraints,
+    last_heartbeat_at: at,
+    last_checked_at: at,
+    stale_after: staleAfter(at, previous.ttl_seconds),
+  };
+  await writeRecord(input.projectRoot, input.statePath, record);
+  await appendReadinessEvent(input.projectRoot, input.statePath, {
+    event_type: 'seat_heartbeat',
+    at,
+    seat: record.seat,
+    operational_status: record.operational_status,
+    active_workers: record.active_workers,
+    max_recommended_workers: record.max_recommended_workers,
+  });
+  return record;
+}
+
+export function evaluateSeatReadiness(record: SeatReadinessRecord, at?: string): SeatReadinessStatus {
+  const checkedAt = nowIso(at);
+  const isStale = Date.parse(checkedAt) > Date.parse(record.stale_after);
+  let routing: SeatReadinessStatus['routing_recommendation'] = 'route_if_policy_allows';
+  if (isStale) routing = 'reject_or_refresh';
+  else if (record.operational_status === 'blocked' || record.operational_status === 'offline') {
+    routing = 'defer_with_reason';
+  } else if (!record.capability_trusted) {
+    routing = 'seek_validation';
+  }
+  return {
+    ...record,
+    checked_at: checkedAt,
+    is_stale: isStale,
+    effective_model_tier: isStale ? 'local_unknown' : record.model_tier,
+    routing_recommendation: routing,
+  };
+}