@personaxis/core 0.11.0

package/dist/registry.js

@@ -0,0 +1,168 @@
+/**
+ * Overseer registry + global/overlay persona model (F7 — plan/08-persona-model).
+ *
+ * The "master" personaxis-system is a governed *runtime* that is aware of every
+ * persona and project in the environment. It is NOT a feeling persona — it
+ * orchestrates and audits. This module is its memory:
+ *
+ *   ~/.personaxis/ (override with PERSONAXIS_HOME)
+ *     registry.json          personas, projects, collections, machines
+ *     personas/<slug>/        global identity + memory (reused across projects)
+ *
+ * Reuse model: a persona lives globally; each project "mounts" it with a local
+ * overlay (its own state.json + project memory). So the same persona can be
+ * reused WITH accumulated memory, or instantiated fresh per project. Collections
+ * (teams) group personas + projects. State is tracked per machine so the same
+ * user-clone can live on Windows/Linux/macOS and reconcile via git without one
+ * machine clobbering another.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { homedir, hostname, platform, userInfo } from "node:os";
+import { join } from "node:path";
+export function personaxisHome() {
+    return process.env.PERSONAXIS_HOME ?? join(homedir(), ".personaxis");
+}
+/** A stable per-machine id so cross-OS instances reconcile without clobbering. */
+export function machineId() {
+    return createHash("sha256")
+        .update(`${hostname()}|${platform()}|${userInfo().username}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+function registryFile() {
+    return join(personaxisHome(), "registry.json");
+}
+function empty() {
+    return { version: 1, personas: {}, projects: {}, collections: {}, teams: {}, machines: {} };
+}
+export function loadRegistry() {
+    const f = registryFile();
+    if (!existsSync(f))
+        return empty();
+    try {
+        return { ...empty(), ...JSON.parse(readFileSync(f, "utf-8")) };
+    }
+    catch {
+        return empty();
+    }
+}
+export function saveRegistry(reg) {
+    mkdirSync(personaxisHome(), { recursive: true });
+    // Atomic write: a concurrent reader (another `personaxis` process on the same registry) must never
+    // observe a half-written file — otherwise loadRegistry's parse falls back to empty() and silently
+    // drops data. Write to a unique temp file, then rename (atomic on the same filesystem).
+    const target = registryFile();
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(reg, null, 2) + "\n", "utf-8");
+    renameSync(tmp, target);
+}
+export function globalPersonaDir(slug) {
+    return join(personaxisHome(), "personas", slug);
+}
+export function registerPersona(slug) {
+    const reg = loadRegistry();
+    const globalPath = join(globalPersonaDir(slug), "personaxis.md");
+    if (!reg.personas[slug]) {
+        reg.personas[slug] = { slug, globalPath, createdTs: new Date().toISOString() };
+    }
+    touchMachine(reg);
+    saveRegistry(reg);
+    return reg.personas[slug];
+}
+export function registerProject(root, slugs) {
+    const reg = loadRegistry();
+    const rec = {
+        root,
+        slugs,
+        lastSeen: new Date().toISOString(),
+        machine: machineId(),
+    };
+    reg.projects[root] = rec;
+    touchMachine(reg);
+    saveRegistry(reg);
+    return rec;
+}
+export function createCollection(name) {
+    const reg = loadRegistry();
+    reg.collections[name] ??= { name, personas: [], projects: [] };
+    saveRegistry(reg);
+    return reg.collections[name];
+}
+export function addToCollection(name, kind, value) {
+    const reg = loadRegistry();
+    const c = (reg.collections[name] ??= { name, personas: [], projects: [] });
+    const list = kind === "persona" ? c.personas : c.projects;
+    if (!list.includes(value))
+        list.push(value);
+    saveRegistry(reg);
+    return c;
+}
+// ─── Teams (operational, with roles + a shared goal) ────────────────────────
+export function createTeam(name, lead) {
+    const reg = loadRegistry();
+    reg.teams[name] ??= { name, lead, members: lead ? [{ slug: lead, role: "lead" }] : [], createdTs: new Date().toISOString() };
+    if (lead)
+        reg.teams[name].lead = lead;
+    saveRegistry(reg);
+    return reg.teams[name];
+}
+export function addTeamMember(name, slug, role) {
+    const reg = loadRegistry();
+    const t = (reg.teams[name] ??= { name, members: [], createdTs: new Date().toISOString() });
+    const existing = t.members.find((m) => m.slug === slug);
+    if (existing)
+        existing.role = role;
+    else
+        t.members.push({ slug, role });
+    if (role === "lead")
+        t.lead = slug;
+    saveRegistry(reg);
+    return t;
+}
+export function setTeamGoal(name, goal) {
+    const reg = loadRegistry();
+    const t = (reg.teams[name] ??= { name, members: [], createdTs: new Date().toISOString() });
+    t.goal = goal;
+    saveRegistry(reg);
+    return t;
+}
+export function getTeam(name) {
+    return loadRegistry().teams[name];
+}
+function touchMachine(reg) {
+    reg.machines[machineId()] = { lastSeen: new Date().toISOString(), os: platform() };
+}
+/**
+ * Resolve the effective persona path for a project + slug: a project-local
+ * overlay (project `.personaxis/personas/<slug>/personaxis.md` or root
+ * `.personaxis/personaxis.md`) takes precedence over the global persona.
+ * Returns the first existing path, or the global path as the default target.
+ */
+export function resolveEffectivePersona(projectRoot, slug) {
+    const candidates = slug
+        ? [
+            join(projectRoot, ".personaxis", "personas", slug, "personaxis.md"),
+            join(globalPersonaDir(slug), "personaxis.md"),
+        ]
+        : [join(projectRoot, ".personaxis", "personaxis.md")];
+    for (let i = 0; i < candidates.length; i++) {
+        if (existsSync(candidates[i])) {
+            return { path: candidates[i], scope: i === 0 && slug ? "project-overlay" : "global" };
+        }
+    }
+    return { path: candidates[candidates.length - 1], scope: "none" };
+}
+/** The overseer's situational summary of the whole environment. */
+export function overseerView() {
+    const reg = loadRegistry();
+    return {
+        machine: machineId(),
+        personas: Object.keys(reg.personas).length,
+        projects: Object.keys(reg.projects).length,
+        collections: Object.keys(reg.collections).length,
+        teams: Object.keys(reg.teams ?? {}).length,
+        machines: Object.keys(reg.machines).length,
+        detail: reg,
+    };
+}

package/dist/responder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Responder — the persona's conversational voice (what makes the REPL playable).
+ *
+ * The Living Loop governs *how the persona changes*; the Responder governs *what it
+ * says back*. They are separate on purpose: the appraiser emits structured evolution
+ * signals; the responder emits a natural-language reply, grounded in the compiled
+ * identity (PERSONA.md), recent memory, and current mood — and bound by the spec
+ * (never claims real feelings).
+ *
+ * `LlmResponder` talks to any OpenAI-compatible endpoint (Ollama/llama.cpp/hosted).
+ * `ReflectiveResponder` is an offline fallback: it doesn't fake a conversation, it
+ * gives an honest persona-flavored acknowledgement and points to enabling a model.
+ */
+export interface RespondInput {
+    message: string;
+    /** Compiled identity (PERSONA.md body) — system-prompt slot #1. */
+    personaBody: string;
+    /** Recent episodic memory lines for grounding (most recent last). */
+    memory: string[];
+    /** Current mood/affect values for tone. */
+    state: Record<string, number>;
+    /** Persona display name. */
+    name: string;
+}
+export interface Responder {
+    respond(input: RespondInput): Promise<string>;
+}
+export interface LlmResponderConfig {
+    endpoint: string;
+    model: string;
+    apiKey?: string;
+    maxTokens?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare class LlmResponder implements Responder {
+    private readonly cfg;
+    constructor(cfg: LlmResponderConfig);
+    respond(input: RespondInput): Promise<string>;
+}
+/**
+ * Offline fallback. It does NOT pretend to converse — it reflects the persona's
+ * current modeled tone honestly and nudges the user to enable a model for real
+ * dialogue. Deterministic, dependency-free.
+ */
+export declare class ReflectiveResponder implements Responder {
+    respond(input: RespondInput): Promise<string>;
+}

package/dist/responder.js

@@ -0,0 +1,78 @@
+/**
+ * Responder — the persona's conversational voice (what makes the REPL playable).
+ *
+ * The Living Loop governs *how the persona changes*; the Responder governs *what it
+ * says back*. They are separate on purpose: the appraiser emits structured evolution
+ * signals; the responder emits a natural-language reply, grounded in the compiled
+ * identity (PERSONA.md), recent memory, and current mood — and bound by the spec
+ * (never claims real feelings).
+ *
+ * `LlmResponder` talks to any OpenAI-compatible endpoint (Ollama/llama.cpp/hosted).
+ * `ReflectiveResponder` is an offline fallback: it doesn't fake a conversation, it
+ * gives an honest persona-flavored acknowledgement and points to enabling a model.
+ */
+const GUARD = "You are this persona. Speak in its voice, consistent with its identity, values, and current mood. " +
+    "You are an AI: never claim real human feelings or consciousness; you may describe your modeled affect as state. " +
+    "Be helpful and concise. Do not invent facts about the user.";
+export class LlmResponder {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async respond(input) {
+        const fetchImpl = this.cfg.fetchImpl ?? fetch;
+        const system = [
+            GUARD,
+            "",
+            "# Identity",
+            input.personaBody.slice(0, 6000),
+            "",
+            "# Current modeled state",
+            Object.entries(input.state)
+                .map(([k, v]) => `${k}=${v.toFixed(2)}`)
+                .join(", "),
+            input.memory.length ? "\n# Recent memory\n" + input.memory.slice(-6).join("\n") : "",
+        ].join("\n");
+        const 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({
+                model: this.cfg.model,
+                messages: [
+                    { role: "system", content: system },
+                    { role: "user", content: input.message },
+                ],
+                temperature: 0.7,
+                max_tokens: this.cfg.maxTokens ?? 512,
+            }),
+        });
+        if (!res.ok)
+            throw new Error(`responder HTTP ${res.status}`);
+        let json;
+        try {
+            json = (await res.json());
+        }
+        catch {
+            throw new Error("responder returned a non-JSON body");
+        }
+        const content = (json.choices?.[0]?.message?.content ?? "").trim();
+        return content || "(the model returned an empty reply — try rephrasing, or check the model/endpoint)";
+    }
+}
+/**
+ * Offline fallback. It does NOT pretend to converse — it reflects the persona's
+ * current modeled tone honestly and nudges the user to enable a model for real
+ * dialogue. Deterministic, dependency-free.
+ */
+export class ReflectiveResponder {
+    async respond(input) {
+        const tone = input.state["mood.tone"] ?? 0;
+        const mood = tone > 0.12 ? "upbeat" : tone < -0.12 ? "subdued" : "even";
+        return (`(${input.name}, modeled tone: ${mood}) I registered that and updated my state + memory. ` +
+            `I can't hold a full conversation without a model — set PERSONAXIS_ENDPOINT + PERSONAXIS_MODEL ` +
+            `(Ollama/llama.cpp) or BYOK to talk with me for real.`);
+    }
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Permission & sandbox policy (F3 / T9 — plan/11-security).
+ *
+ * Honest scope: real *kernel* sandboxing needs native primitives (macOS Seatbelt,
+ * Linux Landlock/seccomp/bubblewrap, Windows job objects / restricted tokens).
+ * This module provides two things that ARE doable cross-platform and that the big
+ * agents rely on most:
+ *
+ *   1. A two-axis POLICY ENGINE (approval × sandbox, the Codex model) that DECIDES
+ *      allow | ask | deny for a command — pure, deterministic, fully tested. This
+ *      is the load-bearing control: a denied command never runs.
+ *   2. A best-effort NATIVE WRAPPER that, when the command is allowed, wraps it
+ *      with the platform's available sandbox (sandbox-exec / bwrap) so writes and
+ *      network are constrained at the OS level where possible.
+ *
+ * If no native sandbox is available, enforcement degrades to the policy decision
+ * (deny-by-default for risky ops) — never a silent full-access fallback.
+ */
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export type ApprovalMode = "untrusted" | "on-failure" | "on-request" | "never";
+export interface Policy {
+    sandbox: SandboxMode;
+    approval: ApprovalMode;
+    /** Regexes (as strings) that force-allow a matching command. */
+    allow: string[];
+    /** Regexes that force-deny a matching command (highest precedence). */
+    deny: string[];
+    workspaceRoot: string;
+    /**
+     * FR.8: additional roots writable under `workspace-write` (the workspaceRoot
+     * is always one). Lets a host grant, e.g., a build output dir outside the repo
+     * without escalating to danger-full-access.
+     */
+    writableRoots?: string[];
+    /**
+     * FR.8: per-category approval overrides — finer than the single global
+     * `approval` knob (e.g. network commands always ask while plain writes flow).
+     */
+    approvals?: Partial<Record<"network" | "destructive" | "write", ApprovalMode>>;
+}
+export declare const DEFAULT_POLICY: Policy;
+/**
+ * FR.8 (Codex protocol.rs anti-escalation): subpaths that stay PROTECTED even
+ * inside a writable root. `.git/hooks` = arbitrary-code-execution escalation
+ * (a write there runs on the user's next git command); `.personaxis` = the
+ * persona's identity artifacts — raw file writes would bypass the governance
+ * ledger (self-edits are the sanctioned path). A deny here is NOT overridable
+ * by the allow-list (deny precedence).
+ */
+export declare const PROTECTED_SUBPATHS: readonly [".git/hooks", ".personaxis"];
+/** Named permission profiles (FR.8) — one word instead of four knobs. */
+export declare const PERMISSION_PROFILES: {
+    readonly strict: {
+        readonly sandbox: "read-only";
+        readonly approval: "untrusted";
+    };
+    readonly standard: {
+        readonly sandbox: "workspace-write";
+        readonly approval: "on-request";
+    };
+    readonly trusted: {
+        readonly sandbox: "workspace-write";
+        readonly approval: "on-failure";
+    };
+    readonly yolo: {
+        readonly sandbox: "danger-full-access";
+        readonly approval: "never";
+    };
+};
+export type PermissionProfile = keyof typeof PERMISSION_PROFILES;
+/** Build a Policy from a named profile (+ optional overrides). */
+export declare function policyFromProfile(profile: PermissionProfile, overrides?: Partial<Policy>): Policy;
+/** True when `p` lands inside a protected subpath of any writable root. */
+export declare function isProtectedPath(p: string, policy: Policy): boolean;
+/**
+ * v0.8: build a Policy from a persona's declared `permissions` block, so a persona
+ * carries its own sandbox posture to any host. Missing fields fall back to defaults.
+ */
+export declare function policyFromFrontmatter(frontmatter: Record<string, unknown>, workspaceRoot?: string): Policy;
+export interface CommandClass {
+    writesFiles: boolean;
+    network: boolean;
+    destructive: boolean;
+    escapesWorkspace: boolean;
+}
+/** Heuristically classify what a shell command would do. */
+export declare function classifyCommand(cmd: string, workspaceRoot: string): CommandClass;
+/** True if `p` resolves outside `root`. */
+export declare function pathEscapesWorkspace(p: string, root: string): boolean;
+export type Decision = "allow" | "ask" | "deny";
+export interface CommandVerdict {
+    decision: Decision;
+    reason: string;
+    class: CommandClass;
+}
+/**
+ * Decide allow | ask | deny for a command under a policy. Precedence:
+ * deny-list > sandbox hard limits > allow-list > approval mode.
+ */
+export declare function evaluateCommand(cmd: string, policy?: Policy): CommandVerdict;
+/**
+ * Decide allow | ask | deny for a FILE WRITE/EDIT under a policy. Mirrors
+ * evaluateCommand's precedence but for a path target (the agent's write_file /
+ * edit_file tools). Reuses pathEscapesWorkspace so a write that escapes the
+ * workspace is denied under workspace-write, exactly like a shell redirect would be.
+ */
+export declare function evaluateFileWrite(targetPath: string, policy?: Policy, opts?: {
+    destructive?: boolean;
+}): CommandVerdict;
+export interface WrapResult {
+    command: string;
+    args: string[];
+    sandbox: "seatbelt" | "bubblewrap" | "none";
+    note: string;
+}
+/**
+ * Best-effort native sandbox wrapping for an ALLOWED command. Caller is
+ * responsible for only wrapping commands that already passed evaluateCommand.
+ */
+export declare function wrapCommand(cmd: string, policy?: Policy): WrapResult;

