8eaebd5 · c23f731 · 0738109
@@ -0,0 +1,5 @@
# What holds a ready issue
`GET /api/v1/repos/:owner/:name/map` and the MCP `map` tool give each `ready` entry `held`: `null`, or `{ by, detail }` with `by` one of the names in `src/crew/held.ts` (`open_pull`, `hot_file`, `run_cap`, …). For `hot_file`, `detail` names the file and its count of open pulls. `startable` lists the ready numbers nothing holds.
Holds are worked out for the viewer: a pull they may not see (a sealed one) neither counts toward a hot file nor holds an issue as `open_pull`. So a guest's `startable` can list an issue the crew will not start; read it as what the viewer can see is free, not as the crew's queue. The direction issue is never in `startable` but shows `held: null`. Hot-file counts come from memory, so a cached map can lag them by up to a minute.
@@ -30,11 +30,12 @@
import type { App } from "../app.ts";
import { listCrewRoles, type Agent, type CrewRole } from "../core/agents.ts";
import { readyNow, repoGraph, type Ranked } from "../core/dependencies.ts";
import { readyNow, repoGraph, type Graph, type Ranked } from "../core/dependencies.ts";
import { alreadyDone, BY_CREW, DONE_LIKE } from "../core/done_on_main.ts";
import type { Issue } from "../core/issues.ts";
import { withPlanner } from "../core/limb_replan.ts";
import type { Repo } from "../core/repos.ts";
import { sealedRowByNumber } from "../core/sealed.ts";
import { listActive, type Run } from "../core/runs.ts";
import { getUserById } from "../core/users.ts";
import type { Stuck } from "./brief.ts";
@@ -120,15 +121,17 @@
export function heldBy(
  ready: readonly Ranked[],
  crew: readonly { agent: Agent; role: CrewRole }[],
  active: readonly Run[],
  admit: (pullNumber: number) => boolean = () => true,
): Held {
  const busyIssues = new Set(active.map((r) => r.issueId));
  const proposed = proposedWork(app.db, repo);
  // Only the pulls the viewer may see count: a sealed pull holds nothing for a guest.
  const proposed = new Map([...proposedWork(app.db, repo)].filter(([, pull]) => admit(pull.number)));
      
        sentinelcrew
        19d ago
        
      
      New behaviour with no test. Add a sealed crew pull that closes a public ready issue. A guest should get held ≠ open_pull and an admin should get open_pull. As it stands, reverting this line breaks no test.
    
  // An issue a planner or a reviewer holds is theirs, not a builder's.
  const planners = new Set(
    crew.filter((c) => c.role !== "builder").map((c) => c.agent.user.id),
  );
  const handed = withPlanner(app.db, repo);
  const hot = hotFiles(repo.id);
  const hot = hotFiles(repo.id, admit);
  const pins = new Map(heldFiles(app.db, repo.id).map((h) => [h.path, h]));
  const pinned = new Map<number, FileHold>();
  // The hold an admin set on a file the issue names, if any: the first by hold order.
@@ -211,3 +214,76 @@
export function stuckOf(held: Held): Stuck | undefined {
  );
  return issues.length === 0 ? undefined : { held: heldWords(held), issues };
}
/** What holds a ready issue, as the map's API says it. */
export interface MapHold {
  readonly by: HoldName;
  readonly detail: string;
}
      
        sentinelcrew
        19d ago
        outdated
      
      open_pull comes from proposedWork, which doesn't filter on sealed. A public ready issue that a sealed pull closes shows as held to a guest. Filter by the viewer's scope.
    
const HOLD_WORDS: Readonly<Record<HoldName, string>> = {
  running: "a run is in flight on it",
  open_pull: "an open pull already proposes it",
  planner: "the planner or a reviewer holds it",
  with_planner: "its limb waits on the planner",
  done_on_main: "found done on the base branch; waits for a person to close it",
  stalled: "a builder ran on it and left without a pull",
  run_cap: "it has used its runs for the day",
  parked_twice: "parked twice; it is the planner's",
  red_fix: "a fix for a red main covers it",
  hot_file: "a file it names is hot",
};
/**
 * The hold on each held ready issue, by number, and the numbers none holds.
 * `hot_file` names the file and its open pulls. Memory and the database only:
 * no git call. `issues` is the viewer's own ready list, so a sealed issue the
 * viewer may not see is never named.
 */
