@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/widget-types/src/dashboard/file-diff.d.ts

@@ -0,0 +1,66 @@
+import { type GitRunner } from '@gemstack/agent-data';
+import type { FileGitStatus } from './file-status.js';
+import { safeRepoPath } from './file-read.js';
+export { safeRepoPath };
+/** One file's diff, capped so a hover card can render it. */
+export interface FileDiff {
+    /** The repo-relative path asked for. */
+    path: string;
+    status: FileGitStatus;
+    /** Unified diff body, hunks only (git's `diff --git` / index preamble is dropped). */
+    patch: string;
+    added: number;
+    removed: number;
+    /** The patch hit the preview cap and was cut. */
+    truncated: boolean;
+    /** Nothing textual to show (git reports a binary change, or the file is not UTF-8 text). */
+    binary: boolean;
+}
+/** One changed file in a session's Changes list (#817): what moved, and by how much. */
+export interface FileChange {
+    path: string;
+    status: FileGitStatus;
+    added: number;
+    removed: number;
+    /** Line counts are unavailable (a binary file, or an untracked one too large to count). */
+    binary: boolean;
+}
+/**
+ * The diff for one changed file in the checkout at `cwd`, or, given a `range`, between two
+ * commits of the repository at `cwd` (a run's committed change, `agent-tree.ts`).
+ *
+ * Tracked files diff against `HEAD`, not the index, so a change the agent staged still shows;
+ * that also matches `git status --porcelain`, which is what dotted the file in the first place.
+ * An untracked file is rendered as all-added from its contents, since `git diff --no-index`
+ * exits non-zero on a difference and would read as a failure here.
+ *
+ * Returns null when the path is unsafe, unreadable, or has no diff to show.
+ */
+export declare function readFileDiff(cwd: string, path: string, status: FileGitStatus, git?: GitRunner, range?: {
+    from: string;
+    to: string;
+}): Promise<FileDiff | null>;
+/** One `git diff --numstat` line, parsed. */
+export interface NumstatEntry {
+    path: string;
+    added: number;
+    removed: number;
+    binary: boolean;
+}
+/**
+ * Parse `git diff --numstat` output: `added<TAB>removed<TAB>path`, with `-` for both counts
+ * on a binary file. The one parser for the grammar — it was written here and in run-handoff,
+ * and the copies had already drifted on a path containing a tab (this side rejoined it, the
+ * other dropped the line).
+ */
+export declare function parseNumstat(out: string): NumstatEntry[];
+/**
+ * Every changed file in the checkout at `cwd`, with its line counts: the session's Changes list
+ * (#817). One `git status` plus one `git diff --numstat`, not a diff per file, so a session that
+ * touched forty files still costs two git calls.
+ *
+ * Untracked files have no numstat entry (they are not in the diff at all), so their added count
+ * is their line count, read from disk. Sorted by path, so the list does not reshuffle as a live
+ * session edits.
+ */
+export declare function readFileChanges(cwd: string, statuses: Record<string, FileGitStatus>, git?: GitRunner): Promise<FileChange[]>;

package/dist/widget-types/src/dashboard/file-read.d.ts

