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

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/statistics/Data/statistics.d.ts

@@ -39,18 +39,31 @@ export interface SeriesFigureValue {
     days: StatisticDay[];
 }
 /**
- * A `ratio` figure's value: its two named factors, side by side.
+ * A `ratio` figure's value: the quotient, and the two factors behind it.
  *
- * The ratio itself is computed CLIENT-SIDE from the two totals — a
- * server-computed copy would be a second source of truth that can disagree
- * (unchanged from GAIA-377's `closedPerRun`, now over server-named factors
- * instead of the fixed tickets/runs pair).
+ * The division was CLIENT-SIDE until GAIA-481 D3, on the reasoning that a
+ * server-computed copy would be a second source of truth. The web Stats tabs
+ * reversed that reasoning: a second SURFACE would have had to re-implement
+ * the same rule in PHP, so the division and its zero-denominator case moved
+ * to the server instead. `ratio` is therefore READ and rendered, never
+ * recomputed here — and it arrives already formatted, because the empty
+ * value is part of the rule rather than a presentation choice each surface
+ * makes for itself.
+ *
+ * `numerator` and `denominator` still travel beside it, unchanged.
  */
 export interface RatioFigureValue {
     generated: string;
+    ratio: RatioQuotients;
     numerator: WindowsFigureValue;
     denominator: WindowsFigureValue;
 }
