@etiquekit/etq 1.0.11 → 1.0.13

package/packages/control/src/harness/pruning.ts

@@ -0,0 +1,406 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { assertSharedMemoryScopeId, assertSharedMemoryText, detectMemoryRiskFlags } from '../memory/sanitize';
+
+type JsonRecord = Record<string, unknown>;
+
+export const HARNESS_OBJECT_CLASSES = [
+  'prompt',
+  'skill',
+  'schema',
+  'adapter',
+  'ui',
+  'runbook',
+  'infra',
+  'other',
+] as const;
+
+export const HARNESS_AUTHORITY_CLASSES = [
+  'ergonomic',
+  'evidence',
+  'authority',
+  'recovery',
+  'unknown',
+] as const;
+
+export const HARNESS_CONSUMER_STATUSES = [
+  'active',
+  'nascent',
+  'stale',
+  'unknown',
+] as const;
+
+export const HARNESS_DISPOSITIONS = [
+  'keep',
+  'consolidate',
+  'quarantine',
+  'delete-ready',
+  'blocked',
+] as const;
+
+export const HARNESS_CANARIES = [
+  'ordinary-run',
+  'onboarding',
+  'recovery',
+  'auth-drift',
+  'single-writer-or-drain',
+  'receipt-verification',
+  'degraded-fail-closed',
+] as const;
+
+export type HarnessObjectClass = (typeof HARNESS_OBJECT_CLASSES)[number];
+export type HarnessAuthorityClass = (typeof HARNESS_AUTHORITY_CLASSES)[number];
+export type HarnessConsumerStatus = (typeof HARNESS_CONSUMER_STATUSES)[number];
+export type HarnessDisposition = (typeof HARNESS_DISPOSITIONS)[number];
+export type HarnessCanary = (typeof HARNESS_CANARIES)[number];
+
+export interface HarnessPruneAuthorityBoundary {
+  can_grant: false;
+  can_close_lane: false;
+  can_merge: false;
+  can_delete: false;
+}
+
+export interface HarnessPruneReceipt {
+  schema: 'harness-prune-receipt.v0';
+  object_id: string;
+  object_class: HarnessObjectClass;
+  authority_class: HarnessAuthorityClass;
+  consumer_status: HarnessConsumerStatus;
+  proposed_disposition: HarnessDisposition;
+  evidence_refs: string[];
+  canary_set: HarnessCanary[];
+  quarantine_until?: string;
+  next_owner: string;
+  authority: HarnessPruneAuthorityBoundary;
+}
+
+export interface HarnessReceiptValidation {
+  schema: 'harness-prune-receipt-validation.v0';
+  receipt_id: string;
+  object_id: string;
+  verdict: 'valid';
+  proposed_disposition: HarnessDisposition;
+  canary: HarnessCanaryResult;
+  authority_boundary: HarnessPruneAuthorityBoundary & {
+    receipt_can_authorize_pruning: false;
+    human_disposition_required: true;
+  };
+}
+
+export interface HarnessCanaryResult {
+  schema: 'harness-canary-result.v0';
+  object_id: string;
+  required_canaries: HarnessCanary[];
+  observed_canaries: HarnessCanary[];
+  missing_canaries: HarnessCanary[];
+  verdict: 'pass' | 'blocked';
+}
+
+export interface HarnessInventoryItem {
+  object_id: string;
+  object_class: HarnessObjectClass;
+  authority_class: HarnessAuthorityClass;
+  consumer_status: HarnessConsumerStatus;
+  evidence_refs: string[];
+  roadmap_ref?: string;
+  last_seen_ref?: string;
+}
+
+export interface HarnessInventoryManifest {
+  schema: 'harness-inventory.v0';
+  generated_by?: string;
+  items: HarnessInventoryItem[];
+}
+
+export interface HarnessInventoryReportItem extends HarnessInventoryItem {
+  suggested_disposition: HarnessDisposition;
+  reason: string;
+}
+
+export interface HarnessInventoryReport {
+  schema: 'harness-inventory-report.v0';
+  item_count: number;
+  counts: Record<HarnessDisposition, number>;
+  items: HarnessInventoryReportItem[];
+  authority_boundary: {
+    inventory_can_delete: false;
+    inventory_can_grant: false;
+    inventory_can_close_lane: false;
+    pruning_receipt_required: true;
+    human_disposition_required: true;
+  };
+}
+
+function stableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
+}
+
+function asRecord(value: unknown, name: string): JsonRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  return value as JsonRecord;
+}
+
+function asString(record: JsonRecord, key: string): string {
+  const value = record[key];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${key} must be a non-empty string`);
+  }
+  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 when present`);
+  }
+  return value.trim();
+}
+
+function asStringArray(record: JsonRecord, key: string): string[] {
+  const value = record[key];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.trim().length === 0)) {
+    throw new Error(`${key} must be a non-empty string array`);
+  }
+  return value.map((item) => item.trim());
+}
+
+function asEnum<T extends readonly string[]>(values: T, raw: unknown, key: string): T[number] {
+  if (typeof raw !== 'string' || !(values as readonly string[]).includes(raw)) {
+    throw new Error(`${key} must be one of: ${values.join(', ')}`);
+  }
+  return raw as T[number];
+}
+
+function asEnumArray<T extends readonly string[]>(values: T, raw: unknown, key: string): T[number][] {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new Error(`${key} must be a non-empty array`);
+  }
+  return raw.map((item, index) => asEnum(values, item, `${key}[${index}]`));
+}
+
+function assertOpaqueText(value: string, field: string): void {
+  assertSharedMemoryText(value, field);
+  if (value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value)) {
+    throw new Error(`${field} must be opaque or repo-relative, not an absolute local path`);
+  }
+  if (/[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+    throw new Error(`${field} must not be a URL`);
+  }
+}
+
+function parseAuthorityBoundary(raw: unknown): HarnessPruneAuthorityBoundary {
+  const record = asRecord(raw, 'authority');
+  const boundary = {
+    can_grant: record.can_grant,
+    can_close_lane: record.can_close_lane,
+    can_merge: record.can_merge,
+    can_delete: record.can_delete,
+  };
+  for (const [key, value] of Object.entries(boundary)) {
+    if (value !== false) throw new Error(`authority.${key} must be false`);
+  }
+  return boundary as HarnessPruneAuthorityBoundary;
+}
+
+function parseHarnessPruneReceipt(value: unknown): HarnessPruneReceipt {
+  const record = asRecord(value, 'harness_prune_receipt');
+  const receipt: HarnessPruneReceipt = {
+    schema: asEnum(['harness-prune-receipt.v0'] as const, record.schema, 'schema'),
+    object_id: asString(record, 'object_id'),
+    object_class: asEnum(HARNESS_OBJECT_CLASSES, record.object_class, 'object_class') as HarnessObjectClass,
+    authority_class: asEnum(HARNESS_AUTHORITY_CLASSES, record.authority_class, 'authority_class') as HarnessAuthorityClass,
+    consumer_status: asEnum(HARNESS_CONSUMER_STATUSES, record.consumer_status, 'consumer_status') as HarnessConsumerStatus,
+    proposed_disposition: asEnum(HARNESS_DISPOSITIONS, record.proposed_disposition, 'proposed_disposition') as HarnessDisposition,
+    evidence_refs: asStringArray(record, 'evidence_refs'),
+    canary_set: asEnumArray(HARNESS_CANARIES, record.canary_set, 'canary_set') as HarnessCanary[],
+    quarantine_until: optionalString(record, 'quarantine_until'),
+    next_owner: asString(record, 'next_owner'),
+    authority: parseAuthorityBoundary(record.authority),
+  };
+  validateHarnessPruneReceiptShape(receipt);
+  return receipt;
+}
+
+function parseHarnessInventoryManifest(value: unknown): HarnessInventoryManifest {
+  const record = asRecord(value, 'harness_inventory');
+  if (asEnum(['harness-inventory.v0'] as const, record.schema, 'schema') !== 'harness-inventory.v0') {
+    throw new Error('schema must be harness-inventory.v0');
+  }
+  const itemsRaw = record.items;
+  if (!Array.isArray(itemsRaw) || itemsRaw.length === 0) throw new Error('items must be a non-empty array');
+  const items = itemsRaw.map((item, index): HarnessInventoryItem => {
+    const entry = asRecord(item, `items[${index}]`);
+    const parsed = {
+      object_id: asString(entry, 'object_id'),
+      object_class: asEnum(HARNESS_OBJECT_CLASSES, entry.object_class, `items[${index}].object_class`) as HarnessObjectClass,
+      authority_class: asEnum(HARNESS_AUTHORITY_CLASSES, entry.authority_class, `items[${index}].authority_class`) as HarnessAuthorityClass,
+      consumer_status: asEnum(HARNESS_CONSUMER_STATUSES, entry.consumer_status, `items[${index}].consumer_status`) as HarnessConsumerStatus,
+      evidence_refs: asStringArray(entry, 'evidence_refs'),
+      roadmap_ref: optionalString(entry, 'roadmap_ref'),
+      last_seen_ref: optionalString(entry, 'last_seen_ref'),
+    };
+    validateInventoryItem(parsed, `items[${index}]`);
+    return parsed;
+  });
+  const generatedBy = optionalString(record, 'generated_by');
+  if (generatedBy) assertSharedMemoryScopeId(generatedBy, 'generated_by');
+  return { schema: 'harness-inventory.v0', ...(generatedBy ? { generated_by: generatedBy } : {}), items };
+}
+
+async function readStructured(path: string): Promise<unknown> {
+  const raw = await readFile(path, 'utf-8');
+  if (extname(path).toLowerCase() === '.json') return JSON.parse(raw) as unknown;
+  return parseYaml(raw) as unknown;
+}
+
+function validateRefs(values: string[], field: string): void {
+  for (const [index, value] of values.entries()) assertOpaqueText(value, `${field}[${index}]`);
+}
+
+function validateInventoryItem(item: HarnessInventoryItem, field: string): void {
+  assertOpaqueText(item.object_id, `${field}.object_id`);
+  validateRefs(item.evidence_refs, `${field}.evidence_refs`);
+  if (item.roadmap_ref) assertOpaqueText(item.roadmap_ref, `${field}.roadmap_ref`);
+  if (item.last_seen_ref) assertOpaqueText(item.last_seen_ref, `${field}.last_seen_ref`);
+}
+
+export function requiredCanariesFor(receipt: Pick<HarnessPruneReceipt, 'proposed_disposition'>): HarnessCanary[] {
+  if (receipt.proposed_disposition === 'delete-ready') return [...HARNESS_CANARIES];
+  return ['ordinary-run', 'receipt-verification'];
+}
+
+export function evaluateHarnessCanary(receipt: HarnessPruneReceipt): HarnessCanaryResult {
+  const required = requiredCanariesFor(receipt);
+  const observed = [...new Set(receipt.canary_set)];
+  const missing = required.filter((canary) => !observed.includes(canary));
+  return {
+    schema: 'harness-canary-result.v0',
+    object_id: receipt.object_id,
+    required_canaries: required,
+    observed_canaries: observed,
+    missing_canaries: missing,
+    verdict: missing.length === 0 ? 'pass' : 'blocked',
+  };
+}
+
+function validateHarnessPruneReceiptShape(receipt: HarnessPruneReceipt): void {
+  assertOpaqueText(receipt.object_id, 'object_id');
+  validateRefs(receipt.evidence_refs, 'evidence_refs');
+  assertSharedMemoryScopeId(receipt.next_owner, 'next_owner');
+  if (receipt.quarantine_until) assertOpaqueText(receipt.quarantine_until, 'quarantine_until');
+
+  const refFlags = receipt.evidence_refs.flatMap((ref) => detectMemoryRiskFlags(ref));
+  if (refFlags.length > 0) throw new Error(`evidence_refs contain restricted shared content: ${[...new Set(refFlags)].join(', ')}`);
+}
+
+export function validateHarnessPruneReceipt(receipt: HarnessPruneReceipt): void {
+  validateHarnessPruneReceiptShape(receipt);
+  if (receipt.consumer_status === 'nascent' && receipt.proposed_disposition === 'delete-ready') {
+    throw new Error('nascent harness surfaces must be quarantined or kept, not delete-ready');
+  }
+  if ((receipt.authority_class === 'authority' || receipt.authority_class === 'recovery')
+    && receipt.proposed_disposition === 'delete-ready') {
+    throw new Error('authority and recovery surfaces cannot be delete-ready in V0; route principal-gated obsolescence separately');
+  }
+  if (receipt.authority_class === 'unknown' && receipt.proposed_disposition !== 'blocked') {
+    throw new Error('unknown authority class must use proposed_disposition: blocked');
+  }
+  if (receipt.consumer_status === 'unknown' && receipt.proposed_disposition !== 'blocked') {
+    throw new Error('unknown consumer status must use proposed_disposition: blocked');
+  }
+  if (receipt.proposed_disposition === 'delete-ready') {
+    if (receipt.authority_class !== 'ergonomic') {
+      throw new Error('delete-ready is only valid for ergonomic scaffolding in V0');
+    }
+    if (receipt.consumer_status !== 'stale') {
+      throw new Error('delete-ready requires consumer_status: stale');
+    }
+    if (!receipt.quarantine_until) {
+      throw new Error('delete-ready requires quarantine_until');
+    }
+  }
+
+  const canary = evaluateHarnessCanary(receipt);
+  if (canary.verdict !== 'pass') {
+    throw new Error(`missing canaries: ${canary.missing_canaries.join(', ')}`);
+  }
+}
+
+export async function loadHarnessPruneReceipt(path: string): Promise<HarnessPruneReceipt> {
+  return parseHarnessPruneReceipt(await readStructured(path));
+}
+
+export async function validateHarnessPruneReceiptFile(path: string): Promise<HarnessReceiptValidation> {
+  const receipt = await loadHarnessPruneReceipt(path);
+  validateHarnessPruneReceipt(receipt);
+  return {
+    schema: 'harness-prune-receipt-validation.v0',
+    receipt_id: `harness-prune:${stableHash(receipt)}`,
+    object_id: receipt.object_id,
+    verdict: 'valid',
+    proposed_disposition: receipt.proposed_disposition,
+    canary: evaluateHarnessCanary(receipt),
+    authority_boundary: {
+      ...receipt.authority,
+      receipt_can_authorize_pruning: false,
+      human_disposition_required: true,
+    },
+  };
+}
+
+function suggestDisposition(item: HarnessInventoryItem): Pick<HarnessInventoryReportItem, 'suggested_disposition' | 'reason'> {
+  if (item.authority_class === 'unknown' || item.consumer_status === 'unknown') {
+    return { suggested_disposition: 'blocked', reason: 'authority or consumer reach is unknown' };
+  }
+  if (item.consumer_status === 'active') {
+    return { suggested_disposition: 'keep', reason: 'active consumer evidence exists' };
+  }
+  if (item.consumer_status === 'nascent') {
+    return { suggested_disposition: 'quarantine', reason: 'roadmap-aware grace: built ahead of consumer' };
+  }
+  if (item.authority_class === 'authority' || item.authority_class === 'recovery') {
+    return { suggested_disposition: 'blocked', reason: 'authority and recovery surfaces require principal-gated obsolescence review' };
+  }
+  if (item.authority_class === 'ergonomic' && item.consumer_status === 'stale') {
+    return { suggested_disposition: 'quarantine', reason: 'stale ergonomic scaffolding; pruning receipt and canary-without required before delete-ready' };
+  }
+  return { suggested_disposition: 'consolidate', reason: 'stale non-authority surface should be simplified before deletion' };
+}
+
+export function buildHarnessInventoryReport(manifest: HarnessInventoryManifest): HarnessInventoryReport {
+  const counts: Record<HarnessDisposition, number> = {
+    keep: 0,
+    consolidate: 0,
+    quarantine: 0,
+    'delete-ready': 0,
+    blocked: 0,
+  };
+  const items = manifest.items.map((item) => {
+    const suggestion = suggestDisposition(item);
+    counts[suggestion.suggested_disposition] += 1;
+    return { ...item, ...suggestion };
+  });
+  return {
+    schema: 'harness-inventory-report.v0',
+    item_count: items.length,
+    counts,
+    items,
+    authority_boundary: {
+      inventory_can_delete: false,
+      inventory_can_grant: false,
+      inventory_can_close_lane: false,
+      pruning_receipt_required: true,
+      human_disposition_required: true,
+    },
+  };
+}
+
+export async function buildHarnessInventoryReportFile(path: string): Promise<HarnessInventoryReport> {
+  return buildHarnessInventoryReport(parseHarnessInventoryManifest(await readStructured(path)));
+}