@@ -0,0 +1,41 @@
+/** Cap what a hover card renders, whether it is a patch or a file. */
+export declare const MAX_PREVIEW_LINES = 500;
+/** One unchanged file's contents for the tree's hover card (#828). */
+export interface FileContent {
+    /** The repo-relative path asked for. */
+    path: string;
+    /** The file's text, cut at {@link MAX_PREVIEW_LINES}. Empty when binary. */
+    text: string;
+    /** The file was longer than the cap and was cut. */
+    truncated: boolean;
+    /** Not UTF-8 text, so there is nothing to render. */
+    binary: boolean;
+}
+/**
+ * Whether a client-supplied path may be read: repo-relative, no traversal, no absolute path, no
+ * leading `-` (git would read it as a flag), and never into `.git` (config and credentials live
+ * there). Rejecting is the whole contract; the caller resolves it against a checkout it chose.
+ */
+export declare function safeRepoPath(path: string): boolean;
+/**
+ * Read a repo-relative file from `cwd`, or null when it is unsafe, outside the checkout, or
+ * unreadable.
+ *
+ * The confinement check is a `realpath` on both sides, not a string compare on the resolved path.
+ * `resolve` does not follow symlinks, so `src/link.txt -> /etc/passwd` resolves to a path that sits
+ * happily under `cwd` and passes a textual check while the read leaves the repo. `realpath` is what
+ * makes the containment real; it also normalizes the platform's own links (macOS `/tmp`), which is
+ * why `cwd` goes through it too rather than being compared raw.
+ */
+export declare function readConfinedFile(cwd: string, path: string): Promise<Buffer | null>;
+/** Cut a body to {@link MAX_PREVIEW_LINES}, reporting whether anything was dropped. */
+export declare function cutToPreview(body: string): {
+    body: string;
+    truncated: boolean;
+};
+/**
+ * One unchanged file's contents (#828). Null when the path is unsafe, outside the checkout, or
+ * unreadable. A file git has not touched still reads from the resolved checkout, so a session's
+ * hover shows its worktree's copy rather than the project root's (#815).
+ */
+export declare function readFileContent(cwd: string, path: string): Promise<FileContent | null>;

package/dist/widget-types/src/dashboard/file-status.d.ts

@@ -0,0 +1,20 @@
+import { type GitRunner } from '@gemstack/agent-data';
+/**
+ * The tree's per-file git state. `added` is a file a commit created (a run's committed change,
+ * `agent-tree.ts`); the working tree's status here never says it, a new file there is `untracked`.
+ */
+export type FileGitStatus = 'untracked' | 'added' | 'modified' | 'deleted';
+/** One `git status --porcelain` line: the two status columns and the path they are about. */
+export interface PorcelainEntry {
+    code: string;
+    /** Repo-relative; a rename resolves to the new path. */
+    path: string;
+}
+/** Parse `git status --porcelain` output. Shared with the handoff's pending-files read (#1173). */
+export declare function parsePorcelain(out: string): PorcelainEntry[];
+/**
+ * Read each changed file's status from `git status --porcelain`, keyed by repo-relative path.
+ * `??` is untracked, a `D` in either column is deleted, anything else (M/A/R/C…) reads as
+ * modified. Renames map to the new path. Returns `{}` when the path is not a git repo.
+ */
+export declare function readFileStatuses(cwd: string, git?: GitRunner): Promise<Record<string, FileGitStatus>>;

package/dist/widget-types/src/dashboard/gh.d.ts

