@moo.md/hum 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/defaults/hum.json +5 -0
  2. package/defaults/roles/build.md +1 -1
  3. package/defaults/roles/fix.md +1 -1
  4. package/npm-shrinkwrap.json +3297 -0
  5. package/package.json +6 -2
  6. package/release.json +3 -0
  7. package/schema/hum.schema.json +47 -7
  8. package/scripts/eval.ts +21 -5
  9. package/src/adapter-api.ts +3 -1
  10. package/src/adapters/claude-bg.ts +2 -2
  11. package/src/adapters/claude-p.ts +44 -18
  12. package/src/adapters/contract.ts +12 -0
  13. package/src/adapters/fake.ts +5 -0
  14. package/src/adapters/git.ts +61 -9
  15. package/src/adapters/github-client.ts +15 -0
  16. package/src/adapters/github-commits.ts +84 -0
  17. package/src/adapters/github.ts +9 -0
  18. package/src/adapters/guard.ts +1 -0
  19. package/src/adapters/item-file.ts +1 -1
  20. package/src/adapters/markdown.ts +10 -1
  21. package/src/adapters/pull-requests.ts +8 -8
  22. package/src/adapters/registry.ts +3 -6
  23. package/src/adapters/roundup.ts +3 -0
  24. package/src/bytes.ts +1 -0
  25. package/src/cli/service.ts +176 -29
  26. package/src/cli/setup.ts +28 -33
  27. package/src/config/checks.ts +21 -50
  28. package/src/config/load.ts +2 -3
  29. package/src/config/machine.ts +29 -0
  30. package/src/config/refusal.ts +5 -6
  31. package/src/config/schema.ts +23 -7
  32. package/src/config/wake-job.ts +6 -2
  33. package/src/decide/risk.ts +2 -2
  34. package/src/exec.ts +10 -0
  35. package/src/index.ts +1 -1
  36. package/src/loop/records.ts +8 -1
  37. package/src/measure/rate.ts +22 -0
  38. package/src/publish/bundle.ts +128 -0
  39. package/src/publish/handoff.ts +107 -0
  40. package/src/publish/handover.ts +182 -0
  41. package/src/publish/intents.ts +61 -0
  42. package/src/publish/publisher.ts +259 -0
  43. package/src/publish/wake.ts +78 -0
  44. package/src/service/ci-state.ts +99 -0
  45. package/src/service/plugins.ts +137 -0
  46. package/src/service/wake.ts +3 -1
  47. package/src/service/workflows.ts +126 -30
  48. package/src/setup/propose.ts +17 -4
  49. package/src/setup/prove.ts +3 -3
  50. package/src/setup/write.ts +2 -2
  51. package/src/state/items.ts +17 -8
  52. package/src/state/open.ts +20 -6
  53. package/src/state/records.ts +7 -0
  54. package/src/state/runs.ts +5 -0
  55. package/src/state/saved.ts +17 -2
  56. package/src/worker/base-check.ts +41 -13
  57. package/src/worker/checks.ts +3 -2
  58. package/src/worker/evidence.ts +72 -0
  59. package/src/worker/kind.ts +4 -7
  60. package/src/worker/land.ts +173 -81
  61. package/src/worker/merged.ts +20 -8
  62. package/src/worker/open.ts +33 -17
  63. package/src/worker/questions.ts +16 -8
  64. package/src/worker/signed-push.ts +167 -0
  65. package/src/worker/thin-path.ts +245 -133
  66. package/src/worker/worker.ts +50 -9
  67. package/surface.json +185 -56
@@ -1,4 +1,4 @@
1
- import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
1
+ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2
2
  import { tmpdir } from "node:os";
3
3
  import { dirname, join } from "node:path";
4
4
  import { z } from "zod";
@@ -12,13 +12,14 @@ import {
12
12
  gitIn,
13
13
  isAncestor,
14
14
  PATCH,
15
- push,
16
15
  type PushOutcome,
16
+ readOrAbsent,
17
17
  } from "../adapters/git.ts";
18
+ import type { GitHubCommits } from "../adapters/github-commits.ts";
18
19
  import { landOwnerCommit } from "../adapters/owner-commit.ts";
19
20
  import { commandTimeoutMs } from "../exec.ts";
20
21
  import { changeOf, historiesOf, readHistory } from "../adapters/history.ts";