+/** A ratio's derived value per trailing window: two decimals, or `—`. */
+export interface RatioQuotients {
+    day: string;
+    week: string;
+    month: string;
+}
 export type FigureValue = WindowsFigureValue | SeriesFigureValue | RatioFigureValue;
 /** One figure discovery names: which blocks the caller may render (spec D5). */
 export interface StatisticListing {
@@ -132,11 +145,3 @@ export declare function loadStatisticValue(client: DropshClient, statisticId: st
  * its own (spec D5). Figures already arrive weight-ordered from discovery.
  */
 export declare function loadGroupStatistics(client: DropshClient, scopeId: string): Promise<GroupStatisticsResult>;
-/** Closed-per-run-shaped ratio, for each trailing window, from two totals. */
-export declare function ratioOf(numerator: StatisticsWindows, denominator: StatisticsWindows): {
-    day: number | null;
-    week: number | null;
-    month: number | null;
-};
-/** Format a ratio value for the screen: two decimals, or `—`. */
-export declare const formatRatio: (value: number | null) => string;

package/dist/src/Entity/statistics/Data/statistics.js

@@ -1,4 +1,12 @@
 import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+/**
+ * What a ratio window reads as when there is nothing to divide by.
+ *
+ * The server owns this rule and sends the character; this constant exists
+ * only so a response that carries no quotient at all degrades to the same
+ * thing rather than to an empty cell.
+ */
+const RATIO_EMPTY = '—';
 /** How an `id: null` breakdown row is named on screen. */
 export const UNATTRIBUTED_LABEL = '— unattributed';
 const num = (value) => typeof value === 'number' && Number.isFinite(value) ? value : 0;
@@ -43,6 +51,23 @@ function windowsFigureOf(attributes) {
         ...(rows ? { rows } : {}),
     };
 }
+/**
+ * A ratio figure's quotients, as the server formatted them (GAIA-481 D3).
+ *
+ * A control plane that predates the move sends no `ratio` at all, and this
+ * reads the empty value for every window rather than throwing or dividing a
+ * replacement: an older server is a missing figure, not a wrong one, and the
+ * one thing this must not do is quietly reintroduce the division it replaced.
+ */
+function quotientsOf(value) {
+    const source = (value ?? {});
+    const windowOf = (key) => typeof source[key] === 'string' ? source[key] : RATIO_EMPTY;
+    return {
+        day: windowOf('day'),
+        week: windowOf('week'),
+        month: windowOf('month'),
+    };
+}
 function figureValueOf(attributes) {
     if (Array.isArray(attributes.days)) {
         return {
@@ -56,6 +81,7 @@ function figureValueOf(attributes) {
         attributes.denominator !== null) {
         return {
             generated: typeof attributes.generated === 'string' ? attributes.generated : '',
+            ratio: quotientsOf(attributes.ratio),
             numerator: windowsFigureOf(attributes.numerator),
             denominator: windowsFigureOf(attributes.denominator),
         };
@@ -198,14 +224,12 @@ export async function loadGroupStatistics(client, scopeId) {
     }
     return { kind: 'ok', figures };
 }
-/** Closed-per-run-shaped ratio, for each trailing window, from two totals. */
-export function ratioOf(numerator, denominator) {
-    const ratio = (n, d) => (d > 0 ? n / d : null);
-    return {
-        day: ratio(numerator.day, denominator.day),
-        week: ratio(numerator.week, denominator.week),
-        month: ratio(numerator.month, denominator.month),
-    };
-}
-/** Format a ratio value for the screen: two decimals, or `—`. */
-export const formatRatio = (value) => value === null ? '—' : value.toFixed(2);
+// GAIA-481 D3 — `ratioOf` and `formatRatio` were exported from here, and are
+// gone. A `ratio` figure's quotient is the server's now
+// (`RatioFigureValue.ratio`), so this module deliberately offers no ratio
+// arithmetic for a caller to reach for: a shared helper sitting beside the
+// server's own value is exactly how the second implementation would come
+// back. The team Users screen still divides, because it derives a PER-MEMBER
+// quotient out of two breakdown figures' rows and no configured figure
+// produces that one; it owns that arithmetic privately rather than sharing
+// it from here.

package/dist/src/Entity/statistics/render.js

@@ -1,5 +1,4 @@
 import { statsPanelRows, } from '../../Component/stats-panel/index.js';
-import { formatRatio, ratioOf } from './Data/statistics.js';
 // GAIA-456 spec D2/D7 — mapping the four configured display kinds onto the
 // renderers the TUI already had: `windows` is the totals row GAIA-256 drew,
 // `breakdown` is the label-by-window table, `series` is the seven-day strip
@@ -24,13 +23,19 @@ function seriesLines(days) {
     const counts = `  ${'Count'.padEnd(LABEL - 2, ' ')}${days.map((row) => cell(String(row.count))).join('')}`;
     return [weekdays, dates, counts];
 }
-/** A ratio figure's two factor totals, divided per trailing window. */
-function ratioLines(numerator, denominator) {
-    const ratios = ratioOf(numerator, denominator);
+/**
+ * A ratio figure's quotient per trailing window, as the SERVER divided it.
+ *
+ * The values arrive already formatted (GAIA-481 D3), so this lays them out
+ * and does nothing else — no division and no em-dash rule, both of which are
+ * the server's now and would otherwise be a terminal-only second opinion on
+ * the same figure the browser renders.
+ */
+function ratioLines(ratios) {
     return [
-        `  ${WINDOWS[0]}                     ${formatRatio(ratios.day)}`,
-        `  ${WINDOWS[1]}                       ${formatRatio(ratios.week)}`,
-        `  ${WINDOWS[2]}                      ${formatRatio(ratios.month)}`,
+        `  ${WINDOWS[0]}                     ${ratios.day}`,
+        `  ${WINDOWS[1]}                       ${ratios.week}`,
+        `  ${WINDOWS[2]}                      ${ratios.month}`,
     ];
 }
 /** One figure's own section: its label as the heading, its display kind's lines. */
@@ -41,10 +46,7 @@ export function figureSection({ listing, value }) {
             return { heading, lines: seriesLines(value.days) };
         case 'ratio': {
             const ratio = value;
-            return {
-                heading,
-                lines: ratioLines(ratio.numerator.total, ratio.denominator.total),
-            };
+            return { heading, lines: ratioLines(ratio.ratio) };
         }
         case 'breakdown': {
             const windows = value;

package/dist/src/Entity/team/Screen/team-users.js

@@ -4,7 +4,7 @@ import { ListCursor } from '../../../lib/cursor.js';
 import { columnNode } from '../../../lib/vnode.js';
 import { AsyncScreen } from '../../../Screen/async-screen.js';
 import { listRowIds, listTableTree } from '../../collection.js';
-import { formatRatio, loadGroupStatistics, ratioOf, } from '../../statistics/Data/statistics.js';
+import { loadGroupStatistics, } from '../../statistics/Data/statistics.js';
 import { listUsers, TEAM_MEMBER_TABLE, } from '../../user/Data/users.js';
 import { listTeamMemberIds } from '../Data/members.js';
 import { TeamsScreen } from './teams-screen.js';
@@ -48,6 +48,20 @@ function rowsById(statistics, statisticId) {
     }
     return map;
 }
+/**
+ * This screen's own closed-per-run, for ONE member over the 30-day window.
+ *
+ * Deliberately local and unexported (GAIA-481 D3). A `ratio` FIGURE is
+ * divided by the server, and this is not one: it is derived per member from
+ * two breakdown figures' rows, and no configured figure produces it. Keeping
+ * it here rather than in the shared statistics module is what stops it being
+ * mistaken for the general "how a ratio is computed" helper and reached for
+ * by a surface that should be reading the server's value instead.
+ *
+ * The rule matches the server's so the two columns agree on screen: two
+ * decimals, and an em-dash when there is nothing to divide by.
+ */
+const perMemberRatio = (numerator, denominator) => denominator > 0 ? (numerator / denominator).toFixed(2) : '—';
 /** One member's row: identity from the collection, figures from the two per-user breakdowns. */
 function rowOf(user, ticketsById, runsById) {
     const tickets30d = ticketsById.get(user.id)?.month ?? 0;
@@ -57,7 +71,7 @@ function rowOf(user, ticketsById, runsById) {
         label: user.label,
         tickets30d,
         runs30d,
-        closedPerRun30d: formatRatio(ratioOf({ day: 0, week: 0, month: tickets30d }, { day: 0, week: 0, month: runs30d }).month),
+        closedPerRun30d: perMemberRatio(tickets30d, runs30d),
     };
 }
 /**

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,62 @@ 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.
+     */
+    /**
+     * GAIA-500 — `l`/`t`'s shared plumbing: resolve the active table's selected
+     * row and ask its `copyLocal`/`copyTunnel`, returning `undefined` when there
+     * is no active table, the table does not implement that side, or the row has
+     * nothing to offer — in every one of which cases the key is left UNHANDLED
+     * (the caller falls through) rather than reporting a copy that did not
+     * happen, exactly as `l`/`t` do nothing on every tab that is not a table.
+     */
+    private copyActiveTableRow;
+    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;
 }