tycono 0.1.93-beta.2 → 0.1.93

package/src/api/src/engine/tools/executor.ts

@@ -6,6 +6,9 @@ import type { ToolCall, ToolResult } from '../llm-adapter.js';
 import { validateWrite, validateRead } from '../authority-validator.js';
 import type { OrgTree } from '../org-tree.js';
 import { buildKnowledgeGateWarning } from '../knowledge-gate.js';
+import { ActivityStream } from '../../services/activity-stream.js';
+import { digest, quietDigest, type DigestResult } from '../../services/digest-engine.js';
+import type { ActivityEvent } from '../../../../shared/types.js';
 
 /* ─── Types ──────────────────────────────────── */
 
@@ -14,9 +17,14 @@ export interface ToolExecutorOptions {
   roleId: string;
   orgTree: OrgTree;
   codeRoot?: string;
+  sessionId?: string;
   onDispatch?: (roleId: string, task: string) => Promise<string>;
   onConsult?: (roleId: string, question: string) => Promise<string>;
   onToolExec?: (name: string, input: Record<string, unknown>) => void;
+  /** For supervision: abort a running session */
+  onAbortSession?: (sessionId: string) => boolean;
+  /** For supervision: amend a running session with new instructions */
+  onAmendSession?: (sessionId: string, instruction: string) => boolean;
 }
 
 /* ─── Tool Executor ──────────────────────────── */
@@ -48,6 +56,12 @@ export async function executeTool(
         return await dispatchTask(id, input, onDispatch);
       case 'consult':
         return await consultTask(id, input, onConsult);
+      case 'heartbeat_watch':
+        return await heartbeatWatch(id, input, companyRoot);
+      case 'amend_session':
+        return amendSession(id, input, options.onAmendSession);
+      case 'abort_session':
+        return abortSession(id, input, options.onAbortSession);
       default:
         return { tool_use_id: id, content: `Unknown tool: ${name}`, is_error: true };
     }
@@ -412,3 +426,152 @@ async function consultTask(
   const result = await onConsult(roleId, question);
   return { tool_use_id: id, content: result };
 }
