@cleocode/adapters 2026.4.101 → 2026.4.103

package/src/providers/opencode/install.ts

@@ -3,13 +3,19 @@
  *
  * Handles CLEO installation into OpenCode environments:
  * - Ensures AGENTS.md has CLEO @-references
+ * - Installs PreCompact hook shell shims + a JS plugin wrapper (T1013)
  *
  * @task T5240
+ * @task T1013
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import {
+  type InstallHookTemplatesResult,
+  installProviderHookTemplates,
+} from '../shared/hook-template-installer.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
 /**
@@ -27,11 +33,17 @@ const INSTRUCTION_REFERENCES = [
  *
  * Manages CLEO's integration with OpenCode by:
  * 1. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ * 2. Installing PreCompact hook shell templates + generating the JS plugin
+ *    wrapper that spawns the shim on `experimental.session.compacting` (T1013).
  *
  * @remarks
  * Installation is idempotent -- running install multiple times on the same
- * project produces the same result. Only AGENTS.md is managed; OpenCode's
- * plugin system is handled separately by the hook provider.
+ * project produces the same result. OpenCode's plugin system is the native
+ * hook surface (OpenCode has no config-file hook registry like Claude Code or
+ * Cursor), so the installer writes a JS plugin that subscribes to the native
+ * event and spawns the shell shim as a child process. This keeps the DRY
+ * contract: all providers funnel through the shared `cleo-precompact-core.sh`
+ * helper and end up in the `cleo` CLI.
  */
 export class OpenCodeInstallProvider implements AdapterInstallProvider {
   /**
@@ -52,6 +64,14 @@ export class OpenCodeInstallProvider implements AdapterInstallProvider {
       details.instructionFile = join(projectDir, 'AGENTS.md');
     }
 
+    // Step 2 (T1013): Install PreCompact hook templates + generate the JS
+    // plugin wrapper that spawns the bash shim on
+    // `experimental.session.compacting`.
+    const hookResult = this.installHookTemplates(projectDir);
+    if (hookResult) {
+      details.hookTemplates = hookResult;
+    }
+
     return {
       success: true,
       installedAt,
@@ -134,4 +154,115 @@ export class OpenCodeInstallProvider implements AdapterInstallProvider {
     writeFileSync(agentsMdPath, content, 'utf-8');
     return true;
   }
+
+  /**
+   * Install the CLEO PreCompact hook templates for OpenCode (T1013).
+   *
+   * OpenCode uses a JavaScript plugin system, not config-based hooks. The
+   * installer:
+   *
+   * 1. Writes the shared bash helper and OpenCode-flavoured `precompact.sh`
+   *    to `<projectDir>/.opencode/plugins/hooks/` so the shim can be spawned
+   *    as a child process.
+   * 2. Generates an OpenCode plugin `.opencode/plugins/cleo-precompact.js`
+   *    that subscribes to `experimental.session.compacting` (CAAMP native
+   *    event for the canonical `PreCompact`) and spawns the shim.
+   *
+   * Idempotent.
+   *
+   * @param projectDir - Project root directory.
+   * @returns Install summary, or `null` when no change was required.
+   *
+   * @task T1013
+   */
+  private installHookTemplates(projectDir: string): {
+    templates: InstallHookTemplatesResult;
+    pluginWritten: boolean;
+  } | null {
+    const pluginsDir = join(projectDir, '.opencode', 'plugins');
+    const hooksDir = join(pluginsDir, 'hooks');
+
+    // Template copy is best-effort so missing/locked filesystems (CI sandboxes,
+    // mocked `node:fs` in unit tests) don't fail the whole install.
+    let templates: InstallHookTemplatesResult;
+    try {
+      templates = installProviderHookTemplates({
+        provider: 'opencode',
+        targetDir: hooksDir,
+      });
+    } catch {
+      return null;
+    }
+
+    let pluginWritten = false;
+    try {
+      pluginWritten = this.writePrecompactPlugin(pluginsDir, join(hooksDir, 'precompact.sh'));
+    } catch {
+      // Best-effort: never block install on hook wiring failures.
+    }
+
+    if (templates.installedFiles.length === 0 && !pluginWritten) {
+      return null;
+    }
+
+    return { templates, pluginWritten };
+  }
+
+  /**
+   * Write an OpenCode JavaScript plugin that spawns `precompact.sh` when the
+   * canonical `PreCompact` event fires. OpenCode exposes the event natively as
+   * `experimental.session.compacting` (see CAAMP `hook-mappings.json`).
+   *
+   * The generated file is idempotent — overwritten only when its content
+   * differs from the target on disk. Uses `child_process.spawn` so the bash
+   * shim runs in a separate process and does not block the compaction path.
+   *
+   * @param pluginsDir - Absolute path to `.opencode/plugins/`.
+   * @param shimPath - Absolute path to the installed `precompact.sh`.
+   * @returns `true` when the plugin file was written, `false` when unchanged.
+   *
+   * @task T1013
+   */
+  private writePrecompactPlugin(pluginsDir: string, shimPath: string): boolean {
+    const pluginPath = join(pluginsDir, 'cleo-precompact.js');
+    const generated = [
+      '// CLEO PreCompact plugin for OpenCode (generated by @cleocode/adapters).',
+      '// Bridges the canonical CAAMP `PreCompact` event',
+      '// (`experimental.session.compacting`) to the shell shim at:',
+      `//   ${shimPath}`,
+      '// The shim invokes only the `cleo` CLI — no core internals.',
+      '',
+      "import { spawn } from 'node:child_process';",
+      '',
+      'export default function register(plugin) {',
+      "  plugin.on('experimental.session.compacting', () => {",
+      '    try {',
+      `      const child = spawn(${JSON.stringify(shimPath)}, [], {`,
+      '        detached: true,',
+      "        stdio: 'ignore',",
+      '      });',
+      '      child.unref();',
+      '    } catch (err) {',
+      '      // Hook errors must never block compaction.',
+      "      console.error('[CLEO] precompact hook failed:', err);",
+      '    }',
+      '  });',
+      '}',
+      '',
+    ].join('\n');
+
+    if (existsSync(pluginPath)) {
+      try {
+        if (readFileSync(pluginPath, 'utf-8') === generated) {
+          return false;
+        }
+      } catch {
+        // Fall through and overwrite.
+      }
+    }
+
+    mkdirSync(pluginsDir, { recursive: true });
+    writeFileSync(pluginPath, generated, 'utf-8');
+    return true;
+  }
 }

