@intentius/chant 0.124.40 → 0.124.42

package/dist/lifecycle/run-ledger.js

@@ -163,6 +163,22 @@ export async function readRunLedger(environment, op, opts) {
     const content = await readBlobFromPath(environment, fileFor(op), opts);
     if (!content)
         return { records: [], malformed: 0 };
+    return parseRunLedger(content);
+}
+/** The run ledger file name for `op` under `<env>/`, `runs__<op>.jsonl`. */
+export function runLedgerFile(op) {
+    return fileFor(op);
+}
+/** The op a run ledger file name holds, or null when `file` is not one. */
+export function opOfRunLedgerFile(file) {
+    return file.startsWith(PREFIX) && file.endsWith(".jsonl") && file.length > PREFIX.length + ".jsonl".length ? file.slice(PREFIX.length, -".jsonl".length) : null;
+}
+/**
+ * Parse the text of one run ledger file the way {@link readRunLedger} reads
+ * it (#4297): a reader that fetches the file itself, such as `chant query`,
+ * gets the same records and the same malformed count.
+ */
+export function parseRunLedger(content) {
     const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
     const records = [];
     let malformed = 0;

package/dist/lifecycle/target-lock.d.ts

@@ -0,0 +1,97 @@
+/** The directory on `chant/lifecycle` that holds the lock files. */
+export declare const LOCKS_DIR = "_locks";
+/**
+ * How a lock was taken. `plan`: the pull request's plan took it (`ci.locks:
+ * plan`). `apply`: its apply took it. `lock`: someone ran `chant lock`.
+ */
+export type TargetLockStage = "plan" | "apply" | "lock";
+export declare const TARGET_LOCK_STAGES: readonly ["plan", "apply", "lock"];
+/** One target's lock: the pull request that holds it, who took it, when, how, and the head it took it at. */
+export interface TargetLock {
+    pr: number;
+    by: string;
+    at: string;
+    stage: TargetLockStage;
+    /** The pull request's head commit when the lock was taken. Absent when the caller did not say. */
+    head?: string;
+}
+/** `_locks/<gate>.json`. */
+export interface TargetLockFile {
+    version: 1;
+    locks: Record<string, TargetLock>;
+}
+/** A lock another open pull request holds on a target the caller needs. */
+export interface HeldTargetLock extends TargetLock {
+    target: string;
+}
+/** Says whether pull request `pr` is still open. */
+export type PullRequestOpen = (pr: number) => Promise<boolean>;
+export interface TargetLockOptions {
+    cwd?: string;
+    /** Whether a holder is still open. Absent: every holder counts as open. */
+    isOpen?: PullRequestOpen;
+}
+export type TakeTargetLocksResult = {
+    ok: true;
+    /** The targets now locked, sorted. */
+    taken: string[];
+    /** Plan locks of the same pull request on targets it no longer reaches, released (`releaseStalePlan`). */
+    released: string[];
+    /** Locks of merged or closed pull requests that this write dropped. */
+    expired: string[];
+    /** Whether the remote has the write. False with no remote, or when recording is off. */
+    pushed: boolean;
+} | {
+    ok: false;
+    held: HeldTargetLock[];
+};
+/** The path of `gate`'s lock file on `chant/lifecycle`, under a member's prefix when it has one. */
+export declare function targetLockPath(gate: string, memberPrefix?: string): string;
+/** A gate name that is safe as a file name. */
+export declare function targetLockGateProblem(gate: string): string | null;
+/** Parse a lock file. Anything that is not a version 1 file with a map of locks reads as no locks; a malformed entry is dropped. */
+export declare function parseTargetLocks(text: string | null): TargetLockFile;
+/** The file's text: targets sorted, so two writes of the same locks are the same blob. */
+export declare function renderTargetLocks(file: TargetLockFile): string;
+/** The locks of `gate` as the remote holds them now, fetched first. */
+export declare function readTargetLocks(gate: string, opts?: {
+    cwd?: string;
+}): Promise<TargetLockFile>;
+/**
+ * The locks on `targets` that an open pull request other than `pr` holds.
+ * Reads only: an apply calls this to refuse a target another pull request
+ * holds. `pr` null (an apply of a green commit) counts every open holder.
+ */
+export declare function heldTargetLocks(gate: string, targets: readonly string[], pr: number | null, opts?: TargetLockOptions): Promise<HeldTargetLock[]>;
+/**
+ * Lock `targets` for pull request `holder.pr`. A target locked by another
+ * pull request that is still open is held, and nothing is locked. A target
+ * locked by one that merged or closed is taken over, and its lock dropped.
+ * Targets this pull request already holds stay its own, with the new head.
+ * An apply or a `chant lock` takes over the pull request's own plan locks;
+ * a plan keeps its own apply and `chant lock` locks as they are. With
+ * `releaseStalePlan`, the pull request's plan locks on targets it no longer
+ * reaches are released.
+ */
+export declare function takeTargetLocks(gate: string, targets: readonly string[], holder: TargetLock, opts?: TargetLockOptions & {
+    releaseStalePlan?: boolean;
+}): Promise<TakeTargetLocksResult>;
+/**
+ * Release the locks pull request `pr` holds on `gate`: every one, or only
+ * those on `targets`. Returns the targets released, sorted.
+ */
+export declare function releaseTargetLocks(gate: string, pr: number, opts?: {
+    cwd?: string;
+    targets?: readonly string[];
+}): Promise<{
+    released: string[];
+    pushed: boolean;
+}>;
+/** The lock file's path for the project at `cwd`, for messages. */
+export declare function targetLockPathAt(gate: string, cwd?: string): Promise<string>;
+/**
+ * One line naming the targets others hold, for a refusal or a note.
+ * `name` says how the forge names a holder (GitLab: `merge request !7`).
+ */
+export declare function describeHeldTargetLocks(held: readonly HeldTargetLock[], name?: (pr: number) => string): string;
+//# sourceMappingURL=target-lock.d.ts.map

package/dist/lifecycle/target-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-lock.d.ts","sourceRoot":"","sources":["../../src/lifecycle/target-lock.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/target-lock.js

@@ -0,0 +1,286 @@
+/**
+ * Target locks (#4293): a pull request holds a lock on each target its
+ * change reaches, so no other pull request applies or locks those targets
+ * until it merges or closes, or someone runs `chant unlock` on it.
+ *
+ * A target is a name the caller picks: a component, a workspace member, or
+ * a lexicon's own unit such as a Terraform root. The locks of one gate live
+ * in one file, `_locks/<gate>.json` on `chant/lifecycle`, under the member's
+ * ledger prefix in a workspace member (./git.ts `ledgerDir`). The gate is
+ * the pull-request loop's, `pr-apply` unless the pipeline names another, so
+ * two pipelines with their own gates keep their own locks.
+ *
+ * Every change is a new commit on the branch, written with the read-then-CAS
+ * the other ledgers use and then pushed. A lock counts only once the remote
+ * has it: when the push is refused because another writer moved the branch,
+ * the local commit is dropped, the branch is read again and the decision is
+ * made again. So two jobs that lock the same target at once cannot both win.
+ * A repository with no remote is one machine, and the local write decides.
+ *
+ * A lock held by a pull request that is no longer open is released: the
+ * holder merged or closed. The caller says which pull requests are open
+ * (`isOpen`, from the forge). Without it every lock counts as held, and only
+ * `chant unlock` releases one.
+ *
+ * The file is coordination, not a record of work. ws-074 holds: the
+ * repository is the database, and the file is one more ledger on the
+ * branch, so any clone can read who holds what.
+ */
+import { getRuntime } from "../runtime-adapter.js";
+import { fetchLifecycleStatus, pushLifecycleStatus, readBlobBySha, readPathSha, RefCASConflictError, writeBlobToPath, } from "./git.js";
+import { resolveMemberLedger } from "./member-ledger.js";
+/** The directory on `chant/lifecycle` that holds the lock files. */
+export const LOCKS_DIR = "_locks";
+const STATE_BRANCH = "chant/lifecycle";
+/** A scratch ref this module owns, for reading the remote tip after a refused push. */
+const PROBE_REF = "refs/chant/target-lock-probe";
+const ATTEMPTS = 5;
+export const TARGET_LOCK_STAGES = ["plan", "apply", "lock"];
+/** The path of `gate`'s lock file on `chant/lifecycle`, under a member's prefix when it has one. */
+export function targetLockPath(gate, memberPrefix = "") {
+    return `${memberPrefix}${LOCKS_DIR}/${gate}.json`;
+}
+/** A gate name that is safe as a file name. */
+export function targetLockGateProblem(gate) {
+    return /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(gate) ? null : `the gate name ${JSON.stringify(gate)} is not a lock file name: letters, digits, '.', '_' and '-', starting with a letter or digit`;
+}
+const isStage = (v) => typeof v === "string" && TARGET_LOCK_STAGES.includes(v);
+/** Parse a lock file. Anything that is not a version 1 file with a map of locks reads as no locks; a malformed entry is dropped. */
+export function parseTargetLocks(text) {
+    if (!text)
+        return { version: 1, locks: {} };
+    try {
+        const doc = JSON.parse(text);
+        if (doc?.version === 1 && doc.locks && typeof doc.locks === "object" && !Array.isArray(doc.locks)) {
+            const locks = {};
+            for (const [target, raw] of Object.entries(doc.locks)) {
+                if (!raw || !Number.isInteger(raw.pr) || typeof raw.by !== "string" || typeof raw.at !== "string" || !isStage(raw.stage))
+                    continue;
+                locks[target] = { pr: raw.pr, by: raw.by, at: raw.at, stage: raw.stage, ...(typeof raw.head === "string" ? { head: raw.head } : {}) };
+            }
+            return { version: 1, locks };
+        }
+    }
+    catch {
+        // An unreadable file holds no locks.
+    }
+    return { version: 1, locks: {} };
+}
+/** The file's text: targets sorted, so two writes of the same locks are the same blob. */
+export function renderTargetLocks(file) {
+    const locks = Object.fromEntries(Object.keys(file.locks).sort().map((t) => [t, file.locks[t]]));
+    return `${JSON.stringify({ version: 1, locks }, null, 2)}\n`;
+}
+/** Fetch `chant/lifecycle`, refusing a ledger this checkout cannot read: a lock decided on a stale branch is no lock. */
+async function fetchForLocks(cwd) {
+    const fetched = await fetchLifecycleStatus({ cwd });
+    if (fetched.status === "diverged")
+        throw new Error(`the local ${STATE_BRANCH} has forked from ${fetched.remote}'s, so the locks cannot be read: ${fetched.stderr}`);
+    if (fetched.status === "unreachable")
+        throw new Error(`cannot fetch ${STATE_BRANCH} from ${fetched.remote}, so the locks cannot be read${fetched.stderr ? `: ${fetched.stderr}` : ""}`);
+}
+async function readCurrent(gate, cwd) {
+    const sha = await readPathSha(LOCKS_DIR, `${gate}.json`, { cwd });
+    return { sha, file: parseTargetLocks(sha ? await readBlobBySha(sha, { cwd }) : null) };
+}
+/** The locks of `gate` as the remote holds them now, fetched first. */
+export async function readTargetLocks(gate, opts = {}) {
+    const problem = targetLockGateProblem(gate);
+    if (problem)
+        throw new Error(problem);
+    await fetchForLocks(opts.cwd);
+    return (await readCurrent(gate, opts.cwd)).file;
+}
+/** A memo of `isOpen`, so one decision asks the forge about each pull request once. */
+function openMemo(isOpen) {
+    const seen = new Map();
+    return (pr) => {
+        if (!isOpen)
+            return Promise.resolve(true);
+        if (!seen.has(pr))
+            seen.set(pr, isOpen(pr));
+        return seen.get(pr);
+    };
+}
+/** The locks on `targets` that an open pull request other than `pr` holds, by target. */
+async function heldIn(file, targets, pr, open) {
+    const held = [];
+    for (const target of [...new Set(targets)].sort()) {
+        const l = file.locks[target];
+        if (l && l.pr !== pr && (await open(l.pr)))
+            held.push({ target, ...l });
+    }
+    return held;
+}
+/**
+ * The locks on `targets` that an open pull request other than `pr` holds.
+ * Reads only: an apply calls this to refuse a target another pull request
+ * holds. `pr` null (an apply of a green commit) counts every open holder.
+ */
+export async function heldTargetLocks(gate, targets, pr, opts = {}) {
+    if (targets.length === 0)
+        return [];
+    const file = await readTargetLocks(gate, opts);
+    return heldIn(file, targets, pr, openMemo(opts.isOpen));
+}
+/** The local tip of `chant/lifecycle`, or "" when there is none. */
+async function localTip(cwd) {
+    const out = await getRuntime().spawn(["git", "rev-parse", "--verify", "--quiet", `refs/heads/${STATE_BRANCH}`], { cwd });
+    return out.exitCode === 0 ? out.stdout.trim() : "";
+}
+/**
+ * After a refused push: drop the lock commit `ours` from the local branch by
+ * moving it to the remote's tip, so the next attempt reads what the other
+ * writer pushed. Done only when `parent`, the tip before the write, is in
+ * the remote's history, so no other local commit is lost. Throws otherwise.
+ */
+async function dropRefusedWrite(remote, ours, parent, cwd) {
+    const rt = getRuntime();
+    const env = { LC_ALL: "C", LANGUAGE: "" };
+    const probe = await rt.spawn(["git", "fetch", "--force", remote, `${STATE_BRANCH}:${PROBE_REF}`], { cwd, env });
+    if (probe.exitCode !== 0)
+        throw new Error(`the push of the locks was refused and ${STATE_BRANCH} could not be read again from ${remote}: ${probe.stderr.trim()}`);
+    try {
+        if (parent) {
+            const contains = await rt.spawn(["git", "merge-base", "--is-ancestor", parent, PROBE_REF], { cwd, env });
+            if (contains.exitCode !== 0)
+                throw new Error(`the push of the locks was refused, and the local ${STATE_BRANCH} holds commits ${remote} does not; push or fetch ${STATE_BRANCH} and lock again`);
+        }
+        const tip = (await rt.spawn(["git", "rev-parse", "--verify", PROBE_REF], { cwd, env })).stdout.trim();
+        const moved = await rt.spawn(["git", "update-ref", `refs/heads/${STATE_BRANCH}`, tip, ours], { cwd, env });
+        if (moved.exitCode !== 0)
+            throw new Error(`could not drop the refused lock commit from ${STATE_BRANCH}: ${moved.stderr.trim()}`);
+        await rt.spawn(["git", "update-ref", `refs/remotes/${remote}/${STATE_BRANCH}`, tip], { cwd, env });
+    }
+    finally {
+        await rt.spawn(["git", "update-ref", "-d", PROBE_REF], { cwd, env });
+    }
+}
+/**
+ * Write `next` over the file read at `sha`, then push. Returns null when the
+ * branch moved under the write (locally or on the remote), so the caller
+ * reads and decides again.
+ */
+async function writeAndPush(gate, sha, next, message, cwd) {
+    const parent = await localTip(cwd);
+    let commit;
+    try {
+        commit = await writeBlobToPath(LOCKS_DIR, `${gate}.json`, renderTargetLocks(next), message, { cwd, expectPriorPathSha: sha });
+    }
+    catch (err) {
+        if (err instanceof RefCASConflictError)
+            return null;
+        throw err;
+    }
+    const push = await pushLifecycleStatus({ cwd });
+    switch (push.status) {
+        case "pushed":
+            return { pushed: true };
+        case "no-remote":
+        case "not-recorded":
+            return { pushed: false };
+        case "stale":
+            await dropRefusedWrite(push.remote, commit, parent, cwd);
+            await fetchForLocks(cwd);
+            return null;
+        case "failed":
+            throw new Error(`the locks were written but the push of ${STATE_BRANCH} to ${push.remote} failed, so they do not count yet: ${push.stderr}`);
+    }
+}
+/**
+ * Lock `targets` for pull request `holder.pr`. A target locked by another
+ * pull request that is still open is held, and nothing is locked. A target
+ * locked by one that merged or closed is taken over, and its lock dropped.
+ * Targets this pull request already holds stay its own, with the new head.
+ * An apply or a `chant lock` takes over the pull request's own plan locks;
+ * a plan keeps its own apply and `chant lock` locks as they are. With
+ * `releaseStalePlan`, the pull request's plan locks on targets it no longer
+ * reaches are released.
+ */
+export async function takeTargetLocks(gate, targets, holder, opts = {}) {
+    const problem = targetLockGateProblem(gate);
+    if (problem)
+        throw new Error(problem);
+    for (const t of targets)
+        if (t.trim() === "")
+            throw new Error("a lock target is a non-empty name");
+    const wanted = [...new Set(targets)].sort();
+    const open = openMemo(opts.isOpen);
+    await fetchForLocks(opts.cwd);
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+        const { sha, file } = await readCurrent(gate, opts.cwd);
+        const held = await heldIn(file, wanted, holder.pr, open);
+        if (held.length > 0)
+            return { ok: false, held };
+        const next = { version: 1, locks: {} };
+        const released = [];
+        const expired = [];
+        for (const [target, l] of Object.entries(file.locks)) {
+            if (l.pr === holder.pr) {
+                if (opts.releaseStalePlan && l.stage === "plan" && !wanted.includes(target)) {
+                    released.push(target);
+                    continue;
+                }
+            }
+            else if (opts.isOpen && !(await open(l.pr))) {
+                expired.push(target);
+                continue;
+            }
+            next.locks[target] = l;
+        }
+        for (const target of wanted) {
+            const own = file.locks[target];
+            next.locks[target] = holder.stage === "plan" && own?.pr === holder.pr && own.stage !== "plan" ? own : holder;
+        }
+        const done = { ok: true, taken: wanted, released: released.sort(), expired: expired.sort() };
+        if (renderTargetLocks(next) === renderTargetLocks(file) && sha !== null)
+            return { ...done, pushed: false };
+        if (wanted.length === 0 && released.length === 0 && expired.length === 0)
+            return { ...done, pushed: false };
+        const wrote = await writeAndPush(gate, sha, next, `Lock ${wanted.length} target${wanted.length === 1 ? "" : "s"} of ${gate} for pull request ${holder.pr} (${holder.stage})`, opts.cwd);
+        if (wrote)
+            return { ...done, pushed: wrote.pushed };
+    }
+    throw new Error(`could not write the locks of ${gate}: ${STATE_BRANCH} kept moving; lock again`);
+}
+/**
+ * Release the locks pull request `pr` holds on `gate`: every one, or only
+ * those on `targets`. Returns the targets released, sorted.
+ */
+export async function releaseTargetLocks(gate, pr, opts = {}) {
+    const problem = targetLockGateProblem(gate);
+    if (problem)
+        throw new Error(problem);
+    await fetchForLocks(opts.cwd);
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+        const { sha, file } = await readCurrent(gate, opts.cwd);
+        const mine = Object.keys(file.locks)
+            .filter((t) => file.locks[t].pr === pr && (!opts.targets || opts.targets.includes(t)))
+            .sort();
+        if (mine.length === 0)
+            return { released: [], pushed: false };
+        const next = { version: 1, locks: Object.fromEntries(Object.entries(file.locks).filter(([t]) => !mine.includes(t))) };
+        const wrote = await writeAndPush(gate, sha, next, `Unlock ${mine.length} target${mine.length === 1 ? "" : "s"} of ${gate} held by pull request ${pr}`, opts.cwd);
+        if (wrote)
+            return { released: mine, pushed: wrote.pushed };
+    }
+    throw new Error(`could not write the locks of ${gate}: ${STATE_BRANCH} kept moving; unlock again`);
+}
+/** The lock file's path for the project at `cwd`, for messages. */
+export async function targetLockPathAt(gate, cwd) {
+    const { prefix } = await resolveMemberLedger(cwd ?? process.cwd());
+    return targetLockPath(gate, prefix);
+}
+const STAGE_WORDS = { plan: "planned", apply: "applied", lock: "locked with chant lock" };
+/**
+ * One line naming the targets others hold, for a refusal or a note.
+ * `name` says how the forge names a holder (GitLab: `merge request !7`).
+ */
+export function describeHeldTargetLocks(held, name = (pr) => `pull request ${pr}`) {
+    const byPr = new Map();
+    for (const h of held)
+        byPr.set(h.pr, [...(byPr.get(h.pr) ?? []), h]);
+    return [...byPr]
+        .map(([pr, hs]) => `${hs.map((h) => h.target).join(", ")} ${hs.length === 1 ? "is" : "are"} locked by ${name(pr)} (${STAGE_WORDS[hs[0].stage]} by ${hs[0].by})`)
+        .join("; ");
+}

