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
30.1 KB
Raw Blame
/**
 * `brain_feedback` (task 3.19): the preference- and signal-feedback
 * capture lane, with the forced-confirmation gate, the write-refusal
 * mapping and the slug derivation it answers through. Split from
 * `feedback-tools.ts`; registration happens through that module's
 * registry, which preserves the public FEEDBACK_TOOLS surface.
 */

import { resolve } from "node:path";
import { loadPermissionsDocumentFor } from "../../core/brain/permissions/document-source.ts";
import { resolveAgentName } from "../../core/config.ts";
import { resolveEffectiveScope, signalRecordExists, writeSignal } from "../../core/brain/signal.ts";
import { computePayloadHash, lookupKey, rememberKey } from "../../core/brain/idempotency-ledger.ts";
import { preferencePathOf } from "../../core/brain/paths.ts";
import { ROUTE_STAGE, timeStageSync } from "../../core/route-scope.ts";
import {
  adviseIncomingFeedback,
  adviseUnroutableCapture,
  captureRoutingHintField,
  type CaptureRoutingHint,
  type WriteConflictAdvisory,
} from "../../core/brain/write-advisory.ts";
import { loadFeedbackDefaultScopeSafe } from "../../core/brain/policy.ts";
import {
  loadPreference,
  preferencePresence,
  writePreference,
} from "../../core/brain/preference.ts";
import { sha256Hex } from "../../core/integrity/digest.ts";
import { normalizeExpirationDate } from "../../core/brain/expiration.ts";
import { validateBrainFeedbackInput } from "../../core/brain/sessions/validate-feedback.ts";
import { isoDate, isoSecond } from "../../core/brain/time.ts";
import { slugify } from "../../core/vault.ts";
import { normalizeAgentArgument } from "../../core/agent-identity.ts";
import {
  BRAIN_LOG_EVENT_KIND,
  BRAIN_PREFERENCE_STATUS,
  type BrainSignalSign,
} from "../../core/brain/types.ts";
import { appendLogEvent } from "../../core/brain/log.ts";
import {
  mirrorReportFields,
  mirrorSignal,
  resolveSharedNamespace,
} from "../../core/brain/shared-namespace.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import {
  PENDING_STAGED_DIAGNOSTIC_CODE,
  WRITE_REFUSAL_CODES,
  WriteRefusedError,
} from "../../core/brain/pending/pending-lanes.ts";
import { nextCommandField, requireNextStep } from "../../core/brain/next-step.ts";
import { resolvePermission } from "../../core/brain/permissions/resolve.ts";
import { substrateSubject } from "../../core/brain/write-disposition.ts";
import { contextVault, type ServerContext } from "../tool-contract.ts";
import { refuseAgentClaim } from "./agent-claim.ts";
import { coerceStr, coerceIsoDate } from "../coerce.ts";
import { toolPath } from "./device-path.ts";
import { readableAtContextReachOrUndefined } from "./reach-readable.ts";

export const FORCE_CONFIRMED_EXIT = requireNextStep(
  WRITE_REFUSAL_CODES.forceConfirmedRequiresAllow,
).nextCommand;

/**
 * The MCP mapping of a document-deny refusal (write-side trust, Task
 * 12): named code, the rule that decided, the principal it named, and
 * the operator exit - the write never landed, so the refusal is the
 * whole answer. Shared by the writers on this surface that let the
 * disposition layer refuse through a typed error.
 */
export function writeRefusedToMcp(tool: string, err: WriteRefusedError): MCPError {
  return new MCPError(INVALID_PARAMS, `${tool}: ${err.message}`, {
    code: err.code,
    rule: err.rule,
    agent: err.agent,
    next_command: err.nextCommand,
  });
}

/**
 * Build the slug used in the signal / preference filename. We never let
 * the agent decide the slug directly — taking `topic` as the slug stem
 * is what the design doc §9.2 prescribes (slugs are deterministic from
 * topic). The slug is run through `slugify` defensively so a slightly
 * mis-shaped topic still yields a filesystem-safe basename.
 */
export function deriveSlug(topic: string): string {
  return slugify(topic);
}

/** How a result names a record written with no vault. */
export const STORE_RECORD_PREFIX = "store:";

