feat(dashboard): pool hot tickets across projects

Add buildHotTickets + an onHotTickets telefunc that pool every project's tickets/
and bucket each into a lane: in-progress (planned or spiked), next (high priority,
not started), or queued (the rest). There is no run to ticket link, so a ticket
being implemented right now is only visible through the plan/spike it left. Exported
through the package surface and the client shim; the telefunc auto-registers.

Author: suleimansh

packages/framework-dashboard/server/reads.telefunc.ts

@@ -5,6 +5,6 @@
 // Imported then exported, not re-exported (#1014): telefunc's dev transform appends
 // `__decorateTelefunction(<name>, ...)` per export, which needs a local binding. An
 // `export ... from` creates none, so `pnpm dev` died with `<name> is not defined`.
-import { onRuns, onRun, onDocs, onProjectLog, onQueue, onOverview, onRecentRuns, onInterventions, onActivity, onDashboard, onGithubUrl, onGitStatus, onProjectFiles, onProjectFileStatus, onFileDiff, onRunChanges, onFileContent, onTickets, onRetainedWorktrees, onRunWorktree, onRunHandoff, onSystemPromptUser } from '@gemstack/the-framework/dashboard-rpc'
+import { onRuns, onRun, onDocs, onProjectLog, onQueue, onOverview, onRecentRuns, onHotTickets, onInterventions, onActivity, onDashboard, onGithubUrl, onGitStatus, onProjectFiles, onProjectFileStatus, onFileDiff, onRunChanges, onFileContent, onTickets, onRetainedWorktrees, onRunWorktree, onRunHandoff, onSystemPromptUser } from '@gemstack/the-framework/dashboard-rpc'
 
-export { onRuns, onRun, onDocs, onProjectLog, onQueue, onOverview, onRecentRuns, onInterventions, onActivity, onDashboard, onGithubUrl, onGitStatus, onProjectFiles, onProjectFileStatus, onFileDiff, onRunChanges, onFileContent, onTickets, onRetainedWorktrees, onRunWorktree, onRunHandoff, onSystemPromptUser }
+export { onRuns, onRun, onDocs, onProjectLog, onQueue, onOverview, onRecentRuns, onHotTickets, onInterventions, onActivity, onDashboard, onGithubUrl, onGitStatus, onProjectFiles, onProjectFileStatus, onFileDiff, onRunChanges, onFileContent, onTickets, onRetainedWorktrees, onRunWorktree, onRunHandoff, onSystemPromptUser }

packages/the-framework/src/dashboard-rpc/index.ts

@@ -2,7 +2,7 @@
 // implementations live here in @gemstack/the-framework so `sendStart` (added with the serve
 // wiring) can reach the daemon's `startRun`; the framework-dashboard client imports
 // these through thin re-export shims so the baked RPC keys stay `/server/*.telefunc.ts`.
-export { onRuns, onRun, onDocs, onProjectLog, onQueue, onOverview, onRecentRuns, onInterventions, onActivity, onDashboard, onGithubUrl, onGitStatus, onProjectFiles, onProjectFileStatus, onFileDiff, onRunChanges, onFileContent, onTickets, onRetainedWorktrees, onRunWorktree, onRunHandoff, onSystemPromptUser } from './reads.telefunc.js'
+export { onRuns, onRun, onDocs, onProjectLog, onQueue, onOverview, onRecentRuns, onHotTickets, onInterventions, onActivity, onDashboard, onGithubUrl, onGitStatus, onProjectFiles, onProjectFileStatus, onFileDiff, onRunChanges, onFileContent, onTickets, onRetainedWorktrees, onRunWorktree, onRunHandoff, onSystemPromptUser } from './reads.telefunc.js'
 export { sendStop, sendChoice, sendMessage, sendSetHandoff, sendStart, sendPreview, onServeTargets, sendStopPreview, onPreviewStatus, sendOpenInApp, sendRemoveWorktree, sendDeleteSession, sendPushBranch, sendOpenPullRequest, sendQueueTicket, type QueueTicketResult } from './control.telefunc.js'
 export { onEvents } from './events.telefunc.js'
 export { onProjects, sendAddProject, onOnboarding } from './projects.telefunc.js'

