@saadnvd1/agent-os 0.3.853 → 0.3.859

package/lib/leads/adopt.ts

@@ -0,0 +1,150 @@
+/**
+ * Adopting an existing chat as a lead. The session keeps its id, its whole
+ * chat and its agent's conversation: it restarts on the same conversation
+ * with the lead's brief and tools, and is asked to carry what matters across
+ * (its memo, and pins proposed from the owner's own messages). Only when the
+ * owner confirms the pins, in one tap, does it switch over to a fresh start
+ * that reads the memo and the direction instead of the old conversation.
+ */
+
+import { db, type Session } from "../db";
+import { owner } from "../owner";
+import { itemsOfKind } from "../chat/store";
+import { originOf } from "../chat/origin";
+import {
+  chatStateNow,
+  freshStartChat,
+  sendChat,
+  stopChat,
+} from "../chat/runner";
+import { removeStaleSocket, waitForExit } from "../chat/worker/client";
+import { AGENTOS_SENDER } from "../orchestrator/deliver";
+import { clip } from "../orchestrator/digest";
+import { addNote } from "../orchestrator/notes";
+import { resolveProposals } from "./direction";
+import { addLeads, getLead, leadTitle, seedCharter } from "./home";
+import { latestMemo } from "./memos";
+import { isLeadKind, isStandingRole, sqlNoRole } from "./roles";
+import { TECH, type DirectionPin, type LeadKind } from "./types";
+
+// How many of the owner's last messages the handover offers as pins.
+const OFFERED = 20;
+
+const sessionRow = (id: string) =>
+  db.prepare(`SELECT * FROM session_rows WHERE id = ?`).get(id) as
+    Session | undefined;
+
+// Why this session can't become this lead, or null.
+function refusal(s: Session | undefined, kind: LeadKind): string | null {
+  if (!s) return "No such session";
+  if (kind === TECH)
+    return "The Tech lead is the workspace's orchestrator; adopt another kind";
+  if (!isLeadKind(kind)) return `"${kind}" isn't a lead's name`;
+  if (isStandingRole(s.role)) return "That session already heads something";
+  if (s.view !== "chat" || s.agent_type !== "claude")
+    return "Only a Claude chat session can be adopted as a lead";
+  if (s.task_status || s.worktree_path)
+    return "A task's session can't be a lead";
+  if (s.archived_at) return "Unarchive the session first";
+  if (s.host_id && s.host_id !== "local")
+    return "Only a session on this machine can be adopted";
+  return null;
+}
+
+function handover(sessionId: string, title: string): string {
+  const who = owner();
+  const offered = itemsOfKind(sessionId, "user")
+    .filter((i) => originOf(i) === null && i.text.trim())
+    .slice(-OFFERED)
+    .map((i) => `- [item ${i.id}] ${clip(i.text, 300)}`);
+  return [
+    `You are now this workspace's ${title}. AgentOS kept this conversation, so you still know everything in it; your brief and tools are a lead's from this message on.`,
+    `Before you switch over to a fresh start (which carries only your memo and your pinned direction, never this conversation), carry across what matters:`,
+    `1. Write your memo with update_memo: what you're working on, what's decided and why, and what's next. Keep it short (about 1.5k tokens).`,
+    `2. Propose pins with propose_pin, one call per message, for ${who}'s messages below that set standing direction (not one-off requests). ${who} confirms them with one tap; until he does, none of it is direction.`,
+    offered.length
+      ? `${who}'s recent messages in this chat:\n${offered.join("\n")}`
+      : `${who} has no messages in this chat to pin.`,
+    "Then say in a sentence or two what you saved. The switch happens when he confirms.",
+  ].join("\n\n");
+}
+
+// Stops the session's worker, if one runs, and waits for it to be gone, so
+// the next message starts one with the lead's brief and tools.
+async function restartWorker(sessionId: string): Promise<void> {
+  const state = await chatStateNow(sessionId).catch(() => null);
+  if (state === "running" || state === "waiting")
+    throw new Error("Adopt it when its current turn has ended");
+  stopChat(sessionId);
+  await waitForExit(sessionId);
+  removeStaleSocket(sessionId);
+}
+
+export async function adoptLead(input: {
+  sessionId: string;
+  workspaceId: string;
+  kind: LeadKind;
+}): Promise<Session> {
+  const { sessionId, workspaceId, kind } = input;
+  const why = refusal(sessionRow(sessionId), kind);
+  if (why) throw new Error(why);
+  if (getLead(workspaceId, kind))
+    throw new Error(
+      `This workspace already has a ${leadTitle(workspaceId, kind)}`
+    );
+  await restartWorker(sessionId);
+  addLeads(workspaceId, []);
+  seedCharter(workspaceId, kind);
+  try {
+    const changed = db
+      .prepare(
+        `UPDATE sessions SET role = ?, lead_kind = ?, lead_since = datetime('now'),
+           workspace_id = ?, pinned = 1
+         WHERE id = ? AND ${sqlNoRole()}`
+      )
+      .run("lead", kind, workspaceId, sessionId).changes;
+    if (!changed) throw new Error("That session already heads something");
+  } catch (e) {
+    // The unique (workspace, kind) index: someone adopted one just now.
+    if (getLead(workspaceId, kind)?.id !== sessionId)
+      throw new Error(
+        `This workspace already has a ${leadTitle(workspaceId, kind)}`
+      );
+    throw e;
+  }
+  const title = leadTitle(workspaceId, kind);
+  addNote(
+    workspaceId,
+    `Adopted as the ${title}. It writes its memo and proposes pins now; it switches over to a fresh start once ${owner()} confirms them.`,
+    "note",
+    kind
+  );
+  await sendChat(sessionId, {
+    text: handover(sessionId, title),
+    queue: true,
+    from: AGENTOS_SENDER,
+    origin: { kind: "system", label: "AgentOS" },
+  });
+  return sessionRow(sessionId)!;
+}
+
+// The owner's one tap: pins the proposals confirmed and drops the rest. With
+// switchOver, the lead then starts fresh on its memo and direction; an
+// adopted lead does this once, after writing its memo.
+export async function confirmPins(input: {
+  workspaceId: string;
+  kind: LeadKind;
+  confirm: number[];
+  switchOver?: boolean;
+}): Promise<{ pins: DirectionPin[]; fresh: "now" | "after-turn" | null }> {
+  const { workspaceId, kind } = input;
+  const lead = getLead(workspaceId, kind);
+  if (!lead) throw new Error("This workspace has no such lead");
+  if (input.switchOver && !latestMemo(workspaceId, kind))
+    throw new Error(
+      "It hasn't written its memo yet, so a fresh start would lose its history"
+    );
+  const pins = resolveProposals(workspaceId, kind, input.confirm);
+  const fresh = input.switchOver ? await freshStartChat(lead.id) : null;
+  return { pins, fresh };
+}

