@openagt/dashboard 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,226 @@
+import { type PublishPick } from './publish-levels.js';
+/**
+ * The multi-project registry (#390): the list of projects the user has
+ * installed OpenAgent into, kept as a single JSON file `.bashrc`-style —
+ * `$HOME/.openagent.json` — so it is the user's responsibility to re-create
+ * per machine. The same file also holds the user's dashboard preferences (#410),
+ * so the daemon owns one user file and the UI never needs localStorage.
+ */
+/** One registered project. */
+export interface ProjectRecord {
+    /** Stable, URL-safe id derived from the path. */
+    id: string;
+    /** Absolute repo path. */
+    path: string;
+    /** ISO timestamp the project was added. */
+    addedAt: string;
+}
+/**
+ * The dashboard's Global options (#410), persisted next to the project list so they
+ * survive restarts without localStorage — the daemon reads/writes them, the SPA reads
+ * them over `POST /_rpc/onPreferences`. Mostly flat booleans mirroring the Start form's
+ * toggles; every field is optional and absent means off, except where a field documents its
+ * own default below.
+ */
+/**
+ * A user-defined preset (#626): a named prompt the user saved to re-run their own high-signal
+ * prompts, listed as a saved prompt in the launcher's Commands menu beside the project's commands.
+ * Just data — the label is the menu item, the prompt is loaded verbatim into the editor. `id` is
+ * stable so edits/deletes address one.
+ */
+export interface CustomPreset {
+    id: string;
+    label: string;
+    prompt: string;
+}
+export interface Preferences {
+    /** Fire a browser notification when a new item lands on the "needs you" queue (#627). Absent = on. */
+    notifyBrowser?: boolean;
+    /**
+     * Also notify on plain agent activity — an agent started, an agent finished (#627). The default-off
+     * counterpart to the always-on "needs you" notifications: it keeps you loosely informed of the
+     * pipeline moving even when nothing needs you. A *category* toggle: it composes with the method
+     * toggle {@link notifyBrowser}.
+     */
+    notifyNewActivity?: boolean;
+    /**
+     * The "needs you" category (#627): notify when an agent is awaiting your answer or a PR is ready
+     * to review. A *category* toggle, like {@link notifyNewActivity}, composing with the method
+     * toggle {@link notifyBrowser}. **Absent = on**: unlike the other
+     * flat opt-in booleans, human-intervention pings are the baseline OpenAgent leans on, so an
+     * unset preference keeps them firing; a user turns them off explicitly.
+     */
+    notifyHumanIntervention?: boolean;
+    /** The model to run on (#628), e.g. `opus` / `sonnet`, handed to the project's start hook. Absent = the hook's own default. */
+    model?: string;
+    /** Which coding agent a run starts on (#650): `claude-code` or `codex`, handed to the project's start hook. Absent = the hook's own default. */
+    driver?: string;
+    /** How far a run started from the dashboard publishes its work: `nothing`, or the level handed to the project's start hook, `commit`, `branch`, `pr` or `merge`. The launcher's menu shows it and writes it. Absent = none saved: the daemon decides where a Start goes. */
+    publish?: PublishPick;
+    /**
+     * Where an agent started from the launcher starts, per project: the projects, by id, whose
+     * launcher is set to "My local branch" (the branch the project's folder is on, as this machine
+     * has it). The launcher's "start from" chip shows it and writes it. **A project not listed
+     * starts from its main branch**, so the default stores nothing.
+     */
+    startFrom?: Record<string, 'local'>;
+    /**
+     * Post-merge cleanup: a run started from the launcher, in a project that has the
+     * `post-merge-cleanup` command, is followed by a fresh agent running it on the run's branch
+     * before the run's pull request merges. The default of the launcher's box, which writes it
+     * too. **Absent = off.**
+     */
+    postMergeCleanup?: boolean;
+    /** Preferred editor for "Open in editor" (#727): an editor CLI (e.g. `code`, `cursor`, `zed`).
+     * Absent falls back to `$OPENAGENT_EDITOR`, then `code`. */
+    editor?: string;
+    /** Dashboard color theme (#725): `system` (follow the OS, the default), `light`, or `dark`. Absent = system. */
+    theme?: 'system' | 'light' | 'dark';
+    /**
+     * The browser bridge (#1237): let an extension running in the user's own Claude session report
+     * the question a Claude web agent is parked on, so it shows in the dashboard rather than only on
+     * claude.ai. **Absent = off.** It opens the daemon's one route reachable from another origin,
+     * so it is opt-in rather than a baseline, and turning it on is what mints the bridge token.
+     */
+    bridge?: boolean;
+    /**
+     * The bridge browser (#1332): let the daemon run its own Chrome for Testing with the bridge
+     * extension installed, signed in once and kept minimized, so web runs stop depending on the
+     * user's own Chrome being open. **Absent = off**: it downloads a browser and keeps a signed-in
+     * claude.ai session on disk, neither of which should happen unasked. Needs {@link bridge}.
+     */
+    bridgeBrowser?: boolean;
+    /** User-defined presets (#626): the user's own saved prompts, shown in the Commands menu beside the project's commands. */
+    customPresets?: CustomPreset[];
+    /**
+     * Whether the Overview's Onboarding checklist has been dismissed (#958). Absent = show it,
+     * so a fresh install is walked through setup; dismissing only hides it on the Overview, and
+     * the same checklist stays available on the settings page.
+     */
+    onboardingDismissed?: boolean;
+}
+/** The persisted registry file shape (#410): the project list plus the user preferences. */
+export interface Registry {
+    projects: ProjectRecord[];
+    preferences: Preferences;
+    /**
+     * The shared daemon token (#1051): generated on the first non-loopback bind and reused after.
+     * A top-level field, deliberately not a {@link Preferences} one, so it is never shipped to the
+     * browser bundle. Absent on a loopback-only machine.
+     */
+    daemonToken?: string;
+}
+/** A read/write handle for the user preferences, wired into the dashboard's context by the daemon. */
+export interface PreferencesStore {
+    read(): Promise<Preferences>;
+    save(preferences: Preferences): Promise<void>;
+    /**
+     * Merge only the keys the caller changed (#1148) and hand back the stored result. Preferred over
+     * {@link save}, which replaces the whole block from a snapshot that may already be stale.
+     */
+    patch(patch: Preferences): Promise<Preferences>;
+}
+/** The registry file name: a single file under `$XDG_CONFIG_HOME` (dotted under `$HOME`). */
+export declare const REGISTRY_FILE = "openagent.json";
+/** Owner read/write only: the file holds the daemon token (#1051). */
+export declare const REGISTRY_FILE_MODE = 384;
+/**
+ * Deterministic, URL-safe id for a project path: the sanitized basename plus a
+ * short hash of the full path, so two repos named alike still get distinct ids.
+ * Pure; same path always yields the same id.
+ */
+export declare function projectId(path: string): string;
+/**
+ * The registry file path, resolved from `env` (injectable so tests never touch
+ * the real home): `$XDG_CONFIG_HOME/openagent.json` when set, else the
+ * dotted `$HOME/.openagent.json`. A single file, not a directory (#390).
+ */
+export declare function registryPath(env: NodeJS.ProcessEnv): string;
+/** Minimal fs seam so the registry is unit-testable without touching disk. */
+export interface RegistryFs {
+    /** Rejects when the file is absent. */
+    read(path: string): Promise<string>;
+    write(path: string, contents: string): Promise<void>;
+    /** Recursive; used on the registry file's parent dir. */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Replace `to` with `from`, atomically. Optional only so an existing implementation of this
+     * seam keeps compiling; without it {@link writeRegistry} falls back to the truncate-then-write
+     * this method exists to avoid (#991).
+     */
+    rename?(from: string, to: string): Promise<void>;
+    /**
+     * Narrow a file's permissions. Optional, and best-effort at the call site: this file holds the
+     * daemon token (#1051), so it is written owner-only — but a
+     * filesystem that cannot express that (Windows, a FAT volume) must not fail the write.
+     */
+    chmod?(path: string, mode: number): Promise<void>;
+}
+/** A {@link RegistryFs} backed by `node:fs/promises`. See {@link nodeFs}. */
+export declare function nodeRegistryFs(): RegistryFs;
+/**
+ * Keep only well-formed custom presets (#626): each needs a non-empty id, label, and prompt;
+ * label/prompt are trimmed and length-capped, the list capped at {@link CUSTOM_PRESET_LIMITS.count},
+ * and duplicate ids dropped. A malformed entry is skipped, not thrown — a bad registry never breaks the read.
+ */
+export declare function sanitizeCustomPresets(value: unknown): CustomPreset[];
+/**
+ * Read the whole registry. Forgiving: a missing / unreadable / malformed file — or one in a shape
+ * this no longer writes — yields an empty registry, never throws. Projects are deduped by resolved
+ * path and unknown preference fields are dropped.
+ */
+export declare function readRegistry(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<Registry>;
+/**
+ * Read the registry's project list. Forgiving: a missing / unreadable / malformed
+ * file yields `[]`, never throws. Deduped by resolved path, first wins.
+ */
+export declare function listProjects(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<ProjectRecord[]>;
+/**
+ * Register a project. Idempotent by resolved path: when the path is already
+ * registered, the existing record is returned untouched (addedAt survives);
+ * otherwise the new record is appended and the file written back (preferences preserved).
+ */
+export declare function addProject(path: string, addedAt: string, fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<ProjectRecord>;
+/**
+ * Take a project off the list, by id. Answers the record that was removed, or `undefined` when
+ * no project has that id. Only the list changes: nothing in the project's folder is touched, so
+ * a project whose folder is gone is removed like any other.
+ */
+export declare function removeProject(id: string, fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<ProjectRecord | undefined>;
+/** The user's dashboard preferences (#410), or `{}` when none are stored. */
+export declare function readPreferences(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<Preferences>;
+/** Persist the dashboard preferences (#410), sanitized, preserving the project list. */
+export declare function writePreferences(preferences: Preferences, fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * Merge `patch` over the stored preferences (#1148) and return the result.
+ *
+ * The counterpart to {@link writePreferences}, which replaces the whole block: a client that
+ * sends its entire snapshot replays every value it happens to hold, so a dashboard tab opened
+ * before someone else's change silently reverted it on the tab's next write, whatever key that
+ * write was actually about. Sending only the changed keys makes a write touch only what it names.
+ *
+ * Clearing needs no sentinel: {@link sanitizePreferences} already drops blank strings and empty
+ * lists, so `{ editor: '' }` merges in as blank and comes out absent, which is how the dashboard
+ * clears the editor today.
+ */
+export declare function patchPreferences(patch: Preferences, fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<Preferences>;
+/**
+ * The shared daemon token (#1051): read the persisted one, or generate + persist it now. Called
+ * only on a non-loopback bind, so a loopback-only machine never grows one. Serialized with the
+ * other mutators so two concurrent binds can't each write a different token. `base64url` of 32
+ * random bytes: URL-safe, so it drops straight into a `?token=` without encoding.
+ */
+export declare function ensureDaemonToken(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<string>;
+/** The persisted daemon token (#1051), or `undefined` when none exists. A pure read, so a process
+ * that only prints the reachable URL never generates one. */
+export declare function readDaemonToken(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/** A {@link PreferencesStore} bound to the real registry file, wired by the daemon so the
+ * dashboard's preferences RPCs read/write the user's home file.
+ *
+ * `onChange` is handed **the keys the caller wrote**, not the merged result, so a listener can
+ * tell "this write switched the setting on" from "it was already on and something else changed"
+ * (#1161). It runs after the write has landed, and its failure is swallowed: the save succeeded,
+ * and a listener must not be able to report otherwise: a setting saved in the browser has to
+ * reach the daemon's own services without a restart.
+ */
+export declare function registryPreferencesStore(fs?: RegistryFs, env?: NodeJS.ProcessEnv, onChange?: (written: Preferences) => void): PreferencesStore;

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

@@ -0,0 +1,53 @@
+import { type BranchesFor, type Checkout } from './branches.js';
+import { type AnyDiaryLine, type RunsFor } from './runs.js';
+/**
+ * A run's checkout, as the project's branches provider lists it, or `undefined` when it lists
+ * none for the id. The provider's list is shared for a few seconds; a run that is not in it may
+ * have started a moment ago, so a miss asks once more, fresh (`branches.ts` bounds how fresh).
+ */
+export declare function findCheckout(projectCwd: string, agentId: string, branches: BranchesFor, opts?: {
+    cached?: boolean;
+}): Promise<Checkout | undefined>;
+/**
+ * The checkout an agent id resolves to (#738/#797): the agent's own checkout while the project's
+ * branches provider lists one for it, else the project root. The list is asked fresh on a miss:
+ * a run that just started has its checkout before its tool has written the card (#766), and the
+ * event stream resolves its path once, when the browser opens it.
+ *
+ * An unknown or finished `agentId` falls back to the project root rather than failing: the
+ * run's checkout may already be gone, and the project's own state is still the sane thing to
+ * act on. This is the one resolution every run-addressed surface shares — the daemon's serve
+ * targets and previews, and each dashboard RPC — so the fallback rules cannot drift apart.
+ */
+export declare function resolveAgentCheckout(projectCwd: string, agentId: string | undefined, branches?: BranchesFor): Promise<string>;
+/**
+ * Where a run's diary is, for a reader that follows it: a file while the run has a checkout, the
+ * finished run's lines once it has none, or nowhere yet (`pending`): the run was started a moment
+ * ago and its tool has not made the checkout, so the reader asks again shortly.
+ */
+export type AgentDiarySource = {
+    file: string;
+} | {
+    finished: AnyDiaryLine[];
+} | {
+    pending: true;
+};
+/**
+ * The diary a run-scoped subscribe should follow (#1472, #1774): the run's own `<id>.jsonl`.
+ * While the run has a checkout it is a file there, under the checkout's `.openagent/`,
+ * written by the run's tool as the agent works. Once the run is recorded and its checkout
+ * reclaimed, it is the finished run's diary, whole, from the project's runs provider. A run that
+ * has neither yet was started a moment ago: its tool has not made the checkout, so the diary is
+ * nowhere yet, and the tail asks again (`../dashboard-rpc/events-tail.ts`). A project with no
+ * runs provider answers the same for a finished run: nowhere, where nothing more comes.
+ *
+ * `cached` answers from the shared lists only, never asking the checkouts fresh on a miss: for a
+ * reader that asks about a finished run for as long as it is open, in case it is resumed.
+ *
+ * Only the events tails resolve here; every other run-addressed surface keeps
+ * {@link resolveAgentCheckout}'s root fallback, where the project's own state is the sane
+ * thing to act on.
+ */
+export declare function resolveAgentDiary(projectCwd: string, agentId: string | undefined, runs?: RunsFor, branches?: BranchesFor, opts?: {
+    cached?: boolean;
+}): Promise<AgentDiarySource | undefined>;

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

@@ -0,0 +1,266 @@
+import type { OpenAgentEvent } from '../events.js';
+import { type BranchesFor, type Checkout } from './branches.js';
+import { type AnyDiaryLine, type RunsFor } from './runs.js';
+/**
+ * The read side of a project's runs (#1774). The daemon runs no agent and writes no run: a run's
+ * tool keeps the run's card (`<id>.json`) and diary (`<id>.jsonl`) under the `.openagent/`
+ * of the run's own checkout while it works, and a finished run is whatever the project's runs
+ * provider answers (`runs.ts`), when one of its packages provides them. The dashboard is a
+ * projection of those files and that answer.
+ */
+export type AgentStatus = 'running' | 'done' | 'stopped' | 'failed' | 'waiting';
+/**
+ * A queryable snapshot of the agent, derived entirely from the event log. Lets the
+ * dashboard render a header (and a future agent list) without parsing every line.
+ */
+export interface AgentMeta {
+    status: AgentStatus;
+    /** Stable, path-safe id for this agent (derived from {@link startedAt}). */
+    id: string;
+    /** ISO timestamp the store was opened (run start). */
+    startedAt: string;
+    /** ISO timestamp of the last event written. */
+    updatedAt: string;
+    /** ISO timestamp the run ended (the `end` event), absent while it is going. The skill's card field. */
+    endedAt?: string;
+    /** What the run cost so far in US dollars, summed over its `usage` events; absent until one says. The skill's card field. */
+    cost?: number;
+    /**
+     * The OS pid of the process running this run, on {@link host} — whatever process the project's
+     * start hook began. Recorded on the card so Stop has something to signal, and so a reader can
+     * tell a run that is working from one whose process died without recording an ending (#716).
+     */
+    pid?: number;
+    /** The host the owning {@link pid} lives on, so a pid probe only trusts a match (#716). */
+    host?: string;
+    /** What this session was asked for (from the `intent` event). */
+    intent?: string;
+    /**
+     * The run this one was started for, by its id: this run is that run's subagent. Written on the
+     * card by the tool that started it; absent on a run a person or a schedule started.
+     */
+    parent?: string;
+    /**
+     * The branch the run was told to start from, by its name: a person's local branch picked in the
+     * launcher, or, for a subagent, its main agent's branch. Written on the card by the tool that
+     * started it; absent on a run that started from origin's default branch.
+     */
+    base?: string;
+    /**
+     * The commit the run's own work begins at: where its branch was made, for a run started from a
+     * branch other than the default one (a subagent starts from its main agent's). Its changes are
+     * measured from it; absent, from the default branch. Written on the card by the tool that
+     * started it.
+     */
+    baseCommit?: string;
+    /**
+     * The last commit of the run's work, written on the card when its main agent landed it: its
+     * branch is gone, and its changes are read from this commit. Absent on a run that is not landed.
+     */
+    landed?: string;
+    /** The wrapped agent (from the `session` event). */
+    driver?: string;
+    /** The workspace the agent builds in (from the `session` event). */
+    workspace?: string;
+    /** The wrapped agent's real session id, once it reports one. */
+    sessionId?: string;
+    /** The link shown to jump into the live agent session. */
+    sessionLink?: string;
+    /**
+     * The branch the agent's work is on: the card's, and for a run with a checkout the branch that
+     * checkout has checked out right now (the branches provider reads it), since the agent renames
+     * its branch itself while the card learns the new name only when the run ends.
+     *
+     * Recorded, not derived: a clean agent loses its checkout, and the agent renames its branch
+     * itself (#1725), so no name built from the run's id is guaranteed to be the one holding the
+     * commits.
+     */
+    branch?: string;
+    /**
+     * The hand-off anchor a cloud run pushed for its session to clone at (#1601): an empty commit
+     * unique to this run, folded from the `cloud-anchor` event. The session works on a `claude/*`
+     * branch of the cloud's own naming, and this is the ancestor by which the daemon's adoption
+     * pass recognizes which of origin's `claude/*` heads is this run's. Absent on non-web runs
+     * and on web runs whose pre-hand-off push failed.
+     */
+    cloudAnchor?: string;
+    /**
+     * The pull request this session's work is on (E6), recorded when one is opened rather than
+     * re-derived from branch names and timestamps by every surface that wants it.
+     */
+    pr?: {
+        number: number;
+        url: string;
+    };
+    /**
+     * What this session's end-of-session handoff is armed to do (#1102): push its branch, and open
+     * a draft PR for it. Both start on.
+     *
+     * On the meta because the checkboxes that show it live in a different process from the agent that
+     * obeys it, and a tab opened after the agent started has no event history to fold — the same
+     * reason {@link browserStreamPort} is here. Absent means an older agent, which the reader treats
+     * as armed, matching what that agent will actually do.
+     *
+     * `merge` mirrors the auto-merge arming (#1216, #1382) — display-only, like the rest of this
+     * field: the agent merges off its own config, never off the meta. Absent on records from before
+     * #1382, which the reader treats as off.
+     */
+    handoff?: {
+        push: boolean;
+        pr: boolean;
+        merge?: boolean;
+    };
+    /**
+     * How the handoff's merge half went (#1418), folded from the `handoff` event's `merge` field.
+     *
+     * What the daemon's CI watch scans for: `watched` is a PR waiting for green that *this* side
+     * must merge (the repo could not arm the git host's auto-merge), `auto-armed` one the git host will land by
+     * itself but whose checks going red is still ours to notice. On the meta because the watch
+     * reads metas, not event logs, and must survive both the agent's process and the daemon's.
+     * Absent on runs from before this field, and on every agent whose handoff had no merge to report.
+     */
+    mergeOutcome?: 'auto-armed' | 'merged' | 'watched' | 'withheld' | 'failed';
+    /**
+     * The choice gate the agent is currently parked on (#636): set when a `choice` event fires and
+     * cleared when its `choice-resolved` (or the agent's `end`) arrives. Present means the agent is
+     * paused waiting for the user's answer — the second "needs you" source after open PRs (#624).
+     */
+    pendingChoice?: {
+        id: string;
+        title: string;
+    };
+    /**
+     * The browser bridge holds a question this run's cloud session is parked on (#1668). Not stored:
+     * the daemon annotates a web run's record on the way to the dashboard, the way a relayed run's
+     * label is, because the bridge store is in memory and the archive on disk knows nothing of it.
+     */
+    cloudWaiting?: boolean;
+    /**
+     * The run was started by another machine's daemon (#1648): its {@link host} is not this one.
+     * Not stored either — annotated on the way to the dashboard like {@link cloudWaiting}, since
+     * the shared data branch shows every machine's runs here and only this daemon knows which host
+     * it is.
+     */
+    otherHost?: boolean;
+    /**
+     * The run ended clean and its process is still alive on this host: the tool that runs it is
+     * still saving its record and cleaning up its checkout, the window every surface says "saving…" for.
+     * Not stored: annotated on the way to the dashboard like {@link otherHost}, since only this
+     * machine can ask whether the process is alive.
+     */
+    saving?: boolean;
+    /**
+     * 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
+     * dashboard is a different process, so meta is the only place it can learn it.
+     */
+    browserStreamPort?: number;
+    /**
+     * Where this run executes (#1050/#1053/#610): `actions` for a GitHub Actions run, `web` for a
+     * Claude Code cloud session, `remote` when relayed to a connected device (#1067), absent for a
+     * local run. Persisted so the agent view can tell a burst-mode Actions run from a stalled live
+     * feed, show a cloud agent's session link after a reload, and gate the browser pane off (#1053).
+     */
+    target?: 'local' | 'actions' | 'remote' | 'web';
+    /** The connected device a remote agent (#1067) executes on, for the session list + notice after a reload. */
+    remoteLabel?: string;
+    /**
+     * The flow this agent started under (#1467): `build` for the scope→build orchestration, `prompt`
+     * for the direct-prompt path (research and transparent runs record `prompt` too). Persisted so a
+     * continuation (#762) can re-enter the flow its first leg ran — the composer's Resume always
+     * arrives as a `prompt` start, and without this record a resumed build agent ended as a bare
+     * prompt session (no synthesize framing, no backlog offer). Absent on records from before this
+     * field, which a reader treats as unknown (the continuation then keeps the prompt path).
+     */
+    kind?: 'build' | 'prompt';
+    /**
+     * The model id the current leg's agent was started with (#1438), folded from each leg's
+     * `session` event — a continuation (#762) may run a different model than the first leg, so
+     * the latest leg wins rather than the first pinning it. Absent when the leg left the agent
+     * on its own default (and on records from before this field).
+     */
+    model?: string;
+}
+/**
+ * The slice of a filesystem the store's reads need: the logic is testable with an in-memory fs,
+ * and only {@link nodeStoreFs} touches disk.
+ */
+export interface StoreFs {
+    read(path: string): Promise<string>;
+    write(path: string, contents: string): Promise<void>;
+    append(path: string, contents: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string): Promise<void>;
+    /** List a directory's entries (names only). Missing dir yields `[]`. */
+    readdir(path: string): Promise<string[]>;
+}
+/**
+ * A project's finished runs, most-recent first: what its runs provider answers, unfolded into
+ * OpenAgent's meta. No provider, or one that cannot be read, is no runs, never a throw.
+ *
+ * `since` (epoch ms) is for a caller that only wants recent runs — a poll on a cadence, not the
+ * history list. `fresh` asks the provider past its last answer: the caller knows a run just finished.
+ */
+export declare function listAgents(cwd: string, runs?: RunsFor, opts?: {
+    since?: number;
+    fresh?: boolean;
+}): Promise<AgentMeta[]>;
+/**
+ * One finished run's whole diary, from the project's runs provider: for a reader that follows a
+ * run past its checkout. `undefined` for an unknown or unsafe id, a project with no provider, and
+ * a record that still says `running` — the marker a run's tool may leave as it starts, before its
+ * checkout exists: that run is not finished, its diary is still to come in the checkout.
+ */
+export declare function readFinishedDiary(cwd: string, agentId: string, runs?: RunsFor): Promise<AnyDiaryLine[] | undefined>;
+/**
+ * Whether `pid` is a live process on this host. `process.kill(pid, 0)` sends no signal but
+ * throws `ESRCH` once the process is gone; `EPERM` means it exists under another user (still
+ * alive). A pid on a *different* host is unknowable here, so callers guard on {@link AgentMeta.host}
+ * before trusting a result. A recycled pid (another process reusing a dead agent's number) reads as
+ * alive — an accepted, vanishingly rare miss on a single dev box.
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * The run a checkout holds, off its live card, `<id>.json` under the checkout's `.openagent/`:
+ * the shape agent-driver's log writes, read as the meta the card unfolds to, `running` or not (a
+ * run that ended waiting on a question keeps its checkout), on the branch the checkout is on now
+ * (the provider read it), since the agent renames its branch itself while its card learns the new
+ * name only when the run ends. `undefined` when there is no card.
+ * Never healed here: the tool that started the run sweeps its own dead runs.
+ */
+export declare function readLiveMeta(checkout: Checkout, fs?: StoreFs): Promise<AgentMeta | undefined>;
+/** A run with a checkout, plus that checkout (#738): where to read the run's git and file status from. */
+export interface LiveAgent extends AgentMeta {
+    /** The run's own checkout, a worktree under `.branches/`. */
+    cwd: string;
+}
+/**
+ * Every run of a project that has a checkout (#738): each checkout the project's branches
+ * provider lists, its card through {@link readLiveMeta}. Newest first, by id. Never throws: a
+ * project with no provider has no checkouts, and an unreadable checkout is skipped.
+ */
+export declare function readLiveMetas(cwd: string, fs?: StoreFs, branches?: BranchesFor): Promise<LiveAgent[]>;
+/**
+ * One run's events, for a reader that replays them: the diary in the run's checkout while it has
+ * one (it is the newer of the two), else the finished run's diary from the runs provider.
+ * `undefined` for an unknown or unsafe id.
+ */
+export declare function loadAgentEvents(cwd: string, id: string, fs?: StoreFs, runs?: RunsFor, branches?: BranchesFor): Promise<OpenAgentEvent[] | undefined>;
+/**
+ * What each of the named runs is doing now, by id: the last thing its diary says it did (a tool
+ * it used, with what) or said, on one line. Only a run with a checkout whose card says `running`
+ * has an entry: an ended run is doing nothing, and its row says how it ended.
+ */
+export declare function readDoing(cwd: string, ids: readonly string[], fs?: StoreFs, branches?: BranchesFor): Promise<Record<string, string>>;
+/** A {@link StoreFs} backed by `node:fs/promises`. See {@link nodeFs}. */
+export declare function nodeStoreFs(): StoreFs;
+/**
+ * A project's runs: the ones with a checkout prepended to the finished ones, newest-first.
+ * Forgiving — a side that cannot be read simply contributes nothing.
+ *
+ * The checkout's card wins over the recorded one (#768): a resumed run has a record from its
+ * first leg AND is going again, and the record alone would show a running agent as finished.
+ */
+export declare function readAllAgents(cwd: string, fs?: StoreFs, runs?: RunsFor, branches?: BranchesFor): Promise<AgentMeta[]>;
+/** One run's meta by id, the checkout's card winning over the record: {@link readAllAgents}'s rule for a single row. */
+export declare function findAgent(cwd: string, agentId: string, fs?: StoreFs, runs?: RunsFor, branches?: BranchesFor): Promise<AgentMeta | undefined>;