@aglyn/plugins-ai 1.0.0-beta.226 → 1.0.0-beta.228

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

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { notifyUsers } from "@aglyn/tenant-data-admin/server/notifications";
+import { aiJobNotice } from "../model/ai-job-notice.js";
+import { aiJobAutoConfirms } from "./ai-job-auto-confirm.js";
+import { registerAiJobTransitionListener } from "./ai-jobs.js";
+/**
+ * The person who started an AI job is told when it needs them, when it
+ * finishes and when it stops (AGL-3593), through the console's notifications
+ * — the bell, and the generic notification email for a person who switched
+ * that channel on for the category. No other channel: there is no push.
+ *
+ * The machine calls this where the job's state changes, once per change
+ * (`registerAiJobTransitionListener`): the request that ran a step inline,
+ * or the beat that ran it with nobody watching — which is exactly when a
+ * person needs telling. The recipient is the job's creator, whose job it is
+ * and who alone confirms its plan; a teammate is not told about someone
+ * else's draft.
+ *
+ * `notifyUsers` never throws, and honors the person's per-category,
+ * per-workspace and per-site preferences.
+ */ export function aiJobTransitionNotifier(notify = notifyUsers) {
+    return async ({ job, to })=>{
+        var _job_review;
+        if (!job.createdBy) return;
+        // A guided site start's plan is confirmed for it the moment it is kept
+        // (AGL-3594): there is nothing for the person to confirm.
+        if (to === 'needs-review' && ((_job_review = job.review) == null ? void 0 : _job_review.reason) === 'plan' && aiJobAutoConfirms(job)) return;
+        await notify([
+            job.createdBy
+        ], aiJobNotice(job, to));
+    };
+}
+/** Registers the notifier the jobs machine tells about each change. */ export function registerAiJobsNotify() {
+    registerAiJobTransitionListener(aiJobTransitionNotifier());
+}
+
+//# sourceMappingURL=ai-jobs-notify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-jobs-notify.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 { notifyUsers } from '@aglyn/tenant-data-admin/server/notifications'\nimport { aiJobNotice } from '../model/ai-job-notice'\nimport { aiJobAutoConfirms } from './ai-job-auto-confirm'\nimport { registerAiJobTransitionListener, type AiJobTransitionListener } from './ai-jobs'\n\n/**\n * The person who started an AI job is told when it needs them, when it\n * finishes and when it stops (AGL-3593), through the console's notifications\n * — the bell, and the generic notification email for a person who switched\n * that channel on for the category. No other channel: there is no push.\n *\n * The machine calls this where the job's state changes, once per change\n * (`registerAiJobTransitionListener`): the request that ran a step inline,\n * or the beat that ran it with nobody watching — which is exactly when a\n * person needs telling. The recipient is the job's creator, whose job it is\n * and who alone confirms its plan; a teammate is not told about someone\n * else's draft.\n *\n * `notifyUsers` never throws, and honors the person's per-category,\n * per-workspace and per-site preferences.\n */\nexport function aiJobTransitionNotifier(\n  notify: typeof notifyUsers = notifyUsers,\n): AiJobTransitionListener {\n  return async ({ job, to }) => {\n    if (!job.createdBy) return\n    // A guided site start's plan is confirmed for it the moment it is kept\n    // (AGL-3594): there is nothing for the person to confirm.\n    if (to === 'needs-review' && job.review?.reason === 'plan' && aiJobAutoConfirms(job)) return\n    await notify([job.createdBy], aiJobNotice(job, to))\n  }\n}\n\n/** Registers the notifier the jobs machine tells about each change. */\nexport function registerAiJobsNotify(): void {\n  registerAiJobTransitionListener(aiJobTransitionNotifier())\n}\n"],"names":["notifyUsers","aiJobNotice","aiJobAutoConfirms","registerAiJobTransitionListener","aiJobTransitionNotifier","notify","job","to","createdBy","review","reason","registerAiJobsNotify"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,WAAW,QAAQ,gDAA+C;AAC3E,SAASC,WAAW,QAAQ,4BAAwB;AACpD,SAASC,iBAAiB,QAAQ,2BAAuB;AACzD,SAASC,+BAA+B,QAAsC,eAAW;AAEzF;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,wBACdC,SAA6BL,WAAW;IAExC,OAAO,OAAO,EAAEM,GAAG,EAAEC,EAAE,EAAE;YAIMD;QAH7B,IAAI,CAACA,IAAIE,SAAS,EAAE;QACpB,uEAAuE;QACvE,0DAA0D;QAC1D,IAAID,OAAO,kBAAkBD,EAAAA,cAAAA,IAAIG,MAAM,qBAAVH,YAAYI,MAAM,MAAK,UAAUR,kBAAkBI,MAAM;QACtF,MAAMD,OAAO;YAACC,IAAIE,SAAS;SAAC,EAAEP,YAAYK,KAAKC;IACjD;AACF;AAEA,qEAAqE,GACrE,OAAO,SAASI;IACdR,gCAAgCC;AAClC"}

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

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type AiJob, type AiJobApplied, type AiJobKind, type AiJobOutput, type AiJobPlan, type AiJobReview, type AiJobStatus, type AiJobStepTokens, type AiJobSummary } from '../model/ai-jobs.types';
+import { AI_JOB_PLAN_STEP, type AiJob, type AiJobApplied, type AiJobKind, type AiJobOutput, type AiJobPlan, type AiJobReview, type AiJobSitePublish, type AiJobStatus, type AiJobStepTokens, type AiJobSummary } from '../model/ai-jobs.types';
 import type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types';
 import { type AiActivityActor } from '../activity/ai-activity';
 import { type AiEffort, type AiUsage } from '../runtime/ai-runtime';
