@gaia-ai/addon-gaia-ui 0.6.4 → 0.6.5

package/dist/src/Agent/Component/agent-list/index.d.ts

@@ -0,0 +1,6 @@
+import type { HostedAgent } from '../../../types.js';
+/** A fixed-column flat table for the Ticket-Agents screen: header + one line per
+ *  live agent (its label · the project/group it runs for). One physical row per
+ *  entry, so the Kernel's `1 + index` selection math holds. The agents are the
+ *  host's live set (from `list(group)`); a finished agent drops out on refresh. */
+export declare function agentListRows(agents: HostedAgent[]): string[];

package/dist/src/Agent/Component/agent-list/index.js

@@ -0,0 +1,14 @@
+import { pad } from '../../../lib/format.js';
+/** A fixed-column flat table for the Ticket-Agents screen: header + one line per
+ *  live agent (its label · the project/group it runs for). One physical row per
+ *  entry, so the Kernel's `1 + index` selection math holds. The agents are the
+ *  host's live set (from `list(group)`); a finished agent drops out on refresh. */
+export function agentListRows(agents) {
+    const header = `${pad('AGENT', 32)} PROJECT`;
+    if (agents.length === 0)
+        return [header, 'No ticket agents.'];
+    return [
+        header,
+        ...agents.map((a) => `${pad(a.label || a.id, 32)} ${a.group}`),
+    ];
+}

package/dist/src/Agent/launch.d.ts

@@ -0,0 +1,25 @@
+import type { CreateFormPayload } from '../Entity/ticket/Form/create.js';
+import type { TuiAgentService } from '../types.js';
+/** The launch intent passed to {@link TuiAgentService.launch}. */
+export type CreateLaunch = Parameters<TuiAgentService['launch']>[0];
+/**
+ * Build the `ticket:create` launch intent for a project. The prompt is a pure
+ * pointer to WORKFLOW.md (the pre-filled form is passed via
+ * `$GAIA_NEW_TICKET_INPUT`); `GAIA_ID` is never inherited (a create must not be
+ * bound to a claimed ticket).
+ */
+export declare function buildCreateLaunch(opts: {
+    project: string;
+    cwd: string;
+    specPath?: string | undefined;
+    workflow?: string | undefined;
+    createPrompt?: string | undefined;
+    label?: string | undefined;
+}): CreateLaunch;
+/**
+ * A short human label for the agent list: the description's first line (capped to 40
+ * incl. the ellipsis), else "New <workflow>". GAIA-236 AC-8: it builds the `label`
+ * `buildCreateLaunch` takes, so it belongs to the module that builds the launch
+ * intent — moved from `Service/create-form.ts` unchanged.
+ */
+export declare function shortName(payload: CreateFormPayload): string;

package/dist/src/Agent/launch.js

@@ -0,0 +1,49 @@
+// Ticket-create launch request (AC-3). Pressing `n` starts an embedded agent
+// that runs the GAIA `ticket:create` workflow. This module is pure: it builds
+// the launch intent (prompt + env) the TUI hands to the injected agent host
+// (`services.agents.launch`); the host (herdr) owns transport + layout. No
+// node-pty / @xterm, no session object.
+const CREATE_PROMPT = 'Read the repository\'s WORKFLOW.md and follow its "Create ticket" section to ' +
+    'create a new GAIA ticket. Do not start work on the new ticket.';
+/**
+ * Build the `ticket:create` launch intent for a project. The prompt is a pure
+ * pointer to WORKFLOW.md (the pre-filled form is passed via
+ * `$GAIA_NEW_TICKET_INPUT`); `GAIA_ID` is never inherited (a create must not be
+ * bound to a claimed ticket).
+ */
+export function buildCreateLaunch(opts) {
+    const env = {
+        ...process.env,
+        TERM: 'xterm-256color',
+        GAIA_PROJECT: opts.project,
+    };
+    delete env.GAIA_ID;
+    if (opts.specPath)
+        env.GAIA_NEW_TICKET_INPUT = opts.specPath;
+    if (opts.workflow)
+        env.GAIA_WORKFLOW = opts.workflow;
+    return {
+        group: opts.project,
+        cwd: opts.cwd,
+        prompt: opts.createPrompt?.trim() || CREATE_PROMPT,
+        env,
+        isNew: true,
+        ...(opts.label !== undefined ? { label: opts.label } : {}),
+    };
+}
+/**
+ * A short human label for the agent list: the description's first line (capped to 40
+ * incl. the ellipsis), else "New <workflow>". GAIA-236 AC-8: it builds the `label`
+ * `buildCreateLaunch` takes, so it belongs to the module that builds the launch
+ * intent — moved from `Service/create-form.ts` unchanged.
+ */
+export function shortName(payload) {
+    const firstLine = payload.description
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (firstLine) {
+        return firstLine.length > 40 ? `${firstLine.slice(0, 39)}…` : firstLine;
+    }
+    return `New ${payload.workflow?.label ?? 'ticket'}`;
+}