package/dist/op/activities/activity-contracts.d.ts

@@ -121,6 +121,36 @@ export declare const behaviourFindingContract: import("../index.js").ActivityCon
     pullRequest?: string | undefined;
     mergeRequest?: string | undefined;
 }>;
+/**
+ * The review agent (#4299). `changeSet` is `composeChangeSet`'s document,
+ * checked only for the fields the prompt reads. `returns` names what a later
+ * step may read; no gate reads it.
+ */
+export declare const reviewAgentContract: import("../index.js").ActivityContract<{
+    op: string;
+    changeSet?: {
+        [x: string]: unknown;
+        digest: string;
+        entries: unknown[];
+    } | undefined;
+    changeSetFile?: string | undefined;
+    mode?: "comment" | "report" | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+    base?: string | undefined;
+    instructions?: string | undefined;
+    command?: string | undefined;
+    keyEnv?: string | undefined;
+    timeout?: number | undefined;
+}, {
+    mode: "comment" | "report";
+    risk: "high" | "low" | "medium" | "unknown";
+    exitCode: number | null;
+    summary: string;
+    commentUrl?: string | undefined;
+    pullRequest?: string | undefined;
+    mergeRequest?: string | undefined;
+}>;
 /**
  * The propose-only template upgrade (#2550, ws-032). `args` mirrors
  * `ProposeWorkspaceUpgradeArgs` without its test hooks. `returns` names what

package/dist/op/activities/activity-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../../src/op/activities/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,eAAO,MAAM,yBAAyB;;SAGrC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;EAIjC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;EAmB5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;EAgB7B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;SAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EAUpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EA8B3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;EAkBhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIjC,CAAC;AAOF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EAIpC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAI1C,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAW/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAWjC,CAAC;AAUF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;EAoBvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;EAWzC,CAAC;AAWF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAQ/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAIhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EASjC,CAAC"}
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../../src/op/activities/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,eAAO,MAAM,yBAAyB;;SAGrC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;EAIjC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;EAmB5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;EAgB7B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;SAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EAUpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;EAwB/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EA8B3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;EAkBhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIjC,CAAC;AAOF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EAIpC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAI1C,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAW/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAWjC,CAAC;AAUF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;EAoBvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;EAWzC,CAAC;AAWF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAQ/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAIhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EASjC,CAAC"}

package/dist/op/activities/activity-contracts.js

@@ -107,6 +107,32 @@ export const behaviourFindingContract = activityContract("behaviourFinding", z.s
     pullRequest: z.string().optional(),
     mergeRequest: z.string().optional(),
 }));
+/**
+ * The review agent (#4299). `changeSet` is `composeChangeSet`'s document,
+ * checked only for the fields the prompt reads. `returns` names what a later
+ * step may read; no gate reads it.
+ */
+export const reviewAgentContract = activityContract("reviewAgent", z.strictObject({
+    op: z.string(),
+    changeSet: z.object({ digest: z.string(), entries: z.array(z.unknown()) }).passthrough().optional(),
+    changeSetFile: z.string().optional(),
+    mode: z.enum(["comment", "report"]).optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    base: z.string().optional(),
+    instructions: z.string().optional(),
+    command: z.string().optional(),
+    keyEnv: z.string().optional(),
+    timeout: z.number().positive().optional(),
+}), z.object({
+    mode: z.enum(["comment", "report"]),
+    risk: z.enum(["low", "medium", "high", "unknown"]),
+    exitCode: z.number().nullable(),
+    summary: z.string(),
+    commentUrl: z.string().optional(),
+    pullRequest: z.string().optional(),
+    mergeRequest: z.string().optional(),
+}));
 /**
  * The propose-only template upgrade (#2550, ws-032). `args` mirrors
  * `ProposeWorkspaceUpgradeArgs` without its test hooks. `returns` names what

package/dist/op/activities/index.d.ts

@@ -38,6 +38,8 @@ export { lexiconUpgrade, isPinned, isRolling, severityToLabel, upgradeBranchName
 export type { LexiconUpgradeArgs, LexiconUpgradeResult, LexiconUpgradeMode, SupportedLexicon, SemverLabel, CheckPinnedFn, CheckRollingFn, GhRunner, ApplyBumpFn, } from "./lexicon-upgrade.js";
 export { predictBehaviour, behaviourFinding, behaviourFindingMarker, declaredEdgeCoverage, baseRefFrom, headRefFrom, noBaseRefMessage, noContributedRowsMessage, } from "./predict-behaviour.js";
 export type { PredictBehaviourArgs, BehaviourFindingArgs, BehaviourFindingResult, BehaviourFindingMode, BehaviourFindingDeps, BaseCheckout, } from "./predict-behaviour.js";
+export { reviewAgent, reviewMarker } from "./review-agent.js";
+export type { ReviewAgentArgs, ReviewAgentResult, ReviewAgentMode, ReviewRisk } from "./review-agent.js";
 export { proposeWorkspaceUpgrade } from "./propose-upgrade.js";
 export type { ProposeWorkspaceUpgradeArgs, ProposeWorkspaceUpgradeResult, ProposeUpgradeMode, CommandRunner, } from "./propose-upgrade.js";
 export { changeCoverage } from "./change-coverage.js";

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"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"}

package/dist/op/activities/index.js

@@ -43,6 +43,10 @@ export { lexiconUpgrade, isPinned, isRolling, severityToLabel, upgradeBranchName
 // collects every exported function as an activity, so `createBehaviourFinding`
 // and `checkoutBase` stay on the module.
 export { predictBehaviour, behaviourFinding, behaviourFindingMarker, declaredEdgeCoverage, baseRefFrom, headRefFrom, noBaseRefMessage, noContributedRowsMessage, } from "./predict-behaviour.js";
+// The review agent (#4299): a model reviews the change set against the pull
+// request's own text and posts one sticky note. Only the activity and its
+// marker are re-exported, since the registry collects every exported function.
+export { reviewAgent, reviewMarker } from "./review-agent.js";
 // The propose-only template upgrade (#2550). Loads the workspace code on first
 // call only, so importing this module loads nothing under `workspace/`.
 export { proposeWorkspaceUpgrade } from "./propose-upgrade.js";

package/dist/op/activities/pr-refs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The pull request's base and head branch names, read off the run's own
+ * event (#4299). Its own module so the review agent bundles without
+ * predict-behaviour's estate code.
+ */
+/** Where the base branch name comes from, most specific first. Pure — exported for testing. */
+export declare function baseRefFrom(env: Record<string, string | undefined>, explicit?: string): string | undefined;
+/** What the head side is called in the finding: the source branch when the run names one, else the short commit. */
+export declare function headRefFrom(env: Record<string, string | undefined>, shortSha?: string): string;
+//# sourceMappingURL=pr-refs.d.ts.map

