@openagt/dashboard 0.25.0 → 0.26.0

package/dist/module-types/dashboard/components/ui/switch.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentProps } from 'react';
-import { Switch as SwitchPrimitive } from '@base-ui-components/react/switch';
+import { Switch as SwitchPrimitive } from '@base-ui/react/switch';
 type SwitchProps = Omit<ComponentProps<typeof SwitchPrimitive.Root>, 'disabled'> & {
     disabled?: boolean | undefined;
 };

package/dist/module-types/dashboard/components/ui/tooltip.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentProps } from 'react';
-import { Tooltip as TooltipPrimitive } from '@base-ui-components/react/tooltip';
-declare const TooltipProvider: import("react").FC<import("@base-ui-components/react/tooltip").TooltipProviderProps>;
-declare const Tooltip: typeof TooltipPrimitive.Root;
+import { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip';
+declare const TooltipProvider: import("react").FC<import("@base-ui/react").TooltipProviderProps>;
+declare const Tooltip: <Payload>(props: TooltipPrimitive.Root.Props<Payload>) => React.JSX.Element;
 declare function TooltipTrigger(props: ComponentProps<typeof TooltipPrimitive.Trigger>): import("react").JSX.Element;
 declare function TooltipContent({ className, sideOffset, side, align, children, ...props }: ComponentProps<typeof TooltipPrimitive.Popup> & {
     sideOffset?: number;

package/dist/module-types/dashboard/lib/data-link.d.ts

@@ -1,4 +1,4 @@
-import { type Route } from './route.js';
+import type { Route } from './route.js';
 /** A repository path's page segment and the rest: `tickets/a.md` → `{ segment: 'tickets', rest: ['a.md'] }`; nothing for a path with no page-shaped first segment or no rest. */
 export declare function dataLinkParts(href: string): {
     segment: string;

package/dist/module-types/dashboard/lib/route.d.ts

@@ -1,27 +1,4 @@
-/**
- * Whether a segment can name a page a module adds (#1774): a lowercase letter, then lowercase
- * letters and digits, and not a word the dashboard keeps. Whichever module claims the segment gets
- * it, and the shell says "no such page" when none does, or when the picked project has no package
- * that adds it.
- */
-export declare function isPageSegment(segment: string): boolean;
-/** Each registered project's address, and the project an address or an id names. */
-export interface ProjectAddresses {
-    /** The project's address: its name, or its id where the name cannot be one. An unknown id is its own address. */
-    addressOf(projectId: string): string;
-    /** The project a first segment names, by its address or by its id; undefined for none. */
-    projectOf(segment: string): string | undefined;
-}
-/**
- * The addresses of the registered projects, in the registry's order, beside the pages' words.
- * A project's name is its id without the `-<hash>`: its folder's name, as the id writes it. The
- * name is its address unless a page has that word, since pages win, or a project before it in the
- * registry already has that name: the first one added keeps it, so adding a second clone changes
- * no address in use.
- */
-export declare function projectAddresses(projectIds: readonly string[], pageWords: readonly string[]): ProjectAddresses;
-/** No project registered: every first segment is a page's, or a project's nobody registered. */
-export declare const NO_PROJECTS: ProjectAddresses;
+import { type ProjectAddresses } from '../../src/project-address.js';
 /** What the dashboard is looking at, as carried by the URL. */
 export interface Route {
     /**

package/dist/module-types/src/bridge-browser.d.ts

@@ -168,6 +168,8 @@ export interface BridgeBrowserOptions {
     extension?: BridgeExtensionSource | undefined;
     /** Progress, one line at a time, for the dashboard to show while the launch runs. */
     report?: ((detail: string) => void) | undefined;
+    /** Gives the launch up: a step under way is not waited for, and a Chrome already spawned is killed. */
+    signal?: AbortSignal | undefined;
 }
 /**
  * Launch the bridge browser and get it ready: binary, profile, extension, developer mode, token,
@@ -204,12 +206,12 @@ export interface BridgeBrowserOwner {
     stop(): Promise<void>;
     act(action: BridgeBrowserAction): Promise<void>;
 }
-/** How the owner launches a browser: the daemon's real launch, or a test's fake. */
-export type BridgeBrowserLauncher = (report: (detail: string) => void) => Promise<BridgeBrowser>;
+/** How the owner launches a browser: the daemon's real launch, or a test's fake. `signal` aborts when a stop gives the launch up. */
+export type BridgeBrowserLauncher = (report: (detail: string) => void, signal: AbortSignal) => Promise<BridgeBrowser>;
 /**
  * The one bridge browser a daemon runs. A launch is slow — the first one downloads Chrome — so
- * the status carries the step it is on, and a stop that lands mid-launch closes the browser the
- * launch then hands over rather than leaving it running unowned. A browser that exits on its own
+ * the status carries the step it is on, and a stop that lands mid-launch gives the launch up, and
+ * closes the browser a launch that went on regardless hands over, rather than leaving it unowned. A browser that exits on its own
  * (the user quit it) is reported as stopped with the reason, and not relaunched: quitting it was
  * an act, and the dashboard offers a restart.
  */

package/dist/module-types/src/dashboard/agent-handoff.d.ts

@@ -272,7 +272,7 @@ export declare function openRemoteBranchPullRequest(cwd: string, agent: HandoffA
  * Open a PR for a finished session, deciding from what the agent recorded which cases should not
  * open one. Reads the branch's handoff first: a branch that no longer exists, or a session that
  * changed nothing, is a clear error rather than an empty PR, and a branch that already has a PR
- * returns that one. Title is its branch, else the id; body is the intent, plus which session did it. This is the handoff decision the
+ * returns that one. Title and body say what its commits did ({@link commitsPrText}). This is the handoff decision the
  * dashboard's open-PR button offers; the RPC layer only resolves which run it is about, and the
  * two providers do the pushing and the opening.
  */
@@ -281,6 +281,7 @@ export declare function openAgentPullRequest(cwd: string, agent: AgentMeta, opti
     branches?: BranchesFor;
     gitHost?: GitHostFor;
     pr?: BranchPrLookup;
+    git?: GitRunner;
 }): Promise<HandoffResult>;
 /**
  * The little a handoff needs to know about the agent it is for: which branch, and what to say on

package/dist/module-types/src/dashboard/interventions.d.ts

@@ -14,22 +14,25 @@ export interface Intervention {
     projectName: string;
     /**
      * `pr` = an open PR to review/merge or close; `awaiting` = a run waiting on the question it ended on (#636/#1774);
-     * `unpushed` = a finished agent whose branch has commits that were never pushed (#860).
+     * `uncommitted` = a finished run whose checkout holds files it never committed; `unpushed` = a finished
+     * run whose branch has commits that were never pushed (#860).
      */
-    kind: 'pr' | 'awaiting' | 'unpushed';
+    kind: 'pr' | 'awaiting' | 'uncommitted' | 'unpushed';
     title: string;
-    /** The PR on the git host (`pr` only): where a click takes the user. */
+    /** The PR on the git host (`pr` only): where a click takes the user when no run of this dashboard opened it. */
     url?: string;
     /** The PR number (`pr` only). */
     number?: number;
     /** The question's id (`awaiting` only) — its stable identity, so it notifies exactly once. */
     awaitId?: string;
-    /** Which run this is about (`awaiting` #738 / `unpushed`): a project has several agents. */
+    /** Which run this is about (every kind but a `pr` opened outside this dashboard's runs): a project has several agents. */
     agentId?: string;
-    /** The branch the work is sitting on (`unpushed` only). */
+    /** The branch the work is sitting on (`uncommitted` and `unpushed` only). */
     branch?: string;
     /** How many commits are waiting (`unpushed` only). */
     commits?: number;
+    /** How many files were left uncommitted (`uncommitted` only). */
+    files?: number;
     /** When the PR was opened (`pr`) or the agent last updated (the other two), ISO, for ordering. */
     createdAt?: string;
 }
@@ -44,12 +47,6 @@ export interface InterventionsDeps {
     agents?: (cwd: string) => Promise<AgentMeta[]>;
     /** The project's checkouts and branches (default the project's provider, {@link projectBranches}): where a branch's state is read; drives the `unpushed` source (#860). */
     branches?: BranchesFor;
-    /**
-     * How many of a project's most recent finished agents to inspect for unpushed work. Each one costs
-     * a handful of git reads, and this runs on a poll, so old history is not re-walked every minute:
-     * work that has sat unpushed for dozens of agents is not news, and the agent list stays the record.
-     */
-    handoffLimit?: number;
 }
 /**
  * Build the cross-project interventions queue: every registered project's open PRs, plus any run

package/dist/module-types/src/dashboard/keys.d.ts

@@ -14,8 +14,8 @@ import type { Intervention } from './interventions.js';
  */
 /**
  * The stable identity of an intervention. A PR is its url (survives title edits and re-sorts);
- * the other two have no url and are keyed on the project plus the thing waiting — the agent and
- * the gate it is parked on, or the agent whose branch is unpushed.
+ * the others have no url and are keyed on the project plus the thing waiting — the agent and
+ * the gate it is parked on, or the agent whose work is uncommitted or unpushed.
  *
  * The agent is part of the awaiting key because a gate id is only unique within its own agent:
  * every agent's first gate is `await-choices`. Two agents running in one project (#736) and both

package/dist/module-types/src/dashboard/pull-requests.d.ts

@@ -91,8 +91,25 @@ export declare function prView(cwd: string, branch: string, gitHost?: GitHostFor
  * deciding whether to offer "Open PR". A read with no branch to ask about answers nothing at once.
  */
 export declare function cachedPrView(cwd: string, branch?: string): Promise<Cached<LinkedPr | undefined>>;
-/** Forget a branch's PR, after an action that changes whether it has one. */
+/** Forget a branch's PR, after an action that changes whether it has one, and with it how the project's PRs stand and which are open. */
 export declare function forgetPr(cwd: string, branch?: string): void;
+/** How a run's pull request stands, as its row in the list of runs shows it. */
+export type PrState = 'open' | 'draft' | 'merged' | 'closed';
+/**
+ * How each of a project's newest pull requests stands, by its address: what the list of runs marks
+ * each run's PR with. One listing of the project's requests, whatever their state, rather than one
+ * per run; a request older than what the git host lists has no state here. A listing the git host
+ * cannot answer throws.
+ */
+export declare function prStates(cwd: string, gitHost?: GitHostFor): Promise<Map<string, PrState>>;
+/**
+ * The cached form of {@link prStates} (#1028): the list of runs is polled every few seconds, and a
+ * PR's state changes far less often. A listing that fails is kept like an answer, as the states
+ * last read, so a git host that cannot answer is asked again a minute later, not at every poll;
+ * and while a read is on its way, after a request was opened or merged here, the rows keep the
+ * states they had.
+ */
+export declare function cachedPrStates(cwd: string, read?: (cwd: string) => Promise<Map<string, PrState>>): Promise<Map<string, PrState>>;
 /** The cached form of {@link prsForBranch}, shared through the same read-through cache (#1028). */
 export declare function cachedPrsForBranch(cwd: string, branch: string): Promise<Cached<LinkedPr[]>>;
 /** Forget a branch's PR history, after an action that changes it (opening one). */
@@ -124,3 +141,12 @@ export declare function pickAgentPr(prs: LinkedPr[], since?: string, order?: 'fi
  * it cannot decide what it never hears about. A project with no git host package has none open.
  */
 export declare function openPrs(cwd: string, gitHost?: GitHostFor): Promise<OpenPr[]>;
+/**
+ * The cached form of {@link openPrs} (#1028), for the Human Queue: it asked the git host at every
+ * poll of every page that shows it, and the page waited. The first ask waits for the answer; after
+ * that the list last read answers at once and is read again behind it once it is
+ * {@link OPEN_PRS_TTL_MS} old. A request opened or merged here is read again at once
+ * ({@link forgetPr}). A first read that fails rejects, as {@link openPrs} does; a later one keeps
+ * the list last read.
+ */
+export declare function cachedOpenPrs(cwd: string, read?: (cwd: string) => Promise<OpenPr[]>): Promise<OpenPr[]>;

package/dist/module-types/src/dashboard/rpc-serve.d.ts

@@ -5,13 +5,15 @@ import type { QuotaSource } from './quota.js';
 import type { ModelsSource } from './models.js';
 import type { BridgeBrowserOwner } from '../bridge-browser.js';
 import type { ProjectErrorsReader } from '../project-errors.js';
-import type { AddProjectResult, RemoveProjectResult, StartAgentOptions, StartAgentResult } from './types.js';
+import type { AddProjectResult, RemoveProjectResult, StartAgentOptions, StartAgentResult, StartedInResult } from './types.js';
 import type { AgentMeta } from '../store/index.js';
 import type { RemoteTarget } from './remote-run.js';
 /** Wired by the daemon so `sendStart` can reach the daemon's own `startAgent` closure. */
 export type StartAgentHandler = (prompt: string, options: StartAgentOptions, projectId?: string) => StartAgentResult | Promise<StartAgentResult>;
 /** Wired by the daemon so `sendAddProject` can install + register a repo (#433). */
 export type AddProjectHandler = (path: string, share: boolean) => AddProjectResult | Promise<AddProjectResult>;
+/** Wired by the daemon so `sendStartedAgain` can find or add the project a second `openagent` was started in. */
+export type StartedInHandler = (folder: string) => StartedInResult | Promise<StartedInResult>;
 /** Wired by the daemon so `sendRemoveProject` can take a project off the list, by its id, and with `files` remove what OpenAgent left in its folder. */
 export type RemoveProjectHandler = (projectId: string, files: boolean) => RemoveProjectResult | Promise<RemoveProjectResult>;
 /** Resolve an agent to its live event stream: the relay feeds `onEvents` from its own in-memory stream
@@ -63,6 +65,7 @@ export interface RemoteAgents {
 export interface DashboardContext {
     startAgent: StartAgentHandler;
     addProject: AddProjectHandler;
+    startedIn: StartedInHandler;
     removeProject: RemoveProjectHandler;
     /** The in-memory event stream for an agent relayed from a saved machine (#1067), else undefined. */
     eventsSource: EventsSource;

package/dist/module-types/src/dashboard/types.d.ts

@@ -28,6 +28,24 @@ export type AddProjectResult = {
     ok: false;
     error: string;
 };
+/**
+ * The project a folder `openagent` was started in is, on the dashboard's list: the listed project
+ * holding the folder, or the folder, added now. `id` always opens its page; `address` is the one
+ * the page writes (`src/project-address.ts`).
+ */
+export interface StartedProject {
+    id: string;
+    path: string;
+    added: boolean;
+    address: string;
+}
+/** The {@link StartedProject}, or why the folder could not be added. */
+export type StartedInResult = ({
+    ok: true;
+} & StartedProject) | {
+    ok: false;
+    error: string;
+};
 /**
  * What removing OpenAgent's files from a project's folder did: what went, what stayed with the
  * reason, and what could not be done, each line in words for a person. Paths are from the

package/dist/module-types/src/dashboard/unpublished.d.ts

@@ -0,0 +1,42 @@
+import type { AgentMeta } from '../store/index.js';
+import { type BranchesFor } from '../store/branches.js';
+/**
+ * A finished run's work that never left this machine: the branch it is on, the commits it holds
+ * that were never published, and the files its checkout left uncommitted. Either count may be 0,
+ * never both.
+ */
+export interface Unpublished {
+    branch: string;
+    commits: number;
+    uncommitted: number;
+}
+/**
+ * The finished runs of a project whose work never left this machine (#860), by run id: what the
+ * Human Queue lists as "Not committed" and "Not published" and the list of runs marks on each row,
+ * read alike so the two never disagree.
+ *
+ * Only a branch the branches provider made for the run counts. A branch of the person's own is
+ * theirs: a run continued on it, or a branch made before the history was rewritten, which is
+ * thousands of commits past the base.
+ *
+ * Files its checkout left uncommitted wait on the person whatever else is true of the branch: the
+ * run's next step is to commit them, a pull request or none. Not for a run waiting on its question,
+ * which is that run's next step, and which keeps its checkout as it was. The checkout on a branch is
+ * the newest run's: a run continued on the branch of an earlier one works in a checkout of its own,
+ * and what it leaves there is not the earlier run's.
+ *
+ * Commits wait when they are the branch's own beyond the base, not in the default branch, never
+ * pushed, in a project with a remote to push to. A branch pushed once whose copy on the remote is
+ * gone since, as a merged pull request's is, left the machine. So did a run with a pull request: its
+ * request is what the queue and its row show, and a branch pushed without an upstream reads, once
+ * its request merged and the remote's copy went, as never pushed.
+ *
+ * Every run is asked, in one quick read of the provider (`ahead`: counts, no file lists). A run
+ * started from another branch is asked apart, from the commit it started at, or that branch's work
+ * would count as its own; a run started from the default branch is counted from it, which already
+ * leaves out whatever it took in later, so the commit it started at changes nothing and all such
+ * runs share one read. A subagent's branch is its main agent's to land, never a person's to push,
+ * and a run still working is still writing its branch. A provider that cannot be found, or does not
+ * answer for every branch asked, throws: "nothing waits" would be a false answer.
+ */
+export declare function unpublishedRuns(cwd: string, agents: readonly AgentMeta[], branches?: BranchesFor): Promise<Map<string, Unpublished>>;

package/dist/module-types/src/dashboard-rpc/context.d.ts

@@ -51,5 +51,7 @@ export declare function contextBridgeBrowser(): BridgeBrowserOwner;
 export declare function contextStartAgent(): DashboardContext['startAgent'];
 /** Install + register a repo (#433), which only the daemon can do. */
 export declare function contextAddProject(): DashboardContext['addProject'];
+/** Find or add the project a second `openagent` was started in (#2141), which only the daemon can do. */
+export declare function contextStartedIn(): DashboardContext['startedIn'];
 /** Take a project off the list, which only the daemon can do: it runs the project's close hooks first. */
 export declare function contextRemoveProject(): DashboardContext['removeProject'];

package/dist/module-types/src/dashboard-rpc/index.d.ts

@@ -1,7 +1,7 @@
 export { onAgents, onAgent, onAgentsDoing, onDocs, onQueue, onOverview, onRecentAgents, onInterventions, onOpenQuestions, onActivity, onDashboard, onGitHostHome, onRepositoryOffer, onGitStatus, onProjectFiles, onRetainedWorktrees, onAgentWorktree, onAgentHandoff, onBridgeQuestion, onBridgeStatus, onBridgeToken, onBridgeEvents, onBridgeAnswer, onBridgeBrowser } from './reads.js';
 export { sendStop, sendChoice, sendBridgeAnswer, sendBridgeAnswerCancel, sendBridgeBrowser, sendMessage, sendStart, sendOpenInApp, sendRemoveWorktree, sendDeleteAgent, sendOpenPullRequest, sendPush, sendMergeBranch, sendMerge, sendCreateRepository } from './control.js';
 export { streamAgentEvents, type LiveFeedEvent, type PartialMessage, type StreamSync } from './events.js';
-export { onProjects, sendAddProject, onCloneTarget, sendAddProjectFromAddress, sendRemoveProject, onRecordsReach, sendShareRecords, sendPickProjectDirectory, onOnboarding, onCommands, onStartCheck, type ProjectLauncher } from './projects.js';
+export { onProjects, sendAddProject, sendStartedAgain, onCloneTarget, sendAddProjectFromAddress, sendRemoveProject, onRecordsReach, sendShareRecords, sendPickProjectDirectory, onOnboarding, onCommands, onStartCheck, type ProjectLauncher } from './projects.js';
 export { onPreferences, savePreferences, patchPreferences, onProjectPresets, saveProjectPresets, onEditors, type SavePreferencesResult, type PatchPreferencesResult, } from './preferences.js';
 export { type EditorInfo } from '../dashboard/open-in-app.js';
 export { onQuota } from './quota.js';

package/dist/module-types/src/dashboard-rpc/projects.d.ts

@@ -3,7 +3,7 @@ import { type BranchReach } from '@openagt/agent-data';
 import { type StartReadiness } from '../project-hooks.js';
 import { type PickDirectoryResult } from '../pick-directory.js';
 import type { ProjectSummary } from '../dashboard/projects.js';
-import type { AddProjectResult, OnboardingSuggestion, RemoveProjectResult } from '../dashboard/types.js';
+import type { AddProjectResult, OnboardingSuggestion, RemoveProjectResult, StartedInResult } from '../dashboard/types.js';
 export declare function onProjects(): Promise<ProjectSummary[]>;
 /**
  * Add a project from the dashboard (#396/#433): install the repo and register it so it joins the
@@ -15,6 +15,16 @@ export declare function onProjects(): Promise<ProjectSummary[]>;
  * repository's remote. Nothing is pushed for a project added with `false`.
  */
 export declare function sendAddProject(path: string, share: boolean): Promise<AddProjectResult>;
+/**
+ * A second `openagent` started while this dashboard listens on its port (#2141): it serves
+ * nothing itself, and hands over the folder it was started in, if it is in a repository. The
+ * answer says which OpenAgent runs here, and the project that holds the folder, else the folder,
+ * added. A page's own call is answered the same, and adds no more than Add project.
+ */
+export declare function sendStartedAgain(folder: string | null): Promise<{
+    version: string;
+    project?: StartedInResult;
+}>;
 /** Where the repository a person typed the address of would be cloned to on this computer, or why what was typed is no address: asked before anything is cloned. */
 export declare function onCloneTarget(address: string): Promise<{
     ok: true;

package/dist/module-types/src/dashboard-rpc/reads.d.ts

@@ -1,5 +1,5 @@
 import type { BridgeBrowserStatus } from '../bridge-browser.js';
-import { type AgentDoing, type AgentMeta } from '../store/index.js';
+import { type AgentDoing, type AgentMeta, type BranchesFor } from '../store/index.js';
 import { type GitHostHome } from '../store/git-host.js';
 import { type RepositoryOffer } from '../store/repository.js';
 import { type WorkspaceDoc } from '../dashboard/docs.js';
@@ -12,6 +12,7 @@ import { type Activity } from '../dashboard/activity.js';
 import { type DashboardData } from '../dashboard/dashboard.js';
 import { type GitStatus } from '../dashboard/git-status.js';
 import { type AgentHandoff } from '../dashboard/agent-handoff.js';
+import { type PrState } from '../dashboard/pull-requests.js';
 import type { AgentWorktree } from '../dashboard/types.js';
 import type { OpenAgentEvent } from '../events.js';
 import type { BridgeEvent, BridgeHello, BridgeQuestion } from '../dashboard/bridge-endpoints.js';
@@ -37,6 +38,22 @@ import type { SavedMachine } from '../dashboard/rpc-serve.js';
  * instead of losing it.
  */
 export declare function onAgents(projectId: string): Promise<AgentMeta[]>;
+/**
+ * What a run's row marks beside its name, for both lists of runs, a project's and all projects'
+ * together: how its pull request stands, and the work it left on this machine.
+ */
+export declare function withRowMarks(cwd: string, agents: AgentMeta[]): Promise<AgentMeta[]>;
+/**
+ * Each run that has a pull request, marked with how the request stands, so its row can show it:
+ * from one cached listing of the project's requests, read only when one of the runs has a request.
+ */
+export declare function withPrStates(cwd: string, agents: AgentMeta[], states?: (cwd: string) => Promise<Map<string, PrState>>): Promise<AgentMeta[]>;
+/**
+ * Each finished run whose work never left this machine, marked with how many files it left
+ * uncommitted and how many commits wait, so its row can say so as the Human Queue does: the same
+ * rule, {@link unpublishedRuns}. A provider that cannot be read marks nothing.
+ */
+export declare function withUnpublished(cwd: string, agents: AgentMeta[], branches?: BranchesFor): Promise<AgentMeta[]>;
 /**
  * A project's runs with the ones this daemon follows on a machine (#1067), which live in its
  * memory. A run this computer sent that has no record here is listed first, as followed, so a

package/dist/module-types/src/project-address.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The words the dashboard keeps for itself, after a project's address and in its place: `overview`,
+ * a project's Overview, and `settings` (#958), where Settings was a page. Settings is a dialog over
+ * the page you are on now, carried as `?settings=`; the old address still opens it, over the
+ * Overview. No module's page takes either.
+ */
+export declare const OVERVIEW_SEGMENT = "overview";
+export declare const SETTINGS_SEGMENT = "settings";
+/**
+ * Whether a segment can name a page a module adds (#1774): a lowercase letter, then lowercase
+ * letters and digits, and not a word the dashboard keeps. Whichever module claims the segment gets
+ * it, and the shell says "no such page" when none does, or when the picked project has no package
+ * that adds it.
+ */
+export declare function isPageSegment(segment: string): boolean;
+/** Each registered project's address, and the project an address or an id names. */
+export interface ProjectAddresses {
+    /** The project's address: its name, or its id where the name cannot be one. An unknown id is its own address. */
+    addressOf(projectId: string): string;
+    /** The project a first segment names, by its address or by its id; undefined for none. */
+    projectOf(segment: string): string | undefined;
+}
+/**
+ * The addresses of the registered projects, in the registry's order, beside the pages' words.
+ * A project's name is its id without the `-<hash>`: its folder's name, as the id writes it. The
+ * name is its address unless a page has that word, since pages win, or a project before it in the
+ * registry already has that name: the first one added keeps it, so adding a second clone changes
+ * no address in use.
+ */
+export declare function projectAddresses(projectIds: readonly string[], pageWords: readonly string[]): ProjectAddresses;
+/** No project registered: every first segment is a page's, or a project's nobody registered. */
+export declare const NO_PROJECTS: ProjectAddresses;

package/dist/module-types/src/store/agent-store.d.ts

@@ -151,6 +151,19 @@ export interface AgentMeta {
      * machine can ask whether the process is alive.
      */
     saving?: boolean;
+    /**
+     * How the run's pull request stands ({@link pr}), as the git host last said. Not stored: annotated
+     * on the way to the dashboard like {@link saving}, since it changes on the git host, not here.
+     */
+    prState?: 'open' | 'draft' | 'merged' | 'closed';
+    /**
+     * How many commits of the run's own wait on its branch, never pushed: its work has not left this
+     * machine. Not stored: annotated on the way to the dashboard like {@link prState}, since a push
+     * changes it, not the run.
+     */
+    unpublished?: number;
+    /** How many files the run's checkout left uncommitted, annotated like {@link unpublished}. */
+    uncommitted?: number;
     /**
      * The loopback port the agent's browser preview is listening on (#813), or absent when the agent
      * has no browser. What lets the daemon proxy the pane: the port is allocated per agent and the

package/dist/module-types/src/store/branches.d.ts

@@ -13,10 +13,12 @@
  *   `<command> show [--from <commit>] <branch>...`      what each branch holds and where it stands, as an array of {@link BranchState}, in the order asked;
  *                                                       measured from `<commit>`, where the branches started, in place of the default branch;
  *                                                       a full commit id in place of a branch is read as a branch that ends there
+ *   `<command> ahead [--from <commit>] <branch>...`     how far each branch is past the base, whether the remote has it, and what its checkout left uncommitted,
+ *                                                       as an array of {@link BranchAhead}: no file lists, so every run's branch can be asked on a poll
  *   `<command> merge <b>`                               merge the branch into the default branch, on this machine, then delete it
  *   `<command> push --branch <b>`                       push the branch to the remote; a branch only the remote has is answered as it is
  *   `<command> remove <id> [--from <commit>] [--discard]`  reclaim a run's checkout once its branch holds everything, pushing nothing, its branch measured from the commit it started from; `--discard` drops uncommitted work
- * `list` and `show` read this machine, no network: OpenAgent polls. `show` answers the branch's
+ * `list`, `show` and `ahead` read this machine, no network: OpenAgent polls. `show` answers the branch's
  * git facts only; its pull request is the git host provider's (`git-host.ts`), as every pull request is.
  *
  * That is the whole contract: git, and nothing beyond it (#1820). OpenAgent reads checkouts to
@@ -24,7 +26,7 @@
  * the Human Queue's unpushed rows. Opening a pull request is the push here, then the git host
  * provider's `open`. What a checkout is, where it lives, how a branch is pushed is the package's.
  *
- * The shapes, owned here: {@link Checkout}, {@link BranchState}.
+ * The shapes, owned here: {@link Checkout}, {@link BranchState}, {@link BranchAhead}.
  */
 /** A run's checkout: where it works, as a provider lists it. */
 export interface Checkout {
@@ -74,6 +76,26 @@ export interface BranchState {
     /** The uncommitted paths in the checkout that is on this branch; absent when no checkout is. */
     pendingFiles?: string[];
 }
+/** How far a branch is past its base and whether the remote has it, as a provider answers `ahead`: counts, no files. */
+export interface BranchAhead {
+    branch: string;
+    /** The branch exists on this machine. */
+    exists: boolean;
+    /** A branch the provider made for a run, not one of the person's own. */
+    agent: boolean;
+    /** How many commits of its own it has beyond the base. */
+    ahead: number;
+    /** The project has a remote to push to. */
+    hasRemote: boolean;
+    /** The remote has the branch at this same tip. */
+    pushed: boolean;
+    /** It was pushed, and the remote's copy is gone since, as a merged pull request's is. */
+    gone: boolean;
+    /** The project's default branch already contains it. */
+    merged: boolean;
+    /** How many paths the run's checkout on it left uncommitted; 0 with no checkout. */
+    uncommitted: number;
+}
 /** What pushing a branch did: `pushed` is false when only the remote had it, so there was nothing here to push. */
 export type PushOutcome = {
     ok: true;
@@ -124,6 +146,8 @@ export interface BranchesSource {
      * branch that ended there held.
      */
     show(branches: readonly string[], from?: string): Promise<BranchState[]>;
+    /** How far each branch is past its base and whether the remote has it, in the order asked; `[]` when nothing can be read. `from` as for {@link show}. */
+    ahead(branches: readonly string[], from?: string): Promise<BranchAhead[]>;
     /** Push a branch to the remote: the checkout on it under its clean rule, else the branch itself. */
     push(branch: string): Promise<PushOutcome>;
     /** Merge a branch into the project's default branch, on this machine, then delete it; a merge that conflicts changes nothing. */
@@ -148,6 +172,8 @@ export type BranchesReader = BranchesFor & {
 export declare function parseCheckouts(output: unknown): Checkout[];
 /** The states read back from a provider's `show`: the objects with a branch and the three verdicts, lists cleaned; anything else is no state. */
 export declare function parseBranchStates(output: unknown): BranchState[];
+/** The counts read back from a provider's `ahead`: the objects with a branch and every verdict; anything else is no answer. */
+export declare function parseBranchesAhead(output: unknown): BranchAhead[];
 /**
  * The production {@link BranchesReader}: the project's provider, looked up among the packages the project has (`built-in.ts`),
  * one source per project kept while the same command provides — so the cache holds across the

package/dist/module-types/src/store/index.d.ts

@@ -1,7 +1,7 @@
 export { nodeStoreFs, listAgents, readAllAgents, findAgent, isPidAlive, readLiveMeta, loadAgentEvents, readLiveMetas, readDoing, type AgentDoing, readFinishedDiary, type StoreFs, type AgentMeta, type LiveAgent, type AgentStatus, } from './agent-store.js';
 export { findCheckout, resolveAgentCheckout, resolveAgentDiary, type AgentDiarySource } from './agent-checkout.js';
 export { projectRuns, providedRuns, noRuns, parseRunCard, isRunId, type RunsFor, type RunsReader, type RunsSource, type RunsWrite, type RunCard, type RunPatch, type RunStatus, type AnyDiaryLine, type FinishedRun } from './runs.js';
-export { projectBranches, providedBranches, noBranches, parseCheckouts, parseBranchStates, type BranchesFor, type BranchesReader, type BranchesSource, type RemoveOutcome as BranchRemoveOutcome, type Checkout, type BranchState, type BranchCommit, type BranchFile, type PushOutcome as BranchPushOutcome } from './branches.js';
+export { projectBranches, providedBranches, noBranches, parseCheckouts, parseBranchStates, parseBranchesAhead, type BranchesFor, type BranchesReader, type BranchesSource, type RemoveOutcome as BranchRemoveOutcome, type Checkout, type BranchState, type BranchAhead, type BranchCommit, type BranchFile, type PushOutcome as BranchPushOutcome } from './branches.js';
 export { projectGitHost, providedGitHost, noGitHost, parseRequests, type GitHostFor, type GitHostReader, type GitHostSource, type GitHostRequest, type GitHostHome, type RequestsOutcome as GitHostRequestsOutcome, type OpenOutcome as GitHostOpenOutcome, type MergeOutcome as GitHostMergeOutcome } from './git-host.js';
 export { projectQueue, providedQueue, noQueue, parseQueueEntries, type QueueFor, type QueueReader, type QueueSource } from './queue.js';
 export { providedDataChanged } from './provided.js';

package/dist/module.css

@@ -34,6 +34,7 @@
   --color-warning: var(--warning);
   --color-danger: var(--danger);
   --color-info: var(--info);
+  --color-merged: var(--merged);
 
   /* The shadcn sidebar reads its own `--sidebar-*` family so a sidebar can be themed apart from
      the page. Its background is its own (`--sidebar`: in the dark theme a step below the page, as

package/dist/project-address.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The words the dashboard keeps for itself, after a project's address and in its place: `overview`,
+ * a project's Overview, and `settings` (#958), where Settings was a page. Settings is a dialog over
+ * the page you are on now, carried as `?settings=`; the old address still opens it, over the
+ * Overview. No module's page takes either.
+ */
+export declare const OVERVIEW_SEGMENT = "overview";
+export declare const SETTINGS_SEGMENT = "settings";
+/**
+ * Whether a segment can name a page a module adds (#1774): a lowercase letter, then lowercase
+ * letters and digits, and not a word the dashboard keeps. Whichever module claims the segment gets
+ * it, and the shell says "no such page" when none does, or when the picked project has no package
+ * that adds it.
+ */
+export declare function isPageSegment(segment: string): boolean;
+/** Each registered project's address, and the project an address or an id names. */
+export interface ProjectAddresses {
+    /** The project's address: its name, or its id where the name cannot be one. An unknown id is its own address. */
+    addressOf(projectId: string): string;
+    /** The project a first segment names, by its address or by its id; undefined for none. */
+    projectOf(segment: string): string | undefined;
+}
+/**
+ * The addresses of the registered projects, in the registry's order, beside the pages' words.
+ * A project's name is its id without the `-<hash>`: its folder's name, as the id writes it. The
+ * name is its address unless a page has that word, since pages win, or a project before it in the
+ * registry already has that name: the first one added keeps it, so adding a second clone changes
+ * no address in use.
+ */
+export declare function projectAddresses(projectIds: readonly string[], pageWords: readonly string[]): ProjectAddresses;
+/** No project registered: every first segment is a page's, or a project's nobody registered. */
+export declare const NO_PROJECTS: ProjectAddresses;
+//# sourceMappingURL=project-address.d.ts.map

package/dist/project-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-address.d.ts","sourceRoot":"","sources":["../src/project-address.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,aAAa,CAAA;AAC1C,eAAO,MAAM,gBAAgB,aAAa,CAAA;AAE1C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,iHAAiH;IACjH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;IACpC,0FAA0F;IAC1F,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAC/C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAe9G;AAED,gGAAgG;AAChG,eAAO,MAAM,WAAW,EAAE,gBAA2C,CAAA"}

package/dist/project-address.js

@@ -0,0 +1,57 @@
+// A project's address in the dashboard's URL (#784): what the page shows, and what `openagent`
+// prints for a project it opens, so the two say one thing.
+//
+// A project's address is its folder's name: the id with its `-<hash>` off. The id itself is the
+// address only where the name cannot be one: a project before it in the registry has the same
+// folder name, or the name is a page's word. Only the address is a name: the id stays what
+// preferences, records and other machines know the project by, and it still opens the project.
+//
+// Pure and browser-safe: the dashboard imports it, and so does the server.
+/**
+ * The words the dashboard keeps for itself, after a project's address and in its place: `overview`,
+ * a project's Overview, and `settings` (#958), where Settings was a page. Settings is a dialog over
+ * the page you are on now, carried as `?settings=`; the old address still opens it, over the
+ * Overview. No module's page takes either.
+ */
+export const OVERVIEW_SEGMENT = 'overview';
+export const SETTINGS_SEGMENT = 'settings';
+/**
+ * Whether a segment can name a page a module adds (#1774): a lowercase letter, then lowercase
+ * letters and digits, and not a word the dashboard keeps. Whichever module claims the segment gets
+ * it, and the shell says "no such page" when none does, or when the picked project has no package
+ * that adds it.
+ */
+export function isPageSegment(segment) {
+    return /^[a-z][a-z0-9]*$/.test(segment) && segment !== OVERVIEW_SEGMENT && segment !== SETTINGS_SEGMENT;
+}
+/**
+ * The addresses of the registered projects, in the registry's order, beside the pages' words.
+ * A project's name is its id without the `-<hash>`: its folder's name, as the id writes it. The
+ * name is its address unless a page has that word, since pages win, or a project before it in the
+ * registry already has that name: the first one added keeps it, so adding a second clone changes
+ * no address in use.
+ */
+export function projectAddresses(projectIds, pageWords) {
+    const taken = new Set([OVERVIEW_SEGMENT, SETTINGS_SEGMENT, ...pageWords, ...projectIds]);
+    const byId = new Map();
+    const byAddress = new Map();
+    for (const id of projectIds) {
+        const name = nameOf(id);
+        const address = name && !taken.has(name) ? name : id;
+        taken.add(address);
+        byId.set(id, address);
+        byAddress.set(address, id);
+    }
+    return {
+        addressOf: id => byId.get(id) ?? id,
+        projectOf: segment => byAddress.get(segment) ?? (byId.has(segment) ? segment : undefined),
+    };
+}
+/** No project registered: every first segment is a page's, or a project's nobody registered. */
+export const NO_PROJECTS = projectAddresses([], []);
+/** A project id's name: the id without its last `-<hash>`; empty for an id with no dash. */
+function nameOf(projectId) {
+    const dash = projectId.lastIndexOf('-');
+    return dash > 0 ? projectId.slice(0, dash) : '';
+}
+//# sourceMappingURL=project-address.js.map