@@ -0,0 +1,130 @@
+import { type CliRunner } from '../cli-exec.js';
+import { type Cached } from './cache.js';
+/**
+ * The `gh` CLI, in one place: the JSON reads the dashboard makes of pull requests. Reads only:
+ * pushing, opening and merging are the project's branches provider's (`../store/branches.ts`).
+ *
+ * There were four separate `gh` adapters across three modules. Three were reads that each
+ * hand-rolled `execFile` + `JSON.parse` + a swallowed failure and each spelled the 8s timeout
+ * again, and two of those differed only in whether a branch positional was passed.
+ */
+/** Runs `gh`, resolving stdout and rejecting with the CLI's own stderr on failure. */
+export type GhRunner = CliRunner;
+/** A forgiving `gh --json` read: resolves `empty` when gh is missing/unauthed, or its output is not JSON. */
+export declare function ghJson<T>(args: string[], cwd: string, empty: T, gh?: GhRunner): Promise<T>;
+/** The PR opened for a branch, when there is one. */
+export interface LinkedPr {
+    number: number;
+    url: string;
+    /** OPEN / MERGED / CLOSED (as gh reports it). */
+    state: string;
+    title: string;
+    /** ISO creation time, when the read included it: what tells one agent's PR from a predecessor's. */
+    createdAt?: string;
+    /**
+     * The head commit the PR covers, when the read included it (#1512): what tells "the branch's
+     * PR already landed everything" from "the session kept working after its PR merged".
+     */
+    headRefOid?: string;
+}
+/**
+ * A best-effort PR lookup, for a named branch or for the checkout's current branch. One type for
+ * both: the named-branch form is the general one, and "the current branch" is just omitting it.
+ */
+export type PrLookup = (cwd: string, branch?: string) => Promise<LinkedPr | undefined>;
+/**
+ * The branch-addressed form, for a caller that always names one (#799): a finished session's
+ * worktree may be gone, so "the current branch" would silently be the project's, not the
+ * session's. Narrower than {@link PrLookup} on purpose, so that invariant is in the type.
+ */
+export type BranchPrLookup = (cwd: string, branch: string) => Promise<LinkedPr | undefined>;
+/**
+ * The PR for `branch`, or for whatever branch `cwd` is on when none is named. Resolves undefined
+ * when gh is missing/unauthed or there is no PR.
+ *
+ * The named-branch form is what a finished session needs (#799): its worktree may be gone, so the
+ * checkout's current branch is the project's, not the session's. The fields are copied out rather
+ * than passed through, so a future `--json` addition cannot leak into what callers store.
+ *
+ * Every optional field {@link LinkedPr} declares must be both asked for and copied out here, or it
+ * is silently absent for every caller of this path. `createdAt` was once neither, and it is what
+ * tells an agent's own PR from a predecessor's on the same branch name ({@link pickAgentPr}).
+ */
+export declare function ghPrView(cwd: string, branch?: string, gh?: GhRunner): Promise<LinkedPr | undefined>;
+/**
+ * The cached form of {@link ghPrView} (#1028), and what the dashboard's panels use.
+ *
+ * A PR lookup costs about 600ms where the git reads beside it cost ten, and the answer changes
+ * about as often as someone opens a PR. Cached per checkout and branch, shared between the
+ * worktree bar and the handoff summary, and refreshed behind whoever asks. `pending` says the
+ * answer is not known yet rather than that there is no PR — the difference matters to a caller
+ * deciding whether to offer "Open PR".
+ */
+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. */
+export declare function forgetPr(cwd: string, branch?: string): void;
+/**
+ * Every PR a branch name has ever had, newest first (#1251).
+ *
+ * `gh pr view <branch>` answers with the newest PR for that head *in any state*, so a session
+ * whose prompt pins its branch name (`the-framework/triage-quick`) inherits a predecessor's
+ * merged PR as its own. The list form keeps the whole history so {@link pickAgentPr} can decide
+ * which entry, if any, belongs to the agent asking. Resolves `[]` when gh is missing/unauthed —
+ * indistinguishable from "no PRs", which is what every caller would do with a failure anyway.
+ */
+export declare function ghPrsForBranch(cwd: string, branch: string): Promise<LinkedPr[]>;
+/**
+ * {@link ghPrsForBranch} for a caller about to *open* a PR (#1601): a listing that fails throws
+ * instead of reading as "no PRs", because "none" and "could not tell" must not look alike there —
+ * the difference is a second draft PR on a branch that already has one.
+ */
+export declare function ghPrsForBranchOrThrow(cwd: string, branch: string): Promise<LinkedPr[]>;
+/** The cached form of {@link ghPrsForBranch}, 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). */
+export declare function forgetBranchPrs(cwd: string, branch: string): void;
+/**
+ * The PR that belongs to an agent, out of every PR its branch name has had (#1251/#1255).
+ *
+ * An OPEN PR always counts: GitHub allows one open PR per head branch, so whatever is open on the
+ * run's branch is where its pushed commits land. A closed one counts only when it was created
+ * after the agent started (`since`, the agent's `startedAt`) — the oldest such entry, which is the one
+ * this agent's handoff opened. Anything older is a previous agent's PR wearing the same branch name,
+ * which is exactly what showed a merged two-day-old PR as a fresh session's own. Without `since`
+ * only an open PR is trusted.
+ *
+ * `order` exists for the one caller asking a different question (#1512). `'first'` answers
+ * identity — which PR did *this agent* open, so a later agent's must not be the answer. `'latest'`
+ * answers the handoff decision — which PR last saw the branch, so "did the session keep working
+ * past it" is readable off that PR's `headRefOid`; there the oldest entry would call work that a
+ * second PR already landed unlanded.
+ */
+export declare function pickAgentPr(prs: LinkedPr[], since?: string, order?: 'first' | 'latest'): LinkedPr | undefined;
+/** An open PR on the interventions queue (#632). */
+export interface OpenPr {
+    number: number;
+    title: string;
+    url: string;
+    /**
+     * Draft PRs are generally left off the queue: a draft is not asking for review.
+     *
+     * The exception is a draft the framework opened for itself (#1102), which {@link headRefName}
+     * is what tells apart.
+     */
+    isDraft: boolean;
+    /** The branch the PR is from, so a session's own PR can be recognised as ours (#1102). */
+    headRefName?: string;
+    createdAt?: string;
+}
+/**
+ * A checkout's open PRs. Unlike the other reads here it *rejects* when gh could not answer — no
+ * remote, not authenticated, GitHub unreachable — instead of resolving `[]`.
+ *
+ * "No PRs are open" and "I could not look" are different answers, and its caller keeps a baseline
+ * of what it has already announced (#1623): taking the second for the first makes the next
+ * successful read announce every already-open PR as new. The caller decides what a failure costs;
+ * it cannot decide what it never hears about.
+ */
+export declare function ghPrList(cwd: string, gh?: GhRunner): Promise<OpenPr[]>;
+/** Lists a checkout's open PRs; rejects when there is no remote / gh is unavailable. */
+export type PrLister = (cwd: string) => Promise<OpenPr[]>;

