@decidio/sdk 0.6.4 → 0.8.0

package/dist/adapters/langgraph.js

@@ -1,19 +1,70 @@
 import { interrupt, Command } from "@langchain/langgraph";
-import { DecidioBlockedError } from "../index.js";
-import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict, checkEngineVersion } from "./_gate.js";
+import * as langgraph from "@langchain/langgraph";
+import { DecidioBlockedError, approvalRefusal, bindingMaterial, requestCommitment, idempotencyKey, decisionIdProblem } from "../index.js";
+import { gateAuthorize, gateConfirm, gateCheckApproval, adapterRequest, checkEngineVersion } from "./_gate.js";
+const gatesOpened = new WeakMap();
+function runIdentity() {
+    let conf;
+    try {
+        const getConfig = langgraph.getConfig;
+        conf = typeof getConfig === "function" ? getConfig()?.configurable : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const thread = conf?.["thread_id"], ns = conf?.["checkpoint_ns"];
+    if ((typeof thread !== "string" && typeof thread !== "number") || String(thread) === "")
+        return undefined;
+    if (typeof ns !== "string" || ns === "")
+        return undefined;
+    const scratch = conf?.["__pregel_scratchpad"];
+    if (!scratch || typeof scratch !== "object")
+        return undefined;
+    const call = gatesOpened.get(scratch) ?? 0;
+    gatesOpened.set(scratch, call + 1);
+    return { thread: String(thread), ns, call };
+}
 export async function decidioGate(config, ctx, run, opts) {
-    const auth = await gateAuthorize(config, ctx);
+    const material = bindingMaterial(config);
+    if (!material) {
+        throw new Error("[decidio] the LangGraph adapter binds a routed approval to the exact request with a key only this agent holds, and none is configured - set DECIDIO_AGENT_KEY + DECIDIO_AGENT_DID (npx @decidio/sdk init) or DECIDIO_API_TOKEN. Nothing was routed or executed.");
+    }
+    const request = adapterRequest(ctx);
+    const self = runIdentity();
+    const key = self ? idempotencyKey(material, { thread: self.thread, ns: self.ns, call: self.call, commitment: requestCommitment(material, request) }) : undefined;
+    const auth = await gateAuthorize(config, ctx, key ? { idempotencyKey: key } : {});
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
-        const resumed = interrupt({ decidio: { decisionId: auth.decisionId, action: ctx.action, amount: ctx.amount, scope: ctx.scope } });
-        assertVerdict(verdictFrom(resumed), auth.decisionId, resumed?.reason);
+        if (!self) {
+            throw new DecidioBlockedError(`this LangGraph run exposes no thread/task identity (a checkpointer with a thread_id, @langchain/langgraph's getConfig() and the node execution's scratchpad are required), so a resumed node could not recognise decision ${auth.decisionId} as its own. Nothing was executed; ${auth.decisionId} is pending in Decidio - reject it (npx @decidio/sdk approvals reject ${auth.decisionId}).`, auth.decisionId);
+        }
+        const payload = { decidio: { decisionId: auth.decisionId, action: ctx.action, amount: ctx.amount, scope: ctx.scope } };
+        let resumed = interrupt(payload);
+        for (;;) {
+            const named = resumed && typeof resumed === "object" ? resumed.decisionId : undefined;
+            if (typeof named !== "string" || named === "") {
+                throw new DecidioBlockedError(`the LangGraph resume value names no decision (${JSON.stringify(resumed ?? null).slice(0, 120)}) - refusing to execute. Build it with decidioResumeCommand(webhookBody), which carries the decisionId: an approval that does not say which decision it approves cannot be applied to this one.`, auth.decisionId);
+            }
+            if (named === auth.decisionId) {
+                const check = await gateCheckApproval(config, auth.decisionId, ctx);
+                if (check.ok)
+                    break;
+                if (check.code !== "pending")
+                    throw approvalRefusal(check);
+            }
+            resumed = interrupt(payload);
+        }
     }
     const result = await run();
     const confirmation = await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     return { value: result, decisionId: auth.decisionId, confirmation };
 }
 export function decidioResumeCommand(body) {
-    return new Command({ resume: { verdict: body.verdict, reason: body.reason } });
+    const decisionId = body?.decisionId;
+    const problem = decisionIdProblem(decisionId);
+    if (problem)
+        throw new Error(`[decidio] decidioResumeCommand needs the webhook's decisionId (${problem}) - the node refuses a resume that does not say which decision it approves. Pass the webhook body verbatim.`);
+    return new Command({ resume: { decisionId, verdict: body.verdict, reason: body.reason } });
 }
 checkEngineVersion("langgraph");

