@remnic/core 9.69.39 → 9.69.41

package/src/recall-state-view-widen.test.ts

@@ -96,11 +96,20 @@ test("#1952 precedence is OR: per-call false never disables a global true", () =
   assert.equal(labeled[1]?.stateLabel, "historical");
 });
 
-test("#1952 override true on a non-change query stays identity (change gate applies)", () => {
-  const input = [CURRENT, HISTORICAL];
-  assert.equal(widenRecallStateViews(input, NON_CHANGE, { recallStateViews: false }, [], true), input);
-  assert.equal(applyRecallStateViews(input, NON_CHANGE, { recallStateViews: false }, true), input);
-  assert.equal(input[0]?.stateLabel, undefined);
+test("#2893 threaded stateViewActive is trusted: no intent re-check at the seam", () => {
+  // The threaded flag means change intent was already classified on the
+  // ORIGINAL prompt at recall entry (resolveRecallStateViewActive); the
+  // query reaching this seam is the cron-normalized retrievalQuery and
+  // can lack the intent signal. Non-change ORIGINAL prompts never thread
+  // a true flag — pinned in recall-state-view-cron-intent.test.ts.
+  const labeled = widenRecallStateViews([CURRENT], NON_CHANGE, { recallStateViews: false }, [HISTORICAL], true);
+  assert.deepEqual(
+    labeled.map((row) => [row.id, row.stateLabel]),
+    [
+      ["new-job", "current"],
+      ["old-job", "historical"],
+    ],
+  );
 });
 
 test("asOf mode keeps a pin-filtered predecessor and never widens the pool (#1952)", () => {

package/src/recall-state-view-widen.ts

@@ -43,7 +43,13 @@ export function widenRecallStateViews<T extends StateViewResult>(
       ? config.recallStateViews
       : undefined;
   const enabled = stateViewActive === true || parseRecallStateViews(raw);
-  if (!enabled || !isChangeOrientedQuery(query)) return results;
+  if (!enabled) return results;
+  // #2893 — a threaded stateViewActive was gated on change intent
+  // classified from the ORIGINAL prompt at recall entry; `query` here is
+  // the cron-normalized retrievalQuery and may have lost the intent
+  // signal (truncation / stop-word compaction), so do not re-check it.
+  // Only the legacy config-only path re-checks intent against this query.
+  if (stateViewActive !== true && !isChangeOrientedQuery(query)) return results;
   const asOfActive = typeof asOfMs === "number" && Number.isFinite(asOfMs);
 
   // #2859: matches are namespace-qualified, and a successor's `supersedes`
@@ -79,6 +85,7 @@ export function widenRecallStateViews<T extends StateViewResult>(
 
   return annotateStateView(extra.length > 0 ? results.concat(extra) : results, query, [], {
     enabled: true,
+    ...(stateViewActive === true ? { changeIntent: true } : {}),
     ...(asOfActive ? { asOfMs } : {}),
   });
 }

package/src/recall-state-view.ts

@@ -205,10 +205,13 @@ export function annotateStateView<T extends StateViewResult>(
   results: T[],
   query: string,
   chains: readonly StateViewChain[],
-  options: { enabled?: boolean; asOfMs?: number } = {},
+  options: { enabled?: boolean; asOfMs?: number; changeIntent?: boolean } = {},
 ): T[] {
   const enabled = options.enabled === true;
-  if (!enabled || !isChangeOrientedQuery(query)) return results;
+  // #2893 — changeIntent:true marks intent as already classified from the
+  // ORIGINAL prompt; `query` may be cron-normalized (intent signal
+  // truncated or stop-worded away) and must not be re-checked then.
+  if (!enabled || (options.changeIntent !== true && !isChangeOrientedQuery(query))) return results;
   // #1952 asOf mode: under a historical pin the pipeline's isValidAsOf
   // gate already decided validity at the pinned instant, so a predecessor
   // must not be discarded merely because its successor is absent under
@@ -293,22 +296,15 @@ export function reconcileStateViewPairs<T extends StateViewResult>(results: read
 }
 
 /**
- * #2859 — packet-counting cap. A predecessor/successor chain admitted
- * together is ONE complete evidence packet: it consumes a single slot of
- * the user cap, and the slice never splits a packet at the boundary (no
- * underfill from post-cap orphan removal). Rows keep their incoming
- * (MMR) order; packets are ordered by first appearance. Call
- * reconcileStateViewPairs first so orphans never consume a slot.
+ * #2928 — per-row packet root keys for the final output budget. Runs the
+ * same namespace-qualified union-find as {@link capStateViewPackets}:
+ * every row of one evidence packet shares the root key, so a downstream
+ * budget that admits one row of the packet can admit them all or none.
+ * Blank-key rows get unique per-index roots (distinct singletons).
  */
-export function capStateViewPackets<T extends StateViewResult>(
+export function stateViewPacketKeys<T extends StateViewResult>(
   ordered: readonly T[],
-  limit: number,
-): T[] {
-  const safeLimit =
-    typeof limit === "number" && Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : 0;
-  if (safeLimit === 0) return [];
-  if (ordered.length === 0) return [];
-
+): string[] {
   const byPred = buildSuccessorMap(ordered, []);
   // Union-find over row keys; blank-key rows become per-index singletons.
   const parent = new Map<string, string>();
@@ -344,14 +340,35 @@ export function capStateViewPackets<T extends StateViewResult>(
     const succIdx = keyToIndex.get(succKey);
     if (predIdx !== undefined && succIdx !== undefined) union(keys[predIdx]!, keys[succIdx]!);
   }
+  return keys.map((key) => root(key));
+}
+
+/**
+ * #2859 — packet-counting cap. A predecessor/successor chain admitted
+ * together is ONE complete evidence packet: it consumes a single slot of
+ * the user cap, and the slice never splits a packet at the boundary (no
+ * underfill from post-cap orphan removal). Rows keep their incoming
+ * (MMR) order; packets are ordered by first appearance. Call
+ * reconcileStateViewPairs first so orphans never consume a slot.
+ */
+export function capStateViewPackets<T extends StateViewResult>(
+  ordered: readonly T[],
+  limit: number,
+): T[] {
+  const safeLimit =
+    typeof limit === "number" && Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : 0;
+  if (safeLimit === 0) return [];
+  if (ordered.length === 0) return [];
+
+  const keys = stateViewPacketKeys(ordered);
   // Packets ordered by first appearance; admit whole packets until the cap.
   const selectedRoots = new Set<string>();
   for (let i = 0; i < ordered.length && selectedRoots.size < safeLimit; i += 1) {
-    selectedRoots.add(root(keys[i]!));
+    selectedRoots.add(keys[i]!);
   }
   const selected: T[] = [];
   for (let i = 0; i < ordered.length; i += 1) {
-    if (selectedRoots.has(root(keys[i]!))) selected.push(ordered[i]!);
+    if (selectedRoots.has(keys[i]!)) selected.push(ordered[i]!);
   }
   return selected;
 }

package/src/reconcile-identity-cache.test.ts

@@ -3,9 +3,15 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import test from "node:test";
+import * as fsp from "node:fs/promises";
 
 import { createHash } from "node:crypto";
-import { type ServerIdentityCacheEntry, planServerIdentityCacheWrite } from "./access-offline-manifest.js";
+import {
+  type ServerIdentityCacheEntry,
+  mergeServerIdentityCacheEntries,
+  planServerIdentityCacheWrite,
+  retainExcludedClassifications,
+} from "./access-offline-manifest.js";
 import { isInternalRemnicStatePath } from "./offline-sync.js";
 import { convergeIdentityCachePath } from "./reconcile/cursor.js";
 import {
@@ -375,4 +381,79 @@ test("a thrown memory-file read is not cached as a reusable negative", async ()
   assert.equal(reads, 1, "a failed read must not become a warm negative hit");
 });
 
+test("the write plan retains never-yielded excluded paths on a completed walk", () => {
+  const persisted = new Map<string, ServerIdentityCacheEntry>([
+    ["facts/gone.md", { path: "facts/gone.md", sha256: "aa" }],
+    ["facts/private.md", { path: "facts/private.md", sha256: "", statIdentity: "s", excluded: true }],
+  ]);
+  const plan = planServerIdentityCacheWrite({
+    persisted,
+    yieldedPaths: new Set([]),
+    retainedPaths: new Set(["facts/private.md"]),
+    streamCompleted: true,
+    cacheDirty: false,
+  });
+  assert.ok(plan.shouldWrite, "the vanished path still forces a write");
+  assert.deepEqual(
+    plan.entries.map((entry) => entry.path),
+    ["facts/private.md"],
+    "an excluded file's entry survives the deleted-path prune; a vanished path's does not"
+  );
+});
+
+test("excluded classifications persist for never-yielded paths without retaining unseen ones", () => {
+  const persisted = new Map<string, ServerIdentityCacheEntry>([
+    ["facts/deleted.md", { path: "facts/deleted.md", sha256: "aa" }],
+  ]);
+  const classifications = new Map([
+    ["facts/private.md", { statIdentity: "1:1:1:1:1", excluded: true }],
+    ["facts/yielded.md", { statIdentity: "2:2:2:2:2", excluded: false }],
+  ]);
+  const { retained, changed } = retainExcludedClassifications({
+    persisted,
+    classifications,
+    yieldedPaths: new Set(["facts/yielded.md"]),
+  });
+  assert.deepEqual([...retained], ["facts/private.md"]);
+  assert.equal(changed, true);
+  assert.equal(persisted.get("facts/private.md")?.excluded, true);
+  assert.equal(typeof persisted.get("facts/private.md")?.statIdentity, "string");
+  assert.ok(!retained.has("facts/deleted.md"), "a path the walk never saw must not be retained");
+});
+
+test("a concurrent server merge preserves the other writer's classification", async () => {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "server-identity-merge-"));
+  try {
+    const cachePath = path.join(dir, "identity.json");
+    await fs.promises.writeFile(
+      cachePath,
+      JSON.stringify({
+        citationTemplate: citationTemplateFingerprint(undefined),
+        files: [
+          { path: "facts/a.md", sha256: "aa", statIdentity: "1:2:3:4:5", excluded: false },
+          { path: "facts/dropped.md", sha256: "dd", statIdentity: "9:9:9:9:9", excluded: true },
+        ],
+      })
+    );
+    const merged = await mergeServerIdentityCacheEntries(
+      fsp,
+      cachePath,
+      [{ path: "facts/b.md", sha256: "bb" }],
+      undefined,
+      new Set(["facts/dropped.md"])
+    );
+    const byPath = new Map(merged.map((entry) => [entry.path, entry]));
+    assert.equal(
+      byPath.get("facts/a.md")?.statIdentity,
+      "1:2:3:4:5",
+      "the other writer's classification survives the merge"
+    );
+    assert.equal(byPath.get("facts/a.md")?.excluded, false);
+    assert.ok(byPath.has("facts/b.md"), "this writer's entry survives too");
+    assert.equal(byPath.has("facts/dropped.md"), false, "a dropped path is still not resurrected");
+  } finally {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  }
+});
+
 

package/src/search/port.ts

@@ -91,7 +91,7 @@ export interface SearchBackendStatus {
  */
 export interface SearchBackend {
   // ── Lifecycle ──
-  probe(): Promise<boolean>;
+  probe(execution?: SearchExecutionOptions): Promise<boolean>;
   /**
    * Optional non-mutating availability probe for health/readiness checks.
    * Implementations must avoid auto-upgrades, collection creation, daemon

package/src/shared-context/envelope-io.ts

@@ -29,6 +29,13 @@ export interface ComposeWriteEnvelopeInput {
   supersedes?: string;
   /** Config opt-in (`sharedContextAllowBindingAuthority`). Binding throws without it. */
   allowBinding: boolean;
+  /**
+   * Write instant for the expiry TTL policy (issue #2920). When finite, an
+   * `expiresAt` must land strictly after it and within the maximum TTL —
+   * a past or effectively-immortal expiry is a client input error, never a
+   * silently accepted stamp.
+   */
+  nowMs?: number;
 }
 
 function requireEnvelopeActor(agentId: string): string {
@@ -48,6 +55,21 @@ function optionalEnvelopeAt(expiresAt: string | undefined): string | undefined {
   return parsed.at;
 }
 
+/** Maximum write-side TTL: 10 years. A farther `expiresAt` is rejected. */
+export const MAX_WRITE_EXPIRES_AT_TTL_MS = 3650 * 24 * 60 * 60 * 1000;
+
+function assertBoundedFutureExpiry(expiresAt: string, nowMs: number): void {
+  const expiresAtMs = Date.parse(expiresAt);
+  if (expiresAtMs <= nowMs) {
+    throw new Error("composeWriteEnvelope: expiresAt must be an instant strictly after the write time");
+  }
+  if (expiresAtMs - nowMs > MAX_WRITE_EXPIRES_AT_TTL_MS) {
+    throw new Error(
+      `composeWriteEnvelope: expiresAt exceeds the maximum TTL of ${MAX_WRITE_EXPIRES_AT_TTL_MS}ms`,
+    );
+  }
+}
+
 function optionalEnvelopeId(supersedes: string | undefined): string | undefined {
   if (supersedes === undefined) return undefined;
   const parsed = parseEnvelopeId(supersedes);
@@ -137,6 +159,9 @@ function requireProducer(value: string): string {
 export function composeWriteEnvelope(input: ComposeWriteEnvelopeInput): SharedEnvelope {
   const sharedBy = requireEnvelopeActor(input.origin);
   const expiresAt = optionalEnvelopeAt(input.expiresAt);
+  if (expiresAt !== undefined && Number.isFinite(input.nowMs ?? Number.NaN)) {
+    assertBoundedFutureExpiry(expiresAt, input.nowMs as number);
+  }
   const supersedes = optionalEnvelopeId(input.supersedes);
   return applyDefaultEnvelope(
     { sharedBy, authority: input.authority, expiresAt, supersedes },

package/src/shared-context/envelope-wiring.test.ts

@@ -36,12 +36,14 @@ test("authority envelope round-trips write -> cross-signals -> curation", async
   const { manager, dir } = await makeManager();
   t.after(() => rm(dir, { recursive: true, force: true }));
 
+  // Within the write TTL policy (issue #2920): strictly future, ≤10 years.
+  const expiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
   const fp = await manager.writeAgentOutput({
     agentId: "agent-alpha",
     title: "Deploy checklist",
     content: "Verified the deploy checklist end to end.",
     authority: "advisory",
-    expiresAt: "2099-01-01T00:00:00.000Z",
+    expiresAt,
     supersedes: "out-0001",
   });
 
@@ -49,7 +51,7 @@ test("authority envelope round-trips write -> cross-signals -> curation", async
   assert.match(raw, /^kind: agent_output$/m);
   assert.match(raw, /^sharedBy: "agent-alpha"$/m);
   assert.match(raw, /^authority: "advisory"$/m);
-  assert.match(raw, /^expiresAt: "2099-01-01T00:00:00\.000Z"$/m);
+  assert.ok(raw.includes(`expiresAt: ${JSON.stringify(expiresAt)}`));
   assert.match(raw, /^supersedes: "out-0001"$/m);
 
   const signals = await manager.synthesizeCrossSignals({ date: today() });

package/src/shared-context/manager.ts

@@ -605,6 +605,7 @@ export class SharedContextManager {
       expiresAt: opts.expiresAt,
       supersedes: opts.supersedes,
       allowBinding: this.allowBindingAuthority,
+      nowMs: createdAt.getTime(),
     });
 
     const dir = path.join(this.outputsDir, agentPathSegment, date);

package/src/shared-context/write-output-controls.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Regression: governed write-output envelope controls exposed on BOTH
+ * documented surfaces (issue #2920).
+ *
+ * Covers the canonical client-input parse, the Access MCP operation
+ * (`shared_context_write_output` via the real operation registry), and the
+ * access-service adapter against the REAL manager write path:
+ * - authority: finite allow-list, binding gated by config
+ * - expiresAt: strict ISO, strictly future, bounded by the 10-year TTL
+ * - supersedes: validated id shape
+ * - client `principal`/`namespace` overrides are rejected
+ * - no idempotent replay/dedup semantics on this surface (two identical
+ *   calls write two files — nothing silently swallows a re-send)
+ *
+ * All fixtures are synthetic — no real user data.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+
+import "../access-operations.js";
+import { getOperation } from "../access-boundary.js";
+import { EngramAccessInputError, EngramAccessService, type EngramAccessService as Service } from "../access-service.js";
+import type { Orchestrator } from "../orchestrator.js";
+import { SharedContextManager } from "./manager.js";
+import { MAX_WRITE_EXPIRES_AT_TTL_MS } from "./envelope-io.js";
+import { parseSharedWriteOutputControls } from "./write-output-controls.js";
+import { parseConfig } from "../config.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+async function makeService(overrides: Record<string, unknown> = {}) {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-shared-controls-"));
+  const config = parseConfig({ sharedContextEnabled: true, sharedContextDir: dir, memoryDir: dir, ...overrides });
+  const manager = new SharedContextManager(config);
+  await manager.ensureStructure();
+  const service = new EngramAccessService({ config, sharedContext: manager } as unknown as Orchestrator);
+  return { service, manager, dir, config };
+}
+
+test("parse: controls are strings-or-absent; empty or non-string values reject", () => {
+  assert.deepEqual(parseSharedWriteOutputControls({}), {});
+  assert.deepEqual(parseSharedWriteOutputControls(undefined), {});
+  assert.deepEqual(parseSharedWriteOutputControls(null), {});
+  assert.deepEqual(
+    parseSharedWriteOutputControls({ authority: "advisory", expiresAt: "2030-01-01T00:00:00Z", supersedes: "out-1" }),
+    { authority: "advisory", expiresAt: "2030-01-01T00:00:00Z", supersedes: "out-1" },
+  );
+  assert.throws(() => parseSharedWriteOutputControls({ authority: 7 }), /authority must be a string/);
+  assert.throws(() => parseSharedWriteOutputControls({ expiresAt: "" }), /expiresAt must be a non-empty string/);
+  assert.throws(() => parseSharedWriteOutputControls({ supersedes: "  " }), /supersedes must be a non-empty string/);
+});
+
+test("parse: client principal/namespace overrides are rejected", () => {
+  assert.throws(
+    () => parseSharedWriteOutputControls({ principal: "attacker" }),
+    /principal is server-resolved and cannot be supplied by the caller/,
+  );
+  assert.throws(
+    () => parseSharedWriteOutputControls({ namespace: "victim-ns" }),
+    /namespace is server-resolved and cannot be supplied by the caller/,
+  );
+  // Absent keys (and stripped nulls) pass through untouched.
+  assert.deepEqual(parseSharedWriteOutputControls({ sessionKey: "ctx" }), {});
+});
+
+test("operation: forwards the envelope controls with the authenticated principal", async () => {
+  let received: Record<string, unknown> | undefined;
+  const service = {
+    sharedContextWriteOutput: async (request: Record<string, unknown>) => {
+      received = request;
+      return { written: true, path: "written.md" };
+    },
+  } as unknown as Service;
+  const operation = getOperation("shared_context_write_output");
+  assert.ok(operation);
+
+  await operation.run(
+    { agentId: "agent", title: "t", content: "c", authority: "advisory", expiresAt: "2030-01-01T00:00:00Z", supersedes: "out-1" },
+    { service, authenticatedPrincipal: "real-principal" },
+  );
+  assert.equal(received?.authority, "advisory");
+  assert.equal(received?.expiresAt, "2030-01-01T00:00:00Z");
+  assert.equal(received?.supersedes, "out-1");
+  assert.equal(received?.principal, "real-principal");
+});
+
+test("operation: client principal/namespace and malformed controls are input errors", async () => {
+  const service = {
+    sharedContextWriteOutput: async () => ({ written: true, path: "x" }),
+  } as unknown as Service;
+  const operation = getOperation("shared_context_write_output");
+  assert.ok(operation);
+
+  for (const payload of [
+    { agentId: "a", title: "t", content: "c", principal: "spoofed" },
+    { agentId: "a", title: "t", content: "c", namespace: "other" },
+    { agentId: "a", title: "t", content: "c", authority: "" },
+    { agentId: "a", title: "t", content: "c", expiresAt: 42 },
+  ]) {
+    await assert.rejects(
+      () => operation.run(payload, { service, authenticatedPrincipal: "real-principal" }),
+      (error: unknown) => error instanceof EngramAccessInputError,
+      `must reject ${JSON.stringify(payload)}`,
+    );
+  }
+});
+
+test("service: controls stamp the envelope; absent controls stay informational", async (t) => {
+  const { service, dir } = await makeService();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+
+  const expiresAt = new Date(Date.now() + 90 * DAY_MS).toISOString();
+  const result = (await service.sharedContextWriteOutput({
+    agentId: "agent-alpha",
+    title: "Plan",
+    content: "x",
+    authority: "advisory",
+    expiresAt,
+    supersedes: "out-0001",
+  })) as { written: boolean; path: string };
+  const raw = await readFile(result.path, "utf-8");
+  assert.match(raw, /^authority: "advisory"$/m);
+  assert.ok(raw.includes(`expiresAt: ${JSON.stringify(expiresAt)}`));
+  assert.match(raw, /^supersedes: "out-0001"$/m);
+
+  const plain = (await service.sharedContextWriteOutput({ agentId: "agent-alpha", title: "Plain", content: "x" })) as {
+    written: boolean;
+    path: string;
+  };
+  const plainRaw = await readFile(plain.path, "utf-8");
+  assert.match(plainRaw, /^authority: "informational"$/m);
+});
+
+test("service: binding requires the operator opt-in, else is a client input error", async (t) => {
+  const gated = await makeService();
+  t.after(() => rm(gated.dir, { recursive: true, force: true }));
+  await assert.rejects(
+    () =>
+      gated.service.sharedContextWriteOutput({ agentId: "agent-alpha", title: "Directive", content: "x", authority: "binding" }),
+    (error: unknown) => error instanceof EngramAccessInputError && /requires an explicit binding flag/.test(error.message),
+  );
+
+  const open = await makeService({ sharedContextAllowBindingAuthority: true });
+  t.after(() => rm(open.dir, { recursive: true, force: true }));
+  const result = (await open.service.sharedContextWriteOutput({
+    agentId: "agent-alpha",
+    title: "Directive",
+    content: "x",
+    authority: "binding",
+  })) as { path: string };
+  assert.match(await readFile(result.path, "utf-8"), /^authority: "binding"$/m);
+});
+
+test("service: expiresAt must be strictly future and within the 10-year TTL", async (t) => {
+  const { service, dir } = await makeService();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+
+  const cases: Array<{ expiresAt: string; message: string }> = [
+    { expiresAt: new Date(Date.now() - DAY_MS).toISOString(), message: "strictly after the write time" },
+    { expiresAt: new Date(Date.now() + MAX_WRITE_EXPIRES_AT_TTL_MS + DAY_MS).toISOString(), message: "maximum TTL" },
+    { expiresAt: "2030-02-31T00:00:00Z", message: "valid ISO-8601 timestamp" },
+  ];
+  for (const { expiresAt, message } of cases) {
+    await assert.rejects(
+      () => service.sharedContextWriteOutput({ agentId: "agent-alpha", title: "Expiry", content: "x", expiresAt }),
+      (error: unknown) => error instanceof EngramAccessInputError && error.message.includes(message),
+      `must reject expiresAt=${expiresAt}`,
+    );
+  }
+});
+
+test("service: supersedes must be a non-blank single-line id", async (t) => {
+  const { service, dir } = await makeService();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+  await assert.rejects(
+    () => service.sharedContextWriteOutput({ agentId: "agent-alpha", title: "Supersede", content: "x", supersedes: "out-1\nout-2" }),
+    (error: unknown) => error instanceof EngramAccessInputError && /supersedes/.test(error.message),
+  );
+});
+
+test("service: no idempotent replay — an identical re-send writes a second file", async (t) => {
+  const { service, dir } = await makeService();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+  const base = { agentId: "agent-alpha", title: "Same", content: "same bytes" };
+  const first = (await service.sharedContextWriteOutput(base)) as { path: string };
+  const second = (await service.sharedContextWriteOutput(base)) as { path: string };
+  assert.notEqual(first.path, second.path, "this surface has no replay/dedup semantics; a re-send must not be swallowed");
+});

package/src/shared-context/write-output-controls.ts

@@ -0,0 +1,72 @@
+/**
+ * Canonical client-input parse for shared-context write-output envelope
+ * controls (issue #2920).
+ *
+ * One module feeds BOTH documented surfaces — the Access MCP
+ * `shared_context_write_output` operation and the OpenClaw
+ * `shared_context_write_output` tool — so surface policy can never drift.
+ * This layer owns only what is a SURFACE concern: field type/shape and the
+ * rejection of client-supplied identity. Semantic validation (authority
+ * allow-list, the binding gate, strict ISO instants, the future/TTL expiry
+ * policy, id shape) stays in `composeWriteEnvelope`, the single write-side
+ * gate every path already routes through — there is no in-process bypass
+ * with looser rules than the tool surfaces.
+ */
+
+export interface SharedWriteOutputControls {
+  authority?: string;
+  expiresAt?: string;
+  supersedes?: string;
+}
+
+const CONTROL_FIELDS = ["authority", "expiresAt", "supersedes"] as const;
+
+/** Server-resolved fields a caller must never supply (issue #2920). */
+const SERVER_RESOLVED_FIELDS = ["principal", "namespace"] as const;
+
+/**
+ * Parse the optional envelope controls off a raw client request.
+ *
+ * - Absent fields are omitted; a control must be a non-blank string when
+ *   present (an explicit empty string is a client error, not "unspecified").
+ * - A client-supplied `principal` or `namespace` is rejected: identity and
+ *   scoping are resolved by the surface, never accepted from the caller.
+ *
+ * Throws `Error` with a `shared-context write output:` prefix; access
+ * surfaces map that to their input-error class.
+ */
+export function parseSharedWriteOutputControls(raw: unknown): SharedWriteOutputControls {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const record = raw as Record<string, unknown>;
+  for (const field of SERVER_RESOLVED_FIELDS) {
+    if (Object.hasOwn(record, field) && record[field] !== undefined) {
+      throw new Error(
+        `shared-context write output: ${field} is server-resolved and cannot be supplied by the caller`,
+      );
+    }
+  }
+  const controls: SharedWriteOutputControls = {};
+  for (const field of CONTROL_FIELDS) {
+    const value = record[field];
+    if (value === undefined) continue;
+    if (typeof value !== "string") {
+      throw new Error(`shared-context write output: ${field} must be a string`);
+    }
+    if (value.trim().length === 0) {
+      throw new Error(`shared-context write output: ${field} must be a non-empty string`);
+    }
+    controls[field] = value;
+  }
+  return controls;
+}
+
+const WRITE_INPUT_PREFIXES = [
+  "shared-context write origin mismatch",
+  "applyDefaultEnvelope:",
+  "composeWriteEnvelope:",
+  "shared-context write output:",
+] as const;
+
+export function isSharedContextWriteInputError(message: string): boolean {
+  return WRITE_INPUT_PREFIXES.some((prefix) => message.startsWith(prefix));
+}

package/src/source-attribution.test.ts

@@ -9,6 +9,9 @@ import { ContentHashIndex, StorageManager } from "./storage.js";
 import {
   DEFAULT_CITATION_FORMAT,
   attachCitation,
+  citationTemplateIsDetectable,
+  citationTemplatesForMerge,
+  citationTemplatesToRecognize,
   deriveSessionId,
   formatCitation,
   hasCitation,
@@ -17,6 +20,7 @@ import {
   parseCitation,
   stripCitation,
   stripCitationForTemplate,
+  stripRecognizedCitations,
 } from "./source-attribution.js";
 
 test("formatCitation emits the default template with provided fields", () => {
@@ -171,6 +175,7 @@ test("parseConfig disables inline source attribution by default", () => {
     cfg.inlineSourceAttributionFormat,
     "[Source: agent={agent}, session={sessionId}, ts={ts}]",
   );
+  assert.deepEqual(cfg.inlineSourceAttributionFormatHistory, []);
 });
 
 test("parseConfig honors explicit inline source attribution overrides", () => {
@@ -196,6 +201,22 @@ test("parseConfig falls back to default format when override is empty", () => {
   );
 });
 
+test("parseConfig keeps inlineSourceAttributionFormatHistory when format is normalized", () => {
+  const prior = "[src:{agent}/{sessionId}@{date}]";
+  const current = "[via:{agent}]";
+  const cfg = parseConfig({
+    inlineSourceAttributionFormat: "   ",
+    inlineSourceAttributionFormatHistory: [prior, "", 12, "  ", current],
+  });
+  assert.equal(cfg.inlineSourceAttributionFormat, DEFAULT_CITATION_FORMAT);
+  assert.deepEqual(cfg.inlineSourceAttributionFormatHistory, [prior, current]);
+  assert.deepEqual(citationTemplatesForMerge(cfg), [
+    DEFAULT_CITATION_FORMAT,
+    prior,
+    current,
+  ]);
+});
+
 // ── Finding 1 regression: custom citation template dedup detection ────────────
 
 test("hasCitationForTemplate detects default [Source:...] marker regardless of template", () => {
@@ -539,6 +560,24 @@ test("hasCitationForTemplate: '{agent}{sessionId}' all-placeholder template retu
   );
 });
 
+test("citationTemplateIsDetectable rejects all-placeholder templates", () => {
+  assert.equal(citationTemplateIsDetectable("{agent}{sessionId}"), false);
+  assert.equal(citationTemplateIsDetectable(DEFAULT_CITATION_FORMAT), true);
+  assert.equal(citationTemplateIsDetectable("[src:{agent}/{sessionId}@{date}]"), true);
+});
+
+test("citationTemplatesToRecognize drops undetectable shapes and keeps prior history", () => {
+  const prior = "[src:{agent}/{sessionId}@{date}]";
+  const recognized = citationTemplatesToRecognize("{agent}{sessionId}", [prior]);
+  assert.deepEqual(recognized, [DEFAULT_CITATION_FORMAT, prior]);
+  const body = "The cadence is weekly. [src:agent-a/s-old@2026-08-19]";
+  assert.equal(stripRecognizedCitations(body, recognized), "The cadence is weekly.");
+  assert.deepEqual(citationTemplatesForMerge({ inlineSourceAttributionFormat: prior }), [
+    DEFAULT_CITATION_FORMAT,
+    prior,
+  ]);
+});
+
 test("formatCitation: substituted values containing placeholder syntax are not re-interpreted", () => {
   // Regression for PR #401 (low-severity): the previous implementation chained
   // `.replace(/\{agent\}/g, ...)`, `.replace(/\{ts\}/g, ...)` etc. If the agent