packages/the-framework/src/dashboard-rpc/reads.telefunc.ts

@@ -5,7 +5,7 @@ import { readLogs, type LogEntry } from '../logs.js'
 import { readDocs, type WorkspaceDoc } from '../dashboard/docs.js'
 import { readTickets, type WorkspaceTicket } from '../dashboard/tickets.js'
 import { collectQueue, type ProjectQueue } from '../dashboard/queue.js'
-import { buildOverview, buildRecentRuns, type Overview, type RecentRun } from '../dashboard/overview.js'
+import { buildOverview, buildRecentRuns, buildHotTickets, type Overview, type RecentRun, type HotTicket } from '../dashboard/overview.js'
 import { buildInterventions, type Intervention } from '../dashboard/interventions.js'
 import { buildActivity, type Activity } from '../dashboard/activity.js'
 import { buildDashboard, type DashboardData } from '../dashboard/dashboard.js'
@@ -182,6 +182,11 @@ export async function onRecentRuns(): Promise<RecentRun[]> {
   return withProjects(projects => buildRecentRuns(projects))
 }
 
+/** Hot tickets across every project (#1112): being worked on, likely next, and queued. */
+export async function onHotTickets(): Promise<HotTicket[]> {
+  return withProjects(projects => buildHotTickets(projects))
+}
+
 /** The cross-project interventions queue (#632, Queue #624): open PRs that need review, newest first. */
 export async function onInterventions(): Promise<Intervention[]> {
   return withProjects(buildInterventions)

packages/the-framework/src/dashboard/index.ts

@@ -15,7 +15,7 @@ export { serveClientBundle } from './static.js'
 export { readDocs, DOC_CATEGORIES, type WorkspaceDoc } from './docs.js'
 export { readTickets, type WorkspaceTicket } from './tickets.js'
 export { collectQueue, parseTodoItems, type ProjectQueue, type QueueItem } from './queue.js'
-export { buildOverview, buildRecentRuns, type Overview, type ActiveRun, type RecentProject, type RecentRun, type OverviewDeps } from './overview.js'
+export { buildOverview, buildRecentRuns, buildHotTickets, ticketBucket, type Overview, type ActiveRun, type RecentProject, type RecentRun, type HotTicket, type HotBucket, type OverviewDeps } from './overview.js'
 export { buildDashboard, type DashboardData, type ProjectStat, type ActivityDay, type DashboardDeps } from './dashboard.js'
 export { readGitStatus, type GitStatus } from './git-status.js'
 export { ghPrView, ghPrList, ghJson, nodeGhRunner, type LinkedPr, type OpenPr, type PrLookup, type BranchPrLookup, type PrLister, type GhRunner } from './gh.js'

packages/the-framework/src/dashboard/overview.test.ts

@@ -1,8 +1,9 @@
 import { strict as assert } from 'node:assert'
 import { test } from 'node:test'
-import { buildOverview, buildRecentRuns } from './overview.js'
+import { buildOverview, buildRecentRuns, buildHotTickets, ticketBucket } from './overview.js'
 import type { ProjectSummary } from './projects.js'
 import type { ProjectQueue } from './queue.js'
+import type { WorkspaceTicket } from './tickets.js'
 import type { RunMeta } from '../store/index.js'
 
 const project = (id: string, path: string, lastActivityAt?: string): ProjectSummary => ({
@@ -91,3 +92,51 @@ test('buildRecentRuns tolerates a project whose runs cannot be read', async () =
   })
   assert.deepEqual(recent.map(r => r.run.id), ['x'])
 })
