@jmtrin/opencode-kevin 0.8.0 → 1.0.0

package/dist/plugin/RepoIdentity.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { fingerprint, fnv1a64 } from "./fingerprint.js";
 // ============================================================
 // Kevin 0.8.0 — RepoIdentity (K8-005/K8-006 / plan §5.1, D8-04)
+// v0.9.0 — host identity source (K9-006 / plan §5.2, D9-13)
 // ============================================================
 // Repository-derived identity that survives a clone. Two clones
 // of the same remote must agree on one `repo_id` even though
@@ -149,8 +150,8 @@ export function computeRepoId(normalized) {
     return fnv1a64(`okf:repo:v1\u0000${normalized}`);
 }
 /**
- * Resolve the repository identity for `cwd`, trying the three
- * sources in order (plan §5.1):
+ * Resolve the repository identity for `cwd`, trying the four
+ * sources in order (plan §5.2, D9-13):
  *
  *   1. `declared` — `.kevin/project.json` → `id` (validated as
  *      exactly 16 lowercase hex characters; anything else is ignored
@@ -159,14 +160,24 @@ export function computeRepoId(normalized) {
  *      onto a typo);
  *   2. `remote` — `.git/config` → `[remote "origin"] url`,
  *      normalized and hashed;
- *   3. `path` — `fingerprint(cwd)`, the v0.7.0 behaviour.
+ *   3. `host` — the value the host resolved for this directory,
+ *      `host.project.worktree` first, `host.project.directory` as
+ *      fallback; both empty or absent falls through to `path`.
+ *      This is strictly better than `process.cwd()` — the host's own
+ *      ToolContext documents "prefer this over `process.cwd()`" —
+ *      but it sits below the explicit sources, because monorepos and
+ *      D8-03's confirmed re-keying depend on `.kevin/project.json`
+ *      winning;
+ *   4. `path` — `fingerprint(cwd)`, the v0.7.0 behaviour, preserved
+ *      exactly when `host` is absent.
  *
  * Never throws: a directory that is not a git repository, an
- * unreadable `.git/config`, and a malformed `project.json` all fall
- * through to source 3. `projectId` is always returned alongside
- * `repoId`, regardless of which source won.
+ * unreadable `.git/config`, a malformed `project.json`, and a host
+ * with no usable project fields all fall through to source 4.
+ * `projectId` is always returned alongside `repoId`, regardless of
+ * which source won.
  */