package/dist/sandbox.js

@@ -0,0 +1,265 @@
+/**
+ * Permission & sandbox policy (F3 / T9 — plan/11-security).
+ *
+ * Honest scope: real *kernel* sandboxing needs native primitives (macOS Seatbelt,
+ * Linux Landlock/seccomp/bubblewrap, Windows job objects / restricted tokens).
+ * This module provides two things that ARE doable cross-platform and that the big
+ * agents rely on most:
+ *
+ *   1. A two-axis POLICY ENGINE (approval × sandbox, the Codex model) that DECIDES
+ *      allow | ask | deny for a command — pure, deterministic, fully tested. This
+ *      is the load-bearing control: a denied command never runs.
+ *   2. A best-effort NATIVE WRAPPER that, when the command is allowed, wraps it
+ *      with the platform's available sandbox (sandbox-exec / bwrap) so writes and
+ *      network are constrained at the OS level where possible.
+ *
+ * If no native sandbox is available, enforcement degrades to the policy decision
+ * (deny-by-default for risky ops) — never a silent full-access fallback.
+ */
+import { platform } from "node:os";
+import { isAbsolute, normalize, relative } from "node:path";
+export const DEFAULT_POLICY = {
+    sandbox: "workspace-write",
+    approval: "on-request",
+    allow: [],
+    deny: [],
+    workspaceRoot: process.cwd(),
+};
+/**
+ * FR.8 (Codex protocol.rs anti-escalation): subpaths that stay PROTECTED even
+ * inside a writable root. `.git/hooks` = arbitrary-code-execution escalation
+ * (a write there runs on the user's next git command); `.personaxis` = the
+ * persona's identity artifacts — raw file writes would bypass the governance
+ * ledger (self-edits are the sanctioned path). A deny here is NOT overridable
+ * by the allow-list (deny precedence).
+ */
+export const PROTECTED_SUBPATHS = [".git/hooks", ".personaxis"];
+/** Named permission profiles (FR.8) — one word instead of four knobs. */
+export const PERMISSION_PROFILES = {
+    strict: { sandbox: "read-only", approval: "untrusted" },
+    standard: { sandbox: "workspace-write", approval: "on-request" },
+    trusted: { sandbox: "workspace-write", approval: "on-failure" },
+    yolo: { sandbox: "danger-full-access", approval: "never" },
+};
+/** Build a Policy from a named profile (+ optional overrides). */
+export function policyFromProfile(profile, overrides = {}) {
+    return { ...DEFAULT_POLICY, ...PERMISSION_PROFILES[profile], ...overrides };
+}
+/** True when `p` lands inside a protected subpath of any writable root. */
+export function isProtectedPath(p, policy) {
+    const roots = [policy.workspaceRoot, ...(policy.writableRoots ?? [])];
+    const abs = isAbsolute(p) ? normalize(p) : normalize(`${policy.workspaceRoot}/${p}`);
+    for (const root of roots) {
+        for (const sub of PROTECTED_SUBPATHS) {
+            const guard = normalize(`${root}/${sub}`);
+            const rel = relative(guard, abs);
+            if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * v0.8: build a Policy from a persona's declared `permissions` block, so a persona
+ * carries its own sandbox posture to any host. Missing fields fall back to defaults.
+ */
+export function policyFromFrontmatter(frontmatter, workspaceRoot = process.cwd()) {
+    const p = (frontmatter.permissions ?? {});
+    const sandbox = p.sandbox === "read-only" || p.sandbox === "workspace-write" || p.sandbox === "danger-full-access"
+        ? p.sandbox
+        : DEFAULT_POLICY.sandbox;
+    const approval = p.approval === "untrusted" || p.approval === "on-failure" || p.approval === "on-request" || p.approval === "never"
+        ? p.approval
+        : DEFAULT_POLICY.approval;
+    return {
+        sandbox,
+        approval,
+        allow: Array.isArray(p.allow) ? p.allow.filter((x) => typeof x === "string") : [],
+        deny: Array.isArray(p.deny) ? p.deny.filter((x) => typeof x === "string") : [],
+        workspaceRoot,
+    };
+}
+const NETWORK = /\b(curl|wget|nc|ncat|ssh|scp|telnet|ftp|rsync)\b|\bnpm\s+(install|i|publish)\b|\bpip\s+install\b/i;
+const WRITE = />>?|\b(rm|mv|cp|mkdir|touch|tee|dd|truncate|chmod|chown|ln)\b/i;
+const DESTRUCTIVE = /\brm\s+-[a-z]*f|\b(mkfs|fdisk|shred|:\(\)\s*\{)/i;
+/**
+ * A leading-slash token that is really a Windows/CLI SWITCH, not a filesystem path
+ * (e.g. `/t`, `/c`, `/s`, `/?`, `/all`, `/b`). Real escaping paths look like
+ * `/etc/passwd`, `/usr`, `/tmp`, `~/x`, `../x`. We exclude switch-shaped tokens so
+ * harmless commands like `date /t` or `dir /s` aren't misflagged as workspace escapes.
+ */
+function isCliSwitch(tok) {
+    return /^\/(\?|[a-zA-Z]{1,3}(:[A-Za-z0-9_-]+)?)$/.test(tok);
+}
+/** Heuristically classify what a shell command would do. */
+export function classifyCommand(cmd, workspaceRoot) {
+    const writesFiles = WRITE.test(cmd);
+    const network = NETWORK.test(cmd);
+    const destructive = DESTRUCTIVE.test(cmd);
+    const escapesWorkspace = (cmd.match(/(?:^|\s)(\/[^\s'"]+|[~][^\s'"]*|\.\.\/[^\s'"]*)/g) ?? [])
+        .map((tok) => tok.trim())
+        .filter((tok) => !isCliSwitch(tok))
+        .some((tok) => pathEscapesWorkspace(tok, workspaceRoot));
+    return { writesFiles, network, destructive, escapesWorkspace };
+}
+/** True if `p` resolves outside `root`. */
+export function pathEscapesWorkspace(p, root) {
+    if (p.startsWith("~"))
+        return true;
+    if (!isAbsolute(p) && !p.startsWith(".."))
+        return false;
+    const rel = relative(normalize(root), normalize(isAbsolute(p) ? p : `${root}/${p}`));
+    return rel.startsWith("..") || isAbsolute(rel);
+}
+function matchesAny(patterns, cmd) {
+    return patterns.some((p) => {
+        try {
+            return new RegExp(p).test(cmd);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Decide allow | ask | deny for a command under a policy. Precedence:
+ * deny-list > sandbox hard limits > allow-list > approval mode.
+ */
+export function evaluateCommand(cmd, policy = DEFAULT_POLICY) {
+    const klass = classifyCommand(cmd, policy.workspaceRoot);
+    if (matchesAny(policy.deny, cmd)) {
+        return { decision: "deny", reason: "matches deny-list", class: klass };
+    }
+    // danger-full-access = explicit YOLO: allow everything the deny-list didn't block, with NO
+    // approval prompt. This is what makes the posture meaningfully different from workspace-write
+    // (which still asks for risky ops) and consistent with wrapCommand's "full access (no wrapping)".
+    if (policy.sandbox === "danger-full-access") {
+        return { decision: "allow", reason: "danger-full-access (no restrictions except deny-list)", class: klass };
+    }
+    // Sandbox hard limits (independent of approval).
+    if (policy.sandbox === "read-only" && (klass.writesFiles || klass.network)) {
+        return { decision: "deny", reason: "read-only sandbox forbids writes/network", class: klass };
+    }
+    if (policy.sandbox === "workspace-write") {
+        if (klass.escapesWorkspace && klass.writesFiles) {
+            return { decision: "deny", reason: "write escapes the workspace", class: klass };
+        }
+        if (klass.destructive) {
+            return { decision: "deny", reason: "destructive command blocked under workspace-write", class: klass };
+        }
+    }
+    if (matchesAny(policy.allow, cmd)) {
+        return { decision: "allow", reason: "matches allow-list", class: klass };
+    }
+    // Approval mode governs the residual risk. FR.8: a per-category override
+    // (approvals.network/destructive/write) takes precedence over the global
+    // knob for commands of that class — most-specific-first, strictest-wins
+    // when a command falls in several categories.
+    const risky = klass.writesFiles || klass.network || klass.destructive || klass.escapesWorkspace;
+    const effective = effectiveApproval(policy, klass);
+    switch (effective) {
+        case "never":
+            return { decision: "allow", reason: "approval=never", class: klass };
+        case "on-failure":
+            return { decision: "allow", reason: "approval=on-failure (pre-approved)", class: klass };
+        case "on-request":
+            return risky
+                ? { decision: "ask", reason: "risky op needs approval", class: klass }
+                : { decision: "allow", reason: "read-only op", class: klass };
+        case "untrusted":
+        default:
+            return risky
+                ? { decision: "ask", reason: "untrusted: confirm any risky op", class: klass }
+                : { decision: "allow", reason: "read-only op", class: klass };
+    }
+}
+/** Strictness order for approval modes (stricter = later). */
+const APPROVAL_STRICTNESS = ["never", "on-failure", "on-request", "untrusted"];
+/** FR.8: resolve the approval mode for a classified command (strictest category wins). */
+function effectiveApproval(policy, klass) {
+    const candidates = [policy.approval];
+    const a = policy.approvals;
+    if (a) {
+        if (klass.network && a.network)
+            candidates.push(a.network);
+        if (klass.destructive && a.destructive)
+            candidates.push(a.destructive);
+        if (klass.writesFiles && a.write)
+            candidates.push(a.write);
+    }
+    return candidates.reduce((strictest, m) => APPROVAL_STRICTNESS.indexOf(m) > APPROVAL_STRICTNESS.indexOf(strictest) ? m : strictest);
+}
+/**
+ * Decide allow | ask | deny for a FILE WRITE/EDIT under a policy. Mirrors
+ * evaluateCommand's precedence but for a path target (the agent's write_file /
+ * edit_file tools). Reuses pathEscapesWorkspace so a write that escapes the
+ * workspace is denied under workspace-write, exactly like a shell redirect would be.
+ */
+export function evaluateFileWrite(targetPath, policy = DEFAULT_POLICY, opts = {}) {
+    // FR.8: writable under workspace-write ⇔ inside ANY writable root.
+    const roots = [policy.workspaceRoot, ...(policy.writableRoots ?? [])];
+    const klass = {
+        writesFiles: true,
+        network: false,
+        destructive: Boolean(opts.destructive),
+        escapesWorkspace: roots.every((r) => pathEscapesWorkspace(targetPath, r)),
+    };
+    // Anti-escalation guard FIRST — not even the allow-list overrides it.
+    if (isProtectedPath(targetPath, policy)) {
+        return {
+            decision: "deny",
+            reason: "protected subpath (.git/hooks = code-execution escalation; .personaxis = governed identity artifacts — use the sanctioned edit tools)",
+            class: klass,
+        };
+    }
+    if (matchesAny(policy.deny, targetPath)) {
+        return { decision: "deny", reason: "path matches deny-list", class: klass };
+    }
+    // danger-full-access = explicit YOLO: writes are allowed without an approval prompt (only the
+    // deny-list still blocks). Mirrors evaluateCommand so cycling to this posture is meaningful.
+    if (policy.sandbox === "danger-full-access") {
+        return { decision: "allow", reason: "danger-full-access (writes allowed, deny-list still applies)", class: klass };
+    }
+    if (policy.sandbox === "read-only") {
+        return { decision: "deny", reason: "read-only sandbox forbids writes", class: klass };
+    }
+    if (policy.sandbox === "workspace-write" && klass.escapesWorkspace) {
+        return { decision: "deny", reason: "write escapes the workspace", class: klass };
+    }
+    if (matchesAny(policy.allow, targetPath)) {
+        return { decision: "allow", reason: "path matches allow-list", class: klass };
+    }
+    switch (policy.approval) {
+        case "never":
+        case "on-failure":
+            return { decision: "allow", reason: `approval=${policy.approval}`, class: klass };
+        case "on-request":
+        case "untrusted":
+        default:
+            return { decision: "ask", reason: "file write needs approval", class: klass };
+    }
+}
+/**
+ * Best-effort native sandbox wrapping for an ALLOWED command. Caller is
+ * responsible for only wrapping commands that already passed evaluateCommand.
+ */
+export function wrapCommand(cmd, policy = DEFAULT_POLICY) {
+    const os = platform();
+    if (policy.sandbox === "danger-full-access") {
+        return { command: "sh", args: ["-c", cmd], sandbox: "none", note: "full access (no wrapping)" };
+    }
+    if (os === "darwin") {
+        // macOS Seatbelt: deny network, allow workspace writes only.
+        const profile = `(version 1)(allow default)` +
+            (policy.sandbox === "read-only" ? `(deny file-write*)` : `(allow file-write* (subpath "${policy.workspaceRoot}"))(deny file-write*)`) +
+            `(deny network*)`;
+        return { command: "sandbox-exec", args: ["-p", profile, "sh", "-c", cmd], sandbox: "seatbelt", note: "macOS Seatbelt profile" };
+    }
+    if (os === "linux") {
+        // Linux bubblewrap: read-only bind of /, writable workspace, no network.
+        const args = ["--ro-bind", "/", "/", "--bind", policy.workspaceRoot, policy.workspaceRoot, "--unshare-net", "--dev", "/dev", "sh", "-c", cmd];
+        return { command: "bwrap", args, sandbox: "bubblewrap", note: "Linux bubblewrap (requires bwrap on PATH)" };
+    }
+    // Windows / other: no portable kernel sandbox here; rely on the policy decision.
+    return { command: "sh", args: ["-c", cmd], sandbox: "none", note: `${os}: no native sandbox wrapper; policy decision is the control` };
+}