package/src/providers/opencode/templates/hooks/precompact.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# CLEO PreCompact Hook — OpenCode emergency safestop shim
+#
+# OpenCode is a plugin-based hook provider (.opencode/plugins/) whose canonical
+# event `PreCompact` maps to the native event `experimental.session.compacting`.
+# OpenCode's handler type is `plugin` (JavaScript) — this shell script is
+# invoked from the JS plugin wrapper as a child process.
+#
+# INSTALLATION (OpenCode):
+#   1. Copy this file to .opencode/plugins/hooks/precompact.sh (alongside
+#      cleo-precompact-core.sh).
+#   2. Register a JS plugin that spawns this shim on the canonical event.
+#      See packages/adapters/src/providers/opencode/install.ts for the
+#      generated wrapper that wires `experimental.session.compacting` to
+#      this script via `child_process.spawn`.
+#
+# The universal flush + safestop sequence lives in cleo-precompact-core.sh.
+# This shim only adds an OpenCode-flavoured banner.
+#
+# @task T1013
+# @provider opencode
+
+set -euo pipefail
+
+# Source the shared CLEO core helper. Installed alongside this shim.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../../shared/templates/hooks/cleo-precompact-core.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/cleo-precompact-core.sh"
+
+# Run the universal flush + safestop sequence.
+cleo_core_run_precompact "precompact-emergency"
+
+# OpenCode-specific status banner (only when a session was actually saved).
+if [[ -n "${CLEO_PRECOMPACT_HANDOFF:-}" ]]; then
+    echo ""
+    echo "[CLEO] Emergency Safestop executed at OpenCode experimental.session.compacting."
+    echo "       Session ended. Handoff saved to: ${CLEO_PRECOMPACT_HANDOFF}"
+    if [[ -n "${CLEO_PRECOMPACT_SESSION_ID:-}" ]]; then
+        echo "       Resume with: cleo session resume ${CLEO_PRECOMPACT_SESSION_ID}"
+    fi
+fi

