harnery 0.8.0 → 0.10.0

package/src/core/hooks/cli.ts

@@ -27,6 +27,17 @@ import { consumeSince, writeCursor } from "../agents/events/consume.ts";
 import { evaluateStopHook } from "../agents/rules/stop-hook.ts";
 import { projectHeartbeats } from "../agents/state/heartbeat-projector.ts";
 import { shellMutationPaths } from "../agents/state/shell-mutation.ts";
+import {
+  checkpointContext,
+  completeContextRecovery,
+  extractContextSample,
+  markContextCompactionCompleted,
+  type PreparedContextRecovery,
+  prepareContextRecovery,
+  readContextState,
+  recordContextSample,
+} from "../context/index.ts";
+import { ensureRelayDaemon, fetchPresence, publishPresence } from "../presence/index.ts";
 import {
   captureImages,
   detectPresence,
@@ -94,6 +105,17 @@ async function readStdin(): Promise<string> {
   }
 }
 
+/**
+ * Env for child agent-coord spawns, with the coord root pinned. The hook
+ * process may be running with the session shell's cwd (inside a submodule or
+ * scratch dir), and agent-coord resolves its root from cwd unless overridden —
+ * without the pin a child could write state to a different .harnery than the
+ * one this hook resolved.
+ */
+function childEnv(coordRoot: string): NodeJS.ProcessEnv {
+  return { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: coordRoot };
+}
+
 function appendDebug(coordRoot: string, entry: Record<string, unknown>): void {
   const path = join(coordRoot, ".harnery", "debug", "agent-hook.ndjson");
   try {
@@ -143,6 +165,7 @@ function assignNameViaAgentCoord(
     const result = spawnSync(binary, ["assign-name", instanceId, kind], {
       encoding: "utf8",
       timeout: 2000,
+      env: childEnv(coordRoot),
     });
     if (result.status !== 0 || !result.stdout) return null;
     const parsed = JSON.parse(result.stdout.trim()) as {
@@ -254,6 +277,12 @@ function buildEventData(
         name: assigned?.name,
         kind: "session",
         agent_id: ctx.instanceId,
+        // Workflow-child linkage: `workflow run` children carry the run id in
+        // env (spawn adapters set it via buildChildEnv), so their sessions and
+        // heartbeats join back to the run journal + /workflows web view.
+        ...(coordEnv("WORKFLOW_CHILD") === "1" && coordEnv("WORKFLOW_RUN_ID")
+          ? { workflow_run_id: coordEnv("WORKFLOW_RUN_ID") }
+          : {}),
       };
     }
 
@@ -368,9 +397,49 @@ function buildEventData(
         ...(summary.truncated ? { truncated: true } : {}),
       };
     }
+
+    case "context.compaction.started": {
+      const metadata = objectRecord(p?.raw.compact_metadata);
+      return {
+        trigger: stringField(p?.raw.trigger) ?? stringField(metadata?.trigger),
+        pre_tokens:
+          numberField(p?.raw.pre_tokens) ??
+          numberField(metadata?.pre_tokens) ??
+          numberField(metadata?.pre_compact_tokens),
+      };
+    }
+
+    case "context.compaction.completed": {
+      const metadata = objectRecord(p?.raw.compact_metadata);
+      return {
+        trigger: stringField(p?.raw.trigger) ?? stringField(metadata?.trigger),
+        pre_tokens:
+          numberField(p?.raw.pre_tokens) ??
+          numberField(metadata?.pre_tokens) ??
+          numberField(metadata?.pre_compact_tokens),
+        post_tokens:
+          numberField(p?.raw.post_tokens) ??
+          numberField(metadata?.post_tokens) ??
+          numberField(metadata?.post_compact_tokens),
+      };
+    }
   }
 }
 
