eve-hub 0.5.7 → 0.6.1

package/CHANGELOG.md

@@ -1,9 +1,22 @@
 # eve-hub
 
+## 0.6.1
+
+### Patch Changes
+
+- Every bot gets an execution-context prompt (`agents/<bot>/agent/instructions/execution-context.ts`), chosen by its definition in `hub.workspace.json`: `runsOn` on the agent, else a workspace-wide `"runsOn"` (a local hub's workspace declares `"local"`; a deployable repo declares `"hosted"`), else hosted. A local bot's comes from the kit's templates; the Vercel build writes a hosted bot's from what it produced: the eve-hub version, the roster and which bots run on the Mac, the deployment, team and repo commit (or that the hub uploaded the files), the kit tools it removed, and the dashboard links to its logs. The shared prompts keep only what is true in both contexts: main's restart, team, memory and Dash-schedule paragraphs, and the image and local-file link rules, moved into the per-context pages. `hub workspace sync` declares `"runsOn": "local"` in a workspace file that declares nothing.
+
+## 0.6.0
+
+### Minor Changes
+
+- A workspace repo carries its bots, memory and workspace file; the Vercel build prepares it (eve-hub/vercel), including bots that run on the Mac (`runsOn: "local"`). The Mac runner downloads the deployed commit through the hub instead of reading a folder.
+
 ## 0.5.7
 
 ### Patch Changes
 
+- One `dash` schedule (every 8 minutes, and when a bot's turn ends) replaces `dash`, `classify` and `tracks`: one GitHub query, a model call per thread whose facts changed and a model call per track with news. The `classify.ts` and `tracks.ts` stubs are retired; the track-writer bot is no longer woken.
 - `post_message` takes a reviewer's `verdict` (ship, fix-first, rethink) and `decisions`; a ship without a change-explainer for the PR shows "no explainer" on the Dash.
 
 ## 0.5.6

package/execution-context.mjs

@@ -0,0 +1,79 @@
+// A bot's execution-context prompt. A bot is defined in hub.workspace.json
+// (`runsOn` on the agent, else the file's own default, else hosted:
+// workspace.mjs agentRunsOn), and the page it gets follows from that field
+// alone: the local page from the kit's templates (every bot's
+// instructions/execution-context.ts stub calls `executionContext`), or, for a
+// bot the Vercel build deploys, a hosted page the build writes over that stub
+// (prepare.mjs), because only the build knows the deployment. The shared
+// prompts (templates/main-instructions.md, workspace-protocol.md) hold only
+// what is true in both contexts.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { templatesDir } from "./main-instructions.mjs";
+import { agentRunsOn, parseWorkspace } from "./workspace.mjs";
+
+const page = (name, options) => readFileSync(join(templatesDir(options), `execution-context-${name}.md`), "utf8").trimEnd();
+
+// The build's Vercel facts. The team and project name come from the build's
+// OIDC token (its `owner` and `project` claims); anything the build doesn't
+// carry stays undefined and the page leaves it out. A malformed token fails
+// the build.
+const claims = (jwt) => JSON.parse(Buffer.from(jwt.split(".")[1], "base64url").toString());
+
+export function deploymentFacts(env = process.env) {
+  const oidc = env.VERCEL_OIDC_TOKEN ? claims(env.VERCEL_OIDC_TOKEN) : {};
+  const repo = env.VERCEL_GIT_REPO_OWNER && env.VERCEL_GIT_REPO_SLUG ? `${env.VERCEL_GIT_REPO_OWNER}/${env.VERCEL_GIT_REPO_SLUG}` : undefined;
+  return {
+    team: oidc.owner,
+    project: oidc.project,
+    projectId: env.VERCEL_PROJECT_ID,
+    deployment: env.VERCEL_DEPLOYMENT_ID,
+    url: env.VERCEL_URL,
+    environment: env.VERCEL_ENV,
+    repo,
+    branch: env.VERCEL_GIT_COMMIT_REF,
+    sha: env.VERCEL_GIT_COMMIT_SHA,
+  };
+}
+
+const list = (items) => items.map((item) => `\`${item}\``).join(", ");
+
+export function hostedContext({ bot, roster, kit, removed, deployment: d }, options) {
+  const mac = roster.filter((agent) => agent.runsOn === "local").map((agent) => agent.name);
+  const cloud = roster.filter((agent) => agent.runsOn !== "local").map((agent) => agent.name);
+  const dashboard = d.team && d.project ? `https://vercel.com/${d.team}/${d.project}` : undefined;
+  const lines = [
+    "## Execution context",
+    `You are \`${bot}\`, an eve agent deployed on Vercel, not on a laptop: \`hub.workspace.json\` defines you as hosted.`,
+    "",
+    `- **Workspace:** ${cloud.length ? `${list(cloud)} run on Vercel` : "no bot runs on Vercel"}${mac.length ? `; ${list(mac)} run on the owner's Mac through the hub runner` : ""}. One hosted hub holds the threads and routes messages to each.`,
+    `- **Package:** your tools, hooks, channel and instructions come from the \`eve-hub\` package, version ${kit}.`,
+    `- **Deployment:** ${[
+      (d.project ?? d.projectId) && `project \`${d.project ?? d.projectId}\``,
+      d.team && `team \`${d.team}\``,
+      d.deployment && `deployment \`${d.deployment}\``,
+      d.environment && `${d.environment} environment`,
+      d.url && `at \`https://${d.url}\``,
+    ].filter(Boolean).join(", ") || "no Vercel facts were available to this build"}. Each bot is its own service at \`/eve/<name>\` in that one project.`,
+    `- **Source:** ${d.repo ? `built from \`${d.repo}\`${d.branch ? ` on \`${d.branch}\`` : ""}${d.sha ? ` at commit \`${d.sha}\`` : ""}` : "no git repository: the hub uploaded these files"}. You are made of files in it: \`agents/${bot}/\`, \`memory/\` and \`hub.workspace.json\`.`,
+    d.repo
+      ? "- **Changing it:** commit to that repository; Vercel builds and deploys the commit."
+      : "- **Changing it:** there is no repository to commit to. The hub replaces these files on its next deploy, so an edit made only in this deployment does not last.",
+    "- **Limits:** there is no `hub` CLI, you cannot restart yourself or any bot, and there are no host paths: your shell is a Vercel Sandbox with its own filesystem, not the owner's machine.",
+    `- **Kit tools this build removed:** ${removed.length ? list(removed) : "none"}. They need the hub's machine, or change the roster, which a deployment does by commit.`,
+    `- **Logs:** ${dashboard ? `[runtime logs](${dashboard}/logs)${d.deployment ? ` and [this deployment](${dashboard}/${d.deployment.replace(/^dpl_/, "")})` : ""} in the Vercel dashboard` : "the Vercel project's runtime logs in the dashboard"}.`,
+    ...(bot === "main" ? [page("hosted-main", options)] : []),
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+// What a bot's instructions/execution-context.ts stub renders. Hosted is the
+// Vercel build's to write (hostedContext), never this process's guess.
+export function executionContext(bot, workspace, options) {
+  const parsed = parseWorkspace(workspace);
+  const runsOn = agentRunsOn(parsed, bot);
+  if (runsOn !== "local") {
+    throw new Error(`${bot} is defined as hosted in hub.workspace.json, and a hosted bot's execution context is written by its Vercel build (eve-hub/vercel). A bot on this machine needs "runsOn": "local", on the agent or at the top of hub.workspace.json.`);
+  }
+  return ["## Execution context", `You are \`${bot}\`: \`hub.workspace.json\` defines you as local.`, "", page("local", options), ...(bot === "main" ? [page("local-main", options)] : [])].join("\n") + "\n";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.5.7",
+  "version": "0.6.1",
   "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",
@@ -23,13 +23,20 @@
     "./subagent-cap": "./subagent-cap.mjs",
     "./session-limits": "./session-limits.mjs",
     "./main-instructions": "./main-instructions.mjs",
+    "./execution-context": "./execution-context.mjs",
     "./connections/*": "./connections/*.js",
-    "./bot-token": "./bot-token.mjs"
+    "./bot-token": "./bot-token.mjs",
+    "./prepare": "./prepare.mjs",
+    "./vercel": "./vercel.mjs",
+    "./world": "./world.mjs"
   },
   "peerDependencies": {
     "eve": "*",
     "zod": "4.5.4",
     "@vercel/connect": "^2.4.1",
     "@vercel/oidc": "4.0.0"
+  },
+  "dependencies": {
+    "ai": "^7.0.122"
   }
 }