package/dist/op/activities/pr-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-refs.d.ts","sourceRoot":"","sources":["../../../src/op/activities/pr-refs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,+FAA+F;AAC/F,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAED,oHAAoH;AACpH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAM9F"}

package/dist/op/activities/pr-refs.js

@@ -0,0 +1,26 @@
+/**
+ * The pull request's base and head branch names, read off the run's own
+ * event (#4299). Its own module so the review agent bundles without
+ * predict-behaviour's estate code.
+ */
+/** Where the base branch name comes from, most specific first. Pure — exported for testing. */
+export function baseRefFrom(env, explicit) {
+    const fromArgs = explicit?.trim();
+    if (fromArgs)
+        return fromArgs;
+    for (const source of ["GITHUB_BASE_REF", "CI_MERGE_REQUEST_TARGET_BRANCH_NAME"]) {
+        const value = env[source]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** What the head side is called in the finding: the source branch when the run names one, else the short commit. */
+export function headRefFrom(env, shortSha) {
+    for (const source of ["GITHUB_HEAD_REF", "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"]) {
+        const value = env[source]?.trim();
+        if (value)
+            return value;
+    }
+    return shortSha?.trim() || "head";
+}

package/dist/op/activities/predict-behaviour.d.ts

@@ -66,6 +66,8 @@
 import { type BehaviourEdgeCoverage, type BehaviourResult } from "../../behaviour.js";
 import { type BehaviourDelta } from "../../behaviour-delta.js";
 import { reconcilePr } from "./reconcile.js";
+import { baseRefFrom, headRefFrom } from "./pr-refs.js";
+export { baseRefFrom, headRefFrom };
 export interface PredictBehaviourArgs {
     /** The environment the prediction is for, mirroring the deep read's `environment`. */
     environment: string;
@@ -167,10 +169,6 @@ export interface BehaviourFindingResult {
 export declare function behaviourFindingMarker(op: string, env: string): string;
 /** What the finding says when the run names no base branch to predict against. */
 export declare function noBaseRefMessage(): string;
-/** Where the base branch name comes from, most specific first. Pure — exported for testing. */
-export declare function baseRefFrom(env: Record<string, string | undefined>, explicit?: string): string | undefined;
-/** What the head side is called in the finding: the source branch when the run names one, else the short commit. */
-export declare function headRefFrom(env: Record<string, string | undefined>, shortSha?: string): string;
 /** A checked-out base branch: where its project root is, and how to remove it. */
 export interface BaseCheckout {
     /** The base branch's counterpart of the working directory. */

package/dist/op/activities/predict-behaviour.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predict-behaviour.d.ts","sourceRoot":"","sources":["../../../src/op/activities/predict-behaviour.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"predict-behaviour.d.ts","sourceRoot":"","sources":["../../../src/op/activities/predict-behaviour.ts"],"names":[],"mappings":"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"}