@illuminis/comprism 0.1.0

package/out/executor/files.js

@@ -0,0 +1,360 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.performFileAction = performFileAction;
+/**
+ * The file actions, on a real filesystem.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D1 to D16 and E6 to E8.
+ *
+ * The same twelve actions the browser performs, with the same refusals, against
+ * a real disk. **The refusals are the part worth reading**: an ambiguous edit,
+ * a path outside the project, a credentials file. An executor that reads and
+ * writes is easy; one that refuses correctly is the one somebody can leave
+ * running.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const paths_1 = require("./paths");
+const MAX_FILE_CHARS = 60_000;
+const MAX_RESULTS = 200;
+const MAX_MAP_PATHS = 2_000;
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".venv",
+    "venv", "env", "__pycache__", ".pytest_cache", ".mypy_cache", "coverage",
+    ".turbo", ".cache", "target", "vendor", ".idea", "Pods", ".gradle",
+    ".terraform", ".serverless", "site-packages",
+]);
+const TEXT_EXT = new Set([
+    "ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "rb", "go", "rs", "java", "kt",
+    "swift", "c", "h", "cc", "cpp", "hpp", "cs", "php", "sh", "bash", "zsh",
+    "sql", "html", "css", "scss", "less", "json", "jsonc", "yaml", "yml", "toml",
+    "ini", "cfg", "conf", "md", "mdx", "txt", "rst", "csv", "tsv", "xml", "svg",
+    "vue", "svelte", "astro", "graphql", "gql", "proto", "lock", "prisma", "tf",
+    "r", "jl", "lua", "pl", "ex", "exs",
+]);
+function isText(name) {
+    const lower = name.toLowerCase();
+    if (!lower.includes("."))
+        return ["makefile", "dockerfile", "gitignore"].includes(lower);
+    return TEXT_EXT.has(lower.split(".").pop());
+}
+function ok(content, summary) {
+    return { content, summary: summary ?? content.split("\n")[0].slice(0, 200) };
+}
+function fail(content) {
+    return { content, isError: true, summary: content.slice(0, 200) };
+}
+function walk(dir, root, out, limit) {
+    if (out.length >= limit)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (out.length >= limit)
+            return;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (SKIP_DIRS.has(e.name))
+                continue;
+            // Not followed. A link pointing outside the project would otherwise pull
+            // the whole machine into a file map, and `resolveInside` would never see
+            // it because nobody asked for that path by name.
+            if (e.isSymbolicLink())
+                continue;
+            walk(full, root, out, limit);
+        }
+        else if (e.isFile()) {
+            out.push(path.relative(root, full));
+        }
+    }
+}
+function globToRegExp(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                out += ".*";
+                i += 1;
+                if (pattern[i + 1] === "/")
+                    i += 1;
+            }
+            else
+                out += "[^/]*";
+        }
+        else if (ch === "?")
+            out += "[^/]";
+        else
+            out += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}
+function countOf(haystack, needle) {
+    if (!needle)
+        return 0;
+    let n = 0, at = haystack.indexOf(needle);
+    while (at !== -1) {
+        n += 1;
+        at = haystack.indexOf(needle, at + needle.length);
+    }
+    return n;
+}
+function performFileAction(root, name, a) {
+    const realRoot = fs.realpathSync(root);
+    try {
+        switch (name) {
+            case "read_file": {
+                const rel = String(a.path ?? "");
+                if ((0, paths_1.isSecret)(rel)) {
+                    return fail(`Refused: ${rel} holds credentials, and credentials are never read into a prompt.`);
+                }
+                const p = (0, paths_1.resolveInside)(realRoot, rel, true);
+                if (!isText(path.basename(p))) {
+                    const size = fs.statSync(p).size;
+                    return fail(`${rel} is not a text file (${size.toLocaleString()} bytes). Reading it would be noise rather than context.`);
+                }
+                let body = fs.readFileSync(p, "utf8");
+                const offset = Number(a.offset ?? 0), limit = Number(a.limit ?? 0);
+                if (offset > 0 || limit > 0) {
+                    const lines = body.split("\n");
+                    const from = Math.max(0, offset > 0 ? offset - 1 : 0);
+                    body = lines.slice(from, limit > 0 ? from + limit : undefined).join("\n");
+                }
+                if (body.length > MAX_FILE_CHARS) {
+                    body = `${body.slice(0, MAX_FILE_CHARS)}\n\n[... truncated. Use offset and limit to read further.]`;
+                }
+                return ok(body, `read ${rel}`);
+            }
+            case "list_dir": {
+                const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
+                const rows = fs.readdirSync(p, { withFileTypes: true })
+                    .map((e) => (e.isDirectory() ? `${e.name}/` : e.name)).sort();
+                return ok(rows.join("\n") || "(empty)", `${rows.length} entries`);
+            }
+            case "file_map": {
+                const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
+                const found = [];
+                walk(p, realRoot, found, MAX_MAP_PATHS);
+                found.sort();
+                const note = found.length >= MAX_MAP_PATHS
+                    ? `\n\n[... stopped at ${MAX_MAP_PATHS} paths. Map a subfolder for the rest.]` : "";
+                return ok(found.join("\n") + note, `${found.length} files`);
+            }
+            case "glob": {
+                const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
+                const found = [];
+                walk(p, realRoot, found, MAX_MAP_PATHS);
+                const rx = globToRegExp(String(a.pattern ?? ""));
+                const hits = found.filter((f) => rx.test(f)).slice(0, MAX_RESULTS);
+                return ok(hits.join("\n") || "(no matches)", `${hits.length} files`);
+            }
+            case "grep": {
+                const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
+                let rx;
+                try {
+                    rx = new RegExp(String(a.pattern ?? ""), a.case_sensitive ? "" : "i");
+                }
+                catch (e) {
+                    return fail(`That is not a valid regular expression: ${e.message}`);
+                }
+                const globRx = a.glob ? globToRegExp(String(a.glob)) : null;
+                const files = [];
+                walk(p, realRoot, files, MAX_MAP_PATHS);
+                const context = Math.max(0, Math.min(Number(a.context_lines ?? 0), 5));
+                const hits = [];
+                for (const rel of files) {
+                    if (hits.length >= MAX_RESULTS)
+                        break;
+                    const leaf = path.basename(rel);
+                    if (!isText(leaf) || (0, paths_1.isSecret)(leaf))
+                        continue;
+                    if (globRx && !globRx.test(rel))
+                        continue;
+                    let text;
+                    try {
+                        text = fs.readFileSync(path.join(realRoot, rel), "utf8");
+                    }
+                    catch {
+                        continue;
+                    }
+                    const lines = text.split("\n");
+                    for (let i = 0; i < lines.length && hits.length < MAX_RESULTS; i += 1) {
+                        if (!rx.test(lines[i]))
+                            continue;
+                        if (context === 0)
+                            hits.push(`${rel}:${i + 1}:${lines[i]}`);
+                        else {
+                            const from = Math.max(0, i - context), to = Math.min(lines.length, i + context + 1);
+                            hits.push(`${rel}:${i + 1}:\n${lines.slice(from, to).join("\n")}`);
+                        }
+                    }
+                }
+                const note = hits.length >= MAX_RESULTS ? `\n\n[... stopped at ${MAX_RESULTS} matches. Narrow the search.]` : "";
+                return ok(hits.join("\n") + note || "(no matches)", `${hits.length} matches`);
+            }
+            // Bytes rather than text, and the ONLY caller is the server writing a
+            // document it just built. A Word file, a deck or a PDF is not text, so it
+            // cannot come down the ordinary write, and a person who asked for a deck
+            // wants it in the folder they are standing in rather than behind a link.
+            //
+            // Deliberately NOT offered to the model. It is issued by the loop after
+            // `make_document`, in the same way the project's instruction file is read
+            // without the model asking. A model that could write arbitrary bytes into
+            // a repository would be a way to put something in a file that no diff
+            // shows and nobody reviews.
+            case "write_bytes": {
+                const rel = String(a.path ?? "");
+                if (a.base64 === undefined || a.base64 === null) {
+                    return fail(`Refused, and nothing was written: write_bytes was called for ${rel} with no content.`);
+                }
+                const p = (0, paths_1.resolveInside)(realRoot, rel, false);
+                fs.mkdirSync(path.dirname(p), { recursive: true });
+                const replaced = fs.existsSync(p);
+                const bytes = Buffer.from(String(a.base64), "base64");
+                fs.writeFileSync(p, bytes);
+                return ok(`${replaced ? "Replaced" : "Saved"} ${rel} (${bytes.length.toLocaleString()} bytes).`, `${replaced ? "replaced" : "saved"} ${rel}`);
+            }
+            case "write_file": {
+                const rel = String(a.path ?? "");
+                // A call that arrives WITHOUT content is a malformed call, not a request
+                // for an empty file. Treating the two as the same is how a whole study
+                // was lost on 11 September 2026: three of four builds saved a blank page,
+                // this returned "ok", and nobody found out until the files were measured.
+                // The model was not at fault - it was told the write succeeded, and on one
+                // run it tried three times and was told so three times.
+                //
+                // An empty file is still reachable, deliberately, with content: "".
+                if (a.content === undefined || a.content === null) {
+                    return fail(`Refused, and nothing was written: write_file was called for ${rel} with no content at all. Send the file's full text in "content". To create a genuinely empty file, pass an empty string.`);
+                }
+                const p = (0, paths_1.resolveInside)(realRoot, rel, false);
+                fs.mkdirSync(path.dirname(p), { recursive: true });
+                const content = String(a.content);
+                // Whether this REPLACED something is checked before the write, because
+                // afterwards there is nothing left to tell from. Writing no longer stops
+                // to ask, so saying which of the two happened is the only way a person
+                // watching knows that a file they already had was just replaced. "wrote"
+                // reads identically in both cases and hides exactly the one that matters.
+                const replaced = fs.existsSync(p);
+                fs.writeFileSync(p, content, "utf8");
+                const size = `${content.length.toLocaleString()} characters`;
+                return replaced
+                    ? ok(`Rewrote ${rel}, replacing what was there (${size}).`, `rewrote ${rel}`)
+                    : ok(`Created ${rel} (${size}).`, `created ${rel}`);
+            }
+            case "edit_file": {
+                const rel = String(a.path ?? "");
+                const p = (0, paths_1.resolveInside)(realRoot, rel, true);
+                const text = fs.readFileSync(p, "utf8");
+                const oldText = String(a.old_text ?? "");
+                const n = countOf(text, oldText);
+                if (n === 0) {
+                    return fail(`Refused: that exact text is not in ${rel}. Read the file again — whitespace and indentation have to match exactly.`);
+                }
+                if (n > 1) {
+                    return fail(`Refused: that text appears ${n} times in ${rel}, so it is not clear which one you mean. Include more surrounding lines to make the target unique.`);
+                }
+                // Missing replacement text used to DELETE the matched section and report
+                // "edited". Worse than the write case, because it destroys work that was
+                // already there. Deleting a section on purpose still works, with
+                // new_text set to an empty string.
+                if (a.new_text === undefined || a.new_text === null) {
+                    return fail(`Refused, and nothing was changed: edit_file was called for ${rel} with no replacement text. Send "new_text". To delete the matched section, pass an empty string.`);
+                }
+                fs.writeFileSync(p, text.replace(oldText, String(a.new_text)), "utf8");
+                return ok(`Edited ${rel}.`, `edited ${rel}`);
+            }
+            case "multi_edit": {
+                const rel = String(a.path ?? "");
+                const p = (0, paths_1.resolveInside)(realRoot, rel, true);
+                const edits = a.edits ?? [];
+                let next = fs.readFileSync(p, "utf8");
+                for (let i = 0; i < edits.length; i += 1) {
+                    const from = String(edits[i].old_text ?? "");
+                    const n = countOf(next, from);
+                    if (n !== 1) {
+                        return fail(`Refused, and nothing was changed: edit ${i + 1} of ${edits.length} matches ${n} times in ${rel}. Every edit has to match exactly once.`);
+                    }
+                    // Same rule as edit_file, checked before anything is written, so a bad
+                    // edit halfway down a list cannot leave the file half changed.
+                    const to = edits[i].new_text;
+                    if (to === undefined || to === null) {
+                        return fail(`Refused, and nothing was changed: edit ${i + 1} of ${edits.length} for ${rel} has no replacement text. Send "new_text". To delete the matched section, pass an empty string.`);
+                    }
+                    next = next.replace(from, String(to));
+                }
+                fs.writeFileSync(p, next, "utf8");
+                return ok(`Applied ${edits.length} edits to ${rel}.`, `${edits.length} edits`);
+            }
+            case "create_dir": {
+                const rel = String(a.path ?? "");
+                fs.mkdirSync((0, paths_1.resolveInside)(realRoot, rel, false), { recursive: true });
+                return ok(`Created ${rel}.`, `created ${rel}`);
+            }
+            case "delete_file": {
+                const rel = String(a.path ?? "");
+                fs.unlinkSync((0, paths_1.resolveInside)(realRoot, rel, true));
+                return ok(`Deleted ${rel}.`, `deleted ${rel}`);
+            }
+            case "move_file": {
+                const rel = String(a.path ?? ""), to = String(a.to ?? "");
+                const from = (0, paths_1.resolveInside)(realRoot, rel, true);
+                const dest = (0, paths_1.resolveInside)(realRoot, to, false);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.renameSync(from, dest);
+                return ok(`Moved ${rel} to ${to}.`, `moved ${rel}`);
+            }
+            default:
+                return fail(`This client cannot do that: ${name}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof paths_1.OutsideWorkspace)
+            return fail(err.message);
+        const e = err;
+        if (e.code === "ENOENT")
+            return fail(`No such file: ${a.path ?? ""}`);
+        if (e.code === "EACCES")
+            return fail(`Permission denied: ${a.path ?? ""}`);
+        return fail(`This action could not be completed: ${e.message}`);
+    }
+}

package/out/executor/git.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Reading the repository, and recording work in it.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D23 to D27.
+ *
+ * **Pushing is the only thing here that sends anything anywhere**, and it is
+ * the only one the server has to have allowed first. Pull requests, reviews,
+ * checks and releases are not git operations at all: they go through GitHub's
+ * own API, on the server, because they need the tenant's credential and that
+ * must never be sent to a client.
+ *
+ * So the split is by what each thing needs. A push needs the repository, which
+ * is here. A pull request needs the credential, which is there.
+ *
+ * Every command goes through `runCommand`, so the folder boundary, the trimmed
+ * environment, the timeout and the output cap all apply here too rather than
+ * being reimplemented for git.
+ */
+import { RunResult, ShellOptions } from "./shell";
+export declare function gitStatus(opts: ShellOptions): Promise<RunResult>;
+export declare function gitDiff(opts: ShellOptions & {
+    path?: string;
+    staged?: boolean;
+}): Promise<RunResult>;
+export declare function gitLog(opts: ShellOptions & {
+    path?: string;
+    limit?: number;
+}): Promise<RunResult>;
+export declare function gitBranch(name: string, opts: ShellOptions): Promise<RunResult>;
+export declare function gitCommit(message: string, opts: ShellOptions & {
+    paths?: string[];
+}): Promise<RunResult>;
+/** Send commits to the remote.
+ *
+ *  Reached only after the server has allowed it: the branch is one the person
+ *  named for this repository, it is not a branch the project is built from, and
+ *  they have just confirmed it. This function does not re-decide any of that,
+ *  and it must not: a client that could decide whether it may publish is a
+ *  client that could grant itself permission.
+ *
+ *  **There is no force push and there is no upstream rewrite.** Not as an
+ *  option, not behind a flag. Everything on the remote stays recoverable by
+ *  whoever is working from it.
+ */
+export declare function gitPush(branch: string, opts: ShellOptions & {
+    createRemote?: boolean;
+}): Promise<RunResult>;