21
- import { markDone } from "../adapters/item-file.ts";
22
+ import { DONE_STATE, markDone, parseItemFile } from "../adapters/item-file.ts";
22
23
  import {
23
24
  type BranchRules,
24
25
  methodFor,
@@ -27,7 +28,9 @@ import {
27
28
  } from "../adapters/pull-requests.ts";
28
29
  import type { ModelCall } from "../adapters/model-call.ts";
29
30
  import type { Config } from "../config/load.ts";
30
- import type { Boundary } from "../config/schema.ts";
31
+ import type { Boundary, Kind, PURPOSES } from "../config/schema.ts";
32
+ import { pickTier } from "../config/checks.ts";
33
+ import { footprintOf } from "./scheduler.ts";
31
34
  import { alignedPlacement, alignmentQuestion, doesGateAlignment } from "../decide/alignment.ts";
32
35
  import {
33
36
  isCleared,
@@ -58,6 +61,8 @@ import { pickedAnswer } from "./thread.ts";
58
61
  import { reportAlignment } from "./alignment-report.ts";
59
62
  import { reportTaste } from "./taste.ts";
60
63
  import type { ThinResult } from "./thin-path.ts";
64
+ import { evidenceMarkdown } from "./evidence.ts";
65
+ import { pushBase, pushCommits, pushRunBranch } from "./signed-push.ts";
61
66
 
62
67
  const SHORT_EXCERPT = 200;
63
68
 
@@ -65,13 +70,14 @@ const HUM_CONFIG = ".hum/hum.json";
65
70
 
66
71
  const NO_RULES: BranchRules = {
67
72
  requiresPullRequest: false,
73
+ requiresSignatures: false,
68
74
  mergeMethods: undefined,
69
75
  };
70
76
 
71
77
  /** A change's pull request as it stands at one head of the run branch, which a report on it is made once for. */
72
78
  export type PullAtHead = { readonly pulls: PullRequests; readonly pull: Pull; readonly head: string };
73
79
 
74
- /** Everything landing a finished change reads and writes. The clone has the run branch checked out and the base fetched. */
80
+ /** Everything landing a finished change reads and writes: publish's own worktree with the run branch checked out. No check of the repo runs here. */
75
81
  export type LandContext = {
76
82
  readonly state: State;
77
83
  readonly config: Config;
@@ -82,19 +88,20 @@ export type LandContext = {
82
88
  readonly base: string;
83
89
  readonly remote: string;
84
90
  readonly clone: string;
85
- /** What the run's folder adds to the environment of the repo's checks. */
86
- readonly env: Readonly<Record<string, string>>;
87
91
  readonly dir: string;
88
92
  readonly git: Git;
89
- readonly checks: readonly string[];
90
93
  readonly workSource: WorkSource;
91
94
  readonly questions: Questions;
92
95
  /** The remote's pull requests and branch rules; undefined for a remote that is not on GitHub. */
93
96
  readonly pulls: PullRequests | undefined;
97
+ /** The remote's branches through GitHub's API, which signs the commits it makes; undefined for a remote that is not on GitHub. */
98
+ readonly commits: GitHubCommits | undefined;
94
99
  readonly now: () => number;
95
100
  readonly judge: ModelCall;
96
101
  /** A fresh review run on the change that ends at `head`, at its level's tier; it saves its verdict. */
97
102
  readonly reviewRun: (change: { readonly head: string; readonly diff: string; readonly level: string }) => Promise<ReviewOutcome>;
103
+ /** The time past which no merge starts, as when the GitHub token's hour runs short; the landing stays saved for the next wake. */
104
+ readonly mergesBefore?: number;
98
105
  };
99
106
 
100
107
  /** What a review run at landing came to: its verdict, or the result that stopped it, such as a usage limit. */
@@ -103,8 +110,8 @@ export type ReviewOutcome = { readonly verdict: Verdict } | { readonly halted: T
103
110
  /** The review verdict that lets a change merge. */
104
111
  const REVIEW_APPROVAL = "approve";
105
112
 
106
- /** Why the change cannot merge on the newest base: it conflicts there, or its checks fail there. */
107
- type Stale = { readonly kind: "stale"; readonly why: string };
113
+ /** The base moved after the work side checked the change on it: pushing now could land code no check ran on. */
114
+ type Moved = { readonly kind: "moved" };
108
115
 
109
116
  /** A push that did not land: the remote refused it in `said`, or another writer moved the ref first. */
110
117
  type Unpushed = Exclude<PushOutcome, { kind: "pushed" }>;
@@ -113,8 +120,8 @@ type Unpushed = Exclude<PushOutcome, { kind: "pushed" }>;
113
120
  export const unpushed = (id: string, ref: string, outcome: Unpushed): ThinResult =>
114
121
  outcome.kind === "refused" ? { outcome: "stuck", item: id, detail: outcome.said } : { outcome: "held", item: id, why: `another push moved ${ref} first` };
115
122
 
116
- /** How a push to the base ended: the base holds the change, it cannot merge on the newest base, or the push did not land. */
117
- type BaseLanding = { readonly kind: "landed" } | Stale | Unpushed;
123
+ /** How a push to the base ended: the base holds the change, the base moved since the change was checked, or the push did not land. */
124
+ type BaseLanding = { readonly kind: "landed" } | Moved | Unpushed;
118
125
 
119
126
  const LANDED: BaseLanding = { kind: "landed" };
120
127
 
@@ -161,13 +168,25 @@ export const placementOf = async (
161
168
  };
162
169
  };
163
170
 
171
+ /** The change an item declares before any run: the paths it says it touches. */
172
+ export const declaredChange = (item: Item): Change => ({ paths: footprintOf(item) ?? [], size: 0, loosened: false, pinChanged: false });
173
+
174
+ /** The model and effort the kind's tier table gives a run of `purpose` on `change`, at the level the change places at. */
175
+ export const tierOf = async (ctx: Pick<LandContext, "config" | "state" | "git" | "base" | "now"> & { readonly kind: string }, kind: Kind, purpose: (typeof PURPOSES)[number], change: Change): Promise<{ readonly model: string; readonly effort: Kind["tiers"][number]["effort"] }> => {
176
+ const { placement } = await placementOf(ctx, change);
177
+ const row = pickTier(kind, { purpose, level: placement.level.name, size: "small" });
178
+
179
+ if (!row) throw new Error(`the ${ctx.kind} table has no ${purpose} row`);
180
+
181
+ return { model: ctx.config.hum.models[row.tier], effort: row.effort };
182
+ };
183
+
184
+ /** The run branch's diff from where it left the base to `tip`, the item's own file left out: hum's done mark is no part of the change. */
185
+ const changeDiff = ({ git, base, dir, id }: Pick<LandContext, "git" | "base" | "dir" | "id">, tip = "HEAD"): Promise<string> =>
186
+ git.raw(["diff", ...PATCH, `origin/${base}...${tip}`, "--", ".", `:(exclude)${dir}/${id}.md`]);
187
+
164
188
  /** The diff of the run branch against the base, read as the risk level reads it. */
165
- export const changeOn = async ({
166
- git,
167
- base,
168
- config,
169
- }: Pick<LandContext, "git" | "base" | "config">): Promise<Change> =>
170
- changeOf(await git.raw(["diff", ...PATCH, `origin/${base}...HEAD`]), config.hum);
189
+ export const changeOn = async (ctx: Pick<LandContext, "git" | "base" | "config" | "dir" | "id">): Promise<Change> => changeOf(await changeDiff(ctx), ctx.config.hum);
171
190
 
172
191
  /** The level the owner picked for unclear paths, answered since the change was saved. */
173
192
  const answeredLevel = (item: Item, since: number, levels: readonly string[]): string | undefined => pickedAnswer(item.thread, levels, since)?.option;
@@ -233,7 +252,7 @@ const learnRules = async (
233
252
  branchPrefix: config.hum.ownerBranchPrefix,
234
253
  mergeMethod: config.hum.mergeMethod,
235
254
  pulls: ctx.pulls,
236
- push: (refspecs) => push(git, ["origin", ...refspecs]),
255
+ push: (refspecs) => pushCommits({ git, base, pulls: ctx.pulls, commits: ctx.commits }, refspecs),
237
256
  });
238
257
 
239
258
  if (landed.via === "refused") return { kind: "refused", said: landed.said };
@@ -249,19 +268,54 @@ const learnRules = async (
249
268
  }
250
269
  };
251
270
 
252
- /** Marks the item done on the run branch, pushes the branch and saves what its diff showed, so a retry lands it without a run. `ownerApproved` records that the owner approved this change in its review state. */
253
- export const prepareLanding = async (ctx: LandContext, { ownerApproved = false }: { readonly ownerApproved?: boolean } = {}): Promise<PushOutcome> => {
254
- const { git, clone, dir, id, branch, state, now } = ctx;
255
- const change = await changeOn(ctx);
256
- const head = (await git.raw(["rev-parse", "HEAD"])).trim();
271
+ /**
272
+ * Where the run branch holds the item's file, as a markdown item's branch does, the file is marked done in a commit of
273
+ * its own, so the merged change itself takes the item off the ready list. A work source that keeps its items
274
+ * elsewhere ends the item once the change merged.
275
+ */
276
+ const markItemDone = async ({ git, clone, dir, id }: LandContext): Promise<void> => {
257
277
  const file = join(clone, dir, `${id}.md`);
258
278
 
259
- writeFileSync(file, markDone(readFileSync(file, "utf8")));
279
+ if (!existsSync(file)) return;
280
+
281
+ const source = readFileSync(file, "utf8");
282
+
283
+ if (parseItemFile(source).state === DONE_STATE) return;
284
+
285
+ writeFileSync(file, markDone(source));
260
286
  await git.raw(["add", `${dir}/${id}.md`]);
261
287
  await git.raw(["commit", "-q", "-m", `hum: finish ${id}`]);
262
- const pushed = await push(git, ["--force", "origin", `HEAD:refs/heads/${branch}`]);
288
+ };
263
289
 
264
- if (pushed.kind === "pushed") state.landings.put(id, { item: id, branch, since: now(), change, head, ownerApproved });
290
+ /** The patch id of the change against the base: a rebase keeps it. */
291
+ const patchOf = async (ctx: Pick<LandContext, "git" | "base" | "dir" | "id">): Promise<string> => (await ctx.git.raw(["patch-id", "--stable"], await changeDiff(ctx))).split(" ")[0] ?? "";
292
+
293
+ /**
294
+ * Marks the item done on the run branch where it holds the item's file, pushes the branch and saves what its diff
295
+ * showed, so a retry lands it without a run. The saved head is the change before hum's done mark; a push GitHub signed
296
+ * rebuilt the change as its own commit, which is then the head, and a verdict on the old commit holds for its tree.
297
+ * The same change saved again, as after a rebase, keeps when it was first saved, so the owner's answers since then
298
+ * still count; a new change starts the count afresh.
299
+ */
300
+ export const prepareLanding = async (ctx: LandContext): Promise<PushOutcome> => {
301
+ const { git, id, branch, state, now } = ctx;
302
+ const change = await changeOn(ctx);
303
+ const built = (await git.raw(["rev-parse", "HEAD"])).trim();
304
+ const patch = await patchOf(ctx);
305
+ const saved = state.landings.get(id);
306
+ const kept = saved?.patch === patch ? saved : undefined;
307
+
308
+ await markItemDone(ctx);
309
+ const pushed = await pushRunBranch(ctx, branch);
310
+
311
+ if (pushed.kind !== "pushed") return pushed;
312
+
313
+ const head = (await isAncestor(git, { ancestor: built, descendant: "HEAD" })) ? built : (await git.raw(["rev-parse", "HEAD"])).trim();
314
+ const verdict = state.verdicts.get(id);
315
+
316
+ if (head !== built && verdict?.head === built) state.verdicts.put(id, { ...verdict, head });
317
+
318
+ state.landings.put(id, { item: id, branch, since: kept?.since ?? now(), change, head, lostRaces: kept?.lostRaces ?? 0, alignment: kept?.alignment, patch });
265
319
 
266
320
  return pushed;
267
321
  };
@@ -273,54 +327,71 @@ const isOnBase = async ({ git, base }: LandContext): Promise<boolean> => {
273
327
  return isAncestor(git, { ancestor: "HEAD", descendant: `origin/${base}` });
274
328
  };
275
329
 
276
- /** The change on the newest base: when the base moved it is rebased and the checks run again; else why it cannot merge there. */
277
- const ontoNewestBase = async ({ git, base, clone, env, checks, config }: LandContext): Promise<Stale | undefined> => {
278
- await git.raw(["fetch", "-q", "origin", base]);
279
-
280
- if (await isAncestor(git, { ancestor: `origin/${base}`, descendant: "HEAD" })) return undefined;
330
+ /**
331
+ * The change on the base the work side checked it on, as a work pass leaves it: rebased there when it does not grow
332
+ * from it, and checked again; else why it cannot merge there.
333
+ */
334
+ export const rebaseOnto = async ({ git, clone, env, checks, config, base }: { readonly git: Git; readonly clone: string; readonly env: Readonly<Record<string, string>>; readonly checks: readonly string[]; readonly config: Config; readonly base: string }, onto: string): Promise<string | undefined> => {
335
+ if (await isAncestor(git, { ancestor: onto, descendant: "HEAD" })) return undefined;
281
336
 
282
- const rebased = await git.run(["rebase", "-q", `origin/${base}`]);
337
+ const rebased = await git.run(["rebase", "-q", onto]);
283
338
 
284
339
  if (rebased.code !== 0) {
285
340
  await git.run(["rebase", "--abort"]);
286
341
 
287
- return { kind: "stale", why: `the change conflicts with the newest ${base}: ${rebased.stderr.trim().slice(0, SHORT_EXCERPT)}` };
342
+ return `the change conflicts with the newest ${base}: ${rebased.stderr.trim().slice(0, SHORT_EXCERPT)}`;
288
343
  }
289
344
 
290
345
  const failure = await runChecks(checks, clone, { env, timeoutMs: checksTimeoutMs(config.hum) });
291
346
 
292
- return failure ? { kind: "stale", why: `the checks fail on the newest ${base}: ${failure.slice(0, SHORT_EXCERPT)}` } : undefined;
347
+ return failure && `the checks fail on the newest ${base}: ${failure.slice(0, SHORT_EXCERPT)}`;
293
348
  };
294
349
 
295
- const pushBranchAndBase = async ({ git, base, branch }: LandContext): Promise<PushOutcome> => {
296
- const toBranch = await push(git, ["--force", "origin", `HEAD:refs/heads/${branch}`]);
350
+ const pushBranchAndBase = async (ctx: LandContext): Promise<PushOutcome> => {
351
+ const toBranch = await pushRunBranch(ctx, ctx.branch);
297
352
 
298
- return toBranch.kind === "pushed" ? push(git, ["origin", `HEAD:refs/heads/${base}`]) : toBranch;
353
+ return toBranch.kind === "pushed" ? pushBase(ctx) : toBranch;
299
354
  };
300
355
 
301
- const finish = async ({ state, git, id, now }: LandContext): Promise<ThinResult> => {
302
- recordMerged(state, { item: id, sha: (await git.raw(["rev-parse", "HEAD"])).trim(), at: now() });
356
+ /** Whether the change holds the item's file marked done, so the merge itself took the item off the ready list. */
357
+ const endedByChange = async ({ git, dir, id }: LandContext): Promise<boolean> => {
358
+ const source = await readOrAbsent(git, ["show", `HEAD:${dir}/${id}.md`]);
359
+
360
+ return source !== undefined && parseItemFile(source).state === DONE_STATE;
361
+ };
362
+
363
+ /**
364
+ * The change is on the base: its item ends at the work source unless the change ended it, then the merge is recorded.
365
+ * A failed end leaves the landing saved, so the next pass ends it again.
366
+ */
367
+ const finish = async (ctx: LandContext): Promise<ThinResult> => {
368
+ const { state, git, id, item, workSource, now } = ctx;
369
+
370
+ if (!(await endedByChange(ctx))) await workSource.finish(item.id);
371
+ await recordMerged(state, { git, remote: "origin" }, { item: id, sha: (await git.raw(["rev-parse", "HEAD"])).trim(), at: now() });
303
372
 
304
373
  return { outcome: "merged", item: id };
305
374
  };
306
375
 
307
- /** Pushes the change to the base once, rechecked on the newest base before each try; a base another push moved first is tried again, up to `mergeTries` pushes. */
376
+ /** Pushes the change to the base once, only as it grows from the base as it stands: a base that moved after the change was checked waits for the next pass to check it again. */
308
377
  const pushToBase = async (ctx: LandContext): Promise<BaseLanding> => {
309
378
  if (await isOnBase(ctx)) return LANDED;
310
379
 
311
- for (let tries = 0; tries < ctx.config.hum.mergeTries; tries++) {
312
- const stale = await ontoNewestBase(ctx);
380
+ if (!(await isAncestor(ctx.git, { ancestor: `origin/${ctx.base}`, descendant: "HEAD" }))) return { kind: "moved" };
313
381
 
314
- if (stale) return stale;
382
+ const pushed = await ctx.state.ops.once({ itemId: ctx.id, run: "merge", attempt: 0, op: "push-base" }, { holds: () => isOnBase(ctx), run: () => pushBranchAndBase(ctx), isDone: ({ kind }) => kind === "pushed" });
315
383
 
316
- const pushed = await ctx.state.ops.once({ itemId: ctx.id, run: "merge", attempt: 0, op: "push-base" }, { holds: () => isOnBase(ctx), run: () => pushBranchAndBase(ctx), isDone: ({ kind }) => kind === "pushed" });
317
-
318
- if (pushed.kind === "skipped" || pushed.value.kind === "pushed") return LANDED;
384
+ return pushed.kind === "skipped" || pushed.value.kind === "pushed" ? LANDED : pushed.value;
385
+ };
319
386
 
320
- if (pushed.value.kind === "refused") return pushed.value;
321
- }
387
+ /** What the change's pull request says: the text the run wrote under the repo's own rules, else the item's title, then its evidence, then hum's word on the merge and the item. */
388
+ const pullRequestOf = ({ state, id, item }: LandContext, merging: string) => {
389
+ const written = state.pullRequests.get(id);
322
390
 
323
- return { kind: "conflict" };
391
+ return {
392
+ title: written?.title ?? `hum: ${item.title}`,
393
+ body: [written?.body, written?.evidence && evidenceMarkdown(written.evidence), merging, `Item ${id}.`].filter(Boolean).join("\n\n"),
394
+ };
324
395
  };
325
396
 
326
397
  /** One pull request from the run branch: it merges itself once GitHub's required checks pass when the change is cleared, and waits for the owner otherwise. */
@@ -328,17 +399,8 @@ const throughPullRequest = async (
328
399
  ctx: LandContext,
329
400
  { pulls, autoMerge, route, rules, why }: { readonly pulls: PullRequests; readonly autoMerge: boolean; readonly route: Route; readonly rules: BranchRules; readonly why: string },
330
401
  ): Promise<ThinResult> => {
331
- const { id, branch, base, item, config } = ctx;
332
- const body = `${autoMerge ? `Level ${route.level.name}: it merges once the required checks pass.` : `Not merged by hum: ${why}.`}\n\nItem ${id}.`;
333
-
334
- const pull =
335
- (await pulls.find(branch)) ??
336
- (await pulls.open({
337
- head: branch,
338
- base,
339
- title: `hum: ${item.title}`,
340
- body,
341
- }));
402
+ const { id, branch, base, config } = ctx;
403
+ const pull = (await pulls.find(branch)) ?? (await pulls.open({ head: branch, base, ...pullRequestOf(ctx, autoMerge ? `Level ${route.level.name}: it merges once the required checks pass.` : `Not merged by hum: ${why}.`) }));
342
404
 
343
405
  if (pull.state === "MERGED") return finish(ctx);
344
406
 
@@ -380,17 +442,26 @@ const afterRefusal = async (
380
442
  );
381
443
  };
382
444
 
383
- /** The card of a base that other pushes kept moving through every one of `mergeTries` pushes. It stands while the item stays held; the pass that decides the item another way clears it. */
445
+ /** The card of a base that other pushes moved first on `mergeTries` passes in a row. It stands while the item stays held; the pass that decides the item another way clears it. */
384
446
  export const BASE_CONTENDED = "base-contended";
385
447
 
386
- /** One card while the item's pushes to the base keep losing the race, however many passes that lasts. */
387
- const raiseContention = ({ state, id, base, config }: LandContext): void =>
388
- void state.faults.raise({
389
- code: BASE_CONTENDED,
390
- item: id,
391
- cause: `${id} lost the race to ${base} on all ${config.hum.mergeTries} pushes of a pass: another push moved ${base} first each time`,
392
- fix: `hum tries again each pass. If this card stays, find what keeps pushing to ${base}, or raise mergeTries in .hum/hum.json.`,
393
- });
448
+ /** Counts a pass that lost the race to the base, and raises one card once `mergeTries` passes in a row did. */
449
+ const loseRace = ({ state, id, base, config }: LandContext, why: string): ThinResult => {
450
+ const saved = state.landings.get(id);
451
+ const lost = (saved?.lostRaces ?? 0) + 1;
452
+
453
+ if (saved) state.landings.put(id, { ...saved, lostRaces: lost });
454
+
455
+ if (lost >= config.hum.mergeTries)
456
+ state.faults.raise({
457
+ code: BASE_CONTENDED,
458
+ item: id,
459
+ cause: `${id} lost the race to ${base} on ${lost} passes in a row: another push moved ${base} first each time`,
460
+ fix: `hum tries again each pass. If this card stays, find what keeps pushing to ${base}, or raise mergeTries in .hum/hum.json.`,
461
+ });
462
+
463
+ return { outcome: "held", item: id, why };
464
+ };
394
465
 
395
466
  const landBy = async (
396
467
  ctx: LandContext,
@@ -402,6 +473,8 @@ const landBy = async (
402
473
  if (landing.via === "wait")
403
474
  return { outcome: "review", item: ctx.id, detail: why };
404
475
 
476
+ if (ctx.mergesBefore !== undefined && ctx.now() >= ctx.mergesBefore) return { outcome: "held", item: ctx.id, why: "too little of the GitHub token's hour is left to merge; the next wake lands it" };
477
+
405
478
  if (landing.via === "pull-request" && ctx.pulls)
406
479
  return throughPullRequest(ctx, { pulls: ctx.pulls, autoMerge: landing.autoMerge, route, rules, why });
407
480
 
@@ -409,24 +482,26 @@ const landBy = async (
409
482
 
410
483
  if (landed.kind === "refused") return afterRefusal(ctx, { cleared: true, route, why, said: landed.said });
411
484
 
412
- if (landed.kind === "conflict") {
413
- raiseContention(ctx);
485
+ if (landed.kind === "conflict") return loseRace(ctx, `another push moved ${ctx.base} first`);
414
486
 
415
- return unpushed(ctx.id, ctx.base, landed);
416
- }
487
+ if (landed.kind === "moved") return loseRace(ctx, `${ctx.base} moved after the change was checked on it; the next pass checks it there`);
417
488
 
418
- return landed.kind === "stale" ? { outcome: "review", item: ctx.id, detail: landed.why } : finish(ctx);
489
+ return finish(ctx);
419
490
  };
420
491
 
421
492
  /**
422
493
  * Lands a change saved by `prepareLanding`, by its level under the policy as it stands now: an answered level
423
494
  * becomes a path rule first, an unclear change asks once, and the target branch's rules pick a push or a pull request.
495
+ * The owner's approval counts only when they gave it after this change was saved, so no earlier answer approves it.
424
496
  */
425
497
  export const land = async (ctx: LandContext): Promise<ThinResult> => {
426
498
  const saved = ctx.state.landings.get(ctx.id);
427
499
 
428
500
  if (!saved) throw new Error(`no landing is saved for ${ctx.id}`);
429
501
 
502
+ // A change of no files, such as a split item's, whose branch the base already holds has nothing left to land.
503
+ if (saved.change.paths.length === 0 && (await isOnBase(ctx))) return finish(ctx);
504
+
430
505
  const first = await placementOf(ctx, saved.change);
431
506
  const answered = answeredLevel(ctx.item, saved.since, levelNames(ctx.config));
432
507
  const learns = first.placement.unclear.length > 0 && answered !== undefined;
@@ -441,10 +516,11 @@ export const land = async (ctx: LandContext): Promise<ThinResult> => {
441
516
 
442
517
  if (placement.unclear.length > 0) await askUnclear(ctx, placement.unclear);
443
518
 
444
- const diff = await ctx.git.raw(["diff", ...PATCH, `origin/${ctx.base}...${saved.head}`]);
519
+ const diff = await changeDiff(ctx, saved.head);
445
520
  const alignment = saved.change.paths.length > 0 ? await alignmentOf(ctx, saved, diff) : undefined;
446
521
  const aligned = doesGateAlignment(ctx.config.hum) && alignment && "graded" in alignment ? alignedPlacement(placement, alignment.graded, ctx.config.hum) : placement;
447
- const routeWith = (verdict?: Verdict): Route => routeOf(aligned, policy.paths, ctx.kind, saved.change.paths, abstentionsOf(ctx, alignment, verdict));
522
+ const planModels = await planModelsOf(ctx);
523
+ const routeWith = (verdict?: Verdict): Route => routeOf(aligned, policy.paths, ctx.kind, saved.change.paths, abstentionsOf(ctx, { alignment, planModels, verdict }));
448
524
  const placed = routeWith();
449
525
  const reviewed = doesNeedReviewRun(placed) ? await verdictOn(ctx, { head: saved.head, diff, level: placed.level.name }) : undefined;
450
526
 
@@ -452,7 +528,7 @@ export const land = async (ctx: LandContext): Promise<ThinResult> => {
452
528
 
453
529
  const verdict = reviewed?.verdict;
454
530
  const route = routeWith(verdict);
455
- const approvals = { review: verdict?.event === REVIEW_APPROVAL, owner: saved.ownerApproved || pickedAnswer(ctx.item.thread, [OWNER_APPROVAL], saved.since) !== undefined };
531
+ const approvals = { review: verdict?.event === REVIEW_APPROVAL, owner: pickedAnswer(ctx.item.thread, [OWNER_APPROVAL], saved.since) !== undefined };
456
532
  const why = verdict && verdict.event !== REVIEW_APPROVAL ? `the review run answered ${verdict.event}: ${verdict.reason}` : waitReason(route);
457
533
  const rules = ctx.pulls ? await ctx.pulls.rules(ctx.base) : NO_RULES;
458
534
 
@@ -482,16 +558,32 @@ const abstained = (boundary: Boundary, why: string): Unclear => ({ cause: "absta
482
558
 
483
559
  const unmeasured = (models: readonly string[]): string => `${models.join(", ") || "no model"} has no measured rate that meets the bar`;
484
560
 
561
+ /** Whether an item of `kind` runs a plan: a state of its machine runs a role whose purpose is plan. */
562
+ const doesPlan = (config: Config, kind: Kind): boolean => Object.values(kind.machine.states).some((node) => node.invoke !== undefined && config.hum.roles[node.invoke.src]?.purpose === "plan");
563
+
564
+ /**
565
+ * The models behind the item's plan: the one its kind's tier table gives the plan run, with any the run reported,
566
+ * which can only add to it; none where the kind never plans.
567
+ */
568
+ const planModelsOf = async (ctx: LandContext): Promise<readonly string[] | undefined> => {
569
+ const kind = ctx.config.kinds[ctx.kind];
570
+
571
+ if (kind === undefined || !doesPlan(ctx.config, kind)) return undefined;
572
+
573
+ const { model } = await tierOf(ctx, kind, "plan", declaredChange(ctx.item));
574
+
575
+ return [...new Set([model, ...(ctx.state.plans.get(ctx.id)?.models ?? [])])];
576
+ };
577
+
485
578
  /** Every model judgment behind the change that abstained, or came from a model id its boundary was not measured on. */
486
- const abstentionsOf = (ctx: LandContext, alignment: SavedLanding["alignment"], verdict: Verdict | undefined): Unclear[] => {
579
+ const abstentionsOf = (ctx: LandContext, { alignment, planModels, verdict }: { readonly alignment: SavedLanding["alignment"]; readonly planModels: readonly string[] | undefined; readonly verdict: Verdict | undefined }): Unclear[] => {
487
580
  const isMeasured = (boundary: Boundary, models: readonly string[]): boolean => isTrusted(models, boundary, ctx.config.hum);
488
581
  const kind = ctx.state.itemKinds.get(ctx.id);
489
- const plan = ctx.state.plans.get(ctx.id);
490
582
 
491
583
  return [
492
584
  ...(kind?.from === "fallback" ? [abstained("kind", kind.why)] : []),
493
585
  ...(doesGateAlignment(ctx.config.hum) && alignment && "abstained" in alignment ? [abstained("alignment", alignment.abstained)] : []),
494
- ...(plan && !isMeasured("plan-outcome", plan.models) ? [abstained("plan-outcome", unmeasured(plan.models))] : []),
586
+ ...(planModels && !isMeasured("plan-outcome", planModels) ? [abstained("plan-outcome", unmeasured(planModels))] : []),
495
587
  ...(verdict && !isMeasured("review-verdict", verdict.models) ? [abstained("review-verdict", unmeasured(verdict.models))] : []),
496
588
  ];
497
589
  };
@@ -1,30 +1,42 @@
1
+ import { ItemId, type WorkSource } from "../adapter-api.ts";
1
2
  import type { PullRequests } from "../adapters/pull-requests.ts";
3
+ import type { Git } from "../adapters/git.ts";
2
4
  import type { State } from "../state/open.ts";
5
+ import { dropEvidence } from "./evidence.ts";
6
+
7
+ /** Where a merged change's evidence ref is taken off: git in a repo with `remote`. */
8
+ export type EvidenceRemote = { readonly git: Git; readonly remote: string };
3
9
 
4
10
  /**
5
- * An item's change reached the base: the merge is kept for the measure, the saved landing, plan and verdict go,
6
- * and the merge is logged once per commit.
11
+ * An item's change reached the base: its evidence ref is taken off the remote, the merge is kept for the measure, the
12
+ * saved landing, plan, verdict and pull request text go, and the merge is logged once per commit.
7
13
  */
8
- export const recordMerged = (state: State, { item, sha, at }: { readonly item: string; readonly sha: string; readonly at: number }): void => {
14
+ export const recordMerged = async (state: State, { git, remote }: EvidenceRemote, { item, sha, at }: { readonly item: string; readonly sha: string; readonly at: number }): Promise<void> => {
9
15
  const landing = state.landings.get(item);
16
+ const evidence = state.pullRequests.get(item)?.evidence;
17
+
18
+ if (evidence !== undefined && "url" in evidence) await dropEvidence(git, { remote, item });
10
19
 
11
- state.merges.put(item, { item, sha, at, paths: [...(landing?.change.paths ?? [])] });
20
+ state.merges.put(item, { item, sha, at, paths: [...(landing?.change.paths ?? [])], baseChecked: false });
12
21
  state.landings.remove(item);
13
22
  state.plans.remove(item);
14
23
  state.verdicts.remove(item);
24
+ state.pullRequests.remove(item);
15
25
  state.events.add({ source: "work-source", sourceId: `merged:${sha}`, itemId: item, type: "merged", payload: {} });
16
26
  };
17
27
 
18
28
  /**
19
- * A change that landed through a pull request is merged by GitHub after the worker has moved on, and the item is never
20
- * listed again. Each saved landing whose pull request has merged is recorded as merged, so the measure counts it.
29
+ * A change that landed through a pull request is merged by GitHub after the worker has moved on. Each saved landing
30
+ * whose pull request has merged ends its item at the work source, so it is never listed again, and is recorded as
31
+ * merged, so the measure counts it.
21
32
  */
22
- export const settleMergedPulls = async (state: State, pulls: Pick<PullRequests, "find">, at: number): Promise<void> => {
33
+ export const settleMergedPulls = async (state: State, { pulls, workSource, ...evidenceRemote }: { readonly pulls: Pick<PullRequests, "find">; readonly workSource: Pick<WorkSource, "finish"> } & EvidenceRemote, at: number): Promise<void> => {
23
34
  await Promise.all(
24
35
  state.landings.list().map(async ({ item, branch, head }) => {
25
36
  if ((await pulls.find(branch))?.state !== "MERGED") return;
26
37
 
27
- recordMerged(state, { item, sha: head, at });
38
+ await workSource.finish(ItemId.parse(item));
39
+ await recordMerged(state, evidenceRemote, { item, sha: head, at });
28
40
  state.items.remove(item);
29
41
  }),
30
42
  );
@@ -1,32 +1,41 @@
1
1
  import { join } from "node:path";
2
2
  import { z } from "zod";
3
- import type { Integrations } from "../adapter-api.ts";
3
+ import { ADAPTER_API_VERSION, type Integrations } from "../adapter-api.ts";
4
+ import type { WorkIntegrations } from "../publish/handover.ts";
4
5
  import { resolveAdapters } from "../adapters/registry.ts";
5
6
  import { startBackgroundRunner } from "../adapters/claude-bg.ts";
6
- import { startRunner } from "../adapters/claude-p.ts";
7
+ import { judgmentRunner, startRunner } from "../adapters/claude-p.ts";
7
8
  import { gitIn } from "../adapters/git.ts";
8
9
  import { repoFromRemote } from "../adapters/github.ts";
9
10
  import { ownerGitHub } from "../adapters/github-client.ts";
10
11
  import { githubLoopReads } from "../loop/github.ts";
11
12
  import { gitHubPullRequests } from "../adapters/pull-requests.ts";
13
+ import { gitHubCommits } from "../adapters/github-commits.ts";
12
14
  import { serialized } from "../adapters/serial.ts";
13
15
  import { SlotPool } from "../slots/pool.ts";
14
16
  import { loadConfig, readConfigDir } from "../config/load.ts";
15
17
  import type { HumConfig } from "../config/schema.ts";
16
- import { commandTimeoutMs, type Env } from "../exec.ts";
18
+ import { commandTimeoutMs, type Env, withoutGitHubTokens } from "../exec.ts";
17
19
  import { defaultStateDir, openState } from "../state/open.ts";
18
20
  import { DEFAULT_BASE } from "./thin-path.ts";
19
21
  import { Worker, type WorkerOptions } from "./worker.ts";
20
22
 
21
- export type OpenWorkerOptions = Omit<WorkerOptions, "repo" | "state" | "config" | "adapters" | "runner" | "remote" | "pulls" | "loop" | "checks" | "runnerVariables"> & {
23
+ export type OpenWorkerOptions = Omit<WorkerOptions, "repo" | "state" | "config" | "adapters" | "runner" | "remote" | "pulls" | "commits" | "loop" | "checks" | "runnerVariables"> & {
22
24
  /** Where saved state lives; default `<git common dir>/hum`. */
23
25
  readonly stateDir?: string;
24
- /** The skill names of hope's installed copy; a role that names another is refused. */
25
- readonly hopeSkills: ReadonlySet<string>;
26
+ /** The installed plugins' skills, as a role names them; a role that names another plugin skill is refused. Absent where the worker makes judgment calls alone. */
27
+ readonly installedSkills?: ReadonlySet<string>;
28
+ /**
29
+ * The worker makes judgment calls alone and runs no role, as a CI job that holds GitHub's token: its runner makes
30
+ * no start check, which would run a full session with the repo's plugins and hooks, and refuses any other run.
31
+ */
32
+ readonly judgmentsOnly?: boolean;
26
33
  readonly remote?: string;
27
34
  readonly binary?: string;
28
35
  /** The process environment: runs start with it, and the GitHub login and adapters read it. */
29
36
  readonly env: Env;
37
+ /** The work source and questions in place of the ones `hum.json` names, with no GitHub reads: a CI work job's inbox. */
38
+ readonly integrations?: WorkIntegrations;
30
39
  };
31
40
 
32
41
  const Latest = z.looseObject({ version: z.string().min(1) });
@@ -51,11 +60,15 @@ const isInBackground = ({ backgroundRuns }: Pick<HumConfig, "backgroundRuns">, w
51
60
  * remote on GitHub its pull requests and branch rules, so landing follows what the target branch requires.
52
61
  * Throws when the config is refused or the repo has no `origin`; the service unit shows that as a card.
53
62
  */
54
- export const openWorker = async (repo: string, options: OpenWorkerOptions): Promise<Worker> => {
55
- const { stateDir, hopeSkills, binary, env, ...rest } = options;
63
+ /** A worker on `repo`, as `workerOptions` opens it. */
64
+ export const openWorker = async (repo: string, options: OpenWorkerOptions): Promise<Worker> => new Worker(await workerOptions(repo, options));
65
+
66
+ /** Everything a worker on `repo` works with: its state, its config, its integrations, its runner and its remote. */
67
+ export const workerOptions = async (repo: string, options: OpenWorkerOptions): Promise<WorkerOptions> => {
68
+ const { stateDir, installedSkills, judgmentsOnly, binary, env, ...rest } = options;
56
69
  const { now } = rest;
57
70
  const state = openState(stateDir ?? (await defaultStateDir(repo)), { now });
58
- const loaded = loadConfig(readConfigDir(join(repo, ".hum")), { env: { hopeSkills } });
71
+ const loaded = loadConfig(readConfigDir(join(repo, ".hum")), { env: { installedSkills } });
59
72
 
60
73
  if (!loaded.ok) throw new Error(loaded.refusal.message);
61
74
 
@@ -68,11 +81,13 @@ export const openWorker = async (repo: string, options: OpenWorkerOptions): Prom
68
81
 
69
82
  if (config.hum.checks.length === 0) throw new Error("hum.json names no checks: set \"checks\" to the commands a change must pass, or run /hum");
70
83
 
71
- const adapters = await resolveAdapters(repo, {
72
- faults: state.faults,
73
- guard: { lastReady: { load: () => state.ready.get("work-source")?.ids ?? [], save: (ids) => state.ready.put("work-source", { ids }) } },
74
- context: { report: (fault) => void state.faults.raise(fault), now, env },
75
- });
84
+ const adapters = options.integrations
85
+ ? { "work-source": { apiVersion: ADAPTER_API_VERSION, ...options.integrations }, questions: { apiVersion: ADAPTER_API_VERSION, ...options.integrations }, answers: undefined }
86
+ : await resolveAdapters(repo, {
87
+ faults: state.faults,
88
+ guard: { lastReady: { load: () => state.ready.get("work-source")?.ids ?? [], save: (ids) => state.ready.put("work-source", { ids }) } },
89
+ context: { report: (fault) => void state.faults.raise(fault), now, env },
90
+ });
76
91
 
77
92
  // One adapter serves several slots; its calls go one at a time whichever slot they come through.
78
93
  const ordered = new Map<Integrations, Integrations>();
@@ -90,13 +105,14 @@ export const openWorker = async (repo: string, options: OpenWorkerOptions): Prom
90
105
  if (!workSource || !questions) throw new Error("hum.json names no work source or no questions integration");
91
106
 
92
107
  const runnerOptions = { state, model: config.hum.models.light, binary, env, now, timeoutMs };
93
- const { runner } = isInBackground(config.hum, rest.where) ? await startBackgroundRunner({ ...runnerOptions, config: config.hum, repo }) : await startRunner(runnerOptions);
108
+ const runner = judgmentsOnly ? judgmentRunner(runnerOptions) : (isInBackground(config.hum, rest.where) ? await startBackgroundRunner({ ...runnerOptions, config: config.hum, repo }) : await startRunner(runnerOptions)).runner;
94
109
 
95
110
  // A slot is a worktree a background run starts in, so the pool stands only where runs are background agents.
96
111
  const slots = config.hum.runSlots.enabled && isInBackground(config.hum, rest.where) ? new SlotPool({ repo, state, config: config.hum, base: rest.base ?? DEFAULT_BASE, liveRuns: runner.liveRuns, now }) : undefined;
97
- const github = repoFromRemote(remote);
112
+ const github = options.integrations ? undefined : repoFromRemote(remote);
98
113
  const pulls = github === undefined ? undefined : gitHubPullRequests(github, { timeoutMs, env });
114
+ const commits = github === undefined ? undefined : gitHubCommits(github, { timeoutMs, env });
99
115
  const loop = github === undefined ? undefined : githubLoopReads(github, rest.base ?? DEFAULT_BASE, config.hum.measureWindow, () => ownerGitHub(timeoutMs, env));
100
116
 
101
- return new Worker({ ...rest, checks: config.hum.checks, checkout: rest.checkout ?? slots?.checkout, slots, repo, state, config, adapters: { workSource, questions, answers }, runner, remote, pulls, loop, runnerVariables: new Set(Object.keys(env)) });
117
+ return { ...rest, checks: config.hum.checks, checkout: rest.checkout ?? slots?.checkout, slots, repo, state, config, adapters: { workSource, questions, answers }, runner, remote, pulls, commits, loop, runnerVariables: new Set(Object.entries(withoutGitHubTokens(env)).flatMap(([name, value]) => (value === undefined ? [] : [name]))) };
102
118
  };