agent-lyceum 0.4.9

package/dist/message-store.d.ts

@@ -0,0 +1,91 @@
+export declare function setFaultHook(fn: ((step: string) => void) | undefined): void;
+export declare function fault(step: string): void;
+export declare const mailDir: (runDir: string) => string;
+export interface JournalEntry {
+    source: string;
+    to: string;
+    msg_id: string;
+    /** Inbox file name chosen when the delivery was planned, so a retry writes the same file. */
+    file: string;
+    created: string;
+    delivered: boolean;
+}
+/** Append-only log of deliveries. A delivery is identified by `(source, recipient)`, never by a random id. */
+export declare class RouteJournal {
+    private readonly file;
+    private readonly entries;
+    constructor(runDir: string);
+    get(source: string, to: string): JournalEntry | undefined;
+    private append;
+    intent(e: Omit<JournalEntry, "delivered">): JournalEntry;
+    delivered(source: string, to: string): void;
+}
+/** Stable id of one outbox file instance: who wrote it, its name, when, and what it said. */
+export declare function sourceIdOf(sender: string, file: string): string;
+export declare function deterministicId(sourceKey: string, to: string): string;
+export type ClaimStatus = "claimed" | "output_ready" | "committed" | "abandoned";
+export interface ClaimRecord {
+    id: string;
+    agent: string;
+    message_ids: string[];
+    files: string[];
+    status: ClaimStatus;
+    created: string;
+}
+export declare function loadClaim(runDir: string, id: string): ClaimRecord;
+/** Record that `agent` is about to handle these messages. They stay unread until `commitClaim`. */
+export declare function claimMessages(runDir: string, agent: string, messages: {
+    file: string;
+    meta: {
+        id: string;
+    };
+}[]): ClaimRecord;
+/** The wake-up was stopped before it finished: its input stays unread and will be handled again. */
+export declare function abandonClaim(runDir: string, claimId: string): void;
+/** The wake-up finished and left its output in the outbox; from here on the output is routed, not redone. */
+export declare function markOutputReady(runDir: string, claimId: string): void;
+/** Mark the claim committed, then move its input to `read/`. Safe to repeat after a crash. */
+export declare function commitClaim(runDir: string, claimId: string): void;
+export type AttemptStatus = "started" | "output_ready" | "committed" | "failed";
+export interface AttemptRecord {
+    /** `<claim id>-a<n>` */
+    id: string;
+    claim_id: string;
+    agent: string;
+    n: number;
+    status: AttemptStatus;
+    started_at: string;
+    finished_at?: string;
+    error?: string;
+    /** Outbox files set aside because this attempt did not succeed. */
+    parked?: string[];
+}
+export declare const attemptLogDir: (runDir: string, id: string) => string;
+export declare const attemptOutboxDir: (runDir: string, id: string) => string;
+export declare function loadAttempt(runDir: string, id: string): AttemptRecord;
+export declare function listAttempts(runDir: string): AttemptRecord[];
+/** Start the next attempt for a claim (a1, a2, ...). */
+export declare function beginAttempt(runDir: string, claimId: string): AttemptRecord;
+export declare function finishAttempt(runDir: string, attemptId: string, status: Exclude<AttemptStatus, "started">, extra?: {
+    error?: string;
+    parked?: string[];
+}): AttemptRecord;
+/** Move whatever is in an agent's outbox into the attempt's own folder, so it can never be mistaken for a later attempt's result. */
+export declare function parkOutbox(runDir: string, outbox: string, attemptId: string): string[];
+export interface RecoveryReport {
+    /** Committed claims whose input had not been moved to `read/` yet; now it has. */
+    finalized: string[];
+    /** Claims that never produced output; their input stays unread and will be handled again. */
+    abandoned: ClaimRecord[];
+    /** Claims whose wake-up finished but whose output was not fully routed yet; the caller routes, then commits them. */
+    ready: ClaimRecord[];
+    /** Attempts that were running when the process died: failed now, their outbox set aside. External side effects may have happened. */
+    interrupted: {
+        attempt: AttemptRecord;
+        parked: string[];
+    }[];
+}
+/** Bring a run's claims back to a consistent state. Call before waking anyone on resume. */
+export declare function recoverRunMail(runDir: string, opts?: {
+    outboxOf?: (agent: string) => string;
+}): RecoveryReport;