package/lib/leads/area.ts

@@ -0,0 +1,77 @@
+// Whether a lead's start or stop falls inside its area. The area is data
+// (lead_areas): the projects and boards the lead owns. A target that can't
+// be found, or sits in no project, is refused: the check fails closed.
+
+import type { Project } from "@/lib/db/types";
+import { getProject } from "../projects";
+import { findRecipe } from "../recipes/store";
+import { findWorkspaceSession } from "../orchestrator/read";
+import { workspaceProject, workspaceTask } from "../orchestrator/targets";
+import { leadAreas } from "./charters";
+import { leadTitle } from "./home";
+import type { LeadKind } from "./types";
+
+type Args = Record<string, unknown>;
+type Found = Project | null | undefined;
+const str = (v: unknown) => (typeof v === "string" ? v : "");
+
+// Each area-checked tool, and the project its call acts on.
+const TARGET: Record<string, (w: string, a: Args) => Found> = {
+  start_task: (w, a) => workspaceProject(w, str(a.project)),
+  start_session: (w, a) => workspaceProject(w, str(a.project)),
+  stack: (w, a) => workspaceProject(w, str(a.target), { boards: true }),
+  run_recipe: (w, a) => getProject(findRecipe(w, str(a.name)).project_id),
+  ...Object.fromEntries(
+    [
+      "drop",
+      "pause_task",
+      "resume_task",
+      "set_priority",
+      "approve_plan",
+      "plan_pieces",
+      "set_task_model",
+    ].map((t) => [
+      t,
+      (w: string, a: Args) =>
+        getProject(workspaceTask(w, str(a.task)).project_id ?? ""),
+    ])
+  ),
+  ...Object.fromEntries(
+    ["stop", "archive", "resurrect", "set_group"].map((t) => [
+      t,
+      (w: string, a: Args) =>
+        getProject(findWorkspaceSession(w, str(a.session)).project_id ?? ""),
+    ])
+  ),
+};
+
+export const AREA_CHECKED = Object.keys(TARGET);
+
+export function areaRefusal(
+  workspaceId: string,
+  kind: LeadKind,
+  tool: string,
+  args: unknown
+): string | null {
+  const target = TARGET[tool];
+  if (!target) return null;
+  let project: Found;
+  try {
+    project = target(workspaceId, (args ?? {}) as Args);
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+  // Not one of the workspace's projects (a session in none): not its area.
+  if (!project)
+    return `That isn't in a project of your area, so ${tool} is refused. Hand it to the Tech lead with send.`;
+  const areas = leadAreas(workspaceId, kind);
+  const owns = areas.some(
+    (a) =>
+      (a.kind === "project" && a.value === project.id) ||
+      (a.kind === "board" &&
+        (a.value === project.lh_board_id || a.value === project.lh_board_name))
+  );
+  if (owns) return null;
+  const title = leadTitle(workspaceId, kind);
+  return `"${project.name}" isn't in your area as ${title}, so ${tool} is refused there. Hand the work to the Tech lead with send, or ask the owner to add the project to your area.`;
+}

package/lib/leads/brief-common.ts

@@ -0,0 +1,122 @@
+// What every standing session's brief shares: the orchestrator's (the Tech
+// lead's) and another lead's. Owner naming, brakes, the hard lines and the
+// project list are said once here, so the two briefs can't drift apart.
+
+import { db, type Project } from "../db";
+import { getDefaultBranch } from "../git";
+import { brakesEnabled } from "../orchestrator/brakes";
+import { noApprovalsOn } from "../approvals/no-approvals";
+import { ORCHESTRATOR_SERVER } from "../orchestrator/tool-names";
+
+export const up = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
+
+const BRAKES_ON = `Starting work (\`start_task\`, \`start_session\`, \`stack\`) is braked: at most a set number of sessions running in this workspace (4 by default), at most a set number of starts an hour (6 by default), and nothing new once the account's usage window would run out before it resets, or isn't being sampled and was near its cap when last seen. Each card of a stack you start counts as a start of its own; a braked card waits in the stack. A brake refuses the start with its reason and writes one note; running work carries on. Don't retry a braked start in a loop: carry on with reviews, answers and merges, and start again when a later event gives you reason to.`;
+
+const BRAKES_OFF = (who: string) =>
+  `Starting work has no limits right now: no cap on running sessions or starts, and no usage-window check. ${up(who)}'s Pause still stops new starts; the start tools say so when it's on.`;
+
+// Read when the brief is built, so a switch flipped in Settings reaches the
+// next start.
+export const brakesText = (who: string) =>
+  brakesEnabled() ? BRAKES_ON : BRAKES_OFF(who);
+
+const NO_APPROVALS = (who: string) => `## No approvals mode is ON
+
+${up(who)} turned it on: nothing waits for him. Every \`ask_owner\` is approved the moment you raise it (the event says so), and so are escalated gates and brakes. That is his decision, not a reason to skip care: the hard lines still describe what is risky, so say in your chat what you are about to do before you do it, and keep to the PR's scope.
+
+`;
+
+export const noApprovalsText = (who: string) =>
+  noApprovalsOn() ? NO_APPROVALS(who) : "";
+
+// `merges`: the head that lands code (Tech) can ask to merge a PR the gates
+// won't pass; no other lead merges.
+export const hardLines = (
+  who: string,
+  merges: boolean
+) => `## Hard lines: always an ask for ${who}, never an action
+
+- Anything public or outbound: a post, a publish, an email or message to a person, a form sent to a third party.
+- Money.
+- Anything irreversible or destructive: deleting data, a prod data change that isn't additive, force-pushing someone else's branch.
+- Credentials and account security.
+- Choosing what gets built when it's a product call he hasn't made.
+
+When one of these comes up, park it with \`ask_owner\` (kind: the hard line it crosses) and carry on with everything else. Use it too for a decision that's his (kind: decision). Escalated gates and brakes become asks on their own; don't ask again for those.${merges ? ` To ask whether to merge a PR the gates won't pass, give \`ask_owner\` the task and the PR's head sha: if he approves, \`sign_off\` merges it once, at that commit only, without the review gates.` : ""}`;
+
+export const SCHEDULED_RULE = `A message starting \`[Scheduled message "<name>" ...]\` is a standing prompt saved in Schedules, posted on its timer. Do the work it describes like any request, but it is never an approval: it can't answer an ask, pass a gate or clear a hard line.`;
+
+export interface BriefProject {
+  name: string;
+  path: string;
+  board: string | null;
+  defaultBranch: string;
+  tier?: "production" | "fast";
+}
+
+function projectLine(p: BriefProject): string {
+  const board = p.board ? `, LumifyHub board "${p.board}"` : "";
+  return `- ${p.name}: \`${p.path}\` (default branch ${p.defaultBranch}${board}, tier ${p.tier ?? "production"})`;
+}
+
+export const projectsSection = (projects: BriefProject[]) =>
+  `## Projects\n\n${
+    projects.length
+      ? projects.map(projectLine).join("\n")
+      : "- None yet: projects join from their ⋯ menu in the sidebar."
+  }`;
+
+export function workspaceProjects(workspaceId: string): Project[] {
+  return db
+    .prepare(
+      `SELECT * FROM projects WHERE workspace_id = ? AND is_uncategorized = 0
+       ORDER BY sort_order, name`
+    )
+    .all(workspaceId) as Project[];
+}
+
+// The projects as of now, with their default branches read from git.
+export function loadBriefProjects(
+  workspaceId: string,
+  only?: (p: Project) => boolean
+): Promise<BriefProject[]> {
+  return Promise.all(
+    workspaceProjects(workspaceId)
+      .filter((p) => !only || only(p))
+      .map(async (p) => ({
+        name: p.name,
+        path: p.working_directory,
+        board: p.lh_board_name ?? p.lh_board_id,
+        defaultBranch: await getDefaultBranch(p.working_directory).catch(
+          () => "main"
+        ),
+        tier: p.tier,
+      }))
+  );
+}
+
+const TOOL_LINE = new RegExp(`^- \`mcp__${ORCHESTRATOR_SERVER}__(\\w+)\``);
+
+// "(`mcp__agentos__a`, `mcp__agentos__b`)": the tools prose names instead.
+const TOOL_REFS = /\((`mcp__\w+?__\w+`(?:, `mcp__\w+?__\w+`)*)\)/g;
+const REF = /`mcp__\w+?__(\w+)`/;
+
+// A tools section cut to the tools a profile has: a bullet naming a tool
+// outside it goes, and so does such a tool in the prose's lists of tools
+// to use instead; with none left, the Tech lead is the one to ask.
+export function keepToolLines(
+  text: string,
+  has: (tool: string) => boolean
+): string {
+  return text
+    .split("\n")
+    .filter((line) => {
+      const m = TOOL_LINE.exec(line);
+      return !m || has(m[1]);
+    })
+    .join("\n")
+    .replace(TOOL_REFS, (_, list: string) => {
+      const kept = list.split(", ").filter((ref) => has(REF.exec(ref)![1]));
+      return `(${kept.length ? kept.join(", ") : "hand it to the Tech lead with send"})`;
+    });
+}