package/out/executor/git.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitStatus = gitStatus;
+exports.gitDiff = gitDiff;
+exports.gitLog = gitLog;
+exports.gitBranch = gitBranch;
+exports.gitCommit = gitCommit;
+exports.gitPush = gitPush;
+/**
+ * Reading the repository, and recording work in it.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D23 to D27.
+ *
+ * **Pushing is the only thing here that sends anything anywhere**, and it is
+ * the only one the server has to have allowed first. Pull requests, reviews,
+ * checks and releases are not git operations at all: they go through GitHub's
+ * own API, on the server, because they need the tenant's credential and that
+ * must never be sent to a client.
+ *
+ * So the split is by what each thing needs. A push needs the repository, which
+ * is here. A pull request needs the credential, which is there.
+ *
+ * Every command goes through `runCommand`, so the folder boundary, the trimmed
+ * environment, the timeout and the output cap all apply here too rather than
+ * being reimplemented for git.
+ */
+const shell_1 = require("./shell");
+/** Arguments passed as a list and quoted, never interpolated into a string.
+ *
+ *  A commit message is written by a model and can contain anything: quotes,
+ *  backticks, a newline, a semicolon. Pasting one into a shell string is how a
+ *  message becomes a second command. */
+function quote(value) {
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+async function gitStatus(opts) {
+    // Porcelain, because the human-readable format changes between versions and
+    // the model has to be able to rely on the shape.
+    const r = await (0, shell_1.runCommand)("git status --porcelain=v1 --branch", opts);
+    if (!r.isError && /^exit 0/.test(r.content) && r.content.trim().split("\n").length <= 3) {
+        return { ...r, content: `${r.content}\n\n[Nothing has changed in the working tree.]` };
+    }
+    return r;
+}
+async function gitDiff(opts) {
+    const parts = ["git", "--no-pager", "diff"];
+    if (opts.staged)
+        parts.push("--staged");
+    // Color off explicitly: a diff full of escape codes costs tokens and reads
+    // as noise to a model.
+    parts.push("--no-color");
+    if (opts.path)
+        parts.push("--", quote(opts.path));
+    return (0, shell_1.runCommand)(parts.join(" "), opts);
+}
+async function gitLog(opts) {
+    const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));
+    const parts = [
+        "git", "--no-pager", "log", `-n ${limit}`,
+        // Quoted. Everything here goes through a shell, so an unquoted format string
+        // is split on its spaces and git reads "%an" as a revision. It fails with
+        // "ambiguous argument", which reads like a broken repository rather than a
+        // quoting mistake, and cost a test run to diagnose.
+        `--pretty=${quote("format:%h %an %ar %s")}`,
+    ];
+    if (opts.path)
+        parts.push("--", quote(opts.path));
+    return (0, shell_1.runCommand)(parts.join(" "), opts);
+}
+async function gitBranch(name, opts) {
+    if (!/^[\w./-]{1,120}$/.test(name)) {
+        return {
+            isError: true,
+            content: `Refused: ${name} is not a usable branch name. Letters, numbers, dots, dashes, underscores and slashes only.`,
+        };
+    }
+    return (0, shell_1.runCommand)(`git checkout -b ${quote(name)}`, opts);
+}
+async function gitCommit(message, opts) {
+    if (!message.trim()) {
+        return { isError: true, content: "Refused: a commit needs a message." };
+    }
+    const stage = opts.paths?.length
+        ? `git add -- ${opts.paths.map(quote).join(" ")}`
+        : "git add -A";
+    const staged = await (0, shell_1.runCommand)(stage, opts);
+    if (staged.isError)
+        return staged;
+    // Nothing to commit is a normal outcome, not a failure. Reported plainly so
+    // the model does not conclude that committing is broken and try again.
+    const check = await (0, shell_1.runCommand)("git diff --staged --quiet", opts);
+    if (/^exit 0\b/.test(check.content)) {
+        return { content: "Nothing to commit: no changes are staged.", summary: "nothing to commit" };
+    }
+    // Attribution, always. A commit that hides having been written by an agent is
+    // a commit somebody later reads as a colleague's careful work, and the whole
+    // record this product keeps depends on that not happening.
+    const trailer = "\n\nCo-authored-by: illuminis coding agent <agent@illuminis.ai>";
+    return (0, shell_1.runCommand)(`git commit -m ${quote(message + trailer)}`, opts);
+}
+/** Send commits to the remote.
+ *
+ *  Reached only after the server has allowed it: the branch is one the person
+ *  named for this repository, it is not a branch the project is built from, and
+ *  they have just confirmed it. This function does not re-decide any of that,
+ *  and it must not: a client that could decide whether it may publish is a
+ *  client that could grant itself permission.
+ *
+ *  **There is no force push and there is no upstream rewrite.** Not as an
+ *  option, not behind a flag. Everything on the remote stays recoverable by
+ *  whoever is working from it.
+ */
+async function gitPush(branch, opts) {
+    if (!/^[\w./-]{1,120}$/.test(branch)) {
+        return { isError: true, content: `Refused: ${branch} is not a usable branch name.` };
+    }
+    // What is about to go, named before it goes. A push that reports success
+    // without saying what it sent is a push nobody can check afterwards.
+    const ahead = await (0, shell_1.runCommand)(`git --no-pager log --oneline origin/${quote(branch)}..HEAD 2>/dev/null || git --no-pager log --oneline -5`, opts);
+    // `-u` on a new branch so later pushes need no arguments, and nothing else.
+    // No `--force`, no `--force-with-lease`, no `+refs` refspec.
+    const flags = opts.createRemote ? "-u" : "";
+    const pushed = await (0, shell_1.runCommand)(`git push ${flags} origin ${quote(branch)}`.replace(/\s+/g, " "), opts);
+    if (pushed.isError || !/^exit 0/.test(pushed.content)) {
+        return { ...pushed, isError: true };
+    }
+    return {
+        content: `Pushed to ${branch}.\n\nWhat went:\n${ahead.content}`,
+        summary: `pushed ${branch}`,
+    };
+}