package/dist/adapters/openai.d.ts

@@ -16,10 +16,27 @@ interface RunStateLike {
  *
  * const state = result.state;                       // or RunState from the run
  * const { resolved, pending } = await authorizeInterruptions(config, state, describe);
- * if (pending.length) { await store.put(decisionId, state.toString()); return; }  // suspend
+ * if (pending.length) {                             // suspend: park the state + each {callId, decisionId}
+ *   await store.put(runId, { state: state.toString(), pending: pending.map(({ callId, decisionId }) => ({ callId, decisionId })) });
+ *   return;
+ * }
  * result = await run(agent, state);                 // all resolved → resume
- * // on Decidio approval webhook: state = await RunState.fromString(agent, parked);
- * //   applyResume(state, item, verdict); result = await run(agent, state);
+ * // on Decidio's webhook (a wake-up): restore, find EACH parked call in the restored state by its call id,
+ * // and let Decidio decide it:
+ * //   const parked = await store.get(runId); const state = await RunState.fromString(agent, parked.state);
+ * //   for (const { callId, decisionId } of parked.pending) {
+ * //     const item = state.getInterruptions().find((i) => i.rawItem?.callId === callId);
+ * //     await applyVerifiedResume(config, state, item, decisionId, describe);
+ * //   }
+ * //   result = await run(agent, state);
+ *
+ * THE BINDING IS THE TOOL CALL (#4B review W2): a routed approval is bound to the described context AND
+ * the call itself - its name, call id and exact argument string (toolCallRequest). An item edited after
+ * approval, or a second identical call (another call id), never rides the approval.
+ *
+ * KNOWN LIMIT (predates 0.7.0): this door has no single-execution claim. The RunState is the host's own
+ * storage, so two concurrent resumes of the same parked state can both apply the approval and both run
+ * the tool; serialize resumes per run on your side (one worker per run id, or a lock).
  *
  * Duck-typed on the state/item (no hard @openai/agents import) so it stays thin.
  *
@@ -30,9 +47,12 @@ export interface Resolved {
     verdict: "approved" | "blocked";
     decisionId: string;
 }
+/** `callId` (0.7.0) is the tool call the approval is bound to - find the item again by it after
+ *  RunState.fromString. */
 export interface Pending {
     item: ToolApprovalItem;
     decisionId: string;
+    callId: string;
 }
 /** THIS DOOR AUTHORIZES; IT DOES NOT CONFIRM. Named `gateInterruptions` it looked like the other
  *  `decidioGate*` functions, which all run the action and report what happened. This one cannot:
@@ -42,7 +62,7 @@ export interface Pending {
  *  and a failed confirmation must not look alike.
  *
  *  proceed → state.approve(item); block → state.reject(item); route → pending (a human decides via
- *  Decidio; the host parks state.toString() + resumes via applyResume). */
+ *  Decidio; the host parks state.toString() + resumes via applyVerifiedResume). */
 export declare function authorizeInterruptions(config: GuardConfig, state: RunStateLike, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<{
     resolved: Resolved[];
     pending: Pending[];
@@ -51,11 +71,21 @@ export declare function authorizeInterruptions(config: GuardConfig, state: RunSt
 /** @deprecated Renamed to `authorizeInterruptions` in 0.3.0 — the old name read like the other
  *  `decidioGate*` doors, which execute and confirm. This one only ever authorized. */
 export declare const gateInterruptions: typeof authorizeInterruptions;
-/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString).
+/** Apply Decidio's answer for one routed tool call to a resumed RunState (after RunState.fromString)
+ *  - VERIFIED (0.7.0). It asks Decidio: GET /agent/status/:decisionId, and the approval must be bound
+ *  to THIS tool call - the commitment Decidio holds is recomputed over the call's name, call id and exact
+ *  argument string plus `describe(item)` (toolCallRequest), the same binding the call was authorized
+ *  with. A parked RunState is the host's own storage: an item whose arguments were edited there after a
+ *  human approved, or another call handed this call's decision id, must not ride that approval.
+ *
+ *  Approved and bound → state.approve(item), returns "approved". Rejected/blocked by Decidio →
+ *  state.reject(item), returns that verdict. Still pending, or approved for a DIFFERENT request, or not
+ *  tied to one → throws the typed refusal and the RunState is NOT modified.
  *
- *  VALIDATES BEFORE MUTATING. `else state.reject(item)` treated every unrecognised string as a
- *  rejection, so a garbled payload, a version-skew verdict or an empty string became a rejection
- *  that a caller could not tell apart from a human deciding no — and the RunState was already
- *  mutated by the time anyone could look. The recognised set is exactly the one `resume` uses. */
-export declare function applyResume(state: RunStateLike, item: ToolApprovalItem, verdict: string): void;
+ *  REPLACES `applyResume(state, item, verdict)`, REMOVED in 0.7.0. It applied a bare verdict string
+ *  with no decision attached, so correctness depended entirely on the host routing the right verdict
+ *  to the right item. It was removed rather than deprecated: a deprecated function that still approves
+ *  keeps the hole open for every integration that never reads the warning, and one that refused
+ *  approvals at runtime would fail AFTER a human approved - the removal fails at build time instead. */
+export declare function applyVerifiedResume(config: GuardConfig, state: RunStateLike, item: ToolApprovalItem, decisionId: string, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<"approved" | "rejected" | "blocked">;
 export {};

package/dist/adapters/openai.js

@@ -1,10 +1,11 @@
-import { gateAuthorize, checkEngineVersion } from "./_gate.js";
-import { DecidioBlockedError } from "../index.js";
+import { gateAuthorize, gateCheckApproval, toolCallRequest, checkEngineVersion } from "./_gate.js";
+import { DecidioBlockedError, approvalRefusal, decisionIdProblem } from "../index.js";
 export async function authorizeInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
-    for (const item of state.getInterruptions()) {
-        const auth = await gateAuthorize(config, describe(item));
+    const batch = state.getInterruptions().map((item) => { const ctx = describe(item); return { item, ctx, request: toolCallRequest(item, ctx) }; });
+    for (const { item, ctx, request } of batch) {
+        const auth = await gateAuthorize(config, ctx, { request });
         if (auth.decision === "proceed") {
             state.approve(item);
             resolved.push({ item, verdict: "approved", decisionId: auth.decisionId });
@@ -14,22 +15,29 @@ export async function authorizeInterruptions(config, state, describe) {
             resolved.push({ item, verdict: "blocked", decisionId: auth.decisionId });
         }
         else if (auth.decision === "route")
-            pending.push({ item, decisionId: auth.decisionId });
+            pending.push({ item, decisionId: auth.decisionId, callId: request.args[0].callId });
         else
             throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)}`, auth.decisionId);
     }
     return { resolved, pending, confirmationSupported: false };
 }
 export const gateInterruptions = authorizeInterruptions;
-export function applyResume(state, item, verdict) {
-    if (verdict === "approved" || verdict === "auto_approved") {
+export async function applyVerifiedResume(config, state, item, decisionId, describe) {
+    const idProblem = decisionIdProblem(decisionId);
+    if (idProblem)
+        throw new DecidioBlockedError(`applyVerifiedResume needs the decision this item was routed as (${idProblem}) - pass the decisionId authorizeInterruptions returned for it. The RunState was NOT modified.`, typeof decisionId === "string" ? decisionId : "");
+    const ctx = describe(item);
+    const check = await gateCheckApproval(config, decisionId, ctx, toolCallRequest(item, ctx));
+    if (check.ok) {
         state.approve(item);
-        return;
+        return "approved";
     }
-    if (verdict === "rejected" || verdict === "blocked") {
+    if (check.code === "rejected" || check.code === "blocked") {
         state.reject(item);
-        return;
+        return check.code;
     }
-    throw new DecidioBlockedError(`unrecognised resume verdict ${JSON.stringify(verdict)} — refusing to apply it. This SDK understands approved / auto_approved / rejected / blocked; anything else is a version skew, and guessing would turn "I do not understand" into a decision. The RunState was NOT modified.`, "");
+    const refusal = approvalRefusal(check);
+    refusal.message += " The RunState was NOT modified.";
+    throw refusal;
 }
 checkEngineVersion("openai");

package/dist/adapters/temporal.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome, type ApprovalCheck } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 /**
  * @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
@@ -9,20 +9,39 @@ import { type GateAuth } from "./_gate.js";
  * const verdicts = installDecidioSignal();                 // wires the resume signal
  * const out = await decidioGate(config, ctx, () => createOpp(o), verdicts, {
  * authorize: () => executeActivity(authorizeActivity, ...),   // HTTP belongs in activities
+ * verify:    (id) => executeActivity(verifyActivity, id),      // body: return verifyApprovalActivity(config, id, ctx)
  * confirm:   (id, r) => executeActivity(confirmActivity, ...),
  * });
  * Decidio's webhook bridges to: handle.signal(decidioResumeSignal, decisionId, verdict, reason)
  *
+ * THE SIGNAL IS A WAKE-UP (0.7.0). Before 0.7.0 the action ran on the signal alone, so anyone who could
+ * signal the workflow with the decisionId approved it. Now the signal only wakes the workflow; `verify`
+ * then confirms with Decidio that THIS request was approved (GET /agent/status + the request
+ * commitment) before `run()`. Still pending → keep waiting for the next signal; rejected/blocked/changed
+ * → the typed refusal. `verify` is HTTP, so it must be an ACTIVITY, never workflow code (determinism) -
+ * and it is required whenever `authorize` is.
+ *
  * (This wiring doc ships in the .d.ts — the README points here.)
  */
 export declare const decidioResumeSignal: import("@temporalio/workflow").SignalDefinition<[string, string, (string | undefined)?]>;
-/** Call inside the workflow to wire the resume signal; returns the verdict store. */
+/** Call inside the workflow to wire the resume signal; returns the signal store. Since 0.7.0 an entry is
+ *  a WAKE-UP for its decision - the verdict it carries is informational and is consumed when the gate
+ *  checks the approval with Decidio. */
 export declare function installDecidioSignal(): Map<string, {
     verdict: string;
     reason?: string;
 }>;
+/** The approval check as an ACTIVITY body (0.7.0) - register an activity that returns this, unchanged,
+ *  and route `verify` through it. GET /agent/status + the request commitment recomputed over `ctx`, which
+ *  must be the same context the gate authorized. Never call it from workflow code (it is HTTP). */
+export declare function verifyApprovalActivity(config: GuardConfig, decisionId: string, ctx: ApprovalContext): Promise<ApprovalCheck>;
 export interface DecidioGateOpts<R = unknown> {
     authorize?: () => Promise<GateAuth>;
+    /** THE APPROVAL CHECK, run after the resume signal and before `run()` (0.7.0). It is HTTP, so route it
+     *  through an ACTIVITY whose body is `return verifyApprovalActivity(config, decisionId, ctx)` - the same
+     *  `ctx` this gate authorized - and return that value unchanged. Required whenever `authorize` is
+     *  supplied; without either it defaults to a direct call (tests only - a workflow must not do I/O). */
+    verify?: (decisionId: string) => Promise<ApprovalCheck>;
     /** Reports through YOUR activity. Return the gate's confirm response body (validated with
      *  `readConfirmResponse`) and it becomes the outcome; return nothing and the outcome says the SDK could
      *  not read back what Decidio recorded (prodsec V035-03: a returned outcome used to be discarded). */

package/dist/adapters/temporal.js

@@ -1,21 +1,34 @@
 import { condition, defineSignal, setHandler } from "@temporalio/workflow";
-import { DecidioBlockedError } from "../index.js";
-import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict, checkEngineVersion, assertAuthorizeVerdict } from "./_gate.js";
+import { DecidioBlockedError, approvalRefusal } from "../index.js";
+import { gateAuthorize, gateConfirm, gateCheckApproval, assertApprovalCheckShape, checkEngineVersion, assertAuthorizeVerdict } from "./_gate.js";
 export const decidioResumeSignal = defineSignal("decidioResume");
 export function installDecidioSignal() {
     const verdicts = new Map();
     setHandler(decidioResumeSignal, (decisionId, verdict, reason) => { verdicts.set(decisionId, { verdict, reason }); });
     return verdicts;
 }
+export function verifyApprovalActivity(config, decisionId, ctx) {
+    return gateCheckApproval(config, decisionId, ctx);
+}
 let confirmWarned = false;
 export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
+    if (opts.authorize && !opts.verify) {
+        throw new Error("[decidio] temporal: `authorize` runs in your activity, so the approval check must too - pass `verify: (decisionId) => executeActivity(verifyActivity, decisionId)`, where the activity returns verifyApprovalActivity(config, decisionId, ctx) (from @decidio/sdk/temporal) unchanged. Since 0.7.0 a resume signal only wakes the workflow; the approval is confirmed with Decidio before your action runs. Nothing was routed or executed.");
+    }
     const auth = assertAuthorizeVerdict(await (opts.authorize ?? (() => gateAuthorize(config, ctx)))(), "unknown");
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
-        await condition(() => verdicts.has(auth.decisionId));
-        const v = verdicts.get(auth.decisionId);
-        assertVerdict(verdictFrom(v), auth.decisionId, v.reason);
+        const verify = opts.verify ?? ((decisionId) => gateCheckApproval(config, decisionId, ctx));
+        for (;;) {
+            await condition(() => verdicts.has(auth.decisionId));
+            verdicts.delete(auth.decisionId);
+            const check = assertApprovalCheckShape(await verify(auth.decisionId), auth.decisionId);
+            if (check.ok)
+                break;
+            if (check.code !== "pending")
+                throw approvalRefusal(check);
+        }
     }
     else if (auth.decision !== "proceed") {
         throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)} — refusing to execute`, auth.decisionId);

package/dist/cli.d.ts

@@ -1,6 +1,15 @@
 #!/usr/bin/env node
 export type ApprovalAnswer = "approve" | "reject" | "again";
 export declare function approvalAnswer(answer: unknown): ApprovalAnswer;
+/** The issuer store's key for a Decidio address: its origin (scheme + lowercased host + non-default port), computed by a
+ *  RESTRICTED parser that FAILS CLOSED, identically in both SDKs. It deliberately does NOT reproduce the browser URL's
+ *  canonicalisation: `new URL("https://%64ecidio-api.onrender.com").origin` is the real host, and keying by that let a
+ *  planted store entry under a percent-encoded / IDN / numeric-shorthand / backslash spelling be silently trusted AS the
+ *  real host (the Python twin, on urlsplit, never decoded these, so the two SDKs also disagreed). Now: only a bare
+ *  http(s)://, an ASCII-label host or a bracketed real IP literal is keyed as an origin; anything the parser is not sure
+ *  it can canonicalise the same in both languages is keyed as its trimmed lowercased self, which cannot equal a real
+ *  origin and so is never mistaken for one. Exported for the smokes; the Python twin _issuer_store_key answers the same. */
+export declare function issuerStoreKey(url: string): string;
 /** The agent id `init` uses when none is given: this folder's name (or the package name), slugified. "my-agent" told a
  *  tester nothing; the folder they are in is the agent they are building (founder ruling 2026-09-06). */
 export declare function defaultAgentId(dir?: string): string;
@@ -8,3 +17,53 @@ export declare function defaultAgentId(dir?: string): string;
  *  distinct decision ids can never share a file (first-run review of 0.4.1: dots were STRIPPED, `a.b` and `ab`
  *  collided). `~` is outside the allowed set, so the escape is unambiguous. Exported for the smokes. */
 export declare function receiptFileName(id: string): string;
+/** Scoped packs (GitHub App design §2): a pack's scope in words - the organisation's, a unit's (its type, and its name when
+ *  the server sent one: names that fail its person check are withheld there), or the reader's own. Null for an older server. */
+export declare function packScopeLabel(scope: any): string | null;
+/** Where `context pull --here` is: a folder's .decidio.json names a unit; else the checkout's GitHub remote names the repository
+ *  (its binding's unit decides); else nowhere in particular (the organisation's packs and your own). */
+export declare function hereQuery(cwd?: string): {
+    unit?: string;
+    repo?: string;
+    error?: string;
+};
+/** PROJECT FILES ARE TOUCHED ONLY THROUGH PLAIN PATHS (invariant-guard 2026-10-16): a repository can commit `.claude/skills/x`
+ *  or `.claude/rules` as a SYMLINK to anywhere, so every component from the project's `.claude` down is lstat'ed and a symlink
+ *  refuses the whole path - nothing is written through it and nothing is removed through it. A missing component is fine. */
+export declare function plainProjectPath(parts: string[]): boolean;
+/** Is this file one `context pull` wrote? A skill file's frontmatter names `decidio-<slug>` and its heading says it is a
+ *  Decidio context pack; a rules file's heading says it is one to read first. A person's own file with our prefix is not. */
+export declare function isPackFileOf(text: string, slug: string, kind: "skill" | "rules"): boolean;
+/** The skill file for one pack: the trigger IS the description (the host reads it every turn), the rows are the body. */
+export declare function packSkillMarkdown(idx: any): string;
+/** An ALWAYS-pack (stackable packs, 2026-10-15): a Claude Code rules file, loaded whole at launch with the project's own
+ *  rules - no frontmatter, no trigger; the foundation every other pack can assume was read. */
+export declare function packRulesMarkdown(idx: any): string;
+export type ParsedAdr = {
+    title: string;
+    status: string | null;
+    decided: string;
+    rationale: string;
+    alternatives: string[];
+};
+/** PURE: one ADR's title, status, decision, context (with its consequences) and the options it considered; null when it has no title. */
+export declare function parseAdr(text: string): ParsedAdr | null;
+export declare const AGENTS_MD_START = "<!-- decidio:start -->";
+export declare const AGENTS_MD_END = "<!-- decidio:end -->";
+/** Decidio's public GitHub Action (github.com/OmniTwin/decidio-actions): one action, step request or verify. It fetches the job's own
+ *  OIDC token (audience "decidio") - no repository secret - and fails the job in plain words when Decidio refuses. Pinned to the
+ *  v1.0.0 COMMIT, never a tag (invariant-guard 2026-10-20): the verify step enforces the approval in a production job with
+ *  id-token: write, so a moved tag must not change it. Bump both pins together, with the release. */
+export declare const DECIDIO_ACTION = "OmniTwin/decidio-actions@e40ba8e75a223f2475038d38a16df5a5885afde4 # v1.0.0";
+export declare const CHECKOUT_ACTION = "actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0";
+export declare function githubRequestWorkflow(api: string, environment: string, branch?: string): string;
+/** The verify step and the checkout of the approved commit: the first steps of any deploy job Decidio starts. */
+export declare function githubVerifySteps(api: string): string;
+export declare function githubDeployWorkflow(api: string, environment: string): string;
+/** The AGENTS.md section: a link to where the decisions live and how an agent checks a plan - never a decision's text (founder
+ *  2026-10-17: decisions embedded in a repository leak and go stale). */
+export declare function agentsMdSection(appUrl: string): string;
+/** PURE: AGENTS.md with our section added, or replaced where it already is (idempotent). Ours is recognised only whole - the start
+ *  marker straight followed by our heading, then the end marker after it - so a stray marker in a person's own text is never
+ *  read as ours and nothing of theirs is ever removed (invariant-guard 2026-10-17). */
+export declare function withAgentsMdSection(text: string, section: string): string;