@personaxis/core 0.11.0

package/dist/injection.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Prompt-injection detection (F3 / T7 — plan/11-security).
+ *
+ * A layered, evasion-aware first line of defense over untrusted text (tool output,
+ * fetched content, project files, observations). Heuristic guardrails are exactly
+ * what production systems run *before* a model-based classifier; this engine is
+ * built to be that first line and to hand off to a model classifier when present.
+ *
+ * Layers:
+ *   1. Normalization — NFKC, strip/flag zero-width + bidi-override chars, fold a
+ *      homoglyph (confusables) map. Adversaries obfuscate; we de-obfuscate first.
+ *   2. Decoding — base64 / hex blocks are decoded and recursively scanned, so an
+ *      "ignore previous instructions" hidden inside base64 is still caught.
+ *   3. Weighted rules across categories (instruction-override, exfiltration,
+ *      role-manipulation, tool-abuse, jailbreak, obfuscation, encoding-evasion).
+ *   4. Score aggregation -> clean | suspicious | malicious, with a confidence.
+ *
+ * Pluggable: pass a `classifier` to layer a model-based judgment on top.
+ */
+export type InjectionSeverity = "info" | "suspicious" | "malicious";
+export type InjectionCategory = "instruction-override" | "exfiltration" | "role-manipulation" | "tool-abuse" | "jailbreak" | "obfuscation" | "encoding-evasion";
+export interface InjectionFinding {
+    rule: string;
+    category: InjectionCategory;
+    severity: InjectionSeverity;
+    weight: number;
+    match: string;
+}
+export interface InjectionScan {
+    verdict: "clean" | "suspicious" | "malicious";
+    /** Aggregate risk score (0..1+). */
+    score: number;
+    findings: InjectionFinding[];
+    /** Text after normalization (de-obfuscation) — what the rules actually saw. */
+    normalized: string;
+    /** Decoded base64/hex segments that were also scanned. */
+    decoded: string[];
+}
+export interface InjectionConfig {
+    suspiciousAt: number;
+    maliciousAt: number;
+    /** Optional model-based classifier; its score is fused with the heuristic. */
+    classifier?: (normalized: string) => {
+        score: number;
+        label?: string;
+    };
+}
+export declare function scanForInjection(text: string, config?: Partial<InjectionConfig>): InjectionScan;

package/dist/injection.js

