@gaia-ai/addon-gaia-ui 0.12.0 → 0.13.0

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

@@ -402,6 +402,16 @@ export interface ConductorQuery {
  * is the convention's cost, not this read's decision to make.
  */
 export declare const listConductorRowPage: (client: DropshClient, ctx: ConductorRowContext, query: ConductorQuery, page?: number) => Promise<Page<ConductorRow>>;
+/**
+ * A single conductor's own `last_seen`, or `undefined` when the record has
+ * none or the read fails.
+ *
+ * GAIA-477 AC-5: the cockpit's `act('start', …)` polls this after a spawn,
+ * comparing against the row's `lastSeen` captured before the start, to tell
+ * a genuine new heartbeat apart from a stale one still in the window — the
+ * same distinction the CLI's `waitForFreshHeartbeat` makes server-side.
+ */
+export declare const fetchConductorLastSeen: (client: DropshClient, id: string) => Promise<number | undefined>;
 /**
  * How large the collection under `query` is, or `null` when that is not
  * established (GAIA-460 D4).

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

@@ -428,6 +428,27 @@ export const listConductorRowPage = async (client, ctx, query, page = 0) => {
         return data.map((raw) => toConductorRow(raw, ctx, machinesById));
     }, page, window);
 };
+/**
+ * A single conductor's own `last_seen`, or `undefined` when the record has
+ * none or the read fails.
+ *
+ * GAIA-477 AC-5: the cockpit's `act('start', …)` polls this after a spawn,
+ * comparing against the row's `lastSeen` captured before the start, to tell
+ * a genuine new heartbeat apart from a stale one still in the window — the
+ * same distinction the CLI's `waitForFreshHeartbeat` makes server-side.
+ */
+export const fetchConductorLastSeen = async (client, id) => {
+    try {
+        const doc = (await client.get(`gaia_conductor/gaia_conductor/${id}`));
+        const raw = doc?.data;
+        if (!raw)
+            return undefined;
+        return toUnixSeconds(asResource(raw).attr('last_seen')) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
 /**
  * How large the collection under `query` is, or `null` when that is not
  * established (GAIA-460 D4).

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

@@ -1,4 +1,5 @@
 import { type SignalOutcome } from '@gaia-ai/core';
+import type { DropshClient } from '../../../types.js';
 /** What a cockpit action reports back to its row. */
 export interface ConductorActionResult {
     ok: boolean;
@@ -35,6 +36,16 @@ export interface ConductorProcessDeps {
      * stop needs this machine's own value to compare against).
      */
     thisHostKey?: () => Promise<string>;
+    /**
+     * GAIA-477 AC-5: how `start` learns whether the spawn actually came online,
+     * injected so tests need no timers or network. Defaults to
+     * {@link fetchConductorLastSeen} against the real control plane.
+     */
+    fetchLastSeen?: (client: DropshClient, id: string) => Promise<number | undefined>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Bounded poll budget; small defaults so a real failure resolves quickly. */
+    heartbeatPollAttempts?: number;
+    heartbeatPollIntervalMs?: number;
 }
 export interface ConductorProcessHost {
     start(input: {
@@ -43,6 +54,15 @@ export interface ConductorProcessHost {
         /** The row's `host_key` (GAIA-450 review B5) — verified against this
          *  machine's own before anything is spawned. */
         hostKey: string | undefined;
+        /**
+         * GAIA-477 AC-5: the conductor's own record id and its `last_seen`
+         * captured before the spawn, and the client to poll with. Present only
+         * when the caller can observe the outcome — absent, `start` reports the
+         * spawn as before and never claims to have seen it come online.
+         */
+        id?: string | undefined;
+        priorLastSeen?: number | undefined;
+        client?: DropshClient | undefined;
     }): Promise<ConductorActionResult>;
     stop(input: {
         pid: number | undefined;

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

@@ -1,5 +1,6 @@
 import { spawn as nodeSpawn } from 'node:child_process';
 import { machineContextPath, readMachineContext, signalVerifiedProcess, } from '@gaia-ai/core';
+import { fetchConductorLastSeen } from './conductors.js';
 /**
  * This machine's host_key, from the same MachineContext the CLI reads.
  *
@@ -28,9 +29,13 @@ export function createConductorProcessHost(deps = {}) {
     const spawn = deps.spawn ?? defaultSpawn;
     const signal = deps.signal ?? signalVerifiedProcess;
     const thisHostKey = deps.thisHostKey ?? defaultThisHostKey;
+    const fetchLastSeen = deps.fetchLastSeen ?? fetchConductorLastSeen;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const heartbeatPollAttempts = deps.heartbeatPollAttempts ?? 5;
+    const heartbeatPollIntervalMs = deps.heartbeatPollIntervalMs ?? 1000;
     return {
         thisHostKey,
-        async start({ workspaceRoot, conductorName, hostKey }) {
+        async start({ workspaceRoot, conductorName, hostKey, id, priorLastSeen, client, }) {
             // GAIA-450 review B5: the only gate this used to have was `isLocal` — a
             // filesystem check on `workspaceRoot`, which answers "does this path
             // exist on THIS disk", not "is this THIS machine's conductor". Two
@@ -68,6 +73,30 @@ export function createConductorProcessHost(deps = {}) {
                         GAIA_CONDUCTOR_CONFIG: '',
                     },
                 });
+                // GAIA-477 AC-5: `spawn` settling only proves the fork happened, not
+                // that a foreground conductor is running under it — the herdr pane
+                // boundary this ticket's other fix crosses can still leave a row
+                // silently offline. Watch for a genuinely NEW heartbeat (never the
+                // stale one already on the row) over a bounded budget before telling
+                // the operator this succeeded, the same distinction the CLI's own
+                // `waitForFreshHeartbeat` makes.
+                if (id && client) {
+                    for (let attempt = 0; attempt < heartbeatPollAttempts; attempt += 1) {
+                        await sleep(heartbeatPollIntervalMs);
+                        const lastSeen = await fetchLastSeen(client, id);
+                        if (lastSeen !== undefined &&
+                            (priorLastSeen === undefined || lastSeen > priorLastSeen)) {
+                            return {
+                                ok: true,
+                                message: `starting ${conductorName ?? 'conductor'} in ${workspaceRoot}`,
+                            };
+                        }
+                    }
+                    return {
+                        ok: false,
+                        message: `${conductorName ?? 'conductor'} did not come online — spawned in ${workspaceRoot} but no fresh heartbeat arrived`,
+                    };
+                }
                 return {
                     ok: true,
                     message: `starting ${conductorName ?? 'conductor'} in ${workspaceRoot}`,

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

@@ -303,6 +303,9 @@ export class ConductorsScreen extends ListScreen {
                     workspaceRoot: row.workspaceRoot,
                     conductorName: row.conductorName,
                     hostKey: row.hostKey,
+                    id: row.id,
+                    priorLastSeen: row.lastSeen || undefined,
+                    client: context.services?.client,
                 })
                 : await host.stop({
                     pid: row.lastPid,

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

@@ -1,6 +1,6 @@
 import type { VNode } from '@opentui/core';
-import type { Section } from '../../../../Component/section-list/index.js';
-import type { PanelSection } from '../../../../Extension/contract.js';
+import type { Section, SectionLine } from '../../../../Component/section-list/index.js';
+import type { PanelColumn, PanelSection } from '../../../../Extension/contract.js';
 import { type StyledLine } from '../../../../lib/vnode.js';
 import type { TicketDetailDocument } from '../../../../types.js';
 import type { CommentItem } from '../comment-item/index.js';
@@ -142,6 +142,35 @@ export declare function detailLines(detail?: TicketDetailDocument | null, labels
     boldRows: Set<number>;
 };
 /** One rendered ticket section: its body, and the selection map into it. */
+/** A row of a contributed table — identity is required, the rest is the addon's. */
+export interface PanelTableRow {
+    readonly id: string;
+}
+/**
+ * GAIA-475 — what the screen resolved out of a `UiTable`, ready to lay out.
+ *
+ * Data only, and deliberately not the `UiTable` itself: by the time it reaches
+ * here `columns()` and `rows()` have already been called inside the screen's
+ * error boundary, so this component never invokes contributed code and cannot be
+ * the thing that throws.
+ */
+export interface PanelTableData {
+    /** The id prefix every node of this list carries; derived from the table id. */
+    readonly noun: string;
+    readonly columns: readonly PanelColumn<PanelTableRow>[];
+    readonly rows: readonly PanelTableRow[];
+    readonly emptyMessage: string;
+}
+/**
+ * GAIA-475 A4 — a contributed table as the PIPE's text, one serialisation reused.
+ *
+ * `listTableRows` is the same function the built-in lists print through, so the
+ * piped form of a contributed table is the piped form of every other list rather
+ * than a second renderer that drifts from it. It is also what keeps the contract
+ * honest: a contribution supplied data, so BOTH renderings are derivable, and
+ * neither is the addon's problem.
+ */
+export declare const panelTableLines: (data: PanelTableData) => SectionLine[];
 export interface TabView {
     /** GAIA-340 D1 — the tab's rows as the renderable tree the screen hands over. */
     readonly body: VNode;
@@ -235,7 +264,7 @@ export declare function firstLineSummary(lines: readonly StyledLine[]): StyledLi
  * off — the Runs tab, by contrast, is one node per run plus six cells and is
  * bounded by the document's sideloaded runs.
  */
-export declare function tabViewTree(detail: TicketDetailDocument | null | undefined, tabIndex: number, { expanded, nowSeconds, labels, selectedIndex, panelSections, }?: {
+export declare function tabViewTree(detail: TicketDetailDocument | null | undefined, tabIndex: number, { expanded, nowSeconds, labels, selectedIndex, panelSections, panelTable, }?: {
     expanded?: ReadonlySet<number>;
     nowSeconds?: number;
     labels?: AssignmentLabels;
@@ -249,4 +278,14 @@ export declare function tabViewTree(detail: TicketDetailDocument | null | undefi
      * `PanelSection[]` contract (spec D4): an addon restates none of it.
      */
     panelSections?: readonly PanelSection[];
+    /**
+     * GAIA-475 — a contributed table's columns and rows, already resolved by the
+     * screen, exactly as `panelSections` is.
+     *
+     * Present ⇒ this tab is a TABLE and `tabIndex` names no built-in section.
+     * Resolved by the screen rather than here for the same reason `panelSections`
+     * is: the contribution is the SCREEN's dependency, and this stays a pure
+     * function of rows.
+     */
+    panelTable?: PanelTableData;
 }): TabView;

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

@@ -686,6 +686,37 @@ const EXPANDABLE_HEADINGS = new Set([
  * be one somewhere else, while `ticket-detail-description-0` is this screen's.
  */
 const BODY_ID = 'ticket-detail';
+/**
+ * The contributed table as the `ListTable` the host's renderer speaks.
+ *
+ * A translation and nothing more — `fields` is `[]` because sparse fieldsets are
+ * a JSON:API query's business and a contribution issues none, and `get` drops the
+ * `Ctx` argument because a contribution's context arrived with `PanelRender`.
+ */
+const listTableOf = (data) => ({
+    noun: data.noun,
+    emptyMessage: data.emptyMessage,
+    columns: data.columns.map((column) => ({
+        key: column.key,
+        label: column.label,
+        width: column.width,
+        fields: [],
+        ...(column.min !== undefined ? { min: column.min } : {}),
+        ...(column.max !== undefined ? { max: column.max } : {}),
+        ...(column.grow !== undefined ? { grow: column.grow } : {}),
+        get: (row) => column.get(row),
+    })),
+});
+/**
+ * GAIA-475 A4 — a contributed table as the PIPE's text, one serialisation reused.
+ *
+ * `listTableRows` is the same function the built-in lists print through, so the
+ * piped form of a contributed table is the piped form of every other list rather
+ * than a second renderer that drifts from it. It is also what keeps the contract
+ * honest: a contribution supplied data, so BOTH renderings are derivable, and
+ * neither is the addon's problem.
+ */
+export const panelTableLines = (data) => listTableRows(listTableOf(data), data.rows, undefined);
 /**
  * One expandable entry: the caret header, the D1 extract while collapsed, the
  * whole body while expanded.
@@ -853,7 +884,7 @@ function sectionTabRows(sections, { expanded, expandableHeadings = EXPANDABLE_HE
  * off — the Runs tab, by contrast, is one node per run plus six cells and is
  * bounded by the document's sideloaded runs.
  */
-export function tabViewTree(detail, tabIndex, { expanded = new Set(), nowSeconds = 0, labels, selectedIndex = -1, panelSections, } = {}) {
+export function tabViewTree(detail, tabIndex, { expanded = new Set(), nowSeconds = 0, labels, selectedIndex = -1, panelSections, panelTable, } = {}) {
     if (panelSections) {
         const sections = panelSections.map((section) => ({
             heading: section.heading,
@@ -871,6 +902,22 @@ export function tabViewTree(detail, tabIndex, { expanded = new Set(), nowSeconds
             keyOf: panelSectionKey,
         }), selectedIndex);
     }
+    // GAIA-475 A2 — a contributed TABLE, mapped onto the very machinery the `runs`
+    // branch below uses. Same `listTableTree`, same `1 + index` header arithmetic,
+    // same `listRowIds`: the contribution supplied columns and rows, and every
+    // question after that — layout, the header row, the highlight, the click map —
+    // is answered by code that already existed. That is the whole reason the
+    // contract carries data instead of a render tree.
+    if (panelTable) {
+        const { rows } = panelTable;
+        const table = listTableOf(panelTable);
+        return {
+            body: columnNode(BODY_ID, listTableTree(table, rows, undefined, { selectedIndex })),
+            headerRows: rows.map((_row, index) => 1 + index),
+            selectable: rows.length,
+            rowIds: listRowIds(table, rows),
+        };
+    }
     const id = TICKET_SECTIONS[tabIndex]?.id;
     if (id === 'runs') {
         const runs = ticketRunRows(detail ?? {});

package/dist/src/Entity/ticket/Screen/ticket-detail.d.ts

@@ -57,6 +57,25 @@ export declare class TicketDetailScreen extends AsyncScreen<TicketDetailDocument
      */
     selectTopTab(tabId: string, context: ScreenContext): boolean;
     reload(context: ScreenContext): void;
+    /**
+     * GAIA-475 criterion 24 — arm or cancel the table's self-refresh.
+     *
+     * Called wherever the OPEN TAB can change: `enter`, `selectTab`, and after an
+     * activation. A contributed table is a view of the machine rather than of the
+     * ticket — a Storybook started ten minutes into a run is not in any document
+     * the host fetched — so it is the one tab that has to re-read without being
+     * asked. The built-in tabs deliberately do not tick: their data comes from the
+     * API, and a timer on them would be a polling loop nobody asked for.
+     *
+     * What a tick does is the cheap half of `reload`: bump the token and redraw.
+     * It does NOT call `retry()`, so no HTTP request is made — the contribution
+     * re-reads its own source (the socket table, the state file) and everything
+     * the screen shows about the ticket is left exactly as it was.
+     */
+    private syncTableTick;
+    private armTableTick;
+    private cancelTableTick;
+    leave(): void;
     static readonly route: {
         id: string;
         path: string;
@@ -86,6 +105,19 @@ export declare class TicketDetailScreen extends AsyncScreen<TicketDetailDocument
      */
     private panelQuery;
     private panelParams;
+    /** GAIA-475 — the table rows whose `onActivate` is in flight. */
+    private activatingRows;
+    /** GAIA-475 A5 — bumped on every reload, handed to a table so it can drop its
+     *  cache. A counter, not a clock. */
+    private reloadToken;
+    /**
+     * GAIA-475 criterion 24 — the self-refresh, as its cancel function.
+     *
+     * Set while a contributed TABLE is the open tab, `undefined` otherwise, so the
+     * field's presence IS "a tick is armed" and there is no second flag to
+     * disagree with it.
+     */
+    private tableTick;
     /** GAIA-326 — the last copy's outcome, shown in the footer. Empty until the
      *  operator asks for one; see `copyOpenTicket`. */
     private status;
@@ -98,7 +130,7 @@ export declare class TicketDetailScreen extends AsyncScreen<TicketDetailDocument
     setLabels(labels: AssignmentLabels | undefined): void;
     selectTab(index: number, context: ScreenContext): boolean;
     select(index: number, context: ScreenContext): boolean;
-    activate(index: number, context: ScreenContext): boolean;
+    activate(index: number, context: ScreenContext, intent?: 'activate' | 'deactivate'): boolean;
     get document(): TicketDetailDocument | undefined;
     protected load(context: ScreenContext): Promise<TicketDetailDocument>;
     protected renderLoading(): string[];
@@ -178,8 +210,8 @@ export declare class TicketDetailScreen extends AsyncScreen<TicketDetailDocument
     reset(): void;
     private initialize;
     private currentView;
-    /** The panel the active index names, or none while a built-in is open. */
-    private activePanel;
+    /** The contribution the active index names, or none while a built-in is open. */
+    private activeContribution;
     /**
      * One panel's sections, with its own explicit empty state applied.
      *
@@ -206,5 +238,53 @@ export declare class TicketDetailScreen extends AsyncScreen<TicketDetailDocument
      * untouched, so `emptyMessage` still means "nothing to show", never "it
      * broke".
      */
+    /**
+     * GAIA-475 A3 — activate one table row, following the conductor screen's shape.
+     *
+     * Mark busy, redraw, await, record the outcome as the footer status, clear busy
+     * in a `finally`, redraw. The busy set is what makes a second Enter a no-op
+     * while the first is in flight (US-12) and what a cell reads through
+     * `PanelRender.activating` to show the work.
+     *
+     * The row is picked from the SAME guarded resolution the render uses
+     * (`tableView`), so the row `onActivate` receives is exactly the row the
+     * operator saw; a table whose `rows()` throws resolves to the error branch and
+     * simply has no row to activate.
+     */
+    private activateTableRow;
+    /** Tests and the busy indicator: the row ids whose activation is in flight. */
+    activatingRowIds(): string[];
+    /**
+     * One contributed table's columns and rows — `panelSections`' twin (GAIA-475).
+     *
+     * Returns the OPTION BAG `tabViewTree` takes rather than the data directly,
+     * because a failure has to change WHICH branch renders: there is no such thing
+     * as a table of an error. On a throw this degrades to `panelSections`, so a
+     * broken table produces the same named, readable failure row a broken panel
+     * does — one rendering of "this addon broke", not two.
+     *
+     * The same chokepoint argument applies here as there, and more sharply: both
+     * `columns()` and `rows()` are contributed code, both run on the draw path, and
+     * the draw path is not uniformly guarded (`Kernel/tui-kernel.ts` wires `draw`
+     * straight onto the resize and mouse-scroll events). A throw out of either one
+     * would freeze or crash the cockpit.
+     *
+     * `noun` replaces `/` with `-` because the id is org-prefixed by convention
+     * (`gaia/ports`) and it becomes a node id prefix here — `rowNodeId(noun, …)` is
+     * what a click resolves through, so the separator has to survive that round
+     * trip intact.
+     */
+    private tableView;
+    /**
+     * One contributed table as the pipe's lines — the SAME resolution the draw
+     * path uses, so the two renderings cannot disagree about what the table holds.
+     *
+     * Routed through `tableView`, which means the error boundary covers the pipe
+     * too: a throwing table prints its named failure row here exactly as it draws
+     * one on screen.
+     */
+    private tableLines;
+    /** The `PanelRender` a contribution is handed — one construction, two kinds. */
+    private panelRender;
     private panelSections;
 }

package/dist/src/Entity/ticket/Screen/ticket-detail.js

@@ -6,13 +6,23 @@ import { copyThrough } from '../../../lib/clipboard.js';
 import { BORDER, columnNode, DEFAULT_FOREGROUND, textNode, } from '../../../lib/vnode.js';
 import { defineContext } from '../../../Routing/context.js';
 import { AsyncScreen } from '../../../Screen/async-screen.js';
+import { timerDebounce } from '../../../Widget/option-source.js';
 import { ticketRunRows } from '../../run/Data/runs.js';
 import { TICKET_SECTIONS } from '../Component/sections/index.js';
-import { detailLines, firstLineSummary, headerLabels, headerState, initialExpandedComments, tabViewTree, } from '../Component/ticket-detail/index.js';
+import { detailLines, firstLineSummary, headerLabels, headerState, initialExpandedComments, panelTableLines, tabViewTree, } from '../Component/ticket-detail/index.js';
 import { ticketTeaserLines, ticketTeaserTree, } from '../Component/ticket-teaser/index.js';
 import { loadTicketDetail } from '../Data/detail.js';
 import { ticketUrl } from '../Data/url.js';
 export const ticketDetailInputContext = defineContext('ticket-detail-input', 'input');
+/**
+ * GAIA-475 criterion 24 — how often an open contributed table re-reads itself.
+ *
+ * "Every few seconds", and five is what that phrase buys: long enough that a
+ * discovery costing a socket-table read and a `ddev describe` is nowhere near a
+ * per-frame cost (spec C6 bounds exactly this), short enough that a service
+ * started mid-run shows up while the operator is still looking for it.
+ */
+const TABLE_REFRESH_MS = 5_000;
 export class TicketDetailScreen extends AsyncScreen {
     frameId = 'ticket';
     /**
@@ -60,9 +70,9 @@ export class TicketDetailScreen extends AsyncScreen {
     effective(context) {
         return [
             ...TICKET_TABS,
-            ...this.matched(context).map((panel) => ({
-                id: panel.id,
-                label: panel.title,
+            ...this.matched(context).map((contribution) => ({
+                id: contribution.id,
+                label: contribution.title,
             })),
         ];
     }
@@ -77,7 +87,10 @@ export class TicketDetailScreen extends AsyncScreen {
      */
     matched(context) {
         const query = context?.panels ?? this.panelQuery;
-        return (query?.('panel', {
+        // GAIA-475 — `'tab'`, so BOTH kinds reach the bar in the one order this
+        // screen promises: load order from `addons[]`. Asking for panels and then
+        // for tables would re-sort the bar by KIND behind the operator's back.
+        return (query?.('tab', {
             routeId: this.id,
             params: context?.params ?? this.panelParams,
         }) ?? []);
@@ -99,8 +112,60 @@ export class TicketDetailScreen extends AsyncScreen {
         return true;
     }
     reload(context) {
+        // GAIA-475 A5 — bump BEFORE the retry, so the next render a contribution sees
+        // already carries the new token and drops its cache on the same reload the
+        // operator asked for.
+        this.reloadToken += 1;
         this.retry(context);
     }
+    /**
+     * GAIA-475 criterion 24 — arm or cancel the table's self-refresh.
+     *
+     * Called wherever the OPEN TAB can change: `enter`, `selectTab`, and after an
+     * activation. A contributed table is a view of the machine rather than of the
+     * ticket — a Storybook started ten minutes into a run is not in any document
+     * the host fetched — so it is the one tab that has to re-read without being
+     * asked. The built-in tabs deliberately do not tick: their data comes from the
+     * API, and a timer on them would be a polling loop nobody asked for.
+     *
+     * What a tick does is the cheap half of `reload`: bump the token and redraw.
+     * It does NOT call `retry()`, so no HTTP request is made — the contribution
+     * re-reads its own source (the socket table, the state file) and everything
+     * the screen shows about the ticket is left exactly as it was.
+     */
+    syncTableTick(context) {
+        const wanted = this.activeContribution(context)?.type === 'table';
+        if (!wanted) {
+            this.cancelTableTick();
+            return;
+        }
+        if (this.tableTick)
+            return;
+        this.armTableTick(context);
+    }
+    armTableTick(context) {
+        const debounce = context.options?.debounce ?? timerDebounce;
+        this.tableTick = debounce(() => {
+            this.tableTick = undefined;
+            // Still the open tab? The operator may have moved on between the arming
+            // and the fire, and a tick that re-arms itself off a stale tab would
+            // outlive the tab that wanted it.
+            if (this.activeContribution(context)?.type !== 'table')
+                return;
+            this.reloadToken += 1;
+            this.armTableTick(context);
+            context.requestDraw();
+        }, TABLE_REFRESH_MS);
+    }
+    cancelTableTick() {
+        this.tableTick?.();
+        this.tableTick = undefined;
+    }
+    leave() {
+        // The screen is gone; its timer may not outlive it.
+        this.cancelTableTick();
+        super.leave();
+    }
     static route = {
         id: 'ticket.detail',
         path: '/tickets/:ticketId',
@@ -138,6 +203,19 @@ export class TicketDetailScreen extends AsyncScreen {
      */
     panelQuery;
     panelParams = {};
+    /** GAIA-475 — the table rows whose `onActivate` is in flight. */
+    activatingRows = new Set();
+    /** GAIA-475 A5 — bumped on every reload, handed to a table so it can drop its
+     *  cache. A counter, not a clock. */
+    reloadToken = 0;
+    /**
+     * GAIA-475 criterion 24 — the self-refresh, as its cancel function.
+     *
+     * Set while a contributed TABLE is the open tab, `undefined` otherwise, so the
+     * field's presence IS "a tick is armed" and there is no second flag to
+     * disagree with it.
+     */
+    tableTick;
     /** GAIA-326 — the last copy's outcome, shown in the footer. Empty until the
      *  operator asks for one; see `copyOpenTicket`. */
     status = '';
@@ -176,12 +254,17 @@ export class TicketDetailScreen extends AsyncScreen {
             const document = context.contexts.get(ticketDetailInputContext).document;
             this.replaceReady(document);
             this.initialize(document);
+            // GAIA-475 criterion 24 — `initialize` may have put the screen straight
+            // onto a contributed tab, and a re-entry after a reload lands here too, so
+            // the tick is resolved on this path as well as on `selectTab`.
+            this.syncTableTick(context);
             context.requestDraw();
             return;
         }
         super.enter(context);
         this.viewMode = viewMode;
         this.requestedTab = requestedTab;
+        this.syncTableTick(context);
     }
     setLabels(labels) {
         this.labels = labels;
@@ -192,6 +275,9 @@ export class TicketDetailScreen extends AsyncScreen {
             return false;
         this.activeTab = next;
         this.selectedEntry = 0;
+        // GAIA-475 criterion 24 — the open tab just changed, so the tick follows it
+        // on or off. This is the only place the active index moves.
+        this.syncTableTick(context);
         context.requestDraw();
         return true;
     }
@@ -204,10 +290,20 @@ export class TicketDetailScreen extends AsyncScreen {
         context.requestDraw();
         return true;
     }
-    activate(index, context) {
+    activate(index, context, intent) {
         const document = this.document;
         if (!document)
             return false;
+        // GAIA-475 — a contributed TABLE claims the key before the expansion toggle,
+        // and instead of it: a table row has nothing to expand. The activation is
+        // async and fire-and-forget from the key path; `activateTableRow` owns the
+        // busy set, the status line and the redraw discipline. `intent` is the
+        // start/stop distinction, forwarded to the contribution.
+        const contribution = this.activeContribution(context);
+        if (contribution?.type === 'table') {
+            void this.activateTableRow(contribution, index, context, intent);
+            return true;
+        }
         if (TICKET_SECTIONS[this.activeTab]?.id === 'runs') {
             const run = ticketRunRows(document)[index];
             if (!run?.id || !context.navigate)
@@ -299,19 +395,25 @@ export class TicketDetailScreen extends AsyncScreen {
         const nowSeconds = context.nowSeconds?.() ?? Math.floor(Date.now() / 1000);
         return [
             ...detailLines(document, this.labels).lines,
-            ...this.matched(context).flatMap((panel) => flattenSections(this.panelSections(panel, context, {
-                expanded: new Set(),
-                nowSeconds,
-            }).map((section) => ({
-                heading: section.heading,
-                // Lifted to rows and read back as text, because since GAIA-372 D3
-                // a collapsed rule is a function over RENDERED LINES. Lifting is
-                // not parsing: a captured log reaches the pipe as the bytes it
-                // holds, exactly as it reaches the tab.
-                lines: section.expandable
-                    ? firstLineSummary(section.lines.map(plainLine)).map((line) => line.text)
-                    : [...section.lines],
-            }))).lines),
+            ...this.matched(context).flatMap((contribution) => contribution.type === 'table'
+                ? // GAIA-475 A4 — the table's own text, under its title as the heading,
+                    // through the list serialisation every built-in list prints through.
+                    // No `firstLineSummary` here and nothing collapsible: a table has no
+                    // body behind a caret, so there is nothing for the pipe to hold back.
+                    this.tableLines(contribution, context, nowSeconds)
+                : flattenSections(this.panelSections(contribution, context, {
+                    expanded: new Set(),
+                    nowSeconds,
+                }).map((section) => ({
+                    heading: section.heading,
+                    // Lifted to rows and read back as text, because since GAIA-372 D3
+                    // a collapsed rule is a function over RENDERED LINES. Lifting is
+                    // not parsing: a captured log reaches the pipe as the bytes it
+                    // holds, exactly as it reaches the tab.
+                    lines: section.expandable
+                        ? firstLineSummary(section.lines.map(plainLine)).map((line) => line.text)
+                        : [...section.lines],
+                }))).lines),
         ];
     }
     handleInput(input, context) {
@@ -335,6 +437,15 @@ export class TicketDetailScreen extends AsyncScreen {
             return true;
         }
         const view = this.currentView(context);
+        // GAIA-475 UX — `s` STARTS and `x` STOPS the selected row's action on a
+        // TABLE tab, two distinct keys because Enter reads as "expand" on a detail
+        // screen and one key doing both is a confusing toggle. Only when a table is
+        // the active contribution, so `s`/`x` are untouched everywhere else.
+        const onTable = this.activeContribution(context)?.type === 'table';
+        if (onTable && input === 's' && view.selectable > 0)
+            return this.activate(this.selectedEntry, context, 'activate');
+        if (onTable && input === 'x' && view.selectable > 0)
+            return this.activate(this.selectedEntry, context, 'deactivate');
         if ((input === 'enter' || input === ' ') && view.selectable > 0)
             return this.activate(this.selectedEntry, context);
         // GAIA-369 AC-7 — "HANDLED" MEANS THE SELECTION MOVED, and that is the whole
@@ -511,10 +622,19 @@ export class TicketDetailScreen extends AsyncScreen {
             actionItem('detail-arrows', '↑↓', arrows),
         ];
         if (view.selectable > 0) {
-            actions.push(this.activeSectionId(context) === 'runs' &&
-                this.activeTab < TICKET_TABS.length
-                ? actionItem('detail-enter', 'Enter', 'open run')
-                : actionItem('detail-enter', 'Enter/Space', 'expand'));
+            // GAIA-475 — a table tab offers its action under a dedicated key `s`, so
+            // the footer names it rather than leaving the operator to guess Enter does
+            // something other than expand.
+            if (this.activeContribution(context)?.type === 'table') {
+                actions.push(actionItem('detail-share', 's', 'start'));
+                actions.push(actionItem('detail-unshare', 'x', 'stop'));
+            }
+            else {
+                actions.push(this.activeSectionId(context) === 'runs' &&
+                    this.activeTab < TICKET_TABS.length
+                    ? actionItem('detail-enter', 'Enter', 'open run')
+                    : actionItem('detail-enter', 'Enter/Space', 'expand'));
+            }
         }
         return actions;
     }
@@ -533,6 +653,9 @@ export class TicketDetailScreen extends AsyncScreen {
         this.status = '';
         this.panelQuery = undefined;
         this.panelParams = {};
+        this.activatingRows = new Set();
+        this.reloadToken = 0;
+        this.cancelTableTick();
     }
     initialize(document) {
         const key = document.data?.id ?? document;
@@ -549,27 +672,31 @@ export class TicketDetailScreen extends AsyncScreen {
         const nowSeconds = context.nowSeconds?.() ?? Math.floor(Date.now() / 1000);
         const expanded = this.expandedByTab.get(this.activeSectionId(context)) ??
             new Set();
-        // GAIA-373 — past the built-ins, the active index names a PANEL, and its
-        // sections are resolved here rather than inside the component: the panel is
-        // the screen's dependency, and `tabViewTree` stays a pure function of rows.
-        const panel = this.activePanel(context);
+        // GAIA-373 — past the built-ins, the active index names a CONTRIBUTION, and
+        // its rows are resolved here rather than inside the component: the
+        // contribution is the screen's dependency, and `tabViewTree` stays a pure
+        // function of rows.
+        //
+        // GAIA-475 — two kinds now, and the branch is on the contribution's own
+        // `type` rather than on anything the screen tracks separately, so the two
+        // cannot disagree about which tab is open.
+        const contribution = this.activeContribution(context);
+        const render = { expanded, nowSeconds };
         return tabViewTree(this.document ?? {}, this.activeTab, {
             expanded,
             nowSeconds,
             selectedIndex: this.selectedEntry,
             ...(this.labels ? { labels: this.labels } : {}),
-            ...(panel
-                ? {
-                    panelSections: this.panelSections(panel, context, {
-                        expanded,
-                        nowSeconds,
-                    }),
-                }
+            ...(contribution?.type === 'panel'
+                ? { panelSections: this.panelSections(contribution, context, render) }
+                : {}),
+            ...(contribution?.type === 'table'
+                ? this.tableView(contribution, context, render)
                 : {}),
         });
     }
-    /** The panel the active index names, or none while a built-in is open. */
-    activePanel(context) {
+    /** The contribution the active index names, or none while a built-in is open. */
+    activeContribution(context) {
         return this.activeTab < TICKET_TABS.length
             ? undefined
             : this.matched(context)[this.activeTab - TICKET_TABS.length];
@@ -600,18 +727,146 @@ export class TicketDetailScreen extends AsyncScreen {
      * untouched, so `emptyMessage` still means "nothing to show", never "it
      * broke".
      */
+    /**
+     * GAIA-475 A3 — activate one table row, following the conductor screen's shape.
+     *
+     * Mark busy, redraw, await, record the outcome as the footer status, clear busy
+     * in a `finally`, redraw. The busy set is what makes a second Enter a no-op
+     * while the first is in flight (US-12) and what a cell reads through
+     * `PanelRender.activating` to show the work.
+     *
+     * The row is picked from the SAME guarded resolution the render uses
+     * (`tableView`), so the row `onActivate` receives is exactly the row the
+     * operator saw; a table whose `rows()` throws resolves to the error branch and
+     * simply has no row to activate.
+     */
+    async activateTableRow(table, index, context, intent) {
+        const nowSeconds = context.nowSeconds?.() ?? Math.floor(Date.now() / 1000);
+        const resolved = this.tableView(table, context, {
+            expanded: new Set(),
+            nowSeconds,
+        });
+        if ('panelSections' in resolved)
+            return;
+        const row = resolved.panelTable.rows[index];
+        if (!row || !table.onActivate || this.activatingRows.has(row.id))
+            return;
+        this.activatingRows.add(row.id);
+        context.requestDraw();
+        try {
+            const result = await table.onActivate(row, this.panelRender(context, { expanded: new Set(), nowSeconds }, intent));
+            this.status = result.message ?? '';
+        }
+        catch (caught) {
+            this.status = `${table.id} action failed: ${caught instanceof Error ? caught.message : String(caught)}`;
+        }
+        finally {
+            this.activatingRows.delete(row.id);
+            // GAIA-475 UX — BUMP the reload token so the contribution drops its
+            // discovery/state cache and the row visibly updates on this redraw: the
+            // tunnel just wrote the state file, and without the bump the cockpit would
+            // read a stale snapshot and the SHARED column would stay empty until the
+            // next auto-reload. This is what makes the async bring-up feel synchronous
+            // — busy `…` while it runs, the URL the instant it is ready.
+            this.reloadToken += 1;
+            context.requestDraw();
+        }
+    }
+    /** Tests and the busy indicator: the row ids whose activation is in flight. */
+    activatingRowIds() {
+        return [...this.activatingRows];
+    }
+    /**
+     * One contributed table's columns and rows — `panelSections`' twin (GAIA-475).
+     *
+     * Returns the OPTION BAG `tabViewTree` takes rather than the data directly,
+     * because a failure has to change WHICH branch renders: there is no such thing
+     * as a table of an error. On a throw this degrades to `panelSections`, so a
+     * broken table produces the same named, readable failure row a broken panel
+     * does — one rendering of "this addon broke", not two.
+     *
+     * The same chokepoint argument applies here as there, and more sharply: both
+     * `columns()` and `rows()` are contributed code, both run on the draw path, and
+     * the draw path is not uniformly guarded (`Kernel/tui-kernel.ts` wires `draw`
+     * straight onto the resize and mouse-scroll events). A throw out of either one
+     * would freeze or crash the cockpit.
+     *
+     * `noun` replaces `/` with `-` because the id is org-prefixed by convention
+     * (`gaia/ports`) and it becomes a node id prefix here — `rowNodeId(noun, …)` is
+     * what a click resolves through, so the separator has to survive that round
+     * trip intact.
+     */
+    tableView(table, context, render) {
+        const ctx = this.panelRender(context, render);
+        try {
+            return {
+                panelTable: {
+                    noun: table.id.replace(/\//g, '-'),
+                    columns: table.columns(ctx),
+                    rows: table.rows(this.document ?? {}, ctx),
+                    emptyMessage: table.emptyMessage ?? 'Nothing to show.',
+                },
+            };
+        }
+        catch (caught) {
+            return {
+                panelSections: [
+                    {
+                        heading: table.title || table.id,
+                        lines: [
+                            `${table.id} failed to render: ` +
+                                `${caught instanceof Error ? caught.message : String(caught)}`,
+                        ],
+                    },
+                ],
+            };
+        }
+    }
+    /**
+     * One contributed table as the pipe's lines — the SAME resolution the draw
+     * path uses, so the two renderings cannot disagree about what the table holds.
+     *
+     * Routed through `tableView`, which means the error boundary covers the pipe
+     * too: a throwing table prints its named failure row here exactly as it draws
+     * one on screen.
+     */
+    tableLines(table, context, nowSeconds) {
+        const resolved = this.tableView(table, context, {
+            expanded: new Set(),
+            nowSeconds,
+        });
+        if ('panelSections' in resolved) {
+            return flattenSections(resolved.panelSections.map((section) => ({
+                heading: section.heading,
+                lines: [...section.lines],
+            }))).lines;
+        }
+        return flattenSections([
+            {
+                heading: table.title || table.id,
+                lines: panelTableLines(resolved.panelTable),
+            },
+        ]).lines;
+    }
+    /** The `PanelRender` a contribution is handed — one construction, two kinds. */
+    panelRender(context, render, intent) {
+        return {
+            routeId: this.id,
+            params: context.params ?? {},
+            expanded: render.expanded,
+            nowSeconds: render.nowSeconds,
+            activating: this.activatingRows,
+            reloadToken: this.reloadToken,
+            ...(intent ? { intent } : {}),
+            ...(context.options?.cwd !== undefined
+                ? { cwd: context.options.cwd }
+                : {}),
+        };
+    }
     panelSections(panel, context, render) {
         let sections;
         try {
-            sections = panel.sections(this.document ?? {}, {
-                routeId: this.id,
-                params: context.params ?? {},
-                expanded: render.expanded,
-                nowSeconds: render.nowSeconds,
-                ...(context.options?.cwd !== undefined
-                    ? { cwd: context.options.cwd }
-                    : {}),
-            });
+            sections = panel.sections(this.document ?? {}, this.panelRender(context, render));
         }
         catch (caught) {
             return [

package/dist/src/Extension/contract.d.ts

@@ -18,6 +18,48 @@ export interface PanelRender extends PanelMatch {
     readonly nowSeconds: number;
     /** The checkout the cockpit was started in (`TuiOptions.cwd`). */
     readonly cwd?: string | undefined;
+    /**
+     * GAIA-475 — the ids of the rows whose `onActivate` is in flight right now.
+     *
+     * The HOST owns this set — it adds a row on activation and clears it in a
+     * `finally` — and hands it to the contribution's `columns`/`rows` so a cell can
+     * say "…" while the work runs (US-12). Absent for a `panel`, which has no
+     * activation; empty when nothing is in flight.
+     */
+    readonly activating?: ReadonlySet<string>;
+    /**
+     * GAIA-475 A5 — a value that CHANGES whenever the host reloads.
+     *
+     * A contribution holding a short-lived cache invalidates it by comparing this
+     * against the token it last computed under. Without it the existing reload key
+     * refreshes the ticket document and leaves a cached list untouched — a keypress
+     * that visibly does nothing. It is a monotone counter, not a timestamp, so it
+     * carries no clock and two reloads are always distinguishable.
+     */
+    readonly reloadToken?: number;
+    /**
+     * GAIA-475 UX — which INTENT triggered this activation, when the host offers
+     * two keys for it.
+     *
+     * A table with a reversible action (a tunnel: up and down) reads better under
+     * two distinct keys than one toggle — `s` to start, `x` to stop — because the
+     * same key doing both is the UX the operator flagged. The host sets this from
+     * the key; the contribution's `onActivate` interprets it. Absent for a single
+     * `Enter`, which the contribution is free to treat as a toggle. The core stays
+     * semantics-free: it forwards the intent, it does not know what start means.
+     */
+    readonly intent?: 'activate' | 'deactivate';
+}
+/**
+ * GAIA-475 — what a table's `onActivate` reports back.
+ *
+ * A footer line and nothing more: the row's own state change is observed on the
+ * next render (the state file the action wrote, re-read), so the result does not
+ * carry a new row — that would be a second source of truth for what the next
+ * `rows()` already answers.
+ */
+export interface ActivationResult {
+    readonly message?: string;
 }
 /**
  * A panel: a section MODE of a host screen.
@@ -53,6 +95,94 @@ export interface UiScreen {
     readonly route: RouteMetadata;
     screen(): Screen;
 }
-export type UiContribution = UiPanel | UiScreen;
-/** The host's read: contributions of one type whose `match` accepts this place. */
-export type PanelQuery = (type: 'panel', ctx: PanelMatch) => readonly UiPanel[];
+/**
+ * One column of a contributed table: its LAYOUT and an accessor, never a renderer.
+ *
+ * Deliberately the subset of `ListColumn` (`Entity/collection.ts`) that a
+ * contribution can answer for. `key`/`label`/`width`/`min`/`max`/`grow` carry the
+ * same meanings there — width 0 is the trailing column that takes the rest of the
+ * row — so the host maps one onto the other without translating anything.
+ *
+ * Two members of `ListColumn` are deliberately absent. `fields` names the JSON:API
+ * attributes a sparse fieldset must request, and a contribution has no such query:
+ * it hands over finished rows. And `get` here takes the row ALONE, where the host's
+ * takes a `Ctx` too — a contribution's context is the `PanelRender` it already
+ * received in `columns()`, so a second channel would be a way to disagree with it.
+ */
+export interface PanelColumn<Row> {
+    /** Stable identity for the column; not rendered, and the id its cells carry. */
+    readonly key: string;
+    readonly label: string;
+    /** Display columns to lay out; **0** is the trailing column. */
+    readonly width: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly grow?: number;
+    get(row: Row): unknown;
+}
+/**
+ * A table: a contributed LIST, rendered by the host's own list machinery.
+ *
+ * The second contribution kind (GAIA-475 A1), and the reason it is data rather
+ * than a render tree: the host already owns TWO serialisations of a list — one
+ * for the terminal and one for piped output — so a contribution that returned a
+ * tree would force a second rendering into existence and leave the piped path to
+ * rot. `columns` and `rows` are all the host needs to drive both.
+ *
+ * `Row extends { id: string }` because row identity is not optional here: it keys
+ * the node a selection lands on, exactly as `ListTable` requires of every list the
+ * cockpit already renders.
+ */
+export interface UiTable<Row extends {
+    id: string;
+} = {
+    id: string;
+}, Doc = unknown> {
+    readonly type: 'table';
+    /** Org-prefixed and globally unique, e.g. `gaia/ports`. */
+    readonly id: string;
+    /** The label the tab bar shows. */
+    readonly title: string;
+    match(ctx: PanelMatch): boolean;
+    columns(ctx: PanelRender): readonly PanelColumn<Row>[];
+    rows(doc: Doc, ctx: PanelRender): readonly Row[];
+    /**
+     * GAIA-475 A2 — what Enter on a row does. Optional: a table with no action is
+     * a read-only list, and Enter on it does nothing rather than toggling anything.
+     *
+     * The host consults this BEFORE its own expansion toggle and, for a table,
+     * instead of it — a table row has no body behind a caret. The host wraps the
+     * call: a rejection becomes a footer message, never a dead cockpit, and the row
+     * is marked in `PanelRender.activating` for the duration.
+     */
+    onActivate?(row: Row, ctx: PanelRender): Promise<ActivationResult>;
+    /** Shown when `rows` comes back empty. */
+    readonly emptyMessage?: string;
+}
+export type UiContribution = UiPanel | UiTable | UiScreen;
+/**
+ * The two kinds that render as a TAB of a host screen.
+ *
+ * `UiScreen` is deliberately absent: it is a destination, not a section mode, and
+ * `store.ts` refuses it at registration anyway.
+ */
+export type UiTab = UiPanel | UiTable;
+/**
+ * The host's read: contributions of one type whose `match` accepts this place.
+ *
+ * Overloaded rather than widened, so the TYPE ARGUMENT decides the result type.
+ * That is what keeps a table out of a `sections`-shaped renderer at compile time
+ * instead of by each caller's discipline.
+ *
+ * `'tab'` is the third reading and not a convenience: a screen's tab order is
+ * LOAD ORDER (`ticket-detail.ts` › `effective`), so asking for panels and then
+ * for tables would quietly re-sort the bar BY KIND and an addon contributing both
+ * would always find its table behind every other addon's panel. One query keeps
+ * the one order the screen promises; `'panel'`/`'table'` narrow when a caller
+ * genuinely wants one kind.
+ */
+export interface PanelQuery {
+    (type: 'panel', ctx: PanelMatch): readonly UiPanel[];
+    (type: 'table', ctx: PanelMatch): readonly UiTable[];
+    (type: 'tab', ctx: PanelMatch): readonly UiTab[];
+}

package/dist/src/Extension/store.js

@@ -39,6 +39,14 @@ export function resetCollector() {
     collected.length = 0;
 }
 export function createPanelQuery(contributions) {
-    const panels = contributions.filter((c) => c.type === 'panel');
-    return (_type, ctx) => panels.filter((panel) => panel.match(ctx));
+    // ONE list, filtered three ways, so the pools cannot drift out of step with
+    // each other or with the order they were registered in. `tabs` keeps that
+    // registration order across both kinds — the property the screen's tab bar is
+    // specified in terms of — and the two narrow pools are derived FROM it rather
+    // than collected separately.
+    const tabs = contributions.filter((c) => c.type === 'panel' || c.type === 'table');
+    const panels = tabs.filter((c) => c.type === 'panel');
+    const tables = tabs.filter((c) => c.type === 'table');
+    const pool = { panel: panels, table: tables, tab: tabs };
+    return ((type, ctx) => pool[type].filter((c) => c.match(ctx)));
 }

package/dist/src/ui.d.ts

@@ -1,2 +1,2 @@
-export type { PanelMatch, PanelQuery, PanelRender, PanelSection, UiContribution, UiPanel, UiScreen, } from './Extension/contract.js';
+export type { ActivationResult, PanelColumn, PanelMatch, PanelQuery, PanelRender, PanelSection, UiContribution, UiPanel, UiScreen, UiTable, } from './Extension/contract.js';
 export { type ContributionApi, register } from './Extension/store.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/addon-gaia-ui",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "GAIA TUI: interactive terminal UI (dashboard, projects, tickets) as a dropsh `tui` renderer plugin.",
   "type": "module",
   "license": "MIT",
@@ -22,10 +22,10 @@
   },
   "dependencies": {
     "@opentui/core": "0.5.1",
-    "bun": "1.3.14",
+    "bun": "1.4.0",
     "drupal-jsonapi-params": "^3.0.1"
   },
   "peerDependencies": {
-    "@gaia-ai/core": "^0.12.0"
+    "@gaia-ai/core": "^0.13.0"
   }
 }