+function objectRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberField(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
 async function main(): Promise<number> {
   const { eventName, extra } = parseArgv(process.argv.slice(2));
   const harness = detectHarness(process.argv.slice(2));
@@ -471,6 +540,84 @@ async function main(): Promise<number> {
     event_id: envelope.event_id,
   });
 
+  // Context telemetry is opportunistic and truthful: only persist a sample
+  // when the harness payload actually exposes usage/window data. Identical
+  // measurements are de-duplicated before they reach the canonical stream.
+  if (payload?.raw) {
+    try {
+      const sample = extractContextSample(payload.raw, {
+        sessionId,
+        harness,
+        model: payload.model,
+        source: "hook",
+        confidence: "reported",
+      });
+      if (sample) {
+        const recorded = recordContextSample(coordRoot, owner.instance_id, sample);
+        if (recorded.changed) {
+          emit(coordRoot, {
+            event_type: "context.sampled",
+            instance_id: owner.instance_id,
+            session_id: sessionId,
+            harness,
+            data: {
+              model: sample.model,
+              used_tokens: sample.used_tokens,
+              window_tokens: sample.window_tokens,
+              used_percent: sample.used_percent,
+              telemetry_source: sample.source,
+              confidence: sample.confidence,
+            },
+          });
+        }
+      }
+    } catch (err) {
+      logError(coordRoot, err, { phase: "context-sample" });
+    }
+  }
+
+  // A native pre-compaction signal is the safest available point to capture
+  // external work state. The operation is idempotent until recovery, so a
+  // harness retry cannot create a storm of near-identical capsules.
+  if (norm.event_type === "context.compaction.started") {
+    try {
+      const checkpoint = checkpointContext(coordRoot, {
+        sessionId,
+        instanceId: owner.instance_id,
+        harness,
+        cwd: payload?.cwd ?? process.cwd(),
+        reason: "pre_compact",
+        model: payload?.model,
+      });
+      emit(coordRoot, {
+        event_type: "context.checkpoint.created",
+        instance_id: owner.instance_id,
+        session_id: sessionId,
+        harness,
+        data: {
+          capsule_id: checkpoint.capsule.capsule_id,
+          generation: checkpoint.capsule.generation,
+          path: checkpoint.state.latest_capsule ?? "",
+          reason: checkpoint.capsule.reason,
+          reused: checkpoint.reused,
+        },
+      });
+    } catch (err) {
+      logError(coordRoot, err, { phase: "context-checkpoint" });
+    }
+  }
+
+  if (norm.event_type === "context.compaction.completed") {
+    try {
+      markContextCompactionCompleted(coordRoot, {
+        sessionId,
+        instanceId: owner.instance_id,
+      });
+    } catch (err) {
+      logError(coordRoot, err, { phase: "context-compaction-completed" });
+    }
+  }
+
   // Phase 8: SessionStart post-emit: project the event so the heartbeat
   // lands synchronously, run stale-sweep, and emit the harness-shaped
   // systemMessage JSON (peer table + wiring check + council invites).
@@ -489,11 +636,61 @@ async function main(): Promise<number> {
     } catch (err) {
       logError(coordRoot, err, { phase: "session-start-image-janitor" });
     }
+    let recovery: PreparedContextRecovery | null = null;
+    if (payload?.source === "compact") {
+      try {
+        emit(coordRoot, {
+          event_type: "context.compaction.completed",
+          instance_id: owner.instance_id,
+          session_id: sessionId,
+          harness,
+          data: { trigger: "auto" },
+        });
+        markContextCompactionCompleted(coordRoot, {
+          sessionId,
+          instanceId: owner.instance_id,
+        });
+        recovery = prepareContextRecovery(coordRoot, {
+          instanceId: owner.instance_id,
+          sessionId,
+          cwd: payload?.cwd ?? process.cwd(),
+        });
+      } catch (err) {
+        logError(coordRoot, err, { phase: "context-recovery-session-start" });
+      }
+    }
     try {
-      await emitSessionStartSystemMessage(coordRoot, owner.instance_id, sessionId, data, harness);
+      const injected = await emitSessionStartSystemMessage(
+        coordRoot,
+        owner.instance_id,
+        sessionId,
+        data,
+        harness,
+        recovery?.briefing ?? "",
+      );
+      if (injected && recovery) {
+        completeRecoveryInjection(
+          coordRoot,
+          owner.instance_id,
+          sessionId,
+          harness,
+          recovery,
+          "SessionStart",
+        );
+      }
     } catch (err) {
       logError(coordRoot, err, { phase: "session-start-systemMessage" });
     }
+    // Cross-machine presence (ADR 0016): announce this machine's sessions and
+    // pull peers'. Both are throttled + fail-silent; network runs detached.
+    // When a relay is configured, also make sure the live-socket daemon runs.
+    try {
+      publishPresence(coordRoot);
+      fetchPresence(coordRoot);
+      ensureRelayDaemon(coordRoot);
+    } catch (err) {
+      logError(coordRoot, err, { phase: "session-start-presence" });
+    }
   }
 
   // Phase 8: SessionEnd cleanup: delete heartbeat + pid-map rows. Harness-
