src/jobs-begin.ts

Functions

Imports

It imports src/agents.ts, src/env.ts, src/jobs-mirror.ts, src/jobs-schema.ts, src/jobs-transition.ts, src/signed-docs.ts. Imported by src/jobs.ts.

Source

1import type { Env } from "./env";
2import type { Agent } from "./agents";
3import { outsideJobNamespace, startedNotice, type JobRow } from "./jobs-schema";
4import { jobAudit, mirrorStatements } from "./jobs-mirror";
5import { guardedTransition, readJob, refuse, type JobResult } from "./jobs-transition";
6import { verifySignedBody } from "./signed-docs";
7
8// Begin: the started label (job_e68de044f8a4; Dustin, 2026-10-10, plan step 2). A cloud
9// session works a job without claiming it and its pull request is the claim, as Copilot,
10// Codex and Claude Code Projects do it. What it lacked was a way to tell the next
11// session that somebody is already on the job. begin marks a queued job started:
12// started_by and started_at (migrations/0042).
13//
14// A label, not a lease. It never expires, and nothing reads it to refuse anything:
15// claim, complete and every other transition go on as before. The first session to
16// begin a job keeps the label; a later begin is told who started it and when, and
17// writes nothing. Any caller holding the write grant on the job's namespace may begin.
18//
19// begin is where a session that never claims starts acting on the body, so the body's
20// signature is checked here as claim checks it: a body changed after post is refused,
21// and the session is told not to run it. Nothing is written for it; claim is where a
22// tampered job is marked failed.
23//
24// One guarded batch, like park: the label, the mirror and the audit row commit together
25// or not at all, and the begin moves updated_at, so two sessions beginning at once
26// resolve to one label and the second is told whose it is.
27
28export async function beginJob(env: Env, agent: Agent, now: Date, id: string): Promise<JobResult> {
29  const current = await readJob(env.DB, id);
30  if (!current) return refuse("begin", `no job ${id}.`);
31  const outside = outsideJobNamespace(agent, current.namespace);
32  if (outside) return refuse("begin", `${agent.actor} cannot begin ${id} ('${current.title}'): ${outside}`);
33  const already = startedNotice(current);
34  if (already) return { ok: true, action: "begin", job: current, started: already, note: "already started; nothing was written." };
35  if (current.status !== "queued") {
36    return refuse(
37      "begin",
38      `${id} is ${current.status}${current.claimed_by ? ` (held by ${current.claimed_by})` : ""}. begin marks a queued job started; a claimed or blocked job already says who is on it, and a finished one is not reopened.`
39    );
40  }
41
42  const verdict = await verifySignedBody(env.IMPROVE_SCORE_SECRET, current.body, "job body");
43  if (!verdict.ok) return refuse("begin", `${id} was not started, and its prompt must not be run: ${verdict.reason}`);
44
45  const at = now.toISOString();
46  const started: JobRow = { ...current, started_at: at, started_by: agent.actor, updated_at: at };
47  const won = await guardedTransition(env, current, [
48    env.DB.prepare(
49      `UPDATE jobs SET started_at = ?2, started_by = ?3, updated_at = ?2 WHERE id = ?1 AND status = 'queued' AND started_at IS NULL RETURNING id`
50    ).bind(id, at, agent.actor),
51    ...(await mirrorStatements(env, started, "job-started", agent.actor)),
52    jobAudit(env.DB, agent.actor, "job-started", started, { started_at: at }),
53  ]);
54  if (!won) {
55    // Somebody began it, or it moved, between the read and the write. Never a refusal
56    // when the reason is another session's label: say whose it is.
57    const moved = await readJob(env.DB, id);
58    const theirs = moved ? startedNotice(moved) : null;
59    if (moved && theirs) return { ok: true, action: "begin", job: moved, started: theirs, note: "already started; nothing was written." };
60    return refuse("begin", `${id} changed between reading it and beginning it: it is now ${moved?.status ?? "gone"}. Nothing was written.`);
61  }
62  return { ok: true, action: "begin", job: started, started: startedNotice(started) ?? undefined };
63}