package/lib/leads/brief.ts

@@ -0,0 +1,155 @@
+// A lead's brief: who it is (charter, area, goal), how a lead works, the
+// shared hard lines and brakes, its tools cut to its profile, and its
+// digest. The Tech lead keeps the orchestrator's brief, with a lead section
+// added once its workspace has leads.
+
+import type { Session } from "../db";
+import { getWorkspace } from "../workspaces";
+import { ownerName } from "../owner";
+import { ownerInPrompt } from "../owner-label";
+import { getProject } from "../projects";
+import { ORCHESTRATOR_SERVER } from "../orchestrator/tool-names";
+import { toolsSection } from "../orchestrator/brief";
+import {
+  brakesText,
+  hardLines,
+  keepToolLines,
+  loadBriefProjects,
+  noApprovalsText,
+  projectsSection,
+  SCHEDULED_RULE,
+  up,
+  type BriefProject,
+} from "./brief-common";
+import { getCharter, leadAreas } from "./charters";
+import { buildLeadDigest } from "./digest";
+import { leadTitle, listLeads } from "./home";
+import { profileHas, type LeadToolName, type Profile } from "./profiles";
+import { leadKindOf } from "./roles";
+import { TECH, type LeadArea, type LeadKind } from "./types";
+
+const tool = (name: LeadToolName) => `mcp__${ORCHESTRATOR_SERVER}__${name}`;
+
+const leadTools = (who: string) => `Your lead tools:
+- \`${tool("update_memo")}\` (text): rewrite your memo, the short note you carry across a fresh start. Keep it current: what you're on, what's decided, what's next.
+- \`${tool("propose_pin")}\` (item): propose one of ${who}'s own messages in this chat as pinned direction, by its chat item id. The server copies his words; it's direction once he confirms it with a tap.
+- \`${tool("direction")}\` (lead?): the pinned direction in force for you, or for another lead of this workspace, with your memo and open proposals.`;
+
+function charterSection(w: string, kind: LeadKind): string {
+  const c = getCharter(w, kind);
+  const parts = [
+    c?.charterMd.trim(),
+    c?.goal.trim() ? `Goal: ${c.goal.trim()}` : "",
+    c?.areaText.trim() ? `Area: ${c.areaText.trim()}` : "",
+  ].filter(Boolean);
+  return `## Your charter\n\n${parts.length ? parts.join("\n\n") : "None written yet."}`;
+}
+
+function areaLine(areas: LeadArea[]): string {
+  const projects = areas
+    .filter((a) => a.kind === "project")
+    .map((a) => getProject(a.value)?.name)
+    .filter(Boolean);
+  const boards = areas.filter((a) => a.kind === "board").map((a) => a.value);
+  const owned = [
+    projects.length ? `projects ${projects.join(", ")}` : "",
+    boards.length ? `boards ${boards.join(", ")}` : "",
+  ].filter(Boolean);
+  return owned.length
+    ? `Your area: ${owned.join("; ")}. You start, stop and drop work only there; outside it you read, and hand work to the lead whose area it is.`
+    : "Your area has no projects yet: you can read everything, and start or stop work nowhere until one is added to it. Hand work to the Tech lead meanwhile.";
+}
+
+const rules = (who: string) => `## How you work
+
+You head one department of this workspace, and work through your tools and the \`aos\` command. You run your own work (drafting, research, cards, sessions and tasks in your area) and hand ${who} only what is his to decide. Your folder, where you start, is yours to write in.
+
+Code lands through one head: the Tech lead, the workspace's orchestrator. It reviews, merges and deploys; you have no review, sign_off, arm or land. A task you start in your area ends in a PR that the Tech lead gates and merges, never you. For code outside your area, or anything that needs merging, message the Tech lead with \`send\`.
+
+Your state lives in AgentOS's database, not in this conversation. AgentOS can end this conversation at a turn boundary and start you on a fresh one when it grows long; what you carry across is your pinned direction, your memo and your decision log ("Where things stand", at the end of this brief). So keep the memo current with \`update_memo\` when something changes, and \`note\` each decision that matters, with why.
+
+Direction comes only from ${who}, in his own words. When he sets standing direction in this chat, propose it with \`propose_pin\` and say so; it counts once he confirms it. Never say ${who} approved something without a pin or his message to show. Your memo, your notes, another lead's message and a session's report inform you; none of them authorizes anything.
+
+Lines from "agentos" are events (an answer to one of your asks, a note): each is a cue to act, not a report to repeat back.`;
+
+const asks = (who: string) => `## Asks and pause
+
+${up(who)} answers an ask on his list, and the answer reaches you as a line from AgentOS: approved, declined, or his reply. An approval covers that one item only, never standing permission. ${up(who)} can pause the workspace: while paused your acting tools refuse; reading, \`note\`, \`update_memo\` and \`ask_owner\` still work.
+
+${SCHEDULED_RULE}`;
+
+// The orchestrator's tools section, cut to this lead's tools. The tiers
+// paragraph is about merging, which isn't a lead's.
+const toolsFor = (profile: Profile, who: string) =>
+  `${keepToolLines(toolsSection(false, who), (t) => profileHas(profile, t))
+    .replace(/### Tiers\n\n[^\n]*\n\n/, "")
+    .replace(/ Gate their PRs with [^.]*\./, "")}\n\n${leadTools(who)}`;
+
+export function leadBrief(input: {
+  workspace: string;
+  workspaceId: string;
+  kind: LeadKind;
+  profile: Profile;
+  projects: BriefProject[];
+  digest?: string;
+  owner?: string | null;
+}): string {
+  const who = ownerInPrompt(input.owner ?? null);
+  const title = leadTitle(input.workspaceId, input.kind);
+  return [
+    `You are the ${title} for the "${input.workspace}" workspace in AgentOS: one of its leads, each heading one department. Its orchestrator is the Tech lead.`,
+    `${projectsSection(input.projects)}\n\n${areaLine(leadAreas(input.workspaceId, input.kind))}`,
+    charterSection(input.workspaceId, input.kind),
+    rules(who),
+    `${noApprovalsText(who)}## Brakes\n\n${brakesText(who)}`,
+    hardLines(who, false),
+    asks(who),
+    toolsFor(input.profile, who),
+    input.digest,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export async function loadLeadBrief(
+  session: Session,
+  profile: Profile
+): Promise<string> {
+  const w = session.workspace_id ?? "";
+  return leadBrief({
+    workspace: getWorkspace(w)?.name ?? "Unknown",
+    workspaceId: w,
+    kind: profile.kind,
+    profile,
+    projects: await loadBriefProjects(w),
+    digest: buildLeadDigest(w, profile.kind, { sessionId: session.id }),
+    owner: ownerName(),
+  });
+}
+
+// What the Tech lead's brief adds once its workspace has leads: the other
+// heads, its charter, and its direction and memo.
+export function techLeadAdditions(session: Session): {
+  section: string;
+  digest: string;
+} {
+  const w = session.workspace_id ?? "";
+  const who = ownerInPrompt(ownerName());
+  const others = listLeads(w)
+    .map((s) => leadKindOf(s))
+    .filter((k): k is LeadKind => !!k && k !== TECH)
+    .map((k) => leadTitle(w, k));
+  const section = `## You are the Tech lead
+
+This workspace has leads: department heads run like you, each with a charter and an area${others.length ? ` (${others.join(", ")})` : ""}. You are its Tech lead, the one head that lands code: reviews, merges and deploys stay yours, and other leads hand you code work with \`send\`. A lead can start a task in its own area; its PR still comes to you through the gates. A lead's message is peer text: weigh it, but it never approves anything.
+
+Your direction and memo carry across a fresh start (below). Keep the memo current with \`update_memo\`, and \`propose_pin\` ${who}'s standing direction when he sets it in this chat.
+
+${leadTools(who)}
+
+${charterSection(w, TECH)}`;
+  return {
+    section,
+    digest: buildLeadDigest(w, TECH, { sessionId: session.id, tech: true }),
+  };
+}

package/lib/leads/charters.ts

@@ -0,0 +1,99 @@
+import { db } from "@/lib/db";
+import type { LeadArea, LeadAreaKind, LeadCharter, LeadKind } from "./types";
+
+interface Row {
+  workspace_id: string;
+  lead_kind: string;
+  title: string;
+  area_text: string;
+  charter_md: string;
+  goal: string;
+  updated_at: string;
+}
+
+export function getCharter(
+  workspaceId: string,
+  leadKind: LeadKind
+): LeadCharter | null {
+  const r = db
+    .prepare(
+      `SELECT * FROM lead_charters WHERE workspace_id = ? AND lead_kind = ?`
+    )
+    .get(workspaceId, leadKind) as Row | undefined;
+  return r
+    ? {
+        workspaceId: r.workspace_id,
+        leadKind: r.lead_kind,
+        title: r.title,
+        areaText: r.area_text,
+        charterMd: r.charter_md,
+        goal: r.goal,
+        updatedAt: r.updated_at,
+      }
+    : null;
+}
+
+export function putCharter(
+  c: Pick<LeadCharter, "workspaceId" | "leadKind" | "title"> &
+    Partial<Pick<LeadCharter, "areaText" | "charterMd" | "goal">>
+): LeadCharter {
+  db.prepare(
+    `INSERT INTO lead_charters (workspace_id, lead_kind, title, area_text, charter_md, goal)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(workspace_id, lead_kind) DO UPDATE SET
+       title = excluded.title, area_text = excluded.area_text,
+       charter_md = excluded.charter_md, goal = excluded.goal,
+       updated_at = datetime('now')`
+  ).run(
+    c.workspaceId,
+    c.leadKind,
+    c.title,
+    c.areaText ?? "",
+    c.charterMd ?? "",
+    c.goal ?? ""
+  );
+  return getCharter(c.workspaceId, c.leadKind)!;
+}
+
+export function leadAreas(workspaceId: string, leadKind: LeadKind): LeadArea[] {
+  return db
+    .prepare(
+      `SELECT kind, value FROM lead_areas WHERE workspace_id = ? AND lead_kind = ?
+       ORDER BY kind, value`
+    )
+    .all(workspaceId, leadKind) as LeadArea[];
+}
+
+// Replaces the lead's area in one step, so a reader never sees half of it.
+export function setLeadAreas(
+  workspaceId: string,
+  leadKind: LeadKind,
+  areas: LeadArea[]
+): void {
+  db.transaction(() => {
+    db.prepare(
+      `DELETE FROM lead_areas WHERE workspace_id = ? AND lead_kind = ?`
+    ).run(workspaceId, leadKind);
+    const insert = db.prepare(
+      `INSERT OR IGNORE INTO lead_areas (workspace_id, lead_kind, kind, value)
+       VALUES (?, ?, ?, ?)`
+    );
+    for (const a of areas) insert.run(workspaceId, leadKind, a.kind, a.value);
+  })();
+}
+
+// The leads whose area holds this value (a project id, a path, a board).
+export function leadsOwning(
+  workspaceId: string,
+  kind: LeadAreaKind,
+  value: string
+): LeadKind[] {
+  return (
+    db
+      .prepare(
+        `SELECT DISTINCT lead_kind FROM lead_areas
+         WHERE workspace_id = ? AND kind = ? AND value = ? ORDER BY lead_kind`
+      )
+      .all(workspaceId, kind, value) as { lead_kind: string }[]
+  ).map((r) => r.lead_kind);
+}

package/lib/leads/deliver.ts

@@ -0,0 +1,24 @@
+import { sendChat } from "../chat/runner";
+import { AGENTOS_SENDER } from "../orchestrator/deliver";
+import { getLead } from "./home";
+import type { LeadKind } from "./types";
+
+// A line from AgentOS to a lead other than Tech, which has no event queue
+// of its own: it arrives as the lead's next prompt, after any turn running.
+export async function tellLead(
+  workspaceId: string,
+  kind: LeadKind,
+  text: string,
+  id?: string
+): Promise<boolean> {
+  const lead = getLead(workspaceId, kind);
+  if (!lead) return false;
+  await sendChat(lead.id, {
+    text,
+    id,
+    queue: true,
+    from: AGENTOS_SENDER,
+    origin: { kind: "event", label: "AgentOS" },
+  });
+  return true;
+}