@@ -0,0 +1,141 @@
+/**
+ * Prompt-injection detection (F3 / T7 — plan/11-security).
+ *
+ * A layered, evasion-aware first line of defense over untrusted text (tool output,
+ * fetched content, project files, observations). Heuristic guardrails are exactly
+ * what production systems run *before* a model-based classifier; this engine is
+ * built to be that first line and to hand off to a model classifier when present.
+ *
+ * Layers:
+ *   1. Normalization — NFKC, strip/flag zero-width + bidi-override chars, fold a
+ *      homoglyph (confusables) map. Adversaries obfuscate; we de-obfuscate first.
+ *   2. Decoding — base64 / hex blocks are decoded and recursively scanned, so an
+ *      "ignore previous instructions" hidden inside base64 is still caught.
+ *   3. Weighted rules across categories (instruction-override, exfiltration,
+ *      role-manipulation, tool-abuse, jailbreak, obfuscation, encoding-evasion).
+ *   4. Score aggregation -> clean | suspicious | malicious, with a confidence.
+ *
+ * Pluggable: pass a `classifier` to layer a model-based judgment on top.
+ */
+const DEFAULT_CONFIG = { suspiciousAt: 0.4, maliciousAt: 0.9 };
+const RULES = [
+    { re: /ignore\s+(all\s+|any\s+)?(previous|prior|above|earlier)\s+(instructions?|prompts?|messages?|context)/i, category: "instruction-override", severity: "malicious", weight: 1.0, rule: "ignore-previous" },
+    { re: /disregard\s+(the\s+|all\s+|any\s+)?(system|previous|above|prior|earlier)/i, category: "instruction-override", severity: "malicious", weight: 1.0, rule: "disregard" },
+    { re: /forget\s+(everything|all|your\s+(instructions|rules|guidelines))/i, category: "instruction-override", severity: "malicious", weight: 0.9, rule: "forget-everything" },
+    { re: /(reveal|print|show|repeat|output|leak)\s+(me\s+)?(your|the)\s+(system\s*prompt|instructions|persona|secret|hidden\s+(rules|prompt))/i, category: "exfiltration", severity: "malicious", weight: 1.0, rule: "prompt-exfil" },
+    { re: /(send|post|exfiltrate|upload|transmit|email)\s+.{0,40}\b(to|at|toward)\b\s*(https?:\/\/|[\w.-]+@)/i, category: "exfiltration", severity: "malicious", weight: 1.0, rule: "exfil-destination" },
+    { re: /override\s+(your\s+)?(safety|guardrails?|governance|constraints?|filters?|policy)/i, category: "instruction-override", severity: "malicious", weight: 1.0, rule: "override-safety" },
+    { re: /\bBEGIN\s+SYSTEM\b|<\s*\/?\s*system\s*>|\[\s*system\s*\]/i, category: "role-manipulation", severity: "suspicious", weight: 0.6, rule: "fake-system-block" },
+    { re: /you\s+are\s+now\s+(a|an|the|in)\b|act\s+as\s+(if\s+you\s+are\s+)?(a|an|the)\b/i, category: "role-manipulation", severity: "suspicious", weight: 0.5, rule: "role-override" },
+    { re: /from\s+now\s+on,?\s+(you|always|never|respond|answer|act)\b/i, category: "role-manipulation", severity: "suspicious", weight: 0.5, rule: "persistent-instruction" },
+    { re: /\b(developer\s+mode|jailbreak|DAN\b|do\s+anything\s+now|unfiltered|no\s+restrictions?)\b/i, category: "jailbreak", severity: "suspicious", weight: 0.6, rule: "jailbreak-keyword" },
+    { re: /(call|invoke|run|execute)\s+(the\s+)?(tool|function|command|shell|bash)\b.{0,40}(delete|rm\b|curl|wget|exfil|secret|cred)/i, category: "tool-abuse", severity: "malicious", weight: 0.9, rule: "tool-abuse" },
+];
+// A compact confusables map (Cyrillic/Greek lookalikes -> Latin) for homoglyph folding.
+const CONFUSABLES = {
+    "а": "a", "е": "e", "о": "o", "р": "p", "с": "c", "х": "x", "у": "y", "і": "i",
+    "Ι": "I", "Ο": "O", "А": "A", "Е": "E", "О": "O", "Р": "P", "С": "C",
+    "ο": "o", "α": "a", "ε": "e", "ρ": "p", "υ": "u",
+};
+const ZERO_WIDTH = new RegExp("[" + [0x200B, 0x200C, 0x200D, 0x2060, 0xFEFF].map((c) => String.fromCharCode(c)).join("") + "]", "g");
+const BIDI_OVERRIDE = new RegExp("[" + [0x202A, 0x202B, 0x202C, 0x202D, 0x202E, 0x2066, 0x2067, 0x2068, 0x2069].map((c) => String.fromCharCode(c)).join("") + "]", "g");
+function normalize(text) {
+    const obfuscations = [];
+    let t = text.normalize("NFKC");
+    // Use replace-and-compare (not .test) — a /g regex with .test() is stateful and
+    // would yield false negatives when the singleton regex is reused across scans.
+    const noZw = t.replace(ZERO_WIDTH, "");
+    if (noZw !== t) {
+        obfuscations.push({ rule: "zero-width-chars", category: "obfuscation", severity: "suspicious", weight: 0.4, match: "<zero-width>" });
+        t = noZw;
+    }
+    const noBidi = t.replace(BIDI_OVERRIDE, "");
+    if (noBidi !== t) {
+        obfuscations.push({ rule: "bidi-override", category: "obfuscation", severity: "suspicious", weight: 0.4, match: "<bidi-override>" });
+        t = noBidi;
+    }
+    let folded = "";
+    let homoglyphHit = false;
+    for (const ch of t) {
+        const sub = CONFUSABLES[ch];
+        if (sub) {
+            homoglyphHit = true;
+            folded += sub;
+        }
+        else
+            folded += ch;
+    }
+    if (homoglyphHit) {
+        obfuscations.push({ rule: "homoglyph", category: "obfuscation", severity: "suspicious", weight: 0.4, match: "<confusable-chars>" });
+    }
+    return { normalized: folded, obfuscations };
+}
+function decodeSegments(text) {
+    const out = [];
+    // base64 runs (length-aware to avoid plain words)
+    for (const m of text.matchAll(/[A-Za-z0-9+/]{16,}={0,2}/g)) {
+        try {
+            const decoded = Buffer.from(m[0], "base64").toString("utf8");
+            if (decoded && /[\x20-\x7e]/.test(decoded) && printableRatio(decoded) > 0.8)
+                out.push(decoded);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // hex runs
+    for (const m of text.matchAll(/(?:[0-9a-fA-F]{2}){8,}/g)) {
+        try {
+            const decoded = Buffer.from(m[0], "hex").toString("utf8");
+            if (decoded && printableRatio(decoded) > 0.8)
+                out.push(decoded);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return out;
+}
+function printableRatio(s) {
+    if (!s.length)
+        return 0;
+    let p = 0;
+    for (const c of s)
+        if (c >= " " && c <= "~")
+            p++;
+    return p / s.length;
+}
+function applyRules(text, decodedOrigin = false) {
+    const findings = [];
+    for (const r of RULES) {
+        const m = text.match(r.re);
+        if (m) {
+            findings.push({
+                rule: decodedOrigin ? `encoded:${r.rule}` : r.rule,
+                category: decodedOrigin ? "encoding-evasion" : r.category,
+                severity: r.severity,
+                weight: decodedOrigin ? Math.min(1, r.weight + 0.2) : r.weight,
+                match: m[0].slice(0, 80),
+            });
+        }
+    }
+    return findings;
+}
+export function scanForInjection(text, config = {}) {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    const { normalized, obfuscations } = normalize(text);
+    const findings = [...obfuscations, ...applyRules(normalized)];
+    const decoded = decodeSegments(normalized);
+    for (const d of decoded)
+        findings.push(...applyRules(d, true));
+    let score = findings.reduce((s, f) => s + f.weight, 0);
+    if (cfg.classifier) {
+        const c = cfg.classifier(normalized);
+        score = Math.max(score, c.score); // fuse: take the stronger signal
+        if (c.score >= cfg.suspiciousAt) {
+            findings.push({ rule: `classifier:${c.label ?? "flagged"}`, category: "instruction-override", severity: c.score >= cfg.maliciousAt ? "malicious" : "suspicious", weight: c.score, match: "<model>" });
+        }
+    }
+    const verdict = score >= cfg.maliciousAt ? "malicious" : score >= cfg.suspiciousAt ? "suspicious" : "clean";
+    return { verdict, score: Number(score.toFixed(3)), findings, normalized, decoded };
+}

package/dist/live-sync.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Live-sync (F5 — plan/05-interop).
+ *
+ * When a persona's runtime state drifts, a host watching the compiled doc must be
+ * able to tell. The compiled `PERSONA.md` is a *purely qualitative* document, so we
+ * never inject numeric state into it. Instead the drift is synced deterministically:
+ *
+ *   - write a `.live.json` notify marker (state hash + counts + current values + ts)
+ *     a host watcher can poll to know "the persona changed";
+ *   - self-heal: if an older version left a delimited LIVE-STATE block inside the
+ *     compiled doc, strip it (state belongs in state.json / .live.json, not in prose).
+ *
+ * This is the loop's `recompile` hook. The qualitative recompile remains a separate,
+ * provider-backed step; nothing here invents or mutates prose.
+ */
+import { type PersonaHandle, type StateFile } from "./persona.js";
+export declare const LIVE_START = "<!-- PERSONAXIS:LIVE-STATE start -->";
+export declare const LIVE_END = "<!-- PERSONAXIS:LIVE-STATE end -->";
+/**
+ * Remove a residual LIVE-STATE block (and its surrounding blank space) from a compiled
+ * doc. Idempotent: returns the input unchanged when no block is present. Used to migrate
+ * docs written by older versions that injected numeric state into the prose.
+ */
+export declare function stripLiveBlock(doc: string): string;
+export interface LiveMarker {
+    ts: string;
+    state_hash: string;
+    mutations: number;
+    values: Record<string, number>;
+}
+export declare function stateHash(state: StateFile): string;
+/** Write the notify marker beside the persona; returns it. */
+export declare function writeLiveMarker(personaPath: string, state: StateFile): LiveMarker;
+/**
+ * Sync runtime state: write the `.live.json` marker and self-heal the compiled doc by
+ * stripping any residual LIVE-STATE block. The compiled doc's prose is never written
+ * with numeric state.
+ */
+export declare function liveSync(handle: PersonaHandle, compiledPath: string | undefined, state: StateFile): LiveMarker;
+export interface RecompileHookOptions {
+    /** Path to the compiled doc to keep in sync (marker + live-block self-heal). */
+    compiledPath?: string;
+    /**
+     * F3.1 — optional DETERMINISTIC inline recompile. When provided, on drift the
+     * hook also rewrites `compiledPath` with this freshly-assembled document (the
+     * stage-1 assembler, no provider — cheap, no tokens). This is what makes the
+     * loop's `recompile` a real recompile rather than a marker: the compiled doc
+     * reflects the evolved spec immediately. A later `personaxis compile` re-polishes.
+     * Returns undefined to skip the rewrite for a given tick.
+     */
+    assemble?: (handle: PersonaHandle) => string | undefined;
+}
+/**
+ * Build a `recompile` hook for the LivingLoop: on numeric drift it writes the `.live.json`
+ * notify marker (and strips any residual live block from the compiled doc). When an
+ * `assemble` function is supplied (F3.1) it ALSO rewrites the compiled doc deterministically
+ * — a cheap, provider-free inline recompile. The qualitative LLM POLISH remains a separate,
+ * provider-backed step (`personaxis compile`).
+ */
+export declare function makeRecompileHook(opts?: string | RecompileHookOptions): (handle: PersonaHandle) => Promise<void>;

package/dist/live-sync.js

@@ -0,0 +1,85 @@
+/**
+ * Live-sync (F5 — plan/05-interop).
+ *
+ * When a persona's runtime state drifts, a host watching the compiled doc must be
+ * able to tell. The compiled `PERSONA.md` is a *purely qualitative* document, so we
+ * never inject numeric state into it. Instead the drift is synced deterministically:
+ *
+ *   - write a `.live.json` notify marker (state hash + counts + current values + ts)
+ *     a host watcher can poll to know "the persona changed";
+ *   - self-heal: if an older version left a delimited LIVE-STATE block inside the
+ *     compiled doc, strip it (state belongs in state.json / .live.json, not in prose).
+ *
+ * This is the loop's `recompile` hook. The qualitative recompile remains a separate,
+ * provider-backed step; nothing here invents or mutates prose.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { readState } from "./persona.js";
+export const LIVE_START = "<!-- PERSONAXIS:LIVE-STATE start -->";
+export const LIVE_END = "<!-- PERSONAXIS:LIVE-STATE end -->";
+/**
+ * Remove a residual LIVE-STATE block (and its surrounding blank space) from a compiled
+ * doc. Idempotent: returns the input unchanged when no block is present. Used to migrate
+ * docs written by older versions that injected numeric state into the prose.
+ */
+export function stripLiveBlock(doc) {
+    const start = doc.indexOf(LIVE_START);
+    const end = doc.indexOf(LIVE_END);
+    if (start === -1 || end === -1 || end < start)
+        return doc;
+    const before = doc.slice(0, start).replace(/\s+$/, "");
+    const after = doc.slice(end + LIVE_END.length).replace(/^\s+/, "");
+    return after ? `${before}\n\n${after}` : `${before}\n`;
+}
+function markerPath(personaPath) {
+    return join(dirname(personaPath), ".live.json");
+}
+export function stateHash(state) {
+    return createHash("sha256").update(JSON.stringify(state.values)).digest("hex").slice(0, 16);
+}
+/** Write the notify marker beside the persona; returns it. */
+export function writeLiveMarker(personaPath, state) {
+    const marker = {
+        ts: new Date().toISOString(),
+        state_hash: stateHash(state),
+        mutations: state.mutation_log.length,
+        values: state.values,
+    };
+    writeFileSync(markerPath(personaPath), JSON.stringify(marker, null, 2) + "\n", "utf-8");
+    return marker;
+}
+/**
+ * Sync runtime state: write the `.live.json` marker and self-heal the compiled doc by
+ * stripping any residual LIVE-STATE block. The compiled doc's prose is never written
+ * with numeric state.
+ */
+export function liveSync(handle, compiledPath, state) {
+    if (compiledPath && existsSync(compiledPath)) {
+        const doc = readFileSync(compiledPath, "utf-8");
+        const cleaned = stripLiveBlock(doc);
+        if (cleaned !== doc)
+            writeFileSync(compiledPath, cleaned, "utf-8");
+    }
+    return writeLiveMarker(handle.personaPath, state);
+}
+/**
+ * Build a `recompile` hook for the LivingLoop: on numeric drift it writes the `.live.json`
+ * notify marker (and strips any residual live block from the compiled doc). When an
+ * `assemble` function is supplied (F3.1) it ALSO rewrites the compiled doc deterministically
+ * — a cheap, provider-free inline recompile. The qualitative LLM POLISH remains a separate,
+ * provider-backed step (`personaxis compile`).
+ */
+export function makeRecompileHook(opts) {
+    const options = typeof opts === "string" ? { compiledPath: opts } : opts ?? {};
+    return async (handle) => {
+        const state = readState(handle.statePath);
+        liveSync(handle, options.compiledPath, state);
+        if (options.assemble && options.compiledPath && existsSync(options.compiledPath)) {
+            const doc = options.assemble(handle);
+            if (doc && doc.trim())
+                writeFileSync(options.compiledPath, doc.trimEnd() + "\n", "utf-8");
+        }
+    };
+}

package/dist/llm-appraiser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * LLM appraiser — small-model feasibility via constrained decoding (F2).
+ *
+ * The model NEVER emits a state mutation by hand. It emits a structured appraisal
+ * signal under APPRAISAL_JSON_SCHEMA, enforced by the server's constrained
+ * decoding (llama.cpp / Ollama `response_format: json_schema`, or a GBNF grammar).
+ * The spec engine then clamps + governs. The model proposes signals; the code +
+ * the spec impose safety — viable on <=4B and safe at the same time.
+ *
+ * Talks to any OpenAI-compatible /chat/completions endpoint (Ollama, llama.cpp
+ * server, LM Studio, or a hosted model). Dependency-free (uses global fetch).
+ */
+import { type AppraiseInput, type AppraisalSignal, type Appraiser } from "./appraisal.js";
+export interface LlmAppraiserConfig {
+    /** OpenAI-compatible base URL, e.g. http://localhost:11434/v1 (Ollama). */
+    endpoint: string;
+    model: string;
+    /** Optional bearer token (hosted endpoints). Local servers need none. */
+    apiKey?: string;
+    /** Hard cap on the response; appraisal signals are tiny. */
+    maxTokens?: number;
+    /** Abort the request after this many ms so a hung endpoint never blocks a turn (default 30s). */
+    timeoutMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export declare class LlmAppraiser implements Appraiser {
+    private readonly cfg;
+    constructor(cfg: LlmAppraiserConfig);
+    appraise(input: AppraiseInput): Promise<AppraisalSignal>;
+}

package/dist/llm-appraiser.js

@@ -0,0 +1,143 @@
+/**
+ * LLM appraiser — small-model feasibility via constrained decoding (F2).
+ *
+ * The model NEVER emits a state mutation by hand. It emits a structured appraisal
+ * signal under APPRAISAL_JSON_SCHEMA, enforced by the server's constrained
+ * decoding (llama.cpp / Ollama `response_format: json_schema`, or a GBNF grammar).
+ * The spec engine then clamps + governs. The model proposes signals; the code +
+ * the spec impose safety — viable on <=4B and safe at the same time.
+ *
+ * Talks to any OpenAI-compatible /chat/completions endpoint (Ollama, llama.cpp
+ * server, LM Studio, or a hosted model). Dependency-free (uses global fetch).
+ */
+import { APPRAISAL_JSON_SCHEMA, parseAppraisalSignal, portableJsonSchema, } from "./appraisal.js";
+import { renderEvolutionView } from "./evolution-view.js";
+const SYSTEM = `You are the appraisal module of a governed AI persona runtime.
+Given the persona's identity and a new observation, output ONLY a JSON object that
+matches the provided schema:
+- "appraisal": a brief read of the situation;
+- "mutations": optional small envelope nudges (field + signed delta in [-1,1] + reason);
+- "memories": optional notes to remember (content + source);
+- "selfEdits": optional durable edits to the persona SPEC, by dot-path. Each item is
+  { "targetPath": "<dot.path>", "toValue": <the full new value>, "rationale": "<why>" }.
+  You may ONLY target the editable sections listed below; identity/character/hard_limits/safety
+  are protected and rejected. Propose these RARELY — only when the observation clearly warrants a
+  lasting change. But when the user EXPLICITLY authorizes a durable change to an editable section,
+  you MUST express it as a selfEdit (the structured field) — never only in the "appraisal" prose.
+  The "toValue" is the replacement value, not a delta: for a scalar give the new number/string;
+  for an object give the whole new object. Worked example — user says "permanently lower your
+  uncertainty disclosure threshold to 0.10":
+    "selfEdits": [{ "targetPath": "cognition.uncertainty_policy.disclose_when_above",
+      "toValue": 0.10, "rationale": "user authorized a durable lower disclosure threshold" }]
+- "preferences": optional stable user preferences you inferred (key + value);
+- "confidence" in [0,1] (self-edits/preferences are only considered at confidence >= 0.6).
+Propose only minimal, well-justified changes. You are NOT applying anything — the runtime
+clamps, governs (mode + consensus + protected paths), and may queue your proposal.`;
+export class LlmAppraiser {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async appraise(input) {
+        const fetchImpl = this.cfg.fetchImpl ?? fetch;
+        // F3.8: prefer the grounded evolution view (current values + envelopes + mode)
+        // over the bare field names, so the model proposes deltas against reality.
+        const evolutionBlock = input.evolutionView
+            ? renderEvolutionView(input.evolutionView)
+            : [
+                `# Mutable envelope fields you may nudge`,
+                input.mutableFields.join(", ") || "(none)",
+                ``,
+                `# Editable spec sections you may propose self-edits to`,
+                (input.editableSections ?? []).join(", ") || "(none — do not propose selfEdits)",
+            ].join("\n");
+        const userMsg = [
+            `# Persona identity (slot #1)`,
+            input.personaBody.slice(0, 4000),
+            ``,
+            evolutionBlock,
+            ``,
+            `# Observation [source: ${input.source}]`,
+            input.observation,
+        ].join("\n");
+        const base = {
+            model: this.cfg.model,
+            messages: [
+                { role: "system", content: SYSTEM },
+                { role: "user", content: userMsg },
+            ],
+            temperature: 0.4,
+            max_tokens: this.cfg.maxTokens ?? 512,
+        };
+        // Constrained decoding, most-constrained first. Endpoints accept different
+        // subsets: llama.cpp/Ollama and OpenAI take full `json_schema`; Cohere/Groq
+        // reject value-constraint keywords (so we send the portable schema) and some
+        // accept only `json_object`; the rest just need a JSON-shaped prompt. We degrade
+        // gracefully so a strict backend never kills the loop. Safety is downstream
+        // (clamp + parseAppraisalSignal), never the model's to enforce.
+        const strategies = [
+            {
+                type: "json_schema",
+                json_schema: {
+                    name: "appraisal_signal",
+                    strict: true,
+                    schema: portableJsonSchema(APPRAISAL_JSON_SCHEMA),
+                },
+            },
+            { type: "json_object" },
+            undefined,
+        ];
+        let lastErr = "no response";
+        for (const responseFormat of strategies) {
+            const body = responseFormat ? { ...base, response_format: responseFormat } : base;
+            // Hard timeout so a slow/hung hosted endpoint never blocks the turn forever.
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), this.cfg.timeoutMs ?? 30_000);
+            let res;
+            try {
+                res = await fetchImpl(`${this.cfg.endpoint.replace(/\/$/, "")}/chat/completions`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        ...(this.cfg.apiKey ? { authorization: `Bearer ${this.cfg.apiKey}` } : {}),
+                    },
+                    body: JSON.stringify(body),
+                    signal: ctrl.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (res.ok) {
+                const json = (await res.json());
+                const content = json.choices?.[0]?.message?.content ?? "{}";
+                let parsed;
+                try {
+                    parsed = JSON.parse(content);
+                }
+                catch {
+                    // Some servers wrap JSON in prose; extract the first {...} block.
+                    const m = content.match(/\{[\s\S]*\}/);
+                    parsed = m ? JSON.parse(m[0]) : {};
+                }
+                return parseAppraisalSignal(parsed);
+            }
+            lastErr = `HTTP ${res.status}: ${await safeText(res)}`;
+            // Auth, rate-limit and server errors won't be fixed by relaxing the
+            // response_format — surface them immediately. Only 400/422 (unsupported
+            // response_format/schema) are worth retrying with a looser strategy.
+            if (res.status === 401 || res.status === 403 || res.status === 429 || res.status >= 500) {
+                break;
+            }
+        }
+        throw new Error(`LLM appraiser ${lastErr}`);
+    }
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 200);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/lock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-persona state lock — same-machine concurrency control (F1.4 / ADR-009).
+ *
+ * Multiple processes write a persona's state.json by design (REPL + serve + watch +
+ * MCP + hooks). Without a lock, read→modify→write races lose mutation_log entries —
+ * unacceptable for a governed, audited runtime.
+ *
+ * Mechanism: a lock DIRECTORY next to the file (`state.json.lock/`). mkdir is atomic
+ * on every OS/filesystem we target; the holder records `owner.json` {pid, ts}. A lock
+ * is stale (stealable) when its owner process is dead or its timestamp is older than
+ * STALE_MS (a holder never legitimately holds it that long: locks wrap only the
+ * mechanical read→apply→write section, never a model call). Waiters retry with a
+ * short sync sleep up to WAIT_TIMEOUT_MS, then fail loudly — silent lock-skipping
+ * would defeat the audit guarantee.
+ *
+ * This does NOT solve cross-machine sync (that is sync.ts's job) — only same-machine.
+ */
+/**
+ * Acquire the lock for `targetPath` (e.g. a state.json), returning a release fn.
+ * Prefer `withStateLock` — it guarantees release.
+ */
+export declare function acquireStateLock(targetPath: string): () => void;
+/** Run `fn` holding the lock for `targetPath`. The lock is always released. */
+export declare function withStateLock<T>(targetPath: string, fn: () => T): T;
+/** True if a live (non-stale) lock currently exists for `targetPath`. */
+export declare function stateLockHeld(targetPath: string): boolean;

package/dist/lock.js

@@ -0,0 +1,99 @@
+/**
+ * Per-persona state lock — same-machine concurrency control (F1.4 / ADR-009).
+ *
+ * Multiple processes write a persona's state.json by design (REPL + serve + watch +
+ * MCP + hooks). Without a lock, read→modify→write races lose mutation_log entries —
+ * unacceptable for a governed, audited runtime.
+ *
+ * Mechanism: a lock DIRECTORY next to the file (`state.json.lock/`). mkdir is atomic
+ * on every OS/filesystem we target; the holder records `owner.json` {pid, ts}. A lock
+ * is stale (stealable) when its owner process is dead or its timestamp is older than
+ * STALE_MS (a holder never legitimately holds it that long: locks wrap only the
+ * mechanical read→apply→write section, never a model call). Waiters retry with a
+ * short sync sleep up to WAIT_TIMEOUT_MS, then fail loudly — silent lock-skipping
+ * would defeat the audit guarantee.
+ *
+ * This does NOT solve cross-machine sync (that is sync.ts's job) — only same-machine.
+ */
+import { mkdirSync, rmSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+const STALE_MS = 10_000;
+const WAIT_TIMEOUT_MS = 5_000;
+const RETRY_SLEEP_MS = 25;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readOwner(lockDir) {
+    try {
+        return JSON.parse(readFileSync(`${lockDir}/owner.json`, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isStale(lockDir) {
+    const owner = readOwner(lockDir);
+    // Unreadable/missing owner right after mkdir can be a holder mid-write; only
+    // treat as stale once the dir itself has been around longer than STALE_MS is
+    // unknowable without the owner file — fall back to "steal" (the dir with no
+    // owner.json for a full retry cycle is a crashed holder).
+    if (!owner)
+        return true;
+    if (!pidAlive(owner.pid))
+        return true;
+    return Date.now() - owner.ts > STALE_MS;
+}
+/**
+ * Acquire the lock for `targetPath` (e.g. a state.json), returning a release fn.
+ * Prefer `withStateLock` — it guarantees release.
+ */
+export function acquireStateLock(targetPath) {
+    const lockDir = `${targetPath}.lock`;
+    const deadline = Date.now() + WAIT_TIMEOUT_MS;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        try {
+            mkdirSync(lockDir);
+            writeFileSync(`${lockDir}/owner.json`, JSON.stringify({ pid: process.pid, ts: Date.now() }), "utf-8");
+            return () => rmSync(lockDir, { recursive: true, force: true });
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            if (isStale(lockDir)) {
+                rmSync(lockDir, { recursive: true, force: true });
+                continue; // retry mkdir immediately
+            }
+            if (Date.now() >= deadline) {
+                const owner = readOwner(lockDir);
+                throw new Error(`could not acquire state lock at ${lockDir} within ${WAIT_TIMEOUT_MS}ms ` +
+                    `(held by pid ${owner?.pid ?? "unknown"}). Another personaxis process is ` +
+                    `writing this persona; retry, or remove the lock dir if that process is gone.`);
+            }
+            sleepSync(RETRY_SLEEP_MS);
+        }
+    }
+}
+/** Run `fn` holding the lock for `targetPath`. The lock is always released. */
+export function withStateLock(targetPath, fn) {
+    const release = acquireStateLock(targetPath);
+    try {
+        return fn();
+    }
+    finally {
+        release();
+    }
+}
+/** True if a live (non-stale) lock currently exists for `targetPath`. */
+export function stateLockHeld(targetPath) {
+    const lockDir = `${targetPath}.lock`;
+    return existsSync(lockDir) && !isStale(lockDir);
+}