@@ -510,6 +707,13 @@ async function main(): Promise<number> {
       scratchArchive(coordRoot, owner.instance_id);
       runSessionSyncExtension(coordRoot, true);
     }
+    // Presence: publish the post-cleanup state so peers see this session gone
+    // promptly rather than waiting out the remote-stale window.
+    try {
+      publishPresence(coordRoot);
+    } catch (err) {
+      logError(coordRoot, err, { phase: "session-end-presence" });
+    }
   }
 
   // Phase 8: SubagentStart: sync-project to create the subagent heartbeat,
@@ -519,7 +723,11 @@ async function main(): Promise<number> {
     try {
       const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
       if (existsSync(agentCoordBin)) {
-        spawnSync(agentCoordBin, ["project"], { encoding: "utf8", timeout: 3000 });
+        spawnSync(agentCoordBin, ["project"], {
+          encoding: "utf8",
+          timeout: 3000,
+          env: childEnv(coordRoot),
+        });
         spawnSync(
           agentCoordBin,
           [
@@ -528,7 +736,7 @@ async function main(): Promise<number> {
             "--instance",
             owner.instance_id,
           ],
-          { encoding: "utf8", timeout: 2000 },
+          { encoding: "utf8", timeout: 2000, env: childEnv(coordRoot) },
         );
       }
       emitSubagentStartContext(coordRoot, owner.instance_id, sessionId, data, harness);
@@ -551,7 +759,7 @@ async function main(): Promise<number> {
             "--instance",
             owner.instance_id,
           ],
-          { encoding: "utf8", timeout: 2000 },
+          { encoding: "utf8", timeout: 2000, env: childEnv(coordRoot) },
         );
       }
     } catch (err) {
@@ -569,8 +777,47 @@ async function main(): Promise<number> {
       const prompt = (payload?.raw?.prompt as string | undefined) ?? "";
       if (prompt) detectPresence(prompt);
     }
+    // Presence: throttled pull of peer machines' presence refs (default 60s
+    // interval; the systemMessage below reads whatever is locally known).
     try {
-      await emitUserPromptSubmitSystemMessage(coordRoot, owner.instance_id, sessionId, harness);
+      fetchPresence(coordRoot);
+    } catch (err) {
+      logError(coordRoot, err, { phase: "user-prompt-submit-presence" });
+    }
+    let recovery: PreparedContextRecovery | null = null;
+    const continuityState = readContextState(coordRoot, sessionId);
+    if (
+      continuityState?.phase === "checkpointed" &&
+      continuityState.compaction_completed_at !== undefined
+    ) {
+      try {
+        recovery = prepareContextRecovery(coordRoot, {
+          instanceId: owner.instance_id,
+          sessionId,
+          cwd: payload?.cwd ?? process.cwd(),
+        });
+      } catch (err) {
+        logError(coordRoot, err, { phase: "context-recovery-user-prompt" });
+      }
+    }
+    try {
+      const injected = await emitUserPromptSubmitSystemMessage(
+        coordRoot,
+        owner.instance_id,
+        sessionId,
+        harness,
+        recovery?.briefing ?? "",
+      );
+      if (injected && recovery) {
+        completeRecoveryInjection(
+          coordRoot,
+          owner.instance_id,
+          sessionId,
+          harness,
+          recovery,
+          "UserPromptSubmit",
+        );
+      }
     } catch (err) {
       logError(coordRoot, err, { phase: "user-prompt-submit-systemMessage" });
     }
@@ -623,6 +870,17 @@ async function main(): Promise<number> {
       logError(coordRoot, err, { phase: "stop-projection" });
     }
 
+    // Presence: publish AFTER the projection above so the blob carries this
+    // turn's fresh task/turn_summary/files. Change-batched + keepalive'd;
+    // the push itself runs detached. The relay daemon (when configured) is
+    // re-ensured here too — it self-exits on idle, and the next turn revives it.
+    try {
+      publishPresence(coordRoot);
+      ensureRelayDaemon(coordRoot);
+    } catch (err) {
+      logError(coordRoot, err, { phase: "stop-presence" });
+    }
+
     // Stop verdict (status-box + set-task gate). Direct in-process call: the
     // rule lives in harnery. agent-hook already emitted this turn.stop (with
     // status_box_present) above, so the evidence is in the stream.
@@ -632,6 +890,7 @@ async function main(): Promise<number> {
       session_id: sessionId,
       harness,
       bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
+      workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
     });
     if (!verdict.allow) {
       // Harness-aware enforcement channel: Claude Code / Codex honor exit-2 +
@@ -796,6 +1055,7 @@ async function runPreToolUseGuard(
       input: verdictReq,
       encoding: "utf8",
       timeout: 3000,
+      env: childEnv(coordRoot),
     });
     if (result.status !== 0 || !result.stdout) continue;
     let parsed: { allow?: boolean; reason?: string } = {};