package/packages/control/src/hooks/dispatcher.ts

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { assertSharedMemoryScopeId, detectMemoryRiskFlags } from './sanitize';
+import { writeOutboxEvent } from './outbox';
+import {
+  HOOK_EVENT_TYPES,
+  type DispatchResult,
+  type HookEvent,
+  type HookStage,
+} from './types';
+
+export interface DispatchOptions {
+  stage: HookStage;
+  workspace_id?: string;
+  payload?: Record<string, unknown>;
+  home?: string;
+  enabled_env?: string;
+  workspace_env?: string;
+}
+
+const DEFAULT_ENABLED_ENV = 'ETIQUETTE_HOOKS_ENABLED';
+const DEFAULT_WORKSPACE_ENV = 'ETIQUETTE_WORKSPACE_ID';
+
+/**
+ * Stage-dispatch entry-point for V0.1 hook adapter.
+ *
+ * Hook dispatch envelope:
+ *   - disabled by default (env var opt-in)
+ *   - local-first (writes per-workspace outbox; no network)
+ *   - metadata-only (sanitizer strips path/host/IP/credential/raw-prompt/raw-tool/source)
+ *   - fast-fail (no retries; no blocking on outbox absence)
+ *   - non-authoritative (writes outbox; never to ledger or canonical surfaces)
+ *   - non-blocking (any failure returns 'skipped', never throws)
+ *
+ * Return contract: always returns a DispatchResult. The CLI wrapper exits 0
+ * regardless of status; status surfaces in stdout for inspectability.
+ */
+export function dispatchHook(opts: DispatchOptions): DispatchResult {
+  const enabledKey = opts.enabled_env ?? DEFAULT_ENABLED_ENV;
+  const workspaceKey = opts.workspace_env ?? DEFAULT_WORKSPACE_ENV;
+
+  if (process.env[enabledKey] !== '1') {
+    return { status: 'disabled' };
+  }
+
+  const workspace_id = (opts.workspace_id ?? process.env[workspaceKey])?.trim();
+  if (!workspace_id || workspace_id.trim() === '') {
+    return {
+      status: 'skipped',
+      reasons: [`no-workspace-id (set ${workspaceKey} env var or pass --workspace)`],
+    };
+  }
+  try {
+    assertSharedMemoryScopeId(workspace_id, 'workspace_id');
+  } catch (err) {
+    return {
+      status: 'skipped',
+      reasons: [`invalid-workspace-id: ${(err as Error).message}`],
+    };
+  }
+
+  // Sanitize each string payload field; strip (do not throw) fields that
+  // contain restricted content classes per sanitizer doctrine.
+  const sourcePayload = opts.payload ?? {};
+  const sanitizedPayload: Record<string, unknown> = {};
+  const strippedFields: string[] = [];
+
+  for (const [key, value] of Object.entries(sourcePayload)) {
+    if (typeof value === 'string') {
+      const flags = detectMemoryRiskFlags(value);
+      if (flags.length > 0) {
+        strippedFields.push(`${key}(${flags.join(',')})`);
+        continue;
+      }
+      sanitizedPayload[key] = value;
+    } else if (
+      typeof value === 'number' ||
+      typeof value === 'boolean' ||
+      value === null
+    ) {
+      sanitizedPayload[key] = value;
+    } else {
+      // Reject objects/arrays at V0.1 — keep payload shape flat.
+      // V0.2 may add nested sanitization with depth limits.
+      strippedFields.push(`${key}(non-scalar)`);
+    }
+  }
+
+  const event: HookEvent = {
+    event_id: randomUUID(),
+    stage: opts.stage,
+    event_type: HOOK_EVENT_TYPES[opts.stage],
+    occurred_at: new Date().toISOString(),
+    workspace_id,
+    payload: sanitizedPayload,
+  };
+
+  const home = opts.home ?? homedir();
+  const writeResult = writeOutboxEvent(home, workspace_id, event);
+
+  if (!writeResult.written) {
+    return {
+      status: 'skipped',
+      reasons: [writeResult.reason ?? 'outbox-write-failed'],
+    };
+  }
+
+  const reasons = strippedFields.length > 0
+    ? [`sanitizer-stripped: ${strippedFields.join(', ')}`]
+    : undefined;
+
+  return {
+    status: 'written',
+    event_id: event.event_id,
+    reasons,
+  };
+}