package/dist/widget-types/src/dashboard/git-status.d.ts

@@ -0,0 +1,32 @@
+import { type GitRunner } from '@gemstack/agent-data';
+import { type LinkedPr, type PrLookup } from './pull-requests.js';
+/** A project's git status for the panel. */
+export interface GitStatus {
+    branch: string;
+    /** Uncommitted changes present. */
+    dirty: boolean;
+    pr?: LinkedPr;
+    /** The PR is not known yet, rather than absent (#1028): the lookup is still running. */
+    prPending?: boolean;
+}
+/** Injectable seams so {@link readGitStatus} is unit-testable off disk. */
+export interface GitStatusDeps {
+    git?: GitRunner;
+    pr?: PrLookup;
+    /**
+     * The agent's start, when the status is read for an agent's checkout (#1255). The default lookup
+     * answers the newest PR for the branch *in any state* — so an agent on a reused pinned branch
+     * (`the-framework/triage-quick`) wears a predecessor's merged PR as its own badge.
+     * With `since` set the PR is picked from the branch's whole history by {@link pickAgentPr}
+     * instead: an open PR, or a closed one no older than the agent itself.
+     */
+    since?: string;
+    /** The branch's full PR history, for the {@link GitStatusDeps.since} path (default {@link cachedPrsForBranch}). */
+    prs?: (cwd: string, branch: string) => Promise<LinkedPr[]>;
+}
+/**
+ * Read a project's git status: the current branch and dirty flag (from git), plus the linked
+ * PR (best-effort). Returns undefined when the path is not a git repo. Forgiving — a failed
+ * `git status` reads as clean, and a failed PR lookup simply omits the PR.
+ */
+export declare function readGitStatus(cwd: string, deps?: GitStatusDeps): Promise<GitStatus | undefined>;

package/dist/widget-types/src/dashboard/github.d.ts