export function mapHolds(
  repo: Repo,
      
        sentinelcrew
        19d ago
        outdated
      
      High: hotFiles counts sealed pulls too (learnPullFiles reads every open pull). This count goes out to every reader of the map, guests included, so it reveals that a hidden pull touches this path. Count only the pulls the viewer's sealed scope admits.
    
  held: Held,
  admit: (pullNumber: number) => boolean = () => true,
): { holds: Map<number, MapHold>; startable: number[] } {
  const hot = hotFiles(repo.id, admit);
  const holds = new Map<number, MapHold>();
  for (const name of HOLDS) {
    for (const issue of held.by[name]) {
      let detail = HOLD_WORDS[name];
      if (name === "hot_file") {
        const pin = held.pinned.get(issue.number);
      
        sentinelcrew
        19d ago
        outdated
      
      This count is the leak in practice: an anonymous N open pulls that is larger than the open pulls the reader can see.
    
        const top = hotOverlap(issue, hot)[0];
      
        sentinelcrew
        19d ago
        
      
      No test covers the admin-pin branch. Seed one file hold on a file a ready issue names, and assert that the detail is <path> is held by an admin.
    
        if (pin !== undefined) detail = `${pin.path} is held by an admin`;
        else if (top !== undefined)
          detail = `${top.path} is in ${top.pulls} open ${top.pulls === 1 ? "pull" : "pulls"}`;
      }
      holds.set(issue.number, { by: name, detail });
    }
  }
  return { holds, startable: held.startable.map((r) => r.issue.number) };
}
/** The pulls a viewer of `scope` may see: all with the sealed scope, else the unsealed and their own. */
function admits(app: App, repo: Repo, scope: { sealed?: true; sealedBy?: string }) {
  if (scope.sealed === true) return () => true;
  return (n: number): boolean => {
    const row = sealedRowByNumber(app.db, repo.id, n);
    return row === undefined || !row.sealed || row.authorId === scope.sealedBy;
  };
}
/** The map's holds for one viewer: shared by the route and the MCP `map` tool. */
export function mapHeldFor(
  app: App,
  repo: Repo,
  graph: Graph,
  scope: { sealed?: true; sealedBy?: string },
): ReturnType<typeof mapHolds> {
  const admit = admits(app, repo, scope);
  const active = listActive(app.db, "agent").filter((r) => r.repoId === repo.id);
  return mapHolds(
    repo,
    heldBy(app, repo, readyNow(graph), listCrewRoles(app.db, repo.id), active, admit),
    admit,
  );
}
@@ -108,18 +108,24 @@
export async function learnPullFiles(app: App, repo: Repo, now: number = Date.no
}
/** Every file of `repoId` with how many open pulls touch it, narrow pulls only. */
export function pullCounts(repoId: string): Map<string, number> {
export function pullCounts(
  repoId: string,
  admit: (pullNumber: number) => boolean = () => true,
): Map<string, number> {
  const counts = new Map<string, number>();
  for (const { files } of touched.get(repoId)?.values() ?? []) {
    if (files.length > WIDE_PULL) continue;
  for (const { files, number } of touched.get(repoId)?.values() ?? []) {
    if (files.length > WIDE_PULL || !admit(number)) continue;
    for (const file of files) counts.set(file, (counts.get(file) ?? 0) + 1);
  }
  return counts;
}
/** Every file of `repo` that `HOT_PULLS` or more open pulls touch, with how many. */
export function hotFiles(repoId: string): Map<string, number> {
  const counts = pullCounts(repoId);
export function hotFiles(
  repoId: string,
  admit?: (pullNumber: number) => boolean,
): Map<string, number> {
  const counts = pullCounts(repoId, admit);
  for (const [file, n] of counts) if (n < HOT_PULLS) counts.delete(file);
  return counts;
}
@@ -350,6 +350,7 @@
import {
} from "../actions/dependencies.ts";
import { openPlan, parsePlan, proposePlan } from "../actions/plan.ts";
import { dependenciesOf, repoGraph } from "../core/dependencies.ts";
import { mapHeldFor } from "../crew/held.ts";
import { pillarView } from "../core/pillars.ts";
import { askToLiveFor } from "../web/ask_to_live.ts";
import { decisionStats, listDecisions } from "../core/decisions.ts";
@@ -3858,12 +3859,13 @@
export function apiRoutes(router: Router<Handler>): void {
        const ask = timePhase(request, "asktolive", () =>
          askToLiveFor(ctx.app, repo, pillars, ctx.auth.user),
        );
        return timePhase(request, "render", () => mapJson(repo, graph, marks, pillars, ask));
        const held = timePhase(request, "held", () => mapHeldFor(ctx.app, repo, graph, scope));
      
        sentinelcrew
        19d ago
        outdated
      
      Pass scope through here so the holds are computed for this viewer. Then put this block in a helper the MCP map tool can call as well (src/http/mcp/tools/map.ts still calls mapJson without held).
    
        return timePhase(request, "render", () => mapJson(repo, graph, marks, pillars, ask, held));
      },
    );
    // A snapshot skips the phases; they are still named, as hits at no cost.
    if (!built)
      for (const name of ["graph", "marks", "pillars", "asktolive", "render"])
      for (const name of ["graph", "marks", "pillars", "asktolive", "held", "render"])
        notePhase(request, name, 0, hit);
    return json(value);
  });
@@ -1,5 +1,6 @@
import { sealedScope } from "../../../core/sealed.ts";
import { repoGraph } from "../../../core/dependencies.ts";
import { mapHeldFor } from "../../../crew/held.ts";
import { pillarView } from "../../../core/pillars.ts";
import { askToLiveFor } from "../../../web/ask_to_live.ts";
import { listActiveRuns } from "../../../core/runs.ts";
@@ -20,9 +21,8 @@
export const tool: Tool = {
  async run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const graph = repoGraph(ctx.app.db, repo.id, {
      ...sealedScope(ctx.app.db, repo, user),
    });
    const scope = sealedScope(ctx.app.db, repo, user);
    const graph = repoGraph(ctx.app.db, repo.id, { ...scope });
    const pillars = pillarView(ctx.app.db, repo);
    return good(
      mapJson(
@@ -36,6 +36,7 @@
export const tool: Tool = {
        ),
        pillars,
        askToLiveFor(ctx.app, repo, pillars, user),
        mapHeldFor(ctx.app, repo, graph, scope),
      ),
    );
  },
@@ -19,6 +19,7 @@
 * can see, one lane each.
 */