+
+/* ─── Supervision Tools (SV-3, SV-6, SV-7) ──── */
+
+const MAX_WATCH_DURATION = 300;
+const DEFAULT_WATCH_DURATION = 120;
+
+/**
+ * heartbeat_watch: Block for N seconds collecting events from activity streams.
+ * Returns a DigestEngine summary. Early-returns on alert events.
+ * $0 LLM cost during wait — all blocking is server-side.
+ */
+async function heartbeatWatch(
+  id: string,
+  input: Record<string, unknown>,
+  companyRoot: string,
+): Promise<ToolResult> {
+  const sessionIds = input.sessionIds as string[] | undefined;
+  if (!sessionIds || !Array.isArray(sessionIds) || sessionIds.length === 0) {
+    return { tool_use_id: id, content: 'Error: sessionIds array is required', is_error: true };
+  }
+
+  const durationSec = Math.min(
+    Math.max(Number(input.durationSec) || DEFAULT_WATCH_DURATION, 5),
+    MAX_WATCH_DURATION,
+  );
+  const alertOn = (input.alertOn as string[] | undefined) ?? ['msg:done', 'msg:error'];
+  const alertSet = new Set(alertOn);
+
+  // Collect current checkpoints (last known seq for each session)
+  const startCheckpoints = new Map<string, number>();
+  for (const sid of sessionIds) {
+    const events = ActivityStream.readAll(sid);
+    startCheckpoints.set(sid, events.length > 0 ? events[events.length - 1].seq + 1 : 0);
+  }
+
+  // Set up event collection with live subscriptions
+  const collectedEvents = new Map<string, ActivityEvent[]>();
+  for (const sid of sessionIds) {
+    collectedEvents.set(sid, []);
+  }
+
+  let earlyReturn = false;
+  const unsubscribers: Array<() => void> = [];
+
+  // Subscribe to live events for early alert detection
+  for (const sid of sessionIds) {
+    const stream = ActivityStream.getOrCreate(sid, 'unknown');
+    const handler = (event: ActivityEvent) => {
+      const events = collectedEvents.get(sid);
+      if (events) events.push(event);
+      if (alertSet.has(event.type)) {
+        earlyReturn = true;
+      }
+    };
+    stream.subscribe(handler);
+    unsubscribers.push(() => stream.unsubscribe(handler));
+  }
+
+  // Wait for duration or early return
+  await new Promise<void>((resolve) => {
+    const timeout = setTimeout(resolve, durationSec * 1000);
+    const checkInterval = setInterval(() => {
+      if (earlyReturn) {
+        clearTimeout(timeout);
+        clearInterval(checkInterval);
+        resolve();
+      }
+    }, 500); // Check every 500ms
+    // Ensure cleanup even if early
+    setTimeout(() => { clearInterval(checkInterval); }, durationSec * 1000 + 100);
+  });
+
+  // Unsubscribe all
+  for (const unsub of unsubscribers) unsub();
+
+  // If live subscription missed events (e.g., stream was not active), read from file
+  for (const sid of sessionIds) {
+    const fromSeq = startCheckpoints.get(sid) ?? 0;
+    const liveEvents = collectedEvents.get(sid) ?? [];
+    if (liveEvents.length === 0) {
+      // Fallback: read from JSONL
+      const fileEvents = ActivityStream.readFrom(sid, fromSeq);
+      collectedEvents.set(sid, fileEvents);
+    }
+  }
+
+  // Run DigestEngine
+  const result: DigestResult = digest(collectedEvents);
+
+  // SV-10: Quiet tick gate
+  if (result.significanceScore < 2 && result.anomalies.length === 0) {
+    const quietText = quietDigest(sessionIds.length, result.eventCount, result.errorCount);
+    return { tool_use_id: id, content: quietText };
+  }
+
+  return { tool_use_id: id, content: result.text };
+}
+
+/**
+ * amend_session: Send additional instructions to a running session (SV-6)
+ */
+function amendSession(
+  id: string,
+  input: Record<string, unknown>,
+  onAmend?: (sessionId: string, instruction: string) => boolean,
+): ToolResult {
+  const sessionId = String(input.sessionId ?? '');
+  const instruction = String(input.instruction ?? '');
+
+  if (!sessionId || !instruction) {
+    return { tool_use_id: id, content: 'Error: sessionId and instruction are required', is_error: true };
+  }
+
+  if (!onAmend) {
+    return { tool_use_id: id, content: 'Error: amend_session not available in this context', is_error: true };
+  }
+
+  const success = onAmend(sessionId, instruction);
+  if (success) {
+    return { tool_use_id: id, content: `Session ${sessionId} amended. Instruction will be injected at next turn boundary.` };
+  }
+  return { tool_use_id: id, content: `Failed to amend session ${sessionId}. Session may not be running.`, is_error: true };
+}
+
+/**
+ * abort_session: Abort a running session immediately (SV-7)
+ */
+function abortSession(
+  id: string,
+  input: Record<string, unknown>,
+  onAbort?: (sessionId: string) => boolean,
+): ToolResult {
+  const sessionId = String(input.sessionId ?? '');
+  const reason = String(input.reason ?? 'Aborted by supervisor');
+
+  if (!sessionId) {
+    return { tool_use_id: id, content: 'Error: sessionId is required', is_error: true };
+  }
+
+  if (!onAbort) {
+    return { tool_use_id: id, content: 'Error: abort_session not available in this context', is_error: true };
+  }
+
+  const success = onAbort(sessionId);
+  if (success) {
+    return { tool_use_id: id, content: `Session ${sessionId} aborted. Reason: ${reason}` };
+  }
+  return { tool_use_id: id, content: `Failed to abort session ${sessionId}. Session may not be running.`, is_error: true };
+}

package/src/api/src/routes/supervision.ts

