eve-hub 0.16.10 → 0.16.12

package/kit-change.d.mts

@@ -0,0 +1,3 @@
+export type KitUpdate = { files: Record<string, string>; deletions: string[]; reported: string[] };
+export declare class KitChangeError extends Error {}
+export declare function kitChange(source: { paths: string[]; read: (paths: string[]) => Promise<Map<string, string>> }): Promise<KitUpdate>;

package/kit-change.mjs

@@ -0,0 +1,66 @@
+// What a kit update changes in a workspace repo, read from any source of its files: the hosted hub reads them over
+// GitHub's API (hosted-hub/src/onboard/repo-bump.ts), `eve-hub update` (update.mjs) from a checkout. syncKit's kit-file
+// changes, the `eve-hub/world` line dropped from each `agent.ts`, and each hosted bot's `sandbox.ts` moved to one
+// `git__gh` runs in (migrateSandbox). Customized files are left alone and reported.
+import { isKitFile, syncKit } from "./sync-kit.mjs";
+import { migrateSandbox } from "./sandbox-migrate.mjs";
+import { agentRunsOn, parseWorkspace, WorkspaceError, WORKSPACE_FILE } from "./workspace.mjs";
+import KIT_MODULES from "./kit-modules.json" with { type: "json" };
+
+const AGENT_FILE = /^agents\/([^/]+)\/agent\/(.+)$/;
+
+// The line workspaces made before kit 0.13.0 have in `agent.ts`. The kit no longer exports `eve-hub/world`, so a build that keeps it fails.
+const HUB_WORLD_LINE = /^[ \t]*experimental:\s*\{\s*workflow:\s*\{\s*world:\s*(["'])eve-hub\/world\1\s*\}\s*\},?[ \t]*\r?\n/m;
+
+// A repo a person must repair before the kit can update it; the message says what to fix.
+export class KitChangeError extends Error {}
+
+// `paths` are every file in the repo, workspace-relative; `read(paths)` returns their text by path.
+export async function kitChange({ paths, read }) {
+  if (!paths.includes(WORKSPACE_FILE)) throw new KitChangeError(`no ${WORKSPACE_FILE}`);
+  const definition = definitionOf((await read([WORKSPACE_FILE])).get(WORKSPACE_FILE));
+  const isAgentFile = (path) => /(?:^|\/)agent\.ts$/.test(AGENT_FILE.exec(path)?.[2] ?? "");
+  const hostedSandbox = (path) => {
+    const m = AGENT_FILE.exec(path);
+    return m?.[2] === "sandbox.ts" && definition.agents.some((a) => a.name === m[1]) && agentRunsOn(definition, m[1]) === "hosted";
+  };
+  const found = paths.filter((p) => isKitFile(AGENT_FILE.exec(p)?.[2] ?? "") || isAgentFile(p) || hostedSandbox(p));
+  const text = await read(found);
+  const files = new Map(definition.agents.map((a) => [a.name, {}]));
+  const agentFiles = [], sandboxes = [];
+  for (const p of found) {
+    const [, bot, file] = AGENT_FILE.exec(p);
+    if (!files.has(bot)) continue;
+    if (isAgentFile(p)) agentFiles.push({ path: p, text: text.get(p) });
+    if (hostedSandbox(p)) sandboxes.push({ path: p, text: text.get(p) });
+    else if (isKitFile(file)) files.get(bot)[file] = text.get(p);
+  }
+  const tiersOf = (name) => Object.keys(definition.agents.find((a) => a.name === name)?.subagents ?? {});
+  const bots = [...files].map(([name, f]) => ({ name, runsOn: agentRunsOn(definition, name), files: f, subagents: tiersOf(name) }));
+  const change = syncKit({ bots, modules: KIT_MODULES });
+  const path = (bot, file) => `agents/${bot}/agent/${file}`;
+  const world = agentFiles.filter((f) => f.text.includes("eve-hub/world")).map((f) => ({ path: f.path, text: f.text.replace(HUB_WORLD_LINE, "") }));
+  const moved = sandboxes.map((f) => ({ path: f.path, text: f.text, ...migrateSandbox(f.text) }));
+  return {
+    files: {
+      ...Object.fromEntries(change.write.map((w) => [path(w.bot, w.file), w.content])),
+      ...Object.fromEntries(world.filter((f) => !f.text.includes("eve-hub/world")).map((f) => [f.path, f.text])),
+      ...Object.fromEntries(moved.filter((f) => f.source !== undefined && f.source !== f.text).map((f) => [f.path, f.source])),
+    },
+    deletions: change.delete.map((d) => path(d.bot, d.file)),
+    reported: [
+      ...change.report.map((r) => `${path(r.bot, r.file)} ${r.reason}`),
+      ...world.filter((f) => f.text.includes("eve-hub/world")).map((f) => `${f.path} still imports eve-hub/world, which the kit no longer has`),
+      ...moved.filter((f) => f.reason).map((f) => `${f.path} ${f.reason}`),
+    ],
+  };
+}
+
+function definitionOf(text) {
+  let json;
+  try { json = JSON.parse(text); } catch { throw new KitChangeError(`${WORKSPACE_FILE} is not valid JSON; fix it, then retry`); }
+  try { return parseWorkspace(json); } catch (e) {
+    if (e instanceof WorkspaceError) throw new KitChangeError(`${e.message}; fix it, then retry`);
+    throw e;
+  }
+}

package/kit-store.d.mts

@@ -0,0 +1,6 @@
+export declare const KIT_STORE: string;
+export declare const KIT_LATEST: string;
+export declare function kitTarball(version: string): string;
+export declare function kitTarballUrl(version: string): string;
+export declare function kitLatestUrl(): string;
+export declare function pinnedVersion(pin: string | undefined): string | undefined;

package/kit-store.mjs

@@ -0,0 +1,14 @@
+// Where each eve-hub version's tarball is served: a public Vercel Blob store (eve-hub-kit, on vercel-internal-playground),
+// one immutable file per version, uploaded by scripts/publish.mjs before the npm publish. Hosted workspaces pin this URL,
+// so nothing a deploy waits on reads eve-hub from npm, whose publish-time malware scan can hold a new version 15 minutes or more.
+// `latest.json` beside them names the newest release; a workspace's eve-hub-update workflow reads it.
+export const KIT_STORE = "https://fql3r3ljskj7rzcd.public.blob.vercel-storage.com";
+export const kitTarball = (version) => `eve-hub/eve-hub-${version}.tgz`;
+export const kitTarballUrl = (version) => `${KIT_STORE}/${kitTarball(version)}`;
+export const KIT_LATEST = "eve-hub/latest.json";
+export const kitLatestUrl = () => `${KIT_STORE}/${KIT_LATEST}`;
+
+// The version a pin names: a tarball URL from the store or a plain version; undefined for anything else (a link, a range).
+export function pinnedVersion(pin) {
+  return /(?:^|\/eve-hub-)(\d+\.\d+\.\d+)(?:\.tgz)?$/.exec(pin ?? "")?.[1];
+}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "eve-hub",
-  "version": "0.16.10",
+  "version": "0.16.12",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",
+  "bin": {
+    "eve-hub": "./update.mjs"
+  },
   "exports": {
     "./package.json": "./package.json",
     "./tools/*": "./tools/*.js",
@@ -30,7 +33,10 @@
     "./bot-token": "./bot-token.mjs",
     "./hub-oidc": "./hub-oidc.mjs",
     "./prepare": "./prepare.mjs",
-    "./vercel": "./vercel.mjs"
+    "./vercel": "./vercel.mjs",
+    "./kit-change": "./kit-change.mjs",
+    "./kit-store": "./kit-store.mjs",
+    "./update": "./update.mjs"
   },
   "peerDependencies": {
     "@vercel/connect": "^2.4.1",
@@ -47,5 +53,8 @@
     "smol-toml": "^1.9.1",
     "tree-sitter-bash": "0.25.1",
     "web-tree-sitter": "0.27.1"
+  },
+  "hubPins": {
+    "eve": "0.88.0"
   }
 }

package/schedules/dash-plan-schema.mjs

@@ -4,10 +4,13 @@
 import * as z from "zod";
 
 export const VERBS = ["Land", "Answer", "Pick", "Look", "Review", "Read", "Write"];
-const Row = z.object({ id: z.string().min(1), title: z.string().min(1).max(120), verb: z.enum(VERBS), minutes: z.int().min(0).max(600), consent: z.boolean() });
+const Row = z.object({
+  id: z.string().min(1), title: z.string().min(1).max(120), verb: z.enum(VERBS), minutes: z.int().min(0).max(600), consent: z.boolean(),
+  why: z.string().min(1).max(160).optional(), park: z.iso.date().nullable().optional(),
+});
 export const PlanBody = z.object({
   line: z.string().min(1).max(240),
-  chunks: z.array(z.object({ title: z.string().min(1).max(120), why: z.string().min(1).max(240), rows: z.array(Row).min(1) })).max(40),
+  chunks: z.array(z.object({ title: z.string().min(1).max(120), why: z.string().min(1).max(240), track: z.string().min(1).max(160).optional(), since: z.string().min(1).max(160).optional(), rows: z.array(Row).min(1) })).max(40),
   later: z.object({ line: z.string().min(1).max(240), rows: z.array(Row) }).nullable(),
   moved: z.array(z.object({ ask: z.string().min(1), reason: z.string().min(1).max(240) })),
 });

package/schedules/dash-plan.mjs

@@ -9,6 +9,10 @@
 // or the local day changed. Answering an ask doesn't make one: the answered row drops out in the
 // app. The previous plan goes into the prompt as a fact, so the list stands still between visits.
 //
+// Parking: a row may carry `park`, a local day. The first plan step on or after it defers that
+// thread through the Dash entries, the way the human's own defer does, and stores the plan without
+// the row. The day changing already makes a plan step, so parking needs no timer of its own.
+//
 // Plain JS on purpose: the schedule (TypeScript, bundled by eve) and the tests and replay (plain
 // node) import the same module.
 import { said, clip } from "./thread-brief.mjs";
@@ -56,13 +60,11 @@ export function waitingThreads(snap) {
 }
 
 /** One key per ask: the asking message, or the request. A new ask in a thread that was planned is a new key. */
-const askKeys = (snap) => {
-  const human = humanOf(snap);
-  return waitingThreads(snap).flatMap((t) => {
-    const m = askingMessage((t.messages ?? []).filter(said), human);
-    return [...(m ? [`${t.id}@${m.id}`] : []), ...requestsOf(snap, t.id).map((r) => `${t.id}@${r.id}`)];
-  }).sort();
+const threadAskKeys = (snap, t, human = humanOf(snap)) => {
+  const m = askingMessage((t.messages ?? []).filter(said), human);
+  return [...(m ? [`${t.id}@${m.id}`] : []), ...requestsOf(snap, t.id).map((r) => `${t.id}@${r.id}`)];
 };
+const askKeys = (snap) => waitingThreads(snap).flatMap((t) => threadAskKeys(snap, t)).sort();
 
 // --- facts --------------------------------------------------------------------------------
 
@@ -99,6 +101,34 @@ export function planCards(snap, { now = Date.now(), sizes = {} } = {}) {
   });
 }
 
+/**
+ * One fact per track that has a card: when the human last posted anywhere in it, and which of its threads
+ * have moved since then, so a chunk's `since` can say what changed there.
+ * @param {any} snap @param {{ id: string }[]} cards @param {{ now?: number }} [opts]
+ */
+export function trackFacts(snap, cards, { now = Date.now() } = {}) {
+  const human = humanOf(snap);
+  const wanted = new Set(cards.map((c) => trackOf(snap?.threads?.[c.id])));
+  const by = new Map([...wanted].map((track) => [track, { lastHuman: 0, threads: [] }]));
+  for (const t of Object.values(snap?.threads ?? {})) {
+    const f = by.get(trackOf(t));
+    if (!f || t.archived || (t.kind && t.kind !== "thread")) continue;
+    const ms = (t.messages ?? []).filter((m) => said(m) && at(m) < now);
+    f.lastHuman = Math.max(f.lastHuman, ...ms.filter((m) => isHuman(m, human)).map(at));
+    f.threads.push({ t, ms });
+  }
+  return [...by].map(([track, f]) => {
+    const summary = snap?.tracks?.[track]?.summary?.text ?? snap?.pathSummaries?.[track]?.text;
+    const moved = f.threads.map(({ t, ms }) => ({ t, fresh: ms.filter((m) => at(m) > f.lastHuman) })).filter((x) => x.fresh.length);
+    return {
+      track,
+      summary: summary ? clip(String(summary), 1500) : null,
+      humanLastPostedHere: f.lastHuman ? ago(now - f.lastHuman) : "never",
+      movedSince: moved.map(({ t, fresh }) => ({ id: t.id, title: t.title ?? t.id, newMessages: fresh.length, latest: `[${fresh.at(-1).author}] ${clip(String(fresh.at(-1).text), 300)}` })),
+    };
+  });
+}
+
 /** What the human is like right now, as facts; `decisions` is the text of their standing decisions. */
 export function aboutHuman(snap, { now = Date.now(), decisions = "" } = {}) {
   const human = humanOf(snap);
@@ -120,6 +150,7 @@ export function aboutHuman(snap, { now = Date.now(), decisions = "" } = {}) {
     justAnswered: last ? { id: last.id, title: last.title, minutesAgo: Math.round((now - last.at) / 60_000) } : null,
     shareOfMessagesInTheSameThreadAsThePreviousOne: mine.length > 1 ? Number((same / (mine.length - 1)).toFixed(2)) : null,
     localTime: new Intl.DateTimeFormat("en-US", { timeZone: tz, weekday: "long", hour: "numeric", minute: "2-digit" }).format(now),
+    today: localDay(now, tz),
     messagesByLocalHourLast14Days: hist,
     mostRecentThreads: [...recent.values()],
     profile: snap?.dash?.about?.profile ? clip(String(snap.dash.about.profile), 3000) : null,
@@ -164,22 +195,26 @@ export function replanReason(snap, now = Date.now()) {
 
 const planned = (p) => [...p.chunks.flatMap((c) => c.rows), ...(p.later?.rows ?? [])];
 
-export function planPrompt(cards, about, { human = "me", prev = null, now = Date.now() } = {}) {
+export function planPrompt(cards, about, { human = "me", prev = null, now = Date.now(), tracks = [] } = {}) {
   const open = new Set(cards.map((c) => c.id));
   const was = prev ? [...prev.chunks.flatMap((c) => c.rows.map((r) => ({ id: r.id, chunk: c.title }))), ...(prev.later?.rows ?? []).map((r) => ({ id: r.id, chunk: "later" }))].filter((r) => open.has(r.id)) : null;
   return [
     `You are main, ${human}'s chief of staff, triaging ${human}'s open threads by hand, exactly as ${human} would if they read every one in full. The cards below are threads where a bot said something after ${human}'s last message.`,
     `For each card decide: is something actually waiting on ${human} (a question, a decision, an approval, a look, a sign-off only they can give), or not (a status report, a bot-to-bot handoff, already settled, or waiting on someone else)? Judge from the text of the ask, not from tags.`,
-    `Then order every real ask into chunks the way a careful person would work through them: what matters most and what is blocking others first; keep the same track and repo together so ${human} switches context as little as possible; weigh how taxing each one is (how much to read, diff size, how many decisions). Each card's \`context\` is its track and repo: neighbours with different contexts are a context switch. The rule: never come back to a track. All asks of one track sit next to each other in the order (chunks first, then later), in one chunk or neighbouring ones; within a track, put quick yeses first and deep reads last. The track of the thread they answered last (justAnswered) goes first, and that thread, if something waits there, is its first row: the share of their messages that stay in the previous message's thread is in the facts. A track whose asks can wait goes to "later" as a whole, not a piece of it. The thread ${human} answered last (justAnswered) is the context they already have loaded. Quick yeses that unblock bots go early; deep reads get their own chunk. Put asks that can genuinely wait into "later".`,
+    `Then order every real ask the way a careful person would work through them, as a chief of staff briefing ${human}: one chunk per track, so ${human} switches context as little as possible. Each card's \`context\` is its track and repo. Put first what matters most and what is blocking others; weigh how taxing each one is (how much to read, diff size, how many decisions). The rule: never come back to a track. All asks of one track sit in its one chunk, or all in "later"; within a track, put quick yeses first and deep reads last. The track of the thread they answered last (justAnswered) goes first, and that thread, if something waits there, is its first row: the share of their messages that stay in the previous message's thread is in the facts. A track whose asks can wait goes to "later" as a whole, not a piece of it. Quick yeses that unblock bots go early.`,
     was ? [`The previous plan, in order (move a row only when a fact changed, and say why in "moved"):`, ...was.map((r) => `- ${r.id} (${r.chunk})`)].join("\n") : "There is no previous plan: \"moved\" is empty.",
     `Facts about ${human}, including their standing decisions (what they have already settled and what they care about); now is ${new Date(now).toISOString()}:\n${JSON.stringify(about)}`,
+    `Facts about each track with an ask: its summary, when ${human} last posted anywhere in it, and the threads that moved since then:\n${JSON.stringify(tracks)}`,
     `Rules for the output:`,
     `- Row titles are plain words a person would say ("Land the hub-check segfault fix"), never leading with PR numbers or jargon, at most 60 characters.`,
-    `- Each chunk has "title" and "why": one plain sentence saying why it sits at that position.`,
+    `- Each chunk is one track (code fills in its "track" from the cards). "title" names the track's work in plain words. "why" is one plain sentence saying why it sits at that position.`,
+    `- Each chunk's "since": one plain sentence, at most 160 characters, saying what changed in that track since ${human} last posted in it (the track facts), e.g. "The reviewer passed the fix and CI went green."`,
+    `- Each row's "why": one plain sentence, at most 160 characters, saying what ${human} has to decide or do and which option the asking bot picked, e.g. "The reviewer passed it and the builder recommends landing now."`,
+    `- Each row's "park": for an ask that has waited 5 days or more (its waitingSince), a day after today (YYYY-MM-DD, today is ${about?.today ?? "in the facts"}) when it gets set aside if still unanswered, usually tomorrow; null for every other row.`,
     `- "minutes" is a whole number: an honest estimate of the effort for that row.`,
     `- "verb" is one of ${VERBS.join(", ")}.`,
     `- "consent" is true only when the ask is a pure yes/no approval with nothing to read (already reviewed, green).`,
-    `- "line" (top level) and "later.line": one short line each in main's voice, dry and cheeky on routine work, never on anything risky. You may tease the oldest waiting ask with its real age. Each is one short sentence of at most ${LINE_MAX} characters, with no semicolon and no counts. Titles and "why" are never jokes.`,
+    `- "line" (top level) says plainly what changed overall since ${human} last looked, and "later.line" says plainly why those can wait. Each is one short sentence of at most ${LINE_MAX} characters, with no semicolon and no counts.`,
     `- "moved": each row whose place changed since the previous plan, with a one-sentence reason (empty when there is no previous plan).`,
     `- Every card id appears exactly once across notAsks, chunks and later. Use only ids from the cards. No empty or placeholder entries.`,
     `"later" is null when nothing can wait.`,
@@ -189,9 +224,10 @@ export function planPrompt(cards, about, { human = "me", prev = null, now = Date
 
 /**
  * The rules a plan must meet beyond its shape (the schema checks the shape): every card once, only real ids, a
- * track's asks together, voice lines short. Throws an Error naming what is wrong; returns the plan (with the planner's `notAsks`).
+ * one chunk per track, lines short, park days after today. Throws an Error naming what is wrong; returns the plan
+ * (with the planner's `notAsks`), each chunk's `track` set from its cards.
  */
-export function checkPlan(raw, cards) {
+export function checkPlan(raw, cards, { today = null } = {}) {
   const long = [raw.line, raw.later?.line].find((l) => typeof l === "string" && l.length > LINE_MAX);
   if (long) throw new Error(`a voice line is ${long.length} characters; keep each to one sentence of at most ${LINE_MAX}`);
   const ids = new Set(cards.map((c) => c.id));
@@ -203,10 +239,17 @@ export function checkPlan(raw, cards) {
   const missing = [...ids].filter((id) => !seen.includes(id));
   if (missing.length) throw new Error(`the plan leaves out ${missing.slice(0, 5).join(", ")}`);
   const trackOfCard = new Map(cards.map((c) => [c.id, String(c.context).split(" | ")[0]]));
+  const mixed = raw.chunks.find((c) => new Set(c.rows.map((r) => trackOfCard.get(r.id))).size > 1);
+  if (mixed) throw new Error(`chunk "${mixed.title}" mixes tracks ${[...new Set(mixed.rows.map((r) => trackOfCard.get(r.id)))].join(", ")}; make one chunk per track`);
+  const chunkTracks = raw.chunks.map((c) => trackOfCard.get(c.rows[0].id));
+  const split = chunkTracks.find((t, i) => chunkTracks.indexOf(t) !== i) ?? (raw.later?.rows ?? []).map((r) => trackOfCard.get(r.id)).find((t) => chunkTracks.includes(t));
+  if (split) throw new Error(`track ${split} is split across chunks or between a chunk and "later"; put all of a track's asks in one chunk or all in "later"`);
   const visits = planned(raw).map((r) => trackOfCard.get(r.id)).filter((t, i, a) => t !== a[i - 1]);
   const back = visits.find((t, i) => visits.indexOf(t) !== i);
   if (back) throw new Error(`the plan comes back to track ${back} after another track's asks; put all of a track's asks together`);
-  return { ...raw, later: raw.later?.rows.length ? raw.later : null, moved: raw.moved.filter((m) => ids.has(m.ask)) };
+  const early = today && planned(raw).find((r) => r.park && r.park <= today);
+  if (early) throw new Error(`${early.id} parks on ${early.park}, which isn't after today (${today}); park on a later day or set park to null`);
+  return { ...raw, chunks: raw.chunks.map((c) => ({ ...c, track: trackOfCard.get(c.rows[0].id) })), later: raw.later?.rows.length ? raw.later : null, moved: raw.moved.filter((m) => ids.has(m.ask)) };
 }
 
 /**
@@ -215,27 +258,60 @@ export function checkPlan(raw, cards) {
  */
 export async function makePlan(generate, cards, about, options) {
   const prompt = planPrompt(cards, about, options);
+  const check = (raw) => checkPlan(raw, cards, { today: about?.today ?? null });
   const first = await generate(prompt);
   try {
-    return checkPlan(first, cards);
+    return check(first);
   } catch (err) {
-    return checkPlan(await generate(`${prompt}\n\nYour previous answer:\n${JSON.stringify(first)}\n\nIt breaks a rule: ${err.message}. Return the corrected full plan.`), cards);
+    return check(await generate(`${prompt}\n\nYour previous answer:\n${JSON.stringify(first)}\n\nIt breaks a rule: ${err.message}. Return the corrected full plan.`));
   }
 }
 
+/**
+ * Defers each thread of the stored plan whose park day has come and that still waits on the asks that plan saw (a new
+ * ask since then is the next plan's to judge), then stores that plan
+ * without those rows (same basis, so the defer change still makes a fresh plan). Returns the ids it parked.
+ */
+export async function parkDue(hub, snap, now = Date.now()) {
+  const prev = snap?.dash?.plan;
+  if (!prev) return [];
+  let was;
+  try { was = new Set(JSON.parse(prev.basis).asks ?? []); } catch { return []; }
+  const today = localDay(now, snap?.dash?.about?.tz);
+  const sameAsk = new Set(waitingThreads(snap).filter((t) => threadAskKeys(snap, t).every((k) => was.has(k))).map((t) => t.id));
+  const due = new Set(planned(prev).filter((r) => r.park && r.park <= today && sameAsk.has(r.id)).map((r) => r.id));
+  if (!due.size) return [];
+  await hub.dashEntries([...due].map((threadId) => ({ threadId, deferred: true })));
+  const keep = (rows) => rows.filter((r) => !due.has(r.id));
+  const laterRows = keep(prev.later?.rows ?? []);
+  await hub.dashPlan(prev.basis, {
+    line: prev.line,
+    chunks: prev.chunks.map((c) => ({ ...c, rows: keep(c.rows) })).filter((c) => c.rows.length),
+    later: laterRows.length ? { line: prev.later.line, rows: laterRows } : null,
+    moved: prev.moved.filter((m) => !due.has(m.ask)),
+  });
+  return [...due];
+}
+
 /**
  * One plan step. Returns { planned: id|null, reason }.
  * @param {any} hub @param {{ generate?: (prompt: string) => Promise<any>, decisions?: string, sizes?: any, now?: number, log?: any, snap?: any }} [opts]
  */
 export async function runPlan(hub, { generate, decisions = "", sizes = {}, now = Date.now(), log = console, snap = null } = {}) {
   if (!generate) return { planned: null, reason: "no model" };
-  const s = snap ?? (await hub.snapshot());
+  let s = snap ?? (await hub.snapshot());
+  const parked = await parkDue(hub, s, now);
+  if (parked.length) {
+    log?.log?.(`dash plan: parked ${parked.join(", ")}`);
+    s = await hub.snapshot();
+  }
   const reason = replanReason(s, now);
   if (!reason) return { planned: null, reason: "plan is current" };
   if (!waitingThreads(s).length) return { planned: null, reason: "nothing waits on the human" };
   let plan;
   try {
-    const { notAsks, ...body } = await makePlan(generate, planCards(s, { now, sizes }), aboutHuman(s, { now, decisions }), { human: humanOf(s), prev: s?.dash?.plan ?? null, now });
+    const cards = planCards(s, { now, sizes });
+    const { notAsks, ...body } = await makePlan(generate, cards, aboutHuman(s, { now, decisions }), { human: humanOf(s), prev: s?.dash?.plan ?? null, now, tracks: trackFacts(s, cards, { now }) });
     plan = body;
   } catch (err) {
     log?.warn?.(`dash plan: skipped, ${err?.message ?? err}`);

package/update.d.mts

@@ -0,0 +1,4 @@
+export type UpdateResult = { version: string; from: string | null; current: boolean; changed: string[]; deleted: string[]; left: { path: string; reason: string }[] };
+export declare function update(options?: { dir?: string; version?: string; eve?: string }): Promise<UpdateResult>;
+export declare function summary(result: UpdateResult): string;
+export declare function commitRequest(result: UpdateResult, at: { dir?: string; repo: string; branch: string; head: string }): unknown;

package/update.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// `eve-hub update`, run in a workspace checkout by its eve-hub-update workflow (hosted-hub/lib/workspace-template.mjs)
+// as `npx --yes <this version's tarball URL> update`: moves the repo to this kit. It applies kitChange (kit-change.mjs)
+// to the files on disk and pins `eve-hub` to this version's tarball, and `eve` to the hub's (`hubPins.eve`, stamped by
+// scripts/pack.mjs). Customized files stay as they are and are reported. A repo already on this version is left alone.
+// `--json` prints the result; `--summary <file>` appends what changed (summary); `--commit <file> --repo <o/n>` writes
+// the GitHub request that commits the update onto the checkout's branch (commitRequest).
+import { execFileSync } from "node:child_process";
+import { appendFileSync, readdirSync, readFileSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { kitChange, KitChangeError } from "./kit-change.mjs";
+import { kitTarballUrl, pinnedVersion } from "./kit-store.mjs";
+
+const SKIPPED = new Set([".git", "node_modules", ".eve", ".vercel", ".hub"]);
+const OWN = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "package.json"), "utf8"));
+
+function filesIn(root, dir = root) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => SKIPPED.has(e.name) ? []
+    : e.isDirectory() ? filesIn(root, join(dir, e.name))
+    : e.isFile() ? [relative(root, join(dir, e.name)).split("\\").join("/")] : []);
+}
+
+export async function update({ dir = process.cwd(), version = OWN.version, eve = OWN.hubPins?.eve } = {}) {
+  const pkgFile = join(dir, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgFile, "utf8"));
+  const pin = kitTarballUrl(version);
+  const current = pkg.dependencies?.["eve-hub"];
+  const from = pinnedVersion(current);
+  const result = { version, from: from ?? current ?? null, changed: [], deleted: [], left: [] };
+  if (current === pin) return { ...result, current: true };
+  const change = await kitChange({ paths: filesIn(dir), read: async (paths) => new Map(paths.map((p) => [p, readFileSync(join(dir, p), "utf8")])) });
+  for (const [path, text] of Object.entries(change.files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  }
+  for (const path of change.deletions) rmSync(join(dir, path), { force: true });
+  writeFileSync(pkgFile, `${JSON.stringify({ ...pkg, dependencies: { ...pkg.dependencies, "eve-hub": pin, ...(eve === undefined ? {} : { eve }) } }, null, 2)}\n`);
+  const left = change.reported.map((r) => { const i = r.indexOf(" "); return { path: r.slice(0, i), reason: r.slice(i + 1) }; });
+  return { ...result, current: false, changed: ["package.json", ...Object.keys(change.files)].sort(), deleted: change.deletions.sort(), left };
+}
+
+export function summary(r) {
+  const list = (items) => items.map((i) => `- \`${i}\``).join("\n");
+  return [
+    `Moves this workspace from eve-hub ${r.from ?? "(unpinned)"} to ${r.version}.`,
+    r.changed.length ? `\nChanged:\n${list(r.changed)}` : "",
+    r.deleted.length ? `\nDeleted:\n${list(r.deleted)}` : "",
+    r.left.length ? `\nKept as you customized them, so this release's version of them is not applied:\n${r.left.map((l) => `- \`${l.path}\` ${l.reason}`).join("\n")}` : "",
+  ].join("\n").trim() + "\n";
+}
+
+// The GraphQL `createCommitOnBranch` request that commits the update onto `branch` if it is still at `head`. GitHub creates
+// and signs that commit, so a repo whose rules require signed commits takes it; a commit made in the checkout and pushed is unsigned.
+export function commitRequest(r, { dir = process.cwd(), repo, branch, head }) {
+  return {
+    query: "mutation($input: CreateCommitOnBranchInput!) { createCommitOnBranch(input: $input) { commit { url } } }",
+    variables: { input: { branch: { repositoryNameWithOwner: repo, branchName: branch }, expectedHeadOid: head, message: { headline: `eve-hub@${r.version}`, body: summary(r) },
+      fileChanges: { additions: r.changed.map((path) => ({ path, contents: readFileSync(join(dir, path)).toString("base64") })), deletions: r.deleted.map((path) => ({ path })) } } },
+  };
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === (await import("node:fs")).realpathSync(process.argv[1])) {
+  const [command, ...args] = process.argv.slice(2);
+  const arg = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+  if (command !== "update" || (arg("--commit") !== undefined && !arg("--repo"))) { console.error("usage: eve-hub update [--json] [--summary <file>] [--commit <file> --repo <owner/name>]"); process.exit(2); }
+  try {
+    const r = await update();
+    if (arg("--summary")) appendFileSync(arg("--summary"), summary(r));
+    if (arg("--commit") && !r.current) {
+      const git = (...a) => execFileSync("git", a, { encoding: "utf8" }).trim();
+      writeFileSync(arg("--commit"), JSON.stringify(commitRequest(r, { repo: arg("--repo"), branch: git("branch", "--show-current"), head: git("rev-parse", "HEAD") })));
+    }
+    if (args.includes("--json")) console.log(JSON.stringify(r));
+    else console.log(r.current ? `already on eve-hub ${r.version}` : `eve-hub ${r.from} -> ${r.version}: ${r.changed.length + r.deleted.length} files changed, ${r.left.length} kept as customized`);
+  } catch (e) {
+    if (!(e instanceof KitChangeError)) throw e;
+    console.error(e.message);
+    process.exit(1);
+  }
+}