@@ -107,8 +107,7 @@ export declare const AI_JOB_NOT_AVAILABLE_COPY = "This kind of AI job is not ava
 export declare const AI_JOB_REFUSED_COPY = "The model declined this brief. Try rephrasing it.";
 type Firestore = FirebaseFirestore.Firestore;
 export declare function isAiJobTerminal(status: AiJobStatus): boolean;
-/** The step a planned kind runs first (AGL-2935). */
-export declare const AI_JOB_PLAN_STEP = "plan";
+export { AI_JOB_PLAN_STEP };
 /**
  * The kinds that build site structure, and so plan before they generate
  * (AGL-2935): the plan their first step proposes is what their generation
@@ -196,6 +195,26 @@ export type AiJobPauseReader = (input: {
  * runs every job, as a process with no lockdown carrier would.
  */
 export declare function registerAiJobPauseReader(reader: AiJobPauseReader | null): void;
+/**
+ * A change a person is told about: the job's plan waits for them (or a step
+ * stopped for their decision), the job finished, or it stopped.
+ */
+export type AiJobTransition = 'needs-review' | 'done' | 'failed';
+export type AiJobTransitionListener = (input: {
+    job: AiJob;
+    to: AiJobTransition;
+}) => Promise<void> | void;
+/**
+ * The listener told each time a job ENTERS `needs_review`, `done` or `failed`
+ * — once per entry, from the write that made it, so a stream that re-reads
+ * the job or a beat that sees it again tells nobody twice. Registered by its
+ * own module (`ai-jobs-notify.ts`) from the console's server surface, as the
+ * pause reader is, so this machine never loads the notification fan-out.
+ * `null` unregisters it.
+ */
+export declare function registerAiJobTransitionListener(listener: AiJobTransitionListener | null): void;
+/** Whether a transition listener is registered: what a surface that runs jobs must have. */
+export declare function aiJobTransitionListenerRegistered(): boolean;
 /** Whether a pause reader is registered: what a surface that runs jobs must have. */
 export declare function aiJobPauseReaderRegistered(): boolean;
 /** The runner for one step of one job: the plan step by its name, else the kind's own. */
