src/overnight.ts

Functions

Imports

It imports src/env.ts, src/log.ts, src/store-guards.ts. Imported by src/controls-perform.ts, src/controls-plan.ts, src/ops-feed.ts, src/status.ts, src/tools/status.ts.

Source

1import type { Env } from "./env";
2import { auditStatement } from "./store-guards";
3import { logEvent } from "./log";
4
5// THE OVERNIGHT RUN SWITCH (capsid/research/design-automation-for-speed.md, D2 and D3, ruled
6// by Dustin 2026-10-04). A scheduled run of the per-namespace drivers on Dustin's own
7// machine, off unless he turns it on, with a "Runs on"
8// choice of API key or subscription. Three values (OVERNIGHT_MODES: api,
9// subscription, off) and the Portal's switch pattern: a reason on every change, an
10// audit row, and the value read back.
11//
12// What the switch is NOT: the way work normally runs. Hand-started VS Code tabs that
13// chain jobs are ordinary use Dustin starts himself; they are the default and this
14// switch does not touch them.
15//
16// Choosing the subscription records the decision where the switch is set, as the ruling
17// requires: who decided, when, and the reasoning, kept beside the mode in APP_KV and in
18// the audit row. The scheduler refuses to run on the subscription without that record.
19
20export const OVERNIGHT_MODE_KEY = "overnight:mode";
21export const OVERNIGHT_DECISION_KEY = "overnight:decision";
22
23const OVERNIGHT_MODES = ["api", "subscription", "off"] as const;
24export type OvernightMode = (typeof OVERNIGHT_MODES)[number];
25
26// The ruling, in one place, so the record and the Portal's confirm text say the same
27// thing. The reasoning is Dustin's, from his ruling of 2026-10-04. Sources and quotes:
28// capsid/research/terms-scheduled-claude-code.md.
29export const SUBSCRIPTION_DECISION = {
30  decided_by: "Dustin Edwards",
31  decided_on: "2026-10-04",
32  ruling: "2026-10-04: overnight runs may use the subscription, by Dustin's choice",
33  reasoning:
34    "The use is personal, on Dustin's own repositories, and not shared. Anthropic's Agent SDK support page (updated 2026-06-16) says claude -p on a plan draws from subscription limits and directs shared production automation to API keys; Dustin reads shared as the operative word. The Consumer Terms clause on automated or non-human access (section 3) is the counterweight: the pages do not settle the question and the risk is to Dustin's own account.",
35} as const;
36
37export interface OvernightDecision {
38  decided_by: string;
39  decided_on: string;
40  ruling: string;
41  reasoning: string;
42  // Who set the switch, when, and the reason given at the switch.
43  set_by: string;
44  set_at: string;
45  reason: string;
46}
47
48export interface OvernightState {
49  mode: OvernightMode;
50  // The recorded decision, present only while the mode is subscription.
51  decision: OvernightDecision | null;
52}
53
54const isMode = (value: unknown): value is OvernightMode => typeof value === "string" && (OVERNIGHT_MODES as readonly string[]).includes(value);
55
56function parseDecision(raw: string | null): OvernightDecision | null {
57  if (raw === null) return null;
58  try {
59    const value = JSON.parse(raw) as Partial<OvernightDecision> | null;
60    if (
61      value &&
62      typeof value.decided_by === "string" &&
63      typeof value.decided_on === "string" &&
64      typeof value.ruling === "string" &&
65      typeof value.reasoning === "string" &&
66      typeof value.set_by === "string" &&
67      typeof value.set_at === "string" &&
68      typeof value.reason === "string"
69    ) {
70      return value as OvernightDecision;
71    }
72  } catch (err) {
73    logEvent("error", "OVERNIGHT_DECISION_UNREADABLE", { message: `OVERNIGHT_DECISION_UNREADABLE: ${err instanceof Error ? err.message : String(err)}; treating the record as absent` });
74    return null;
75  }
76  // Valid JSON of another shape: reported and read as absent, never as a decision.
77  logEvent("error", "OVERNIGHT_DECISION_UNREADABLE", {
78    message: "OVERNIGHT_DECISION_UNREADABLE: the stored decision record is not the shape setOvernight writes; treating it as absent",
79  });
80  return null;
81}
82
83/**
84 * The switch as stored. Anything unreadable or unexpected is off: a switch that fails
85 * open would start a scheduled run on a value nobody set. The subscription mode with no
86 * readable decision record reads as off for the same reason.
87 */
88export async function overnightState(env: Env): Promise<OvernightState> {
89  try {
90    const mode = await env.APP_KV.get(OVERNIGHT_MODE_KEY);
91    if (!isMode(mode) || mode === "off") return { mode: "off", decision: null };
92    if (mode === "api") return { mode, decision: null };
93    const decision = parseDecision(await env.APP_KV.get(OVERNIGHT_DECISION_KEY));
94    return decision ? { mode, decision } : { mode: "off", decision: null };
95  } catch (err) {
96    logEvent("error", "OVERNIGHT_UNREADABLE", { message: `OVERNIGHT_UNREADABLE: ${err instanceof Error ? err.message : String(err)}; treating the switch as off` });
97    return { mode: "off", decision: null };
98  }
99}
100
101export function overnightValueRefusal(value: string | undefined): string | null {
102  return isMode(value) ? null : `overnight must be one of ${OVERNIGHT_MODES.join(", ")}; got '${value ?? ""}'.`;
103}
104
105/** What setting the switch will record, for the confirm step and the audit row. */
106export function decisionFor(value: OvernightMode, actor: string, now: Date, reason: string): OvernightDecision | null {
107  return value === "subscription" ? { ...SUBSCRIPTION_DECISION, set_by: actor, set_at: now.toISOString(), reason } : null;
108}
109
110/**
111 * Set the switch, audited, and read back. The reason is required: turning automation on
112 * or off needs one (ruled 2026-09-30). Choosing the subscription writes the decision
113 * record in the same step; any other value deletes it, so a later choice of the
114 * subscription records its own date and reason rather than inheriting an old one.
115 */
116export async function setOvernight(env: Env, actor: string, now: Date, opts: { value?: string; reason?: string }): Promise<{ action: "overnight" } & OvernightState> {
117  const value = opts.value?.trim().toLowerCase();
118  const bad = overnightValueRefusal(value);
119  if (bad) throw new Error(`${bad} Nothing was changed.`);
120  const reason = opts.reason?.trim();
121  if (!reason) throw new Error("overnight needs a reason: why the overnight run goes on, off, or changes what it runs on. It is recorded with the change. Nothing was changed.");
122  const mode = value as OvernightMode;
123  const decision = decisionFor(mode, actor, now, reason);
124  await env.APP_KV.put(OVERNIGHT_MODE_KEY, mode);
125  if (decision) await env.APP_KV.put(OVERNIGHT_DECISION_KEY, JSON.stringify(decision));
126  else await env.APP_KV.delete(OVERNIGHT_DECISION_KEY);
127  await env.DB.batch([auditStatement(env.DB, actor, "overnight-set", null, null, { mode, reason, ...(decision ? { decision } : {}) })]);
128  return { action: "overnight", ...(await overnightState(env)) };
129}