package/dist/src/Component/tab-bar/index.d.ts

@@ -7,3 +7,14 @@ export interface DetailTab {
 export declare const DETAIL_TABS: DetailTab[];
 /** The tab bar as a single row; the active tab is bracketed. */
 export declare function tabBar(activeIndex: number): string;
+/** Where one detail tab sits inside the bar: `[start, end)` in display columns
+ *  from the bar's own first column. */
+export interface DetailTabSpan {
+    index: number;
+    start: number;
+    end: number;
+}
+/** The bar's own hit map, built from the SAME `segment`/`SEPARATOR` the rendered
+ *  bar is joined from — see `Component/top-tabs/index.ts`'s `topTabSpans` for the
+ *  full argument. */
+export declare function detailTabSpans(activeIndex: number): DetailTabSpan[];

package/dist/src/Component/tab-bar/index.js

@@ -1,3 +1,4 @@
+import { displayWidth } from '../../lib/width.js';
 // The ticket-detail screen is split into tabs so only one tab's content draws at
 // a time (keeps the fixed-height window small) — Sub-tickets + Referenced share a
 // Related tab, Comments is its own tab with collapsible entries (owned by the
@@ -16,7 +17,26 @@ export const DETAIL_TABS = [
     },
     { id: 'runs', label: 'Runs', headings: ['Runs'] },
 ];
+/** What joins two tabs in the rendered bar — part of neither tab's span. */
+const SEPARATOR = ' ';
+/** One tab's rendered segment: bracketed when active, space-padded otherwise. */
+const segment = (tab, index, activeIndex) => index === activeIndex ? `[${tab.label}]` : ` ${tab.label} `;
 /** The tab bar as a single row; the active tab is bracketed. */
 export function tabBar(activeIndex) {
-    return DETAIL_TABS.map((t, i) => i === activeIndex ? `[${t.label}]` : ` ${t.label} `).join(' ');
+    return DETAIL_TABS.map((t, i) => segment(t, i, activeIndex)).join(SEPARATOR);
+}
+/** The bar's own hit map, built from the SAME `segment`/`SEPARATOR` the rendered
+ *  bar is joined from — see `Component/top-tabs/index.ts`'s `topTabSpans` for the
+ *  full argument. */
+export function detailTabSpans(activeIndex) {
+    const spans = [];
+    let start = 0;
+    DETAIL_TABS.forEach((tab, index) => {
+        if (index > 0)
+            start += displayWidth(SEPARATOR);
+        const width = displayWidth(segment(tab, index, activeIndex));
+        spans.push({ index, start, end: start + width });
+        start += width;
+    });
+    return spans;
 }

package/dist/src/Component/ticket-detail/index.d.ts

@@ -1,6 +1,14 @@
 import type { TicketDetailDocument } from '../../types.js';
 import type { CommentItem } from '../comment-item/index.js';
 import type { Section } from '../section-list/index.js';