package/prepare.mjs

@@ -0,0 +1,219 @@
+// What a Vercel build does to a workspace checkout before eve builds its bots:
+// the deployed bots differ from the Mac's in what they run on, not in what they
+// are (vercel.mjs calls this from the repo's vercel.ts, after install and
+// before withEve assembles the services):
+// - bots marked `runsOn: "local"` are the Mac runner's: their folders and
+//   roster entries leave the hosted build, after hub.manifest.json records the
+//   whole roster for the hub;
+// - each bot runs in a Vercel Sandbox (the project's OIDC token opens it and
+//   pays for model calls) with only the kit stubs that run off the hub's
+//   machine (DEPLOYED_KIT_FILES);
+// - the kit extension, host-only workers and kit stubs are dropped, the hub's
+//   workflow world and the Vercel Kit connection are wired in, and the
+//   workspace's memory is embedded in the bots' memory providers (a function
+//   has no workspace cwd);
+// - /hub/manifest: the roster and the commit sha the deployment was built
+//   from, for the hub to sync from: a custom channel on main, routed in
+//   vercel.mjs. Bearer BOT_TOKEN, as on each bot's eve channel (bot-token.mjs).
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { KIT_FILES, MAIN_KIT_FILES } from "./stubs.mjs";
+import { deploymentFacts, hostedContext } from "./execution-context.mjs";
+import { botDomains, domainFolders, readBotMemory, readMemory, validateMemory } from "./memory.mjs";
+import { agentRunsOn, readWorkspaceFile, removeWorkspaceAgent } from "./workspace.mjs";
+
+// The kit stubs a deployed main keeps: ones whose whole import closure in the
+// published kit runs in a Vercel function and talks to the hub over HTTP alone
+// (test/workspace-template.test.mjs walks it). Every other kit stub needs the
+// hub's machine: the sandbox hook (it migrates host sessions, and deletes any
+// sandbox that resolves /workspace as itself, which a Vercel Sandbox does),
+// the kit's bash (HostSandbox's root, the daemon's env; eve's own bash runs
+// instead), the browser and the screenshot paths of attach_image/view_image,
+// the mention gate (the
+// daemon's per-process HUB_AGENT and patched model credential), the tools that
+// scaffold, remove or restart bots on the hub's disk (a deployment changes its
+// roster by commit), memory (the workspace's files), and main's schedules.
+export const DEPLOYED_KIT_FILES = new Set([
+  "channels/eve.ts",
+  "skills/change-explainer.ts",
+  ...["react", "show", "update_thread", "list_threads", "read_thread", "post_message"].map((t) => `tools/${t}.ts`),
+  ...["create_thread", "set_summary", "move_path", "archive_thread", "unarchive_thread", "list_agents", "agent_send", "tag_threads", "dash_update", "apply_tags", "artifact_publish", "artifact_status", "artifact_list"].map((t) => `tools/${t}.ts`),
+]);
+
+
+const vercelSandbox = (prepare) => `import { defineSandbox } from "eve/sandbox";
+import { VercelSandbox } from "eve/sandbox/vercel";
+${prepare ? 'import { installCodeTooling } from "eve/extensions/code/sandbox";\n' : ""}
+// TEMPORARY (until the Vercel Connect GitHub connector replaces it): the
+// project's GITHUB_TOKEN is added to GitHub requests by the sandbox firewall,
+// so the token never enters the sandbox. api.github.com (gh, REST) takes
+// Bearer; github.com (git over HTTPS) takes Basic. Unset: no policy.
+const token = process.env.GITHUB_TOKEN;
+const networkPolicy = token ? { allow: {
+  "api.github.com": [{ transform: [{ headers: { authorization: "Bearer " + token } }] }],
+  "github.com": [{ transform: [{ headers: { authorization: "Basic " + Buffer.from("x-access-token:" + token).toString("base64") } }] }],
+  "*": [],
+} } : undefined;
+
+// A Vercel Sandbox, opened with the project's OIDC token.
+export const environment = VercelSandbox.environment({ networkPolicy, prepare: async (sandbox) => {${prepare}
+  const run = async (command, what) => {
+    if ((await sandbox.run({ command })).exitCode !== 0) throw new Error(what + " failed");
+  };
+  if (!token) return;
+  // eve's sandbox image is Ubuntu with git only; gh and ssh-keygen come from apt.
+  await run("sudo apt-get update -qq && sudo apt-get install -y -qq gh openssh-client", "gh and ssh installation");
+  // gh refuses to run without a login; this one is a placeholder the firewall overwrites.
+  await run("mkdir -p ~/.config/gh && printf 'github.com:\\n  user: hub\\n  oauth_token: placeholder\\n  git_protocol: https\\n' > ~/.config/gh/hosts.yml", "gh login");
+  // The org requires signed commits. Eve reuses a named template sandbox after a failed prepare, so
+  // this step starts by clearing an earlier key. A key made here, registered as a signing key on
+  // the token's user, never leaves the sandbox; commits carry that user's noreply email.
+  await run([
+    "mkdir -p ~/.ssh && rm -f ~/.ssh/signing ~/.ssh/signing.pub && ssh-keygen -q -t ed25519 -N '' -C hub-bot -f ~/.ssh/signing",
+    "gh api user/ssh_signing_keys -f title=\\\"hub bot sandbox $(date -u +%FT%TZ)\\\" -f key=\\\"$(cat ~/.ssh/signing.pub)\\\" --silent",
+    "login=$(gh api user --jq .login) && id=$(gh api user --jq .id)",
+    "git config --global user.name \\\"$login\\\" && git config --global user.email \\\"$id+$login@users.noreply.github.com\\\"",
+    "git config --global gpg.format ssh && git config --global user.signingkey ~/.ssh/signing && git config --global commit.gpgsign true",
+  ].join(" && "), "git signing setup");
+} });
+export default defineSandbox(() => environment.open());
+`;
+
+export const VERCEL_SANDBOX = vercelSandbox("");
+
+// The builder's sandbox also carries eve-code's tooling (agents/builder/agent/extensions/code/).
+export const CODE_SANDBOX = vercelSandbox("\n  await installCodeTooling(sandbox);");
+
+// Bots that edit code: eve-code (apply_patch, grep, the review skills and its
+// read-only worker) plus eve's git extension, both with no `github` option. The
+// git extension then points the bot at `gh` and `git` in bash, whose GitHub
+// credential is the sandbox firewall's (VERCEL_SANDBOX above), and its `pr` skill
+// is the plain commit, push and draft-PR one. The worker runs on the roster's
+// subagent cap like every other subagent, not on eve's built-in default.
+export const CODE_BOTS = ["builder"];
+export const codeExtensionFiles = (bot) => ({
+  "extensions/code/extension.ts": `import code from "eve/extensions/code";
+import { bindRoster } from "eve-hub/roster-model";
+import { resolveSubagent } from "eve-hub/subagent-cap";
+import workspace from "../../../../../hub.workspace.json" with { type: "json" };
+
+const { agents, subagentCap } = bindRoster(workspace);
+const { model, reasoning } = resolveSubagent(agents, subagentCap, ${JSON.stringify(bot)}, "code__worker");
+
+export default code({ worker: { model, reasoning } });
+`,
+  "extensions/git/extension.ts": `import git from "eve/extensions/git";\n\nexport default git({});\n`,
+});
+
+const KIT_VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
+const MANIFEST_CHANNEL = `import { defineChannel, GET } from "eve/channels";
+import { isBotToken } from "eve-hub/bot-token";
+import { parseWorkspace } from "eve-hub/workspace";
+import workspace from "../../../../hub.manifest.json" with { type: "json" };
+
+// The roster and subagent cap as deployed, Mac bots included, and the eve-hub version that built it, for the hub to sync from:
+// hub.manifest.json is bundled at build, so a push whose deploy fails never
+// changes it. \`sha\` is the commit the deployment was built from, which the hub
+// syncs by; a deployment with none (\`vercel deploy\` uploads no git metadata)
+// has no manifest to give.
+const sha = process.env.VERCEL_GIT_COMMIT_SHA;
+const { agents, subagentCap } = parseWorkspace(workspace);
+const manifest = { sha, kit: ${JSON.stringify(KIT_VERSION)}, agents, subagentCap };
+
+export default defineChannel({
+  routes: [
+    GET("/hub/manifest", (request) => {
+      if (!isBotToken(request.headers.get("authorization"))) return new Response("unauthorized", { status: 401 });
+      if (!sha) return new Response("no commit sha: this deployment wasn't built from git", { status: 500 });
+      return Response.json(manifest);
+    }),
+  ],
+});
+`;
+
+export const MANIFEST_FILE = "hub.manifest.json";
+
+export function injectWorkflowWorld(agent, file) {
+  const count = agent.split("defineAgent({").length - 1;
+  if (count !== 1) throw new Error(`${file}: expected exactly one defineAgent({, found ${count}`);
+  return agent.replace("defineAgent({", `defineAgent({\n  experimental: { workflow: { world: "eve-hub/world" } },`);
+}
+
+// Removes `file` under `bot`, then any directory it leaves empty.
+function removeStub(bot, file) {
+  unlinkSync(join(bot, file));
+  for (let dir = dirname(file); dir !== "." && !readdirSync(join(bot, dir)).length; dir = dirname(dir)) rmdirSync(join(bot, dir));
+}
+
+const memoryProvider = (slot, entries, prefix, scope) => `import { defineMemory, defineMemoryProvider } from "eve/memory";
+import { memoryRecall } from "eve-hub/memory";
+const entries = ${JSON.stringify(entries)};
+const recall = ({ messages }) => ({ messages: memoryRecall(entries, messages, { prefix: ${JSON.stringify(prefix)} }) });
+export default defineMemory({ namespace: ${JSON.stringify(`hub-${slot}-memory`)}, scope: ${JSON.stringify(scope)}, provider: defineMemoryProvider({ recall: { "turn.started": recall, "compaction.completed": recall } }) });
+`;
+
+// Replaces the kit's execution-context stub (the local page) with the hosted
+// page, for a bot the definition says is hosted. Its removed-tools list is read
+// from the bot's folder as pruned.
+function writeExecutionContext(bot, { bot: name, roster, deployment }) {
+  const kitTools = Object.keys(name === "main" ? MAIN_KIT_FILES : KIT_FILES).filter((file) => file.startsWith("tools/") && file !== "tools/bash.ts").map((file) => basename(file, ".ts"));
+  const removed = kitTools.filter((tool) => !existsSync(join(bot, "tools", `${tool}.ts`)));
+  const section = hostedContext({ bot: name, roster, kit: KIT_VERSION, removed, deployment });
+  mkdirSync(join(bot, "instructions"), { recursive: true });
+  writeFileSync(join(bot, "instructions", "execution-context.ts"), `import { defineInstructions } from "eve/instructions";\n\nexport default defineInstructions({ content: ${JSON.stringify(section)} });\n`);
+}
+
+// Applies to a checkout the build owns: it deletes and rewrites files in place.
+// A tree that already has hub.manifest.json was prepared, and a second pass
+// would record the stripped roster.
+export function prepareDeployment(dir) {
+  if (existsSync(join(dir, MANIFEST_FILE))) return;
+  validateMemory(dir);
+  const definition = readWorkspaceFile(dir);
+  const resolved = { ...definition, agents: definition.agents.map((agent) => ({ ...agent, runsOn: agentRunsOn(definition, agent.name) })) };
+  writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(resolved, null, 2)}\n`);
+  for (const { name } of definition.agents) {
+    if (agentRunsOn(definition, name) !== "local") continue;
+    removeWorkspaceAgent(dir, name);
+    rmSync(join(dir, "agents", name), { recursive: true, force: true });
+  }
+  mkdirSync(join(dir, "agents", "main", "agent", "channels"), { recursive: true });
+  writeFileSync(join(dir, "agents", "main", "agent", "channels", "manifest.ts"), MANIFEST_CHANNEL);
+  for (const file of readdirSync(join(dir, "agents"), { recursive: true })) {
+    if (!file.endsWith("/agent.ts")) continue;
+    const bot = dirname(join(dir, "agents", file));
+    for (const stub of Object.keys({ ...MAIN_KIT_FILES, "memory/workspace.ts": 0, "memory/bot.ts": 0 })) if (!DEPLOYED_KIT_FILES.has(stub) && existsSync(join(bot, stub))) removeStub(bot, stub);
+    // learning-review is not in MAIN_KIT_FILES, but also requires the host.
+    if (existsSync(join(bot, "schedules/learning-review.ts"))) removeStub(bot, "schedules/learning-review.ts");
+    const name = basename(dirname(bot));
+    const code = CODE_BOTS.includes(name);
+    writeFileSync(join(bot, "sandbox.ts"), code ? CODE_SANDBOX : VERCEL_SANDBOX);
+    if (code) {
+      for (const [stub, content] of Object.entries(codeExtensionFiles(name))) {
+        mkdirSync(dirname(join(bot, stub)), { recursive: true });
+        writeFileSync(join(bot, stub), content);
+      }
+    }
+  }
+  const roster = resolved.agents;
+  const deployment = deploymentFacts();
+  for (const name of readdirSync(join(dir, "agents"))) {
+    const bot = join(dir, "agents", name, "agent");
+    writeExecutionContext(bot, { bot: name, roster, deployment });
+    // The kit's extension (kit__worker) runs host-only workers and is excluded from the kit tarball.
+    // Other extensions, such as eve-code, stay.
+    for (const item of readdirSync(bot, { recursive: true })) {
+      if (item.endsWith(join("extensions", "kit.ts"))) removeStub(bot, item);
+    }
+    const agentFile = join(bot, "agent.ts");
+    writeFileSync(agentFile, injectWorkflowWorld(readFileSync(agentFile, "utf8"), agentFile));
+    // Hosted bots reach the human's connected services (GitHub) through Vercel Kit,
+    // with the project's KIT_CONNECTOR; there is no host credential to fall back on.
+    mkdirSync(join(bot, "connections"), { recursive: true });
+    writeFileSync(join(bot, "connections", "vercel-kit.ts"), 'export { default } from "eve-hub/connections/vercel-kit";\n');
+    mkdirSync(join(bot, "memory"), { recursive: true });
+    const botDir = join(dir, "agents", name);
+    writeFileSync(join(bot, "memory", "workspace.ts"), memoryProvider("workspace", readMemory(dir, { folders: domainFolders(botDomains(dir, botDir)) }).entries, "Standing decision", "workspace"));
+    writeFileSync(join(bot, "memory", "bot.ts"), memoryProvider("bot", readBotMemory(dir, botDir).entries, "Your standing decision", name));
+  }
+}

package/schedules/dash-classify.mjs

@@ -1,14 +1,19 @@
-// main's classify schedule (schedules/classify.ts): gives
-// every idle thread a Dash entry (registry/dash.mjs: importance, delay) and
-// writes them back through POST /api/dash/entries.
+// The threads part of main's dash pass (schedules/dash-pass.mjs): gives
+// every open thread, busy or idle, a Dash entry (registry/dash.mjs: importance,
+// lane, reason) and writes them back through POST /api/dash/entries.
 //
-//   targets   open threads (not DMs, schedule threads or archived) where no
-//             bot is working, that aren't deferred, and whose basis changed
-//             since their entry was written. An unchanged hub costs nothing.
-//   classify  (target, snap) -> { threadId, importance, delay } or null, all
+//   targets   open threads (not DMs, schedule threads or archived) that aren't
+//             deferred and are due. A thread is due when its basis changed
+//             since its entry was written; a busy thread's basis ends with
+//             its facts' key (./lane-facts.mjs), which moves when it goes
+//             quiet for another pass, not while its bot keeps working. An
+//             unchanged hub costs nothing.
+//   classify  (target, snap) -> { threadId, importance, lane, reason } or null, all
 //             targets at once, each written as soon as it's decided.
 //             modelClassify: one evaluation per thread on the AI Gateway
-//             (openai/gpt-6-luna-decisions), two choice questions. Its
+//             (openai/gpt-6-luna-decisions), two choice questions: the
+//             thread's state (each state is one lane) and its importance. The
+//             reason line is quoted from facts by ./lane-facts.mjs. Its
 //             answer is the classification. No model, a failed call or an
 //             invalid answer writes nothing for that thread, so it's tried
 //             again next tick, and the pass doesn't stamp classifiedAt.
@@ -23,7 +28,8 @@
 // tests (plain node) import the same module.
 
 import { createHash } from "node:crypto";
-import { lastSaid, threadBrief, briefText } from "./thread-brief.mjs";
+import { lastSaid, said, threadBrief, briefText } from "./thread-brief.mjs";
+import { busyBasis, factsText, laneFacts, factsKey, paragraphs, reasonLine } from "./lane-facts.mjs";
 
 export { threadBrief, briefText } from "./thread-brief.mjs";
 
@@ -39,7 +45,7 @@ const working = (t) => Object.values(t?.status ?? {}).includes("working");
 // The input version (registry/dash.mjs BASIS_VERSION): bumped when what the
 // model reads changes, so every entry made from the older input is
 // classified once more, then stays quiet.
-export const BASIS_VERSION = "v:brief1";
+export const BASIS_VERSION = "v:lanes1";
 export function classifyBasis(t) {
   const st = Object.values(t?.status ?? {});
   const live = st.includes("waiting") ? "waiting" : st.includes("working") ? "working" : "idle";
@@ -67,6 +73,24 @@ export function pathQuestion(paths) {
   return { type: "choice", instructions: "Which path covers this thread's work? Paths group threads by feature or effort at any depth. A bug, polish or follow-up belongs to its area's existing path. Prefer an existing path where it fits; choose new only when none fits.", criteria };
 }
 
+// Which paragraph holds the ask the human would answer: the row quotes the one
+// the model points at, word for word, so code never guesses where it is. The
+// candidates are the paragraphs of the bot messages in the brief that @-mention
+// the human; the model is asked only when there are two or more (the API wants
+// two choices). The choices are labelled p0, p1, …: the gateway fails on
+// labels like `thr_0m7l#3`, not on how many there are.
+export function askCandidates(t, brief) {
+  const ids = new Set([...(brief?.earlier ?? []), ...(brief?.recent ?? [])].map((l) => l.id));
+  return (t?.messages ?? [])
+    .filter((m) => ids.has(m.id) && said(m) && m.authorKind !== "human" && m.author !== brief.human && ((m.mentions ?? []).includes(brief.human) || String(m.text).includes(`@${brief.human}`)))
+    .flatMap((m) => paragraphs(m.text).map((text) => ({ author: m.author, text })))
+    .map((c, i) => ({ id: `p${i}`, ...c }));
+}
+export function askQuestion(candidates) {
+  const criteria = Object.fromEntries(candidates.map((c) => [c.id, `${c.author}: ${c.text.slice(0, 160)}`]));
+  return { type: "choice", instructions: "Which of these paragraphs holds what the human is asked to answer, decide or do? Pick the paragraph a person reading the thread would point to as the ask. If none asks them anything, pick the newest.", criteria };
+}
+
 // The threads to (re)classify this pass, at most `max`: those the Dash needs
 // (no entry, or the thread moved on) first, newest change first, so the
 // thread whose turn just ended (what fired this pass) is selected under the
