@aglyn/plugins-ai 1.0.0-beta.266 → 1.0.0-beta.269

package/src/lib/jobs/ai-jobs-beat.d.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 import { type SweepAiJobsResult } from './ai-jobs';
+import { type AiEmptySiteSweepResult } from './ai-empty-site-sweep';
 /**
  * Resume AI generation jobs on the AI jobs beat (AGL-2904, AGL-3026).
  *
@@ -69,10 +70,17 @@ export type AiJobsBeatResult = {
     held: true;
 } | ({
     held: false;
+    emptySites: AiEmptySiteSweepResult | null;
 } & SweepAiJobsResult);
 /**
- * One beat: the switch, then one sweep under its own lease owner. The owner
- * is fresh per beat and fixed for the whole sweep, so two beats overlapping
- * inside a lease never read each other's lease as their own.
+ * One beat: the switch, then the empty sites a guided start left that are
+ * due for removal (AGL-3936), then one sweep under its own lease owner. The
+ * owner is fresh per beat and fixed for the whole sweep, so two beats
+ * overlapping inside a lease never read each other's lease as their own.
+ *
+ * The removals come first, a few a beat inside
+ * `AI_EMPTY_SITE_SWEEP_BUDGET_MS`, and whatever they took comes off the
+ * sweep's budget, so the route's arithmetic inside `maxDuration` holds. A
+ * removal that fails never holds up a job's step.
  */
 export declare function runAiJobsBeat(): Promise<AiJobsBeatResult>;

package/src/lib/jobs/ai-jobs-beat.js

@@ -17,6 +17,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  */ import { randomUUID } from "crypto";
 import { featureLockdownRefusal, firebaseAdmin } from "@aglyn/tenant-data-admin";
 import { AI_JOB_SWEEP_BUDGET_MS, sweepAiJobs } from "./ai-jobs.js";
+import { sweepAiEmptySites } from "./ai-empty-site-sweep.js";
 /**
  * Resume AI generation jobs on the AI jobs beat (AGL-2904, AGL-3026).
  *
@@ -64,9 +65,15 @@ import { AI_JOB_SWEEP_BUDGET_MS, sweepAiJobs } from "./ai-jobs.js";
  * with the sweep's function time, so the plugin dispatcher never serves it.
  */ export const AI_JOBS_BEAT_PATH = 'admin/ai-jobs-beat';
 /**
- * One beat: the switch, then one sweep under its own lease owner. The owner
- * is fresh per beat and fixed for the whole sweep, so two beats overlapping
- * inside a lease never read each other's lease as their own.
+ * One beat: the switch, then the empty sites a guided start left that are
+ * due for removal (AGL-3936), then one sweep under its own lease owner. The
+ * owner is fresh per beat and fixed for the whole sweep, so two beats
+ * overlapping inside a lease never read each other's lease as their own.
+ *
+ * The removals come first, a few a beat inside
+ * `AI_EMPTY_SITE_SWEEP_BUDGET_MS`, and whatever they took comes off the
+ * sweep's budget, so the route's arithmetic inside `maxDuration` holds. A
+ * removal that fails never holds up a job's step.
  */ export async function runAiJobsBeat() {
     const locked = await featureLockdownRefusal({
         feature: 'ai-generate'
@@ -77,16 +84,26 @@ import { AI_JOB_SWEEP_BUDGET_MS, sweepAiJobs } from "./ai-jobs.js";
             held: true
         };
     }
+    const firestore = firebaseAdmin.app().firestore();
+    const startedAt = Date.now();
+    const emptySites = await sweepAiEmptySites({
+        firestore
+    }).catch((error)=>{
+        console.error('ai jobs beat: the empty site sweep failed', error);
+        return null;
+    });
+    if (emptySites == null ? void 0 : emptySites.removed) console.info(`ai jobs: ${emptySites.removed} empty site(s) removed`);
     const result = await sweepAiJobs({
-        firestore: firebaseAdmin.app().firestore(),
+        firestore,
         owner: `beat:${randomUUID()}`,
-        budgetMs: AI_JOB_SWEEP_BUDGET_MS
+        budgetMs: Math.max(0, AI_JOB_SWEEP_BUDGET_MS - (Date.now() - startedAt))
     });
     if (result.due) {
         console.info(`ai jobs: ${result.ran} step(s) run, ${result.skipped} skipped, ` + `${result.paused} held by a workspace's AI pause, ` + `${result.remaining} left for the next beat` + (result.budgetExhausted ? ' (budget exhausted)' : ''));
     }
     return _extends({
-        held: false
+        held: false,
+        emptySites
     }, result);
 }
 

