@gaia-ai/addon-gaia-ui 0.6.1 → 0.6.2

package/dist/src/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;

package/dist/src/Component/project-picker/index.js

@@ -0,0 +1,42 @@
+// GAIA-223 AC-8 (spec Decision 14) — the picker `gaia ui --here` shows when the
+// cwd's repo is claimed by MORE THAN ONE gaia project.
+//
+// One repo mapping to several projects is designed for, not an edge case:
+// GAIA-126/137 let `.gaia/` hold one conductor config per project, which is how
+// a Drupal multisite repo maps each site to its own GAIA project. Erroring on
+// N>1 would fail permanently, by design, in exactly the repos the feature is
+// most useful in — so the ambiguity is shown rather than resolved behind the
+// user's back.
+//
+// Pure, like every other Component: candidates in, rows out. The kernel owns
+// selection state, Enter and Esc.
+/** Clamp a selection index into the candidate range (0 when there are none). */
+function clamp(selected, length) {
+    if (length <= 0)
+        return 0;
+    return Math.max(0, Math.min(Math.trunc(selected), length - 1));
+}
+/**
+ * The picker screen's rows: a heading naming the repo, then one row per
+ * candidate with `▸` on the selected one.
+ */
+export function projectPickerRows(candidates, repo, selected) {
+    const heading = [`Several gaia projects claim ${repo} — which one?`, ''];
+    if (candidates.length === 0) {
+        return [...heading, 'No projects.'];
+    }
+    const index = clamp(selected, candidates.length);
+    return [
+        ...heading,
+        ...candidates.map((c, i) => `${i === index ? '▸' : ' '} ${c.name}`),
+    ];
+}
+/**
+ * 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 function projectPickerHint(candidates, repo) {
+    const names = candidates.map((c) => `  ${c.name}`).join('\n');
+    return (`Several gaia projects claim ${repo}:\n${names}\n` +
+        "Open one directly with 'gaia ui project:<name>'.");
+}

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

@@ -0,0 +1,7 @@
+import type { TicketDetailDocument, UiViewMode } from '../../types.js';
+/**
+ * A ticket rendered compactly, with the field set of its Drupal view-mode
+ * display. `full` never reaches here — the kernel renders the tabbed detail for
+ * it — but it is accepted and treated as `teaser` so the function is total.
+ */
+export declare function ticketTeaserLines(document: TicketDetailDocument, mode: UiViewMode): string[];

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

@@ -0,0 +1,76 @@
+// GAIA-223 AC-7 — the compact ticket block behind `gaia ui <ticket> --view
+// teaser|board_card` (spec Decision 13, variant A).
+//
+// THE FIELD SETS BELOW ARE A DELIBERATE DUPLICATE of two Drupal displays:
+//   config/sync/core.entity_view_display.gaia_ticket.gaia_ticket.teaser.yml
+//     → gaia_theme:ticket-row — identifier, title, state, derived_status,
+//       since_label, claim_machine, assignee_{name,initials,color}
+//   config/sync/core.entity_view_display.gaia_ticket.gaia_ticket.board_card.yml
+//     → gaia_theme:board-card — identifier, title, state, workflow(type),
+//       derived_status, priority, url; footer slot: claim_machine
+//
+// Why duplicated: those displays are display_builder→SDC bindings producing
+// HTML, JSON:API never serves rendered output, and NEITHER the `session` nor the
+// `pm` scope may read `entity_view_display` (both come back empty with
+// "insufficient authorization"). Reading the mapping at runtime — variant B — is
+// the named follow-up in the spec's *Out of scope*; it needs a `gaia_session`
+// read permission in `config/sync` AND the recipe copy, plus proof that
+// `third_party_settings` survives JSON:API serialization. When that lands, this
+// module is the ONE place that changes; the `--view` CLI surface is identical
+// either way. Until then, this file drifting from those YAMLs is the accepted
+// cost, named in Decision 13.
+import { asString } from '../../lib/format.js';
+/** The same em-dash placeholder ticket-table/run-table use for a missing value. */
+const MISSING = '—';
+/** Left column width, so the labels line up like the other components' columns. */
+const LABEL_WIDTH = 10;
+function row(label, value) {
+    return `${label.padEnd(LABEL_WIDTH)} ${value}`;
+}
+/** An attribute as a display string, or the shared placeholder. */
+function attr(attributes, key) {
+    const raw = attributes[key];
+    if (typeof raw === 'string' && raw !== '')
+        return raw;
+    if (typeof raw === 'number')
+        return String(raw);
+    return MISSING;
+}
+/**
+ * A ticket rendered compactly, with the field set of its Drupal view-mode
+ * display. `full` never reaches here — the kernel renders the tabbed detail for
+ * it — but it is accepted and treated as `teaser` so the function is total.
+ */
+export function ticketTeaserLines(document, mode) {
+    const a = document.data?.attributes ?? {};
+    const heading = `${attr(a, 'identifier')} · ${attr(a, 'title')}`;
+    if (mode === 'board_card') {
+        return [
+            heading,
+            '',
+            row('state', attr(a, 'state')),
+            row('type', attr(a, 'workflow')),
+            row('status', attr(a, 'derived_status')),
+            row('priority', attr(a, 'priority')),
+            row('claim', attr(a, 'claim_machine')),
+        ];
+    }
+    // `teaser`. The display binds assignee_name + assignee_initials + a colour;
+    // the terminal block shows the name with the initials as its short handle.
+    const name = attr(a, 'assignee_name');
+    const initials = asString(a.assignee_initials);
+    const assignee = name === MISSING
+        ? (initials ?? MISSING)
+        : initials
+            ? `${name} (${initials})`
+            : name;
+    return [
+        heading,
+        '',
+        row('state', attr(a, 'state')),
+        row('status', attr(a, 'derived_status')),
+        row('since', attr(a, 'since_label')),
+        row('assignee', assignee),
+        row('claim', attr(a, 'claim_machine')),
+    ];
+}