@@ -230,9 +249,23 @@ export declare function createAiJob(firestore: Firestore, input: CreateAiJobInpu
 export declare function getAiJob(firestore: Firestore, orgId: string, jobId: string): Promise<AiJob | null>;
 export interface ListAiJobsOptions {
     status?: AiJobStatus;
+    /**
+     * Any of these statuses (AGL-3593): the console's indicator asks for every
+     * job not yet settled in one read. Ignored when `status` is given.
+     */
+    statuses?: readonly AiJobStatus[];
+    /**
+     * One site's jobs (AGL-3596), for the site's AI jobs page; on the
+     * (hostId, createdAt) index. Not combined with a status filter, which no
+     * reader asks for and no index answers.
+     */
+    hostId?: string;
     limit?: number;
 }
-/** Newest first. Needs the (status, createdAt) index when filtered. */
+/**
+ * Newest first. Needs the (status, createdAt) index when filtered, which
+ * answers an `in` over statuses as it answers one status.
+ */
 export declare function listAiJobs(firestore: Firestore, orgId: string, options?: ListAiJobsOptions): Promise<AiJob[]>;
 /** The wire form. `running` is the lease, read against `now`. */
 export declare function aiJobSummary(job: AiJob, now?: Date): AiJobSummary;
@@ -288,6 +321,8 @@ export interface RecordStepInput {
     continued?: boolean;
     /** What the run cost in tokens and time (AGL-2937), added to the step's totals. */
     tokens?: AiJobStepTokenRun;
+    /** What a guided site start put live (AGL-3596), kept on the job. */
+    sitePublish?: AiJobSitePublish;
 }
 /** One run of a step's runner, as the machine measured it (AGL-2937). */
 export interface AiJobStepTokenRun {

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

@@ -23,7 +23,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
 import { createResourceUid } from "@aglyn/aglyn/app-utils/create-resource-uid";
 import { checkEntitlement } from "@aglyn/aglyn/server";
 import { assistCreditsFromUsd, assistFreeTasteRefusalText, assistHardCapRefusalText, assistRefusedByHardCap } from "../usage/assist-credits.js";
-import { AI_JOB_TERMINAL_STATUSES } from "../model/ai-jobs.types.js";
+import { AI_JOB_PLAN_STEP, AI_JOB_TERMINAL_STATUSES } from "../model/ai-jobs.types.js";
 import { resolveEffectivePlan } from "@aglyn/aglyn/app-utils/plan-entitlements";
 import { aiOverageReservationRefusal } from "../billing/ai-overage-gate.js";
 import { aiAllotmentRefusalText } from "../model/ai-allotments.js";
@@ -39,7 +39,10 @@ import { aiMintJobDraftIds } from "./ai-job-draft-ids.js";
 import { AI_JOB_TEXT_STEP_MINIMUM_MS, runAiJobTextStep } from "./ai-job-text-step.js";
 import { AI_JOB_SEO_STEP_MINIMUM_MS } from "./ai-job-seo-budget.js";
 import { AI_JOB_THEME_STEP_MINIMUM_MS } from "./ai-job-theme-budget.js";
-import { assistExchangeExpiry, recordAssistCost, releaseAssistMessage, reserveAssistMessage } from "../usage/assist-usage.js";
+import { assistExchangeExpiry, assistUsageDay, assistUsageMonth, recordAssistCost, releaseAssistMessage, reserveAssistMessage } from "../usage/assist-usage.js";
+import { aiJobRefundCredits, refundJobCredits } from "../usage/assist-job-refund.js";
+import { freeAssistAccount } from "../usage/assist-free-taste.js";
+import { aiJobAutoConfirms } from "./ai-job-auto-confirm.js";
 import { addAdminAudit } from "@aglyn/tenant-data-admin/server/admin-audit-write";
 /**
  * AI generation jobs — the Firestore state machine (AGL-2904).
@@ -134,7 +137,9 @@ export function isAiJobTerminal(status) {
     return AI_JOB_TERMINAL_STATUSES.includes(status);
 }
 // ── The step runner registry ──────────────────────────────────────────────
-/** The step a planned kind runs first (AGL-2935). */ export const AI_JOB_PLAN_STEP = 'plan';
+// The step a planned kind runs first (AGL-2935), named in the model so the
+// console reads a job's phase off its steps without loading this machine.
+export { AI_JOB_PLAN_STEP };
 /**
  * The kinds that build site structure, and so plan before they generate
  * (AGL-2935): the plan their first step proposes is what their generation
@@ -232,6 +237,36 @@ let pauseReader = null;
  */ export function registerAiJobPauseReader(reader) {
     pauseReader = reader;
 }
+let transitionListener = null;
+/**
+ * The listener told each time a job ENTERS `needs_review`, `done` or `failed`
+ * — once per entry, from the write that made it, so a stream that re-reads
+ * the job or a beat that sees it again tells nobody twice. Registered by its
+ * own module (`ai-jobs-notify.ts`) from the console's server surface, as the
+ * pause reader is, so this machine never loads the notification fan-out.
+ * `null` unregisters it.
+ */ export function registerAiJobTransitionListener(listener) {
+    transitionListener = listener;
+}
+/** Whether a transition listener is registered: what a surface that runs jobs must have. */ export function aiJobTransitionListenerRegistered() {
+    return transitionListener !== null;
+}
+/** Tells the listener; a listener that throws never fails the write it follows. */ async function announceAiJobTransition(job, to) {
+    if (!transitionListener) return;
+    try {
+        await transitionListener({
+            job,
+            to
+        });
+    } catch (error) {
+        console.error('ai job transition listener failed', {
+            orgId: job.orgId,
+            jobId: job.$id,
+            to,
+            error
+        });
+    }
+}
 /** Whether a pause reader is registered: what a surface that runs jobs must have. */ export function aiJobPauseReaderRegistered() {
     return pauseReader !== null;
 }
@@ -378,19 +413,27 @@ function jobFrom(snapshot) {
 export async function getAiJob(firestore, orgId, jobId) {
     return jobFrom(await jobsCollection(firestore, orgId).doc(jobId).get());
 }
-/** Newest first. Needs the (status, createdAt) index when filtered. */ export async function listAiJobs(firestore, orgId, options = {}) {
+/**
+ * Newest first. Needs the (status, createdAt) index when filtered, which
+ * answers an `in` over statuses as it answers one status.
+ */ export async function listAiJobs(firestore, orgId, options = {}) {
     var _options_limit;
+    var _options_statuses;
     const limit = Math.min(Math.max(1, Math.floor((_options_limit = options.limit) != null ? _options_limit : 20)), 100);
     let query = jobsCollection(firestore, orgId);
     if (options.status) query = query.where('status', '==', options.status);
+    else if ((_options_statuses = options.statuses) == null ? void 0 : _options_statuses.length) query = query.where('status', 'in', [
+        ...options.statuses
+    ]);
+    else if (options.hostId) query = query.where('hostId', '==', options.hostId);
     const snapshot = await query.orderBy('createdAt', 'desc').limit(limit).get();
     return snapshot.docs.map((doc)=>jobFrom(doc)).filter((job)=>job !== null);
 }
 /** The wire form. `running` is the lease, read against `now`. */ export function aiJobSummary(job, now = new Date()) {
-    var _job_hostId, _job_steps, _job_outputs, _job_creditsReserved, _job_creditsSpent, _toIso, _toIso1, _job_error, _job_plan_labels, _job_plan_confirmedBy, _job_review, _job_applied_versions, _job_applied_staged;
+    var _job_hostId, _job_steps, _job_outputs, _job_creditsReserved, _job_creditsSpent, _job_refundedCredits, _toIso, _toIso1, _job_error, _job_plan_labels, _job_plan_confirmedBy, _job_review, _job_applied_versions, _job_applied_staged;
     var _job_lease, _job_inputs;
     const leaseUntil = toMillis((_job_lease = job.lease) == null ? void 0 : _job_lease.until);
-    return {
+    return _extends({
         id: job.$id,
         orgId: job.orgId,
         hostId: (_job_hostId = job.hostId) != null ? _job_hostId : null,
@@ -412,6 +455,7 @@ export async function getAiJob(firestore, orgId, jobId) {
         outputs: (_job_outputs = job.outputs) != null ? _job_outputs : [],
         creditsReserved: (_job_creditsReserved = job.creditsReserved) != null ? _job_creditsReserved : 0,
         creditsSpent: (_job_creditsSpent = job.creditsSpent) != null ? _job_creditsSpent : 0,
+        refundedCredits: (_job_refundedCredits = job.refundedCredits) != null ? _job_refundedCredits : 0,
         createdBy: job.createdBy,
         createdAt: (_toIso = toIso(job.createdAt)) != null ? _toIso : new Date(0).toISOString(),
         updatedAt: (_toIso1 = toIso(job.updatedAt)) != null ? _toIso1 : new Date(0).toISOString(),
@@ -430,7 +474,9 @@ export async function getAiJob(firestore, orgId, jobId) {
             versions: (_job_applied_versions = job.applied.versions) != null ? _job_applied_versions : {},
             staged: (_job_applied_staged = job.applied.staged) != null ? _job_applied_staged : []
         } : null
-    };
+    }, job.sitePublish ? {
+        sitePublish: job.sitePublish
+    } : {});
 }
 function leaseIsLive(job, owner, nowMs) {
     const lease = job.lease;
@@ -605,7 +651,7 @@ function nextStepIndex(job) {
  * in the same transaction, so no beat can claim the next step in between.
  */ export async function recordStep(firestore, orgId, jobId, owner, stepIndex, input, now = new Date()) {
     const ref = jobsCollection(firestore, orgId).doc(jobId);
-    return firestore.runTransaction(async (tx)=>{
+    const recorded = await firestore.runTransaction(async (tx)=>{
         var _job_outputs, _input_outputs, _job_creditsSpent, _job_creditsReserved, _job_creditsReserved1;
         var _job_lease;
         const job = jobFrom(await tx.get(ref));
@@ -645,6 +691,8 @@ function nextStepIndex(job) {
             lease: null
         } : {}, input.plan ? {
             plan: input.plan
+        } : {}, input.sitePublish ? {
+            sitePublish: input.sitePublish
         } : {}, parksForReview && input.review ? {
             review: input.review,
             error: input.review.reason === 'plan' ? null : input.review.message
@@ -654,9 +702,16 @@ function nextStepIndex(job) {
         });
         return {
             job: _extends({}, job, patch),
-            remaining
+            remaining,
+            // Entered `needs_review` in this write, rather than parked again.
+            parked: parksForReview && job.status !== 'needs_review'
         };
     });
+    if (recorded.parked) await announceAiJobTransition(recorded.job, 'needs-review');
+    return {
+        job: recorded.job,
+        remaining: recorded.remaining
+    };
 }
 async function transition(firestore, orgId, jobId, apply) {
     const ref = jobsCollection(firestore, orgId).doc(jobId);
@@ -678,13 +733,14 @@ async function transition(firestore, orgId, jobId, apply) {
     });
 }
 /** Every step done: the job is `done` and holds nothing. */ export async function completeAiJob(firestore, orgId, jobId, now = new Date()) {
-    const { job } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
+    const { job, changed } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
             status: 'done',
             creditsReserved: 0,
             lease: null,
             error: null,
             updatedAt: now
         });
+    if (changed) await announceAiJobTransition(job, 'done');
     return job;
 }
 /**
@@ -699,7 +755,7 @@ async function transition(firestore, orgId, jobId, apply) {
         stepIndex: (_ref = detail == null ? void 0 : detail.stepIndex) != null ? _ref : null,
         error: (detail == null ? void 0 : detail.error) instanceof Error ? detail.error.message : (_ref1 = detail == null ? void 0 : detail.error) != null ? _ref1 : null
     });
-    const { job } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
+    const { job, changed } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
             status: 'failed',
             error: message,
             creditsReserved: 0,
@@ -711,6 +767,7 @@ async function transition(firestore, orgId, jobId, apply) {
                 }) : step),
             updatedAt: now
         });
+    if (changed) await announceAiJobTransition(job, 'failed');
     return job;
 }
 /**
@@ -760,6 +817,57 @@ async function transition(firestore, orgId, jobId, apply) {
     }
     return result;
 }
+/**
+ * Gives back what a job spent when it failed on our side (AGL-3594), and
+ * records the give-back on the job — `refundedCredits`, `refundReason` and
+ * the count its next key is numbered by. Everything the job spent and has not
+ * given back where it delivered nothing; the failing step's own spend where
+ * it delivered drafts, which it keeps. `assist-job-refund.ts` has the rule
+ * and the bound. Never throws: a give-back that cannot be made leaves the job
+ * as the failure left it, metered as every other step.
+ */ async function refundOurFailure(firestore, orgId, job, input) {
+    try {
+        var _job_outputs, _job_creditsSpent, _job_refundedCredits, _data, _job_refunds;
+        const delivered = ((_job_outputs = job.outputs) != null ? _job_outputs : []).some((output)=>output.resource !== 'seo');
+        const credits = aiJobRefundCredits({
+            delivered,
+            jobCredits: (_job_creditsSpent = job.creditsSpent) != null ? _job_creditsSpent : 0,
+            stepCredits: input.stepCredits,
+            alreadyRefunded: (_job_refundedCredits = job.refundedCredits) != null ? _job_refundedCredits : 0
+        });
+        if (credits <= 0) return job;
+        const free = input.free !== undefined ? input.free : freeAssistAccount((_data = (await firestore.collection('orgs').doc(orgId).get()).data()) != null ? _data : {});
+        const ordinal = (_job_refunds = job.refunds) != null ? _job_refunds : 0;
+        const refund = await refundJobCredits(firestore, {
+            orgId,
+            free,
+            jobId: job.$id,
+            ordinal,
+            credits,
+            month: assistUsageMonth(input.now),
+            day: assistUsageDay(input.now),
+            reason: input.reason
+        });
+        if (refund.status !== 'returned') return job;
+        const { job: refunded } = await transition(firestore, orgId, job.$id, (current)=>{
+            var _current_refundedCredits, _current_refunds;
+            return {
+                refundedCredits: ((_current_refundedCredits = current.refundedCredits) != null ? _current_refundedCredits : 0) + credits,
+                refundReason: input.reason,
+                refunds: ((_current_refunds = current.refunds) != null ? _current_refunds : 0) + 1,
+                updatedAt: input.now
+            };
+        });
+        return refunded;
+    } catch (error) {
+        console.error('ai job refund failed', {
+            orgId,
+            jobId: job.$id,
+            error
+        });
+        return job;
+    }
+}
 /**
  * Resume a job that stopped for a person (AGL-2935): confirm its plan, or
  * try again the step whose answer broke a building rule. One transaction,
@@ -938,22 +1046,32 @@ async function transition(firestore, orgId, jobId, apply) {
     const runner = aiJobRunnerForStep(job.kind, step.name);
     if (!runner) {
         await releaseHeld();
+        const failed = await failAiJob(firestore, orgId, jobId, AI_JOB_NOT_AVAILABLE_COPY, {
+            stepIndex,
+            error: `no runner registered for kind ${job.kind}`
+        }, now);
         return {
             outcome: 'failed',
-            job: await failAiJob(firestore, orgId, jobId, AI_JOB_NOT_AVAILABLE_COPY, {
-                stepIndex,
-                error: `no runner registered for kind ${job.kind}`
-            }, now)
+            job: await refundOurFailure(firestore, orgId, failed, {
+                reason: 'unavailable',
+                stepCredits: 0,
+                now
+            })
         };
     }
     if (((_step_attempts = step.attempts) != null ? _step_attempts : 0) > AI_JOB_STEP_MAX_ATTEMPTS) {
         await releaseHeld();
+        const failed = await failAiJob(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
+            stepIndex,
+            error: `step ${step.name} exhausted ${AI_JOB_STEP_MAX_ATTEMPTS} attempts`
+        }, now);
         return {
             outcome: 'failed',
-            job: await failAiJob(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
-                stepIndex,
-                error: `step ${step.name} exhausted ${AI_JOB_STEP_MAX_ATTEMPTS} attempts`
-            }, now)
+            job: await refundOurFailure(firestore, orgId, failed, {
+                reason: 'timeout',
+                stepCredits: 0,
+                now
+            })
         };
     }
     const org = (_options_org = options.org) != null ? _options_org : (_data = (await firestore.collection('orgs').doc(orgId).get()).data()) != null ? _data : {};
@@ -1058,6 +1176,7 @@ async function transition(firestore, orgId, jobId, apply) {
             modelFor
         });
     } catch (error) {
+        var _reservation_free;
         // The provider refused the request or the budget ended before it
         // answered: no usage came back, so nothing is metered and the message
         // goes back to the org. The provider's own words are already in the
@@ -1078,12 +1197,18 @@ async function transition(firestore, orgId, jobId, apply) {
                 job: requeued
             };
         }
+        const failed = await failAiJob(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
+            stepIndex,
+            error
+        }, now);
         return {
             outcome: 'failed',
-            job: await failAiJob(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
-                stepIndex,
-                error
-            }, now)
+            job: await refundOurFailure(firestore, orgId, failed, {
+                reason: 'provider',
+                stepCredits: 0,
+                free: (_reservation_free = reservation.free) != null ? _reservation_free : null,
+                now
+            })
         };
     }
     const latencyMs = Math.max(0, Date.now() - runStarted);
@@ -1092,6 +1217,7 @@ async function transition(firestore, orgId, jobId, apply) {
     // back and nothing is metered, exactly as for a request the provider
     // refused.
     if (outcome.failure && aiJobStepSpentNothing(outcome)) {
+        var _reservation_free1;
         await releaseAssistMessage(firestore, orgId, reservation).catch((releaseError)=>console.error('ai job release failed', {
                 orgId,
                 jobId,
@@ -1102,12 +1228,18 @@ async function transition(firestore, orgId, jobId, apply) {
             creditsSpent: 0,
             error: outcome.failure
         }, now);
+        const failed = await failAiJob(firestore, orgId, jobId, outcome.failure, {
+            stepIndex,
+            error: `step failure before the provider: ${outcome.failure}`
+        }, now);
         return {
             outcome: 'failed',
-            job: await failAiJob(firestore, orgId, jobId, outcome.failure, {
-                stepIndex,
-                error: `step failure before the provider: ${outcome.failure}`
-            }, now)
+            job: await refundOurFailure(firestore, orgId, failed, {
+                reason: 'step-failure',
+                stepCredits: 0,
+                free: (_reservation_free1 = reservation.free) != null ? _reservation_free1 : null,
+                now
+            })
         };
     }
     const tokens = {
@@ -1132,7 +1264,7 @@ async function transition(firestore, orgId, jobId, apply) {
         // Tokens were spent, so the bill is written first and its failure is a
         // log line, never a failed job — the same rule the chat route keeps.
         try {
-            var _job_hostId1, _reservation_free;
+            var _job_hostId1, _reservation_free2;
             await recordAssistCost(firestore, orgId, {
                 route: 'ai/jobs',
                 hostId: (_job_hostId1 = job.hostId) != null ? _job_hostId1 : null,
@@ -1145,7 +1277,7 @@ async function transition(firestore, orgId, jobId, apply) {
                 // The account this job drew on, as the reservation decided it
                 // (AGL-2925): a Free job lands on the owner's allowance and the
                 // platform's day; a paid one on neither.
-                free: (_reservation_free = reservation.free) != null ? _reservation_free : null,
+                free: (_reservation_free2 = reservation.free) != null ? _reservation_free2 : null,
                 // The step is the creator's spend, under the job's kind (AGL-2928).
                 uid: job.createdBy,
                 kind: job.kind
@@ -1163,6 +1295,7 @@ async function transition(firestore, orgId, jobId, apply) {
     // model's answer (AGL-2938), fails the job with its own sentence. The
     // tokens are already on the bill above.
     if (outcome.refused || outcome.failure) {
+        var _reservation_free3;
         const message = outcome.refused ? AI_JOB_REFUSED_COPY : outcome.failure;
         await recordStep(firestore, orgId, jobId, options.owner, stepIndex, {
             status: 'failed',
@@ -1170,12 +1303,19 @@ async function transition(firestore, orgId, jobId, apply) {
             error: message,
             tokens
         }, now);
+        const failed = await failAiJob(firestore, orgId, jobId, message, {
+            stepIndex,
+            error: outcome.refused ? 'stop_reason refusal' : `step failure: ${message}`
+        }, now);
+        // A model declining the brief is not our failure; a step's own is (AGL-3594).
         return {
             outcome: 'failed',
-            job: await failAiJob(firestore, orgId, jobId, message, {
-                stepIndex,
-                error: outcome.refused ? 'stop_reason refusal' : `step failure: ${message}`
-            }, now)
+            job: outcome.refused ? failed : await refundOurFailure(firestore, orgId, failed, {
+                reason: 'step-failure',
+                stepCredits: credits,
+                free: (_reservation_free3 = reservation.free) != null ? _reservation_free3 : null,
+                now
+            })
         };
     }
     // A step that stopped for a person parks the job in the same write that
@@ -1212,6 +1352,8 @@ async function transition(firestore, orgId, jobId, apply) {
         plan: outcome.plan
     } : {}, review ? {
         review
+    } : {}, outcome.sitePublish ? {
+        sitePublish: outcome.sitePublish
     } : {}), now);
     const actor = (_options_actor = options.actor) != null ? _options_actor : {
         uid: job.createdBy
@@ -1245,7 +1387,30 @@ async function transition(firestore, orgId, jobId, apply) {
             }
         });
     }
+    if ((review == null ? void 0 : review.reason) === 'plan' && recorded.job.status === 'needs_review' && aiJobAutoConfirms(job)) {
+        // A guided site start confirms its own plan (AGL-3594): the resume
+        // door's confirmation, by the job's creator, and the build queued.
+        const resumed = await resumeAiJob(firestore, orgId, jobId, {
+            uid: job.createdBy
+        }, now);
+        await writeAiJobAudit(firestore, {
+            action: 'ai.job.resume',
+            actorUid: job.createdBy,
+            orgId,
+            jobId,
+            after: {
+                status: resumed.job.status,
+                confirmedPlan: true,
+                autoConfirm: true
+            }
+        });
+        return {
+            outcome: 'done',
+            job: resumed.job
+        };
+    }
     if (review && recorded.job.status === 'needs_review') {
+        var _reservation_free4;
         // Nobody parked the job but its own step, so the row names no actor, as
         // the meter's park does.
         await logAiJobNeedsInput(orgId, {
@@ -1255,9 +1420,15 @@ async function transition(firestore, orgId, jobId, apply) {
             kind: job.kind,
             reason: review.reason
         });
+        // A plan the plan rules still refused is our failure (AGL-3594).
         return {
             outcome: 'needs_review',
-            job: recorded.job
+            job: outcome.uncredited ? await refundOurFailure(firestore, orgId, recorded.job, {
+                reason: 'plan-refused',
+                stepCredits: credits,
+                free: (_reservation_free4 = reservation.free) != null ? _reservation_free4 : null,
+                now
+            }) : recorded.job
         };
     }
     if (recorded.remaining > 0 || isAiJobTerminal(recorded.job.status)) {