package/src/lib/jobs/ai-jobs-beat.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-jobs-beat.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { randomUUID } from 'crypto'\nimport { featureLockdownRefusal, firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { AI_JOB_SWEEP_BUDGET_MS, sweepAiJobs, type SweepAiJobsResult } from './ai-jobs'\n\n/**\n * Resume AI generation jobs on the AI jobs beat (AGL-2904, AGL-3026).\n *\n * A job's first step runs inline in the console route when it can; every\n * step after it, every step too long for an inline door, and any step a\n * budget cut short, runs here. The sweep bounds itself at\n * `AI_JOB_SWEEP_BUDGET_MS` of wall clock and hands the rest to the next beat\n * — the ordering of the queue is the cursor, so nothing is stored between\n * beats and nothing can be skipped.\n *\n * ## Why the console runs it\n *\n * A step calls the AI provider, and the provider's key is held by the\n * console alone: the tenant app serves every published site, and a\n * credential it holds is one request-handling bug away from a visitor. So\n * the beat is a console route (`server/ai-jobs-beat-route.ts`, registered\n * by the console surface), driven every minute by its own Cloud Scheduler\n * job in `cloud/functions` on the console's cron secret — the reason the\n * sending-domain sweep is a console route and not a job on the tenant's\n * platform beat. A beat must resolve to the minute: a step handed back by\n * a budget, or a page pass waiting on the next, should resume on the next\n * minute, not the next quarter hour.\n *\n * ## The kill switch\n *\n * `ai-generate` on the staff lockdown page is the lever for a provider\n * incident or a spend runaway on the generative doors, and this beat is the\n * one generative caller with no request to refuse. So it asks the same\n * feature verdict a door would — the platform scope and then the feature\n * document — and does nothing while either is locked. A job it leaves\n * queued stays queued: its lease is not taken, so nothing expires and\n * nothing is lost, and the first beat after the lock lifts picks it up.\n *\n * The same switch paused for ONE workspace (AGL-3037) holds that workspace's\n * jobs and no other's: `runAiJobStep` asks the verdict with the job's org\n * before it claims a step, and leaves a paused workspace's job queued.\n */\n\n/** The beat's row in `SCHEDULED_JOBS`, and the mark it leaves for `/api/health/crons`. */\nexport const AI_JOBS_BEAT_CRON_ID = 'ai-jobs-beat'\n\n/**\n * The console path the beat is registered at: the one path this plugin\n * registers outside its own prefixes. `/api/admin/` is where the console's\n * scheduled sweeps live, and the console's edge lets a request past its bot\n * challenge there when it carries the cron secret's header — a route\n * anywhere else would need a firewall rule of its own before a scheduler\n * could reach it. The console app serves this exact path from a named route\n * with the sweep's function time, so the plugin dispatcher never serves it.\n */\nexport const AI_JOBS_BEAT_PATH = 'admin/ai-jobs-beat'\n\n/** What one beat did: nothing while `ai-generate` is locked, else the sweep's account. */\nexport type AiJobsBeatResult =\n  | { held: true }\n  | ({ held: false } & SweepAiJobsResult)\n\n/**\n * One beat: the switch, then one sweep under its own lease owner. The owner\n * is fresh per beat and fixed for the whole sweep, so two beats overlapping\n * inside a lease never read each other's lease as their own.\n */\nexport async function runAiJobsBeat(): Promise<AiJobsBeatResult> {\n  const locked = await featureLockdownRefusal({ feature: 'ai-generate' })\n  if (locked) {\n    console.warn('ai jobs beat held: ai-generate is locked')\n    return { held: true }\n  }\n  const result = await sweepAiJobs({\n    firestore: firebaseAdmin.app().firestore(),\n    owner: `beat:${randomUUID()}`,\n    budgetMs: AI_JOB_SWEEP_BUDGET_MS,\n  })\n  if (result.due) {\n    console.info(\n      `ai jobs: ${result.ran} step(s) run, ${result.skipped} skipped, ` +\n        `${result.paused} held by a workspace's AI pause, ` +\n        `${result.remaining} left for the next beat` +\n        (result.budgetExhausted ? ' (budget exhausted)' : ''),\n    )\n  }\n  return { held: false, ...result }\n}\n"],"names":["randomUUID","featureLockdownRefusal","firebaseAdmin","AI_JOB_SWEEP_BUDGET_MS","sweepAiJobs","AI_JOBS_BEAT_CRON_ID","AI_JOBS_BEAT_PATH","runAiJobsBeat","locked","feature","console","warn","held","result","firestore","app","owner","budgetMs","due","info","ran","skipped","paused","remaining","budgetExhausted"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,QAAQ,SAAQ;AACnC,SAASC,sBAAsB,EAAEC,aAAa,QAAQ,2BAA0B;AAChF,SAASC,sBAAsB,EAAEC,WAAW,QAAgC,eAAW;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCC,GAED,wFAAwF,GACxF,OAAO,MAAMC,uBAAuB,eAAc;AAElD;;;;;;;;CAQC,GACD,OAAO,MAAMC,oBAAoB,qBAAoB;AAOrD;;;;CAIC,GACD,OAAO,eAAeC;IACpB,MAAMC,SAAS,MAAMP,uBAAuB;QAAEQ,SAAS;IAAc;IACrE,IAAID,QAAQ;QACVE,QAAQC,IAAI,CAAC;QACb,OAAO;YAAEC,MAAM;QAAK;IACtB;IACA,MAAMC,SAAS,MAAMT,YAAY;QAC/BU,WAAWZ,cAAca,GAAG,GAAGD,SAAS;QACxCE,OAAO,CAAC,KAAK,EAAEhB,cAAc;QAC7BiB,UAAUd;IACZ;IACA,IAAIU,OAAOK,GAAG,EAAE;QACdR,QAAQS,IAAI,CACV,CAAC,SAAS,EAAEN,OAAOO,GAAG,CAAC,cAAc,EAAEP,OAAOQ,OAAO,CAAC,UAAU,CAAC,GAC/D,GAAGR,OAAOS,MAAM,CAAC,iCAAiC,CAAC,GACnD,GAAGT,OAAOU,SAAS,CAAC,uBAAuB,CAAC,GAC3CV,CAAAA,OAAOW,eAAe,GAAG,wBAAwB,EAAC;IAEzD;IACA,OAAO;QAAEZ,MAAM;OAAUC;AAC3B"}
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-jobs-beat.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { randomUUID } from 'crypto'\nimport { featureLockdownRefusal, firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { AI_JOB_SWEEP_BUDGET_MS, sweepAiJobs, type SweepAiJobsResult } from './ai-jobs'\nimport { sweepAiEmptySites, type AiEmptySiteSweepResult } from './ai-empty-site-sweep'\n\n/**\n * Resume AI generation jobs on the AI jobs beat (AGL-2904, AGL-3026).\n *\n * A job's first step runs inline in the console route when it can; every\n * step after it, every step too long for an inline door, and any step a\n * budget cut short, runs here. The sweep bounds itself at\n * `AI_JOB_SWEEP_BUDGET_MS` of wall clock and hands the rest to the next beat\n * — the ordering of the queue is the cursor, so nothing is stored between\n * beats and nothing can be skipped.\n *\n * ## Why the console runs it\n *\n * A step calls the AI provider, and the provider's key is held by the\n * console alone: the tenant app serves every published site, and a\n * credential it holds is one request-handling bug away from a visitor. So\n * the beat is a console route (`server/ai-jobs-beat-route.ts`, registered\n * by the console surface), driven every minute by its own Cloud Scheduler\n * job in `cloud/functions` on the console's cron secret — the reason the\n * sending-domain sweep is a console route and not a job on the tenant's\n * platform beat. A beat must resolve to the minute: a step handed back by\n * a budget, or a page pass waiting on the next, should resume on the next\n * minute, not the next quarter hour.\n *\n * ## The kill switch\n *\n * `ai-generate` on the staff lockdown page is the lever for a provider\n * incident or a spend runaway on the generative doors, and this beat is the\n * one generative caller with no request to refuse. So it asks the same\n * feature verdict a door would — the platform scope and then the feature\n * document — and does nothing while either is locked. A job it leaves\n * queued stays queued: its lease is not taken, so nothing expires and\n * nothing is lost, and the first beat after the lock lifts picks it up.\n *\n * The same switch paused for ONE workspace (AGL-3037) holds that workspace's\n * jobs and no other's: `runAiJobStep` asks the verdict with the job's org\n * before it claims a step, and leaves a paused workspace's job queued.\n */\n\n/** The beat's row in `SCHEDULED_JOBS`, and the mark it leaves for `/api/health/crons`. */\nexport const AI_JOBS_BEAT_CRON_ID = 'ai-jobs-beat'\n\n/**\n * The console path the beat is registered at: the one path this plugin\n * registers outside its own prefixes. `/api/admin/` is where the console's\n * scheduled sweeps live, and the console's edge lets a request past its bot\n * challenge there when it carries the cron secret's header — a route\n * anywhere else would need a firewall rule of its own before a scheduler\n * could reach it. The console app serves this exact path from a named route\n * with the sweep's function time, so the plugin dispatcher never serves it.\n */\nexport const AI_JOBS_BEAT_PATH = 'admin/ai-jobs-beat'\n\n/** What one beat did: nothing while `ai-generate` is locked, else the sweep's account. */\nexport type AiJobsBeatResult =\n  | { held: true }\n  | ({ held: false; emptySites: AiEmptySiteSweepResult | null } & SweepAiJobsResult)\n\n/**\n * One beat: the switch, then the empty sites a guided start left that are\n * due for removal (AGL-3936), then one sweep under its own lease owner. The\n * owner is fresh per beat and fixed for the whole sweep, so two beats\n * overlapping inside a lease never read each other's lease as their own.\n *\n * The removals come first, a few a beat inside\n * `AI_EMPTY_SITE_SWEEP_BUDGET_MS`, and whatever they took comes off the\n * sweep's budget, so the route's arithmetic inside `maxDuration` holds. A\n * removal that fails never holds up a job's step.\n */\nexport async function runAiJobsBeat(): Promise<AiJobsBeatResult> {\n  const locked = await featureLockdownRefusal({ feature: 'ai-generate' })\n  if (locked) {\n    console.warn('ai jobs beat held: ai-generate is locked')\n    return { held: true }\n  }\n  const firestore = firebaseAdmin.app().firestore()\n  const startedAt = Date.now()\n  const emptySites = await sweepAiEmptySites({ firestore }).catch((error: unknown) => {\n    console.error('ai jobs beat: the empty site sweep failed', error)\n    return null\n  })\n  if (emptySites?.removed) console.info(`ai jobs: ${emptySites.removed} empty site(s) removed`)\n  const result = await sweepAiJobs({\n    firestore,\n    owner: `beat:${randomUUID()}`,\n    budgetMs: Math.max(0, AI_JOB_SWEEP_BUDGET_MS - (Date.now() - startedAt)),\n  })\n  if (result.due) {\n    console.info(\n      `ai jobs: ${result.ran} step(s) run, ${result.skipped} skipped, ` +\n        `${result.paused} held by a workspace's AI pause, ` +\n        `${result.remaining} left for the next beat` +\n        (result.budgetExhausted ? ' (budget exhausted)' : ''),\n    )\n  }\n  return { held: false, emptySites, ...result }\n}\n"],"names":["randomUUID","featureLockdownRefusal","firebaseAdmin","AI_JOB_SWEEP_BUDGET_MS","sweepAiJobs","sweepAiEmptySites","AI_JOBS_BEAT_CRON_ID","AI_JOBS_BEAT_PATH","runAiJobsBeat","locked","feature","console","warn","held","firestore","app","startedAt","Date","now","emptySites","catch","error","removed","info","result","owner","budgetMs","Math","max","due","ran","skipped","paused","remaining","budgetExhausted"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,QAAQ,SAAQ;AACnC,SAASC,sBAAsB,EAAEC,aAAa,QAAQ,2BAA0B;AAChF,SAASC,sBAAsB,EAAEC,WAAW,QAAgC,eAAW;AACvF,SAASC,iBAAiB,QAAqC,2BAAuB;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCC,GAED,wFAAwF,GACxF,OAAO,MAAMC,uBAAuB,eAAc;AAElD;;;;;;;;CAQC,GACD,OAAO,MAAMC,oBAAoB,qBAAoB;AAOrD;;;;;;;;;;CAUC,GACD,OAAO,eAAeC;IACpB,MAAMC,SAAS,MAAMR,uBAAuB;QAAES,SAAS;IAAc;IACrE,IAAID,QAAQ;QACVE,QAAQC,IAAI,CAAC;QACb,OAAO;YAAEC,MAAM;QAAK;IACtB;IACA,MAAMC,YAAYZ,cAAca,GAAG,GAAGD,SAAS;IAC/C,MAAME,YAAYC,KAAKC,GAAG;IAC1B,MAAMC,aAAa,MAAMd,kBAAkB;QAAES;IAAU,GAAGM,KAAK,CAAC,CAACC;QAC/DV,QAAQU,KAAK,CAAC,6CAA6CA;QAC3D,OAAO;IACT;IACA,IAAIF,8BAAAA,WAAYG,OAAO,EAAEX,QAAQY,IAAI,CAAC,CAAC,SAAS,EAAEJ,WAAWG,OAAO,CAAC,sBAAsB,CAAC;IAC5F,MAAME,SAAS,MAAMpB,YAAY;QAC/BU;QACAW,OAAO,CAAC,KAAK,EAAEzB,cAAc;QAC7B0B,UAAUC,KAAKC,GAAG,CAAC,GAAGzB,yBAA0Bc,CAAAA,KAAKC,GAAG,KAAKF,SAAQ;IACvE;IACA,IAAIQ,OAAOK,GAAG,EAAE;QACdlB,QAAQY,IAAI,CACV,CAAC,SAAS,EAAEC,OAAOM,GAAG,CAAC,cAAc,EAAEN,OAAOO,OAAO,CAAC,UAAU,CAAC,GAC/D,GAAGP,OAAOQ,MAAM,CAAC,iCAAiC,CAAC,GACnD,GAAGR,OAAOS,SAAS,CAAC,uBAAuB,CAAC,GAC3CT,CAAAA,OAAOU,eAAe,GAAG,wBAAwB,EAAC;IAEzD;IACA,OAAO;QAAErB,MAAM;QAAOM;OAAeK;AACvC"}