package/out/executor/hooks.d.ts

@@ -0,0 +1,67 @@
+export interface Hook {
+    /** Which actions this runs around. Three forms, all common in the market:
+     *
+     *    "edit_file"                 exactly that one
+     *    "write_file|edit_file"      any in the list
+     *    "*"                         every one
+     *
+     *  Anything else is treated as a regular expression anchored at both ends, so
+     *  `"git_.*"` covers the git actions without naming all five. A pattern that
+     *  will not compile matches nothing and says so once, rather than matching
+     *  everything: a broken pattern that ran a hook on every action would be the
+     *  dangerous way to be wrong. */
+    on: string;
+    /** "before" or "after". */
+    when: "before" | "after";
+    command: string;
+    /** Words a person reads in the timeline when it runs. */
+    what?: string;
+}
+/** What this project asks for, or nothing.
+ *
+ *  A malformed file is ignored with a warning rather than failing the job. A
+ *  project whose hook configuration has a trailing comma should not be a project
+ *  where the agent refuses to work, and the person who broke it is not usually
+ *  the person now trying to get something done.
+ */
+export declare function hooksFor(root: string): Hook[];
+/** Does this hook's matcher cover this action.
+ *
+ *  Exported because it is the part with the rules in it, and a rule with no
+ *  test is a rule that drifts.
+ */
+export declare function covers(pattern: string, action: string): boolean;
+export interface HookOutcome {
+    ran: number;
+    /** Set when a `before` hook refused the action. */
+    refusedBy?: string;
+    detail?: string;
+}
+/**
+ * Run the hooks that come before one action.
+ *
+ * **A non-zero exit cancels the action.** This is the one place a hook changes
+ * what happens, and it is deliberate: "do not let the agent touch anything under
+ * generated/" is a real thing to want, and refusing is the only way for a
+ * project to say it.
+ *
+ * It can only ever REFUSE. There is no exit code that approves something the
+ * agent was not already allowed to do, because a permission system inside the
+ * repository would live exactly where an attacker who got that far already is.
+ */
+export declare function before(root: string, action: string, args: Record<string, unknown>, hooks?: Hook[]): Promise<HookOutcome>;
+/**
+ * Run the hooks that come after one action.
+ *
+ * A failure here is reported and nothing else: the action has already happened,
+ * and refusing it afterwards is not a thing that can be done. The overwhelming
+ * case is a formatter, and a formatter that fails is worth knowing about and not
+ * worth losing the work over.
+ */
+export declare function after(root: string, action: string, args: Record<string, unknown>, hooks?: Hook[]): Promise<{
+    ran: number;
+    failed: string[];
+}>;
+/** The example a person copies. Kept in code so the readme and the behavior
+ *  cannot drift: this is what the reader actually gets. */
+export declare const EXAMPLE: string;