/**
 * The ledger namespace of the force-confirmed capture markers. A marker
 * lives outside the shared key space so a client key reused across tools
 * never collides with one.
 */
export const PREFERENCE_MARKER_NAMESPACE = "brain-feedback-preference";

/**
 * Ledger keys of the force-confirmed capture marker: the PENDING marker
 * is appended right before the confirmed preference write is attempted,
 * the DONE marker right after it succeeded. The append-only ledger cannot
 * update a receipt, so completion is a second receipt, and "unfinished"
 * is positive evidence: PENDING present, DONE absent. Both carry the same
 * capture hash, so a retry whose force flag or expiration differs from
 * the original call never resumes the original's capture.
 *
 * Both keys are derived from a fixed-length digest of the client key,
 * never from the key itself: the ledger accepts keys up to 256
 * characters, and appending a suffix to a near-limit key would push the
 * marker past that limit - the PENDING/DONE appends would fail soft, but
 * every later `lookupKey` on the retry path would throw and turn the
 * documented deduped replay of a successful capture into an error. A
 * digest keeps every valid client key usable.
 *
 * Both keys hash the TRIMMED key: the receipt the ledger keeps for the
 * client key is normalised the same way (trimmed), so a retry that
 * spells the key with different surrounding whitespace dedupes the
 * original signal and must find its PENDING/DONE markers too - hashing
 * the untrimmed key would strand the marker behind a marker no retry
 * key can ever match.
 */
const preferenceMarkerKey = (idempotencyKey: string): string =>
  `pref-capture:${sha256Hex(idempotencyKey.trim())}`;
const preferenceDoneKey = (idempotencyKey: string): string =>
  `pref-capture-done:${sha256Hex(idempotencyKey.trim())}`;

/**
 * The payload identity of the force-confirmed preference write, hashed
 * into the marker pair: WHAT is captured (topic, principle, agent,
 * scope), THAT it is force-confirmed, and HOW LONG it lives. Two calls
 * that differ in any of these are different payloads, so a forced retry
 * of an unforced capture (no marker exists) and a forced retry with a
 * different expiration (marker hash differs) both stay true no-ops.
 * Old receipts stay readable: the marker namespace is new, so receipts
 * written before it existed simply never resume.
 */
function preferenceCaptureHash(input: {
  topic: string;
  principle: string;
  agent: string;
  scope: string | undefined;
  expires: string | undefined;
}): string {
  return computePayloadHash({
    force_confirmed: true,
    topic: input.topic,
    principle: input.principle,
    agent: input.agent,
    scope: input.scope ?? undefined,
    expiration_date: input.expires ?? undefined,
  });
}

/** Append one capture-marker receipt, failing soft: the marker is a
 * repair aid, so an unreadable key or a full disk must never break the
 * capture it guards (the same policy the log appends follow). */
function appendMarkerReceipt(
  vault: string | null,
  key: string,
  captureHash: string,
  createdAt: string,
): void {
  try {
    rememberKey(vault, {
      key,
      namespace: PREFERENCE_MARKER_NAMESPACE,
      contentHash: captureHash,
      createdAt,
    });
  } catch (err) {
    process.stderr.write(
      `warning: record feedback capture marker failed: ${(err as Error).message}\n`,
    );
  }
}