@@ -0,0 +1,10 @@
+import { type GitRunner } from '@gemstack/agent-data';
+/**
+ * Normalize a git remote URL to an `https://github.com/<owner>/<repo>` URL, or undefined when
+ * it is not a GitHub remote. Handles the scp-style (`git@github.com:o/r.git`), ssh
+ * (`ssh://git@github.com/o/r.git`), and https (`https://github.com/o/r.git`) forms, dropping
+ * a `.git` suffix, an embedded credential, and a trailing slash.
+ */
+export declare function githubUrlFromRemote(remote: string): string | undefined;
+/** The repo's GitHub URL from its `origin` remote, or undefined (no remote / not GitHub). */
+export declare function githubUrlFor(cwd: string, git?: GitRunner): Promise<string | undefined>;

package/dist/widget-types/src/dashboard/http.d.ts

@@ -0,0 +1,28 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * The plumbing every one of the daemon's non-RPC HTTP surfaces shares: the browser bridge
+ * (`/_bridge`), the web-start queue (`/_web-start`) and the device relay (`/_relay`).
+ *
+ * All three answer plain-text statuses, JSON payloads, and read capped JSON request bodies, and
+ * each carried its own copy — two body readers that differed only in which message they rejected
+ * with, and three identical status responders.
+ */
+/** Answer with a plain-text status line. */
+export declare function end(res: ServerResponse, status: number, message: string, headers?: Record<string, string>): void;
+/** Answer with a JSON payload. */
+export declare function sendJson(res: ServerResponse, payload: unknown, status?: number): void;
+/**
+ * Read a JSON body, refusing anything past the cap rather than buffering it. Rejects with
+ * `body too large` on overflow and `body must be JSON` on anything unparseable — the messages the
+ * bridge and web-start routes answer 400 with, so a caller learns which of the two it hit.
+ */
+export declare function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<unknown>;
+/**
+ * The preamble every POST route runs: refuse a non-POST, then read the body. Answers the request
+ * itself on either failure and resolves `undefined`, so a caller's whole check is
+ * `const body = await readPost(...); if (body === undefined) return`. JSON has no `undefined`, so
+ * the sentinel cannot collide with a body that parsed.
+ */
+export declare function readPost(req: IncomingMessage, res: ServerResponse, maxBytes: number): Promise<unknown>;
+/** Refuse anything but a GET, answering 405 itself. `false` means the request is already answered. */
+export declare function requireGet(req: IncomingMessage, res: ServerResponse): boolean;

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