package/src/providers/pi/templates/hooks/README.md

@@ -0,0 +1,40 @@
+# Pi Hook Templates — Not Shell
+
+Pi (CAAMP's primary harness, ADR-035) does **not** use shell hooks natively.
+Its hook system is TypeScript-based extensions loaded from:
+
+- Global: `~/.pi/agent/extensions/*.ts`
+- Project: `<projectDir>/.pi/extensions/*.ts`
+
+## How PreCompact fires on Pi
+
+Pi's native event catalog (`piEventCatalog` in
+`packages/caamp/providers/hook-mappings.json`) maps the canonical
+`PreCompact` CAAMP event to the native `context` event (Pi's context-assembly
+lifecycle stage is the closest proxy for pre-compaction).
+
+## Why there is no bash shim here
+
+The `packages/adapters/src/providers/{claude-code,cursor,opencode,gemini-cli}/templates/hooks/`
+directories ship bash templates because those providers expose `command`-type
+handlers. Pi exposes only `extension` handlers, so its pre-compact hook is a
+TypeScript module, not a shell script.
+
+## Where the Pi implementation lives
+
+The Pi PreCompact handler is implemented in TypeScript inside CLEO core and is
+loaded into the Pi extension runtime via `packages/core/src/hooks/handlers/precompact.ts`.
+That handler invokes the same universal sequence as the bash helpers:
+
+1. `cleo memory precompact-flush` — drain in-flight observations + WAL checkpoint (T1004)
+2. `cleo safestop --reason precompact-emergency --commit --handoff <file>`
+
+Both execution paths terminate in the same CLI, so the universal CLEO
+surface remains the single source of truth. Provider adapters never reach
+into core internals.
+
+## See also
+
+- `packages/adapters/src/providers/README.md` — Hook Template Architecture
+- `packages/adapters/src/providers/pi/hooks.ts` — `PiHookProvider.mapProviderEvent`
+- `packages/caamp/providers/hook-mappings.json` — canonical event → provider map

package/src/providers/shared/hook-template-installer.ts