+/**
+ * The `expandedComments` set a freshly opened ticket detail starts with: the
+ * newest comment expanded, every older one collapsed.
+ *
+ * It lives beside the sort on purpose — "index 0 is the newest" is one module's
+ * invariant, so the kernel never needs to know which index that is.
+ */
+export declare function initialExpandedComments(document: TicketDetailDocument): Set<number>;
 /**
  * The ticket detail sections, each with an explicit empty state:
  * Description, Comments, Sub-tickets, Runs, Referenced tickets, Links,

package/dist/src/Component/ticket-detail/index.js

@@ -19,8 +19,71 @@ function refCount(document, name) {
     const data = document.data?.relationships?.[name]?.data;
     return Array.isArray(data) ? data.length : data ? 1 : 0;
 }
+/**
+ * Newest-first — the exact reversal of the server's total order
+ * (`CommentsItemList`: `created ASC, id ASC`), three keys applied in turn:
+ * `created` DESC, then `drupal_internal__id` DESC (the server's own monotonic
+ * key, so two comments written in the same second keep the server's relative
+ * order, reversed), then the resource `id` DESC.
+ *
+ * The third key exists to make the comparator TOTAL rather than leaning on
+ * `Array.prototype.sort` being stable in modern V8: the order must be
+ * *deterministic* — identical for the same comments in any input order, and
+ * defined even for a fixture or partial include that carries no
+ * `drupal_internal__id`. Stability would only preserve whatever order the
+ * include happened to arrive in.
+ *
+ * A missing or unparseable `created` sorts LAST (treated as the oldest), so a
+ * malformed row can never take the top slot and steal the default expansion.
+ */
+function compareCommentsNewestFirst(a, b) {
+    const at = Date.parse(asString(a.attributes?.created) ?? '');
+    const bt = Date.parse(asString(b.attributes?.created) ?? '');
+    const aUnknown = Number.isNaN(at);
+    const bUnknown = Number.isNaN(bt);
+    if (aUnknown !== bUnknown)
+        return aUnknown ? 1 : -1;
+    if (!aUnknown && at !== bt)
+        return bt - at;
+    const ai = Number(a.attributes?.drupal_internal__id);
+    const bi = Number(b.attributes?.drupal_internal__id);
+    if (!Number.isNaN(ai) && !Number.isNaN(bi) && ai !== bi)
+        return bi - ai;
+    // Code-unit comparison, not localeCompare: a locale-sensitive collation would
+    // put the "deterministic" back in the hands of the runtime's locale data.
+    const aid = a.id ?? '';
+    const bid = b.id ?? '';
+    return aid === bid ? 0 : aid < bid ? 1 : -1;
+}
+/**
+ * The document's `gaia_comment` includes, NEWEST FIRST.
+ *
+ * This is the single function both renderings read — `detailSections`' Comments
+ * section (→ `detailLines`, the non-TTY render) and `commentItems` (→ the
+ * interactive Comments tab) — so newest-first is one line of code and the two
+ * orders structurally cannot drift.
+ *
+ * It sorts the copy `filter` already allocated and NEVER `document.included`
+ * itself: that array is mixed (comments *plus* sub-tickets, runs and referenced
+ * tickets) and shared with those consumers, so an in-place sort would be an
+ * invisible side effect on someone else's input.
+ */
 function commentResources(document) {
-    return (document.included ?? []).filter((r) => r.type === 'gaia_comment--gaia_comment');
+    return (document.included ?? [])
+        .filter((r) => r.type === 'gaia_comment--gaia_comment')
+        .sort(compareCommentsNewestFirst);
+}
+/**
+ * The `expandedComments` set a freshly opened ticket detail starts with: the
+ * newest comment expanded, every older one collapsed.
+ *
+ * It lives beside the sort on purpose — "index 0 is the newest" is one module's
+ * invariant, so the kernel never needs to know which index that is.
+ */
+export function initialExpandedComments(document) {
+    return commentResources(document).length
+        ? new Set([0])
+        : new Set();
 }
 /**
  * The ticket detail sections, each with an explicit empty state:
@@ -108,9 +171,10 @@ export function commentItems(document) {
         return { type, author, created, bodyLines, preview: bodyLines[0] ?? '' };
     });
 }
-// The whole ticket-detail document flattened (all sections). Reserved helper —
-// currently unused by the interactive screen (which renders one tab at a time
-// via tabViewLines); kept as a tested convenience for a full-document render.
+// The whole ticket-detail document flattened (all sections) — the NON-TTY ticket
+// render, printed verbatim by the kernel when stdout is not a terminal
+// (`Kernel/tui-kernel.ts:147`), i.e. what `gaia ui GAIA-nnn | cat` shows. The
+// interactive screen renders one tab at a time via tabViewLines instead.
 export function detailLines(detail) {
     return flattenSections(detailSections(detail ?? {}));
 }

package/dist/src/Component/top-tabs/index.d.ts

@@ -3,6 +3,120 @@ export interface TopTab {
     id: string;
     label: string;
 }
-export declare const TOP_TABS: TopTab[];
-/** The top tab bar as a single row; the active tab is bracketed. */
-export declare function topTabBar(activeId: string): string;
+/** The root level: what there is before a project is chosen. */
+export declare const ROOT_TABS: readonly [{
+    readonly id: "projects";
+    readonly label: "Projects";
+}];
+/** The project level: the tabs of an opened project. */
+export declare const PROJECT_TABS: readonly [{
+    readonly id: "tickets";
+    readonly label: "Tickets";
+}, {
+    readonly id: "ticket-agents";
+    readonly label: "Ticket-Agents";
+}, {
+    readonly id: "runs";
+    readonly label: "Runs";
+}];
+/** The tab bars, keyed by level — the one place a level is named. */
+export declare const TAB_LEVELS: {
+    readonly root: readonly [{
+        readonly id: "projects";
+        readonly label: "Projects";
+    }];
+    readonly project: readonly [{
+        readonly id: "tickets";
+        readonly label: "Tickets";
+    }, {
+        readonly id: "ticket-agents";
+        readonly label: "Ticket-Agents";
+    }, {
+        readonly id: "runs";
+        readonly label: "Runs";
+    }];
+};
+/** The name of a level that carries a top-level tab bar. */
+export type TabLevel = keyof typeof TAB_LEVELS;
+/** The ids of one level's tabs, derived from {@link TAB_LEVELS}. */
+export type TabIdOf<L extends TabLevel> = (typeof TAB_LEVELS)[L][number]['id'];
+/**
+ * The id of any top-level tab, derived — never re-listed. Before GAIA-239 this
+ * union was hand-written in `tui-kernel.ts` alongside a third hardcoded copy of
+ * the same ids for the Tab cycle order; the three could drift silently.
+ */
+export type TopTabId = {
+    [L in TabLevel]: TabIdOf<L>;
+}[TabLevel];
+/**
+ * Where a screen sits in the navigation: which bar it draws, and which tab of
+ * that bar is its own. A discriminated union over the levels, so a location can
+ * never pair one level's name with another level's tab id.
+ */
+export type TabLocation = {
+    [L in TabLevel]: {
+        level: L;
+        tab: TabIdOf<L>;
+    };
+}[TabLevel];
+/**
+ * One level's tab bar as a single row; the active tab is bracketed.
+ *
+ * The level is part of the signature on purpose: it is what keeps the id checked
+ * at compile time now that there is more than one bar. `topTabBar('root', 'runs')`
+ * is a TS2345 naming the root level's valid ids — not a bar that silently
+ * brackets nothing.
+ */
+export declare function topTabBar<L extends TabLevel>(level: L, activeId: TabIdOf<L>): string;
+/**
+ * The same bar, for a caller holding a whole {@link TabLocation} rather than a
+ * literal level. The pairing was already checked when the location was built, so
+ * this needs no second check — and unlike `topTabBar(loc.level, loc.tab)` it does
+ * not ask the compiler to correlate two independently narrowed properties.
+ */
+export declare function tabBarFor(location: TabLocation): string;
+/**
+ * Which level a tab id belongs to, as a whole {@link TabLocation} — or `null`
+ * for an id no level declares.
+ *
+ * The cast is the one place the level→id pairing is asserted rather than
+ * checked, and it is sound by construction: the id was just found **in that
+ * level's own registry**, which is exactly what `TabLocation` requires.
+ * TypeScript cannot see that through the `Object.keys` loop, so it is stated
+ * here once, behind a checked lookup, instead of at every call site.
+ */
+export declare function locateTab(tab: TopTabId): TabLocation | null;
+/** Where one tab sits inside the bar: `[start, end)` in display columns from the
+ *  bar's own first column. */
+export interface TopTabSpan<Id extends string = TopTabId> {
+    id: Id;
+    start: number;
+    end: number;
+}
+/**
+ * One level's own hit map, built from the SAME `segment`/`SEPARATOR` that level's
+ * rendered bar is joined from — so the layout and the click mapping are two
+ * readings of one expression and cannot drift apart. That is the argument
+ * `lib/hit-test.ts` makes for the body rows, applied to a column axis.
+ *
+ * Offsets are display columns, which is the unit a mouse report carries. For the
+ * current ASCII labels that coincides with string offsets, which is what lets
+ * the test slice `topTabBar()` with a span and compare.
+ *
+ * GAIA-239: the LEVEL is part of the signature, exactly as it is for
+ * {@link topTabBar}, and for the same reason twice over. GAIA-241 shipped one
+ * `topTabSpans(activeId)` over the single flat bar; read level-blind it would
+ * publish the project bar's three spans on the root screen too, so a click at
+ * the column where `Ticket-Agents` used to sit would open a tab that screen does
+ * not draw — the very defect this ticket removes, arriving through the mouse.
+ * A map and a bar of two different levels is now a TS2345, not a silent
+ * mis-click.
+ */
+export declare function topTabSpans<L extends TabLevel>(level: L, activeId: TabIdOf<L>): TopTabSpan<TabIdOf<L>>[];
+/**
+ * The same hit map, for a caller holding a whole {@link TabLocation} — the
+ * companion of {@link tabBarFor}, and the pairing it needs was already checked
+ * when the location was built. Keeping the two in step is what makes "the bar you
+ * see is the bar you click" true by construction: both read `location`.
+ */
+export declare function tabSpansFor(location: TabLocation): TopTabSpan[];