import type { MapHold } from "../../crew/held.ts";
import { sealedScope } from "../../core/sealed.ts";
import type { Database } from "bun:sqlite";
import {
@@ -1482,6 +1483,7 @@
export function mapJson(
  marks: Marks = NO_MARKS,
  pillars?: PillarView,
  ask: readonly AskToLiveCount[] = [],
  held?: { holds: ReadonlyMap<number, MapHold>; startable: readonly number[] },
): Record<string, unknown> {
  const ready = readyNow(graph);
  const readySet = new Set(ready.map((r) => r.issue.id));
@@ -1508,7 +1510,10 @@
export function mapJson(
    ready: ready.map((r) => ({
      ...brief(r.issue),
      holdsUp: r.holdsUp,
      ...(held === undefined ? {} : { held: held.holds.get(r.issue.number) ?? null }),
    })),
    // The ready numbers no filter holds: what a builder may start now.
    ...(held === undefined ? {} : { startable: held.startable }),
    blockedOn: blockedOn(graph).map((r) => ({
      ...brief(r.issue),
      holdsUp: r.holdsUp,
@@ -52,6 +52,6 @@
test("the repository map names its phases in order, with durations", async () =>
  expect(body.ready.length).toBeGreaterThan(0);
  const parts = (res.headers.get("server-timing") ?? "").split(", ");
  const names = parts.map((p) => p.split(";")[0]!);
  expect(names.filter((n) => n !== "app")).toEqual(["session", "graph", "marks", "pillars", "asktolive", "render"]);
  expect(names.filter((n) => n !== "app")).toEqual(["session", "graph", "marks", "pillars", "asktolive", "held", "render"]);
  for (const p of parts) expect(Number(/dur=([\d.]+)/.exec(p)?.[1])).not.toBeNaN();
});
@@ -0,0 +1,160 @@
/** GET …/map names what holds each ready issue (#6441): `held`, and `startable` for the rest. */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { commitToBranch, createRepo } from "../src/actions/repos.ts";
import { openPull } from "../src/actions/pulls.ts";
import { holdFile } from "../src/crew/file_holds.ts";
import { getUserByName } from "../src/core/users.ts";
import { createIssue } from "../src/core/issues.ts";
import { HOT_PULLS, rememberPullFiles } from "../src/crew/hot_files.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { seedAdmin } from "./helpers/admin.ts";
let dataDir = "";
let app: App, servers: Servers, repoId = "", bearer = "";
const nums: Record<string, number> = {};
beforeAll(async () => {
  dataDir = await mkdtemp(join(tmpdir(), "forge-mapheld-"));
  app = createApp({ dataDir, port: 0 });
  servers = await serve(app);
  const admin = await seedAdmin(app, { username: "alice", email: "[email protected]", password: "correct-horse-battery" });
  if (!admin.ok) throw new Error(admin.error);
  const made = await createRepo(app, admin.value, { name: "notes", visibility: "public", description: "" });
  if (!made.ok) throw new Error(String(made.error));
  repoId = made.value.id;
  rememberPullFiles(
    repoId,
    Array.from({ length: HOT_PULLS }, (_, i) => ({ number: i + 1, files: ["src/hot.ts", `src/own${i}.ts`] })),
  );
  const add = (key: string, title: string, body = "", sealed = false) => {
    const r = createIssue(app.db, { repoId, authorId: admin.value.id, title, body, sealed });
    if (!r.ok) throw new Error(r.error);
    nums[key] = r.value.number;
  };
  add("hot", "Add a flag to src/hot.ts");
  add("free", "Tidy src/cold.ts");
  add("secret", "Leak in src/hot.ts", "", true);
  // A sealed pull touching the same file: only a viewer who may see it counts it.
  rememberPullFiles(repoId, [
    ...Array.from({ length: HOT_PULLS }, (_, i) => ({ number: 100 + i, files: ["src/hot.ts"] })),
    { number: nums.secret!, files: ["src/hot.ts"] },
  ]);
  const minted = await fetch(`${servers.url}/api/v1/tokens`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ adminConfirm: true, username: "alice", password: "correct-horse-battery", name: "cli", scope: "admin" }),
  });
  bearer = ((await minted.json()) as { token: string }).token;
});
afterAll(async () => {
  rememberPullFiles(repoId, []);
  servers.stop?.();
  app.close();
  await rm(dataDir, { recursive: true, force: true });
});
test("a ready issue holding a hot file says so, and startable lists only the free one", async () => {
      
        sentinelcrew
        19d ago
        outdated
      
      This passes on main as well: a sealed issue was never in an anonymous ready list. Seed a sealed pull touching src/hot.ts and assert that the guest's count leaves it out.
    
  const res = await fetch(`${servers.url}/api/v1/repos/alice/notes/map`);
  const body = (await res.json()) as {
    ready: { number: number; held: { by: string; detail: string } | null }[];
    startable: number[];
  };
  const of = (n: number) => body.ready.find((r) => r.number === n)!;
  expect(of(nums.hot!).held?.by).toBe("hot_file");
  expect(of(nums.hot!).held?.detail).toContain("src/hot.ts");
  expect(of(nums.hot!).held?.detail).toContain(`${HOT_PULLS} open pulls`);
  expect(of(nums.free!).held).toBeNull();
  expect(body.startable).toEqual([nums.free!]);
});
test("an anonymous reader is told nothing of a sealed issue", async () => {
  const res = await fetch(`${servers.url}/api/v1/repos/alice/notes/map`);
  const text = await res.text();
  expect(text).not.toContain("Leak in");
  expect(JSON.parse(text).ready.some((r: { number: number }) => r.number === nums.secret)).toBe(false);
  expect(JSON.parse(text).startable).not.toContain(nums.secret);
});
type Ready = { ready: { number: number; held: { by: string; detail: string } | null }[] };
test("a sealed pull is not counted for a guest, and is for a viewer who may see it", async () => {
  const guest = (await (await fetch(`${servers.url}/api/v1/repos/alice/notes/map`)).json()) as Ready;
  const admin = (await (
    await fetch(`${servers.url}/api/v1/repos/alice/notes/map`, { headers: { authorization: `Bearer ${bearer}` } })
  ).json()) as Ready;
  const detail = (m: Ready) => m.ready.find((r) => r.number === nums.hot!)?.held?.detail;
  expect(detail(guest)).toBe(`src/hot.ts is in ${HOT_PULLS} open pulls`);
  expect(detail(admin)).toBe(`src/hot.ts is in ${HOT_PULLS + 1} open pulls`);
});
test("the MCP map tool carries held and startable too", async () => {
  const res = await fetch(`${servers.url}/mcp`, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      accept: "application/json, text/event-stream",
      authorization: `Bearer ${bearer}`,
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: { name: "map", arguments: { app: "alice/notes" } },
    }),
  });
  const body: any = await res.json();
  const map = JSON.parse(body.result.content[0].text) as Ready & { startable: number[] };
  expect(map.ready.find((r) => r.number === nums.hot!)?.held?.by).toBe("hot_file");
  expect(map.startable).toEqual([nums.free!]);
});
test("an open pull a guest cannot see holds nothing for the guest; an admin's map says open_pull", async () => {
  const alice = getUserByName(app.db, "alice")!;
  const made = await createRepo(app, alice, { name: "pulls", visibility: "public", description: "" });
  if (!made.ok) throw new Error(String(made.error));
  const repo = made.value;
  const mk = (title: string) => {
    const r = createIssue(app.db, { repoId: repo.id, authorId: alice.id, title, body: "" });
    if (!r.ok) throw new Error(r.error);
    return r.value;
  };
  const closed = mk("Proposed by a sealed pull");
  const pinned = mk("Edit src/pinned.ts");
  const seeded = await commitToBranch(app, alice, repo, {
    message: "Start",
    files: [{ path: "README.md", content: "# pulls\n" }],
  });
  if (!seeded.ok) throw new Error(JSON.stringify(seeded.error));
  const branch = await commitToBranch(app, alice, repo, {
    branch: "feature/sealed",
    base: "main",
    message: "Fix",
    files: [{ path: "fix.ts", content: "export const n = 1;\n" }],
  });
  if (!branch.ok) throw new Error(JSON.stringify(branch.error));
  const pull = await openPull(app, alice, repo, {
    title: "Fix",
    body: `Closes #${closed.number}`,
    baseBranch: "main",
    headBranch: "feature/sealed",
  });
  if (!pull.ok) throw new Error(String(pull.error));
  // The pull is an issue row: seal it the way a security fix is.
  app.db.query("UPDATE issue SET sealed = 1 WHERE repo_id = ?1 AND number = ?2").run(repo.id, pull.value.number);
  expect(holdFile(app.db, repo.id, "src/pinned.ts", alice.id).ok).toBe(true);
  const read = async (headers: Record<string, string>) =>
    (await (await fetch(`${servers.url}/api/v1/repos/alice/pulls/map`, { headers })).json()) as Ready;
  const guest = await read({});
  const admin = await read({ authorization: `Bearer ${bearer}` });
  const held = (m: Ready, n: number) => m.ready.find((r) => r.number === n)?.held;
  expect(held(guest, closed.number)).toBeNull();
  expect(held(admin, closed.number)?.by).toBe("open_pull");
  expect(held(guest, pinned.number)?.detail).toBe("src/pinned.ts is held by an admin");
  expect(held(admin, pinned.number)?.by).toBe("hot_file");
});
		@@ -0,0 +1,5 @@
	1	# What holds a ready issue
	2
	3	`GET /api/v1/repos/:owner/:name/map` and the MCP `map` tool give each `ready` entry `held`: `null`, or `{ by, detail }` with `by` one of the names in `src/crew/held.ts` (`open_pull`, `hot_file`, `run_cap`, …). For `hot_file`, `detail` names the file and its count of open pulls. `startable` lists the ready numbers nothing holds.
	4
	5	Holds are worked out for the viewer: a pull they may not see (a sealed one) neither counts toward a hot file nor holds an issue as `open_pull`. So a guest's `startable` can list an issue the crew will not start; read it as what the viewer can see is free, not as the crew's queue. The direction issue is never in `startable` but shows `held: null`. Hot-file counts come from memory, so a cached map can lag them by up to a minute.
		@@ -30,11 +30,12 @@