export async function toolBrainFeedback(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  // `null` on a server with no vault: the writes are store records (D14).
  const vault = contextVault(ctx);
  // Single source of truth for the brain_feedback payload contract —
  // session-replay (sessions/import.ts) and the MCP live path now go
  // through the same validator so rule shape cannot drift between the
  // two surfaces.
  const validated = validateBrainFeedbackInput(args);
  if (!validated.ok) {
    throw new MCPError(INVALID_PARAMS, validated.reason);
  }
  const {
    topic,
    signal: signalRaw,
    principle,
    scope,
    raw,
    source,
    force_confirmed,
  } = validated.value;
  const forceConfirmed = force_confirmed ?? false;

  // Identity, resolved once (write-side trust, Task 7). The
  // transport-minted identity WINS over the config resolution, and under
  // a token a caller-supplied `agent` that claims somebody else is
  // refused outright; resolveAgentName stays the stdio and CLI fallback.
  const identity = ctx.requestIdentity;
  const claimedAgent = normalizeAgentArgument(validated.value.agent ?? null);
  refuseAgentClaim(identity, claimedAgent, "brain_feedback");
  const agent = claimedAgent ?? identity?.agent ?? resolveAgentName(ctx.configPath ?? undefined);
  // The subject the write-side gates answer for: the credential-minted
  // one when the transport minted it, the config-shaped one otherwise.
  const subject = identity ?? { agent, via: "config" as const };

  // The force-confirmed rule (write-side trust, Task 12). `force_confirmed`
  // skips the dream trial window - the one write whose whole point is to
  // bypass a review - so under a permissions document that bypass belongs
  // to the operator, not the caller: the caller's `write` verdict must be
  // `allow`, and anything else refuses with the named token BEFORE any
  // write. With no document this block never runs, so the document-absent
  // behavior is byte-identically the pre-Task-12 one. The verdict consult
  // is the substrate resolver directly - no disposition row - because the
  // write it guards has its own gate; this check only polices the bypass,
  // and it answers for the credential-minted subject, never for a name
  // the request argued for.
  if (forceConfirmed) {
    // The permissions document: the operator's shared setting, or the legacy
    // file on an unswitched machine (document-source.ts).
    const { document } = loadPermissionsDocumentFor(vault);
    if (document !== null) {
      const decision = resolvePermission(document, substrateSubject(subject), "write");
      if (decision.verdict !== "allow") {
        throw new MCPError(
          INVALID_PARAMS,
          `brain_feedback refused (${WRITE_REFUSAL_CODES.forceConfirmedRequiresAllow}): ` +
            "force_confirmed skips the dream trial window, which the permissions " +
            `document reserves for allow-verdict callers. Rule ${decision.source} ` +
            `(${decision.reason}) decided ${decision.verdict} for agent ` +
            `${JSON.stringify(subject.agent)}. The operator can review the policy: ` +
            FORCE_CONFIRMED_EXIT,
          {
            code: WRITE_REFUSAL_CODES.forceConfirmedRequiresAllow,
            rule: decision.source,
            verdict: decision.verdict,
            agent: subject.agent,
          },
        );
      }
    }
  }

  // Per-row event-time (A2 / t_7526e8d3): an optional caller-supplied
  // `event_time` lets a backfilled / imported "remember" carry when it
  // actually happened instead of the wall-clock. When present and valid,
  // it drives the signal's `created_at` / filename day and the
  // bi-temporal `valid_from` / `recorded_at` slots. The audit log and any
  // force-confirmed preference stay stamped at the real write moment
  // (`now`) so the audit chronology is not rewritten. Absent →
  // byte-identical to the historical wall-clock path.
  const eventTime = coerceIsoDate(args, "event_time");
  // Optional client idempotency key (C1 / t_213f356b): forwarded to the
  // signal writer so a retried / double-delivered feedback call dedupes
  // instead of appending a second signal. Absent → historical behaviour.
  const idempotencyKey = coerceStr(args, "idempotency_key", false);
  // Creation-time expiration (unit 3c). Validated through the one
  // chokepoint BEFORE the signal write, so an unparseable date refuses
  // the whole call rather than landing a signal and then failing on the
  // preference beside it.
  const expiresRaw = coerceStr(args, "expires", false);
  let expires: string | undefined;
  if (expiresRaw !== null && expiresRaw !== undefined) {
    try {
      expires = normalizeExpirationDate(expiresRaw);
    } catch (err) {
      throw new MCPError(INVALID_PARAMS, `brain_feedback: expires: ${(err as Error).message}`);
    }
  }
  const now = new Date();
  const createdAt = isoSecond(now);
  const signalStamp = eventTime ?? now;
  const signalCreatedAt = isoSecond(signalStamp);
  const signalDate = isoDate(signalStamp);
  const slug = deriveSlug(topic);

  // Vault-configured fallback scope (`feedback.default_scope`). Applied
  // only when the call passes no explicit scope. Compute one effective
  // scope so the signal, its mirror, and any force-confirmed preference
  // all land on the same scope.
  const defaultScope = loadFeedbackDefaultScopeSafe(vault);
  const effectiveScope = resolveEffectiveScope(scope, defaultScope);
  const writeOpts = defaultScope !== undefined ? { defaultScope } : {};

  // 1. Always write the signal to inbox/. Mirrors the CLI handler so the
  //    audit trail in `Brain/log/` and `inbox/processed/` stays consistent
  //    across CLI and MCP entry points. `--force-confirmed` ADDITIONALLY
  //    creates a confirmed pref below. The transport-minted identity
  //    rides to the review gate as its subject (write-side-trust, Task
  //    7): a document that denies the token's agent refuses this write
  //    before any byte exists.
  const signalInput = {
    topic,
    signal: signalRaw as BrainSignalSign,
    agent,
    principle,
    created_at: signalCreatedAt,
    date: signalDate,
    slug,
    ...(scope ? { scope } : {}),
    ...(source && source.length > 0 ? { source: [...source] } : {}),
    ...(raw ? { raw } : {}),
    // Stamp the bi-temporal slots only when an explicit event_time was
    // supplied, so a live "remember" stays byte-identical.
    ...(eventTime ? { valid_from: signalCreatedAt, recorded_at: signalCreatedAt } : {}),
    ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
    ...(expires !== undefined ? { expiration_date: expires } : {}),
  };
  let sigResult;
  try {
    sigResult = writeSignal(vault, signalInput, {
      ...writeOpts,
      // The review disposition always answers for THIS tool's resolved
      // identity: the credential-minted subject when the transport minted
      // one, the config-shaped subject this tool resolved (config path
      // honored, caller claim refused) otherwise. Leaving the subject off
      // would make the disposition re-resolve the agent without this
      // context's config path and answer for a stranger.
      subject,
    });
  } catch (err) {
    if (err instanceof WriteRefusedError) throw writeRefusedToMcp("brain_feedback", err);
    throw err;
  }
  // A deduped signal means this whole feedback call is a retry of one
  // already recorded — skip the log event, the shared-namespace mirror,
  // and any force-confirmed pref so the retry stays a true no-op.
  // EXCEPT a capture the ledger shows is UNFINISHED: when the original
  // call was force-confirmed, its signal landed, and its preference
  // write never completed, the call leaves a PENDING capture marker in
  // the idempotency ledger (below) and the retry that finds PENDING
  // without DONE, with the same capture payload, and with the signal
  // still present, completes the write. Everything else stays a true
  // no-op:
  //   - a completed capture (DONE exists),
  //   - a capture whose signal delete-by-source later forgot (the
  //     signal page / store record is gone - a user's forget must not
  //     be undone by a replay),
  //   - a first call made WITHOUT force_confirmed (no marker exists),
  //   - a retry whose force flag or expiration differs from the
  //     original (the marker hash names both, so it does not match).
  // "The preference is absent" proves none of this - a preference the
  // user removed by hand reads exactly like one never written - which is
  // why the resume reads the marker pair instead.
  // The force-confirmed preference write, spelled once so the deduped
  // retry path can resume it: same payload, same stamps, same writer.
  const writeConfirmedPreference = (): { path: string; id: string } =>
    timeStageSync(ROUTE_STAGE.preferenceWrite, () =>
      writePreference(
        vault,
        {
          slug,
          topic: topic.trim(),
          principle: principle.trim(),
          created_at: createdAt,
          unconfirmed_until: createdAt,
          status: BRAIN_PREFERENCE_STATUS.confirmed,
          evidenced_by: [`[[${sigResult.id}]]`],
          confirmed_at: createdAt,
          // Issue #149: an explicit zero, not an absent value. The
          // on-disk encoding of "absent" is the literal `null`, and two
          // ranking surfaces (`pre-compress-pack`, `morning-brief`) map
          // `null` to negative infinity before sorting - so a rule
          // force-confirmed a second ago would sort BELOW every rule
          // that has a number, including one measured at zero. Zero is
          // also the true Wilson lower bound on no evidence, which is
          // why the dream pass already pre-seeds it for new
          // preferences. This writer now matches it.
          confidence_value: 0,
          ...(effectiveScope !== undefined ? { scope: effectiveScope } : {}),
          // The same lifetime the signal carries: a rule confirmed from an
          // observation that expires on a date does not outlive it.
          ...(expires !== undefined ? { expiration_date: expires } : {}),
        },
        // Ownership is resolved by the writer, never echoed from `agent`:
        // that argument is caller-supplied, and a caller must not be able to
        // name whose memory this becomes. The server's config path is handed
        // over rather than a resolved name for the same reason, and the
        // transport-minted identity rides as the credential-minted subject
        // (write-side-trust, Task 7) so the gate and the stamp answer for
        // the token's agent.
        {
          ...(ctx.configPath !== null ? { configPath: ctx.configPath } : {}),
          ...(identity !== undefined ? { subject: identity } : {}),
        },
      ),
    );
  const logConfirmedPreference = (preferenceId: string): void => {
    try {
      // Offset by 1s so the force-confirmed event sorts after the feedback
      // event on the same UTC second (parseLogDay is stable on ties, but a
      // visible chronology reads cleaner).
      timeStageSync(ROUTE_STAGE.logAppend, () =>
        appendLogEvent(vault, {
          timestamp: isoSecond(new Date(now.getTime() + 1000)),
          eventType: BRAIN_LOG_EVENT_KIND.forceConfirmed,
          body: {
            preference: `[[${preferenceId}]]`,
            agent,
          },
        }),
      );
    } catch (err) {
      process.stderr.write(
        `warning: append force-confirmed log failed: ${(err as Error).message}\n`,
      );
    }
  };
  // The capture hash and marker keys, computed once: both the fresh
  // path (before the write) and the deduped retry path (to decide the
  // resume) read them.
  const captureHash = preferenceCaptureHash({
    topic: topic.trim(),
    principle: principle.trim(),
    agent,
    scope: effectiveScope,
    expires,
  });
  const markerKey =
    idempotencyKey !== null && idempotencyKey !== undefined
      ? preferenceMarkerKey(idempotencyKey)
      : undefined;
  const doneKey =
    idempotencyKey !== null && idempotencyKey !== undefined
      ? preferenceDoneKey(idempotencyKey)
      : undefined;
  if (sigResult.deduped) {
    // Positive evidence this capture is unfinished: the marker pair from
    // a force-confirmed original, with the same payload as THIS retry,
    // and a signal that still exists on disk / in the store.
    const presence = preferencePresence(vault, slug, ctx.configPath ?? undefined);
    const resumable =
      markerKey !== undefined &&
      doneKey !== undefined &&
      forceConfirmed &&
      lookupKey(vault, markerKey, PREFERENCE_MARKER_NAMESPACE)?.contentHash === captureHash &&
      lookupKey(vault, doneKey, PREFERENCE_MARKER_NAMESPACE) === null &&
      // A rule the user retired in the crash window stays retired: the
      // resume must not write a fresh confirmed rule beside it.
      presence !== "retired" &&
      signalRecordExists(vault, sigResult.path, sigResult.id, ctx.configPath ?? undefined);
    if (resumable && presence === "active") {
      // The crash landed AFTER the preference write but BEFORE the DONE
      // marker: the rule the original call wrote is already active. An
      // active rule matching this capture's own slug and payload IS the
      // completed capture, so the replay closes the ledger instead of
      // attempting the write a second time (which would refuse on the
      // existing rule). A rule that exists under this slug but does not
      // match the payload is not this capture's write, so it falls
      // through to the resume below and surfaces the conflict.
      const existing = loadPreference(vault, slug, {
        ...(ctx.configPath !== null ? { configPath: ctx.configPath } : {}),
      });
      // An active rule under this slug proves nothing on its own: a rule
      // the caller wrote earlier under the same slug and payload would be
      // adopted here without this capture ever having completed its own
      // write. Only THIS capture's write closes it - the write at
      // `writeConfirmedPreference` stamps the rule `confirmed` and names
      // the deduped signal under `evidenced_by` - so both must be present
      // before the ledger is closed on the existing rule.
      const captureMatches =
        existing !== null &&
        existing.status === BRAIN_PREFERENCE_STATUS.confirmed &&
        existing.evidenced_by.some(
          (ref) =>
            typeof ref === "string" && ref.replace(/^\[\[|\]\]$/g, "").trim() === sigResult.id,
        ) &&
        existing.topic === topic.trim() &&
        existing.principle === principle.trim() &&
        existing.scope === effectiveScope &&
        existing.expiration_date === expires;
      if (captureMatches && doneKey !== undefined) {
        appendMarkerReceipt(vault, doneKey, captureHash, createdAt);
        logConfirmedPreference(existing.id);
        const existingPath = preferencePathOf(vault, slug);
        return {
          kind: "preference",
          deduped: true,
          staged: false,
          signal_path:
            vault === null
              ? `${STORE_RECORD_PREFIX}${sigResult.id}`
              : toolPath(ctx, sigResult.path),
          signal_absolute_path:
            vault === null ? `${STORE_RECORD_PREFIX}${sigResult.id}` : resolve(sigResult.path),
          signal_id: sigResult.id,
          preference_path:
            vault === null ? `${STORE_RECORD_PREFIX}${existing.id}` : toolPath(ctx, existingPath),
          preference_absolute_path:
            vault === null ? `${STORE_RECORD_PREFIX}${existing.id}` : resolve(existingPath),
          preference_id: existing.id,
          path:
            vault === null ? `${STORE_RECORD_PREFIX}${existing.id}` : toolPath(ctx, existingPath),
          absolute_path:
            vault === null ? `${STORE_RECORD_PREFIX}${existing.id}` : resolve(existingPath),
          id: existing.id,
          agent,
        };
      }
    }
    if (resumable) {
      const resumed = writeConfirmedPreference();
      if (doneKey !== undefined) appendMarkerReceipt(vault, doneKey, captureHash, createdAt);
      logConfirmedPreference(resumed.id);
      return {
        kind: "preference",
        deduped: true,
        // The signal was deduped, so the retry staged nothing new.
        staged: false,
        signal_path:
          vault === null ? `${STORE_RECORD_PREFIX}${sigResult.id}` : toolPath(ctx, sigResult.path),
        signal_absolute_path:
          vault === null ? `${STORE_RECORD_PREFIX}${sigResult.id}` : resolve(sigResult.path),
        signal_id: sigResult.id,
        preference_path:
          vault === null ? `${STORE_RECORD_PREFIX}${resumed.id}` : toolPath(ctx, resumed.path),
        preference_absolute_path:
          vault === null ? `${STORE_RECORD_PREFIX}${resumed.id}` : resolve(resumed.path),
        preference_id: resumed.id,
        path: vault === null ? `${STORE_RECORD_PREFIX}${resumed.id}` : toolPath(ctx, resumed.path),
        absolute_path:
          vault === null ? `${STORE_RECORD_PREFIX}${resumed.id}` : resolve(resumed.path),
        id: resumed.id,
        agent,
      };
    }
    return {
      kind: "signal",
      deduped: true,
      // A dedup wrote nothing, so it staged nothing.
      staged: false,
      signal_path:
        vault === null ? `${STORE_RECORD_PREFIX}${sigResult.id}` : toolPath(ctx, sigResult.path),
      signal_absolute_path:
        vault === null ? `${STORE_RECORD_PREFIX}${sigResult.id}` : resolve(sigResult.path),
      signal_id: sigResult.id,
      path:
        vault === null ? `${STORE_RECORD_PREFIX}${sigResult.id}` : toolPath(ctx, sigResult.path),
      absolute_path:
        vault === null ? `${STORE_RECORD_PREFIX}${sigResult.id}` : resolve(sigResult.path),
      id: sigResult.id,
      agent,
    };
  }
  // t_936a1a61: fail-soft mirror into the shared namespace AFTER the
  // primary write; `mirror` is reported only when the key is configured.
  const sharedNamespace = resolveSharedNamespace(ctx.configPath);
  // The mirror copies from a vault, so there is none without one.
  const mirror =
    sharedNamespace === null || vault === null
      ? undefined
      : mirrorSignal(sharedNamespace, vault, signalInput, writeOpts, ctx.configPath);

  try {
    timeStageSync(ROUTE_STAGE.logAppend, () =>
      appendLogEvent(vault, {
        timestamp: createdAt,
        eventType: BRAIN_LOG_EVENT_KIND.feedback,
        body: {
          signal: `[[${sigResult.id}]]`,
          topic: topic.trim(),
          sign: signalRaw,
          agent,
        },
      }),
    );
  } catch (err) {
    process.stderr.write(`warning: append feedback log failed: ${(err as Error).message}\n`);
  }

  // Write-time conflict advisory (A4): compare the incoming principle
  // against confirmed same-scope preferences and surface a non-blocking
  // advisory when it closely resembles an existing rule. Computed BEFORE
  // any force-confirmed write so it never matches the pref this very call
  // is about to create. The write has already landed; this never blocks it.
  // Both advisories answer at the caller's reach: a preference or signal
  // the caller may not read is never scored, named or counted.
  const readable = readableAtContextReachOrUndefined(ctx);
  const advisory: WriteConflictAdvisory | null = adviseIncomingFeedback(vault, {
    principle,
    ...(readable !== undefined ? { readable } : {}),
    ...(effectiveScope !== undefined ? { scope: effectiveScope } : {}),
    agent,
    now,
  });

  // Unroutable-capture routing hint (unit 4): the signal above resolved
  // no scope, so no scoped recall reaches it. Non-blocking like the
  // advisory, and absent entirely when this vault uses no scopes yet.
  const routingHint: CaptureRoutingHint | null = adviseUnroutableCapture(vault, {
    ...(readable !== undefined ? { readable } : {}),
    ...(effectiveScope !== undefined ? { scope: effectiveScope } : {}),
    agent,
    now,
  });

  let prefResult: { path: string; id: string } | null = null;
  if (forceConfirmed) {
    // Leave the PENDING capture marker BEFORE the write: the signal and
    // its own receipt have already landed, so a crash or refusal inside
    // `writePreference` leaves PENDING without DONE - the positive mark
    // a deduped retry reads to finish this capture (see the deduped
    // branch above). Fail-soft: without a client key there is nothing to
    // mark, and a marker that cannot be stored only costs the repair.
    if (markerKey !== undefined) appendMarkerReceipt(vault, markerKey, captureHash, createdAt);
    // Escape hatch: skip the dream pass and create the confirmed rule now.
    // `confirmed_at` is now; `unconfirmed_until` is also now so the trial
    // window collapses on inspection. The just-written signal is recorded
    // as the rule's origin under `evidenced_by`. A throw here leaves
    // PENDING without DONE in the ledger - exactly the resume mark.
    prefResult = writeConfirmedPreference();
    if (doneKey !== undefined) appendMarkerReceipt(vault, doneKey, captureHash, createdAt);
    logConfirmedPreference(prefResult.id);
  }

  // With no vault the records have no file: both fields name the record
  // (`store:<id>`), as the CLI does.
  const named = (path: string, id: string): string =>
    vault === null ? `${STORE_RECORD_PREFIX}${id}` : toolPath(ctx, path);
  const absolute = (path: string, id: string): string =>
    vault === null ? `${STORE_RECORD_PREFIX}${id}` : resolve(path);
  return {
    kind: prefResult ? "preference" : "signal",
    ...mirrorReportFields(mirror),
    ...(advisory !== null ? { advisory } : {}),
    // Same key and same resolution as the CLI's `--json` renderer, from
    // the one composer: an agent that learns the exit on one surface
    // reads it on the other.
    ...captureRoutingHintField(routingHint),
    // Write-side trust (Task 6): the gate resolved inside writeSignal, so
    // the receipt says which directory the bytes actually landed in. An
    // agent that reads `staged: true` knows the signal is awaiting review
    // under `Brain/pending/`, not recalled from `Brain/inbox/`. The
    // pending id and the queue command (Task 9) give that agent the
    // handle and the exit, since applying is an operator's move.
    staged: sigResult.staged,
    ...(sigResult.staged
      ? {
          pending_id: sigResult.id,
          ...nextCommandField(PENDING_STAGED_DIAGNOSTIC_CODE),
        }
      : {}),
    signal_path: named(sigResult.path, sigResult.id),
    signal_absolute_path: absolute(sigResult.path, sigResult.id),
    signal_id: sigResult.id,
    ...(prefResult
      ? {
          preference_path: named(prefResult.path, prefResult.id),
          preference_absolute_path: absolute(prefResult.path, prefResult.id),
          preference_id: prefResult.id,
          // Back-compat: top-level `path`/`id` previously pointed at the
          // pref on the force-confirmed branch. Keep them aligned for
          // callers that look at the bare fields.
          path: named(prefResult.path, prefResult.id),
          absolute_path: absolute(prefResult.path, prefResult.id),
          id: prefResult.id,
        }
      : {
          path: named(sigResult.path, sigResult.id),
          absolute_path: absolute(sigResult.path, sigResult.id),
          id: sigResult.id,
        }),
    agent,
  };
}