Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
12.7 KB
Raw Blame
/**
 * Ctrl-C reaches the operations that can hear it (nothing-runs-unwatched, U3).
 *
 * The cooperative-cancellation contract was already written and never
 * connected. `createSafeguard` accepts a `signal`, checks it in priority
 * over the deadline, and throws `SafeguardAbortError` - a class kept
 * deliberately distinct from `SafeguardTimeoutError` so, in its own
 * words, "the watch shutdown coordinator can treat an intentional abort
 * as a clean stop rather than a failure". Not one production call site
 * passed a signal, so that class was unreachable and every long verb had
 * exactly one way to stop: the deadline, or SIGKILL.
 *
 * This module is the missing half, and it is deliberately smaller than
 * the half that was first written here.
 *
 * ## Why four of the six operations get no handle at all
 *
 * A Node/Bun signal handler is a JavaScript callback dispatched from the
 * event loop. `dreamRun`, `detectCommunitiesRun`, `discoverBridgesRun`
 * and `generateRun` are declared `function`, not `async`, and contain no
 * `await`: from the moment the pass starts until the moment it returns,
 * the process never re-enters the event loop, so the handler cannot run.
 * Measured against these exact modules - a real SIGINT delivered 0.3 s
 * into a synchronous `checkpoint()` loop - 27,356,853 checkpoints ran
 * with the signal pending, `SafeguardAbortError` was never thrown, and
 * `received()` was still `null` when the loop ended. One turn of the
 * event loop later it was `"SIGINT"`. The signal was never lost; it was
 * unobservable for the entire duration of the work.
 *
 * `safeguard.ts` already states the general form of this - "a JavaScript
 * timer cannot interrupt a fully-synchronous CPU hang on a single
 * thread" - and frames it as the pathological case. For these four it is
 * the NORMAL case: they are synchronous end to end, so the whole pass is
 * a region no cooperative signal can enter.
 *
 * Making them `async` does not fix it and would hide it. An `await` on a
 * resolved promise is a MICROtask, and microtasks drain without ever
 * yielding to libuv: 4,810,652 `await Promise.resolve()` iterations with
 * a SIGINT pending, and `received()` still `null`. Only a macrotask yield
 * (`setImmediate`) lets the handler run, at ~184 k yields/s against
 * ~13.7 M synchronous checkpoints/s. An async rewrite would therefore
 * have to insert a purpose-built macrotask yield at every checkpoint
 * across 137 call sites - and if any one of them used a plain `await`, it
 * would reproduce this exact false claim invisibly.
 *
 * So the honest answer is not to make the handler work where it cannot.
 * It is to install it only where the operation actually yields, and to
 * leave the default disposition in place everywhere else - where the
 * keystroke keeps doing what it did before this branch existed: killing
 * the process at once. Those four write atomically (`atomicWriteFileSync`
 * in dream, plan-then-write under one lock in architect), so a pass
 * killed mid-way leaves no half-written artifact.
 *
 * ## Why an unobserved signal still ends the run
 *
 * Registering a listener suppresses the default terminate for as long as
 * it is registered, and every verb holds the handle across work that
 * never consults the signal: `Store.open`, a proposal write, a report
 * render, the reindex swap. A Ctrl-C landing there aborted a controller
 * nobody read, and the verb returned 0 - a success code for a run the
 * operator stopped. So {@link InterruptHandle.release} reconciles: a
 * signal that arrived and was never acknowledged is re-raised, which ends
 * the process the way the keystroke would have. Suppressing the default
 * is a loan against the operation acting on it, and `release` is where
 * the loan is called in.
 *
 * `process.once` rather than `process.on`, following the one working
 * teardown in the repository, `IndexWatchRunner`'s: a SECOND interrupt is
 * not intercepted and falls through to the default handler that
 * force-kills.
 *
 * The exit code is the shell's own convention rather than a new project
 * vocabulary: 128 plus the signal number. It matters that it is not 0.
 * `o2b search watch` exits 0 when interrupted because stopping IS how
 * that command ends; a consolidation pass interrupted half-way did not
 * do what it was asked, and reporting that as success is exactly the
 * misleading quiet this release removes.
 */