30	30
31	31	import type { App } from "../app.ts";
32	32	import { listCrewRoles, type Agent, type CrewRole } from "../core/agents.ts";
33		import { readyNow, repoGraph, type Ranked } from "../core/dependencies.ts";
	33	import { readyNow, repoGraph, type Graph, type Ranked } from "../core/dependencies.ts";
34	34	import { alreadyDone, BY_CREW, DONE_LIKE } from "../core/done_on_main.ts";
35	35	import type { Issue } from "../core/issues.ts";
36	36	import { withPlanner } from "../core/limb_replan.ts";
37	37	import type { Repo } from "../core/repos.ts";
	38	import { sealedRowByNumber } from "../core/sealed.ts";
38	39	import { listActive, type Run } from "../core/runs.ts";
39	40	import { getUserById } from "../core/users.ts";
40	41	import type { Stuck } from "./brief.ts";
		@@ -120,15 +121,17 @@ export function heldBy(
120	121	ready: readonly Ranked[],
121	122	crew: readonly { agent: Agent; role: CrewRole }[],
122	123	active: readonly Run[],
	124	admit: (pullNumber: number) => boolean = () => true,
123	125	): Held {
124	126	const busyIssues = new Set(active.map((r) => r.issueId));
125		const proposed = proposedWork(app.db, repo);
	127	// Only the pulls the viewer may see count: a sealed pull holds nothing for a guest.
	128	const proposed = new Map([...proposedWork(app.db, repo)].filter(([, pull]) => admit(pull.number)));
		sentinelcrew 19d ago New behaviour with no test. Add a sealed crew pull that closes a public ready issue. A guest should get `held` ≠ `open_pull` and an admin should get `open_pull`. As it stands, reverting this line breaks no test.
126	129	// An issue a planner or a reviewer holds is theirs, not a builder's.
127	130	const planners = new Set(
128	131	crew.filter((c) => c.role !== "builder").map((c) => c.agent.user.id),
129	132	);
130	133	const handed = withPlanner(app.db, repo);
131		const hot = hotFiles(repo.id);
	134	const hot = hotFiles(repo.id, admit);
132	135	const pins = new Map(heldFiles(app.db, repo.id).map((h) => [h.path, h]));
133	136	const pinned = new Map<number, FileHold>();
134	137	// The hold an admin set on a file the issue names, if any: the first by hold order.
		@@ -211,3 +214,76 @@ export function stuckOf(held: Held): Stuck \| undefined {
211	214	);
212	215	return issues.length === 0 ? undefined : { held: heldWords(held), issues };
213	216	}
	217
	218	/** What holds a ready issue, as the map's API says it. */
	219	export interface MapHold {
	220	readonly by: HoldName;
	221	readonly detail: string;
	222	}
	223
		sentinelcrew 19d ago outdated `open_pull` comes from `proposedWork`, which doesn't filter on `sealed`. A public ready issue that a sealed pull closes shows as held to a guest. Filter by the viewer's scope.
	224	const HOLD_WORDS: Readonly<Record<HoldName, string>> = {
	225	running: "a run is in flight on it",
	226	open_pull: "an open pull already proposes it",
	227	planner: "the planner or a reviewer holds it",
	228	with_planner: "its limb waits on the planner",
	229	done_on_main: "found done on the base branch; waits for a person to close it",
	230	stalled: "a builder ran on it and left without a pull",
	231	run_cap: "it has used its runs for the day",
	232	parked_twice: "parked twice; it is the planner's",
	233	red_fix: "a fix for a red main covers it",
	234	hot_file: "a file it names is hot",
	235	};
	236
	237	/**
	238	* The hold on each held ready issue, by number, and the numbers none holds.
	239	* `hot_file` names the file and its open pulls. Memory and the database only:
	240	* no git call. `issues` is the viewer's own ready list, so a sealed issue the
	241	* viewer may not see is never named.
	242	*/
	243	export function mapHolds(
	244	repo: Repo,
		sentinelcrew 19d ago outdated High: `hotFiles` counts sealed pulls too (`learnPullFiles` reads every open pull). This count goes out to every reader of the map, guests included, so it reveals that a hidden pull touches this path. Count only the pulls the viewer's sealed scope admits.
	245	held: Held,
	246	admit: (pullNumber: number) => boolean = () => true,
	247	): { holds: Map<number, MapHold>; startable: number[] } {
	248	const hot = hotFiles(repo.id, admit);
	249	const holds = new Map<number, MapHold>();
	250	for (const name of HOLDS) {
	251	for (const issue of held.by[name]) {
	252	let detail = HOLD_WORDS[name];
	253	if (name === "hot_file") {
	254	const pin = held.pinned.get(issue.number);
		sentinelcrew 19d ago outdated This count is the leak in practice: an anonymous `N open pulls` that is larger than the open pulls the reader can see.
	255	const top = hotOverlap(issue, hot)[0];
		sentinelcrew 19d ago No test covers the admin-pin branch. Seed one file hold on a file a ready issue names, and assert that the detail is `<path> is held by an admin`.
	256	if (pin !== undefined) detail = `${pin.path} is held by an admin`;
	257	else if (top !== undefined)
	258	detail = `${top.path} is in ${top.pulls} open ${top.pulls === 1 ? "pull" : "pulls"}`;
	259	}
	260	holds.set(issue.number, { by: name, detail });
	261	}
	262	}
	263	return { holds, startable: held.startable.map((r) => r.issue.number) };
	264	}
	265
	266	/** The pulls a viewer of `scope` may see: all with the sealed scope, else the unsealed and their own. */
	267	function admits(app: App, repo: Repo, scope: { sealed?: true; sealedBy?: string }) {
	268	if (scope.sealed === true) return () => true;
	269	return (n: number): boolean => {
	270	const row = sealedRowByNumber(app.db, repo.id, n);
	271	return row === undefined \|\| !row.sealed \|\| row.authorId === scope.sealedBy;
	272	};
	273	}
	274
	275	/** The map's holds for one viewer: shared by the route and the MCP `map` tool. */
	276	export function mapHeldFor(
	277	app: App,
	278	repo: Repo,
	279	graph: Graph,
	280	scope: { sealed?: true; sealedBy?: string },
	281	): ReturnType<typeof mapHolds> {
	282	const admit = admits(app, repo, scope);
	283	const active = listActive(app.db, "agent").filter((r) => r.repoId === repo.id);
	284	return mapHolds(
	285	repo,
	286	heldBy(app, repo, readyNow(graph), listCrewRoles(app.db, repo.id), active, admit),
	287	admit,
	288	);
	289	}
		@@ -108,18 +108,24 @@ export async function learnPullFiles(app: App, repo: Repo, now: number = Date.no
108	108	}
109	109
110	110	/** Every file of `repoId` with how many open pulls touch it, narrow pulls only. */
111		export function pullCounts(repoId: string): Map<string, number> {
	111	export function pullCounts(
	112	repoId: string,
	113	admit: (pullNumber: number) => boolean = () => true,
	114	): Map<string, number> {
112	115	const counts = new Map<string, number>();
113		for (const { files } of touched.get(repoId)?.values() ?? []) {
114		if (files.length > WIDE_PULL) continue;
	116	for (const { files, number } of touched.get(repoId)?.values() ?? []) {
	117	if (files.length > WIDE_PULL \|\| !admit(number)) continue;
115	118	for (const file of files) counts.set(file, (counts.get(file) ?? 0) + 1);
116	119	}
117	120	return counts;
118	121	}
119	122
120	123	/** Every file of `repo` that `HOT_PULLS` or more open pulls touch, with how many. */
121		export function hotFiles(repoId: string): Map<string, number> {
122		const counts = pullCounts(repoId);
	124	export function hotFiles(
	125	repoId: string,
	126	admit?: (pullNumber: number) => boolean,
	127	): Map<string, number> {
	128	const counts = pullCounts(repoId, admit);
123	129	for (const [file, n] of counts) if (n < HOT_PULLS) counts.delete(file);
124	130	return counts;
125	131	}
		@@ -350,6 +350,7 @@ import {
350	350	} from "../actions/dependencies.ts";
351	351	import { openPlan, parsePlan, proposePlan } from "../actions/plan.ts";
352	352	import { dependenciesOf, repoGraph } from "../core/dependencies.ts";
	353	import { mapHeldFor } from "../crew/held.ts";
353	354	import { pillarView } from "../core/pillars.ts";
354	355	import { askToLiveFor } from "../web/ask_to_live.ts";
355	356	import { decisionStats, listDecisions } from "../core/decisions.ts";
		@@ -3858,12 +3859,13 @@ export function apiRoutes(router: Router<Handler>): void {
3858	3859	const ask = timePhase(request, "asktolive", () =>
3859	3860	askToLiveFor(ctx.app, repo, pillars, ctx.auth.user),
3860	3861	);
3861		return timePhase(request, "render", () => mapJson(repo, graph, marks, pillars, ask));
	3862	const held = timePhase(request, "held", () => mapHeldFor(ctx.app, repo, graph, scope));
		sentinelcrew 19d ago outdated Pass `scope` through here so the holds are computed for this viewer. Then put this block in a helper the MCP `map` tool can call as well (`src/http/mcp/tools/map.ts` still calls `mapJson` without `held`).
	3863	return timePhase(request, "render", () => mapJson(repo, graph, marks, pillars, ask, held));
3862	3864	},
3863	3865	);
3864	3866	// A snapshot skips the phases; they are still named, as hits at no cost.
3865	3867	if (!built)
3866		for (const name of ["graph", "marks", "pillars", "asktolive", "render"])
	3868	for (const name of ["graph", "marks", "pillars", "asktolive", "held", "render"])
3867	3869	notePhase(request, name, 0, hit);
3868	3870	return json(value);
3869	3871	});
		@@ -1,5 +1,6 @@
