@gentbajko/slopify 3.17.0 → 3.18.0

package/dist/slices/rebuild/runtime-store.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { stageKinds, stageStates } from "../../kernel/pipeline.js";
 import { optionalDeps } from "../../kernel/runner/graph.js";
+import { admittedStates, parkedKinds } from "../admission/admitted-work.js";
 import { sourceOf } from "../admission/model.js";
 import { usesShorts, usesYoutubeDescription } from "../admission/rules.js";
 import { reviewsNarration } from "../reviews/rules.js";
@@ -138,7 +139,7 @@ export function executionStandings(deps, projectId, derived) {
     if (view === undefined)
         return [];
     const work = derived ?? executionStages(deps, projectId);
-    return stageKinds.map((kind) => {
+    const standings = stageKinds.map((kind) => {
         const source = sourceOf(view.revision.config.sources, kind);
         const group = work
             .filter((entry) => entry.kind === kind)
@@ -174,8 +175,17 @@ export function executionStandings(deps, projectId, derived) {
                     ? "provided"
                     : "done"
                 : "pending";
-        return state === "pending" && retryAt !== null ? { kind, state, retryAt } : { kind, state };
+        return state === "pending" && retryAt !== null
+            ? { kind, state, source, retryAt }
+            : { kind, state, source };
     });
+    const admitted = admittedStates(deps.db, projectId);
+    const parked = parkedKinds(deps.db, projectId);
+    return standings.map((stage) => ({
+        ...stage,
+        ...(admitted.has(`${stage.kind}:${stage.state}`) ? { admitted: true } : {}),
+        ...(parked.has(stage.kind) ? { parked: true } : {}),
+    }));
 }
 // A finished piece whose request was planned under this fingerprint: a placeholder is planned
 // under the logical fingerprint, the finished piece carries the one its request resolved to.
@@ -216,7 +226,9 @@ export function projectStandings(deps, projectId) {
                 .get(entry.work.workId);
             return total + fraction(progress?.progress_current, progress?.progress_total);
         }, 0);
-        // A failed step, or else one waiting to run again, says why on the stage row.
+        // A failed step, or else one waiting to run again, says why on the stage row. A failed
+        // stage keeps the moment it failed: needs_attention tells a narration retry started after
+        // the failure (still going) from one started before it (spent) by it.
         const failed = all.find((work) => work.state === "failed") ??
             (stage.retryAt === undefined || stage.retryAt === null
                 ? undefined
@@ -227,8 +239,23 @@ export function projectStandings(deps, projectId) {
                 .prepare("SELECT failure_reason,failure_kind FROM revision_work WHERE id=?")
                 .get(failed.work.workId);
         deps.db
-            .prepare("UPDATE stages SET state=?,failure_reason=?,failure_kind=?,retry_at=?,progress_current=?,progress_total=?,finished_at=CASE WHEN ?='done' THEN ? ELSE NULL END WHERE project_id=? AND kind=?")
-            .run(stage.state, textOf(failure?.failure_reason), textOf(failure?.failure_kind), stage.retryAt ?? null, invocations.length === 0 ? null : current, invocations.length === 0 ? null : invocations.length, stage.state, deps.clock.now().toISOString(), projectId, stage.kind);
+            .prepare(`UPDATE stages SET state=:state,failure_reason=:reason,failure_kind=:kind,retry_at=:retryAt,
+           progress_current=:current,progress_total=:total,
+           finished_at=CASE WHEN :state='done' THEN :now
+             WHEN :state='failed' THEN CASE WHEN state='failed' AND finished_at IS NOT NULL THEN finished_at ELSE :now END
+             ELSE NULL END
+         WHERE project_id=:projectId AND kind=:stage`)
+            .run({
+            state: stage.state,
+            reason: textOf(failure?.failure_reason),
+            kind: textOf(failure?.failure_kind),
+            retryAt: stage.retryAt ?? null,
+            current: invocations.length === 0 ? null : current,
+            total: invocations.length === 0 ? null : invocations.length,
+            now: deps.clock.now().toISOString(),
+            projectId,
+            stage: stage.kind,
+        });
     }
     settleScheduleRunsForProject(deps.db, projectId, deps.clock.now().toISOString());
     return work;

package/dist/slices/reruns/index.js

@@ -2,7 +2,8 @@ import { rmSync } from "node:fs";
 import { z } from "zod";
 import { transact } from "../../kernel/db/tx.js";
 import { allPiecesOf, deletePiece, deletePieces, setPiece, } from "../../kernel/runner/piece-repo.js";
-import { projectById, resetStage, stagesOf } from "../admission/repo.js";
+import { projectById, stagesOf } from "../admission/repo.js";
+import { resetStage } from "../admission/stage-writes.js";
 import { storeArticleText } from "../article/store.js";
 import { currentRevisionId } from "../revisions/repo.js";
 import { outputPath } from "../storage/layout.js";

package/dist/slices/research/run.js

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { transact } from "../../kernel/db/tx.js";
 import { isProviderError } from "../../kernel/ports/model.js";
 import { insertPiece, piecesOf, setPiece } from "../../kernel/runner/piece-repo.js";
-import { projectById, setStageProgress } from "../admission/repo.js";
+import { projectById } from "../admission/repo.js";
+import { setStageProgress } from "../admission/stage-writes.js";
 import { storeText } from "../storage/staging.js";
 import { noTokens, plusUsage } from "../telemetry/model.js";
 import { researchDocuments } from "./documents.js";

package/dist/slices/reviews/external-model.js

@@ -0,0 +1,21 @@
+// ceiling: the owner's number. An hourly agent routine answers well inside two hours; a run
+// with no agent at all still finishes the same evening.
+export const externalReviewWaitMs = 2 * 60 * 60 * 1000;
+// `canceled`: Cancel closed it while it waited; taken up again, its step asks it once more.
+export const externalReviewStates = [
+    "waiting",
+    "answered",
+    "auto-passed",
+    "superseded",
+    "canceled",
+];
+// Why a review takes no verdict, one sentence per standing: what get_external_review explains,
+// and what a refused verdict says after "The verdict wasn't saved."
+export const closedReviewSentences = {
+    answered: "This review was already answered, so it takes no other verdict. Call needs_attention to see what is waiting now.",
+    "auto-passed": "This review passed at its 2-hour deadline with no verdict, so it takes none now. Call needs_attention to see what is waiting now.",
+    superseded: "This review was replaced: its item was made again or edited, and the new one waits for its own verdict. Call needs_attention to see it.",
+    "replaced-pending": "This review was replaced: its item was made again or edited, so it takes no verdict, and no new review waits for it yet. One opens once the new item is made; an edit saved but not continued makes none until the run is continued. There is nothing to answer here: call needs_attention to see what is waiting now.",
+    canceled: "This review's run was canceled, so nothing waits on it and it takes no verdict: a canceled run's reviews never pass. Call needs_attention to see what is waiting now.",
+    trashed: "This review's project is in the Trash, so nothing waits on it and it takes no verdict. Restore the project in Settings → Backup & storage → Trash; the review then waits for its verdict again.",
+};

package/dist/slices/reviews/external-release.js

@@ -0,0 +1,38 @@
+import { causedBy } from "../../kernel/errors.js";
+import { reviewItemName } from "../notifications/rules.js";
+import { revisionById } from "../revisions/repo.js";
+import { settleExternalReviews } from "./external-repo.js";
+function itemName(db, review) {
+    const revision = revisionById(db, review.projectId, review.revisionId);
+    return reviewItemName(review.itemKey, revision?.content.imageOrder ?? []);
+}
+// At boot and every few seconds: each review past its deadline passes, says so, and the run
+// goes on. The deadline is a row, so a restart in between loses nothing. Each passed review is
+// announced and woken on its own: one that throws is logged, and the others still go on (the
+// passing itself is already saved).
+export function releaseDueReviews(deps) {
+    const passed = settleExternalReviews(deps.db, deps.now());
+    for (const review of passed) {
+        try {
+            deps.emit(review.projectId, {
+                type: "review.auto-passed",
+                projectId: review.projectId,
+                reviewId: review.id,
+                stage: review.stage,
+                itemKey: review.itemKey,
+                item: itemName(deps.db, review),
+                revisionId: review.revisionId,
+                workId: review.workId,
+            });
+            deps.emit(review.projectId, { type: "project.updated", projectId: review.projectId });
+            deps.tick(review.projectId);
+        }
+        catch (error) {
+            deps.log.write("error", "review.deadline", {
+                projectId: review.projectId,
+                detail: `Review ${review.id} passed at its deadline, but announcing it or waking the run failed: ${causedBy(error)}`,
+            });
+        }
+    }
+    return passed.length;
+}

package/dist/slices/reviews/external-repo.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { transact } from "../../kernel/db/tx.js";
+import { liveProject } from "../admission/repo.js";
+import { externalReviewByFingerprint, externalReviewById } from "./external-rows.js";
+import { liveWork, reviewStanding, wantedBy } from "./external-waiting.js";
+import { reviewStages } from "./model.js";
+// A step asked again for the same review keeps its row; one whose earlier wait was superseded
+// or canceled waits again from now.
+export function openExternalReview(db, input) {
+    db.prepare(`INSERT INTO external_reviews(id,project_id,revision_id,work_id,piece_id,work_key,item_key,stage,item_fingerprint,review_fingerprint,material,state,waiting_since,deadline_at)
+     VALUES (?,?,?,?,?,?,?,?,?,?,?,'waiting',?,?)
+     ON CONFLICT(project_id,review_fingerprint) DO UPDATE SET revision_id=excluded.revision_id,
+       work_id=excluded.work_id,piece_id=excluded.piece_id,work_key=excluded.work_key,
+       item_fingerprint=excluded.item_fingerprint,material=excluded.material,state='waiting',
+       waiting_since=excluded.waiting_since,deadline_at=excluded.deadline_at,verdict=NULL,
+       answered_by=NULL,answered_at=NULL
+     WHERE external_reviews.state IN ('superseded','canceled')`).run(input.id, input.projectId, input.revisionId, input.workId, input.pieceId, input.workKey, input.itemKey, input.stage, input.itemFingerprint, input.reviewFingerprint, JSON.stringify(input.material), input.waitingSince, input.deadlineAt);
+    const saved = externalReviewByFingerprint(db, input.projectId, input.reviewFingerprint);
+    if (saved === undefined)
+        throw new Error("Slopify hit an internal error (an external review could not be saved). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
+    return saved;
+}
+// Cancel stops a run's reviews waiting. Retried, its step asks again (`openExternalReview`) and
+// each review waits its whole two hours from then, not from before the cancel.
+export function stopWaitingReviews(db, projectId) {
+    db.prepare("UPDATE external_reviews SET state='canceled' WHERE project_id=? AND state='waiting'").run(projectId);
+}
+// The step that waited ended its stage as held, which parks the work (`finishWork`); a settled
+// review lets it be claimed again while the current version still wants it. A restart also
+// held the work's unfinished pieces (`recoverWork`), so the ones never submitted are allowed
+// again, as boot does for work it keeps (`recoverCheckpointWork`). A paused project stays put:
+// the runner claims nothing for it until Resume.
+function releaseParkedWork(db, projectId, id) {
+    const parked = `(SELECT e.work_id FROM external_reviews e WHERE e.project_id=? AND e.id=? AND ${wantedBy("e")})`;
+    const released = db
+        .prepare(`UPDATE revision_work SET dispatch_state='allowed' WHERE state='pending' AND dispatch_state='held' AND id=${parked}`)
+        .run(projectId, id);
+    if (Number(released.changes) === 0)
+        return;
+    db.prepare(`UPDATE revision_work_pieces SET state='pending',dispatch_state='allowed'
+     WHERE work_id=${parked} AND state='held' AND submitted_at IS NULL AND continuation IS NULL`).run(projectId, id);
+}
+// The first verdict saved wins: read and answered in one transaction, so two agents answering
+// at once cannot both succeed. A review whose item was just replaced is superseded here rather
+// than at the next settle, a project in the Trash takes no verdict until it is restored, and a
+// canceled run's review takes none at all.
+export function answerExternalReview(db, input) {
+    return transact(db, () => {
+        const review = externalReviewById(db, input.projectId, input.id);
+        if (review === undefined)
+            return { ok: false, reason: "not-found" };
+        const standing = reviewStanding(db, review);
+        if (standing === "trashed")
+            return { ok: false, reason: "trashed" };
+        if (standing === "superseded" || standing === "replaced-pending")
+            db.prepare("UPDATE external_reviews SET state='superseded' WHERE project_id=? AND id=? AND state='waiting'").run(input.projectId, input.id);
+        if (standing !== "waiting")
+            return { ok: false, reason: standing, value: review };
+        db.prepare("UPDATE external_reviews SET state='answered', verdict=?, answered_by=?, answered_at=? WHERE project_id=? AND id=?").run(JSON.stringify(input.verdict), input.by, input.at, input.projectId, input.id);
+        releaseParkedWork(db, input.projectId, input.id);
+        return {
+            ok: true,
+            value: {
+                ...review,
+                state: "answered",
+                verdict: input.verdict,
+                answeredBy: input.by,
+                answeredAt: input.at,
+            },
+        };
+    });
+}
+const dueRow = z.object({
+    id: z.string(),
+    project_id: z.string(),
+    revision_id: z.string(),
+    work_id: z.string(),
+    stage: z.enum(reviewStages),
+    item_key: z.string(),
+});
+// Replaced reviews stop waiting; waiting ones past their deadline pass without review. A
+// paused project's review passes too (nothing runs until Resume); a canceled run's never does,
+// nor one of a project in the Trash (it waits on, and passes once restored).
+// Read by plain columns only: a review whose stored material can't be read back still passes,
+// and never holds up the others.
+export function settleExternalReviews(db, now) {
+    const at = now.toISOString();
+    return transact(db, () => {
+        db.prepare(`UPDATE external_reviews SET state='superseded' WHERE state='waiting' AND NOT ${wantedBy("external_reviews")}`).run();
+        const due = db
+            .prepare(`SELECT e.id, e.project_id, e.revision_id, e.work_id, e.stage, e.item_key FROM external_reviews e
+         WHERE e.state='waiting' AND e.deadline_at<=? AND ${liveWork("e")} AND ${liveProject("e", "project_id")}
+         ORDER BY e.waiting_since, e.rowid`)
+            .all(at)
+            .map((value) => dueRow.parse(value));
+        return due.map((row) => {
+            db.prepare("UPDATE external_reviews SET state='auto-passed', answered_at=? WHERE id=? AND state='waiting'").run(at, row.id);
+            releaseParkedWork(db, row.project_id, row.id);
+            return {
+                id: row.id,
+                projectId: row.project_id,
+                revisionId: row.revision_id,
+                workId: row.work_id,
+                stage: row.stage,
+                itemKey: row.item_key,
+            };
+        });
+    });
+}

package/dist/slices/reviews/external-rows.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { actors } from "../agents/model.js";
+import { externalReviewStates } from "./external-model.js";
+import { reviewStages } from "./model.js";
+const materialSchema = z.object({
+    request: z.object({
+        stage: z.enum(reviewStages),
+        instruction: z.string(),
+        sections: z.array(z.object({ label: z.string(), text: z.string() })),
+        images: z.array(z.string()),
+    }),
+    images: z.array(z.object({ stored: z.string(), name: z.string() })),
+});
+const verdictSchema = z.object({ passed: z.boolean(), reasons: z.array(z.string()) });
+const rowSchema = z.object({
+    id: z.string(),
+    project_id: z.string(),
+    revision_id: z.string(),
+    work_id: z.string(),
+    piece_id: z.string(),
+    work_key: z.string(),
+    item_key: z.string(),
+    stage: z.enum(reviewStages),
+    item_fingerprint: z.string(),
+    review_fingerprint: z.string(),
+    material: z.string(),
+    state: z.enum(externalReviewStates),
+    waiting_since: z.string(),
+    deadline_at: z.string(),
+    verdict: z.string().nullable(),
+    answered_by: z.enum(actors).nullable(),
+    answered_at: z.string().nullable(),
+});
+// One stored review as the slice speaks of it; throws for a row that can't be read back.
+export function externalReviewOf(value) {
+    const row = rowSchema.parse(value);
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        revisionId: row.revision_id,
+        workId: row.work_id,
+        pieceId: row.piece_id,
+        workKey: row.work_key,
+        itemKey: row.item_key,
+        stage: row.stage,
+        itemFingerprint: row.item_fingerprint,
+        reviewFingerprint: row.review_fingerprint,
+        material: materialSchema.parse(JSON.parse(row.material)),
+        state: row.state,
+        waitingSince: row.waiting_since,
+        deadlineAt: row.deadline_at,
+        verdict: row.verdict === null ? null : verdictSchema.parse(JSON.parse(row.verdict)),
+        answeredBy: row.answered_by,
+        answeredAt: row.answered_at,
+    };
+}
+export function externalReviewByFingerprint(db, projectId, reviewFingerprint) {
+    const row = db
+        .prepare("SELECT * FROM external_reviews WHERE project_id=? AND review_fingerprint=?")
+        .get(projectId, reviewFingerprint);
+    return row === undefined ? undefined : externalReviewOf(row);
+}
+export function externalReviewById(db, projectId, id) {
+    const row = db
+        .prepare("SELECT * FROM external_reviews WHERE project_id=? AND id=?")
+        .get(projectId, id);
+    return row === undefined ? undefined : externalReviewOf(row);
+}

package/dist/slices/reviews/external-waiting.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { liveProject, oneProject, projectTrashed } from "../admission/repo.js";
+import { externalReviewOf } from "./external-rows.js";
+// A review the project still wants: its step is reserved by the project's current version with
+// the same fingerprint. A rerun or an edit that replaced the item leaves it unwanted.
+export function wantedBy(table) {
+    return `EXISTS (SELECT 1 FROM revision_work_reservations r
+    JOIN project_heads h ON h.project_id=r.project_id AND h.revision_id=r.revision_id
+    WHERE r.project_id=${table}.project_id AND r.work_id=${table}.work_id
+      AND r.work_key=${table}.work_key AND r.fingerprint=${table}.review_fingerprint)`;
+}
+// Nothing of a canceled run goes ahead on its own: the review's work, or its own step, is
+// canceled. Another step canceled is not enough: retrying one step (`recoverProject`) admits
+// it again while the rest stay canceled, and its reviews wait for their verdict.
+export function liveWork(table) {
+    return `EXISTS (SELECT 1 FROM revision_work w WHERE w.id=${table}.work_id AND NOT ${canceledStep("w")})`;
+}
+// The step reads canceled by its stage too, whatever the work row says: a restart before
+// canceled work was kept canceled (`recoverWork`) held it pending.
+function canceledStep(work) {
+    return `(${work}.state='canceled' OR EXISTS (SELECT 1 FROM stages s WHERE s.id=${work}.stage_id AND s.state='canceled'))`;
+}
+// Where a review stands, in the one order get_external_review and a refused verdict both say
+// it: a verdict already kept, its run canceled (Cancel closed it, or its step reads canceled;
+// no new one waits until the step is taken up and asks again, unless its item was made again
+// and the new review waits: superseded), its item replaced or its step gone (`superseded`, or
+// `replaced-pending` while no new one waits yet), then its project in the Trash - said last,
+// as only then would Restore bring it back. It waits only when none holds, exactly when
+// `stillWaiting` lists it.
+export function reviewStanding(db, review) {
+    if (review.state === "answered" || review.state === "auto-passed")
+        return review.state;
+    if (review.state === "canceled" ||
+        db
+            .prepare(`SELECT 1 FROM revision_work w WHERE w.id=? AND ${canceledStep("w")}`)
+            .get(review.workId) !== undefined)
+        return replacementWaits(db, review) ? "superseded" : "canceled";
+    const wanted = review.state === "waiting" &&
+        db
+            .prepare(`SELECT 1 FROM external_reviews e WHERE e.project_id=? AND e.id=? AND ${wantedBy("e")} AND ${liveWork("e")}`)
+            .get(review.projectId, review.id) !== undefined;
+    if (!wanted)
+        return replacementWaits(db, review) ? "superseded" : "replaced-pending";
+    return projectTrashed(db, review.projectId) ? "trashed" : "waiting";
+}
+// Whether another review of the same item waits in its place, the project in the Trash or not:
+// either way the old one was replaced.
+function replacementWaits(db, review) {
+    return (db
+        .prepare(`SELECT 1 FROM external_reviews e WHERE ${wantedAndLive} AND e.project_id=? AND e.item_key=? AND e.id!=?`)
+        .get(review.projectId, review.itemKey, review.id) !== undefined);
+}
+// A review `e` marked waiting, still wanted and of a run that isn't canceled.
+const wantedAndLive = `e.state='waiting' AND ${wantedBy("e")} AND ${liveWork("e")}`;
+// A review `e` that waits: the same, of a project not in the Trash.
+const stillWaiting = `${wantedAndLive} AND ${liveProject("e", "project_id")}`;
+// Waiting, still wanted by the current version, of a run that isn't canceled, oldest first.
+export function waitingExternalReviews(db, projectId) {
+    return waitingExternalReviewRows(db, projectId).map(externalReviewOf);
+}
+// The same rows unread, for a caller that skips one it can't read instead of failing them all.
+export function waitingExternalReviewRows(db, projectId) {
+    const one = oneProject("e", projectId);
+    return db
+        .prepare(`SELECT e.* FROM external_reviews e WHERE ${stillWaiting}${one.sql} ORDER BY e.waiting_since, e.rowid`)
+        .all(...one.params);
+}
+// The projects with a review waiting for an agent, as `waitingExternalReviewRows` finds them.
+export function projectsWaitingOnAgents(db, projectId) {
+    const one = oneProject("e", projectId);
+    const rows = db
+        .prepare(`SELECT DISTINCT e.project_id FROM external_reviews e WHERE ${stillWaiting}${one.sql}`)
+        .all(...one.params);
+    return new Set(rows.map((row) => z.string().parse(row.project_id)));
+}

package/dist/slices/reviews/holds.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { derive, satisfied, deps as stageDeps, } from "../../kernel/runner/graph.js";
+import { pendingAdmitted } from "../admission/admitted-work.js";
+import { liveProject, oneProject, stageStandingsByProject } from "../admission/repo.js";
+import { checkpointStageSchema } from "../checkpoints/schema.js";
+import { heldForItsDay } from "../schedules/prepare.js";
+import { uploadedAndSettled } from "../uploads/repo.js";
+import { projectsWaitingOnAgents } from "./external-waiting.js";
+const gateRow = z.object({
+    project_id: z.string(),
+    checkpoint_id: z.string(),
+    stage: checkpointStageSchema,
+    revision_id: z.string(),
+    fingerprint: z.string(),
+    created_at: z.string(),
+    own: z.number(),
+});
+const projectRow = z.object({ project_id: z.string() });
+// Every project's holds, or one project's alone when `projectId` is given. A caller that has
+// already read the stage standings (`stageStandingsByProject`) or the uploaded projects that
+// read Done (`uploadedAndSettled`) passes them; one that lists what it can read passes `skip`,
+// given each checkpoint row that can't be read instead of failing them all.
+export function projectHolds(db, scope = {}) {
+    const { projectId, skip } = scope;
+    const gatesOf = oneProject("c", projectId);
+    const gateSql = `SELECT c.project_id, c.checkpoint_id, c.stage, c.revision_id, c.fingerprint, c.created_at, (c.stage='video' AND ${heldForItsDay("c")}) AS own
+       FROM review_checkpoints c
+       JOIN project_heads h ON h.project_id=c.project_id AND h.revision_id=c.revision_id
+       WHERE c.state IN ('held','pending-review') AND c.approved_at IS NULL AND ${liveProject("c", "project_id")}${gatesOf.sql}`;
+    const gates = db
+        .prepare(gateSql)
+        .all(...gatesOf.params)
+        .flatMap((row) => {
+        if (skip === undefined)
+            return [gateRow.parse(row)];
+        const gate = gateRow.safeParse(row);
+        if (gate.success)
+            return [gate.data];
+        skip(row, gate.error);
+        return [];
+    });
+    const standings = scope.standings ?? stageStandingsByProject(db, projectId);
+    // A checkpoint holds the run once the stages its step needs are made; before that the run
+    // is held by whatever those stages wait on.
+    const reached = (project, stage) => stageDeps[stage].every((dependency) => {
+        const standing = standings.get(project)?.find((made) => made.kind === dependency);
+        return standing === undefined || satisfied(standing.state);
+    });
+    const theirs = new Set();
+    const reachedTheirs = new Set();
+    const reachedOwn = new Set();
+    const holding = new Map();
+    for (const gate of gates) {
+        const own = gate.own === 1;
+        if (!own)
+            theirs.add(gate.project_id);
+        if (!reached(gate.project_id, gate.stage))
+            continue;
+        (own ? reachedOwn : reachedTheirs).add(gate.project_id);
+        const hold = {
+            checkpointId: gate.checkpoint_id,
+            stage: gate.stage,
+            waitsFor: own ? "day" : "person",
+            revisionId: gate.revision_id,
+            fingerprint: gate.fingerprint,
+            since: gate.created_at,
+        };
+        holding.set(gate.project_id, [...(holding.get(gate.project_id) ?? []), hold]);
+    }
+    const headsOf = oneProject("h", projectId);
+    const scheduled = db
+        .prepare(`SELECT h.project_id FROM project_heads h WHERE ${heldForItsDay("h")}${headsOf.sql}`)
+        .all(...headsOf.params)
+        .map((row) => projectRow.parse(row).project_id);
+    const agents = projectsWaitingOnAgents(db, projectId);
+    const runs = heldRuns(db, projectId);
+    // An uploaded project with nothing admitted reads Done (`edge/http/projects.ts`).
+    const settled = scope.settled ?? uploadedAndSettled(db, projectId);
+    const waitingForAgent = new Set([...agents].filter((id) => !reachedTheirs.has(id) && runs.get(id)?.held !== true));
+    const stopped = new Set([...runs]
+        .filter(([, run]) => run.stuck)
+        .map(([id]) => id)
+        .filter((id) => !reachedTheirs.has(id) &&
+        !waitingForAgent.has(id) &&
+        // Held at its day's hold, it goes on by itself on its day, though a failed step's
+        // admission holds its video's step back until then; a step a restart held still
+        // waits for Continue the run.
+        (!reachedOwn.has(id) || runs.get(id)?.held === true) &&
+        !settled.has(id) &&
+        derive(standings.get(id) ?? []) === "pending"));
+    return {
+        prepared: new Set(scheduled.filter((id) => !theirs.has(id) && !stopped.has(id))),
+        waitingForAgent,
+        stopped,
+        // Only Continue the run moves a stopped run on: the one hold it can have reached, its
+        // day's, holds it again once it has.
+        holding: new Map([...holding].filter(([id]) => !stopped.has(id))),
+    };
+}
+// An admitted step of `h`'s project still to run (`pendingAdmitted`), held other than one
+// parked on an agent's review: a restart (`recoverWork`) or a pause held it, and only Continue
+// the run starts it.
+function heldBesideReviews(h) {
+    return `EXISTS (SELECT 1 FROM revision_work w
+     WHERE w.project_id=${h}.project_id AND w.dispatch_state='held' AND ${pendingAdmitted("w")}
+       AND NOT EXISTS (SELECT 1 FROM external_reviews e WHERE e.work_id=w.id AND e.state='waiting'))`;
+}
+const runRow = z.object({ project_id: z.string(), held: z.number(), stuck: z.number() });
+// Whether `h` is still: no step's call in flight, not paused and not waiting its turn in a
+// batch. A running stage needs no clause here: it makes the run's state running (`derive`).
+function still(h) {
+    return `NOT EXISTS(SELECT 1 FROM revision_work w WHERE w.project_id=${h}.project_id AND w.state='running')
+    AND NOT EXISTS(SELECT 1 FROM project_controls c WHERE c.project_id=${h}.project_id AND c.paused=1)
+    AND NOT EXISTS(SELECT 1 FROM project_queue q WHERE q.project_id=${h}.project_id AND q.state='queued')`;
+}
+// No admitted work of `h`'s current version that can start: a saved rerun or edit is admitted
+// by no one until Resume, and work whose admission has a failed sibling never starts.
+function nothingAdmitted(h) {
+    return `NOT EXISTS(SELECT 1 FROM revision_work w
+    JOIN revision_work_reservations r ON r.work_id=w.id AND r.revision_id=${h}.revision_id
+    WHERE w.state='pending' AND w.dispatch_state='allowed' AND NOT EXISTS(
+      SELECT 1 FROM revision_work f WHERE f.admission_id=w.admission_id AND f.state IN ('failed','canceled')))`;
+}
+// Each project out of the Trash with a step held beside the reviews (`held`), and whether its
+// run is stuck: it has unfinished stages, is still, and nothing will move it on but Continue
+// the run, because nothing admitted can start or because a step is held (a step still allowed
+// may wait on it). Each reading is made once per project (MATERIALIZED), not once per use.
+function heldRuns(db, projectId) {
+    const one = oneProject("h", projectId);
+    const rows = db
+        .prepare(`WITH runs AS MATERIALIZED (
+         SELECT h.project_id, ${heldBesideReviews("h")} AS held,
+           EXISTS(SELECT 1 FROM stages s WHERE s.project_id=h.project_id AND s.state NOT IN ('done','provided','skipped'))
+             AND ${still("h")} AS idle,
+           ${nothingAdmitted("h")} AS unadmitted
+         FROM project_heads h WHERE ${liveProject("h", "project_id")}${one.sql})
+       SELECT project_id, held, idle AND (held OR unadmitted) AS stuck FROM runs
+       WHERE held OR (idle AND unadmitted)`)
+        .all(...one.params);
+    return new Map(rows.map((row) => {
+        const run = runRow.parse(row);
+        return [run.project_id, { held: run.held === 1, stuck: run.stuck === 1 }];
+    }));
+}

package/dist/slices/reviews/model.js

@@ -6,6 +6,15 @@ export const reviewStages = ["article", "images", "narration", "thumbnail", "sho
 // Off is the same as the stage having no entry, which is what every project saved before
 // reviews existed has.
 export const reviewModes = ["off", "flag", "redo"];
+// Who answers the reviews: a text model Slopify calls, or an external agent through MCP.
+export const reviewers = ["model", "agent"];
+// Who gave a verdict: the reviewer model, an external agent, the person (through the verdict
+// route), or nobody when the review passed at its deadline.
+export const reviewAnswerers = ["model", "agent", "person", "nobody"];
+export const reviewerLabels = {
+    model: "Model",
+    agent: "External agent (MCP)",
+};
 // ceiling: the owner's numbers. Two redos is what a person would try before looking at it
 // themselves; five is already six paid images for one slot.
 export const defaultReviewRetries = 2;
@@ -35,6 +44,9 @@ export function reviewModeOf(settings, stage) {
 export function reviewRetriesOf(settings) {
     return settings?.retries ?? defaultReviewRetries;
 }
+export function reviewedByAgent(settings) {
+    return settings?.reviewer === "agent";
+}
 export function reviewedStages(settings) {
     return reviewStages.filter((stage) => reviewModeOf(settings, stage) !== "off");
 }
@@ -56,6 +68,7 @@ export function reviewSettingsForm(settings) {
         provider: settings.provider,
         model: settings.model,
         ...(settings.thinking === undefined ? {} : { thinking: settings.thinking }),
+        ...(settings.reviewer === "agent" ? { reviewer: "agent" } : {}),
         retries: settings.retries === undefined ? "" : String(settings.retries),
         stages: Object.fromEntries(reviewStages.flatMap((stage) => {
             const picked = settings.stages[stage];
@@ -86,6 +99,7 @@ export function reviewSettingsFromForm(form, makes) {
             provider: form.provider,
             model: form.model,
             ...(form.thinking === undefined ? {} : { thinking: form.thinking }),
+            ...(form.reviewer === "agent" ? { reviewer: "agent" } : {}),
             ...(retries === undefined || !valid ? {} : { retries }),
             stages,
         },