import { OPERATION, type Operation } from "../core/brain/safeguard.ts";

import { okJson } from "./output.ts";

const SIGINT_EXIT = 130;
const SIGTERM_EXIT = 143;

/**
 * Exit code for a run the operator stopped with Ctrl-C. 128 + SIGINT(2).
 */
export const EXIT_INTERRUPTED = SIGINT_EXIT;

/** Exit code for a run stopped by SIGTERM. 128 + SIGTERM(15). */
export const EXIT_TERMINATED = SIGTERM_EXIT;

/** The signals a long foreground verb listens for. */
const HANDLED_SIGNALS = Object.freeze(["SIGINT", "SIGTERM"] as const);

type HandledSignal = (typeof HANDLED_SIGNALS)[number];

const EXIT_FOR_SIGNAL: Readonly<Record<HandledSignal, number>> = Object.freeze({
  SIGINT: EXIT_INTERRUPTED,
  SIGTERM: EXIT_TERMINATED,
});

/**
 * Whether each long operation yields to the event loop while it runs.
 *
 * One table rather than a convention followed six times, for the reason
 * `progressReasonForError` lives in the spine: the fact that decides
 * whether a handle may be opened is the fact a reader needs, and six
 * copies of it are six chances for the seventh verb to guess. A new
 * member of `OPERATION` cannot compile without answering here, which is
 * the point - the question is easy to answer and impossible to ask
 * yourself unprompted.
 *
 * `reindex` awaits real I/O between files and between embed batches, and
 * checks `throwIfAborted` at both boundaries. The maintenance lane awaits
 * between its four tasks, so a signal delivered during one task is seen
 * before the next one starts - which is also why the lane's own
 * sub-passes are listed `false` here and cancelled through the lane
 * rather than on their own.
 */
const YIELDS_TO_EVENT_LOOP: Readonly<Record<Operation, boolean>> = Object.freeze({
  [OPERATION.dream]: false,
  [OPERATION.bridges]: false,
  [OPERATION.clusters]: false,
  [OPERATION.architect]: false,
  [OPERATION.relink]: false,
  [OPERATION.reindex]: true,
  [OPERATION.maintenance]: true,
  // The session sweep is synchronous end to end: the walk and the hash
  // pass are both sync fs calls, so a signal handler cannot run while it
  // does. Leaving SIGINT alone keeps the keystroke lethal, which is the
  // only way this pass can actually be stopped.
  [OPERATION.sessions]: false,
});

/**
 * Whether a cooperative interrupt can reach `operation` at all.
 *
 * The predicate a verb consults before it decides to advertise Ctrl-C,
 * and the predicate `docs/cli-reference.md` is written from.
 */
export function interruptIsObservable(operation: Operation): boolean {
  return YIELDS_TO_EVENT_LOOP[operation];
}

export interface InterruptHandle {
  /** Hand this to `createSafeguard`; the next checkpoint throws when set. */
  readonly signal: AbortSignal;
  /** Which signal arrived, or `null` while none has. */
  readonly received: () => HandledSignal | null;
  /**
   * The exit code for the signal that arrived, or {@link EXIT_INTERRUPTED}
   * when a stop is reported without one - an abort raised by a caller
   * rather than by a key press.
   */
  readonly exitCode: () => number;
  /**
   * Declare that the run has acted on the interrupt: it stopped at a
   * checkpoint and the verb is about to return {@link exitCode}. Called
   * for you by {@link reportInterrupted}; a verb that reports a stop its
   * own way - the maintenance lane does, from its journal - calls it
   * directly.
   *
   * Without it {@link release} cannot tell a stop that was honoured from
   * a signal that was swallowed, and it must assume the latter, because
   * assuming the former is how a stopped run exits 0.
   */
  readonly acknowledge: () => void;
  /**
   * Stop listening, and settle an interrupt nobody acted on.
   *
   * MUST be called in a `finally`: the listeners are process-global, and
   * a verb that returns without releasing leaves a dead controller wired
   * to the next signal. When a signal arrived and {@link acknowledge} was
   * never called, this does not return - it re-raises, ending the process
   * as the un-suppressed keystroke would have.
   */
  readonly release: () => void;
}