package/packages/control/src/hooks/outbox.ts

@@ -0,0 +1,86 @@
+import { appendFileSync, existsSync, mkdirSync, rmdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { HookEvent } from './types';
+
+export interface OutboxWriteResult {
+  written: boolean;
+  reason?: string;
+}
+
+export function outboxDir(home: string, workspace_id: string): string {
+  return join(home, '.etiquette', 'state', 'workspaces', workspace_id);
+}
+
+export function outboxPath(home: string, workspace_id: string): string {
+  return join(outboxDir(home, workspace_id), 'outbox.ndjson');
+}
+
+const LOCK_DIR_NAME = '.outbox.lock';
+const LOCK_MAX_ATTEMPTS = 100;
+const LOCK_SLEEP_MS = 50;
+
+function acquireLock(lockPath: string): boolean {
+  for (let attempt = 0; attempt < LOCK_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      mkdirSync(lockPath);
+      return true;
+    } catch {
+      // already locked; busy-wait briefly
+      const deadline = Date.now() + LOCK_SLEEP_MS;
+      while (Date.now() < deadline) {
+        // busy wait — sync only because hooks must not yield
+      }
+    }
+  }
+  return false;
+}
+
+function releaseLock(lockPath: string): void {
+  try {
+    rmdirSync(lockPath);
+  } catch {
+    // lock already released or never acquired; swallow
+  }
+}
+
+/**
+ * Append a HookEvent to the per-workspace outbox NDJSON. Race-safe via mkdir
+ * lock (same pattern as the PR #5 fix for `bin/local-event`). Non-blocking:
+ * any failure (missing directory, lock timeout, write error) returns
+ * `{written:false, reason}` and the caller decides — V0.1 dispatcher logs and
+ * proceeds.
+ *
+ * Per [[feedback_rotated_operator_topology]]: outbox lives per-workspace, not
+ * per-seat. Operator rotation across seats preserves continuity.
+ */
+export function writeOutboxEvent(
+  home: string,
+  workspace_id: string,
+  event: HookEvent,
+): OutboxWriteResult {
+  const dir = outboxDir(home, workspace_id);
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    return { written: false, reason: `outbox-dir-unavailable: ${(err as Error).message}` };
+  }
+
+  const lockPath = join(dir, LOCK_DIR_NAME);
+  if (!acquireLock(lockPath)) {
+    return { written: false, reason: `lock-timeout after ${LOCK_MAX_ATTEMPTS} attempts` };
+  }
+
+  const path = outboxPath(home, workspace_id);
+  try {
+    appendFileSync(path, `${JSON.stringify(event)}\n`, 'utf-8');
+    return { written: true };
+  } catch (err) {
+    return { written: false, reason: `append-failed: ${(err as Error).message}` };
+  } finally {
+    releaseLock(lockPath);
+  }
+}
+
+export function outboxExists(home: string, workspace_id: string): boolean {
+  return existsSync(outboxPath(home, workspace_id));
+}

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