package/dist/src/Kernel/tui-kernel.js

@@ -4,10 +4,12 @@ import { join } from 'node:path';
 import { agentListRows } from '../Component/agent-list/index.js';
 import { createFormLines } from '../Component/create-form/index.js';
 import { dashboardRows } from '../Component/dashboard-list/index.js';
+import { projectPickerHint, projectPickerRows, } from '../Component/project-picker/index.js';
 import { runTableRows } from '../Component/run-table/index.js';
 import { DETAIL_TABS, tabBar } from '../Component/tab-bar/index.js';
-import { tabViewLines } from '../Component/ticket-detail/index.js';
+import { detailLines, tabViewLines } from '../Component/ticket-detail/index.js';
 import { ticketTableRows } from '../Component/ticket-table/index.js';
+import { ticketTeaserLines } from '../Component/ticket-teaser/index.js';
 import { topTabBar } from '../Component/top-tabs/index.js';
 import { ANSI, fitLine, styleVisibleLines } from '../lib/ansi.js';
 import { scrollTo } from '../lib/scroll.js';
@@ -20,6 +22,13 @@ import { loadDashboardProjects, } from '../Service/projects.js';
 import { loadProjectRuns, selectedRunTicketId } from '../Service/run-data.js';
 import { loadTicketDetail } from '../Service/ticket-data.js';
 const nowSeconds = () => Math.floor(Date.now() / 1000);
+/** `<identifier> · <title>` for a ticket document — the TTY title bar's text,
+ *  reused as the heading of the non-TTY ticket output (spec Decision 11). */
+function ticketHeading(document) {
+    const a = document.data?.attributes ?? {};
+    const str = (key) => typeof a[key] === 'string' ? a[key] : '';
+    return `${str('identifier')} · ${str('title') || 'ticket'}`.trim();
+}
 // The three read-only screens each project a `document`/state into plain string
 // rows; a Herdr-backed create agent is layered on top as a full-terminal
 // passthrough (no node-pty / @xterm — the core renders raw ANSI to the real TTY).