package/dist/message-store.js

@@ -0,0 +1,225 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+/** Test seam: called after every durable step of routing and claim commits, so a test can "kill the process" there. */
+let faultHook;
+export function setFaultHook(fn) {
+    faultHook = fn;
+}
+export function fault(step) {
+    faultHook?.(step);
+}
+export const mailDir = (runDir) => path.join(runDir, "mail");
+/** Append-only log of deliveries. A delivery is identified by `(source, recipient)`, never by a random id. */
+export class RouteJournal {
+    file;
+    entries = new Map();
+    constructor(runDir) {
+        this.file = path.join(mailDir(runDir), "journal.jsonl");
+        let text = "";
+        try {
+            text = fs.readFileSync(this.file, "utf8");
+        }
+        catch {
+            return;
+        }
+        for (const line of text.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const j = JSON.parse(line);
+                const key = `${j.source}\u0000${j.to}`;
+                if (j.t === "intent")
+                    this.entries.set(key, { source: j.source, to: j.to, msg_id: j.msg_id, file: j.file, created: j.created, delivered: false });
+                else if (j.t === "delivered") {
+                    const e = this.entries.get(key);
+                    if (e)
+                        e.delivered = true;
+                }
+            }
+            catch {
+                /* a line cut short by a crash: ignore it */
+            }
+        }
+    }
+    get(source, to) {
+        return this.entries.get(`${source}\u0000${to}`);
+    }
+    append(obj) {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+        const fd = fs.openSync(this.file, "a");
+        try {
+            fs.writeSync(fd, JSON.stringify(obj) + "\n");
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    intent(e) {
+        this.append({ t: "intent", ...e });
+        const entry = { ...e, delivered: false };
+        this.entries.set(`${e.source}\u0000${e.to}`, entry);
+        return entry;
+    }
+    delivered(source, to) {
+        this.append({ t: "delivered", source, to });
+        const e = this.entries.get(`${source}\u0000${to}`);
+        if (e)
+            e.delivered = true;
+    }
+}
+/** Stable id of one outbox file instance: who wrote it, its name, when, and what it said. */
+export function sourceIdOf(sender, file) {
+    const st = fs.statSync(file);
+    return crypto
+        .createHash("sha256")
+        .update(`${sender}\0${path.basename(file)}\0${Math.round(st.mtimeMs)}\0`)
+        .update(fs.readFileSync(file))
+        .digest("hex")
+        .slice(0, 16);
+}
+export function deterministicId(sourceKey, to) {
+    return crypto.createHash("sha256").update(`${sourceKey}\0${to}`).digest("hex").slice(0, 8);
+}
+const claimFile = (runDir, id) => path.join(mailDir(runDir), "claims", `${id}.json`);
+function saveClaim(runDir, c) {
+    atomicWrite(claimFile(runDir, c.id), JSON.stringify(c, null, 2));
+}
+export function loadClaim(runDir, id) {
+    return JSON.parse(fs.readFileSync(claimFile(runDir, id), "utf8"));
+}
+/** Record that `agent` is about to handle these messages. They stay unread until `commitClaim`. */
+export function claimMessages(runDir, agent, messages) {
+    const rec = {
+        id: `${Date.now().toString(36)}-${agent}-${crypto.randomBytes(3).toString("hex")}`,
+        agent,
+        message_ids: messages.map((m) => m.meta.id),
+        files: messages.map((m) => m.file),
+        status: "claimed",
+        created: new Date().toISOString(),
+    };
+    saveClaim(runDir, rec);
+    return rec;
+}
+/** The wake-up was stopped before it finished: its input stays unread and will be handled again. */
+export function abandonClaim(runDir, claimId) {
+    const c = loadClaim(runDir, claimId);
+    if (c.status === "claimed" || c.status === "output_ready")
+        saveClaim(runDir, { ...c, status: "abandoned" });
+}
+/** The wake-up finished and left its output in the outbox; from here on the output is routed, not redone. */
+export function markOutputReady(runDir, claimId) {
+    const c = loadClaim(runDir, claimId);
+    if (c.status === "claimed")
+        saveClaim(runDir, { ...c, status: "output_ready" });
+}
+function moveToRead(file) {
+    if (!fs.existsSync(file))
+        return false;
+    const dest = path.join(path.dirname(file), "read", path.basename(file));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.renameSync(file, dest);
+    return true;
+}
+/** Mark the claim committed, then move its input to `read/`. Safe to repeat after a crash. */
+export function commitClaim(runDir, claimId) {
+    const c = loadClaim(runDir, claimId);
+    if (c.status !== "committed")
+        saveClaim(runDir, { ...c, status: "committed" });
+    fault("claim:marked");
+    for (const f of c.files) {
+        moveToRead(f);
+        fault("claim:moved");
+    }
+}
+const attemptFile = (runDir, id) => path.join(mailDir(runDir), "attempts", `${id}.json`);
+export const attemptLogDir = (runDir, id) => path.join(mailDir(runDir), "attempts", id, "log");
+export const attemptOutboxDir = (runDir, id) => path.join(mailDir(runDir), "attempts", id, "outbox");
+function saveAttempt(runDir, a) {
+    atomicWrite(attemptFile(runDir, a.id), JSON.stringify(a, null, 2));
+}
+export function loadAttempt(runDir, id) {
+    return JSON.parse(fs.readFileSync(attemptFile(runDir, id), "utf8"));
+}
+export function listAttempts(runDir) {
+    const dir = path.join(mailDir(runDir), "attempts");
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of fs.readdirSync(dir).filter((x) => x.endsWith(".json")).sort()) {
+        try {
+            out.push(JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")));
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return out;
+}
+/** Start the next attempt for a claim (a1, a2, ...). */
+export function beginAttempt(runDir, claimId) {
+    const claim = loadClaim(runDir, claimId);
+    const n = listAttempts(runDir).filter((a) => a.claim_id === claimId).length + 1;
+    const rec = { id: `${claimId}-a${n}`, claim_id: claimId, agent: claim.agent, n, status: "started", started_at: new Date().toISOString() };
+    saveAttempt(runDir, rec);
+    return rec;
+}
+export function finishAttempt(runDir, attemptId, status, extra = {}) {
+    const rec = { ...loadAttempt(runDir, attemptId), status, finished_at: new Date().toISOString(), ...extra };
+    saveAttempt(runDir, rec);
+    return rec;
+}
+/** Move whatever is in an agent's outbox into the attempt's own folder, so it can never be mistaken for a later attempt's result. */
+export function parkOutbox(runDir, outbox, attemptId) {
+    if (!fs.existsSync(outbox))
+        return [];
+    const moved = [];
+    const dest = attemptOutboxDir(runDir, attemptId);
+    for (const e of fs.readdirSync(outbox, { withFileTypes: true })) {
+        if (!e.isFile() || e.name.startsWith("."))
+            continue;
+        fs.mkdirSync(dest, { recursive: true });
+        fs.renameSync(path.join(outbox, e.name), path.join(dest, e.name));
+        moved.push(e.name);
+    }
+    return moved;
+}
+/** Bring a run's claims back to a consistent state. Call before waking anyone on resume. */
+export function recoverRunMail(runDir, opts = {}) {
+    const report = { finalized: [], abandoned: [], ready: [], interrupted: [] };
+    for (const a of listAttempts(runDir)) {
+        if (a.status !== "started")
+            continue;
+        const parked = opts.outboxOf ? parkOutbox(runDir, opts.outboxOf(a.agent), a.id) : [];
+        const done = finishAttempt(runDir, a.id, "failed", { error: "interrupted", parked });
+        report.interrupted.push({ attempt: done, parked });
+    }
+    const dir = path.join(mailDir(runDir), "claims");
+    if (!fs.existsSync(dir))
+        return report;
+    for (const name of fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort()) {
+        let c;
+        try {
+            c = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (c.status === "committed") {
+            let moved = false;
+            for (const f of c.files)
+                moved = moveToRead(f) || moved;
+            if (moved)
+                report.finalized.push(c.id);
+        }
+        else if (c.status === "claimed") {
+            saveClaim(runDir, { ...c, status: "abandoned" });
+            report.abandoned.push({ ...c, status: "abandoned" });
+        }
+        else if (c.status === "output_ready")
+            report.ready.push(c);
+    }
+    return report;
+}

package/dist/paths.d.ts

@@ -0,0 +1,30 @@
+export declare const NAME_RE: RegExp;
+export declare function expandHome(p: string): string;
+/** Resolve a path from a config file: expand `~`, then resolve relative to `base`. */
+export declare function absPath(p: string, base: string): string;
+export declare function resolveHome(opt?: string): string;
+export declare function assertName(kind: string, name: string): void;
+export interface HomePaths {
+    home: string;
+    globalConfig: string;
+    globalAgentsDir: string;
+    projectsDir: string;
+}
+export declare function homePaths(home: string): HomePaths;
+export interface ProjectPaths {
+    root: string;
+    config: string;
+    agentsDir: string;
+    shared: string;
+    common: string;
+    inboxRoot: string;
+    outboxRoot: string;
+    runs: string;
+    /** Per-task memory: <taskMemory>/<run-id>/<agent>. Never shared between runs. */
+    taskMemory: string;
+}
+export declare function projectPaths(home: string, project: string): ProjectPaths;
+/** True when `child` is `parent` or inside it. */
+export declare function isInside(parent: string, child: string): boolean;
+/** Directory part of a glob that precedes the first wildcard segment. */
+export declare function globStaticPrefix(glob: string): string;

package/dist/paths.js

@@ -0,0 +1,62 @@
+import os from "node:os";
+import path from "node:path";
+export const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+export function expandHome(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+/** Resolve a path from a config file: expand `~`, then resolve relative to `base`. */
+export function absPath(p, base) {
+    return path.resolve(base, expandHome(p));
+}
+export function resolveHome(opt) {
+    const raw = opt ?? process.env.AGENT_LYCEUM_HOME ?? path.join(os.homedir(), "agent-lyceum-config");
+    return path.resolve(expandHome(raw));
+}
+export function assertName(kind, name) {
+    if (!NAME_RE.test(name)) {
+        throw new Error(`Invalid ${kind} name "${name}": use letters, digits, "-" or "_" (must not start with "-" or "_").`);
+    }
+}
+export function homePaths(home) {
+    return {
+        home,
+        globalConfig: path.join(home, "team.yaml"),
+        globalAgentsDir: path.join(home, "agents"),
+        projectsDir: path.join(home, "projects"),
+    };
+}
+export function projectPaths(home, project) {
+    const root = path.join(home, "projects", project);
+    const shared = path.join(root, "shared");
+    return {
+        root,
+        config: path.join(root, "project.yaml"),
+        agentsDir: path.join(root, "agents"),
+        shared,
+        common: path.join(shared, "COMMON.md"),
+        inboxRoot: path.join(shared, "inbox"),
+        outboxRoot: path.join(shared, "outbox"),
+        runs: path.join(root, "runs"),
+        taskMemory: path.join(root, "task-memory"),
+    };
+}
+/** True when `child` is `parent` or inside it. */
+export function isInside(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/** Directory part of a glob that precedes the first wildcard segment. */
+export function globStaticPrefix(glob) {
+    const segs = glob.split("/");
+    const out = [];
+    for (const s of segs) {
+        if (/[*?[\]{}]/.test(s))
+            break;
+        out.push(s);
+    }
+    return out.join("/");
+}

package/dist/policy.d.ts

@@ -0,0 +1,38 @@
+import type { ResolvedAgent, ResolvedProject } from "./config.js";
+export type Level = "os" | "tool-rules" | "post-hoc" | "prompt-only" | "n/a";
+export interface AgentEnforcement {
+    agent: string;
+    runtime: string;
+    memory: Level;
+    agentMd: Level;
+    otherContext: Level;
+    repoInstructions: Level;
+    owns: Level;
+    /** Absolute paths outside the repo this agent may write. */
+    writablePaths: string[];
+    notes: string[];
+}
+export interface WritePolicy {
+    /** Directories the agent may write to (besides the repo). */
+    allowDirs: string[];
+    /** Individual files the agent may write (outside allowDirs). */
+    allowFiles: string[];
+    /** Files/dirs that must stay unwritable (checked even inside the repo). */
+    deny: string[];
+    /** Repo-relative globs the agent owns (only enforced when max_parallel > 1). */
+    owns: string[];
+    restrictRepoToOwns: boolean;
+}
+export declare function commonFile(project: ResolvedProject): string;
+export declare function outboxDir(project: ResolvedProject, agent: string): string;
+export declare function inboxDir(project: ResolvedProject, agent: string): string;
+export declare function repoInstructionFiles(project: ResolvedProject): string[];
+export declare function memoryDirs(a: ResolvedAgent): string[];
+/** The repo directory this agent works in: its own worktree, or the main repo. */
+export declare function repoDirFor(project: ResolvedProject, agent: string): string;
+export declare function writePolicy(project: ResolvedProject, agent: ResolvedAgent): WritePolicy;
+export declare function enforcementFor(project: ResolvedProject, agent: ResolvedAgent): AgentEnforcement;
+/** Static directory prefixes (absolute) of an agent's `owns` globs. */
+export declare function ownsDirs(project: ResolvedProject, agent: ResolvedAgent): string[];
+/** Can `agent` legitimately change this protected file? */
+export declare function mayEditProtected(project: ResolvedProject, agent: ResolvedAgent, file: string): boolean;

package/dist/policy.js

@@ -0,0 +1,143 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { globStaticPrefix } from "./paths.js";
+export function commonFile(project) {
+    return path.join(project.paths.shared, "common", "COMMON.md");
+}
+export function outboxDir(project, agent) {
+    return path.join(project.paths.outboxRoot, agent);
+}
+export function inboxDir(project, agent) {
+    return path.join(project.paths.inboxRoot, agent);
+}
+export function repoInstructionFiles(project) {
+    return [path.join(project.dir, "CLAUDE.md"), path.join(project.dir, "AGENTS.md")];
+}
+export function memoryDirs(a) {
+    return [a.memory.global, a.memory.project, a.memory.task].filter((x) => !!x);
+}
+const RUN_ENTRIES = ["state.json", "log.jsonl", "result.md", "task.md", "snapshots", "agents", "mail"];
+const MAIL_ENTRIES = ["inbox", "claims", "attempts", "journal.jsonl"];
+function entries(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The run records agents must not write. A run's mailboxes sit inside its run dir, and a deny on a parent would
+ * beat the allow on an agent's own outbox, so the run dir is denied entry by entry instead of as a whole.
+ */
+function runDenyPaths(project) {
+    const runs = project.paths.runs;
+    if (project.run?.layout !== "run")
+        return [runs];
+    const runDir = project.run.dir;
+    const mail = path.join(runDir, "mail");
+    const unique = (xs) => [...new Set(xs)];
+    return unique([
+        ...entries(runs).filter((e) => e !== project.run.id).map((e) => path.join(runs, e)),
+        ...[...RUN_ENTRIES, ...entries(runDir)].filter((e) => e !== "mail").map((e) => path.join(runDir, e)),
+        ...[...MAIL_ENTRIES, ...entries(mail)].filter((e) => e !== "outbox").map((e) => path.join(mail, e)),
+    ]);
+}
+/** The repo directory this agent works in: its own worktree, or the main repo. */
+export function repoDirFor(project, agent) {
+    return project.workspaces?.[agent]?.dir ?? project.dir;
+}
+export function writePolicy(project, agent) {
+    const isLead = agent.name === project.lead;
+    const ws = project.workspaces?.[agent.name];
+    const allowDirs = [...memoryDirs(agent), outboxDir(project, agent.name), ...(ws ? [ws.gitDir] : [])];
+    const allowFiles = [];
+    if (isLead)
+        allowFiles.push(commonFile(project));
+    if (agent.canEditAgentMd) {
+        for (const a of Object.values(project.agents))
+            allowFiles.push(a.agentMd);
+        allowFiles.push(...repoInstructionFiles(project));
+    }
+    const deny = [];
+    const allowedFileSet = new Set(allowFiles);
+    const addDeny = (p) => {
+        if (!allowedFileSet.has(p))
+            deny.push(p);
+    };
+    for (const a of Object.values(project.agents)) {
+        addDeny(a.agentMd);
+        if (a.name !== agent.name)
+            for (const m of memoryDirs(a))
+                deny.push(m);
+        if (a.name !== agent.name)
+            deny.push(outboxDir(project, a.name));
+        deny.push(inboxDir(project, a.name));
+    }
+    addDeny(commonFile(project));
+    for (const f of repoInstructionFiles(project))
+        addDeny(f);
+    deny.push(...runDenyPaths(project), project.paths.config, path.join(project.home, "team.yaml"));
+    // In a worktree: other agents' checkouts are off limits, and so are this checkout's own copies of the protected files.
+    for (const [name, other] of Object.entries(project.workspaces ?? {}))
+        if (name !== agent.name)
+            deny.push(other.root);
+    if (ws)
+        for (const f of ["CLAUDE.md", "AGENTS.md"])
+            addDeny(path.join(ws.dir, f));
+    return {
+        allowDirs,
+        allowFiles,
+        deny: [...new Set(deny)],
+        owns: agent.owns,
+        restrictRepoToOwns: project.dispatcher.max_parallel > 1 && agent.owns.length > 0 && !isLead,
+    };
+}
+let sandboxProbe;
+function osSandboxAvailable() {
+    if (sandboxProbe !== undefined)
+        return sandboxProbe;
+    if (process.platform === "darwin")
+        sandboxProbe = true;
+    else if (process.platform === "linux")
+        sandboxProbe = spawnSync("which", ["bwrap"]).status === 0;
+    else
+        sandboxProbe = false;
+    return sandboxProbe;
+}
+export function enforcementFor(project, agent) {
+    const pol = writePolicy(project, agent);
+    const os = osSandboxAvailable();
+    const notes = [];
+    const parallel = project.dispatcher.max_parallel > 1;
+    let e;
+    if (agent.runtime === "claude-code") {
+        const lvl = os ? "os" : "tool-rules";
+        e = { memory: lvl, agentMd: lvl, otherContext: lvl, repoInstructions: lvl, owns: parallel ? "tool-rules" : "n/a" };
+        if (!os)
+            notes.push("OS sandbox unavailable (Windows, or Linux without bubblewrap): Bash can bypass Edit rules.");
+    }
+    else {
+        const lvl = os ? "os" : "prompt-only";
+        e = { memory: lvl, agentMd: lvl, otherContext: lvl, repoInstructions: "post-hoc", owns: parallel ? "prompt-only" : "n/a" };
+        notes.push("Codex cannot forbid single files inside the repo; CLAUDE.md/AGENTS.md changes are detected and reverted after each wake-up.");
+        if (agent.canEditAgentMd)
+            notes.push("can_edit_agent_md widens Codex writable roots to whole agent directories.");
+    }
+    return {
+        agent: agent.name,
+        runtime: agent.runtime ?? "?",
+        ...e,
+        writablePaths: [...pol.allowDirs, ...pol.allowFiles.filter((f) => !f.startsWith(project.dir + path.sep))],
+        notes,
+    };
+}
+/** Static directory prefixes (absolute) of an agent's `owns` globs. */
+export function ownsDirs(project, agent) {
+    return agent.owns.map((g) => path.join(project.dir, globStaticPrefix(g)));
+}
+/** Can `agent` legitimately change this protected file? */
+export function mayEditProtected(project, agent, file) {
+    return writePolicy(project, agent).allowFiles.includes(file);
+}

package/dist/process-runner.d.ts

@@ -0,0 +1,21 @@
+import type { Invocation, WakeResult } from "./adapters/types.js";
+/** Most output kept in memory per stream; the rest only goes to the log files. */
+export declare const TAIL_BYTES: number;
+/** A stdout line longer than this is not offered to the adapter's parser (it is still logged). */
+export declare const MAX_LINE_BYTES: number;
+export interface RunnerOptions {
+    timeoutSec: number;
+    signal?: AbortSignal;
+    /** `stdout.log` and `stderr.log` of this invocation are written here, in full. */
+    logDir: string;
+    /** How long a stopping process gets between SIGTERM and SIGKILL. Default 5000. */
+    killGraceMs?: number;
+    /** How long to wait for output pipes to close after the process is gone or killed, before giving up on them. Default 1000. */
+    settleWaitMs?: number;
+}
+/**
+ * Run an invocation as a child process in its own process group, with a timeout, cancellation, bounded memory
+ * and a bounded finish: whatever the runtime and its descendants do with the output pipes, this settles once,
+ * and the whole process tree is gone by then (SIGTERM, then SIGKILL after `killGraceMs`).
+ */
+export declare function runInvocation(inv: Invocation, opts: RunnerOptions): Promise<WakeResult>;