@@ -0,0 +1,268 @@
+/**
+ * Shared hook-template installer for provider adapters.
+ *
+ * Each provider ships its own PreCompact shell shim under
+ * `packages/adapters/src/providers/<provider>/templates/hooks/` which sources
+ * the universal helper at
+ * `packages/adapters/src/providers/shared/templates/hooks/cleo-precompact-core.sh`.
+ *
+ * This module wires the templates into the provider's hooks directory at
+ * install time. Provider-specific {@link AdapterInstallProvider} implementations
+ * call {@link installProviderHookTemplates} with their own provider id, and the
+ * installer consults CAAMP's `hook-mappings.json` SSoT to verify the provider
+ * supports the required canonical event and handler type before writing.
+ *
+ * DRY invariant: all shims source the same core helper — adapter-specific
+ * shims only add provider-flavoured banners and `$CLEO_PRECOMPACT_*` env
+ * handling.
+ *
+ * @task T1013
+ * @epic T1000
+ */
+
+import { copyFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Identifiers for providers that ship bash hook templates. */
+export type HookTemplateProviderId = 'claude-code' | 'cursor' | 'opencode' | 'gemini-cli';
+
+/**
+ * Result returned by {@link installProviderHookTemplates}.
+ *
+ * @remarks
+ * Paths are absolute and point at the filesystem locations the installer
+ * actually wrote to. When no template files needed copying (e.g. because the
+ * destination already contained identical files), `installedFiles` is empty
+ * and `skipped` carries the reason-keyed paths instead.
+ */
+export interface InstallHookTemplatesResult {
+  /** Provider identifier the templates were installed for. */
+  provider: HookTemplateProviderId;
+  /** Absolute path to the hooks directory that received the templates. */
+  targetDir: string;
+  /** Absolute paths to files written during this install invocation. */
+  installedFiles: string[];
+  /** Files that were not written (already present and identical). */
+  skipped: string[];
+}
+
+/**
+ * Options for {@link installProviderHookTemplates}.
+ */
+export interface InstallHookTemplatesOptions {
+  /** Provider to install hook templates for. */
+  provider: HookTemplateProviderId;
+  /** Absolute path to the hooks directory that should receive the shims. */
+  targetDir: string;
+  /**
+   * When `true`, overwrite existing files even if their contents match.
+   *
+   * @defaultValue `false`
+   */
+  force?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Template file resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the `providers/` base directory relative to this source file.
+ *
+ * Template shell scripts live alongside TypeScript source at
+ * `src/providers/<provider>/templates/hooks/`. The TypeScript compiler
+ * emits `.d.ts` / `.js` artefacts into `dist/providers/...` without copying
+ * non-TS assets. To support both development (running from `src/`) and
+ * published installs (running from `dist/`), this resolver returns a list of
+ * candidate provider directories — one for the current runtime location and
+ * one for the parallel `src/providers/` tree. Template lookup callers must
+ * pick the first candidate that contains the expected file.
+ *
+ * @internal
+ */
+function resolveProviderCandidates(): string[] {
+  // One level up from shared/ = providers/. This is the compiled location
+  // when running from `dist/providers/shared/hook-template-installer.js` or
+  // the source location in development.
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const here = dirname(thisDir);
+
+  // Also look in the sibling `src/providers/` tree so compiled runs can still
+  // find template assets that tsc didn't copy. `dist/providers/shared/...`
+  // → `../../src/providers/`.
+  const fromDist = join(here, '..', '..', 'src', 'providers');
+
+  return [here, fromDist];
+}
+
+/**
+ * Find a template file by searching the provider-directory candidates.
+ *
+ * @internal
+ */
+function findTemplateFile(relativeSegments: string[]): string {
+  for (const base of resolveProviderCandidates()) {
+    const candidate = join(base, ...relativeSegments);
+    if (existsSync(candidate)) return candidate;
+  }
+  // Surface a precise error pointing to the first candidate so install
+  // failures are self-describing.
+  const [first] = resolveProviderCandidates();
+  return join(first ?? '', ...relativeSegments);
+}
+
+/**
+ * Per-provider shim filename (relative to `<provider>/templates/hooks/`).
+ * Shell scripts named per the provider's canonical hook event convention.
+ *
+ * @internal
+ */
+const PROVIDER_SHIM: Record<HookTemplateProviderId, string> = {
+  'claude-code': 'precompact-safestop.sh',
+  cursor: 'precompact.sh',
+  opencode: 'precompact.sh',
+  'gemini-cli': 'precompact.sh',
+};
+
+/** Filename of the shared universal helper. */
+const SHARED_CORE_FILE = 'cleo-precompact-core.sh';
+
+/**
+ * Resolve the absolute source path of a provider's shim script.
+ *
+ * @internal
+ */
+function providerShimSource(provider: HookTemplateProviderId): string {
+  return findTemplateFile([provider, 'templates', 'hooks', PROVIDER_SHIM[provider]]);
+}
+
+/**
+ * Resolve the absolute source path of the shared `cleo-precompact-core.sh`
+ * helper.
+ *
+ * @internal
+ */
+function sharedCoreSource(): string {
+  return findTemplateFile(['shared', 'templates', 'hooks', SHARED_CORE_FILE]);
+}
+
+// ---------------------------------------------------------------------------
+// Copy helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy a single template file, preserving the executable bit. Returns the
+ * destination path on successful write, or `null` when the destination
+ * already matches the source (idempotent no-op).
+ *
+ * @internal
+ */
+function copyTemplate(src: string, dest: string, force: boolean): { wrote: boolean } {
+  if (!existsSync(src)) {
+    throw new Error(`CLEO hook template missing at source: ${src}`);
+  }
+  if (!force && existsSync(dest)) {
+    const srcStat = statSync(src);
+    const destStat = statSync(dest);
+    if (srcStat.size === destStat.size && srcStat.mtimeMs <= destStat.mtimeMs) {
+      return { wrote: false };
+    }
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  return { wrote: true };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Install the CLEO PreCompact hook templates for a provider.
+ *
+ * Writes two files into `targetDir`:
+ *
+ * 1. `cleo-precompact-core.sh` — universal helper (shared across all providers)
+ * 2. `<provider-shim>.sh` — provider-flavoured shim that sources the helper
+ *
+ * The shim invokes only the universal CLEO CLI (`cleo memory precompact-flush`
+ * and `cleo safestop …`) — adapters never reach into core internals.
+ *
+ * @param options - Installation target and provider id.
+ * @returns Paths written, paths skipped, and the resolved target directory.
+ *
+ * @example
+ * ```typescript
+ * import { homedir } from 'node:os';
+ * import { join } from 'node:path';
+ * import { installProviderHookTemplates } from '@cleocode/adapters';
+ *
+ * const result = installProviderHookTemplates({
+ *   provider: 'claude-code',
+ *   targetDir: join(homedir(), '.claude', 'hooks'),
+ * });
+ * // result.installedFiles includes both scripts on first run.
+ * ```
+ *
+ * @task T1013
+ * @public
+ */
+export function installProviderHookTemplates(
+  options: InstallHookTemplatesOptions,
+): InstallHookTemplatesResult {
+  const { provider, targetDir, force = false } = options;
+  const result: InstallHookTemplatesResult = {
+    provider,
+    targetDir,
+    installedFiles: [],
+    skipped: [],
+  };
+
+  mkdirSync(targetDir, { recursive: true });
+
+  // 1. Shared universal helper
+  const coreDest = join(targetDir, SHARED_CORE_FILE);
+  const coreOutcome = copyTemplate(sharedCoreSource(), coreDest, force);
+  if (coreOutcome.wrote) result.installedFiles.push(coreDest);
+  else result.skipped.push(coreDest);
+
+  // 2. Provider-specific shim
+  const shimName = PROVIDER_SHIM[provider];
+  const shimDest = join(targetDir, shimName);
+  const shimOutcome = copyTemplate(providerShimSource(provider), shimDest, force);
+  if (shimOutcome.wrote) result.installedFiles.push(shimDest);
+  else result.skipped.push(shimDest);
+
+  return result;
+}
+
+/**
+ * Resolve the source-side path of a provider's hook template for inspection
+ * and testing. Returns the absolute path where the installer will read from.
+ *
+ * @param provider - Provider identifier.
+ * @returns Absolute path to the provider's shim template file.
+ *
+ * @task T1013
+ * @public
+ */
+export function getProviderHookTemplatePath(provider: HookTemplateProviderId): string {
+  return providerShimSource(provider);
+}
+
+/**
+ * Resolve the source-side path of the shared universal helper.
+ *
+ * @returns Absolute path to `cleo-precompact-core.sh` in the adapter package.
+ *
+ * @task T1013
+ * @public
+ */
+export function getSharedHookCorePath(): string {
+  return sharedCoreSource();
+}

package/src/providers/shared/templates/hooks/cleo-precompact-core.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# CLEO PreCompact Core — Shared universal logic (provider-neutral)
+#
+# This helper performs the provider-agnostic work for a pre-compact hook:
+#   1. Locate the CLEO project directory (walks up from $PWD looking for .cleo/)
+#   2. Resolve the `cleo` CLI binary
+#   3. Invoke `cleo memory precompact-flush` to drain pending observations + checkpoint WAL
+#   4. Invoke `cleo safestop --reason precompact-emergency --commit --handoff <file>`
+#   5. Emit a human-readable summary to stderr
+#
+# This script is intentionally INVOKED via the CLEO CLI only — it never
+# reaches into core internals. Provider-specific hook shims (Claude Code's
+# `precompact-safestop.sh`, Cursor's `precompact.sh`, etc.) source this file
+# and then perform any provider-specific banner/exit handling.
+#
+# INSTALLATION:
+#   Provider-specific installers copy this file alongside the provider shim
+#   to the target hooks directory. See:
+#     - packages/adapters/src/providers/claude-code/templates/hooks/
+#     - packages/adapters/src/providers/cursor/templates/hooks/
+#     - packages/adapters/src/providers/opencode/templates/hooks/
+#
+# Exit code: always 0 (hook must never block the provider's compaction path).
+#
+# Environment overrides:
+#   CLEO_PROJECT_DIR  — absolute path to .cleo/ (skips upward search)
+#   CLEO_HOME         — CLEO install root (controls default cleo binary lookup)
+#
+# @task T1013
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# 1. Locate the CLEO project directory
+# ---------------------------------------------------------------------------
+cleo_core_find_dir() {
+    local dir="$PWD"
+    while [[ "$dir" != "/" ]]; do
+        if [[ -d "$dir/.cleo" ]]; then
+            echo "$dir/.cleo"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    echo ""
+}
+
+# ---------------------------------------------------------------------------
+# 2. Resolve the cleo CLI binary
+# ---------------------------------------------------------------------------
+cleo_core_find_cli() {
+    local candidate="${CLEO_HOME:-$HOME/.cleo}/bin/cleo"
+    if [[ -x "$candidate" ]]; then
+        echo "$candidate"
+        return 0
+    fi
+    command -v cleo 2>/dev/null || echo ""
+}
+
+# ---------------------------------------------------------------------------
+# 3. Append a timestamped log line to ${CLEO_DIR}/safestop.log (best-effort)
+# ---------------------------------------------------------------------------
+cleo_core_log() {
+    local message="$1"
+    local log_file="$2"
+    local timestamp
+    timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    echo "[$timestamp] $message" >> "$log_file" 2>/dev/null || true
+    echo "[CLEO] $message" >&2
+}
+
+# ---------------------------------------------------------------------------
+# 4. Main entrypoint — runs the flush + safestop sequence
+#
+# Usage: cleo_core_run_precompact "<reason>"
+#        Emits a `$CLEO_PRECOMPACT_HANDOFF` env var in the caller's shell
+#        pointing at the handoff JSON file (empty string if not produced).
+# ---------------------------------------------------------------------------
+cleo_core_run_precompact() {
+    local reason="${1:-precompact-emergency}"
+    local cleo_dir="${CLEO_PROJECT_DIR:-$(cleo_core_find_dir)}"
+    local session_file="${cleo_dir:-.cleo}/.current-session"
+    local log_file="${cleo_dir:-.cleo}/safestop.log"
+
+    CLEO_PRECOMPACT_HANDOFF=""
+    CLEO_PRECOMPACT_SESSION_ID=""
+
+    if [[ -z "$cleo_dir" ]] || [[ ! -f "$session_file" ]]; then
+        # No CLEO project here — silent no-op so we never interfere with the host.
+        if [[ -n "$cleo_dir" ]]; then
+            cleo_core_log "PreCompact triggered but no active CLEO session" "$log_file"
+        fi
+        return 0
+    fi
+
+    local session_id
+    session_id=$(cat "$session_file" 2>/dev/null || echo "")
+    if [[ -z "$session_id" ]]; then
+        cleo_core_log "PreCompact triggered but session file empty" "$log_file"
+        return 0
+    fi
+
+    CLEO_PRECOMPACT_SESSION_ID="$session_id"
+    cleo_core_log "PreCompact triggered — initiating emergency safestop (reason=$reason)" "$log_file"
+
+    local cleo_cmd
+    cleo_cmd=$(cleo_core_find_cli)
+    if [[ -z "$cleo_cmd" ]] || [[ ! -x "$cleo_cmd" ]]; then
+        cleo_core_log "ERROR: cleo command not found — cannot perform safestop" "$log_file"
+        return 0
+    fi
+
+    # Step 1 — flush in-flight observations + checkpoint WAL before the compaction boundary.
+    # Invokes: cleo memory precompact-flush (T1004).
+    "$cleo_cmd" memory precompact-flush 2>&1 | tee -a "$log_file" || true
+
+    # Step 2 — run safestop with the emergency reason.
+    local handoff_file="${cleo_dir}/handoff-emergency-$(date +%s).json"
+    "$cleo_cmd" safestop \
+        --reason "$reason" \
+        --commit \
+        --handoff "$handoff_file" \
+        2>&1 | tee -a "$log_file" || true
+
+    cleo_core_log "Emergency safestop completed. Handoff: $handoff_file" "$log_file"
+    CLEO_PRECOMPACT_HANDOFF="$handoff_file"
+    return 0
+}