-export function resolve(cwd) {
+export function resolve(cwd, host) {
     const projectId = fingerprint(cwd);
     // 1. Declared.
     try {
@@ -201,7 +212,31 @@ export function resolve(cwd) {
     catch {
         // Unreadable or missing — fall through.
     }
-    // 3. Path — the v0.7.0 behaviour, preserved exactly.
+    // 3. Host — the value the host already resolved for this
+    //    directory (D9-13), inserted above `path` and below the two
+    //    explicit sources. `worktree` first, `directory` as fallback;
+    //    both empty or absent falls through. The chosen value feeds
+    //    the unchanged `computeRepoId()` — this chain changes which
+    //    string is hashed, never how.
+    const worktree = host?.project?.worktree;
+    if (typeof worktree === "string" && worktree.length > 0) {
+        return {
+            repoId: computeRepoId(worktree),
+            source: "host",
+            evidence: "host:worktree",
+            projectId,
+        };
+    }
+    const directory = host?.project?.directory;
+    if (typeof directory === "string" && directory.length > 0) {
+        return {
+            repoId: computeRepoId(directory),
+            source: "host",
+            evidence: "host:directory",
+            projectId,
+        };
+    }
+    // 4. Path — the v0.7.0 behaviour, preserved exactly.
     return { repoId: projectId, source: "path", evidence: "cwd", projectId };
 }
 /**
@@ -240,7 +275,7 @@ export function initProjectFile(cwd, writer) {
     const createdAt = new Date().toISOString();
     const payload = `${JSON.stringify({
         created_at: createdAt,
-        generator: "opencode-kevin/0.8.0",
+        generator: "opencode-kevin/0.9.0",
         id,
     })}\n`;
     try {
@@ -263,4 +298,3 @@ export function initProjectFile(cwd, writer) {
         };
     }
 }
-//# sourceMappingURL=RepoIdentity.js.map

package/dist/plugin/RepoTruth.js

@@ -597,4 +597,3 @@ function normalizeBool(v) {
     return null;
 }
 export { MAX_FACTS_PER_PROJECT };
-//# sourceMappingURL=RepoTruth.js.map

package/dist/plugin/Retrospective.js

@@ -58,6 +58,22 @@ export const METRIC_KEY_LABELS = {
     okf_merge_folds: "Fusiones OKF (folds)",
     rekey_events: "Re-keys de repositorio",
     injections_from_shared: "Inyecciones desde la capa compartida",
+    // v0.9.0 (K9-003 / plan §8.16) — the K9 metric keys need their own
+    // Spanish labels; the audit regression forbids raw-key fallback for any
+    // key in METRIC_KEYS.
+    hook_fires_total: "Disparos de hooks (totales)",
+    hook_errors_total: "Errores de hooks",
+    hooks_dead_total: "Hooks muertos",
+    injections_suppressed_dead_hook: "Inyecciones suprimidas (hook muerto)",
+    native_registrations_total: "Registros nativos (totales)",
+    native_registration_failures: "Fallos de registro nativo",
+    // v1.0.0 (K10-005 / plan §6) — the six keys seeded by migration 011 section 3.
+    perf_samples_recorded: "Muestras de rendimiento registradas",
+    perf_budget_breaches: "Brechas de presupuesto de rendimiento",
+    dispose_fires_total: "Disparos de dispose (totales)",
+    dispose_misses_total: "Misses de dispose",
+    contract_digest_changes: "Cambios de digest de contrato",
+    bench_runs_total: "Ejecuciones de benchmark (totales)",
 };
 function originLabel(origin) {
     if (origin === "reflector")
@@ -191,4 +207,3 @@ export class Retrospective {
         return lines.join("\n");
     }
 }
-//# sourceMappingURL=Retrospective.js.map

package/dist/plugin/SharedLayer.js

@@ -460,4 +460,3 @@ export class SharedLayer {
         return n;
     }
 }
-//# sourceMappingURL=SharedLayer.js.map

package/dist/plugin/Store.js

@@ -48,4 +48,3 @@ export class Store {
         return this.db;
     }
 }
-//# sourceMappingURL=Store.js.map

package/dist/plugin/ToolCallObserver.js

@@ -186,4 +186,3 @@ export class ToolCallObserver {
         return v;
     }
 }
-//# sourceMappingURL=ToolCallObserver.js.map

package/dist/plugin/capabilities.js

@@ -39,4 +39,3 @@ export function probe(input) {
         return ALL_FALSE;
     }
 }
-//# sourceMappingURL=capabilities.js.map

package/dist/plugin/confidence.js

@@ -32,4 +32,3 @@ export function computeConfidence(evidenceCount, recurrenceCount, positiveFeedba
         FEEDBACK_NEGATIVE_STEP * negativeFeedback;
     return Math.min(CONFIDENCE_MAX, Math.max(CONFIDENCE_MIN, raw));
 }
-//# sourceMappingURL=confidence.js.map

package/dist/plugin/contract.d.ts

@@ -0,0 +1,46 @@
+export declare const CONTRACT_VERSION = 1;
+export type Stability = "frozen" | "forward-only";
+export interface ContractClause {
+    readonly id: string;
+    readonly title: string;
+    readonly stability: Stability;
+    readonly since: string;
+    readonly deprecated?: string;
+    readonly replacement?: string;
+    readonly value: unknown;
+}
+export interface PublicContract {
+    readonly contractVersion: number;
+    readonly clauses: readonly ContractClause[];
+}
+export interface ContractInput {
+    readonly packageName?: string;
+    readonly packageVersion?: string;
+}
+export declare const CONTRACT_TOOL_NAMES: readonly string[];
+/**
+ * v1.0.0 (K10-018/K10-019 / plan §5.6) — tools added AFTER the initial
+ * freeze, each carrying the `since` the deprecation policy requires. A
+ * 1.x addition without an entry here fails the contract test as
+ * added_bare.
+ */
+export declare const CONTRACT_TOOL_ADDITIONS: readonly {
+    name: string;
+    since: string;
+}[];
+/**
+ * v1.0.0 (K10-027 / plan §5.7) — the C-09 boundary addition. Stored is
+ * not trusted: anything reaching an artifact or a prompt is escaped at
+ * the single write path, according to its container.
+ */
+export declare const BOUNDARY_INVARIANT = "untrusted-input escaping at the single write path";
+export declare function describeContract(_input?: ContractInput): PublicContract;
+export declare function contractDigest(c: PublicContract): string;
+export type ContractDiffKind = "removed" | "changed" | "added_ok" | "added_bare";
+export interface ContractDiff {
+    readonly clauseId: string;
+    readonly path: string;
+    readonly kind: ContractDiffKind;
+    readonly remedy: string;
+}
+export declare function diffContract(golden: PublicContract, live: PublicContract): readonly ContractDiff[];

package/dist/plugin/contract.js

@@ -0,0 +1,368 @@
+// v1.0.0 (K10-006 / plan §5.1) — the surface, as data.
+import { MARKER_BEGIN, MARKER_END } from "./ArtifactWriter.js";
+import { METRIC_KEY_LABELS } from "./Retrospective.js";
+import { fnv1a64 } from "./fingerprint.js";
+import { KEVIN_CONFIG_KEYS } from "./index.js";
+import { MAX_ENTRIES, MAX_LINE_BYTES } from "./okf.js";
+export const CONTRACT_VERSION = 1;
+// Tool names — the live source of truth for C-03. Any rename here must
+// flow to the contract (K10-006 AC: renaming a tool changes C-03).
+// Keep this array adjacent to the actual tool registrations in index.ts
+// (checked by a test that parses both files).
+export const CONTRACT_TOOL_NAMES = [
+    "kevin_save",
+    "kevin_query",
+    "kevin_get",
+    "kevin_recall",
+    "kevin_status",
+    "kevin_project",
+    "kevin_audit",
+    "kevin_doctor",
+    "kevin_native",
+    "kevin_retrospective",
+    "kevin_why",
+    "kevin_feedback",
+    "kevin_trace",
+    "kevin_export",
+    "kevin_import",
+    "kevin_config",
+    "kevin_facts",
+    "kevin_conflicts",
+    "kevin_propose",
+    "kevin_publish",
+    "kevin_approve",
+    "kevin_share",
+    "kevin_sync",
+];
+/**
+ * v1.0.0 (K10-018/K10-019 / plan §5.6) — tools added AFTER the initial
+ * freeze, each carrying the `since` the deprecation policy requires. A
+ * 1.x addition without an entry here fails the contract test as
+ * added_bare.
+ */
+export const CONTRACT_TOOL_ADDITIONS = [
+    { name: "kevin_contract", since: "1.0.0" },
+    { name: "kevin_bench", since: "1.0.0" },
+];
+/**
+ * v1.0.0 (K10-027 / plan §5.7) — the C-09 boundary addition. Stored is
+ * not trusted: anything reaching an artifact or a prompt is escaped at
+ * the single write path, according to its container.
+ */
+export const BOUNDARY_INVARIANT = "untrusted-input escaping at the single write path";
+// For canonical JSON: sort keys recursively, no floats.
+function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || !Number.isInteger(value))
+            throw new Error("contract: non-integer number in canonical JSON");
+        return String(value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+export function describeContract(_input) {
+    // Derive clause values from live source wherever possible (plan §5.1).
+    // C-03 members added after the freeze carry their `since` as objects;
+    // the original frozen set stays plain strings.
+    const additions = [...CONTRACT_TOOL_ADDITIONS].sort((a, b) => a.name.localeCompare(b.name));
+    const toolValue = {
+        tools: [[...CONTRACT_TOOL_NAMES].sort(), additions].flat(),
+    };
+    const settingValue = { keys: [...KEVIN_CONFIG_KEYS].sort() };
+    const metricValue = { keys: Object.keys(METRIC_KEY_LABELS).sort() };
+    const clauses = [
+        {
+            id: "C-01",
+            title: "AGENTS.md marker pair",
+            stability: "frozen",
+            since: "0.6.0",
+            value: {
+                markers: [MARKER_BEGIN, MARKER_END],
+                splice_rule: "bytes outside markers preserved verbatim",
+            },
+        },
+        {
+            id: "C-02",
+            title: "OKF v2 wire format",
+            stability: "frozen",
+            since: "0.8.0",
+            value: {
+                header_lines: 3,
+                field_order: ["entry_id", "type", "content", "scope", "created_at"],
+                entry_id_derivation: "fnv1a64 over canonical field ordering",
+                eol: "LF",
+                integers_only: true,
+                sort_order: "entry_id ascending",
+                max_line_bytes: MAX_LINE_BYTES,
+                max_entries: MAX_ENTRIES,
+            },
+        },
+        {
+            id: "C-03",
+            title: "Tool names and argument shapes",
+            stability: "frozen",
+            since: "0.2.0",
+            value: toolValue,
+        },
+        {
+            id: "C-04",
+            title: "Setting keys, types and defaults",
+            stability: "frozen",
+            since: "0.2.0",
+            value: settingValue,
+        },
+        {
+            id: "C-05",
+            title: "Metric key names",
+            stability: "frozen",
+            since: "0.2.0",
+            value: metricValue,
+        },
+        {
+            id: "C-06",
+            title: "Package entry points",
+            stability: "frozen",
+            since: "0.1.0",
+            value: {
+                name: "@jmtrin/opencode-kevin",
+                main: "dist/plugin/index.js",
+                types: "dist/plugin/index.d.ts",
+                exports_order: ["types", "import"],
+                engines: ">=22.5.0",
+            },
+        },
+        {
+            id: "C-07",
+            title: "Database schema",
+            stability: "forward-only",
+            since: "0.1.0",
+            value: {
+                schema_version: "011",
+                migrations_forward_only: true,
+            },
+        },
+        {
+            id: "C-08",
+            title: "Filesystem locations",
+            stability: "frozen",
+            since: "0.2.0",
+            value: {
+                db: "~/.opencode-kevin/kevin.db",
+                refs: "refs/",
+                skills: "skills/",
+                okf: ".kevin/knowledge.okf",
+            },
+        },
+        {
+            id: "C-09",
+            title: "Behavioural invariants",
+            stability: "frozen",
+            since: "0.8.0",
+            value: {
+                invariants: [
+                    "zero process spawns",
+                    "zero network calls",
+                    "no raw author email written",
+                    "single write path: ArtifactWriter is the only artifact writer",
+                ],
+                // v1.0.0 (K10-027 / plan §5.7) — the untrusted-input boundary
+                // joins the clause as an addition carrying its `since`; the
+                // frozen invariant strings above are untouched.
+                boundary: [{ name: BOUNDARY_INVARIANT, since: "1.0.0" }],
+            },
+        },
+    ];
+    return { contractVersion: CONTRACT_VERSION, clauses };
+}
+export function contractDigest(c) {
+    const payload = canonicalJson(c.clauses);
+    return fnv1a64(payload);
+}
+function valueMembers(value) {
+    // Normalize clause value into a flat member map for diffing.
+    // If value is { tools: [...] } => members are tool names.
+    // If { keys: [...] } => member per key.
+    // Otherwise flatten object keys.
+    if (value !== null && typeof value === "object") {
+        const obj = value;
+        if (Array.isArray(obj.tools)) {
+            const m = new Map();
+            for (const t of obj.tools) {
+                if (typeof t === "string")
+                    m.set(t, undefined);
+                else if (t !== null &&
+                    typeof t === "object" &&
+                    "name" in t)
+                    m.set(t.name, t);
+            }
+            return m;
+        }
+        if (Array.isArray(obj.keys)) {
+            const m = new Map();
+            for (const k of obj.keys) {
+                if (typeof k === "string")
+                    m.set(k, undefined);
+                else if (k !== null &&
+                    typeof k === "object" &&
+                    "name" in k)
+                    m.set(k.name, k);
+            }
+            return m;
+        }
+        if (Array.isArray(obj.markers) || Array.isArray(obj.invariants)) {
+            const arr = (obj.markers ?? obj.invariants);
+            const m = new Map();
+            for (const v of arr)
+                m.set(v, v);
+            // v1.0.0 (K10-027) — boundary additions sit beside the frozen
+            // invariant strings and carry their `since` like tool additions.
+            if (Array.isArray(obj.boundary)) {
+                for (const b of obj.boundary) {
+                    if (b !== null &&
+                        typeof b === "object" &&
+                        "name" in b)
+                        m.set(b.name, b);
+                }
+            }
+            return m;
+        }
+        // Generic object: each key is a member
+        const m = new Map();
+        for (const [k, v] of Object.entries(obj))
+            m.set(k, v);
+        return m;
+    }
+    return new Map([["value", value]]);
+}
+export function diffContract(golden, live) {
+    const diffs = [];
+    const goldenById = new Map(golden.clauses.map((c) => [c.id, c]));
+    const liveById = new Map(live.clauses.map((c) => [c.id, c]));
+    // Removed clauses
+    for (const g of golden.clauses) {
+        if (!liveById.has(g.id)) {
+            diffs.push({
+                clauseId: g.id,
+                path: g.id,
+                kind: "removed",
+                remedy: `Clause ${g.id} was removed. Revert, or open a 2.0.0.`,
+            });
+        }
+    }
+    // Added clauses — check since
+    for (const l of live.clauses) {
+        if (!goldenById.has(l.id)) {
+            const hasSince = typeof l.since === "string" &&
+                l.since.length > 0;
+            diffs.push({
+                clauseId: l.id,
+                path: l.id,
+                kind: hasSince ? "added_ok" : "added_bare",
+                remedy: hasSince
+                    ? `Clause ${l.id} was added with since. Allowed in 1.x.`
+                    : `Clause ${l.id} was added without since. Add since or revert, or open a 2.0.0.`,
+            });
+        }
+    }
+    // Within-clause diff
+    for (const g of golden.clauses) {
+        const l = liveById.get(g.id);
+        if (!l)
+            continue;
+        const gMembers = valueMembers(g.value);
+        const lMembers = valueMembers(l.value);
+        // Normalize members: for arrays we care about set equality
+        for (const [mem, _gv] of gMembers) {
+            if (!lMembers.has(mem)) {
+                diffs.push({
+                    clauseId: g.id,
+                    path: `${g.id}.${mem}`,
+                    kind: "removed",
+                    remedy: `Member ${mem} in ${g.id} was removed. Revert, or open a 2.0.0.`,
+                });
+            }
+            else {
+                const lv = lMembers.get(mem);
+                const gv = gMembers.get(mem);
+                if (JSON.stringify(lv) !== JSON.stringify(gv)) {
+                    // Member present on both sides but its value moved (e.g. an
+                    // addition object whose `since` was edited). Report it here,
+                    // at member granularity, instead of letting it fall through
+                    // to the coarser clause-level check below.
+                    diffs.push({
+                        clauseId: g.id,
+                        path: `${g.id}.${mem}`,
+                        kind: "changed",
+                        remedy: `Member ${mem} in ${g.id} changed. Revert, or open a 2.0.0.`,
+                    });
+                }
+            }
+        }
+        for (const [mem, _lv] of lMembers) {
+            if (!gMembers.has(mem)) {
+                const liveVal = l.value;
+                // Check if the live member carries `since` (additions may ride
+                // in the keys, tools or boundary arrays — K10-018/K10-027).
+                const lists = [liveVal.keys, liveVal.tools, liveVal.boundary];
+                let hasSince = false;
+                for (const list of lists) {
+                    if (!Array.isArray(list))
+                        continue;
+                    const entry = list.find((e) => {
+                        if (typeof e === "string")
+                            return e === mem;
+                        if (e !== null &&
+                            typeof e === "object" &&
+                            "name" in e)
+                            return e.name === mem;
+                        return false;
+                    });
+                    if (entry !== null &&
+                        typeof entry === "object" &&
+                        typeof entry.since === "string") {
+                        hasSince = true;
+                        break;
+                    }
+                }
+                diffs.push({
+                    clauseId: g.id,
+                    path: `${g.id}.${mem}`,
+                    kind: hasSince ? "added_ok" : "added_bare",
+                    remedy: hasSince
+                        ? `Member ${mem} in ${g.id} was added with since. Allowed in 1.x.`
+                        : `Member ${mem} in ${g.id} was added without since. Add since or revert, or open a 2.0.0.`,
+                });
+            }
+        }
+        // Also compare clause-level metadata that is not in valueMembers (e.g., package version in C-06)
+        // If the whole value JSON differs but members didn't capture it (e.g., name change), mark changed.
+        if (JSON.stringify(g.value) !== JSON.stringify(l.value)) {
+            // Only emit clause-level changed if no finer-grained diff already emitted for this clause
+            const hasFiner = diffs.some((d) => d.clauseId === g.id && d.path !== g.id);
+            if (!hasFiner) {
+                diffs.push({
+                    clauseId: g.id,
+                    path: g.id,
+                    kind: "changed",
+                    remedy: `Clause ${g.id} changed. Revert, or open a 2.0.0.`,
+                });
+            }
+        }
+    }
+    diffs.sort((a, b) => a.clauseId === b.clauseId
+        ? a.path.localeCompare(b.path)
+        : a.clauseId.localeCompare(b.clauseId));
+    return diffs;
+}

package/dist/plugin/diff.js

@@ -180,4 +180,3 @@ export function unifiedDiff(path, before, after) {
     const header = `--- a/${path}\n+++ b/${path}\n`;
     return `${header}${parts.join("\n")}\n`;
 }
-//# sourceMappingURL=diff.js.map

package/dist/plugin/escape.d.ts

@@ -0,0 +1,39 @@
+/**
+ * v1.0.0 (K10-027 / plan §5.7) — the untrusted-input boundary.
+ *
+ * One pure, total, idempotent escaping function per container Kevin
+ * writes stored text into. Every function here is a fixed point after
+ * one application — applying it twice equals applying it once — because
+ * a re-curated memory passes through the boundary on every regeneration
+ * and must not accumulate escaping.
+ *
+ * This module imports nothing and touches no filesystem. It is the
+ * boundary; the single enforcement point is ArtifactWriter (D6-01).
+ */
+/**
+ * Neutralise text destined for the AGENTS.md marker block: HTML-escape
+ * (the memory-format discipline, made idempotent) so the literal
+ * `<!-- kevin:end -->` marker sequence and every comment terminator
+ * lose their meaning inside the block. The line-level strip of anything
+ * containing `kevin:begin`/`kevin:end` stays in
+ * ArtifactWriter.sanitizeArtifactBody — it is a filter, not an escape.
+ */
+export declare function escapeForMarkerBlock(text: string): string;
+/**
+ * Neutralise fenced-code delimiters: any run of three or more backticks
+ * or tildes would close (or open) a markdown fence around the rendered
+ * block and let stored text masquerade as un-fenced document content.
+ * Each byte of the run becomes its numeric HTML entity, which renders
+ * identically but can never form a delimiter again.
+ */
+export declare function escapeForFence(text: string): string;
+/**
+ * Neutralise bytes that would terminate an OKF v2 line: newline,
+ * carriage return and every other C0 control character become their
+ * JSON-style escapes, so a statement can never split into a second
+ * line even if a future writer forgets JSON.stringify. Quotation marks
+ * and backslashes are deliberately NOT touched here — the OKF line is
+ * canonical JSON and re-escaping them would corrupt parsing; JSON
+ * already guarantees they stay inside the string.
+ */
+export declare function escapeForOkfLine(text: string): string;

package/dist/plugin/escape.js

@@ -0,0 +1,60 @@
+/**
+ * v1.0.0 (K10-027 / plan §5.7) — the untrusted-input boundary.
+ *
+ * One pure, total, idempotent escaping function per container Kevin
+ * writes stored text into. Every function here is a fixed point after
+ * one application — applying it twice equals applying it once — because
+ * a re-curated memory passes through the boundary on every regeneration
+ * and must not accumulate escaping.
+ *
+ * This module imports nothing and touches no filesystem. It is the
+ * boundary; the single enforcement point is ArtifactWriter (D6-01).
+ */
+const ENTITY_HEADS = /&(?!(amp|lt|gt|#\d+);)/g;
+/**
+ * Neutralise text destined for the AGENTS.md marker block: HTML-escape
+ * (the memory-format discipline, made idempotent) so the literal
+ * `<!-- kevin:end -->` marker sequence and every comment terminator
+ * lose their meaning inside the block. The line-level strip of anything
+ * containing `kevin:begin`/`kevin:end` stays in
+ * ArtifactWriter.sanitizeArtifactBody — it is a filter, not an escape.
+ */
+export function escapeForMarkerBlock(text) {
+    return text
+        .replace(ENTITY_HEADS, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/**
+ * Neutralise fenced-code delimiters: any run of three or more backticks
+ * or tildes would close (or open) a markdown fence around the rendered
+ * block and let stored text masquerade as un-fenced document content.
+ * Each byte of the run becomes its numeric HTML entity, which renders
+ * identically but can never form a delimiter again.
+ */
+export function escapeForFence(text) {
+    return text
+        .replace(/`{3,}/g, (run) => "&#96;".repeat(run.length))
+        .replace(/~{3,}/g, (run) => "&#126;".repeat(run.length));
+}
+/**
+ * Neutralise bytes that would terminate an OKF v2 line: newline,
+ * carriage return and every other C0 control character become their
+ * JSON-style escapes, so a statement can never split into a second
+ * line even if a future writer forgets JSON.stringify. Quotation marks
+ * and backslashes are deliberately NOT touched here — the OKF line is
+ * canonical JSON and re-escaping them would corrupt parsing; JSON
+ * already guarantees they stay inside the string.
+ */
+export function escapeForOkfLine(text) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: neutralising control bytes is this function's entire job
+    return text.replace(/[\u0000-\u001f]/g, (c) => {
+        if (c === "\n")
+            return "\\n";
+        if (c === "\r")
+            return "\\r";
+        if (c === "\t")
+            return "\\t";
+        return `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`;
+    });
+}