1	1	import { sealedScope } from "../../../core/sealed.ts";
2	2	import { repoGraph } from "../../../core/dependencies.ts";
	3	import { mapHeldFor } from "../../../crew/held.ts";
3	4	import { pillarView } from "../../../core/pillars.ts";
4	5	import { askToLiveFor } from "../../../web/ask_to_live.ts";
5	6	import { listActiveRuns } from "../../../core/runs.ts";
		@@ -20,9 +21,8 @@ export const tool: Tool = {
20	21	async run(ctx, user, args) {
21	22	const repo = planRepo(ctx, user, args);
22	23	if (isAnswer(repo)) return repo;
23		const graph = repoGraph(ctx.app.db, repo.id, {
24		...sealedScope(ctx.app.db, repo, user),
25		});
	24	const scope = sealedScope(ctx.app.db, repo, user);
	25	const graph = repoGraph(ctx.app.db, repo.id, { ...scope });
26	26	const pillars = pillarView(ctx.app.db, repo);
27	27	return good(
28	28	mapJson(
		@@ -36,6 +36,7 @@ export const tool: Tool = {
36	36	),
37	37	pillars,
38	38	askToLiveFor(ctx.app, repo, pillars, user),
	39	mapHeldFor(ctx.app, repo, graph, scope),
39	40	),
40	41	);
41	42	},
		@@ -19,6 +19,7 @@
19	19	* can see, one lane each.
20	20	*/
21	21
	22	import type { MapHold } from "../../crew/held.ts";
22	23	import { sealedScope } from "../../core/sealed.ts";
23	24	import type { Database } from "bun:sqlite";
24	25	import {
		@@ -1482,6 +1483,7 @@ export function mapJson(
1482	1483	marks: Marks = NO_MARKS,
1483	1484	pillars?: PillarView,
1484	1485	ask: readonly AskToLiveCount[] = [],
	1486	held?: { holds: ReadonlyMap<number, MapHold>; startable: readonly number[] },
1485	1487	): Record<string, unknown> {
1486	1488	const ready = readyNow(graph);
1487	1489	const readySet = new Set(ready.map((r) => r.issue.id));
		@@ -1508,7 +1510,10 @@ export function mapJson(
1508	1510	ready: ready.map((r) => ({
1509	1511	...brief(r.issue),
1510	1512	holdsUp: r.holdsUp,
	1513	...(held === undefined ? {} : { held: held.holds.get(r.issue.number) ?? null }),
1511	1514	})),
	1515	// The ready numbers no filter holds: what a builder may start now.
	1516	...(held === undefined ? {} : { startable: held.startable }),
1512	1517	blockedOn: blockedOn(graph).map((r) => ({
1513	1518	...brief(r.issue),
1514	1519	holdsUp: r.holdsUp,
		@@ -52,6 +52,6 @@ test("the repository map names its phases in order, with durations", async () =>
52	52	expect(body.ready.length).toBeGreaterThan(0);
53	53	const parts = (res.headers.get("server-timing") ?? "").split(", ");
54	54	const names = parts.map((p) => p.split(";")[0]!);
55		expect(names.filter((n) => n !== "app")).toEqual(["session", "graph", "marks", "pillars", "asktolive", "render"]);
	55	expect(names.filter((n) => n !== "app")).toEqual(["session", "graph", "marks", "pillars", "asktolive", "held", "render"]);
56	56	for (const p of parts) expect(Number(/dur=([\d.]+)/.exec(p)?.[1])).not.toBeNaN();
57	57	});
		@@ -0,0 +1,160 @@
	1	/** GET …/map names what holds each ready issue (#6441): `held`, and `startable` for the rest. */
	2	import { afterAll, beforeAll, expect, test } from "bun:test";
	3	import { mkdtemp, rm } from "node:fs/promises";
	4	import { tmpdir } from "node:os";
	5	import { join } from "node:path";
	6	import { createApp, type App } from "../src/app.ts";
	7	import { commitToBranch, createRepo } from "../src/actions/repos.ts";
	8	import { openPull } from "../src/actions/pulls.ts";
	9	import { holdFile } from "../src/crew/file_holds.ts";
	10	import { getUserByName } from "../src/core/users.ts";
	11	import { createIssue } from "../src/core/issues.ts";
	12	import { HOT_PULLS, rememberPullFiles } from "../src/crew/hot_files.ts";
	13	import { serve, type Servers } from "../src/http/server.ts";
	14	import { seedAdmin } from "./helpers/admin.ts";
	15
	16	let dataDir = "";
	17	let app: App, servers: Servers, repoId = "", bearer = "";
	18	const nums: Record<string, number> = {};
	19
	20	beforeAll(async () => {
	21	dataDir = await mkdtemp(join(tmpdir(), "forge-mapheld-"));
	22	app = createApp({ dataDir, port: 0 });
	23	servers = await serve(app);
	24	const admin = await seedAdmin(app, { username: "alice", email: "[email protected]", password: "correct-horse-battery" });
	25	if (!admin.ok) throw new Error(admin.error);
	26	const made = await createRepo(app, admin.value, { name: "notes", visibility: "public", description: "" });
	27	if (!made.ok) throw new Error(String(made.error));
	28	repoId = made.value.id;
	29	rememberPullFiles(
	30	repoId,
	31	Array.from({ length: HOT_PULLS }, (_, i) => ({ number: i + 1, files: ["src/hot.ts", `src/own${i}.ts`] })),
	32	);
	33	const add = (key: string, title: string, body = "", sealed = false) => {
	34	const r = createIssue(app.db, { repoId, authorId: admin.value.id, title, body, sealed });
	35	if (!r.ok) throw new Error(r.error);
	36	nums[key] = r.value.number;
	37	};
	38	add("hot", "Add a flag to src/hot.ts");
	39	add("free", "Tidy src/cold.ts");
	40	add("secret", "Leak in src/hot.ts", "", true);
	41	// A sealed pull touching the same file: only a viewer who may see it counts it.
	42	rememberPullFiles(repoId, [
	43	...Array.from({ length: HOT_PULLS }, (_, i) => ({ number: 100 + i, files: ["src/hot.ts"] })),
	44	{ number: nums.secret!, files: ["src/hot.ts"] },
	45	]);
	46	const minted = await fetch(`${servers.url}/api/v1/tokens`, {
	47	method: "POST",
	48	headers: { "content-type": "application/json" },
	49	body: JSON.stringify({ adminConfirm: true, username: "alice", password: "correct-horse-battery", name: "cli", scope: "admin" }),
	50	});
	51	bearer = ((await minted.json()) as { token: string }).token;
	52	});
	53
	54	afterAll(async () => {
	55	rememberPullFiles(repoId, []);
	56	servers.stop?.();
	57	app.close();
	58	await rm(dataDir, { recursive: true, force: true });
	59	});
	60
	61	test("a ready issue holding a hot file says so, and startable lists only the free one", async () => {
		sentinelcrew 19d ago outdated This passes on main as well: a sealed issue was never in an anonymous `ready` list. Seed a sealed pull touching `src/hot.ts` and assert that the guest's count leaves it out.
	62	const res = await fetch(`${servers.url}/api/v1/repos/alice/notes/map`);
	63	const body = (await res.json()) as {
	64	ready: { number: number; held: { by: string; detail: string } \| null }[];
	65	startable: number[];
	66	};
	67	const of = (n: number) => body.ready.find((r) => r.number === n)!;
	68	expect(of(nums.hot!).held?.by).toBe("hot_file");
	69	expect(of(nums.hot!).held?.detail).toContain("src/hot.ts");
	70	expect(of(nums.hot!).held?.detail).toContain(`${HOT_PULLS} open pulls`);
	71	expect(of(nums.free!).held).toBeNull();
	72	expect(body.startable).toEqual([nums.free!]);
	73	});
	74
	75	test("an anonymous reader is told nothing of a sealed issue", async () => {
	76	const res = await fetch(`${servers.url}/api/v1/repos/alice/notes/map`);
	77	const text = await res.text();
	78	expect(text).not.toContain("Leak in");
	79	expect(JSON.parse(text).ready.some((r: { number: number }) => r.number === nums.secret)).toBe(false);
	80	expect(JSON.parse(text).startable).not.toContain(nums.secret);
	81	});
	82
	83	type Ready = { ready: { number: number; held: { by: string; detail: string } \| null }[] };
	84
	85	test("a sealed pull is not counted for a guest, and is for a viewer who may see it", async () => {
	86	const guest = (await (await fetch(`${servers.url}/api/v1/repos/alice/notes/map`)).json()) as Ready;
	87	const admin = (await (
	88	await fetch(`${servers.url}/api/v1/repos/alice/notes/map`, { headers: { authorization: `Bearer ${bearer}` } })
	89	).json()) as Ready;
	90	const detail = (m: Ready) => m.ready.find((r) => r.number === nums.hot!)?.held?.detail;
	91	expect(detail(guest)).toBe(`src/hot.ts is in ${HOT_PULLS} open pulls`);
	92	expect(detail(admin)).toBe(`src/hot.ts is in ${HOT_PULLS + 1} open pulls`);
	93	});
	94
	95	test("the MCP map tool carries held and startable too", async () => {
	96	const res = await fetch(`${servers.url}/mcp`, {
	97	method: "POST",
	98	headers: {
	99	"content-type": "application/json",
	100	accept: "application/json, text/event-stream",
	101	authorization: `Bearer ${bearer}`,
	102	},
	103	body: JSON.stringify({
	104	jsonrpc: "2.0",
	105	id: 1,
	106	method: "tools/call",
	107	params: { name: "map", arguments: { app: "alice/notes" } },
	108	}),
	109	});
	110	const body: any = await res.json();
	111	const map = JSON.parse(body.result.content[0].text) as Ready & { startable: number[] };
	112	expect(map.ready.find((r) => r.number === nums.hot!)?.held?.by).toBe("hot_file");
	113	expect(map.startable).toEqual([nums.free!]);
	114	});
	115
	116	test("an open pull a guest cannot see holds nothing for the guest; an admin's map says open_pull", async () => {
	117	const alice = getUserByName(app.db, "alice")!;
	118	const made = await createRepo(app, alice, { name: "pulls", visibility: "public", description: "" });
	119	if (!made.ok) throw new Error(String(made.error));
	120	const repo = made.value;
	121	const mk = (title: string) => {
	122	const r = createIssue(app.db, { repoId: repo.id, authorId: alice.id, title, body: "" });
	123	if (!r.ok) throw new Error(r.error);
	124	return r.value;
	125	};
	126	const closed = mk("Proposed by a sealed pull");
	127	const pinned = mk("Edit src/pinned.ts");
	128	const seeded = await commitToBranch(app, alice, repo, {
	129	message: "Start",
	130	files: [{ path: "README.md", content: "# pulls\n" }],
	131	});
	132	if (!seeded.ok) throw new Error(JSON.stringify(seeded.error));
	133	const branch = await commitToBranch(app, alice, repo, {
	134	branch: "feature/sealed",
	135	base: "main",
	136	message: "Fix",
	137	files: [{ path: "fix.ts", content: "export const n = 1;\n" }],
	138	});
	139	if (!branch.ok) throw new Error(JSON.stringify(branch.error));
	140	const pull = await openPull(app, alice, repo, {
	141	title: "Fix",
	142	body: `Closes #${closed.number}`,
	143	baseBranch: "main",
	144	headBranch: "feature/sealed",
	145	});
	146	if (!pull.ok) throw new Error(String(pull.error));
	147	// The pull is an issue row: seal it the way a security fix is.
	148	app.db.query("UPDATE issue SET sealed = 1 WHERE repo_id = ?1 AND number = ?2").run(repo.id, pull.value.number);
	149	expect(holdFile(app.db, repo.id, "src/pinned.ts", alice.id).ok).toBe(true);
	150
	151	const read = async (headers: Record<string, string>) =>
	152	(await (await fetch(`${servers.url}/api/v1/repos/alice/pulls/map`, { headers })).json()) as Ready;
	153	const guest = await read({});
	154	const admin = await read({ authorization: `Bearer ${bearer}` });
	155	const held = (m: Ready, n: number) => m.ready.find((r) => r.number === n)?.held;
	156	expect(held(guest, closed.number)).toBeNull();
	157	expect(held(admin, closed.number)?.by).toBe("open_pull");
	158	expect(held(guest, pinned.number)?.detail).toBe("src/pinned.ts is held by an admin");
	159	expect(held(admin, pinned.number)?.by).toBe("hot_file");
	160	});