vericify 1.2.0 → 1.3.1

package/README.md

@@ -8,15 +8,15 @@ __     _______ ____  ___ ____ ___ _______   __
    \_/  |_____|_| \_\___\____|___|_|     |_|
 ```
 
-Vericify is a local-first operations hub for agent work.
+Vericify is a local-first run intelligence hub for multi-agent workflows and AI agent state.
 
-It gives a workspace a durable run model instead of making you reconstruct intent from chat scrollback, shell history, and raw logs.
+It gives a workspace durable run records, checkpointed handoffs, and a four-layer compare engine instead of making you reconstruct intent from chat scrollback, shell history, and raw logs.
 
 It works on its own, and it also plugs neatly into [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm) workspaces that already emit `agent-state/*`.
 
 ## Product Summary
 
-Vericify is for people building with agents who want to answer questions like:
+Vericify is for engineers building with AI agents who want run-level observability and clear answers to questions like:
 
 - What is moving right now?
 - What is blocked?
@@ -41,12 +41,12 @@ Default behavior is simple:
 
 Vericify gives you:
 
-- a terminal cockpit for run inspection
+- a terminal cockpit with four views — Hub, Inspect, Compare, History — for run inspection and agent observability
 - a structured run model built from handoffs, posts, todos, events, and checkpoints
-- a compare engine that explains divergence and recovery
+- a compare engine that measures divergence and recovery across four layers: exact diff, structural delta, semantic similarity (MinHash), and operational timing
 - publishable run artifacts under `.vericify/published/`
 - a local-first sync outbox under `.vericify/sync-outbox/`
-- partner compatibility with [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm)
+- adapter contracts for Claude Code, Codex, Cursor, VS Code Copilot, Antigravity, and [ACE / ace-swarm](https://www.npmjs.com/package/ace-swarm) workspaces
 
 ## Install
 
@@ -62,6 +62,7 @@ Node `18+` is required.
 
 ```bash
 cd /path/to/repo
+vericify context
 vericify adapters
 vericify hub
 ```
@@ -76,6 +77,7 @@ If your workspace already contains `agent-state/*`, Vericify reads it automatica
 
 ```bash
 cd /path/to/ace-workspace
+vericify context
 vericify adapters
 vericify hub
 ```
@@ -93,6 +95,30 @@ vericify adapters
 
 That creates or updates `.vericify/adapters.json` for the current repo and marks the adapter as attached.
 
+For Claude Code, `vericify attach --adapter claude-code` also writes compact-bootstrap guidance into `CLAUDE.md` and, when `.claude/` exists, installs the Vericify hook block into `.claude/settings.json`.
+
+## Compact Bootstrap And Resume
+
+Use the compact packet when you want session bootstrap or resume without rereading the full projected state. This is the primary path for workflow continuity across context resets:
+
+```bash
+vericify context
+vericify delta --since vcx_...
+vericify snapshot --format compact
+```
+
+`vericify context` returns one minified JSON packet with:
+
+- the selected run
+- status
+- current focus
+- blockers
+- a strict `live_signal` subset
+- the last meaningful events
+- a fresh opaque continuity id
+
+Use `--pretty` if you want the compact packet formatted for humans.
+
 ## Do I Need `--session-id`?
 
 No. `--session-id` is optional.
@@ -189,15 +215,16 @@ vericify hub
 
 Best when you already have `agent-state/*` and want a cockpit, history, and compare surface.
 
-### Use case 2: Tag a Codex or Claude Code workspace before richer capture exists
+### Use case 2: Tag a Codex, Claude Code, Cursor, VS Code Copilot, or Antigravity workspace before richer capture exists
 
 ```bash
 vericify attach --adapter codex --label "Primary Codex"
 vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment
+vericify context
 vericify hub
 ```
 
-Best when you want durable workspace metadata now, even before vendor-specific live capture bridges are added.
+Best when you want durable workspace metadata now. Claude Code attach also writes the startup guidance for `vericify context`, the `vericify delta --since=<id>` resume path, and the `PreCompact` reinjection hook when `.claude/` is available.
 
 ### Use case 3: Create a native run trail manually
 
@@ -216,14 +243,13 @@ Best when you want to model agent work directly in Vericify.
 vericify compare --run-id handoff:run-a --compare-run-id workspace:current
 ```
 
-The comparison report includes:
+The comparison runs four layers simultaneously — exact diff, structural graph delta, semantic MinHash similarity, and operational timing analysis — and returns:
 
-- composite similarity
+- composite similarity score
 - latest checkpoint similarity
-- actor overlap
-- node overlap
+- actor and node overlap
 - layer-level divergence cues
-- recovery explanations
+- recovery paths from prior runs
 - recommended next actions
 
 ### Use case 5: Publish or queue a run artifact
@@ -248,7 +274,7 @@ This writes:
 - `Lane`: one concurrent execution stream
 - `Handoff`: transfer of responsibility
 - `Checkpoint`: durable snapshot at a meaningful transition
-- `Delta`: structural, semantic, or operational change between checkpoints
+- `Delta`: change between checkpoints, measured across four layers: exact diff, structural graph, semantic MinHash, and operational timing
 
 ### Storage Contract
 
@@ -319,11 +345,14 @@ Today the package is semantic-first. Git-backed provenance can be attached when
 
 ```bash
 vericify help
+vericify context
+vericify delta --since vcx_...
 vericify adapters
 vericify attach --adapter codex --label "Primary Codex session"
 vericify attach --adapter claude-code --session-id claude-main --capture-mode attachment --label "Claude main"
 vericify hub
 vericify snapshot
+vericify snapshot --format compact
 vericify compare --run-id handoff:run-a --compare-run-id workspace:current
 vericify publish --run-id handoff:run-a
 vericify sync --run-id handoff:run-a --endpoint https://sync.example.test
@@ -354,36 +383,34 @@ Start the cockpit:
 vericify hub
 ```
 
+The cockpit has four views. Each answers a different operational question.
+
 Keys:
 
 - `q` quit
 - `j` / `k` move between runs
-- `Enter` inspect selected run
-- `c` compare selected run
-- `y` history view
-- `h` back to hub
+- `Enter` inspect selected run — lane activity, blockers, checkpoint timeline
+- `c` compare selected run — four-layer diff across exact, structural, semantic, and operational dimensions
+- `y` history view — prior runs indexed, recovery patterns ranked by similarity to the current state
+- `a` adapters view — attached tools and detection status
+- `h` back to hub — all active runs, what is moving, what is blocked
 - `r` refresh
 - `/` command palette
 - `Ctrl+R` command history search
 
 ## Programmatic API
 
-The package also exports:
+The package exports functions for workspace state projection, run comparison, and artifact publishing:
 
 - `loadWorkspaceState`
 - `projectWorkspaceState`
+- `buildCompactPacket`
+- `buildCompactPacketDetails`
+- `buildCompactDelta`
 - `detectAdapters`
+- `listAvailableAdapters`
+- `listDefaultWorkspacePaths`
 - `attachAdapter`
 - `buildRunComparison`
 - `publishRunArtifact`
 - `enqueueSyncOutboxItem`
-
-## Honest Status
-
-Vericify is intentionally honest about what is implemented now.
-
-- peer client adapters are not full live capture bridges yet
-- hosted sync is an outbox contract today, not a running SaaS backend
-- git-backed diffing exists as optional provenance, not the whole product
-
-That is deliberate: the package is meant to be useful now, without pretending unfinished infrastructure already exists.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vericify",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "private": false,
   "type": "module",
   "description": "Local-first run intelligence and operations hub for agent systems.",
@@ -20,6 +20,8 @@
   "scripts": {
     "adapters": "node src/index.js adapters",
     "attach": "node src/index.js attach",
+    "context": "node src/index.js context",
+    "delta": "node src/index.js delta",
     "hub": "node src/index.js hub",
     "compare": "node src/index.js compare",
     "publish:artifact": "node src/index.js publish",

package/src/adapters/claude-attach.js

@@ -0,0 +1 @@
+export { attachClaudeWorkspace } from "./handshake/claude-code.js";

package/src/adapters/handshake/antigravity.js

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { readJson } from "../../core/fs.js";
+import { createHandshakeResult, emitHandshakeStartedEvent, mergeJsonFile, writeInstructionBlock } from "./common.js";
+
+function antigravityInstructionBlock() {
+  return `## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id antigravity --kind blocker --summary "<what is blocking>"\`
+- **Handoff:** \`vericify post --run-id workspace:current --agent-id antigravity --kind handoff_note --summary "<handoff context>"\`
+- **Completion:** \`vericify post --run-id workspace:current --agent-id antigravity --kind completion --summary "<what changed>"\`
+- **Intentional silence:** \`vericify post --run-id workspace:current --agent-id antigravity --kind stale_ack --summary "<reason>"\`
+
+You may also write structured state to \`.antigravity/vericify-state.json\` using the passthrough schema.`;
+}
+
+export function antigravityHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+  const antigravityDir = resolve(workspaceRoot, ".antigravity");
+  const statePath = resolve(antigravityDir, "vericify-state.json");
+  const instructionPath = resolve(antigravityDir, "vericify-instructions.md");
+  const configPath = resolve(workspaceRoot, "antigravity.config.json");
+
+  if (existsSync(antigravityDir)) {
+    try {
+      const stateResult = mergeJsonFile(statePath, (existing) => ({
+        ...(existing && typeof existing === "object" ? existing : {}),
+        _vericify_passthrough: true,
+        handoffs: existing?.handoffs && typeof existing.handoffs === "object" ? existing.handoffs : {},
+        nodes: existing?.nodes && typeof existing.nodes === "object" ? existing.nodes : {},
+        entries: Array.isArray(existing?.entries) ? existing.entries : [],
+        events: Array.isArray(existing?.events) ? existing.events : [],
+        posts: Array.isArray(existing?.posts) ? existing.posts : [],
+      }));
+      result.passthrough_written = Boolean(stateResult.written);
+      result.passthrough_path = statePath;
+      if (stateResult.skipped) skippedReasons.push(stateResult.reason);
+    } catch (error) {
+      skippedReasons.push(`.antigravity/vericify-state.json write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    try {
+      const instructionResult = writeInstructionBlock(instructionPath, "## Vericify Process Posts", antigravityInstructionBlock(), {
+        createIfAbsent: true,
+        createDirs: true,
+      });
+      result.instruction_written = Boolean(instructionResult.written);
+      result.instruction_path = instructionPath;
+      if (instructionResult.skipped) skippedReasons.push(instructionResult.reason);
+    } catch (error) {
+      skippedReasons.push(`antigravity instructions write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    if (existsSync(configPath)) {
+      const config = readJson(configPath, null);
+      const hasVericifyConfig = Boolean(config && typeof config === "object" && "vericify" in config);
+      if (hasVericifyConfig) {
+        skippedReasons.push("antigravity.config.json already contains vericify keys; left unchanged");
+      }
+    }
+  } else {
+    skippedReasons.push(".antigravity directory is missing; passthrough config and instructions skipped");
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "antigravity",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: false,
+    instructionWritten: result.instruction_written,
+    passthroughWritten: result.passthrough_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...eventResult.skipped_reasons].filter(Boolean),
+  };
+}

package/src/adapters/handshake/claude-code.js

@@ -0,0 +1,150 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { readJson, readText } from "../../core/fs.js";
+import { createHandshakeResult, emitHandshakeStartedEvent } from "./common.js";
+
+const CLAUDE_DIR = ".claude";
+const CLAUDE_SETTINGS_FILE = "settings.json";
+const VERICIFY_MARKER = "<!-- vericify-instruction -->";
+const VERICIFY_END_MARKER = "<!-- /vericify-instruction -->";
+const VERICIFY_CONTEXT_COMMAND = "vericify context";
+const VERICIFY_CONTEXT_RESUME_COMMAND = "vericify delta --since=<id>";
+const VERICIFY_PRECOMPACT_COMMAND = "vericify context --run-id workspace:current";
+
+function markerBlock() {
+  return `${VERICIFY_MARKER}
+## Vericify Bootstrap
+
+At session start, run \`${VERICIFY_CONTEXT_COMMAND}\` and use that packet as the default bootstrap surface.
+
+Between sessions, prefer \`${VERICIFY_CONTEXT_RESUME_COMMAND}\` over rereading raw ACE files.
+
+When Claude compaction fires, re-inject \`${VERICIFY_PRECOMPACT_COMMAND}\`.
+
+## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id claude-code --kind blocker --summary "<what is blocking and what is needed>"\`
+- **Handoff initiated or acknowledged:** \`vericify post --run-id workspace:current --agent-id claude-code --kind handoff_note --summary "<what was handed off and what is expected next>"\`
+- **Meaningful work completed:** \`vericify post --run-id workspace:current --agent-id claude-code --kind completion --summary "<what changed and what is now true>"\`
+- **Extended silence is intentional:** \`vericify post --run-id workspace:current --agent-id claude-code --kind stale_ack --summary "<why silence is expected and when to re-check>"\`
+
+These posts are how Vericify tracks run narrative. Without them the hub cannot distinguish active silence from stale work.
+${VERICIFY_END_MARKER}`;
+}
+
+function upsertClaudeInstruction(workspaceRoot) {
+  const path = resolve(workspaceRoot, "CLAUDE.md");
+  const existing = readText(path, "");
+  const nextBlock = markerBlock();
+  const blockPattern = new RegExp(`${VERICIFY_MARKER}[\\s\\S]*?${VERICIFY_END_MARKER}`);
+  const prefix = existing.trimEnd();
+  const next = blockPattern.test(existing)
+    ? existing.replace(blockPattern, nextBlock)
+    : prefix
+      ? `${prefix}\n\n${nextBlock}\n`
+      : `${nextBlock}\n`;
+  if (next !== existing) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next);
+    return { path, written: true };
+  }
+  return { path, written: false };
+}
+
+function upsertClaudeSettings(workspaceRoot, commands) {
+  const claudeDir = resolve(workspaceRoot, CLAUDE_DIR);
+  const settingsPath = join(claudeDir, CLAUDE_SETTINGS_FILE);
+  if (!existsSync(claudeDir)) {
+    return {
+      path: settingsPath,
+      written: false,
+      skipped_reason: `${CLAUDE_DIR} directory is missing; Claude hook installation skipped`,
+    };
+  }
+
+  const currentSettings = readJson(settingsPath, {});
+  const nextSettings = {
+    ...currentSettings,
+    hooks: {
+      ...(currentSettings.hooks && typeof currentSettings.hooks === "object" ? currentSettings.hooks : {}),
+    },
+  };
+  for (const [hookName, command] of Object.entries(commands)) {
+    const currentGroups = Array.isArray(nextSettings.hooks[hookName])
+      ? nextSettings.hooks[hookName].map((group) => ({
+          ...group,
+          hooks: Array.isArray(group.hooks) ? group.hooks.map((hook) => ({ ...hook })) : [],
+        }))
+      : [];
+    const nextGroups = currentGroups.map((group) => ({
+      ...group,
+      hooks: Array.isArray(group.hooks) ? group.hooks.filter((hook) => !hook?._vericify) : [],
+    }));
+    const targetIndex = nextGroups.findIndex((group) => String(group?.matcher ?? "") === "");
+    const targetGroup = targetIndex >= 0 ? nextGroups[targetIndex] : { matcher: "", hooks: [] };
+    targetGroup.hooks = Array.isArray(targetGroup.hooks) ? targetGroup.hooks : [];
+    targetGroup.hooks.push({
+      _vericify: true,
+      type: "command",
+      command,
+    });
+    if (targetIndex >= 0) {
+      nextGroups[targetIndex] = targetGroup;
+    } else {
+      nextGroups.push(targetGroup);
+    }
+    nextSettings.hooks[hookName] = nextGroups.filter((group) => Array.isArray(group.hooks) && group.hooks.length > 0);
+  }
+
+  const nextRaw = `${JSON.stringify(nextSettings, null, 2)}\n`;
+  const currentRaw = readText(settingsPath, "");
+  if (nextRaw !== currentRaw) {
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, nextRaw);
+    return { path: settingsPath, written: true, settings: nextSettings };
+  }
+  return { path: settingsPath, written: false, settings: nextSettings };
+}
+
+export function claudeCodeHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+
+  try {
+    const settingsResult = upsertClaudeSettings(workspaceRoot, {
+      PostToolUse: "vericify event --source-module claude-code --event-type TOOL_COMPLETED --status done",
+      Stop: "vericify event --source-module claude-code --event-type SESSION_STOPPED --status done",
+      PreCompact: VERICIFY_PRECOMPACT_COMMAND,
+    });
+    result.hooks_written = Boolean(settingsResult.written);
+    result.hooks_path = settingsResult.path;
+    if (settingsResult.skipped_reason) skippedReasons.push(settingsResult.skipped_reason);
+  } catch (error) {
+    skippedReasons.push(`Claude settings write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  try {
+    const instructionResult = upsertClaudeInstruction(workspaceRoot);
+    result.instruction_written = Boolean(instructionResult.written);
+    result.instruction_path = instructionResult.path;
+  } catch (error) {
+    skippedReasons.push(`CLAUDE.md write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "claude-code",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: result.hooks_written,
+    instructionWritten: result.instruction_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...eventResult.skipped_reasons],
+  };
+}
+
+export { claudeCodeHandshake as attachClaudeWorkspace };

package/src/adapters/handshake/codex.js

@@ -0,0 +1,75 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createHandshakeResult, emitHandshakeStartedEvent, mergeJsonFile, writeInstructionBlock } from "./common.js";
+
+const VERICIFY_MARKER = "<!-- vericify-instruction -->";
+
+function codexInstructionBlock() {
+  return `${VERICIFY_MARKER}
+## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id codex --kind blocker --summary "<what is blocking>"\`
+- **Handoff:** \`vericify post --run-id workspace:current --agent-id codex --kind handoff_note --summary "<handoff context>"\`
+- **Completion:** \`vericify post --run-id workspace:current --agent-id codex --kind completion --summary "<what changed>"\`
+- **Intentional silence:** \`vericify post --run-id workspace:current --agent-id codex --kind stale_ack --summary "<reason>"\`
+
+You may also write structured state directly to \`.codex/vericify-state.json\` using the passthrough schema (handoffs, nodes, entries, events, posts).
+<!-- /vericify-instruction -->`;
+}
+
+export function codexHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+  let instructionResult = { skipped: false, reason: "" };
+  const codexDir = resolve(workspaceRoot, ".codex");
+  const statePath = resolve(codexDir, "vericify-state.json");
+  const agentsPath = resolve(workspaceRoot, "AGENTS.md");
+
+  if (existsSync(codexDir)) {
+    try {
+      const mergeResult = mergeJsonFile(statePath, (existing) => ({
+        ...(existing && typeof existing === "object" ? existing : {}),
+        _vericify_passthrough: true,
+        handoffs: existing?.handoffs && typeof existing.handoffs === "object" ? existing.handoffs : {},
+        nodes: existing?.nodes && typeof existing.nodes === "object" ? existing.nodes : {},
+        entries: Array.isArray(existing?.entries) ? existing.entries : [],
+        events: Array.isArray(existing?.events) ? existing.events : [],
+        posts: Array.isArray(existing?.posts) ? existing.posts : [],
+      }));
+      result.passthrough_written = Boolean(mergeResult.written);
+      result.passthrough_path = statePath;
+    } catch (error) {
+      skippedReasons.push(`.codex/vericify-state.json write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    skippedReasons.push(".codex directory is missing; passthrough config skipped");
+  }
+
+  try {
+    instructionResult = writeInstructionBlock(agentsPath, VERICIFY_MARKER, codexInstructionBlock(), {
+      createIfAbsent: true,
+      createDirs: true,
+    });
+    result.instruction_written = Boolean(instructionResult.written);
+    result.instruction_path = agentsPath;
+    if (instructionResult.skipped) skippedReasons.push(instructionResult.reason);
+  } catch (error) {
+    skippedReasons.push(`AGENTS.md write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "codex",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: false,
+    instructionWritten: result.instruction_written,
+    passthroughWritten: result.passthrough_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...(instructionResult.skipped ? [instructionResult.reason] : []), ...eventResult.skipped_reasons].filter(Boolean),
+  };
+}

package/src/adapters/handshake/common.js

@@ -0,0 +1,130 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { readJson, readText } from "../../core/fs.js";
+import { isoNow } from "../../core/util.js";
+import { appendStatusEvent } from "../../store/status-events.js";
+
+export function createHandshakeResult() {
+  return {
+    hooks_written: false,
+    hooks_path: null,
+    mcp_written: false,
+    mcp_path: null,
+    instruction_written: false,
+    instruction_path: null,
+    passthrough_written: false,
+    passthrough_path: null,
+    event_emitted: false,
+    skipped_reasons: [],
+  };
+}
+
+function ensureParentDir(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+export function mergeJsonFile(filePath, mergeFn, { createIfAbsent = true } = {}) {
+  if (!existsSync(filePath) && !createIfAbsent) {
+    return {
+      written: false,
+      skipped: true,
+      reason: `${filePath} is missing; skipped.`,
+      value: null,
+    };
+  }
+
+  const currentRaw = readText(filePath, "");
+  const existing = currentRaw.trim() ? readJson(filePath, null) : null;
+  const next = mergeFn(existing);
+  const nextRaw = `${JSON.stringify(next, null, 2)}\n`;
+  if (nextRaw === currentRaw) {
+    return {
+      written: false,
+      skipped: false,
+      reason: "Already up to date.",
+      value: next,
+    };
+  }
+
+  ensureParentDir(filePath);
+  writeFileSync(filePath, nextRaw);
+  return {
+    written: true,
+    skipped: false,
+    reason: "",
+    value: next,
+  };
+}
+
+export function writeInstructionBlock(filePath, markerComment, block, { createIfAbsent = true, createDirs = true } = {}) {
+  const currentRaw = readText(filePath, "");
+  if (!currentRaw && !createIfAbsent) {
+    return {
+      written: false,
+      skipped: true,
+      reason: `${filePath} is missing; skipped.`,
+    };
+  }
+
+  if (currentRaw.includes(markerComment)) {
+    return {
+      written: false,
+      skipped: false,
+      reason: "Instruction block already present.",
+    };
+  }
+
+  if (createDirs) {
+    ensureParentDir(filePath);
+  }
+
+  const body = String(block ?? "").trimEnd();
+  const next = currentRaw.trimEnd()
+    ? `${currentRaw.trimEnd()}\n\n${body}\n`
+    : `${body}\n`;
+  if (next === currentRaw) {
+    return {
+      written: false,
+      skipped: false,
+      reason: "Already up to date.",
+    };
+  }
+
+  writeFileSync(filePath, next);
+  return {
+    written: true,
+    skipped: false,
+    reason: "",
+  };
+}
+
+export function emitHandshakeStartedEvent(workspaceRoot, { adapterId, sessionId, hooksWritten, instructionWritten, mcpWritten = false, passthroughWritten = false }) {
+  try {
+    appendStatusEvent(workspaceRoot, {
+      source_module: adapterId,
+      event_type: "SESSION_STARTED",
+      status: "started",
+      payload: {
+        summary: `${adapterId} adapter attached.`,
+        adapter_id: adapterId,
+        session_id: sessionId ?? null,
+        hooks_written: Boolean(hooksWritten),
+        instruction_written: Boolean(instructionWritten),
+        workspace_root: workspaceRoot,
+        mcp_written: Boolean(mcpWritten),
+        passthrough_written: Boolean(passthroughWritten),
+      },
+    });
+    return {
+      event_emitted: true,
+      skipped_reasons: [],
+      timestamp: isoNow(),
+    };
+  } catch (error) {
+    return {
+      event_emitted: false,
+      skipped_reasons: [`Failed to emit SESSION_STARTED: ${error instanceof Error ? error.message : String(error)}`],
+      timestamp: isoNow(),
+    };
+  }
+}