/** Thrown when a handle is asked for on behalf of an operation that cannot see it. */
export class UnobservableInterruptError extends Error {
  readonly operation: Operation;

  constructor(operation: Operation) {
    super(
      `${operation} runs to completion without yielding to the event loop, so a ` +
        "signal handler cannot run while it does. Opening a handle would only " +
        "suppress the default terminate and swallow the operator's Ctrl-C; leave " +
        "the signal alone so the keystroke still stops the process.",
    );
    this.name = "UnobservableInterruptError";
    this.operation = operation;
  }
}

/**
 * Listen for an interrupt for the duration of one `operation`.
 *
 * Throws {@link UnobservableInterruptError} for an operation that cannot
 * observe one. A handle that installed nothing would be worse than the
 * throw: the call site would read as cancelled-on-request and behave as
 * uncancellable, which is the state this module was written to end.
 *
 * Concurrent handles are not supported and are not defended against. Node
 * dispatches a signal to EVERY registered listener, so two overlapping
 * handles both abort - the hazard is not a missed abort but a `release`
 * on one handle re-raising a signal the other already acted on. Long
 * verbs are one-per-process here; `cmdBrainDream` opens its staged handle
 * and the inline one sequentially, never at once.
 */
export function onInterrupt(operation: Operation): InterruptHandle {
  if (!interruptIsObservable(operation)) throw new UnobservableInterruptError(operation);

  const controller = new AbortController();
  let received: HandledSignal | null = null;
  let acknowledged = false;
  let released = false;
  const listeners = new Map<HandledSignal, () => void>();

  for (const name of HANDLED_SIGNALS) {
    const listener = (): void => {
      received = name;
      controller.abort();
    };
    listeners.set(name, listener);
    process.once(name, listener);
  }

  return Object.freeze({
    signal: controller.signal,
    received: () => received,
    exitCode: () => (received === null ? EXIT_INTERRUPTED : EXIT_FOR_SIGNAL[received]),
    acknowledge: () => {
      acknowledged = true;
    },
    release: () => {
      if (released) return;
      released = true;
      for (const [name, listener] of listeners) process.removeListener(name, listener);
      listeners.clear();
      if (received === null || acknowledged) return;
      const signal = received;
      process.stderr.write(
        `interrupted: ${signal} arrived while ${operation} was in a region that does not ` +
          "check for it, so the run could not stop at a boundary; stopping now\n",
      );
      // Our listeners are gone, so with nothing else holding this signal
      // the default disposition is back and this call does not return.
      process.kill(process.pid, signal);
      // Reached only when another subsystem in this process still holds a
      // listener for the signal and absorbed the re-raise. The run must
      // still not report success, so it ends here by exit code instead.
      process.exit(EXIT_FOR_SIGNAL[signal]);
    },
  });
}

/**
 * Report a run the operator stopped, and give back its exit code.
 *
 * The long verbs that reach this arm all say the same two things: the
 * stop is not a crash, and it is not a success. Written once here rather
 * than retyped per verb, for the reason `progressReasonForError` lives in
 * the spine rather than at each of the operations - copies of one fact
 * are chances for one of them to report a deliberate stop as a failure,
 * which is the distinction `SafeguardAbortError` exists to keep.
 *
 * Acknowledging is part of reporting, not a second step a caller could
 * forget: a stop that has been reported has been acted on, and `release`
 * must not then re-raise it.
 *
 * A `--json` caller gets the refusal as a document because its stdout is a
 * payload it parses; a human gets the line on stderr, where the verb's
 * other diagnostics already are. The two are exclusive: a JSON run that
 * also wrote the prose line would put the same fact on two streams, and a
 * human run has no document to put it in.
 */
export function reportInterrupted(handle: InterruptHandle, error: Error, asJson: boolean): number {
  handle.acknowledge();
  if (asJson) okJson({ ok: false, interrupted: true, message: error.message });
  else process.stderr.write(`${error.message}\n`);
  return handle.exitCode();
}