@@ -0,0 +1,66 @@
+import { type LiveAgent, type AgentMeta } from '../store/index.js';
+import type { FrameworkEvent } from '../events.js';
+import type { ProjectSummary, ProjectionRead } from './projects.js';
+import { type BranchesFor } from '../store/branches.js';
+import { type PrLister } from './pull-requests.js';
+export { interventionKey } from './keys.js';
+/**
+ * One item awaiting the human. Two kinds: an open `pr` to review/merge or close, and an
+ * `awaiting` run paused on a choice gate. The card and the browser hook both iterate the flat
+ * list, branching on `kind` for the fields that differ.
+ */
+export interface Intervention {
+    projectId: string;
+    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).
+     */
+    kind: 'pr' | 'awaiting' | 'unpushed';
+    title: string;
+    /** The PR on the git host (`pr` only): where a click takes the user. */
+    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. */
+    agentId?: string;
+    /** The branch the work is sitting on (`unpushed` only). */
+    branch?: string;
+    /** How many commits are waiting (`unpushed` only). */
+    commits?: number;
+    /** When the PR was opened (`pr`) or the agent last updated (the other two), ISO, for ordering. */
+    createdAt?: string;
+}
+/** Injectable seam so {@link buildInterventions} is unit-testable off disk. */
+export interface InterventionsDeps {
+    prs?: PrLister;
+    /** The reader of the runs that have a checkout (default {@link readLiveMetas}): a waiting run keeps its own; drives the `awaiting` source (#636). */
+    liveAgents?: (cwd: string) => Promise<LiveAgent[]>;
+    /** One run's events, by the project's path and the run's id (default {@link loadAgentEvents}): where a waiting run's question is read. */
+    events?: (cwd: string, agentId: string) => Promise<FrameworkEvent[] | undefined>;
+    /** The finished-agent reader (default {@link listAgents}); drives the `unpushed` source (#860). */
+    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
+ * currently paused on a choice gate (#636), newest first. Forgiving — a project with no remote
+ * (or an unreadable one) simply contributes nothing. Hand-opened draft PRs are excluded: they are
+ * not yet asking for review. A draft on an agent's branch is not (#1102): an agent publishes a
+ * draft when a person should look first, and cloud work adoption opens its PRs as drafts.
+ *
+ * Which projects were read whole comes back alongside the items (#1623): forgiveness here is what
+ * lets one unreachable project keep the queue useful, and it is also what would let that project's
+ * whole backlog announce itself as new the moment it came back. The queue's panels ignore this;
+ * the notification watcher is the caller that cannot.
+ */
+export declare function buildInterventions(projects: ProjectSummary[], deps?: InterventionsDeps): Promise<ProjectionRead<Intervention>>;

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

@@ -0,0 +1,30 @@
+import type { Activity } from './activity.js';
+import type { Intervention } from './interventions.js';
+/**
+ * The stable identity of a watched item, which the browser notifications dedupe on.
+ *
+ * A leaf module on purpose: `activity.ts` and `interventions.ts` build their items by reading the
+ * store, so they import `node:*` and cannot be reached from the browser bundle. These functions
+ * are pure and depend on nothing but the item, so they live here and are re-exported from
+ * `client.ts` — which is what lets the dashboard share them instead of keeping a copy that could
+ * drift from the item types.
+ *
+ * The type imports are erased at compile time, so they add no edge to the graph `client.test.ts`
+ * walks.
+ */
+/**
+ * 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 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
+ * parked would otherwise share one identity, and the dedupe would announce only one of them.
+ */
+export declare function interventionKey(item: Intervention): string;
+/**
+ * The stable identity of an activity item: its kind + project + run. The kind is part of the key
+ * so an agent's `started` and `finished` are two separate announcements (one when it kicks off, one
+ * when it lands), each firing exactly once.
+ */
+export declare function activityKey(item: Activity): string;

package/dist/widget-types/src/dashboard/models.d.ts

@@ -0,0 +1,24 @@
+import type { Driver, DriverModel } from 'agent-driver';
+import { type DriverName } from '../driver-names.js';
+/** What one coding agent offers: its models, or why it could not say. */
+export type DriverModels = {
+    models: DriverModel[];
+} | {
+    models: [];
+    error: string;
+};
+/** The models of every coding agent a person can pick, by driver. */
+export type ModelsView = Record<DriverName, DriverModels>;
+/** Where the dashboard reads which models each coding agent offers. */
+export interface ModelsSource {
+    read(): Promise<ModelsView>;
+}
+/**
+ * Ask each coding agent for its models, once: the first read asks, every later read answers from
+ * what it said, for the daemon's life. The list changes only with a new CLI version or a new
+ * login, and each question starts a CLI, so a menu opened again never waits on one. An agent that
+ * could not say is asked again at the next read, so a CLI installed or logged in since is found.
+ */
+export declare function cachedModelsSource(drivers: Record<DriverName, Pick<Driver, 'listModels'>>): ModelsSource;
+/** The daemon's own source: the coding agents on this machine, asked as the person's own login. */
+export declare function defaultModelsSource(): ModelsSource;

package/dist/widget-types/src/dashboard/open-in-app.d.ts

@@ -0,0 +1,42 @@
+/** Which app to open the project in. */
+export type OpenTarget = 'files' | 'editor';
+/** A known editor: its launcher CLI plus a human label for the picker (#727). */
+export interface EditorInfo {
+    bin: string;
+    label: string;
+}
+/**
+ * The editors the picker can offer (#727), probed by their CLI launcher on PATH. Order is the
+ * display order. `$FRAMEWORK_EDITOR` and a hand-typed value stay valid beyond this list; this is
+ * only what auto-detection looks for.
+ */
+export declare const KNOWN_EDITORS: EditorInfo[];
+/** Whether an editor launcher is installed (on PATH). A seam so detection is unit-testable. */
+export type EditorProbe = (bin: string) => Promise<boolean>;
+/** The installed subset of {@link KNOWN_EDITORS}, in display order (#727). */
+export declare function detectEditors(probe?: EditorProbe): Promise<EditorInfo[]>;
+/** The outcome of an open attempt. */
+export type OpenResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Spawns a command, resolving once it launches (not on exit) and rejecting if it can't start. */
+export type SpawnRunner = (command: string, args: string[]) => Promise<void>;
+/** The OS command that reveals a path in the file manager. */
+export declare function fileManagerCommand(path: string, os?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/** The command to open a path in an editor: `$FRAMEWORK_EDITOR` when set, else the VS Code CLI. */
+export declare function editorCommand(path: string, editor?: string | undefined): {
+    command: string;
+    args: string[];
+};
+/**
+ * Open the project at `cwd` in the file manager or an editor. Failures are values, never throws.
+ * `editor` (#727) is the stored preference; when unset {@link editorCommand} falls back to
+ * `$FRAMEWORK_EDITOR`, then `code`.
+ */
+export declare function openInApp(cwd: string, target: OpenTarget, agent?: SpawnRunner, editor?: string): Promise<OpenResult>;

package/dist/widget-types/src/dashboard/open-questions.d.ts

@@ -0,0 +1,52 @@
+import { type AgentMeta, type LiveAgent } from '../store/index.js';
+import type { ChoiceRequest, FrameworkEvent } from '../events.js';
+import { type BridgeQuestion } from './bridge-question.js';
+import type { ProjectSummary } from './projects.js';
+/** One session's open question: the full gate, answerable from wherever it is rendered. */
+export interface OpenQuestion {
+    projectId: string;
+    projectName: string;
+    agentId: string;
+    /** What the agent was asked to do: the card's label. */
+    intent?: string;
+    /** When the agent last spoke, ISO: what the longest-waiting-first order sorts on. */
+    updatedAt?: string;
+    choice: ChoiceRequest;
+    /**
+     * Asked by a Claude web session and carried here by the browser bridge (#1237/#1554): the pick
+     * goes back through `sendBridgeAnswer` on this session, not through the run's resume hook. The option
+     * ids of {@link choice} are the labels, which is what the extension types.
+     */
+    bridge?: {
+        sessionId: string;
+        url: string;
+    };
+}
+/** Injectable seams so {@link buildOpenQuestions} is unit-testable off disk. */
+export interface OpenQuestionsDeps {
+    /** The reader of the runs that have a checkout (default {@link readLiveMetas}): a waiting run keeps its own. */
+    liveAgents?: (cwd: string) => Promise<LiveAgent[]>;
+    /** One run's events, by the project's path and the run's id (default {@link loadAgentEvents}). */
+    events?: (cwd: string, agentId: string) => Promise<FrameworkEvent[] | undefined>;
+    /**
+     * The questions the browser bridge holds, minus those with an answer already on its way
+     * (default: the daemon's bridge store).
+     */
+    bridged?: () => BridgeQuestion[];
+    /**
+     * Every agent of a project, archived included (default {@link readAllAgents}): a web agent is
+     * `done` at its hand-off (#1231) and its checkout may be long gone, so the live reader alone
+     * would never find the run a bridged question belongs to.
+     */
+    agents?: (cwd: string) => Promise<AgentMeta[]>;
+}
+/**
+ * Every project's parked questions, longest-waiting first (#1455): an agent that has been blocked
+ * on its human the longest is the one to unblock first.
+ *
+ * Forgiving throughout, like every cross-project rollup: an unreadable project, agent list or
+ * event log contributes nothing rather than failing the read. A waiting run whose diary shows no
+ * open question (log unreadable) is skipped — offering an answer the daemon would refuse is
+ * worse than one card fewer.
+ */
+export declare function buildOpenQuestions(projects: ProjectSummary[], deps?: OpenQuestionsDeps): Promise<OpenQuestion[]>;

package/dist/widget-types/src/dashboard/overview.d.ts

@@ -0,0 +1,77 @@
+import { type LiveAgent, type AgentMeta, type AgentStatus } from '../store/index.js';
+import type { ProjectSummary } from './projects.js';
+import { type ProjectQueue } from './queue.js';
+/** One project's in-flight run, surfaced in the Overview's "working now" list. */
+export interface ActiveAgent {
+    projectId: string;
+    projectName: string;
+    /** Which run this is (#738): a project can have several in flight, one per worktree. */
+    agentId: string;
+    /** The agent's own checkout, so its git/file status is read from the worktree it edits (#738). */
+    cwd: string;
+    status: AgentStatus;
+    /** What the user asked to build (the agent's `scope` event). */
+    intent?: string;
+    scope?: string;
+    /** ISO timestamp of the agent's last event. */
+    updatedAt?: string;
+    /**
+     * A web run at work on its cloud side (#1668): in its session, or parked on a question the
+     * bridge reported. Its local half is over, so it is not a live agent — it is listed because the
+     * cloud side is the agent, and "no agents working" over a waiting cloud session was a lie.
+     */
+    cloud?: 'in-cloud' | 'waiting';
+    /** The machine whose daemon started it (#1648), only when that is not this one. */
+    host?: string;
+}
+/** One recently active project, most-recent first. */
+export interface RecentProject {
+    projectId: string;
+    projectName: string;
+    lastActivityAt?: string;
+}
+/** The cross-project Overview payload. */
+export interface Overview {
+    /** Projects with a running agent, most-recently-updated first. */
+    active: ActiveAgent[];
+    /** Total open TODO items across every project. */
+    queueOpen: number;
+    /** The most recently active projects (capped). */
+    recent: RecentProject[];
+}
+/** One recent session, tagged with the project it belongs to, for the cross-project rail. */
+export interface RecentAgent {
+    projectId: string;
+    projectName: string;
+    agent: AgentMeta;
+}
+/** Injectable reader so {@link buildRecentAgents} is unit-testable off disk. */
+export interface RecentAgentsDeps {
+    agents?: (cwd: string) => Promise<AgentMeta[]>;
+}
+/**
+ * Every project's sessions pooled and sorted newest-first (capped), so the shared sidebar (#shared-
+ * shell) can show recents on the home/Overview where no single project is selected. Each row carries
+ * the project it belongs to, so selecting it jumps into that project's session. Forgiving — a project
+ * whose agents cannot be read simply contributes nothing.
+ */
+export declare function buildRecentAgents(projects: ProjectSummary[], deps?: RecentAgentsDeps): Promise<RecentAgent[]>;
+/** Injectable readers so {@link buildOverview} is unit-testable off disk. */
+export interface OverviewDeps {
+    liveAgents?: (cwd: string) => Promise<LiveAgent[]>;
+    queue?: (projects: ProjectSummary[]) => Promise<ProjectQueue[]>;
+    /** Every run of a project, archived included (default {@link readAllAgents}): where the web runs are. */
+    agents?: (cwd: string) => Promise<AgentMeta[]>;
+    /** Whether the bridge holds a question for that cloud session (default: the daemon's bridge store). */
+    waiting?: (sessionId: string) => boolean;
+    now?: () => number;
+    /** This machine's hostname; `node:os` in production. */
+    host?: string;
+}
+/**
+ * Build the cross-project Overview: the running agents (every live agent of each project, one per
+ * worktree since #736), the total of open queue entries (from {@link collectQueue}), and the most
+ * recently active projects (by {@link ProjectSummary.lastActivityAt}). Forgiving — a project
+ * with no live run, or none running, simply contributes nothing to `active`.
+ */
+export declare function buildOverview(projects: ProjectSummary[], deps?: OverviewDeps): Promise<Overview>;