src/jobs-holder.ts

Functions

Imports

It imports src/agents.ts, src/complete-ci.ts, src/env.ts, src/fail-exemption.ts, src/github/client.ts, src/job-claims.ts, src/job-outcomes.ts, src/job-overlaps.ts, src/job-signing.ts, src/job-touches.ts, src/jobs-mirror.ts, src/jobs-schema.ts, src/jobs-transition.ts, src/outcome-prs.ts, src/provenance.ts, src/review.ts, src/store-guards.ts. Imported by src/jobs-seat.ts, src/jobs.ts, src/ops-feed.ts, src/whats-next.ts.

Source

1import type { Env } from "./env";
2import type { Agent } from "./agents";
3import {
4  swallowedParamTag,
5  swallowedTagRefusal,
6  type JobRow,
7  type JobStatus,
8  CORRECTION_CAP,
9  RETRY_CAP_REASON,
10  atCorrectionCap,
11  cappedSummary,
12} from "./jobs-schema";
13import { reviewGate, type GateOutcome, type Review } from "./review";
14import { outcomePrStatements } from "./outcome-prs";
15import { isMissingRowAbort, requireJobUnchanged } from "./store-guards";
16import {
17  outcomeFrom,
18  outcomeStatement,
19  readJobUsage,
20  namedPrUrls,
21  verifyEvidence,
22  type JobEvidence,
23  type JobOutcomeRow,
24} from "./job-outcomes";
25import {
26  claimRow,
27  claimStatement,
28  evaluationRows,
29  evaluationStatements,
30  parseClaim,
31  workerEvaluatorId,
32  type ClaimInput,
33  type ClaimRaw,
34  type JobClaim,
35} from "./job-claims";
36import { jobAudit, mirrorStatements } from "./jobs-mirror";
37import { signJobText } from "./job-signing";
38import { checkOverlaps, overlapLine, prUrlsIn, type OverlapReport } from "./job-overlaps";
39import { callerIsSeat, correctionsForWork, guardedTransition, readJob, refuse, type JobResult } from "./jobs-transition";
40import { actorKind, touchStatement } from "./job-touches";
41import { externalFence } from "./provenance";
42import { ciRefusal } from "./complete-ci";
43import { breakerExemption, type BreakerExemption } from "./fail-exemption";
44import { parsePrUrl } from "./github/client";
45
46// The transitions the driver holding a job makes: complete, fail and block, and the
47// review gate they consult.
48
49// The transitions a holder makes. complete, fail and block are the same shape: a keyed
50// UPDATE that only fires for the claimed job this caller holds, so a job the seat
51// released back to the queue cannot be completed out from under its new owner.
52function holderRefusal(action: string, id: string, actor: string, current: JobRow | null): JobResult | null {
53  if (!current) return refuse(action, `no job ${id}.`);
54  if (current.status !== "claimed") {
55    return refuse(
56      action,
57      `${id} is ${current.status}, not claimed. ${current.status === "queued" ? "It is back in the queue (the seat released it); claim it again." : "It has already been finished."}`
58    );
59  }
60  if (current.claimed_by !== actor) return refuse(action, `${id} is held by ${current.claimed_by}, not by ${actor}.`);
61  return null;
62}
63
64// The seat completing a blocked job it does not hold. Null when the job is blocked and
65// held by someone else; otherwise what the job is and what to do instead.
66function seatCloseRefusal(action: string, id: string, seat: string, current: JobRow | null): JobResult | null {
67  if (!current) return refuse(action, `no job ${id}.`);
68  if (current.status === "blocked") {
69    return current.claimed_by === seat
70      ? refuse(action, `${id} is blocked and held by ${seat} itself. A holder resumes its own gate before it completes; the seat's close is for a job another credential blocked.`)
71      : null;
72  }
73  if (current.status === "queued") {
74    return refuse(action, `${id} is queued: nobody has worked it, so there is nothing to complete. A driver claims it, or the seat supersedes it.`);
75  }
76  if (current.status === "claimed") {
77    return refuse(action, `${id} is claimed by ${current.claimed_by}. Its holder completes it, or the seat releases the claim first. The seat completes a job only once it is blocked.`);
78  }
79  return refuse(action, `${id} is already ${current.status}; there is nothing to complete.`);
80}
81
82// The seat recording a queued job's outcome. Null when the job is queued and unheld.
83function recordRefusal(action: string, id: string, current: JobRow | null): JobResult | null {
84  if (!current) return refuse(action, `no job ${id}.`);
85  if (current.status === "queued" && current.claimed_by === null) return null;
86  if (current.status === "claimed") return refuse(action, `${id} is claimed by ${current.claimed_by}: its holder completes it. record is for work done on a job nobody claimed.`);
87  if (current.status === "blocked") return refuse(action, `${id} is blocked: the seat completes a blocked job with action complete.`);
88  return refuse(action, `${id} is ${current.status}; record is for a queued job.`);
89}
90
91// What the agent said on one complete, fail or block call, for its job_claims row.
92// `as` and `evidence` are set when the review gate turned the call into another
93// transition: the claim is still the agent's, made on the action it called, and a
94// complete the reviewer stopped is exactly the claim the dataset exists to keep.
95type Said = { claim?: JobClaim; raw: ClaimRaw; as?: "complete" | "fail" | "block"; evidence?: JobEvidence };
96
97async function holderTransition(
98  env: Env,
99  agent: Agent,
100  now: Date,
101  action: "complete" | "fail" | "block",
102  id: string,
103  patch: {
104    status: JobStatus;
105    result_summary?: string | null;
106    result_ref?: string | null;
107    // Only block bumps the gate counter. Bound as a number, not interpolated as a SQL
108    // fragment: the statement stays one static string, so test/jobs.test.ts can read
109    // that it is keyed and test-integration/query-plans.test.ts can reconstruct it and
110    // EXPLAIN it. A statement assembled at runtime is invisible to both.
111    bumpBlocked?: boolean;
112    // A holder's fail the breaker does not count, and why (src/fail-exemption.ts).
113    breakerExempt?: BreakerExemption | null;
114    // What the driver says this job produced. Verified against GitHub and written into
115    // job_outcomes below, on the terminal transitions only.
116    evidence?: JobEvidence;
117    // Human-touch rows (src/job-touches.ts) for this transition, built from the row as
118    // the UPDATE leaves it, so they commit or abort with it. Only block writes any.
119    touches?: (job: JobRow) => D1PreparedStatement[];
120    // What the agent said on this complete, fail or block, as sent. Present, the
121    // transition writes one job_claims row. `as` is the action the agent called, when the review
122    // gate turned it into another transition.
123    said?: Said;
124    // The seat completing a BLOCKED job another credential holds (completeAsSeat). The
125    // row must be blocked and held by someone else, the UPDATE leaves claimed_by alone,
126    // and so the outcome row, which copies claimed_by, credits the driver that did the
127    // work. The caller is only the actor on the audit, mirror and claim rows.
128    seatCloses?: boolean;
129    // The seat recording the outcome of work done on a QUEUED job nobody claimed
130    // (recordAsSeat). The row must
131    // be queued and unheld; the UPDATE credits the recorder as claimed_by, so the outcome
132    // row names who said the work was done. recordVerb names the audit and mirror action:
133    // "record" for the seat's record, "complete-unclaimed" for a session completing its own
134    // work without a claim (src/jobs-seat.ts completeUnclaimed), so the two stay apart.
135    records?: boolean;
136    recordVerb?: "record" | "complete-unclaimed";
137    // The overlap report for the pull request this call named, recorded on the audit row
138    // and returned. Its line is already in result_summary.
139    overlaps?: OverlapReport | null;
140  }
141): Promise<JobResult> {
142  const actor = agent.actor;
143  const read = await readJob(env.DB, id);
144  const notHeld = patch.records
145    ? recordRefusal(action, id, read)
146    : patch.seatCloses
147      ? seatCloseRefusal(action, id, actor, read)
148      : holderRefusal(action, id, actor, read);
149  if (notHeld) return notHeld;
150  if (!read) return refuse(action, `no job ${id}.`);
151  // What the row must be for this transition to apply, and who holds it. For a holder's
152  // own transition that is the claimed row it holds, as it always was.
153  const fromStatus = patch.records ? "queued" : patch.seatCloses ? "blocked" : "claimed";
154  const verb = patch.records ? (patch.recordVerb ?? "record") : patch.seatCloses ? "admin-complete" : action;
155  // The row as the UPDATE below will leave it, computed from the read so the mirror
156  // and the outcome can be built before anything is written. The guard at the head of
157  // the batch is what keeps the read true when the batch commits.
158  const job: JobRow = {
159    ...read,
160    ...(patch.records ? { claimed_by: actor } : {}),
161    status: patch.status,
162    result_summary: patch.result_summary ?? read.result_summary,
163    result_ref: patch.result_ref ?? read.result_ref,
164    updated_at: now.toISOString(),
165    blocked_count: read.blocked_count + (patch.bumpBlocked ? 1 : 0),
166  };
167
168  // The transition and every record of it (mirror, audit, outcome, pull request and
169  // attribution rows) are one batch. The first statement aborts the whole batch unless
170  // the row is still claimed by this caller at the updated_at just read, so either all
171  // of it commits or none of it does, and a throw cannot leave a finished job with no
172  // record. id is the primary key, so the guard passing means the UPDATE moves exactly
173  // that one row.
174  //
175  // The outcome row is written on the terminal transitions only. A running job has no
176  // outcome, and one that reached `done` or `failed` will not transition again, so this
177  // runs once per job and the primary key enforces that rather than trusting it.
178  //
179  // A failed job gets a row too. A driver whose jobs mostly fail is what this table
180  // exists to show, and recording only successes would make every agent look equally
181  // good.
182  //
183  // Verification runs before the batch and cannot fail the transition. verifyEvidence
184  // reports its own errors as notes, so an unreachable GitHub costs the verified flags
185  // and not the driver's ability to close a finished job.
186  let outcome: { row: JobOutcomeRow; notes: string[] } | undefined;
187  // The summary is signed as it is written, so the command a blocked job shows a person
188  // can be told apart from one changed afterwards (src/job-signing.ts).
189  const summarySig = patch.result_summary ? await signJobText(env.IMPROVE_SCORE_SECRET, "summary", id, { summary: patch.result_summary }) : null;
190  const statements = [
191    requireJobUnchanged(env.DB, id, fromStatus, read.claimed_by, read.updated_at),
192    env.DB.prepare(
193      `UPDATE jobs SET status = ?2, result_summary = COALESCE(?3, result_summary), result_ref = COALESCE(?4, result_ref),
194         summary_sig = CASE WHEN ?3 IS NULL THEN summary_sig ELSE ?8 END,
195         updated_at = ?5, blocked_count = blocked_count + ?7, claimed_by = COALESCE(?10, claimed_by)
196       WHERE id = ?1 AND status = ?9 AND claimed_by IS ?6 RETURNING id`
197    ).bind(
198      id,
199      patch.status,
200      patch.result_summary ?? null,
201      patch.result_ref ?? null,
202      now.toISOString(),
203      read.claimed_by,
204      patch.bumpBlocked ? 1 : 0,
205      summarySig,
206      fromStatus,
207      patch.records ? actor : null
208    ),
209    ...(await mirrorStatements(env, job, `job-${verb}`, actor)),
210    jobAudit(env.DB, actor, `job-${verb}`, job, {
211      status: job.status,
212      ...(patch.seatCloses ? { held_by: read.claimed_by } : {}),
213      ...(patch.result_summary ? { result_summary: patch.result_summary } : {}),
214      ...(patch.result_ref ? { result_ref: patch.result_ref } : {}),
215      ...(patch.overlaps ? { overlaps: patch.overlaps } : {}),
216      ...(patch.breakerExempt ? { breaker_exempt: patch.breakerExempt } : {}),
217    }),
218  ];
219  if (patch.touches) statements.push(...patch.touches(job));
220  // The claim row is built here, BEFORE verifyEvidence runs, from the arguments as
221  // sent, so nothing GitHub says can reach it (src/job-claims.ts). It rides in this
222  // batch, so a transition the guard aborts leaves no claim behind either.
223  const claimed =
224    patch.said && (action === "complete" || action === "fail" || action === "block")
225      ? claimRow({
226          job_id: id,
227          action: patch.said.as ?? action,
228          agent: actor,
229          namespace: job.namespace,
230          raw: patch.said.raw,
231          claim: patch.said.claim,
232          evidence: patch.said.evidence ?? patch.evidence,
233          capsid_sha: env.BUILD_SHA ?? null,
234          now,
235        })
236      : undefined;
237  if (claimed) statements.push(claimStatement(env.DB, claimed));
238  if (job.status === "done" || job.status === "failed") {
239    const verdict = await verifyEvidence(env, job.namespace, patch.evidence, job.result_ref);
240    // One evaluation per worker check, the claim and GitHub's value side by side,
241    // after the claim row so its claim_id subquery finds it.
242    if (claimed) {
243      statements.push(...evaluationStatements(env.DB, evaluationRows(claimed, verdict, { evaluator_id: workerEvaluatorId(env.BUILD_SHA), now })));
244    }
245    // Cost, tokens and active time from the job's sessions' telemetry, NULL when none
246    // reached Capsid (src/ops-otlp.ts). Points exported after this read stay in
247    // session_usage and are not added to the row, which is written once.
248    const row = outcomeFrom(job, verdict, now, await readJobUsage(env.DB, job.id), claimed?.model_id ?? null);
249    outcome = { row, notes: verdict.notes };
250    statements.push(outcomeStatement(env.DB, row));
251    // One row per pull request the evidence named, in the same batch as the outcome.
252    // Without them the outcome keeps counts with no way back to what they counted, and
253    // the merge state recorded at complete time could never be corrected.
254    statements.push(...outcomePrStatements(env.DB, job.id, namedPrUrls(patch.evidence, job.result_ref), verdict.pr_states, now, verdict.pr_identity));
255  }
256  try {
257    await env.DB.batch(statements);
258  } catch (err) {
259    if (!isMissingRowAbort(err)) throw err;
260    // Nothing was written. Say what the row is now, as a lost race would have.
261    const current = await readJob(env.DB, id);
262    const gone = patch.seatCloses ? seatCloseRefusal(action, id, actor, current) : holderRefusal(action, id, actor, current);
263    return gone ?? refuse(action, `${id} changed between reading it and recording the ${action}. Nothing was written; try again.`);
264  }
265  return {
266    ok: true,
267    action,
268    job,
269    ...(outcome ? { outcome } : {}),
270    ...(patch.overlaps ? { overlaps: patch.overlaps } : {}),
271  };
272}
273
274// Binds a claimed job to the pull request a gate read, in result_ref, so a later call
275// naming another pull request is still answered for this one. Returns the row as bound,
276// or the refusal when the caller does not hold the job or the row moved.
277async function bindPullRequest(
278  env: Env,
279  agent: Agent,
280  now: Date,
281  action: string,
282  current: JobRow,
283  pr: string,
284  auditAction: "job-review-bound" | "job-ci-bound"
285): Promise<JobRow | JobResult> {
286  const notHeld = holderRefusal(action, current.id, agent.actor, current);
287  if (notHeld) return notHeld;
288  const job: JobRow = { ...current, result_ref: pr, updated_at: now.toISOString() };
289  const bound = await guardedTransition(env, current, [
290    env.DB.prepare(
291      `UPDATE jobs SET result_ref = ?2, updated_at = ?3
292       WHERE id = ?1 AND status = 'claimed' AND claimed_by = ?4 AND result_ref IS NULL RETURNING id`
293    ).bind(current.id, pr, now.toISOString(), agent.actor),
294    ...(await mirrorStatements(env, job, auditAction, agent.actor)),
295    jobAudit(env.DB, agent.actor, auditAction, job, { result_ref: pr }),
296  ]);
297  if (!bound) return refuse(action, `${current.id} moved between reading it and recording its pull request. Ask again.`);
298  return job;
299}
300
301// The review gate, consulted by complete, fail and block alike.
302//
303// A gate on one of them would not be a gate: a driver that found `complete` refused
304// would `block` or `fail` instead, and the bypass would look like ordinary use. So the
305// same function answers for all three, and the answer is turned into a JobResult here
306// so they cannot describe the same verdict differently.
307//
308// Only complete demands a pull request, because it hands the work on. A job that stops
309// at a gate has usually opened nothing yet, and a job that cannot be done has no pull
310// request to review; demanding one would leave the driver unable to close the job at
311// all. When a pull request is named, block and fail still consult the gate, so a
312// driver cannot walk away from a CHANGES or a BLOCK.
313//
314// Returns null when the gate does not apply: no review_required, or no pull request on
315// a transition that does not demand one. That is the normal path for almost every job.
316async function reviewRefusal(
317  env: Env,
318  agent: Agent,
319  now: Date,
320  action: string,
321  id: string,
322  resultRef: string | null,
323  opts: { requirePullRequest?: boolean; candidateRefs?: readonly (string | null | undefined)[]; said?: Said } = {}
324): Promise<JobResult | null> {
325  const current = await readJob(env.DB, id);
326  if (!current) return null;
327  // The stored reference is the job's bound pull request, if the gate has read one.
328  // The references this call names are candidates, so a driver completing with the
329  // pull request it just opened has it in its arguments.
330  let outcome: GateOutcome | null;
331  try {
332    outcome = await reviewGate(
333      env,
334      { namespace: current.namespace, review_required: current.review_required, result_ref: current.result_ref },
335      { requirePullRequest: opts.requirePullRequest, candidateRefs: [resultRef, ...(opts.candidateRefs ?? [])] }
336    );
337  } catch (err) {
338    // A GitHub failure holds the job rather than waving it through. The gate puts a
339    // second reader in front of the seat, and an unreadable comment list is not
340    // evidence that one looked.
341    return refuse(
342      action,
343      `${id} needs a review and GitHub could not be read: ${err instanceof Error ? err.message : String(err)}. ` +
344        `The job stays claimed; try again rather than treating an unreadable review as an approval.`
345    );
346  }
347  if (outcome === null) return null;
348
349  // The first read binds the job to its pull request in the result_ref column. On a
350  // claimed job nothing else writes it, and the terminal transition that does runs
351  // after this gate. Recorded whatever the verdict, so a CHANGES cannot be escaped by
352  // naming another pull request on the next call.
353  //
354  // Each write below is one guarded batch built from the caller's claimed job as read.
355  // The binding moves updated_at, so the CHANGES write after it guards on the row the
356  // binding left.
357  let read = current;
358  if (outcome.pr && !current.result_ref) {
359    const bound = await bindPullRequest(env, agent, now, action, current, outcome.pr, "job-review-bound");
360    if (!("status" in bound)) return bound;
361    read = bound;
362  }
363
364  if (outcome.kind === "proceed") return null;
365
366  if (outcome.kind === "waiting") {
367    return refuse(action, `${id} is ${outcome.reason} The job stays claimed.`);
368  }
369
370  // CHANGES and BLOCK both move the job, so neither is a plain refusal: the row has to
371  // record what the reviewer said, or the next reader sees a job that stalled for no
372  // stated reason.
373  const { review } = outcome;
374  // The reviewer's words come from a pull request comment, outside Capsid, and the driver reads them
375  // in the refusal and the block reason: fenced as external, and cut to fit the reason cap.
376  const said = review.said ? ` ${externalFence("review", review.by, review.said, 300)}` : "";
377  if (outcome.kind === "rework") {
378    // The cap is checked before the correction is spent, so the loop it bounds is
379    // bounded. If the rework path only incremented and left the job claimed, a third
380    // CHANGES would spend a third correction and send the work back again, and a
381    // reviewer and a driver disagreeing forever is the loop the cap exists for.
382    //
383    // At the cap the job goes to the seat through the ordinary block path, so it
384    // carries the reviewer's objection and the gate counter behaves as for any other
385    // block. fromReview stops blockJob consulting the review that produced it and
386    // recursing.
387    const spentOnWork = await correctionsForWork(env.DB, current.namespace, current.title);
388    if (atCorrectionCap(spentOnWork)) {
389      return endedElsewhere(action, await blockJob(env, agent, now, id, {
390        reason:
391          `review by ${review.by}: CHANGES.${said} This is correction ${spentOnWork + 1} against this work, past the cap of ${CORRECTION_CAP}: ` +
392          `${RETRY_CAP_REASON}. The reviewer and the driver have not converged, so what happens next is a person's call rather than another round.`,
393        fromReview: true,
394        review,
395        said: opts.said,
396      }));
397    }
398    // Back to the driver, spending a correction from the same budget the retry cap
399    // bounds. Counting review rounds separately would exempt them from the cap.
400    const summary = `review by ${review.by}: CHANGES.${said}`;
401    const notHeld = holderRefusal(action, id, agent.actor, read);
402    if (notHeld) return notHeld;
403    const job: JobRow = { ...read, result_summary: summary, corrections_count: read.corrections_count + 1, updated_at: now.toISOString() };
404    const won = await guardedTransition(env, read, [
405      env.DB.prepare(
406        `UPDATE jobs SET result_summary = ?2, summary_sig = NULL, corrections_count = corrections_count + 1, updated_at = ?3
407         WHERE id = ?1 AND status = 'claimed' AND claimed_by = ?4 RETURNING id`
408      ).bind(id, summary, now.toISOString(), agent.actor),
409      ...(await mirrorStatements(env, job, "job-review-changes", agent.actor)),
410      jobAudit(env.DB, agent.actor, "job-review-changes", job, {
411        verdict: review.verdict,
412        by: review.by,
413        at: review.at,
414        corrections_count: job.corrections_count,
415      }),
416      reviewTouch(env.DB, job, review, now),
417      ...(opts.said
418        ? [
419            claimStatement(
420              env.DB,
421              claimRow({
422                job_id: id,
423                action: opts.said.as ?? (action as "complete" | "fail" | "block"),
424                agent: agent.actor,
425                namespace: job.namespace,
426                raw: opts.said.raw,
427                claim: opts.said.claim,
428                evidence: opts.said.evidence,
429                capsid_sha: env.BUILD_SHA ?? null,
430                now,
431              })
432            ),
433          ]
434        : []),
435    ]);
436    if (!won) return refuse(action, `${id} moved between reading it and recording the review. Ask again.`);
437    return { ok: false, action, job, refusal: `${summary} The job stays claimed: fix it and hand it on again. This spent a correction (${job.corrections_count} of ${CORRECTION_CAP}).` };
438  }
439
440  // BLOCK: blocked for the seat, with the objection as the reason, through the
441  // ordinary block path so the gate counter and the mirror document behave as they do
442  // for any other block.
443  return endedElsewhere(action, await blockJob(env, agent, now, id, { reason: `review by ${review.by}: BLOCK.${said}`, fromReview: true, review, said: opts.said }));
444}
445
446// A CHANGES or BLOCK acted on is a touch by the reviewer named on the verdict, not by
447// the driver whose call met it. It ends no wait, so it carries no waited_ms.
448function reviewTouch(db: D1Database, job: JobRow, review: Review, now: Date): D1PreparedStatement {
449  return touchStatement(db, {
450    job_id: job.id,
451    namespace: job.namespace,
452    kind: "review",
453    actor: review.by,
454    actor_kind: actorKind(review.by, { reviewer: true }),
455    detail: { verdict: review.verdict, at: review.at, ...(review.said ? { said: review.said } : {}) },
456    sinceGate: false,
457    at: now.toISOString(),
458  });
459}
460
461// A transition that ended somewhere other than asked is not a success. A complete or
462// fail that met a reviewer BLOCK, or a CHANGES at the correction cap, blocks the job
463// instead, and passing blockJob's result through would tell a driver that asked for
464// something else ok: true with action "block". The block is recorded either way; this
465// reports it as a refusal of the caller's own action, with the job as it now stands.
466// A caller that asked to block got a block, so its result passes.
467function endedElsewhere(action: string, result: JobResult): JobResult {
468  if (!result.ok || action === result.action) return result;
469  return {
470    ok: false,
471    action,
472    ...(result.job ? { job: result.job } : {}),
473    refusal:
474      `${result.job?.id ?? "the job"} was not ${action === "complete" ? "completed" : `${action}ed`}: the reviewer's verdict blocked it for the seat instead, and that block is recorded. ` +
475      `${result.job?.result_summary ?? ""}`.trim(),
476  };
477}
478
479type CompleteArgs = { result_summary: string; result_ref?: string; evidence?: JobEvidence; claim?: ClaimInput; raw?: ClaimRaw };
480
481export async function completeJob(env: Env, agent: Agent, now: Date, id: string, args: CompleteArgs): Promise<JobResult> {
482  return completeWith(env, agent, now, id, args, false);
483}
484
485// The seat completing a blocked job (src/jobs-seat.ts adminCompleteJob checks who may).
486// The same checks and records as a holder's complete; only the row it applies to differs.
487export async function completeAsSeat(env: Env, agent: Agent, now: Date, id: string, args: CompleteArgs): Promise<JobResult> {
488  return completeWith(env, agent, now, id, args, true);
489}
490
491// The seat recording the outcome of a queued job that was worked without a claim. The
492// same checks, verification and records as a complete; the seat's review gate applies.
493export async function recordAsSeat(env: Env, agent: Agent, now: Date, id: string, args: CompleteArgs): Promise<JobResult> {
494  return completeWith(env, agent, now, id, args, true, "record");
495}
496
497// A session completing a queued job it worked without a claim, naming the pull request
498// (src/jobs-seat.ts completeUnclaimed checks who may). The record path, audited as
499// complete-unclaimed so it is not read as the seat recording somebody else's work.
500export async function completeWithoutClaim(env: Env, agent: Agent, now: Date, id: string, args: CompleteArgs): Promise<JobResult> {
501  return completeWith(env, agent, now, id, args, true, "complete-unclaimed");
502}
503
504// The review gate for a close the seat makes. A holder's complete may write (bind the
505// pull request, send the work back, block it); the seat's close writes nothing until the
506// review allows it, so a CHANGES or a BLOCK is answered, not escaped, and a refusal
507// leaves the job exactly as it was.
508async function seatReviewRefusal(env: Env, id: string, args: CompleteArgs): Promise<JobResult | null> {
509  const current = await readJob(env.DB, id);
510  if (!current) return null;
511  let outcome: GateOutcome | null;
512  try {
513    outcome = await reviewGate(
514      env,
515      { namespace: current.namespace, review_required: current.review_required, result_ref: current.result_ref },
516      { requirePullRequest: true, candidateRefs: [args.result_ref, ...(args.evidence?.prs ?? [])] }
517    );
518  } catch (err) {
519    return refuse(
520      "complete",
521      `${id} needs a review and GitHub could not be read: ${err instanceof Error ? err.message : String(err)}. Nothing was written; try again rather than treating an unreadable review as an approval.`
522    );
523  }
524  if (outcome === null || outcome.kind === "proceed") return null;
525  if (outcome.kind === "waiting") return refuse("complete", `${id} is ${outcome.reason} Nothing was written.`);
526  const verdict = outcome.kind === "rework" ? "CHANGES" : "BLOCK";
527  return refuse(
528    "complete",
529    `${id} cannot be completed around its review: review by ${outcome.review.by}: ${verdict}. ${outcome.review.said} A reviewer's ${verdict} is answered by the work or by a new review, not by the seat's close. Nothing was written.`
530  );
531}
532
533async function completeWith(
534  env: Env,
535  agent: Agent,
536  now: Date,
537  id: string,
538  args: CompleteArgs,
539  seatCloses: boolean,
540  records: false | "record" | "complete-unclaimed" = false
541): Promise<JobResult> {
542  if (!args.result_summary?.trim()) {
543    return refuse("complete", "complete needs a result_summary. A done job with no summary is a job the seat has to reconstruct from the diff.");
544  }
545  // Refused before anything else runs, so a claim that cannot be recorded whole
546  // leaves no row of any kind.
547  const claim = parseClaim(args.claim);
548  if ("error" in claim) return refuse("complete", claim.error);
549  // Checked before the write, because the outcome row this call produces cannot be
550  // corrected afterwards: a result_ref and evidence swallowed into the summary would
551  // leave a row that records nothing.
552  const swallowed = swallowedParamTag(args.result_summary);
553  if (swallowed) return refuse("complete", swallowedTagRefusal("result_summary", swallowed));
554  // The review gate (see reviewRefusal). complete must name a pull request and carry
555  // an APPROVE; evidence.prs counts as naming it, so a driver cannot report its work
556  // there with a document key in result_ref and escape the gate.
557  const completeRaw: ClaimRaw = args.raw ?? { evidence: args.evidence, claim: args.claim, result_summary: args.result_summary, result_ref: args.result_ref };
558  const review = seatCloses
559    ? await seatReviewRefusal(env, id, args)
560    : await reviewRefusal(env, agent, now, "complete", id, args.result_ref ?? null, {
561        requirePullRequest: true,
562        candidateRefs: args.evidence?.prs,
563        said: { claim: claim.claim, raw: completeRaw, as: "complete", evidence: args.evidence },
564      });
565  if (review) return review;
566  const held = await readJob(env.DB, id);
567  // The CI gate (src/complete-ci.ts): every pull request this complete names, and the one
568  // the job is bound to, must show green CI. A refused holder's job is bound to the pull
569  // request that was not green, so naming a different one next time does not escape it.
570  // The seat's close writes nothing before it is allowed, as with its review gate.
571  if (held) {
572    const bound = parsePrUrl(held.result_ref) ? [held.result_ref!.trim()] : [];
573    const ci = await ciRefusal(env, held.namespace, [...new Set([...bound, ...namedPrUrls(args.evidence, args.result_ref)])], held.body);
574    if (ci) {
575      if (!seatCloses && !held.result_ref && ci.pr) {
576        const kept = await bindPullRequest(env, agent, now, "complete", held, ci.pr, "job-ci-bound");
577        if (!("status" in kept)) return kept;
578      }
579      return refuse("complete", `${id} was not completed: ${ci.why}`);
580    }
581  }
582  // Overlap warning (Track A D1): the pull requests this complete names, against every other
583  // open one. The line rides in the summary the seat reads; the check cannot fail the call.
584  const overlaps = held ? await checkOverlaps(env, held.namespace, namedPrUrls(args.evidence, args.result_ref ?? held.result_ref)) : null;
585  const overlap = overlaps ? overlapLine(overlaps) : null;
586  return holderTransition(env, agent, now, "complete", id, {
587    status: "done",
588    result_summary: overlap ? `${args.result_summary}
589
590${overlap}` : args.result_summary,
591    overlaps,
592    result_ref: args.result_ref ?? null,
593    evidence: args.evidence,
594    said: { claim: claim.claim, raw: completeRaw },
595    ...(records
596      ? { records: true, recordVerb: records }
597      : seatCloses
598      ? {
599          seatCloses: true,
600          // The seat ending a blocked job's wait, in the same batch as the audit row. The job
601          // row it is built from still names the driver, so detail.held_by is who did the work.
602          touches: (job: JobRow) => [
603            touchStatement(env.DB, {
604              job_id: job.id,
605              namespace: job.namespace,
606              kind: "admin_complete",
607              actor: agent.actor,
608              actor_kind: actorKind(agent.actor, { seat: true }),
609              detail: { held_by: job.claimed_by, result_ref: job.result_ref },
610              sinceGate: true,
611              at: now.toISOString(),
612            }),
613          ],
614        }
615      : {}),
616  });
617}
618
619export async function failJob(
620  env: Env,
621  agent: Agent,
622  now: Date,
623  id: string,
624  reason: string,
625  said: { claim?: ClaimInput; raw?: ClaimRaw } = {}
626): Promise<JobResult> {
627  if (!reason?.trim()) return refuse("fail", "fail needs a reason. A failed job with no reason is one nobody can retry or rule on.");
628  const failSwallowed = swallowedParamTag(reason);
629  if (failSwallowed) return refuse("fail", swallowedTagRefusal("reason", failSwallowed));
630  const failClaim = parseClaim(said.claim);
631  if ("error" in failClaim) return refuse("fail", failClaim.error);
632  // The review gate (see reviewRefusal), without demanding a pull request.
633  const failRaw: ClaimRaw = said.raw ?? { claim: said.claim, reason };
634  const review = await reviewRefusal(env, agent, now, "fail", id, null, { said: { claim: failClaim.claim, raw: failRaw, as: "fail" } });
635  if (review) return review;
636  const held = await readJob(env.DB, id);
637  const breakerExempt = held && held.claimed_by === agent.actor ? await breakerExemption(env, held, reason) : null;
638  return holderTransition(env, agent, now, "fail", id, {
639    status: "failed",
640    result_summary: reason,
641    breakerExempt,
642    said: { claim: failClaim.claim, raw: failRaw },
643  });
644}
645
646// A blocked job carries the exact command. A job that hit a gate is not a failure; it
647// is work waiting on a human, and the human needs the command to run, not a
648// description of the situation. Capsid Portal shows these. blockJob writes this marker
649// and commandFromSummary reads it back, so the format cannot drift between the two.
650export const RESUME_MARKER = "Run this, then send it back in with capsid_work_jobs action 'resume':";
651// What blockJob wrote before the MCP 4 regroup. Summaries already stored carry it, so it
652// is still read; nothing writes it.
653const LEGACY_RESUME_MARKER = "Run this, then send it back in with jobs action 'resume':";
654
655/** Where a summary's resume marker starts and how long it is, or null with none. */
656export function resumeMarkerIn(summary: string): { at: number; length: number } | null {
657  for (const marker of [RESUME_MARKER, LEGACY_RESUME_MARKER]) {
658    const at = summary.indexOf(marker);
659    if (at !== -1) return { at, length: marker.length };
660  }
661  return null;
662}
663
664// A question block (Track A D4): a session that needs an answer rather than a command run
665// blocks with question: true. The reason is the question, the Worker fixes the command, and
666// the summary starts with this prefix, which is how every reader tells it from a gate. No new
667// status and no column: the seat answers with resume and a note, which claim and
668// list then hand to the driver permanently (resume_notes).
669const QUESTION_PREFIX = "QUESTION: ";
670const QUESTION_COMMAND = "Answer in a resume note";
671
672/** Whether a blocked job's summary is a question block. */
673export function isQuestionSummary(summary: string | null): boolean {
674  return summary !== null && summary.startsWith(QUESTION_PREFIX);
675}
676
677/** The exact command a blocked job is waiting on, or null when it recorded none. */
678export function commandFromSummary(summary: string | null): string | null {
679  if (!summary) return null;
680  const found = resumeMarkerIn(summary);
681  if (!found) return null;
682  const rest = summary.slice(found.at + found.length).trim();
683  return rest.length > 0 ? rest : null;
684}
685
686export async function blockJob(
687  env: Env,
688  agent: Agent,
689  now: Date,
690  id: string,
691  // review: the verdict that produced this block, when the gate blocked it, recorded
692  // as the reviewer's touch beside the gate. said: the agent's claim on the call the
693  // gate turned into this block, recorded under the action the agent called.
694  args: { reason: string; command?: string; question?: boolean; fromReview?: boolean; review?: Review; claim?: ClaimInput; raw?: ClaimRaw; said?: Said }
695): Promise<JobResult> {
696  if (!args.reason?.trim()) return refuse("block", args.question ? "a question block needs the question as its reason." : "block needs a reason: what gate was hit.");
697  // The command of a question is the Worker's, never the session's: a question that carried a
698  // command would be a gate in disguise, and the seat answers by resuming with a note.
699  if (args.question && args.command?.trim()) {
700    return refuse("block", `a question block takes no command: the Worker fixes it as '${QUESTION_COMMAND}'. Send the question as the reason, or drop question: true and block with the command.`);
701  }
702  const blockClaim = parseClaim(args.claim);
703  if ("error" in blockClaim) return refuse("block", blockClaim.error);
704  // The review gate (see reviewRefusal). `fromReview` is set when the gate itself
705  // blocks, so it does not consult itself again.
706  const blockRaw: ClaimRaw = args.raw ?? { claim: args.claim, reason: args.reason, command: args.command };
707  if (!args.fromReview) {
708    const review = await reviewRefusal(env, agent, now, "block", id, null, { said: { claim: blockClaim.claim, raw: blockRaw, as: "block" } });
709    if (review) return review;
710  }
711  const command = args.question ? QUESTION_COMMAND : args.command;
712  const base = args.question ? `${QUESTION_PREFIX}${args.reason}` : args.reason;
713  // Overlap warning (Track A D1): the pull requests this block names, in the job's result_ref
714  // or as URLs in the command, against every other open one. The line sits before the resume
715  // marker, so commandFromSummary still reads the command and nothing after it.
716  const named = await readJob(env.DB, id);
717  const overlaps = named ? await checkOverlaps(env, named.namespace, [...(named.result_ref ? [named.result_ref.trim()] : []), ...prUrlsIn(command)]) : null;
718  const overlap = overlaps ? overlapLine(overlaps) : null;
719  const text = overlap ? `${base}
720
721${overlap}` : base;
722  const summary = command ? `${text}\n\n${RESUME_MARKER}\n\n    ${command}` : text;
723  // The cap is applied where the block is written, so a capped job says so in the one
724  // field every reader already looks at: the Portal prints result_summary, the driver
725  // reads it to continue, and a human deciding reads it there too. The budget is read
726  // before the transition, because the transition is what makes this block count.
727  const current = await readJob(env.DB, id);
728  const capped = current !== null && atCorrectionCap(await correctionsForWork(env.DB, current.namespace, current.title));
729  return holderTransition(env, agent, now, "block", id, {
730    status: "blocked",
731    result_summary: capped ? cappedSummary(summary) : summary,
732    overlaps,
733    bumpBlocked: true,
734    // The gate is the start of a wait for someone else, which the resume that ends it
735    // measures from. The reason and command as the driver gave them, before the cap
736    // wording is added to the summary.
737    touches: (job) => [
738      ...(args.review ? [reviewTouch(env.DB, job, args.review, now)] : []),
739      touchStatement(env.DB, {
740        job_id: job.id,
741        namespace: job.namespace,
742        kind: "gate",
743        actor: agent.actor,
744        actor_kind: actorKind(agent.actor, { seat: callerIsSeat(agent) }),
745        detail: { reason: args.reason, command: command ?? null, ...(args.question ? { question: true } : {}) },
746        sinceGate: false,
747        at: now.toISOString(),
748      }),
749    ],
750    // A block the review gate made carries the claim of the call it diverted, if any.
751    said: args.fromReview ? args.said : { claim: blockClaim.claim, raw: blockRaw },
752  });
753}