@@ -0,0 +1,136 @@
+/**
+ * Supervision API — Long-poll watch + peer session discovery (SV-13)
+ *
+ * GET  /api/supervision/watch?sessions=ses-001,ses-002&duration=120&alertOn=msg:done
+ *   → Long-poll: blocks for duration seconds → returns JSON digest
+ *
+ * GET  /api/supervision/peers?waveId=xxx&roleId=cto
+ *   → Returns peer C-Level sessions in the same wave
+ */
+import { Router, type Request, type Response } from 'express';
+import { ActivityStream } from '../services/activity-stream.js';
+import { digest, quietDigest } from '../services/digest-engine.js';
+import { executionManager } from '../services/execution-manager.js';
+import type { ActivityEvent } from '../../../shared/types.js';
+
+export const supervisionRouter = Router();
+
+/* ─── GET /watch — Long-poll supervision digest ─── */
+
+supervisionRouter.get('/watch', async (req: Request, res: Response) => {
+  const sessionsParam = req.query.sessions as string | undefined;
+  if (!sessionsParam) {
+    res.status(400).json({ error: 'sessions query parameter is required (comma-separated session IDs)' });
+    return;
+  }
+
+  const sessionIds = sessionsParam.split(',').filter(Boolean);
+  if (sessionIds.length === 0) {
+    res.status(400).json({ error: 'At least one session ID is required' });
+    return;
+  }
+
+  const durationSec = Math.min(Math.max(Number(req.query.duration) || 120, 5), 300);
+  const alertOnParam = req.query.alertOn as string | undefined;
+  const alertOn = alertOnParam ? alertOnParam.split(',') : ['msg:done', 'msg:error'];
+  const alertSet = new Set(alertOn);
+
+  // Record start checkpoints
+  const startCheckpoints = new Map<string, number>();
+  for (const sid of sessionIds) {
+    const events = ActivityStream.readAll(sid);
+    startCheckpoints.set(sid, events.length > 0 ? events[events.length - 1].seq + 1 : 0);
+  }
+
+  // Set up event collection
+  const collectedEvents = new Map<string, ActivityEvent[]>();
+  for (const sid of sessionIds) {
+    collectedEvents.set(sid, []);
+  }
+
+  let earlyReturn = false;
+  const unsubscribers: Array<() => void> = [];
+
+  for (const sid of sessionIds) {
+    const stream = ActivityStream.getOrCreate(sid, 'unknown');
+    const handler = (event: ActivityEvent) => {
+      const events = collectedEvents.get(sid);
+      if (events) events.push(event);
+      if (alertSet.has(event.type)) {
+        earlyReturn = true;
+      }
+    };
+    stream.subscribe(handler);
+    unsubscribers.push(() => stream.unsubscribe(handler));
+  }
+
+  // Wait for duration or early return
+  await new Promise<void>((resolve) => {
+    const timeout = setTimeout(resolve, durationSec * 1000);
+    const checkInterval = setInterval(() => {
+      if (earlyReturn) {
+        clearTimeout(timeout);
+        clearInterval(checkInterval);
+        resolve();
+      }
+    }, 500);
+    setTimeout(() => { clearInterval(checkInterval); }, durationSec * 1000 + 100);
+  });
+
+  // Unsubscribe all
+  for (const unsub of unsubscribers) unsub();
+
+  // Fallback: read from JSONL for sessions with no live events
+  for (const sid of sessionIds) {
+    const fromSeq = startCheckpoints.get(sid) ?? 0;
+    const liveEvents = collectedEvents.get(sid) ?? [];
+    if (liveEvents.length === 0) {
+      const fileEvents = ActivityStream.readFrom(sid, fromSeq);
+      collectedEvents.set(sid, fileEvents);
+    }
+  }
+
+  const result = digest(collectedEvents);
+
+  res.json({
+    text: result.text,
+    significanceScore: result.significanceScore,
+    anomalies: result.anomalies,
+    checkpoints: Object.fromEntries(result.checkpoints),
+    eventCount: result.eventCount,
+    errorCount: result.errorCount,
+    earlyReturn,
+  });
+});
+
+/* ─── GET /peers — Peer C-Level session discovery ─── */
+
+supervisionRouter.get('/peers', (req: Request, res: Response) => {
+  const waveId = req.query.waveId as string | undefined;
+  const roleId = req.query.roleId as string | undefined;
+
+  if (!waveId || !roleId) {
+    res.status(400).json({ error: 'waveId and roleId are required' });
+    return;
+  }
+
+  // Find all active executions in the same wave that are C-Level
+  const allExecs = executionManager.listExecutions({ active: true });
+  const peers = allExecs.filter(exec => {
+    if (exec.roleId === roleId) return false; // Exclude self
+    // Check if this execution belongs to the same wave
+    // Wave membership is tracked via session store
+    return true; // For now, return all active C-Level sessions
+  });
+
+  res.json({
+    waveId,
+    roleId,
+    peers: peers.map(p => ({
+      sessionId: p.id,
+      roleId: p.roleId,
+      task: p.task.slice(0, 200),
+      status: p.status,
+    })),
+  });
+});

package/src/api/src/services/digest-engine.ts