package/src/lib/jobs/ai-jobs.js

@@ -47,6 +47,7 @@ import { AI_SITE_GUIDED_BUILD_FAILED_COPY, aiCustomerSafeCopy, aiCustomerSafeIte
 import { aiSiteStartInputsOf } from "../model/ai-site-start.js";
 import { addAdminAudit } from "@aglyn/tenant-data-admin/server/admin-audit-write";
 import { AI_JOB_CANCELED_ITEM_NOTE, aiJobCancelPending, isAiJobCanceledError, watchAiJobCancel } from "./ai-job-cancel.js";
+import { clearAiEmptySiteSweep, scheduleAiEmptySiteSweep } from "./ai-empty-site-sweep.js";
 /**
  * AI generation jobs — the Firestore state machine (AGL-2904).
  *
@@ -256,6 +257,16 @@ let transitionListener = null;
 /** Whether a transition listener is registered: what a surface that runs jobs must have. */ export function aiJobTransitionListenerRegistered() {
     return transitionListener !== null;
 }
+/**
+ * A job just ENDED `canceled` or `failed`, in the write the caller made
+ * (AGL-3936): a site start that built nothing schedules the removal of the
+ * empty site it was for, an hour out (`ai-empty-site-sweep.ts`). Every write
+ * that ends a job calls this once, after its transaction commits. Never
+ * throws.
+ */ async function noteAiJobEnded(firestore, job, now) {
+    if (!job || job.status !== 'canceled' && job.status !== 'failed') return;
+    await scheduleAiEmptySiteSweep(firestore, job, now);
+}
 /** Tells the listener; a listener that throws never fails the write it follows. */ async function announceAiJobTransition(job, to, failure) {
     if (!transitionListener) return;
     try {
@@ -408,6 +419,8 @@ function jobFrom(snapshot) {
         creditsConfirmed: input.creditsConfirmed
     } : {});
     await ref.set(data);
+    // A new job on the site — a guided start begun again — keeps it (AGL-3936).
+    await clearAiEmptySiteSweep(firestore, input.hostId);
     await logAiJobCreated(input.orgId, {
         uid: input.createdBy,
         email: (_input_createdByEmail = input.createdByEmail) != null ? _input_createdByEmail : null
@@ -527,6 +540,8 @@ export async function getAiJob(firestore, orgId, jobId) {
         publishAsked: true
     } : {}, aiJobCancelPending(job) ? {
         cancelRequested: true
+    } : {}, job.siteRemoved ? {
+        siteRemoved: true
     } : {});
 }
 function leaseIsLive(job, owner, nowMs) {
@@ -607,16 +622,20 @@ function nextStepIndex(job) {
  * stale lease is released by being taken, not by a sweep of its own.
  */ export async function claimNextStep(firestore, orgId, jobId, owner, now = new Date()) {
     const ref = jobsCollection(firestore, orgId).doc(jobId);
-    return firestore.runTransaction(async (tx)=>{
+    let ended = null;
+    const claimed = await firestore.runTransaction(async (tx)=>{
+        ended = null;
         const job = jobFrom(await tx.get(ref));
         if (!job) return null;
         // A cancel asked while a step ran, whose runner never came back to end
         // it (AGL-3616): the lease ran out, so the job ends here, unclaimed.
         if (aiJobCancelPending(job)) {
             if (!leaseIsLive(job, owner, now.getTime())) {
-                tx.set(ref, aiJobCanceledPatch(job, now, cancelRequestOf(job, now)), {
+                const patch = aiJobCanceledPatch(job, now, cancelRequestOf(job, now));
+                tx.set(ref, patch, {
                     merge: true
                 });
+                ended = _extends({}, job, patch);
             }
             return null;
         }
@@ -652,6 +671,8 @@ function nextStepIndex(job) {
             stepIndex
         };
     });
+    await noteAiJobEnded(firestore, ended, now);
+    return claimed;
 }
 /**
  * Extend the lease while a long step is still running. `false` when the
@@ -689,15 +710,19 @@ function nextStepIndex(job) {
  * parked, no step left, or another owner's live lease.
  */ export async function holdPausedAiJob(firestore, orgId, jobId, owner, now = new Date()) {
     const ref = jobsCollection(firestore, orgId).doc(jobId);
-    return firestore.runTransaction(async (tx)=>{
+    let ended = null;
+    const held = await firestore.runTransaction(async (tx)=>{
+        ended = null;
         const job = jobFrom(await tx.get(ref));
         if (!job) return null;
         // A paused workspace's job a person canceled ends canceled (AGL-3616).
         if (aiJobCancelPending(job)) {
             if (!leaseIsLive(job, owner, now.getTime())) {
-                tx.set(ref, aiJobCanceledPatch(job, now, cancelRequestOf(job, now)), {
+                const patch = aiJobCanceledPatch(job, now, cancelRequestOf(job, now));
+                tx.set(ref, patch, {
                     merge: true
                 });
+                ended = _extends({}, job, patch);
             }
             return null;
         }
@@ -711,6 +736,8 @@ function nextStepIndex(job) {
             updatedAt: now
         });
     });
+    await noteAiJobEnded(firestore, ended, now);
+    return held;
 }
 /**
  * A build's ledger with one pass applied (AGL-3616): the pass's credits on
@@ -874,9 +901,12 @@ function nextStepIndex(job) {
             job: _extends({}, job, patch),
             remaining,
             // Entered `needs_review` in this write, rather than parked again.
-            parked: parksForReview && job.status !== 'needs_review'
+            parked: parksForReview && job.status !== 'needs_review',
+            // Ended `canceled` in this write (AGL-3936).
+            ended: canceling && !isAiJobTerminal(job.status)
         };
     });
+    if (recorded.ended) await noteAiJobEnded(firestore, recorded.job, now);
     if (recorded.parked && !input.quiet) await announceAiJobTransition(recorded.job, 'needs-review');
     return {
         job: recorded.job,
@@ -912,6 +942,7 @@ async function transition(firestore, orgId, jobId, apply) {
             updatedAt: now
         });
     if (changed && job.status === 'done') await announceAiJobTransition(job, 'done');
+    if (changed) await noteAiJobEnded(firestore, job, now);
     return job;
 }
 /**
@@ -946,6 +977,7 @@ async function transition(firestore, orgId, jobId, apply) {
             error: (detail == null ? void 0 : detail.error) instanceof Error ? detail.error.message : (detail == null ? void 0 : detail.error) == null ? null : String(detail.error)
         });
     }
+    if (changed) await noteAiJobEnded(firestore, job, now);
     return job;
 }
 /**
@@ -953,7 +985,7 @@ async function transition(firestore, orgId, jobId, apply) {
  * step goes back to `pending` so the same step is what runs when the beat
  * tries again; its attempt is not counted, because nothing was attempted.
  */ export async function markAiJobNeedsInput(firestore, orgId, jobId, reason, now = new Date()) {
-    const { job } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : aiJobCancelPending(current) ? aiJobCanceledPatch(current, now, cancelRequestOf(current, now)) : {
+    const { job, changed } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : aiJobCancelPending(current) ? aiJobCanceledPatch(current, now, cancelRequestOf(current, now)) : {
             status: 'needs_input',
             error: reason,
             lease: null,
@@ -966,6 +998,7 @@ async function transition(firestore, orgId, jobId, apply) {
             }),
             updatedAt: now
         });
+    if (changed) await noteAiJobEnded(firestore, job, now);
     return job;
 }
 /**
@@ -1016,6 +1049,7 @@ async function transition(firestore, orgId, jobId, apply) {
             kind: result.job.kind
         });
     }
+    if (result.changed) await noteAiJobEnded(firestore, result.job, now);
     return result;
 }
 /**
@@ -1372,6 +1406,8 @@ async function transition(firestore, orgId, jobId, apply) {
             updatedAt: now
         });
     });
+    // A site start tried again keeps its site (AGL-3936).
+    if (result.changed) await clearAiEmptySiteSweep(firestore, result.job.hostId);
     return _extends({}, result, {
         retried: result.changed ? retried : []
     });
@@ -1388,7 +1424,7 @@ async function transition(firestore, orgId, jobId, apply) {
  * and a confirmed plan is held at what the whole job is estimated to cost
  * (AGL-3031), creations included, where that is more.
  */ export async function resumeAiJob(firestore, orgId, jobId, actor, now = new Date(), options = {}) {
-    return transition(firestore, orgId, jobId, (current)=>{
+    const resumed = await transition(firestore, orgId, jobId, (current)=>{
         var _options_reducePlan;
         var _current_review, _current_inputs;
         // A job the meter paused (AGL-3660) carries on from the step it paused
@@ -1435,6 +1471,9 @@ async function transition(firestore, orgId, jobId, apply) {
             updatedAt: now
         });
     });
+    // A site start resumed keeps its site (AGL-3936).
+    if (resumed.changed) await clearAiEmptySiteSweep(firestore, resumed.job.hostId);
+    return resumed;
 }
 /**
  * Record what a person applied from a finished job's outputs (AGL-2910): the