@remembrance-ai/opencode-plugin 0.1.77 → 0.2.0

package/README.md

@@ -2,8 +2,8 @@
 
 Connects Remembrance to [opencode](https://opencode.ai): the MCP server that
 exposes the Remembrance tools, plus a plugin that records activation health,
-observes Remembrance tool use, and asks for redacted feedback when a session goes
-idle.
+observes Remembrance tool use, and records unfinished feedback/capture work
+silently when a session goes idle so the next prompt can recover it.
 
 ## Install
 
@@ -18,8 +18,18 @@ server to `~/.config/opencode/opencode.json`. It preserves comments and unrelate
 settings and creates a new config with mode `0600` when none exists.
 
 Restart opencode. Remembrance then appears in its tools list, adds bounded
-matching guidance to eligible model turns, observes completed use, and asks once
-for concise, redacted feedback.
+matching guidance to eligible model turns, observes completed use, and silently
+queues any missing feedback or capture action for the next real prompt.
+
+**Node.js runtime.** The MCP entry that setup writes runs `npx`, so Node.js
+18.17.0 or newer and npm must be on the PATH opencode starts with. A host
+started from the Dock, Finder or an IDE may not have your shell's PATH, so a
+Node.js installed by nvm, fnm, volta, asdf, nodenv or mise can be missing from
+it; the symptom is `spawn node ENOENT` or "No such file or directory". `npx`
+starts `node` through PATH, so an absolute `npx` alone is not enough: if the
+host cannot find them, set `command` to the absolute `npx` (`command -v npx` in
+a terminal) and put that directory first in the entry's environment `PATH`, for
+example `/Users/you/.nvm/versions/node/v22.12.0/bin:/usr/bin:/bin`.
 
 At session creation, the plugin performs a bounded, credential-free release
 check. If a newer verified version exists, opencode shows a notice and gives the
@@ -44,8 +54,8 @@ The stable plugin API exposes `chat.message` and
 `experimental.chat.system.transform`. Remembrance uses them together to run the
 fail-open query helper and inject bounded guidance before an eligible model
 turn. Empty or unavailable queries never block the task. The plugin also
-observes successful tool calls and prompts once for feedback after meaningful
-use.
+observes successful tool calls and records pending feedback after meaningful
+use for bounded recovery on the next prompt.
 
 ## Installation identity and preferences
 
@@ -64,10 +74,14 @@ working preferences follow each engineer across approved agents and steer
 relevant public and team skills without changing shared instructions or
 weakening organization policy. Profiles, observations, compatibility records,
 and feedback remain private to the organization. An explicit instruction
-governs the current task immediately. Known built-ins activate durably at once.
+governs the current task immediately. Known built-ins activate durably at once for a
+managed-encryption organization.
 Custom preferences remain pending until automatic normalization and validation
 approves them; unsafe, malformed, or uncertain custom behavior stays inactive
-and is never replayed to an agent. Classification runs
+and is never replayed to an agent.
+An organization using customer-held encryption is currently deferred: every substantive preference write and every compatibility-feedback call is refused before persistence with HTTP 422 and code `customer_held_preference_processing_deferred`. Existing records are unchanged, reads and the content-free withdrawal lane keep working, and responses withhold the compatibility-feedback offer there. Read `activated` and
+`normalized_activation_state` in the response instead of assuming a setting is
+live. Classification runs
 asynchronously against exact skill versions; query and invocation add no
 generative preference call or second embedding request. Material compatibility
 may reorder only already-relevant skills inside one match tier or apply a
@@ -132,12 +146,48 @@ link-local self-host also requires `REMEMBRANCE_ALLOW_PRIVATE_REGISTRY=true`.
 | `chat.message`                       | Runs the fail-open query helper for the current user turn.      |
 | `experimental.chat.system.transform` | Adds bounded Remembrance guidance before model dispatch.        |
 | `tool.execute.after`                 | Correlates query, invocation, detail, and contribution calls.   |
-| `session.idle`                       | Shows a compact contribution nudge once per engagement.         |
-
+| `session.idle`                       | Records bounded pending contribution work for the next prompt.  |
+
+Host-generated text a trigger word matches (a Codex commit or pull-request
+generation prompt, a subagent hand-back, pasted `git status` output, an explicit
+local skill invocation) skips only the skill search: the organization policy,
+required settings and preferences a search would carry still arrive; set
+`REMEMBRANCE_AUTO_QUERY_HYGIENE=0` to search it anyway.
+Besides prompts a keyword trigger matches, the hook searches any other
+task-shaped prompt of at least 40 characters (trigger reason `task_shape`).
+A task-shape search that finds nothing adds nothing of its own: no no-match
+block, no completion recovery and no query-feedback request. Its organization
+policy, required settings, preferences and capture lines still arrive, and the
+server still records the missing-skill demand.
+Set `REMEMBRANCE_AUTO_QUERY_TASK_SHAPE=0` to search keyword-triggered prompts
+only.
+Without an organization key, the server's relevance judge chooses what a search
+is shown from the top 20 public candidates: Jev (TypeSafe, through Vercel AI
+Gateway) rates each candidate first, and a language model decides the ones Jev
+leaves undecided while there is time. It receives the search's task text and
+public skill cards only. Every request asks for zero retention and no prompt
+training; for Jev, zero retention rests on Remembrance's account-specific
+agreement with TypeSafe through Vercel, which the Gateway does not confirm.
+With an organization key, a search is judged only under the organization's
+managed processing grant for semantic search, and Jev rates it first only when
+that grant also approves TypeSafe, under the owner-attested zero-retention
+agreement with TypeSafe (owner decisions 36 and 64), which covers this judge
+stage and no other purpose: its task text and skill cards, the organization's
+own included, go only to the hosts that grant approves, each asked for zero
+retention and no prompt training. Without that grant nothing is sent and the
+search keeps the rule's list.
+A card shows a skill's use and exclusion conditions only where the
+platform generated them or a person reviewed them. A use condition only
+promotes a result, and only an exclusion its author stated or a person
+reviewed makes it `unlikely`; `applicability.provenance` says who stated
+them.
+Set `REMEMBRANCE_AUTO_QUERY_STRIP_INJECTED_CONTEXT=1` to search only the text
+after a leading `<compartment_examples_from_other_projects>` block (off by
+default).
 Set `REMEMBRANCE_AUTO_QUERY=0` to disable the query, or
-`REMEMBRANCE_AUTO_CONTRIBUTE=0` to disable the completion nudge. OpenCode's
-current idle event exposes this compact instruction as a toast or structured
-log rather than forcing another agent turn.
+`REMEMBRANCE_AUTO_CONTRIBUTE=0` to disable silent completion recovery. The
+idle event does not emit routine contribution text as a toast or structured log;
+the next real user prompt receives only the exact bounded recovery actions.
 
 ## Host policy
 
@@ -145,18 +195,29 @@ A tenant or privacy-policy denial in the host happens before Remembrance is
 called, so it is not a Remembrance misconfiguration — the same boundary as a
 Codex tenant/privacy-policy denial, which occurs before Remembrance is reached
 and must not be reported as a Remembrance setup failure. The plugin reports one
-local, content-free alert: **Remembrance was blocked by host policy before
-reaching Remembrance. Nothing was sent. Querying remains available.** It does
+local, content-free alert: **The host blocked this Remembrance action. Do not
+treat it as submitted. Earlier successful actions are unaffected; querying remains available.** It does
 not retry or automatically create a handoff.
 
-### Private lesson autopilot
-
-The local `prepare_private_lesson_candidate` tool canonicalizes and redacts a
-routine organization lesson in memory and stores only an encrypted
-post-redaction draft. `submit_private_lesson_candidate` is the separate network
-action; it sends those exact bytes only to the authenticated organization's
-private verifier queue. This action always submits privately and never falls
-back to anonymous or public submission. After the private outcome is accepted,
+### Private learning autopilot
+
+Current organization-capable local clients expose `capture_learning` as the
+only routine reusable-learning entry point. Supply exactly one compact
+`lesson`, complete `private_skill`, or structured durable `preference`. It
+accepts no organization, destination, visibility, credential, or public
+fallback. Lessons are canonicalized and redacted in memory; complete skills
+retain bounded markdown, public citations, snippets, metadata, and actionable
+instructions. Lesson and skill drafts are encrypted in separate outboxes; a
+preference returns the exact existing `record_preference` action.
+`capture_learning` is local and makes no network request.
+
+Invoke only the returned `submit_private_lesson_candidate`,
+`submit_private_skill_candidate`, or `record_preference` action.
+These actions always submit privately. Lesson and skill actions carry only a local draft ID
+through OpenCode to the authenticated organization's pipeline and never falls
+back to anonymous or public submission. Accepted content reuses the existing verifier,
+topology, review, versioning, audit, and admin-controlled propagation pipeline;
+the submitting agent never chooses visibility. After the private outcome is accepted,
 a separate server-owned process may create a freshly redacted public candidate
 only when the organization admin enabled **Contribution propagation**; the
 submitting agent neither chooses nor sees that process, and the derivative must
@@ -165,20 +226,99 @@ or auto-delete. Verified submissions discard encrypted lesson content
 immediately; their content-free completion markers are automatically deleted
 after 14 days.
 
-The signed policy pins the corrected `private-lesson-redaction-v2` profile and
-its exact digest. Unsupported-profile drafts become terminal
-`superseded_redactor`, stay encrypted, and are never retried, re-redacted, or
-automatically deleted. When health reporting is enabled, a held draft may send
+The lesson client offers a bounded `private-lesson-redaction-v2` supported
+redactor-profile set and the
+server signs policy for the newest mutual profile. Retained drafts require
+their exact bound profile. Temporary incompatibility remains encrypted as
+`awaiting_compatible_profile` with precise update, restart, or server-rollout
+guidance; it is not mislabeled as safety or host denial. A profile becomes
+terminal only when the installed client no longer supports it; that state is
+`superseded_redactor`. Terminal drafts stay encrypted and are never retried, re-redacted, or automatically deleted.
+When health reporting is enabled, a held draft may send
 only content-free category/version counts and signed protocol digests through
 the same approved action; that telemetry cannot enter verification, review,
 topology, or skill materialization. Disable it with
 `REMEMBRANCE_HEALTH_REPORTING=0`.
 
-OpenCode permission keys match MCP tool names. Set only
-`remembrance_submit_private_lesson_candidate` to `allow`; broader Remembrance
-write tools can remain `ask` or `deny`. Local preparation, inspection, retry,
-and confirmed deletion remain local-only. A host denial is held and is never
-retried through another transport.
+OpenCode permission keys match MCP tool names. Allow the submit and retry tools
+for the `private_lesson` and `private_skill` lanes; broader Remembrance write
+tools can remain `ask` or `deny`. Remembrance maps an existing submit approval
+to its lane. Local capture, inspection, and confirmed deletion remain
+zero-network; a fresh-draft retry stops before network access. Broad `submit_remembrance` and
+`propose_private_skill` are legacy/hosted/raw compatibility routes and are
+unavailable by default locally. `submit_query_feedback` remains independently
+available for one complete good/partial/poor query-fit verdict set;
+`submit_feedback` is categorical post-use feedback. A host denial is held and
+is never retried through another transport.
+
+### Routing metadata on complete skill proposals
+
+In 0.2.0 a complete skill sent with `propose_skill_idea` or
+`propose_private_skill` (or their REST routes) carries routing metadata
+(contract v1, published at `/schemas/skill-routing-metadata.v1.json`): when
+an agent should pick the skill (`applicability`) and what it does and needs
+(`routing`). Ask for a platform draft first, show it to the author, and send
+the confirmed or edited fields back with the draft's token. The draft call
+stores nothing:
+
+```json
+{
+  "title": "Deploy a prepared app to Azure",
+  "description": "Deploy an already-prepared app to Azure with azd.",
+  "proposed_skill_md": "# Deploy a prepared app to Azure\n\nRun azd up ...",
+  "prefill_routing_metadata": true
+}
+```
+
+Its answer holds `example.proposed_metadata` and `routing_draft.token`. The
+submission then sends the confirmed fields:
+
+```json
+{
+  "title": "Deploy a prepared app to Azure",
+  "description": "Deploy an already-prepared app to Azure with azd.",
+  "proposed_skill_md": "# Deploy a prepared app to Azure\n\nRun azd up ...",
+  "proposed_metadata": {
+    "applicability": {
+      "scope": "specialized",
+      "use_when": [
+        "The user wants to deploy an already-prepared app to Azure",
+        "A deployment plan and infrastructure files already exist",
+        "The user asks to run azd up or azd deploy"
+      ],
+      "avoid_when": [
+        "The app has no Azure deployment files yet (prepare it first)",
+        "The user only wants a readiness check without deploying"
+      ],
+      "task_examples": [
+        "Deploy this prepared app to Azure Container Apps",
+        "Run azd up for my project",
+        "Push the validated Bicep deployment to production"
+      ],
+      "not_for": []
+    },
+    "routing": {
+      "capabilities": ["deploy-to-cloud"],
+      "domains": ["deployments-cicd", "cloud-platforms"],
+      "runtime_requirements": ["repo-checkout", "shell", "cloud-account", "provider-azure"],
+      "risk": "cloud-changes"
+    }
+  },
+  "routing_draft_token": "rd1.<token from the draft>"
+}
+```
+
+A complete skill without these fields is refused with 422
+`skill_routing_metadata_incomplete` (`delivery: not_delivered`; nothing is
+stored). The refusal lists every issue and carries the same draft, so fix
+the listed fields and send the request again. Fields taken unchanged are
+recorded as author-confirmed draft values; edits that widen the draft (a
+broader scope, added `use_when` items or capabilities, a lower risk) are
+flagged for review. An organization's text is drafted only through its
+approved semantic-enrichment processing grant; without one the draft is held
+and nothing is sent. A private capture (`capture_learning` with
+`private_skill`) may ask for automatic completion: the skill becomes
+available after acceptance once its routing metadata is complete.
 
 ## Generated files
 

package/opencode.json

@@ -6,7 +6,7 @@
       "command": [
         "npx",
         "-y",
-        "@remembrance-ai/mcp-server@0.1.77"
+        "@remembrance-ai/mcp-server@0.2.0"
       ],
       "enabled": true,
       "environment": {
@@ -16,6 +16,6 @@
     }
   },
   "plugin": [
-    "@remembrance-ai/opencode-plugin@0.1.77"
+    "@remembrance-ai/opencode-plugin@0.2.0"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remembrance-ai/opencode-plugin",
-  "version": "0.1.77",
+  "version": "0.2.0",
   "license": "Apache-2.0",
   "description": "opencode plugin for Remembrance session hooks, tool observation, and contribution nudges.",
   "type": "module",

package/scripts/feedback-disposition.mjs

@@ -0,0 +1,376 @@
+import { createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  opendirSync,
+  readSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+
+const FEEDBACK_DENIAL_VERSION = "feedback-denial-acknowledgement-v1";
+const FEEDBACK_DENIAL_SUBDIRECTORY = "feedback-denials";
+const FEEDBACK_DENIAL_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+const MAX_FEEDBACK_IDENTIFIER_LENGTH = 512;
+const MAX_FEEDBACK_DENIAL_MARKER_BYTES = 1024;
+const MAX_FEEDBACK_DENIAL_MARKERS = 512;
+const MARKER_NAME_PATTERN = /^[a-f0-9]{64}\.json$/u;
+
+class FeedbackDenialStorageError extends Error {
+  constructor() {
+    super("The host-policy denial acknowledgement could not be persisted.");
+    this.name = "FeedbackDenialStorageError";
+    this.code = "feedback_denial_acknowledgement_failed";
+    this.status = "acknowledgement_failed";
+    this.acknowledged = false;
+    this.submitted = false;
+    this.local_only = true;
+  }
+}
+
+function normalizeInput(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+  const keys = Object.keys(input).sort();
+  const expectedKeys =
+    input.tool === "submit_feedback"
+      ? ["query_id", "reason", "result_id", "tool"]
+      : ["query_id", "reason", "tool"];
+  if (
+    keys.length !== expectedKeys.length ||
+    keys.some((key, index) => key !== expectedKeys[index]) ||
+    !["submit_query_feedback", "submit_feedback"].includes(input.tool) ||
+    input.reason !== "host_policy_denied" ||
+    !validIdentifier(input.query_id)
+  ) {
+    return null;
+  }
+  if (input.tool === "submit_feedback") {
+    if (!validIdentifier(input.result_id)) return null;
+    return {
+      tool: input.tool,
+      query_id: input.query_id,
+      result_id: input.result_id,
+      reason: input.reason,
+    };
+  }
+  if ("result_id" in input) return null;
+  return {
+    tool: input.tool,
+    query_id: input.query_id,
+    reason: input.reason,
+  };
+}
+
+function validIdentifier(value) {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_FEEDBACK_IDENTIFIER_LENGTH
+  );
+}
+
+function exactEventDigest(input) {
+  const fields = [input.tool, input.query_id, input.result_id ?? ""];
+  const hash = createHash("sha256");
+  for (const field of fields) {
+    const bytes = Buffer.from(field, "utf8");
+    hash.update(String(bytes.length), "utf8");
+    hash.update(":", "utf8");
+    hash.update(bytes);
+    hash.update(";", "utf8");
+  }
+  return hash.digest("hex");
+}
+
+function localUsageOwnerId() {
+  const uid = currentUserId();
+  if (uid !== null) return `uid-${uid}`;
+  return `home-${createHash("sha256")
+    .update(homedir())
+    .digest("hex")
+    .slice(0, 16)}`;
+}
+
+function currentUserId() {
+  try {
+    const uid = userInfo().uid;
+    if (Number.isSafeInteger(uid) && uid >= 0) return uid;
+  } catch {
+    // Non-POSIX runtimes fall back to the same home hash as hook-core.
+  }
+  return null;
+}
+
+function usageDirectory(env) {
+  return env?.REMEMBRANCE_USAGE_DIR
+    ? String(env.REMEMBRANCE_USAGE_DIR)
+    : join(tmpdir(), `remembrance-usage-${localUsageOwnerId()}`);
+}
+
+function markerDirectory(env) {
+  return join(usageDirectory(env), FEEDBACK_DENIAL_SUBDIRECTORY);
+}
+
+function markerPath(input, env) {
+  return join(markerDirectory(env), `${exactEventDigest(input)}.json`);
+}
+
+function isPosix() {
+  return currentUserId() !== null;
+}
+
+function assertCurrentOwner(uid) {
+  const currentUid = currentUserId();
+  if (currentUid !== null && uid !== currentUid) {
+    throw new Error("Local state is not owned by the current user.");
+  }
+}
+
+function ensurePrivateDirectory(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const metadata = lstatSync(path);
+  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+    throw new Error("Local state is not a regular directory.");
+  }
+  assertCurrentOwner(metadata.uid);
+  if (isPosix() && (metadata.mode & 0o077) !== 0) {
+    chmodSync(path, 0o700);
+    const repaired = lstatSync(path);
+    assertCurrentOwner(repaired.uid);
+    if ((repaired.mode & 0o077) !== 0) {
+      throw new Error("Local state directory permissions are not private.");
+    }
+  }
+}
+
+function assertPrivateDirectory(path) {
+  const metadata = lstatSync(path);
+  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+    throw new Error("Local state is not a regular directory.");
+  }
+  assertCurrentOwner(metadata.uid);
+  if (isPosix() && (metadata.mode & 0o022) !== 0) {
+    throw new Error("Local state directory is writable by another user.");
+  }
+}
+
+function assertPrivateMarker(metadata) {
+  if (
+    metadata.isSymbolicLink() ||
+    !metadata.isFile() ||
+    metadata.size > MAX_FEEDBACK_DENIAL_MARKER_BYTES
+  ) {
+    throw new Error("Local state marker is unsafe.");
+  }
+  assertCurrentOwner(metadata.uid);
+  if (isPosix() && (metadata.mode & 0o077) !== 0) {
+    throw new Error("Local state marker permissions are not private.");
+  }
+}
+
+function readBoundedDescriptor(descriptor) {
+  const chunks = [];
+  let total = 0;
+  while (total <= MAX_FEEDBACK_DENIAL_MARKER_BYTES) {
+    const chunk = Buffer.allocUnsafe(
+      Math.min(1024, MAX_FEEDBACK_DENIAL_MARKER_BYTES + 1 - total),
+    );
+    const bytesRead = readSync(descriptor, chunk, 0, chunk.length, null);
+    if (bytesRead === 0) break;
+    chunks.push(chunk.subarray(0, bytesRead));
+    total += bytesRead;
+  }
+  if (total > MAX_FEEDBACK_DENIAL_MARKER_BYTES) {
+    throw new Error("Local state marker exceeds its size limit.");
+  }
+  return Buffer.concat(chunks, total).toString("utf8");
+}
+
+function readMarker(path, expectedDigest) {
+  assertPrivateDirectory(dirname(dirname(path)));
+  assertPrivateDirectory(dirname(path));
+  const before = lstatSync(path);
+  assertPrivateMarker(before);
+  const descriptor = openSync(
+    path,
+    constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
+  );
+  try {
+    const opened = fstatSync(descriptor);
+    assertPrivateMarker(opened);
+    if (before.dev !== opened.dev || before.ino !== opened.ino) {
+      throw new Error("Local state marker changed while opening.");
+    }
+    const parsed = JSON.parse(readBoundedDescriptor(descriptor));
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed) ||
+      parsed.version !== FEEDBACK_DENIAL_VERSION ||
+      parsed.event_digest !== `sha256:${expectedDigest}` ||
+      typeof parsed.acknowledged_at !== "string" ||
+      typeof parsed.expires_at !== "string" ||
+      !Number.isFinite(Date.parse(parsed.acknowledged_at)) ||
+      !Number.isFinite(Date.parse(parsed.expires_at))
+    ) {
+      throw new Error("Local state marker is malformed.");
+    }
+    return parsed;
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function removeExpiredMarker(path, marker, now) {
+  if (Date.parse(marker.expires_at) > now) return false;
+  rmSync(path, { force: true });
+  return true;
+}
+
+function cleanupExpiredMarkers(directory, now) {
+  const handle = opendirSync(directory);
+  let markerCount = 0;
+  let visited = 0;
+  try {
+    while (visited <= MAX_FEEDBACK_DENIAL_MARKERS) {
+      const entry = handle.readSync();
+      if (!entry) break;
+      visited += 1;
+      if (!entry.isFile() || !MARKER_NAME_PATTERN.test(entry.name)) continue;
+      markerCount += 1;
+      const digest = entry.name.slice(0, -".json".length);
+      const path = join(directory, entry.name);
+      try {
+        if (removeExpiredMarker(path, readMarker(path, digest), now)) {
+          markerCount -= 1;
+        }
+      } catch {
+        // One corrupt marker cannot acknowledge or remove another event.
+      }
+    }
+    if (visited > MAX_FEEDBACK_DENIAL_MARKERS) {
+      throw new Error("Local acknowledgement storage exceeds its entry limit.");
+    }
+  } finally {
+    handle.closeSync();
+  }
+  if (markerCount >= MAX_FEEDBACK_DENIAL_MARKERS) {
+    throw new Error("Local acknowledgement storage is full.");
+  }
+}
+
+function writeMarkerAtomically(path, marker) {
+  const temporaryPath = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+  let descriptor;
+  try {
+    descriptor = openSync(
+      temporaryPath,
+      constants.O_WRONLY |
+        constants.O_CREAT |
+        constants.O_EXCL |
+        (constants.O_NOFOLLOW ?? 0),
+      0o600,
+    );
+    writeFileSync(descriptor, `${JSON.stringify(marker)}\n`, {
+      encoding: "utf8",
+    });
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+    renameSync(temporaryPath, path);
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try {
+        closeSync(descriptor);
+      } catch {
+        // Preserve the original persistence failure.
+      }
+    }
+    try {
+      rmSync(temporaryPath, { force: true });
+    } catch {
+      // Preserve the original persistence failure.
+    }
+    throw error;
+  }
+}
+
+export function acknowledgeFeedbackDenial(input, env = process.env) {
+  const normalized = normalizeInput(input);
+  if (!normalized) {
+    throw new TypeError("Invalid feedback denial acknowledgement input.");
+  }
+  const digest = exactEventDigest(normalized);
+  const directory = markerDirectory(env);
+  const path = markerPath(normalized, env);
+  const now = Date.now();
+  try {
+    ensurePrivateDirectory(usageDirectory(env));
+    ensurePrivateDirectory(directory);
+    cleanupExpiredMarkers(directory, now);
+    try {
+      const existing = readMarker(path, digest);
+      if (Date.parse(existing.expires_at) > now) {
+        return {
+          status: "acknowledged_host_denial",
+          acknowledged: true,
+          submitted: false,
+          local_only: true,
+          already_acknowledged: true,
+          expires_at: existing.expires_at,
+        };
+      }
+      rmSync(path, { force: true });
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    const acknowledgedAt = new Date(now).toISOString();
+    const expiresAt = new Date(
+      now + FEEDBACK_DENIAL_RETENTION_MS,
+    ).toISOString();
+    writeMarkerAtomically(path, {
+      version: FEEDBACK_DENIAL_VERSION,
+      event_digest: `sha256:${digest}`,
+      acknowledged_at: acknowledgedAt,
+      expires_at: expiresAt,
+    });
+    const persisted = readMarker(path, digest);
+    if (Date.parse(persisted.expires_at) <= now) {
+      throw new Error("Local acknowledgement expired before persistence.");
+    }
+    return {
+      status: "acknowledged_host_denial",
+      acknowledged: true,
+      submitted: false,
+      local_only: true,
+      already_acknowledged: false,
+      expires_at: persisted.expires_at,
+    };
+  } catch (error) {
+    throw new FeedbackDenialStorageError();
+  }
+}
+
+export function feedbackDenialAcknowledged(input, env = process.env) {
+  const normalized = normalizeInput(input);
+  if (!normalized) return false;
+  const digest = exactEventDigest(normalized);
+  const path = markerPath(normalized, env);
+  try {
+    const marker = readMarker(path, digest);
+    const now = Date.now();
+    if (removeExpiredMarker(path, marker, now)) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}