@@ -893,6 +1153,7 @@ function healHeartbeatViaCli(
   spawnSync(agentCoordBin, ["heal-heartbeat", instanceId, sessionId, `--harness=${harness}`], {
     encoding: "utf8",
     timeout: 2000,
+    env: childEnv(coordRoot),
   });
 }
 
@@ -1000,6 +1261,7 @@ function stampToolActivity(
   spawnSync(agentCoordBin, ["stamp-tool-activity", instanceId, toolName, target], {
     encoding: "utf8",
     timeout: 2000,
+    env: childEnv(coordRoot),
   });
 }
 
@@ -1051,6 +1313,7 @@ function releaseClaimOnFailure(
   spawnSync(agentCoordBin, ["release-claim", instanceId, canonical], {
     encoding: "utf8",
     timeout: 2000,
+    env: childEnv(coordRoot),
   });
 }
 
@@ -1101,36 +1364,42 @@ async function emitUserPromptSubmitSystemMessage(
   instanceId: string,
   sessionId: string,
   harness: Harness,
-): Promise<void> {
+  recoveryBriefing = "",
+): Promise<boolean> {
   const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
-  if (!existsSync(agentCoordBin)) return;
+  let additionalContext = "";
 
-  // Look up the agent's name from its heartbeat (for council pending rendering).
-  let agentName = "";
-  try {
-    const fs = require("node:fs") as typeof import("node:fs");
-    const hbPath = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
-    if (fs.existsSync(hbPath)) {
-      const hb = JSON.parse(fs.readFileSync(hbPath, "utf8")) as { name?: string };
-      agentName = hb.name ?? "";
+  if (existsSync(agentCoordBin)) {
+    // Look up the agent's name from its heartbeat (for council pending rendering).
+    let agentName = "";
+    try {
+      const fs = require("node:fs") as typeof import("node:fs");
+      const hbPath = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+      if (fs.existsSync(hbPath)) {
+        const hb = JSON.parse(fs.readFileSync(hbPath, "utf8")) as { name?: string };
+        agentName = hb.name ?? "";
+      }
+    } catch {
+      /* fall through with empty name; peer table still renders */
     }
-  } catch {
-    /* fall through with empty name; peer table still renders */
-  }
 
-  const args = ["prompt-context", "--instance", instanceId, "--session", sessionId];
-  if (agentName) args.push("--name", agentName);
-  // Cursor + Codex sessions get the set-task staleness nudge. CC enforces it
-  // via the Stop-hook transcript scan; the nudge replaces that for harnesses
-  // that don't reliably expose a transcript_path during stop.
-  if (harness === "cursor" || harness === "codex") args.push("--task-nudge");
-  const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
-  if (result.status !== 0 || !result.stdout) return;
-  const additionalContext = result.stdout.trim();
-  if (!additionalContext) return;
+    const args = ["prompt-context", "--instance", instanceId, "--session", sessionId];
+    if (agentName) args.push("--name", agentName);
+    // Cursor + Codex sessions get the set-task staleness nudge. CC enforces it
+    // via the Stop-hook transcript scan; the nudge replaces that for harnesses
+    // that don't reliably expose a transcript_path during stop.
+    if (harness === "cursor" || harness === "codex") args.push("--task-nudge");
+    const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
+    if (result.status === 0 && result.stdout) additionalContext = result.stdout.trim();
+  }
+  if (recoveryBriefing) {
+    additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
+  }
+  if (!additionalContext) return false;
 
   const { emitContext } = await import("./harness/output.ts");
   emitContext(harness, "UserPromptSubmit", additionalContext);
+  return true;
 }
 
 function emitSubagentStartContext(
@@ -1183,45 +1452,45 @@ async function emitSessionStartSystemMessage(
   sessionId: string,
   emittedData: Record<string, unknown>,
   harness: Harness,
-): Promise<void> {
+  recoveryBriefing = "",
+): Promise<boolean> {
   const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
-  if (!existsSync(agentCoordBin)) return;
+  let additionalContext = "";
+  if (existsSync(agentCoordBin)) {
+    // Sync-project so the heartbeat exists for downstream readers (peer table,
+    // wiring check, council invites).
+    spawnSync(agentCoordBin, ["project"], { encoding: "utf8", timeout: 3000 });
+    // Stale-sweep dead peers before rendering peer table.
+    spawnSync(agentCoordBin, ["stale-sweep"], { encoding: "utf8", timeout: 3000 });
+
+    // SESSION_START activity log line, fired across all harnesses.
+    const model = (emittedData.model as string | undefined) ?? "unknown";
+    const source = (emittedData.source as string | undefined) ?? "startup";
+    const platform = harnessPlatform(harness);
+    spawnSync(
+      agentCoordBin,
+      [
+        "log",
+        `SESSION_START   model=${model} source=${source} platform=${platform}`,
+        "--instance",
+        instanceId,
+      ],
+      { encoding: "utf8", timeout: 2000 },
+    );
 
-  // Sync-project so the heartbeat exists for downstream readers (peer table,
-  // wiring check, council invites).
-  spawnSync(agentCoordBin, ["project"], { encoding: "utf8", timeout: 3000 });
-  // Stale-sweep dead peers before rendering peer table.
-  spawnSync(agentCoordBin, ["stale-sweep"], { encoding: "utf8", timeout: 3000 });
-
-  // SESSION_START activity log line, fired across all harnesses.
-  const model = (emittedData.model as string | undefined) ?? "unknown";
-  const source = (emittedData.source as string | undefined) ?? "startup";
-  const platform = harnessPlatform(harness);
-  spawnSync(
-    agentCoordBin,
-    [
-      "log",
-      `SESSION_START   model=${model} source=${source} platform=${platform}`,
-      "--instance",
-      instanceId,
-    ],
-    { encoding: "utf8", timeout: 2000 },
-  );
-
-  // Render the systemMessage via agent-coord.
-  const agentName = (emittedData.name as string | undefined) ?? "";
-  const args = ["session-context", "--instance", instanceId, "--session", sessionId];
-  if (agentName) args.push("--name", agentName);
-  // The "You are agent-X." prefix in session-context renders unqualified by
-  // default (claude-code-style). For cursor/codex the bash dispatchers add
-  // a "(Cursor)" / "(Codex)" suffix; pass it through as --platform-label.
-  if (harness !== "claude-code") {
-    args.push("--platform-label", platform === "cursor" ? "Cursor" : "Codex");
+    // Render the systemMessage via agent-coord.
+    const agentName = (emittedData.name as string | undefined) ?? "";
+    const args = ["session-context", "--instance", instanceId, "--session", sessionId];
+    if (agentName) args.push("--name", agentName);
+    // The "You are agent-X." prefix in session-context renders unqualified by
+    // default (claude-code-style). For cursor/codex the bash dispatchers add
+    // a "(Cursor)" / "(Codex)" suffix; pass it through as --platform-label.
+    if (harness !== "claude-code") {
+      args.push("--platform-label", platform === "cursor" ? "Cursor" : "Codex");
+    }
+    const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
+    if (result.status === 0 && result.stdout) additionalContext = result.stdout.trim();
   }
-  const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
-  if (result.status !== 0 || !result.stdout) return;
-  let additionalContext = result.stdout.trim();
-  if (!additionalContext) return;
 
   // Effect (claude-code): merge the scratch recovery cue into the session-start
   // context. Was a standalone additionalContext emission from the previous
@@ -1229,11 +1498,38 @@ async function emitSessionStartSystemMessage(
   // entry, it folds in here.
   if (harness === "claude-code") {
     const cue = scratchRecoveryCue(coordRoot);
-    if (cue) additionalContext = `${additionalContext}\n\n${cue}`;
+    if (cue) additionalContext = [additionalContext, cue].filter(Boolean).join("\n\n");
+  }
+  if (recoveryBriefing) {
+    additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
   }
+  if (!additionalContext) return false;
 
   const { emitContext } = await import("./harness/output.ts");
   emitContext(harness, "SessionStart", additionalContext);
+  return true;
+}
+
+function completeRecoveryInjection(
+  coordRoot: string,
+  instanceId: string,
+  sessionId: string,
+  harness: Harness,
+  recovery: PreparedContextRecovery,
+  injectionEvent: "SessionStart" | "UserPromptSubmit",
+): void {
+  completeContextRecovery(coordRoot, { sessionId, instanceId });
+  emit(coordRoot, {
+    event_type: "context.recovery.injected",
+    instance_id: instanceId,
+    session_id: sessionId,
+    harness,
+    data: {
+      capsule_id: recovery.capsule.capsule_id,
+      generation: recovery.capsule.generation,
+      injection_event: injectionEvent,
+    },
+  });
 }
 
 main()

package/src/core/hooks/events/schema.ts

@@ -47,6 +47,10 @@ export type SessionStart = EventEnvelope<
     cwd: string;
     model?: string;
     pid: number;
+    /** Present iff this session is a `workflow run` child: the run id whose
+     * journal owns it (child env HARNERY_WORKFLOW_RUN_ID). Optional-field
+     * addition per the schema evolution rules (minor bump). */
+    workflow_run_id?: string;
   }
 >;
 
@@ -190,6 +194,56 @@ export type ImageCaptured = EventEnvelope<
   }
 >;
 
+// Context continuity
+export type ContextSampled = EventEnvelope<
+  "context.sampled",
+  {
+    model?: string;
+    used_tokens?: number;
+    window_tokens?: number;
+    used_percent?: number;
+    telemetry_source: "hook" | "native_event" | "result" | "transcript" | "estimate";
+    confidence: "exact" | "reported" | "estimated";
+  }
+>;
+
+export type ContextCheckpointCreated = EventEnvelope<
+  "context.checkpoint.created",
+  {
+    capsule_id: string;
+    generation: number;
+    path: string;
+    reason: "manual" | "pressure" | "pre_compact" | "session_end";
+    reused: boolean;
+  }
+>;
+
+export type ContextCompactionStarted = EventEnvelope<
+  "context.compaction.started",
+  {
+    trigger?: string;
+    pre_tokens?: number;
+  }
+>;
+
+export type ContextCompactionCompleted = EventEnvelope<
+  "context.compaction.completed",
+  {
+    trigger?: string;
+    pre_tokens?: number;
+    post_tokens?: number;
+  }
+>;
+
+export type ContextRecoveryInjected = EventEnvelope<
+  "context.recovery.injected",
+  {
+    capsule_id: string;
+    generation: number;
+    injection_event: "SessionStart" | "UserPromptSubmit";
+  }
+>;
+
 // File claims
 export type ClaimAcquire = EventEnvelope<
   "claim.acquire",
@@ -253,6 +307,18 @@ export type StatePresenceChange = EventEnvelope<
 
 export type StateHeartbeat = EventEnvelope<"state.heartbeat", Record<string, never>>;
 
+/** A live session adopted a durable persona/role. The event is authoritative
+ * for replay; `.name-history` carries the same binding for heartbeat healing. */
+export type IdentityAssumed = EventEnvelope<
+  "identity.assumed",
+  {
+    name: string;
+    agent_id: string;
+    previous_name?: string;
+    previous_agent_id?: string;
+  }
+>;
+
 // Council
 export type CouncilOpen = EventEnvelope<
   "council.open",
@@ -394,6 +460,11 @@ export type Event =
   | ToolPostUseFailure
   | ToolOutputChunk
   | ImageCaptured
+  | ContextSampled
+  | ContextCheckpointCreated
+  | ContextCompactionStarted
+  | ContextCompactionCompleted
+  | ContextRecoveryInjected
   | ClaimAcquire
   | ClaimRelease
   | ClaimConflict
@@ -402,6 +473,7 @@ export type Event =
   | StateScratchAppend
   | StatePresenceChange
   | StateHeartbeat
+  | IdentityAssumed
   | CouncilOpen
   | CouncilRoundOpen
   | CouncilContribution