@@ -74,21 +98,24 @@ export function pathQuestion(paths) {
 // fresh ones instead of holding the front; later passes drain the rest. Then those
 // asked only for a path, least recently classified first, so threads still
 // waiting on main's filing take turns and never crowd out the Dash.
-export function classifyTargets(snap, { max = CLASSIFY_MAX } = {}) {
+export function classifyTargets(snap, { max = CLASSIFY_MAX, now = Date.now() } = {}) {
   const entries = snap?.dash?.entries ?? {};
   const out = [];
   const pathOnly = [];
   for (const t of Object.values(snap?.threads ?? {})) {
-    if (!open(t) || working(t)) continue;
+    if (!open(t)) continue;
     const e = entries[t.id];
     if (e?.deferred) continue;
     const last = lastSaid(t);
     if (!last) continue;
-    const basis = classifyBasis(t);
+    const facts = laneFacts(t, snap, now);
+    const base = classifyBasis(t);
+    const busy = working(t);
+    const basis = busy ? busyBasis(base, factsKey(facts)) : base;
+    const look = { due: !e || e.basis !== basis, basis };
     const path = askPath(t);
-    const due = !e || e.basis !== basis;
-    if (!due && !path) continue;
-    (due ? out : pathOnly).push({ id: t.id, title: t.title, tags: t.tags ?? {}, status: t.status ?? {}, last, brief: threadBrief(t, snap), basis, entry: e ?? null, paths: path ? pathsInProject(t, snap) : null });
+    if (!look.due && !path) continue;
+    (look.due ? out : pathOnly).push({ id: t.id, title: t.title, tags: t.tags ?? {}, status: t.status ?? {}, last, brief: threadBrief(t, snap), facts, basis: look.basis, entry: e ?? null, paths: path ? pathsInProject(t, snap) : null });
   }
   const at = (x) => String(x ?? "");
   out.sort((a, b) => at(b.last.at).localeCompare(at(a.last.at)));
@@ -102,14 +129,27 @@ export function classifyTargets(snap, { max = CLASSIFY_MAX } = {}) {
 // (eve/ai); tests pass a mock.
 export const DECISION_MODEL = "openai/gpt-6-luna-decisions";
 
+// What the thread is doing for the human, as one pick. Each state is one lane
+// (the entry's `lane`); `ready` isn't here, the hub derives it from the reviewer's
+// ship verdict on the PR's current head (entriesOf, registry/dash.mjs).
+export const STATES = {
+  "asks-you": "needs-you",
+  stuck: "running", // a stall is a bot's to steer; it shows on the thread's own row, not as the human's task
+  dropped: "needs-you",
+  running: "running",
+  settled: "fyi",
+};
+
 export const QUESTIONS = {
-  delay: {
+  state: {
     type: "choice",
-    instructions: "Who has to act next in this thread, and what does it cost the human to leave it alone right now? Read the whole brief, not just the last message: something asked of the human stays open until they settle it, and a reply from them that asks back or comments without deciding doesn't settle it.",
+    instructions: "What is this thread doing for the human right now? Read the whole brief and the live facts. Be strict: the human's attention is scarce, so a thread belongs in front of them only when something specific is theirs to do right now, and every other thread is running or settled. Read from the newest message back to the latest ask to the human; that is the only candidate. A bot that mentions the human, reports progress, says work is done or ready, or asks another bot for something is not asking the human; a request to confirm, approve or land something is.",
     criteria: {
-      blocking: "A bot can't continue until the human answers a question, makes a decision or approves something, and they haven't settled it yet.",
-      land: "The work is finished and waits on the human to try, validate, merge or sign it off, and they haven't yet.",
-      fyi: "Nothing waits on the human: whatever was asked of them is settled, or a bot acts next.",
+      "asks-you": "The thread's last substantive message to or about the human is a bot putting an explicit question, a choice between options, a decision, or a request to confirm, approve or land something to the human, including an approval they give outside the thread such as a GitHub review (a proposal the thread says waits on their confirmation counts), and it is still open: the human's reply closes it only when that reply answers or decides it (a question back keeps it open), and a later bot message closes it only when it carries on that same work or answers its own question. Bot-to-bot messages about anything else (status, cleanup, handoffs) don't close it, however many follow. If you can't point at the exact ask and the human is its only possible answerer, it's not this.",
+      stuck: "A bot's turn is live but going nowhere that more waiting won't fix: no tool activity for far longer than that kind of work normally pauses (a bot thinking or writing between calls for a few minutes is normal), the same call or file repeated over and over (once or twice is normal work), a call far longer than its kind normally takes, or a restart that left the turn silent. A CI watch, a build, a test run, subagents out or a task_wait that is long but making sense is not stuck.",
+      dropped: "No bot is working, nothing is open with the human, and work was left hanging: a bot said it would do or report something next and didn't (the turn ended without finishing what it announced), or a bot was handed work by another bot and nobody picked it up.",
+      running: "A bot's turn is live, working or waiting on something that will end by itself (CI, a build, subagents, another bot). The human has nothing to do. Never pick this when every bot is idle.",
+      settled: "Nothing specific waits on the human and nobody is working: whatever was asked of them is settled, or the work is done, reported or landed.",
     },
   },
   importance: {
@@ -131,31 +171,35 @@ export function threadState(t, snap) {
   return [
     `A chat thread between a human (${brief.human}) and AI bots that work for them. A message addresses whoever it @-mentions; a bot addressing another bot asks nothing of ${brief.human}.`,
     `Bot status now: ${status}`,
+    ...(t.facts ? [`Live facts:`, factsText(t.facts)] : []),
     briefText(brief),
   ].join("\n");
 }
 
-// One evaluation; returns { delay, importance } when both answers are valid
+// One evaluation; returns { state, importance } when both answers are valid
 // choices, else null, plus `path` (a path id or `new`) for an unfiled
 // thread: `new` without a call when the project has no open paths, and left
 // out when that answer alone is invalid. Throws when the call fails.
 export async function decideThread(t, snap, { evaluate, model = DECISION_MODEL, timeoutMs = 20000 }) {
   const uq = t.paths ? pathQuestion(t.paths) : null;
-  const questions = uq ? { ...QUESTIONS, path: uq } : QUESTIONS;
+  const asks = askCandidates(snap?.threads?.[t.id], t.brief ?? threadBrief(t, snap));
+  const questions = { ...QUESTIONS, ...(asks.length > 1 ? { ask: askQuestion(asks) } : {}), ...(uq ? { path: uq } : {}) };
   const r = await evaluate({ model, state: threadState(t, snap), questions, maxRetries: 1, abortSignal: AbortSignal.timeout(timeoutMs) });
   const out = {};
   for (const [name, q] of Object.entries(questions)) {
     const a = r?.answers?.[name];
     const ok = a?.type === "choice" && Object.hasOwn(q.criteria, a.choice);
     if (ok) out[name] = a.choice;
-    else if (name !== "path") return null;
+    else if (name !== "path" && name !== "ask") return null;
   }
   if (t.paths && !uq) out.path = NEW_PATH;
+  if (asks.length === 1) out.ask = asks[0].text;
+  else if (out.ask) out.ask = asks.find((c) => c.id === out.ask).text;
   return out;
 }
 
 // The schedule's classifier, one thread: the model's answer as is
-// ({ threadId, importance, delay, path? }), or null when there's no
+// ({ threadId, importance, lane, reason, path? }), or null when there's no
 // `evaluate`, the call failed or the answer is invalid (no entry for it).
 /** @param {{ evaluate?: (options: any) => Promise<any>, log?: any, model?: string, timeoutMs?: number }} [options] */
 export function modelClassify({ evaluate, log = console, ...opts } = {}) {
@@ -163,7 +207,9 @@ export function modelClassify({ evaluate, log = console, ...opts } = {}) {
     if (!evaluate) return null;
     const a = await decideThread(t, snap, { evaluate, ...opts }).catch((err) => (log?.warn?.(`dash: decide ${t.id} failed, skipped: ${err?.message ?? err}`), undefined));
     if (a === null) log?.warn?.(`dash: decide ${t.id}: invalid answer, skipped`);
-    return a ? { threadId: t.id, ...a } : null;
+    if (!a) return null;
+    const { state, ask, ...rest } = a;
+    return { threadId: t.id, ...rest, lane: STATES[state], reason: reasonLine(state, t.brief, t.facts, ask) };
   };
 }
 
@@ -198,22 +244,22 @@ export function newPathNotice(threads, snap) {
   ].join("\n");
 }
 
-// The "asks you" notice: a thread whose verdict changed to waiting on the
-// human (blocking: their decision; land: their sign-off), or from that to
-// not. The model's verdict on the brief decides; nothing here reads the
-// messages. (A pending request is posted by the rule scan, dash-rules.mjs.)
-const WAITS = { blocking: "waiting on your decision", land: "waiting on your sign-off" };
+// The "asks you" notice: a thread whose lane changed to needs-you (its reason
+// says why), or from needs-you or ready (waiting on the human's sign-off) to
+// anything else. The model's pick decides; nothing here reads the messages. (A
+// pending request is posted by the rule scan, dash-rules.mjs.)
+const asking = (lane) => lane === "needs-you" || lane === "ready";
 // The notice for `e`, the new entry of target `t`, or null: committed with
 // it in one write (hub.dashEntries), so a verdict and its notice are kept
 // together or not at all, and a failed write is judged afresh next pass
 // against the entry as it still is.
 export function asksNotice(e, t) {
-  const was = t.entry?.delay;
-  if (was === e.delay) return null;
+  const was = t.entry?.lane;
+  if (was === e.lane || (asking(was) && asking(e.lane))) return null;
   const link = `[${String(t.title ?? t.id).replace(/[[\]]/g, "")}](${t.id})`;
-  const line = WAITS[e.delay] ? `asks you: ${link}, ${WAITS[e.delay]}` : WAITS[was] ? `no longer asking you: ${link}` : null;
+  const line = asking(e.lane) ? `needs you: ${link}, ${e.reason}` : asking(was) ? `no longer asking you: ${link}` : null;
   if (!line) return null;
-  const key = `asks-${createHash("sha256").update(`${e.threadId}:${e.delay}:${e.basis}`).digest("hex").slice(0, 32)}`;
+  const key = `asks-${createHash("sha256").update(`${e.threadId}:${e.lane}:${e.basis}`).digest("hex").slice(0, 32)}`;
   return { schedule: "dash", text: `@main dash: ${line}`, clientId: key };
 }
 
@@ -247,7 +293,8 @@ async function noticeNewPaths(hub, fresh, log) {
 // thread whose turn just ended shows within its own call. Path picks are
 // filed after the pass (`filing`, see filePaths), outside it. Each entry
 // carries the basis its target was classified from, so a thread that moved
-// on meanwhile is looked at again next pass, and clears any old reason line.
+// on meanwhile is looked at again next pass. The entry's reason is the lane's
+// one-line why, replaced with every classification.
 // Importance a human set (entry.importanceBy) is never sent. classifiedAt is
 // stamped when there was nothing to do or every target was written; a
 // skipped target or a failed write leaves it, so "never classified" and
@@ -265,7 +312,7 @@ export async function runClassify(hub, { classify = async () => null, max = CLAS
     if (!d) return 0;
     if (d.path) picks.push([t, d.path]);
     const own = humans.has(t.entry?.importanceBy);
-    const entry = { threadId: t.id, ...(own || d.importance === undefined ? {} : { importance: d.importance }), delay: d.delay, reason: null, basis: t.basis };
+    const entry = { threadId: t.id, ...(own || d.importance === undefined ? {} : { importance: d.importance }), lane: d.lane, reason: d.reason, basis: t.basis };
     const notice = asksNotice(entry, t);
     try {
       await (notice ? hub.dashEntries([entry], [], notice) : hub.dashEntries([entry]));