@@ -0,0 +1,6 @@
+// Re-export the memory-spine sanitizer so the hook adapter applies the same
+// content-class boundary as recall capsules. Single source of truth.
+// Keep hook payload filtering on the same content-class boundary as recall.
+
+export { assertSharedMemoryScopeId, detectMemoryRiskFlags } from '../memory/sanitize';
+export type { MemoryRiskFlag } from '../memory/types';

package/packages/control/src/hooks/types.ts

@@ -0,0 +1,34 @@
+export const HOOK_STAGES = [
+  'session_start',
+  'user_prompt_submit',
+  'post_tool_use',
+  'stop',
+  'session_end',
+] as const;
+
+export type HookStage = (typeof HOOK_STAGES)[number];
+
+export const HOOK_EVENT_TYPES: Record<HookStage, string> = {
+  session_start: 'seat:session_started',
+  user_prompt_submit: 'trace:prompt_boundary',
+  post_tool_use: 'trace:tool_used',
+  stop: 'playback:candidate_observed',
+  session_end: 'seat:session_completed',
+};
+
+export interface HookEvent {
+  event_id: string;
+  stage: HookStage;
+  event_type: string;
+  occurred_at: string;
+  workspace_id: string;
+  payload: Record<string, unknown>;
+}
+
+export type DispatchStatus = 'disabled' | 'written' | 'skipped';
+
+export interface DispatchResult {
+  status: DispatchStatus;
+  event_id?: string;
+  reasons?: string[];
+}