package/dist/src/Component/top-tabs/index.js

@@ -1,13 +1,129 @@
-// The top-level navigation tabs. `tickets` is the project/ticket drill-down;
-// `ticket-agents` is the managed create-agent list (GAIA-190); `runs` is the
-// project-scoped run overview (GAIA-192). `conductors` is a planned follow-up
-// (tracked separately) — not wired yet.
-export const TOP_TABS = [
+import { displayWidth } from '../../lib/width.js';
+// GAIA-239: THE registry — the single place the set, the order and the labels of
+// the top-level tabs are written. Navigation has THREE levels, and every screen
+// shows exactly ONE tab bar: the one of its own level.
+//
+//   root     dashboard, project-picker            → Projects
+//   project  project, ticket-agents, project-runs → Tickets · Ticket-Agents · Runs
+//   ticket   ticket                               → the DETAIL tabs, drawn as the
+//                                                    header box's meta row, so no
+//                                                    top-level bar at all
+//
+// `tickets` is the project/ticket drill-down; `ticket-agents` is the managed
+// create-agent list (GAIA-190); `runs` is the project-scoped run overview
+// (GAIA-192) — all three project-scoped, which is why they sit on the project
+// level and not on the root one.
+//
+// Only tabs that are actually navigable are listed. A planned screen (`Users` on
+// the root level, `Conductors` on the project level) arrives with its own ticket
+// and adds its entry here then — a tab drawn before its screen exists would
+// advertise navigation the operator cannot take, which is the very defect
+// GAIA-239 removes.
+//
+// `as const satisfies` is load-bearing on both halves: `satisfies` still
+// shape-checks every entry against `TopTab`, while `as const` keeps the literal
+// ids so the id unions below can be DERIVED from them. A plain `: TopTab[]`
+// annotation would widen `id` to `string` and the derivation would collapse to
+// `string`, taking the compile-time check with it.
+/** The root level: what there is before a project is chosen. */
+export const ROOT_TABS = [
+    { id: 'projects', label: 'Projects' },
+];
+/** The project level: the tabs of an opened project. */
+export const PROJECT_TABS = [
     { id: 'tickets', label: 'Tickets' },
     { id: 'ticket-agents', label: 'Ticket-Agents' },
     { id: 'runs', label: 'Runs' },
 ];
-/** The top tab bar as a single row; the active tab is bracketed. */
-export function topTabBar(activeId) {
-    return TOP_TABS.map((t) => t.id === activeId ? `[${t.label}]` : ` ${t.label} `).join('  ');
+/** The tab bars, keyed by level — the one place a level is named. */
+export const TAB_LEVELS = {
+    root: ROOT_TABS,
+    project: PROJECT_TABS,
+};
+/** What joins two tabs in the rendered bar — part of neither tab's span. */
+const SEPARATOR = '  ';
+/** One tab's rendered segment: bracketed when active, space-padded otherwise. */
+const segment = (tab, activeId) => tab.id === activeId ? `[${tab.label}]` : ` ${tab.label} `;
+const renderBar = (tabs, activeId) => tabs.map((t) => segment(t, activeId)).join(SEPARATOR);
+/**
+ * One level's tab bar as a single row; the active tab is bracketed.
+ *
+ * The level is part of the signature on purpose: it is what keeps the id checked
+ * at compile time now that there is more than one bar. `topTabBar('root', 'runs')`
+ * is a TS2345 naming the root level's valid ids — not a bar that silently
+ * brackets nothing.
+ */
+export function topTabBar(level, activeId) {
+    return renderBar(TAB_LEVELS[level], activeId);
+}
+/**
+ * The same bar, for a caller holding a whole {@link TabLocation} rather than a
+ * literal level. The pairing was already checked when the location was built, so
+ * this needs no second check — and unlike `topTabBar(loc.level, loc.tab)` it does
+ * not ask the compiler to correlate two independently narrowed properties.
+ */
+export function tabBarFor(location) {
+    return renderBar(TAB_LEVELS[location.level], location.tab);
+}
+/**
+ * Which level a tab id belongs to, as a whole {@link TabLocation} — or `null`
+ * for an id no level declares.
+ *
+ * The cast is the one place the level→id pairing is asserted rather than
+ * checked, and it is sound by construction: the id was just found **in that
+ * level's own registry**, which is exactly what `TabLocation` requires.
+ * TypeScript cannot see that through the `Object.keys` loop, so it is stated
+ * here once, behind a checked lookup, instead of at every call site.
+ */
+export function locateTab(tab) {
+    for (const level of Object.keys(TAB_LEVELS)) {
+        const tabs = TAB_LEVELS[level];
+        if (tabs.some((t) => t.id === tab)) {
+            return { level, tab };
+        }
+    }
+    return null;
+}
+const renderSpans = (tabs, activeId) => {
+    const spans = [];
+    let start = 0;
+    tabs.forEach((tab, index) => {
+        if (index > 0)
+            start += displayWidth(SEPARATOR);
+        const width = displayWidth(segment(tab, activeId));
+        spans.push({ id: tab.id, start, end: start + width });
+        start += width;
+    });
+    return spans;
+};
+/**
+ * One level's own hit map, built from the SAME `segment`/`SEPARATOR` that level's
+ * rendered bar is joined from — so the layout and the click mapping are two
+ * readings of one expression and cannot drift apart. That is the argument
+ * `lib/hit-test.ts` makes for the body rows, applied to a column axis.
+ *
+ * Offsets are display columns, which is the unit a mouse report carries. For the
+ * current ASCII labels that coincides with string offsets, which is what lets
+ * the test slice `topTabBar()` with a span and compare.
+ *
+ * GAIA-239: the LEVEL is part of the signature, exactly as it is for
+ * {@link topTabBar}, and for the same reason twice over. GAIA-241 shipped one
+ * `topTabSpans(activeId)` over the single flat bar; read level-blind it would
+ * publish the project bar's three spans on the root screen too, so a click at
+ * the column where `Ticket-Agents` used to sit would open a tab that screen does
+ * not draw — the very defect this ticket removes, arriving through the mouse.
+ * A map and a bar of two different levels is now a TS2345, not a silent
+ * mis-click.
+ */
+export function topTabSpans(level, activeId) {
+    return renderSpans(TAB_LEVELS[level], activeId);
+}
+/**
+ * The same hit map, for a caller holding a whole {@link TabLocation} — the
+ * companion of {@link tabBarFor}, and the pairing it needs was already checked
+ * when the location was built. Keeping the two in step is what makes "the bar you
+ * see is the bar you click" true by construction: both read `location`.
+ */
+export function tabSpansFor(location) {
+    return renderSpans(TAB_LEVELS[location.level], location.tab);
 }

package/dist/src/Entity/conductor/Data/conductors.d.ts

@@ -0,0 +1,22 @@
+import type { DropshClient } from '../../../types.js';
+import { type OptionClients } from '../../transport.js';
+/** One conductor of the control plane, as this renderer needs it. */
+export interface Conductor {
+    id: string;
+    /** Never empty — the uuid is the last fallback, so nothing renders as blank. */
+    label: string;
+    /** The machine the conductor runs on. */
+    machineId: string | undefined;
+    /** Liveness, as the control plane reports it. */
+    status: string | undefined;
+    /** The conductor's project, `null` when unlinked. */
+    projectId: string | null;
+}
+/** The conductor collection through one client, in server order. */
+export declare const listConductors: (client: DropshClient) => Promise<Conductor[]>;
+/**
+ * The same collection read through the WRITE client where there is one — still just
+ * reading, but the write scope is the one that decides what a write may reference,
+ * and `pm` sees the FULL conductor set where `session` sees a subset.
+ */
+export declare const listConductorsPreferringWrite: (clients: OptionClients) => Promise<Conductor[]>;

package/dist/src/Entity/conductor/Data/conductors.js

@@ -0,0 +1,17 @@
+import { list, listPreferringWrite, } from '../../transport.js';
+const str = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
+const toConductor = (r) => ({
+    id: r.id,
+    label: str(r.attr('label')) ?? str(r.attr('machine_id')) ?? r.id,
+    machineId: str(r.attr('machine_id')),
+    status: str(r.attr('status')),
+    projectId: r.rel('project_id'),
+});
+/** The conductor collection through one client, in server order. */
+export const listConductors = (client) => list(client, 'gaia_conductor', toConductor);
+/**
+ * The same collection read through the WRITE client where there is one — still just
+ * reading, but the write scope is the one that decides what a write may reference,
+ * and `pm` sees the FULL conductor set where `session` sees a subset.
+ */
+export const listConductorsPreferringWrite = (clients) => listPreferringWrite(clients, 'gaia_conductor', toConductor);

package/dist/src/Entity/conductor/Data/liveness.d.ts

@@ -0,0 +1,10 @@
+/** The derived liveness state of a conductor. */
+export type ConductorStatus = 'running' | 'stale' | 'offline' | 'registry-only';
+/** The raw liveness inputs derived from a `gaia_conductor` record. */
+export interface ConductorInput {
+    present?: boolean;
+    status?: string | null;
+    lastSeen?: number | null;
+    leaseExpiresAt?: number | null;
+}
+export declare function deriveConductorStatus(conductor: ConductorInput, nowSeconds: number): ConductorStatus;

package/dist/src/Entity/conductor/Data/liveness.js

@@ -0,0 +1,25 @@
+// Conductor liveness derivation. Mirrors the server-side ConductorDeriver
+// (web/modules/custom/gaia_core/modules/gaia_dashboard/src/Dashboard/ConductorDeriver.php)
+// and the CLI `classify()` in gaia-cli/conductor/src/commands/conductor.ts:
+// no gaia_conductor record → registry-only; status 'offline' → offline; else
+// stale when last_seen older than 600s OR the lease has expired; else running.
+const STALE_WINDOW_SECONDS = 600;
+export function deriveConductorStatus(conductor, nowSeconds) {
+    if (!conductor?.present)
+        return 'registry-only';
+    if (conductor.status === 'offline')
+        return 'offline';
+    if (conductor.lastSeen == null)
+        return 'stale';
+    if (nowSeconds - conductor.lastSeen > STALE_WINDOW_SECONDS)
+        return 'stale';
+    if (conductor.leaseExpiresAt != null &&
+        conductor.leaseExpiresAt < nowSeconds) {
+        return 'stale';
+    }
+    return 'running';
+}
+// `humanizeAge` moved to `lib/format.ts` (GAIA-236, entity-slice Phase 0): it is a
+// generic relative-time formatter with no conductor vocabulary, and keeping it here
+// is what made `Component/comment-item` and `Deriver/run-status` import a CONDUCTOR
+// module. Its test moved with it, to `tests/lib/format.test.ts`.

package/dist/src/Entity/project/Component/dashboard-list/index.d.ts

@@ -0,0 +1,8 @@
+/** The minimum shape a dashboard row needs to render. */
+export interface DashboardRowInput {
+    project: string;
+    derivedStatus: string;
+    ageLabel: string;
+}
+/** One line per project: name, derived status, relative age. */
+export declare function dashboardRows(projects: DashboardRowInput[]): string[];

package/dist/src/Entity/project/Component/dashboard-list/index.js

@@ -0,0 +1,7 @@
+import { pad } from '../../../../lib/format.js';
+/** One line per project: name, derived status, relative age. */
+export function dashboardRows(projects) {
+    if (projects.length === 0)
+        return ['No projects.'];
+    return projects.map((p) => `${pad(p.project, 24)} ${pad(p.derivedStatus, 14)} ${p.ageLabel}`);
+}

package/dist/src/Entity/project/Component/project-picker/index.d.ts

@@ -0,0 +1,15 @@
+/** A project that claims the repo. */
+export interface PickerCandidate {
+    id: string;
+    name: string;
+}
+/**
+ * The picker screen's rows: a heading naming the repo, then one row per
+ * candidate with `▸` on the selected one.
+ */
+export declare function projectPickerRows(candidates: PickerCandidate[], repo: string, selected: number): string[];
+/**
+ * The non-TTY form (spec Decision 11): the candidate list plus the direct
+ * command, printed once so `gaia ui --here | cat` stays scriptable — no prompt.
+ */
+export declare function projectPickerHint(candidates: PickerCandidate[], repo: string): string;