+
+const ticket = (file: string, over: Partial<WorkspaceTicket> = {}): WorkspaceTicket => ({
+  file,
+  title: file,
+  summary: '',
+  spiked: false,
+  planned: false,
+  ...over,
+})
+
+test('ticketBucket: planned/spiked is in-progress, high priority is next, else queued', () => {
+  assert.equal(ticketBucket(ticket('a', { planned: true })), 'in-progress')
+  assert.equal(ticketBucket(ticket('b', { spiked: true })), 'in-progress')
+  assert.equal(ticketBucket(ticket('c', { priority: 'high' })), 'next')
+  assert.equal(ticketBucket(ticket('d', { priority: 'p1' })), 'next')
+  assert.equal(ticketBucket(ticket('e')), 'queued')
+  assert.equal(ticketBucket(ticket('f', { priority: 'low' })), 'queued')
+  // A planned high-prio ticket is in-progress, not next: work already started outranks the flag.
+  assert.equal(ticketBucket(ticket('g', { planned: true, priority: 'high' })), 'in-progress')
+})
+
+test('buildHotTickets pools every project, buckets each, and orders lane-first', async () => {
+  const tickets: Record<string, WorkspaceTicket[]> = {
+    '/a': [ticket('a1.md', { planned: true }), ticket('a2.md', { priority: 'high' })],
+    '/b': [ticket('b1.md')],
+  }
+  const hot = await buildHotTickets([project('alpha', '/a'), project('beta', '/b')], {
+    tickets: async cwd => tickets[cwd] ?? [],
+  })
+  assert.deepEqual(
+    hot.map(h => ({ p: h.projectName, f: h.ticket.file, b: h.bucket })),
+    [
+      { p: 'alpha', f: 'a1.md', b: 'in-progress' },
+      { p: 'alpha', f: 'a2.md', b: 'next' },
+      { p: 'beta', f: 'b1.md', b: 'queued' },
+    ],
+  )
+})
+
+test('buildHotTickets tolerates a project whose tickets cannot be read', async () => {
+  const hot = await buildHotTickets([project('ok', '/ok'), project('bad', '/bad')], {
+    tickets: async cwd => {
+      if (cwd === '/bad') throw new Error('unreadable')
+      return [ticket('x.md', { priority: 'high' })]
+    },
+  })
+  assert.deepEqual(hot.map(h => h.ticket.file), ['x.md'])
+})

packages/the-framework/src/dashboard/overview.ts

@@ -1,6 +1,7 @@
 import { readAllRuns, readLiveMetas, type LiveRun, type RunMeta, type RunStatus } from '../store/index.js'
 import type { ProjectSummary } from './projects.js'
 import { collectQueue, type ProjectQueue } from './queue.js'
+import { readTickets, type WorkspaceTicket } from './tickets.js'
 
 // The first-sidebar Overview (#437, part of #314): a cross-project glance at what the agent
 // is working on right now, the size of the backlog, and the recently active projects. It
@@ -81,6 +82,60 @@ export async function buildRecentRuns(projects: ProjectSummary[], deps: RecentRu
   return all.slice(0, RECENT_RUNS_LIMIT)
 }
 