@@ -0,0 +1,313 @@
+/**
+ * DigestEngine — Server-side JSONL event summarizer for C-Level supervision.
+ *
+ * Pure TypeScript, zero LLM calls ($0 cost).
+ * Classifies activity events by significance tier, detects anomalies,
+ * and produces a concise digest for C-Level consumption.
+ *
+ * SV-2: Core supervision service
+ */
+import type { ActivityEvent, ActivityEventType } from '../../../shared/types.js';
+
+/* ─── Types ──────────────────────────────────── */
+
+export interface Anomaly {
+  type: 'error' | 'stall' | 'scope_creep' | 'awaiting_input' | 'budget_warning';
+  sessionId: string;
+  message: string;
+  severity: number; // 0-10
+}
+
+export interface DigestResult {
+  text: string;                      // C-Level readable summary (<500 tokens quiet, <2000 active)
+  significanceScore: number;         // 0-10
+  anomalies: Anomaly[];
+  checkpoints: Map<string, number>;  // sessionId → lastSeq
+  peerActivity?: string;             // peer C-Level activity summary
+  eventCount: number;
+  errorCount: number;
+}
+
+/* ─── Event Classification ───────────────────── */
+
+type EventTier = 'critical' | 'high' | 'medium' | 'low';
+
+const EVENT_TIER_MAP: Partial<Record<ActivityEventType, EventTier>> = {
+  'msg:error': 'critical',
+  'msg:awaiting_input': 'critical',
+  'dispatch:start': 'high',
+  'dispatch:done': 'high',
+  'msg:done': 'high',
+  'msg:start': 'high',
+  'thinking': 'medium',
+  'text': 'low',
+  'stderr': 'medium',
+  'turn:complete': 'low',
+  'turn:warning': 'high',
+  'turn:limit': 'critical',
+};
+
+const TIER_WEIGHT: Record<EventTier, number> = {
+  critical: 10,
+  high: 5,
+  medium: 2,
+  low: 0,
+};
+
+function classifyEvent(event: ActivityEvent): EventTier {
+  // tool:start classification depends on tool name
+  if (event.type === 'tool:start') {
+    const toolName = (event.data?.name as string) ?? '';
+    const highTools = ['write_file', 'edit_file', 'bash_execute', 'dispatch', 'consult'];
+    if (highTools.includes(toolName)) return 'high';
+    return 'medium';
+  }
+
+  if (event.type === 'tool:result') {
+    const isError = event.data?.is_error === true;
+    return isError ? 'high' : 'low';
+  }
+
+  return EVENT_TIER_MAP[event.type] ?? 'low';
+}
+
+/* ─── Anomaly Detection ──────────────────────── */
+
+interface SessionState {
+  sessionId: string;
+  roleId: string;
+  lastEventTs: number;
+  eventCount: number;
+  errorCount: number;
+  isDone: boolean;
+  isError: boolean;
+  isAwaitingInput: boolean;
+  toolCalls: string[];       // tool names used
+  filesModified: string[];   // file paths modified
+}
+
+function detectAnomalies(
+  sessionStates: Map<string, SessionState>,
+  now: number,
+): Anomaly[] {
+  const anomalies: Anomaly[] = [];
+
+  for (const [sessionId, state] of sessionStates) {
+    // Stall detection: 3+ minutes without events
+    if (!state.isDone && !state.isError && !state.isAwaitingInput) {
+      const silenceMs = now - state.lastEventTs;
+      if (silenceMs > 3 * 60 * 1000) {
+        anomalies.push({
+          type: 'stall',
+          sessionId,
+          message: `Session ${sessionId} (${state.roleId}): No events for ${Math.round(silenceMs / 60000)}min`,
+          severity: 7,
+        });
+      }
+    }
+
+    // Error detection
+    if (state.isError) {
+      anomalies.push({
+        type: 'error',
+        sessionId,
+        message: `Session ${sessionId} (${state.roleId}): Ended with error`,
+        severity: 10,
+      });
+    }
+
+    // Awaiting input
+    if (state.isAwaitingInput) {
+      anomalies.push({
+        type: 'awaiting_input',
+        sessionId,
+        message: `Session ${sessionId} (${state.roleId}): Awaiting input`,
+        severity: 8,
+      });
+    }
+  }
+
+  return anomalies;
+}
+
+/* ─── Digest Builder ─────────────────────────── */
+
+function buildDigestText(
+  sessionStates: Map<string, SessionState>,
+  eventsBySession: Map<string, ActivityEvent[]>,
+  anomalies: Anomaly[],
+  significanceScore: number,
+): string {
+  const parts: string[] = [];
+
+  // Header
+  const totalEvents = Array.from(eventsBySession.values()).reduce((sum, evts) => sum + evts.length, 0);
+  const totalErrors = Array.from(sessionStates.values()).reduce((sum, s) => sum + s.errorCount, 0);
+  const activeSessions = Array.from(sessionStates.values()).filter(s => !s.isDone && !s.isError).length;
+  const doneSessions = Array.from(sessionStates.values()).filter(s => s.isDone).length;
+
+  parts.push(`## Supervision Digest [score: ${significanceScore}/10]`);
+  parts.push(`Sessions: ${activeSessions} active, ${doneSessions} done | Events: ${totalEvents} | Errors: ${totalErrors}`);
+  parts.push('');
+
+  // Anomalies first (most important)
+  if (anomalies.length > 0) {
+    parts.push('### ⚠️ Anomalies');
+    for (const a of anomalies) {
+      const icon = a.type === 'error' ? '🔴' : a.type === 'stall' ? '🟡' : a.type === 'awaiting_input' ? '🟠' : '⚪';
+      parts.push(`- ${icon} **${a.type}**: ${a.message}`);
+    }
+    parts.push('');
+  }
+
+  // Per-session summary
+  parts.push('### Session Activity');
+  for (const [sessionId, state] of sessionStates) {
+    const events = eventsBySession.get(sessionId) ?? [];
+    const status = state.isDone ? '✅ Done' : state.isError ? '❌ Error' : state.isAwaitingInput ? '🟠 Awaiting' : '🔵 Active';
+
+    parts.push(`**[${state.roleId}]** ${sessionId} — ${status} (${events.length} events)`);
+
+    // Highlight significant events
+    const significant = events.filter(e => {
+      const tier = classifyEvent(e);
+      return tier === 'critical' || tier === 'high';
+    });
+
+    for (const evt of significant.slice(-5)) { // Last 5 significant events
+      const summary = summarizeEvent(evt);
+      if (summary) parts.push(`  - ${summary}`);
+    }
+  }
+
+  return parts.join('\n');
+}
+
+function summarizeEvent(event: ActivityEvent): string | null {
+  switch (event.type) {
+    case 'msg:start':
+      return `Started: ${(event.data?.task as string ?? '').slice(0, 80)}`;
+    case 'msg:done':
+      return `Completed (${event.data?.turns ?? '?'} turns)`;
+    case 'msg:error':
+      return `Error: ${(event.data?.message as string ?? 'unknown').slice(0, 100)}`;
+    case 'msg:awaiting_input':
+      return `Awaiting input: ${(event.data?.question as string ?? '').slice(0, 80)}`;
+    case 'dispatch:start':
+      return `Dispatched → ${event.data?.targetRoleId}: ${(event.data?.task as string ?? '').slice(0, 60)}`;
+    case 'dispatch:done':
+      return `Dispatch completed: ${event.data?.targetRoleId}`;
+    case 'tool:start': {
+      const toolName = event.data?.name as string ?? 'unknown';
+      const input = event.data?.input as Record<string, unknown> | undefined;
+      if (toolName === 'write_file' || toolName === 'edit_file') {
+        return `${toolName}: ${(input?.path as string ?? '').slice(0, 60)}`;
+      }
+      if (toolName === 'bash_execute') {
+        return `bash: ${(input?.command as string ?? '').slice(0, 60)}`;
+      }
+      return null; // Skip read-only tools in summary
+    }
+    case 'turn:warning':
+      return `⚠️ Turn limit warning (${event.data?.turn}/${event.data?.hardLimit})`;
+    case 'turn:limit':
+      return `🔴 Turn limit reached (${event.data?.turn})`;
+    default:
+      return null;
+  }
+}
+
+/* ─── Public API ─────────────────────────────── */
+
+/**
+ * Digest a set of events from multiple sessions.
+ *
+ * @param eventsBySession - Map of sessionId → events collected during the watch period
+ * @param peerEvents - Optional events from peer C-Level sessions
+ */
+export function digest(
+  eventsBySession: Map<string, ActivityEvent[]>,
+  peerEvents?: Map<string, ActivityEvent[]>,
+): DigestResult {
+  const now = Date.now();
+  const sessionStates = new Map<string, SessionState>();
+  const checkpoints = new Map<string, number>();
+
+  // Build session states
+  for (const [sessionId, events] of eventsBySession) {
+    if (events.length === 0) continue;
+
+    const state: SessionState = {
+      sessionId,
+      roleId: events[0].roleId,
+      lastEventTs: new Date(events[events.length - 1].ts).getTime(),
+      eventCount: events.length,
+      errorCount: events.filter(e => e.type === 'msg:error' || (e.type === 'tool:result' && e.data?.is_error)).length,
+      isDone: events.some(e => e.type === 'msg:done'),
+      isError: events.some(e => e.type === 'msg:error'),
+      isAwaitingInput: events.some(e => e.type === 'msg:awaiting_input') && !events.some(e => e.type === 'msg:done'),
+      toolCalls: events.filter(e => e.type === 'tool:start').map(e => e.data?.name as string).filter(Boolean),
+      filesModified: events
+        .filter(e => e.type === 'tool:start' && ['write_file', 'edit_file'].includes(e.data?.name as string))
+        .map(e => (e.data?.input as Record<string, unknown>)?.path as string)
+        .filter(Boolean),
+    };
+    sessionStates.set(sessionId, state);
+    checkpoints.set(sessionId, events[events.length - 1].seq);
+  }
+
+  // Calculate significance score
+  let maxWeight = 0;
+  for (const events of eventsBySession.values()) {
+    for (const event of events) {
+      const tier = classifyEvent(event);
+      const weight = TIER_WEIGHT[tier];
+      if (weight > maxWeight) maxWeight = weight;
+    }
+  }
+
+  const anomalies = detectAnomalies(sessionStates, now);
+  const anomalyBoost = anomalies.length > 0 ? Math.min(anomalies.reduce((sum, a) => sum + a.severity, 0), 10) : 0;
+  const significanceScore = Math.min(10, Math.max(maxWeight, anomalyBoost));
+
+  // Build digest text
+  const text = buildDigestText(sessionStates, eventsBySession, anomalies, significanceScore);
+
+  // Peer activity digest
+  let peerActivity: string | undefined;
+  if (peerEvents && peerEvents.size > 0) {
+    const peerLines: string[] = ['## Peer Activity'];
+    for (const [sessionId, events] of peerEvents) {
+      if (events.length === 0) continue;
+      const roleId = events[0].roleId;
+      const significant = events.filter(e => {
+        const tier = classifyEvent(e);
+        return tier === 'critical' || tier === 'high';
+      });
+      for (const evt of significant.slice(-3)) {
+        const summary = summarizeEvent(evt);
+        if (summary) peerLines.push(`[${roleId}] ${summary}`);
+      }
+    }
+    if (peerLines.length > 1) {
+      peerActivity = peerLines.join('\n');
+    }
+  }
+
+  return {
+    text: peerActivity ? `${text}\n\n${peerActivity}` : text,
+    significanceScore,
+    anomalies,
+    checkpoints,
+    peerActivity,
+    eventCount: Array.from(eventsBySession.values()).reduce((sum, evts) => sum + evts.length, 0),
+    errorCount: Array.from(sessionStates.values()).reduce((sum, s) => sum + s.errorCount, 0),
+  };
+}
+
+/**
+ * Generate a quiet tick summary (for significanceScore < 2 && no anomalies)
+ */
+export function quietDigest(sessionCount: number, eventCount: number, errorCount: number): string {
+  return `All ${sessionCount} sessions progressing normally. No anomalies. [${eventCount} events, ${errorCount} errors]`;
+}

package/src/api/src/services/execution-manager.ts

@@ -249,6 +249,12 @@ class ExecutionManager {
           ...process.env,
           ...portEnv,
         },
+        // SV-6, SV-7: Supervision callbacks (direct-api runner only)
+        onAbortSession: (sessionId: string) => this.abortSession(sessionId),
+        onAmendSession: (sessionId: string, instruction: string) => {
+          const result = this.continueSession(sessionId, `[SUPERVISION AMENDMENT] ${instruction}`, params.roleId);
+          return result !== null;
+        },
       },
       {
         onText: (text) => {

package/src/shared/types.ts

@@ -82,6 +82,8 @@ export type ActivityEventType =
   | 'import:scan' | 'import:process' | 'import:created'
   // Trace (full prompt/response capture for AI debugging)
   | 'trace:prompt' | 'trace:response'
+  // Supervision (C-Level heartbeat)
+  | 'heartbeat:tick' | 'heartbeat:skip'
   // Other
   | 'stderr';