@@ -32,8 +41,40 @@ export function runTicketTui(_document, _context, services, options = {}) {
     const currentUser = services?.currentUser ?? options?.currentUser;
     const ownConductorMachineId = services?.ownConductorMachineId ?? options?.ownConductorMachineId;
     const createPrompt = services?.createPrompt ?? options?.createPrompt;
-    // Non-TTY: emit the dashboard once so `gaia ui </dev/null` stays scriptable.
+    // GAIA-223: the RESOLVED deep-link target (`Service/route.ts` produced it in
+    // the plugin's `run()`, before we got here). Absent ⇒ the dashboard (AC-4).
+    const bootRoute = options.route;
+    // Non-TTY: emit ONE screen so `gaia ui </dev/null` stays scriptable. With a
+    // route it emits THAT route's content (spec Decision 11) — otherwise
+    // `gaia ui GAIA-223 | cat` would silently print the wrong thing.
     if (!input.isTTY || !output.isTTY) {
+        if (bootRoute?.screen === 'ticket') {
+            return loadTicketDetail(services.client, bootRoute.ticketId).then((doc) => {
+                const lines = bootRoute.view === 'full'
+                    ? // The same `<identifier> · <title>` heading the TTY draws in its
+                        // title bar (and the teaser block emits itself) — without it a
+                        // piped `gaia ui GAIA-223` or `gaia ui run:<uuid>` would print a
+                        // wall of sections that never says WHICH ticket it is.
+                        [ticketHeading(doc), '', ...detailLines(doc).lines]
+                    : ticketTeaserLines(doc, bootRoute.view);
+                output.write(`${lines.join('\n')}\n`);
+            });
+        }
+        // AC-8: no terminal ⇒ no prompt. Print the candidates plus the direct
+        // command and exit, so `gaia ui --here | cat` stays scriptable (Decision 11).
+        if (bootRoute?.screen === 'project-picker') {
+            output.write(`${projectPickerHint(bootRoute.candidates, bootRoute.repo)}\n`);
+            return Promise.resolve();
+        }
+        if (bootRoute?.screen === 'project') {
+            return loadFilteredTickets(services.client, bootRoute.projectId, {
+                query: '',
+                state: null,
+                type: null,
+            }).then((rows) => {
+                output.write(`${bootRoute.projectName} · tickets\n${ticketTableRows(rows).join('\n')}\n`);
+            });
+        }
         return loadDashboardProjects({ client: services.client, nowSeconds })
             .catch(() => [])
             .then((rows) => {
@@ -52,6 +93,10 @@ export function runTicketTui(_document, _context, services, options = {}) {
     let searchMode = false;
     let searchTimer = null;
     let detail = null;
+    // GAIA-223 AC-7: how the ticket screen renders. 'full' is the tabbed detail
+    // (every path except an explicit `--view`); the other two are the compact
+    // block, which has no tabs (spec Decision 13).
+    const ticketView = bootRoute?.screen === 'ticket' ? bootRoute.view : 'full';
     let activeTab = 0;
     let selectedComment = 0;
     let expandedComments = new Set();
@@ -65,6 +110,11 @@ export function runTicketTui(_document, _context, services, options = {}) {
     let selectedAgent = 0;
     let runRows = [];
     let selectedRun = 0;
+    // GAIA-223 AC-8: the `--here` picker's state (spec Decision 14). Empty unless
+    // a `project-picker` route booted us.
+    let pickerCandidates = bootRoute?.screen === 'project-picker' ? bootRoute.candidates : [];
+    let pickerRepo = bootRoute?.screen === 'project-picker' ? bootRoute.repo : '';
+    let selectedCandidate = 0;
     let closing = false;
     let createSeq = 0;
     let lastCreateAtMs = 0;
@@ -112,6 +162,23 @@ export function runTicketTui(_document, _context, services, options = {}) {
                 selRow: runRows.length ? 1 + selectedRun : -1,
             };
         }
+        if (screen === 'project-picker') {
+            // Two heading rows precede the candidates, so the physical row is 2 + i.
+            return {
+                lines: projectPickerRows(pickerCandidates, pickerRepo, selectedCandidate),
+                selectable: pickerCandidates.length,
+                selRow: pickerCandidates.length ? 2 + selectedCandidate : -1,
+            };
+        }
+        // AC-7: a non-`full` view replaces the tabbed detail with the compact block
+        // — nothing selectable, no tabs.
+        if (ticketView !== 'full') {
+            return {
+                lines: ticketTeaserLines(detail ?? {}, ticketView),
+                selectable: 0,
+                selRow: -1,
+            };
+        }
         const view = tabViewLines(detail ?? {}, activeTab, {
             expanded: expandedComments,
             nowSeconds: nowSeconds(),
@@ -137,7 +204,9 @@ export function runTicketTui(_document, _context, services, options = {}) {
             ? selectedAgent
             : screen === 'project-runs'
                 ? selectedRun
-                : selectedTicket;
+                : screen === 'project-picker'
+                    ? selectedCandidate
+                    : selectedTicket;
     // The "New ticket" popup: a centered floating box drawn ON TOP of the current
     // screen (a real modal overlay, not a full-screen replace) via absolute cursor
     // positioning, so the dashboard/ticket list stays visible around it.
@@ -193,7 +262,9 @@ export function runTicketTui(_document, _context, services, options = {}) {
                     ? 'Ticket-Agents'
                     : screen === 'project-runs'
                         ? `${currentProjectName ?? currentProjectSlug} · runs`
-                        : `${detailAttr('identifier') ?? ''} · ${detailAttr('title') ?? 'ticket'}`;
+                        : screen === 'project-picker'
+                            ? 'Which project?'
+                            : `${detailAttr('identifier') ?? ''} · ${detailAttr('title') ?? 'ticket'}`;
         const meta = screen === 'dashboard'
             ? `${projects.length} registered project(s)  ·  ${services?.baseUrl ?? ''}`
             : screen === 'project'
@@ -204,16 +275,24 @@ export function runTicketTui(_document, _context, services, options = {}) {
                     ? `${agentRows.length} agent(s)  ·  Enter switch · z overview · r retry · x close · Esc back`
                     : screen === 'project-runs'
                         ? `${runRows.length} run(s)  ·  Enter ticket · Tab cycle · Esc back`
-                        : tabBar(activeTab);
+                        : screen === 'project-picker'
+                            ? `${pickerCandidates.length} project(s) claim ${pickerRepo}  ·  Enter open · Esc dashboard`
+                            : ticketView !== 'full'
+                                ? `view: ${ticketView}  ·  Esc back · q quit`
+                                : tabBar(activeTab);
         const keys = screen === 'ticket'
-            ? isCommentsTab()
-                ? ' Tab tab · ↑↓ select · Enter/Space expand · Esc back · q quit '
-                : ' Tab tab · ↑↓ scroll · Esc back · q quit '
+            ? ticketView !== 'full'
+                ? ' ↑↓ scroll · Esc back · q quit '
+                : isCommentsTab()
+                    ? ' Tab tab · ↑↓ select · Enter/Space expand · Esc back · q quit '
+                    : ' Tab tab · ↑↓ scroll · Esc back · q quit '
             : screen === 'ticket-agents'
                 ? ' ↑↓ select · Enter switch · z overview · r retry · x close · Tab/t tickets · q quit '
                 : screen === 'project-runs'
                     ? ' ↑↓ select · Enter ticket · Tab cycle · Esc back · q quit '
-                    : ' ↑↓ select · Enter open · n new · Tab/a agents · u runs · Esc back · q quit ';
+                    : screen === 'project-picker'
+                        ? ' ↑↓ select · Enter open · Esc dashboard · q quit '
+                        : ' ↑↓ select · Enter open · n new · Tab/a agents · u runs · Esc back · q quit ';
         const bar = loading
             ? ' Loading… '
             : error
@@ -254,6 +333,9 @@ export function runTicketTui(_document, _context, services, options = {}) {
         selectedAgent,
         runRows,
         selectedRun,
+        pickerCandidates,
+        pickerRepo,
+        selectedCandidate,
     });
     const restore = (s) => {
         screen = s.screen;
@@ -268,6 +350,9 @@ export function runTicketTui(_document, _context, services, options = {}) {
         selectedAgent = s.selectedAgent;
         runRows = s.runRows;
         selectedRun = s.selectedRun;
+        pickerCandidates = s.pickerCandidates;
+        pickerRepo = s.pickerRepo;
+        selectedCandidate = s.selectedCandidate;
         error = '';
         status = '';
     };
@@ -293,6 +378,112 @@ export function runTicketTui(_document, _context, services, options = {}) {
             draw();
         }
     };
+    /**
+     * Open a project screen from an already-resolved id + name — the deep-link
+     * path (`project:`/`--here`) and the picker's Enter. `openSelectedProject`
+     * cannot be reused: it starts from a dashboard ROW and re-looks-up the project
+     * by name, and neither the resolved route nor the picker has such a row.
+     */
+    const openProjectById = async (projectId, projectName, { push = false, initial = false, } = {}) => {
+        if (loading)
+            return;
+        if (push)
+            history.push(remember());
+        // See `openTicketById`: the deep-link loading frame shows the TARGET screen.
+        if (initial) {
+            screen = 'project';
+            ticketRows = [];
+            currentProjectName = projectName;
+            currentProjectSlug = projectName;
+        }
+        loading = true;
+        error = '';
+        status = '';
+        draw();
+        try {
+            criteria = { query: '', state: null, type: null };
+            searchMode = false;
+            ticketRows = await loadFilteredTickets(services.client, projectId, criteria);
+            currentProjectId = projectId;
+            currentProjectName = projectName;
+            currentProjectSlug = projectName;
+            selectedTicket = 0;
+            offset = 0;
+            screen = 'project';
+        }
+        catch (caught) {
+            if (push)
+                history.pop();
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        finally {
+            loading = false;
+            draw();
+        }
+    };
+    /**
+     * Open a ticket screen from an already-resolved id — the deep-link path.
+     * `tab: 'runs'` activates the Runs tab, which is the observable meaning of a
+     * `run:` target (spec Decision 2, the same landing `openSelectedRunTicket`
+     * produces when you press Enter on a run row).
+     */
+    const openTicketById = async (ticketId, tab, { initial = false } = {}) => {
+        // Booting a deep link: swap to the target screen BEFORE the first draw, so
+        // the loading frame is an empty ticket skeleton and never a dashboard the
+        // user did not ask for (AC-3).
+        if (initial) {
+            screen = 'ticket';
+            detail = null;
+            activeTab = 0;
+        }
+        loading = true;
+        error = '';
+        status = '';
+        draw();
+        try {
+            detail = await loadTicketDetail(services.client, ticketId);
+            screen = 'ticket';
+            activeTab =
+                tab === 'runs'
+                    ? Math.max(0, DETAIL_TABS.findIndex((t) => t.id === 'runs'))
+                    : 0;
+            expandedComments = new Set();
+            selectedComment = 0;
+            offset = 0;
+        }
+        catch (caught) {
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        finally {
+            loading = false;
+            draw();
+        }
+    };
+    /**
+     * GAIA-223 AC-3/AC-4/AC-8: boot the RESOLVED route's screen instead of the
+     * dashboard. No route ⇒ `openDashboard()`, byte-for-byte the previous
+     * behaviour. Nothing here pushes a history frame — there is no frame to go
+     * back to — which is exactly the case Decision 7's back handler covers.
+     */
+    const bootFromRoute = async () => {
+        if (bootRoute === undefined)
+            return openDashboard();
+        if (bootRoute.screen === 'ticket') {
+            return openTicketById(bootRoute.ticketId, bootRoute.tab, {
+                initial: true,
+            });
+        }
+        if (bootRoute.screen === 'project') {
+            return openProjectById(bootRoute.projectId, bootRoute.projectName, {
+                initial: true,
+            });
+        }
+        // The picker's candidates are already in hand — no read at all.
+        screen = 'project-picker';
+        selectedCandidate = 0;
+        offset = 0;
+        draw();
+    };
     const openSelectedProject = async () => {
         const p = projects[selectedProject];
         if (!p || loading)
@@ -771,6 +962,15 @@ export function runTicketTui(_document, _context, services, options = {}) {
                 const previous = history.pop();
                 if (previous)
                     restore(previous);
+                // GAIA-223 Decision 7: a deep-linked screen is not a dead end. Booting
+                // straight into a ticket/project/picker pushes no frame, so Esc used to
+                // do NOTHING and only `q` was left. An empty stack anywhere but the
+                // dashboard now converges on the normal navigation model — which also
+                // fixes the same latent trap for any future screen entered frameless.
+                else if (screen !== 'dashboard') {
+                    void openDashboard();
+                    return;
+                }
                 draw();
                 return;
             }
@@ -845,7 +1045,8 @@ export function runTicketTui(_document, _context, services, options = {}) {
             }
             if (screen === 'ticket') {
                 const tabCount = DETAIL_TABS.length;
-                if (key === '\t') {
+                // AC-7: the compact block has no tabs, so Tab is inert there.
+                if (ticketView === 'full' && key === '\t') {
                     activeTab = (activeTab + 1) % tabCount;
                     offset = 0;
                     selectedComment = 0;
@@ -909,6 +1110,15 @@ export function runTicketTui(_document, _context, services, options = {}) {
                     await openSelectedDetail();
                 else if (screen === 'project-runs')
                     await openSelectedRunTicket();
+                else if (screen === 'project-picker') {
+                    // AC-8: the picked candidate takes the SAME code path a resolved
+                    // `project` route takes — the picker only chose which one.
+                    const picked = pickerCandidates[selectedCandidate];
+                    if (picked)
+                        await openProjectById(picked.id, picked.name, {
+                            push: true,
+                        });
+                }
                 return;
             }
             const { selectable } = screenView();
@@ -945,6 +1155,8 @@ export function runTicketTui(_document, _context, services, options = {}) {
                     selectedAgent = next;
                 else if (screen === 'project-runs')
                     selectedRun = next;
+                else if (screen === 'project-picker')
+                    selectedCandidate = next;
                 else
                     selectedTicket = next;
                 offset = scrollTo(screenView().selRow, offset, viewHeight());
@@ -978,6 +1190,8 @@ export function runTicketTui(_document, _context, services, options = {}) {
         // Surviving agents rehydrate lazily: opening a project's Ticket-Agents screen
         // reconciles it from that project's live panes (AC-5 restart survival) — there
         // is no project context at start, so nothing to reconcile here.
-        void openDashboard();
+        // GAIA-223: with a resolved deep link this boots that screen instead of the
+        // dashboard; without one it IS `openDashboard()` (AC-4).
+        void bootFromRoute();
     });
 }

package/dist/src/Service/route.d.ts

@@ -0,0 +1,11 @@
+import type { DropshClient, ResolvedRoute, UiInitialRoute } from '../types.js';
+/** Context for the error messages — which control plane was asked. */
+export interface ResolveRouteContext {
+    baseUrl?: string | undefined;
+}
+/**
+ * Resolve a CLI deep-link target into the screen the kernel should boot.
+ * Throws — always with a message naming the target and the control plane — when
+ * the target does not exist or is ambiguous.
+ */
+export declare function resolveRoute(client: DropshClient, route: UiInitialRoute, ctx?: ResolveRouteContext): Promise<ResolvedRoute>;

package/dist/src/Service/route.js

@@ -0,0 +1,215 @@
+// GAIA-223: deep-link resolution — the unresolved CLI route (`UiInitialRoute`)
+// against the control plane into the renderer's `ResolvedRoute`.
+//
+// WHERE this runs matters (spec Decision 5). The `gaia ui` entry has no JSON:API
+// client at all — the client first exists as `services.client` inside the dropsh
+// program, in the renderer's `run()`. That is the earliest point resolution can
+// happen, and it is still strictly BEFORE `runTicketTui` reaches
+// `input.setRawMode(true)`. So every failure here throws out of `run()`, through
+// `parseAsync`, into `cmdUi`'s catch: no alternate screen, no raw mode, no
+// dashboard — a stderr line and exit 1 (AC-3).
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+import { asString } from '../lib/format.js';
+import { normalizeRepoUrl } from '../lib/repo-url.js';
+/** `" on <baseUrl>"`, or '' when the caller did not supply one. */
+function on(ctx) {
+    return ctx?.baseUrl ? ` on ${ctx.baseUrl}` : '';
+}
+/** `" (from branch '<b>')"` — so a branch-derived over-match (`release/v2-2026`
+ *  → `V2-2026`, spec § Risks) explains itself instead of looking like a typo. */
+function via(route) {
+    return route.fromBranch ? ` (derived from branch '${route.fromBranch}')` : '';
+}
+/** Read a single resource, mapping any transport failure to `undefined` so the
+ *  caller always produces the same named, actionable error. */
+async function getOne(client, path) {
+    const doc = (await client.get(path).catch(() => undefined));
+    return doc?.data ?? undefined;
+}
+/** The id of a single-valued relationship linkage, or null. */
+function relId(resource, name) {
+    const data = resource.relationships?.[name]?.data;
+    if (!data)
+        return null;
+    return Array.isArray(data) ? (data[0]?.id ?? null) : (data.id ?? null);
+}
+async function resolveTicketByUuid(client, route, ctx) {
+    const found = await getOne(client, `gaia_ticket/gaia_ticket/${route.value}`);
+    if (!found?.id) {
+        throw new Error(`no ticket ${route.value}${on(ctx)}${via(route)}.`);
+    }
+    return { screen: 'ticket', ticketId: found.id, view: route.view ?? 'full' };
+}
+async function resolveTicketByIdentifier(client, route, ctx) {
+    // Pages to TWO, not one: identifiers are unique per PROJECT, so a
+    // cross-project collision is possible in principle. Fetching a second row
+    // turns a silent wrong-ticket into a named ambiguity (spec Decision 6).
+    const params = new DrupalJsonApiParams();
+    params.addFilter('identifier', route.value);
+    params.addPageLimit(2);
+    const doc = (await client
+        .get('gaia_ticket/gaia_ticket', params)
+        .catch(() => undefined));
+    const rows = doc?.data ?? [];
+    if (rows.length === 0) {
+        throw new Error(`no ticket ${route.value}${on(ctx)}${via(route)}.`);
+    }
+    if (rows.length > 1) {
+        const candidates = rows
+            .map((r) => `  ticket:${r.id} — ${asString(r.attributes?.title) ?? ''}`)
+            .join('\n');
+        throw new Error(`${route.value} matches ${rows.length} tickets${on(ctx)}${via(route)}. ` +
+            `Name one with 'ticket:<uuid>':\n${candidates}`);
+    }
+    const id = rows[0]?.id;
+    if (!id) {
+        throw new Error(`no ticket ${route.value}${on(ctx)}${via(route)}.`);
+    }
+    return { screen: 'ticket', ticketId: id, view: route.view ?? 'full' };
+}
+/**
+ * The repo URLs a `gaia_project` row declares, normalised. `repos` is a JSON
+ * field: JSON:API serves it as a real array of objects (measured on dev2), but a
+ * JSON *string* is accepted too so a differently-serialized deployment does not
+ * silently stop matching. Anything unparseable yields no URLs — a malformed row
+ * is skipped, never fatal.
+ */
+function projectRepoIdentities(resource) {
+    const raw = resource.attributes?.repos;
+    let entries;
+    if (typeof raw === 'string') {
+        try {
+            entries = JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+    }
+    else {
+        entries = raw;
+    }
+    if (!Array.isArray(entries))
+        return [];
+    const out = [];
+    for (const entry of entries) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const normalised = normalizeRepoUrl(entry.url);
+        if (normalised !== undefined)
+            out.push(normalised);
+    }
+    return out;
+}
+/**
+ * The `--here` project rung (spec Decision 3): the project(s) whose `repos[]`
+ * claim the cwd's normalised git remote.
+ *
+ * The match is CLIENT-SIDE by necessity, not by taste — `filter[repos]=…`
+ * answers **HTTP 400** (measured): `repos` is a JSON field on the entity, not a
+ * relationship JSON:API can filter inside. So this reads the project collection
+ * (a handful of rows) and matches in memory: one round trip, the same one a name
+ * lookup would have cost.
+ *
+ * Zero matches is the one hard error. TWO OR MORE is NOT — a repo claimed by
+ * several projects is a designed-for topology (Decision 14, AC-8), so it
+ * resolves to the picker screen.
+ */
+async function resolveProjectByRepo(client, route, ctx) {
+    const params = new DrupalJsonApiParams();
+    params.addFields('gaia_project--gaia_project', ['name', 'repos']);
+    params.addPageLimit(200);
+    const doc = (await client
+        .get('gaia_project/gaia_project', params)
+        .catch(() => undefined));
+    const rows = doc?.data ?? [];
+    const candidates = rows
+        .filter((r) => projectRepoIdentities(r).includes(route.value))
+        .map((r) => ({
+        id: r.id ?? '',
+        name: asString(r.attributes?.name) ?? '',
+    }))
+        .filter((c) => c.id !== '');
+    if (candidates.length === 0) {
+        const known = rows
+            .map((r) => asString(r.attributes?.name))
+            .filter((n) => Boolean(n));
+        const list = known.length ? known.join(', ') : '(none visible)';
+        throw new Error(`no gaia project owns the repo ${route.value}${on(ctx)}${via(route)}.\n` +
+            `  Known projects: ${list}\n` +
+            "  Run 'gaia ui' for the dashboard, or 'gaia ui project:<name>' to open one directly.");
+    }
+    if (candidates.length === 1) {
+        const only = candidates[0];
+        return {
+            screen: 'project',
+            projectId: only.id,
+            projectName: only.name || route.value,
+        };
+    }
+    return { screen: 'project-picker', repo: route.value, candidates };
+}
+async function resolveProject(client, route, ctx) {
+    if (route.by === 'repo')
+        return resolveProjectByRepo(client, route, ctx);
+    if (route.by === 'uuid') {
+        const found = await getOne(client, `gaia_project/gaia_project/${route.value}`);
+        if (!found?.id) {
+            throw new Error(`no project ${route.value}${on(ctx)}${via(route)}.`);
+        }
+        return {
+            screen: 'project',
+            projectId: found.id,
+            projectName: asString(found.attributes?.name) ?? route.value,
+        };
+    }
+    // By NAME — the same `collection('gaia_project').where('name','=',…)` read
+    // the project screen already performs, so both agree on what a name means.
+    const found = await client
+        .collection('gaia_project')
+        .where('name', '=', route.value)
+        .first()
+        .catch(() => null);
+    if (!found) {
+        throw new Error(`no project named '${route.value}'${on(ctx)}${via(route)}.`);
+    }
+    return {
+        screen: 'project',
+        projectId: found.id,
+        projectName: found.attr('name') ?? route.value,
+    };
+}
+async function resolveRun(client, route, ctx) {
+    const found = await getOne(client, `gaia_run/gaia_run/${route.value}?include=ticket_id`);
+    if (!found?.id) {
+        throw new Error(`no run ${route.value}${on(ctx)}${via(route)}.`);
+    }
+    const ticketId = relId(found, 'ticket_id');
+    if (!ticketId) {
+        throw new Error(`run ${route.value} has no ticket${on(ctx)}.`);
+    }
+    // Decision 2: the observable meaning of a `run:` target is the owning
+    // ticket's detail screen with the Runs tab active. `runId` rides along even
+    // though nothing renders it, so a later dedicated run screen is a purely
+    // renderer-internal change.
+    return {
+        screen: 'ticket',
+        ticketId,
+        view: 'full',
+        tab: 'runs',
+        runId: found.id,
+    };
+}
+/**
+ * Resolve a CLI deep-link target into the screen the kernel should boot.
+ * Throws — always with a message naming the target and the control plane — when
+ * the target does not exist or is ambiguous.
+ */
+export function resolveRoute(client, route, ctx) {
+    if (route.kind === 'run')
+        return resolveRun(client, route, ctx);
+    if (route.kind === 'project')
+        return resolveProject(client, route, ctx);
+    return route.by === 'uuid'
+        ? resolveTicketByUuid(client, route, ctx)
+        : resolveTicketByIdentifier(client, route, ctx);
+}

package/dist/src/launcher.d.ts

@@ -1,5 +1,5 @@
 import { type GaiaUiOptions } from './plugin.js';
-import type { TuiAgentService } from './types.js';
+import type { TuiAgentService, UiInitialRoute, UiViewMode } from './types.js';
 /** A dropsh program: only the `parseAsync` we drive is modelled. */
 export interface DropshProgram {
     parseAsync(argv: string[], opts: {
@@ -48,7 +48,12 @@ export interface GaiaUiLauncherOptions {
     /** Injected renderer factory; defaults to this package's own plugin. The
      *  `$GAIA_UI_PLUGIN` dev override resolves a different module in the entry. */
     renderer?: ((opts: GaiaUiOptions) => unknown) | undefined;
+    /** GAIA-223: the deep-link target the entry parsed, still UNRESOLVED — the
+     *  entry has no JSON:API client (spec Finding 1), so the renderer resolves it
+     *  in `run()` before the kernel takes the terminal. Absent ⇒ the dashboard. */
+    initialRoute?: UiInitialRoute | undefined;
 }
+export type { UiInitialRoute, UiViewMode };
 /**
  * Build + run the dropsh `--format tui` program with the TUI renderer and the
  * injected agent host. A trivial `search gaia_project` seeds the renderer's

package/dist/src/launcher.js

@@ -32,6 +32,10 @@ export async function runGaiaUi(opts) {
         ...(opts.createPrompt !== undefined
             ? { createPrompt: opts.createPrompt }
             : {}),
+        // Optional at every hop — omitting the key IS the dashboard path (AC-4).
+        ...(opts.initialRoute !== undefined
+            ? { initialRoute: opts.initialRoute }
+            : {}),
     });
     const program = opts.buildProgram({
         plugins: [...opts.connection.authPlugins, renderer],

package/dist/src/lib/repo-url.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `host/path`, with scheme, userinfo, port, a trailing `.git` and trailing
+ * slashes dropped, lowercased. `undefined` when the input carries no host+path.
+ *
+ * | raw                                     | normalised          |
+ * |-----------------------------------------|---------------------|
+ * | `git@host:keytec/gaia.git`              | `host/keytec/gaia`  |
+ * | `ssh://git@host/keytec/gaia.git`        | `host/keytec/gaia`  |
+ * | `ssh://git@host:2222/keytec/gaia.git`   | `host/keytec/gaia`  |
+ * | `https://host/keytec/gaia.git`          | `host/keytec/gaia`  |
+ */
+export declare function normalizeRepoUrl(raw: unknown): string | undefined;

package/dist/src/lib/repo-url.js

@@ -0,0 +1,64 @@
+// GAIA-223 (spec Decision 3) — a git remote URL reduced to a comparable
+// `host/path` identity.
+//
+// DELIBERATE MIRROR of `@gaia-ai/ui`'s `normalizeRepoUrl` (`ui/src/route.ts`),
+// for the same reason `UiInitialRoute` and `HomeConnection` are mirrored: the
+// command package resolves this renderer DYNAMICALLY and must never import it
+// (`ui/tests/no-gaia-ui-import.test.ts`), and the layering forbids an addon from
+// edging `@gaia-ai/ui`. Both sides need the SAME reduction — the CLI normalises
+// the cwd's remote, this side normalises every `gaia_project.repos[].url` — so
+// the function exists twice and is fixture-tested on both sides against the same
+// measured pair.
+/**
+ * `host/path`, with scheme, userinfo, port, a trailing `.git` and trailing
+ * slashes dropped, lowercased. `undefined` when the input carries no host+path.
+ *
+ * | raw                                     | normalised          |
+ * |-----------------------------------------|---------------------|
+ * | `git@host:keytec/gaia.git`              | `host/keytec/gaia`  |
+ * | `ssh://git@host/keytec/gaia.git`        | `host/keytec/gaia`  |
+ * | `ssh://git@host:2222/keytec/gaia.git`   | `host/keytec/gaia`  |
+ * | `https://host/keytec/gaia.git`          | `host/keytec/gaia`  |
+ */
+export function normalizeRepoUrl(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return undefined;
+    let host;
+    let path;
+    // `scheme://[user@]host[:port]/path` — checked FIRST, so an `ssh://…:2222/…`
+    // port is never mistaken for the scp form's `host:path` colon.
+    const withScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/(.+)$/.exec(trimmed);
+    if (withScheme?.[1] !== undefined) {
+        const rest = withScheme[1];
+        const slash = rest.indexOf('/');
+        if (slash < 0)
+            return undefined;
+        host = rest.slice(0, slash);
+        path = rest.slice(slash + 1);
+    }
+    else {
+        // The scp-like form `[user@]host:path` — what `git remote get-url` emits for
+        // an ssh clone. A bare local path has no colon and falls out here.
+        const scp = /^(?:[^/@]+@)?([^/:]+):(.+)$/.exec(trimmed);
+        if (scp?.[1] === undefined || scp[2] === undefined)
+            return undefined;
+        host = scp[1];
+        path = scp[2];
+    }
+    host = host
+        .replace(/^[^@]*@/, '')
+        .replace(/:\d+$/, '')
+        .toLowerCase();
+    path = path
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/i, '')
+        .replace(/\/+$/, '')
+        .toLowerCase();
+    if (host === '' || path === '')
+        return undefined;
+    return `${host}/${path}`;
+}

package/dist/src/plugin.js

@@ -1,7 +1,15 @@
 import { runTicketTui } from './Kernel/tui-kernel.js';
+import { resolveRoute } from './Service/route.js';
 // The dropsh `tui` renderer plugin: a single interactive renderer that hands off
 // to the TUI kernel. The conductor's plugin resolver auto-picks the default
 // export, so the factory is the module default.
+//
+// GAIA-223 (spec Decision 5): `run()` is ALSO where a deep-link target is
+// resolved. It is the earliest point at which a JSON:API client exists —
+// `services.client` — and it is still strictly before the kernel reaches
+// `input.setRawMode(true)`. A resolution failure therefore rejects out of
+// `run()`, through dropsh's `parseAsync`, into `cmdUi`'s catch: no alternate
+// screen, no raw mode, no dashboard — a stderr line and exit 1 (AC-3).
 export default function gaiaUiPlugin(options = {}) {
     return {
         id: 'gaia-ticket-renderer',
@@ -10,7 +18,20 @@ export default function gaiaUiPlugin(options = {}) {
             {
                 id: 'tui',
                 interactive: true,
-                run: (document, context, services) => runTicketTui(document, context, services, options),
+                run: async (document, context, services) => {
+                    const route = options.initialRoute === undefined
+                        ? undefined
+                        : await resolveRoute(services.client, options.initialRoute, {
+                            ...(services.baseUrl !== undefined
+                                ? { baseUrl: services.baseUrl }
+                                : {}),
+                        });
+                    return runTicketTui(document, context, services, {
+                        ...options,
+                        // Optional at every hop — omitting the key IS the dashboard path.
+                        ...(route !== undefined ? { route } : {}),
+                    });
+                },
             },
         ],
     };

package/dist/src/types.d.ts

@@ -87,6 +87,66 @@ export interface RendererServices {
     /** Config override for the ticket-create agent's base prompt. */
     createPrompt?: string;
 }
+/** How a ticket target is rendered. Mirrors the Drupal `gaia_ticket` view modes. */
+export type UiViewMode = 'full' | 'teaser' | 'board_card';
+/**
+ * A deep-link target as the CLI parsed it — UNRESOLVED. It says what to look up
+ * and how, never what screen results. Mirror of `@gaia-ai/ui`'s `UiInitialRoute`.
+ */
+export interface UiInitialRoute {
+    kind: 'ticket' | 'project' | 'run';
+    /**
+     * How `value` must be looked up. `'repo'` is the `--here` project rung: the
+     * value is a NORMALISED remote URL (`host/path`), matched client-side against
+     * every `gaia_project.repos[].url` (spec Decision 3).
+     */
+    by: 'uuid' | 'identifier' | 'name' | 'repo';
+    value: string;
+    /** Drupal view mode for a ticket target; default 'full'. */
+    view?: UiViewMode | undefined;
+    /** Set when the target came from `--here`; error messages only. */
+    fromBranch?: string | undefined;
+}
+/**
+ * A route AFTER resolution against the control plane — renderer-internal, never
+ * crossing a package boundary, so it may speak screen vocabulary.
+ *
+ * `view` and `tab` are orthogonal and both needed: `view` says HOW the ticket is
+ * rendered (the tabbed detail vs. a compact block), `tab` says which detail tab
+ * is active WHEN `view` is 'full'. A `run:` target sets `tab: 'runs'`. The
+ * project variant carries both id and name — the kernel queries by id and
+ * headlines by name, and resolving `project:<uuid>` already fetched both.
+ */
+export type ResolvedRoute = {
+    screen: 'ticket';
+    ticketId: string;
+    view: UiViewMode;
+    tab?: 'runs' | undefined;
+    /** Carried even though nothing renders it yet, so a future dedicated run
+     *  screen needs no change to the CLI grammar or the launcher contract. */
+    runId?: string | undefined;
+} | {
+    screen: 'project';
+    projectId: string;
+    projectName: string;
+}
+/**
+ * Spec Decision 14 (AC-8): several gaia projects claim the same repo — a
+ * DESIGNED-FOR topology (GAIA-126/137 map each site of a Drupal multisite repo
+ * to its own project), so `--here` shows the ambiguity and lets the user pick
+ * instead of failing permanently. This is the one route outcome that is a
+ * screen rather than a lookup result, which is why Decision 5's "abort before
+ * the TUI" invariant is scoped to FAILURES.
+ */
+ | {
+    screen: 'project-picker';
+    /** The normalised `host/path` every candidate claims. */
+    repo: string;
+    candidates: {
+        id: string;
+        name: string;
+    }[];
+};
 /** Options passed by the factory into the kernel. */
 export interface TuiOptions {
     project?: string;
@@ -95,4 +155,9 @@ export interface TuiOptions {
     currentUser?: string;
     ownConductorMachineId?: string;
     createPrompt?: string;
+    /** GAIA-223: the unresolved deep-link target, as it arrived from the CLI. */
+    initialRoute?: UiInitialRoute | undefined;
+    /** GAIA-223: the RESOLVED route the plugin's `run()` produced. The kernel
+     *  boots this screen instead of the dashboard; absent ⇒ dashboard (AC-4). */
+    route?: ResolvedRoute | undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/addon-gaia-ui",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "GAIA TUI: interactive terminal UI (project dashboard, ticket list, ticket detail) as a dropsh `tui` renderer plugin.",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,6 @@
     "drupal-jsonapi-params": "^3.0.1"
   },
   "peerDependencies": {
-    "@gaia-ai/core": "^0.6.1"
+    "@gaia-ai/core": "^0.6.2"
   }
 }