+/** Which lane of the "hot tickets" overview (#1112) a ticket sits in. */
+export type HotBucket = 'in-progress' | 'next' | 'queued'
+
+/** One ticket surfaced on the Overview's hot-tickets card, tagged with its project and lane. */
+export interface HotTicket {
+  projectId: string
+  projectName: string
+  bucket: HotBucket
+  ticket: WorkspaceTicket
+}
+
+/** Priority values that read as "do this soon" — the "likely next" lane (#1112). */
+const HIGH_PRIORITY = new Set(['high', 'urgent', 'critical', 'p0', 'p1', '0', '1'])
+
+/**
+ * A ticket's lane (#1112):
+ * - in-progress: the agent has planned or spiked it, i.e. work is under way. (There is no run↔ticket
+ *   link, so a ticket being *implemented* right now is only visible through the plan/spike it left.)
+ * - next: no plan/spike yet, but flagged high priority — likely the next thing picked up.
+ * - queued: everything else open, the backlog waiting its turn.
+ */
+export function ticketBucket(ticket: WorkspaceTicket): HotBucket {
+  if (ticket.planned || ticket.spiked) return 'in-progress'
+  if (ticket.priority && HIGH_PRIORITY.has(ticket.priority)) return 'next'
+  return 'queued'
+}
+
+/** How many hot tickets the Overview pools before the card trims per lane. */
+const HOT_TICKETS_LIMIT = 60
+
+/** Injectable reader so {@link buildHotTickets} is unit-testable off disk. */
+export interface HotTicketsDeps {
+  tickets?: (cwd: string) => Promise<WorkspaceTicket[]>
+}
+
+/**
+ * Every project's tickets pooled and bucketed for the Overview's "hot tickets" card (#1112): what
+ * is being worked on (planned/spiked), what is likely next (high priority), and the queued rest.
+ * Ordered lane-first (in-progress, then next, then queued), file order within a lane. Forgiving —
+ * a project whose tickets cannot be read simply contributes nothing.
+ */
+export async function buildHotTickets(projects: ProjectSummary[], deps: HotTicketsDeps = {}): Promise<HotTicket[]> {
+  const readT = deps.tickets ?? readTickets
+  const all: HotTicket[] = []
+  for (const project of projects) {
+    for (const ticket of await readT(project.path).catch(() => [])) {
+      all.push({ projectId: project.id, projectName: project.name, bucket: ticketBucket(ticket), ticket })
+    }
+  }
+  const lane: Record<HotBucket, number> = { 'in-progress': 0, next: 1, queued: 2 }
+  all.sort((a, b) => lane[a.bucket] - lane[b.bucket])
+  return all.slice(0, HOT_TICKETS_LIMIT)
+}
+
 /** Injectable readers so {@link buildOverview} is unit-testable off disk. */
 export interface OverviewDeps {
   liveRuns?: (cwd: string) => Promise<LiveRun[]>

packages/the-framework/src/index.ts

@@ -130,7 +130,7 @@ export {
   type SweepDeps,
   type MaintenanceFs,
 } from './maintenance.js'
-export { startDashboard, summarizeProject, defaultProjectsProvider, readDocs, type Dashboard, type DashboardOptions, type StartRunKind, type StartRunResult, type AddProjectResult, type OnboardingSuggestion, type PreviewResult, type PreviewStatus, type RunWorktree, type ProjectSummary, type ProjectsProvider, type SummarizeDeps, type WorkspaceDoc, readTickets, type WorkspaceTicket, type ProjectQueue, type QueueItem, type Overview, type ActiveRun, type RecentProject, type RecentRun, buildRecentRuns, type DashboardData, type ProjectStat, type ActivityDay, type GitStatus, type LinkedPr, type FileDiff, type FileChange, type FileContent, type RunHandoff, type HandoffCommit, type HandoffFile, type HandoffResult, buildInterventions, type Intervention, type OpenPr, type PrLister, type InterventionsDeps, buildActivity, activityKey, pickNewActivity, type Activity, type ActivityDeps } from './dashboard/index.js'
+export { startDashboard, summarizeProject, defaultProjectsProvider, readDocs, type Dashboard, type DashboardOptions, type StartRunKind, type StartRunResult, type AddProjectResult, type OnboardingSuggestion, type PreviewResult, type PreviewStatus, type RunWorktree, type ProjectSummary, type ProjectsProvider, type SummarizeDeps, type WorkspaceDoc, readTickets, type WorkspaceTicket, type ProjectQueue, type QueueItem, type Overview, type ActiveRun, type RecentProject, type RecentRun, buildRecentRuns, type HotTicket, type HotBucket, buildHotTickets, type DashboardData, type ProjectStat, type ActivityDay, type GitStatus, type LinkedPr, type FileDiff, type FileChange, type FileContent, type RunHandoff, type HandoffCommit, type HandoffFile, type HandoffResult, buildInterventions, type Intervention, type OpenPr, type PrLister, type InterventionsDeps, buildActivity, activityKey, pickNewActivity, type Activity, type ActivityDeps } from './dashboard/index.js'
 export { startPreview, detectDevScript, detectServeTargets, parsePreviewUrl, PREVIEW_SCRIPTS, type PreviewHandle, type StartPreviewOptions, type ServeTarget } from './preview.js'
 export {
   RunStore,