@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/dist/app/session-shell/workflow-output.js

@@ -0,0 +1,174 @@
+import { createPiShellArmin, createPiShellEarendilAnnouncement, } from "../../integrations/pi/components/shell-selectors-dialogs.js";
+import { createPiShellChangelog, createPiShellHotkeys, createPiShellSessionInfo, renderPiShellCommandMessage, renderPiShellStatusText, } from "../../integrations/pi/components/shell-presenters-info.js";
+import { piShellHyperlink } from "../../integrations/pi/components/shell-shared-facade.js";
+/**
+ * Presents workflow results: bare A1 answers in the dock notice, the pinned profile appends
+ * transcript-anchored output, and consecutive status lines at the same anchor replace each other.
+ */
+export class WorkflowOutput {
+    #ports;
+    #sequence = 0;
+    #statusMessages = new Map();
+    #lastStatusId;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    appendStatus(message) {
+        // Rationale: bare A1 acknowledges commands in one dock notice above the editor, where the
+        // reader's eye already is, instead of a transcript row that opens an empty session at the
+        // top-left or sinks into a long feed. The pinned route keeps Pi's chat placement.
+        if (this.#ports.customViewport) {
+            this.#ports.dock.setNotice({ kind: "status", message });
+            return;
+        }
+        const { document } = this.#ports;
+        const previousId = this.#lastStatusId;
+        if (previousId !== undefined
+            && document.lastId === previousId
+            && document.anchorOf(previousId) === this.#ports.transcriptLength()) {
+            this.#statusMessages.set(previousId, message);
+            document.invalidate("workflow-status");
+            this.#ports.invalidate();
+            return;
+        }
+        const id = this.#appendAnchored(width => [
+            "",
+            ...renderPiShellStatusText(this.#statusMessages.get(id) ?? message, width),
+        ]);
+        this.#statusMessages.set(id, message);
+        this.#lastStatusId = id;
+    }
+    appendMessage(message, errorCode) {
+        if (message.kind === "status") {
+            this.appendStatus(message.message);
+            return;
+        }
+        if (this.#ports.customViewport && (message.kind === "warning" || message.kind === "error")) {
+            this.#ports.dock.setNotice({
+                kind: errorCode === "image-count" ? "warning" : message.kind,
+                message: message.message,
+                ...(errorCode === undefined ? {} : { errorCode }),
+            });
+            return;
+        }
+        this.#lastStatusId = undefined;
+        const presentation = { kind: message.kind, message: message.message };
+        this.#appendAnchored(width => renderPiShellCommandMessage(presentation, width, this.#ports.outputPad()));
+    }
+    appendResult(result, errorCode) {
+        if (result.messages !== undefined) {
+            for (const message of result.messages)
+                this.appendMessage(message, errorCode);
+            return;
+        }
+        if (result.messageKind === "silent" || (result.outcome === "cancelled" && result.messageKind === undefined))
+            return;
+        if (result.command === "reload" && result.outcome === "completed") {
+            this.appendStatus(result.message);
+            return;
+        }
+        if (result.outcome === "completed" && this.#appendPresentation(result))
+            return;
+        if (result.outcome === "failed") {
+            this.appendMessage({
+                kind: result.messageKind === "warning" ? "warning" : "error",
+                message: result.message,
+            }, errorCode);
+            return;
+        }
+        if (result.outcome === "completed" && (result.command === "quit" || result.command === "compact"))
+            return;
+        if (result.outcome === "completed" && result.command === "new" && this.#ports.customViewport) {
+            // Rationale: bare A1 keeps the replacement session visually empty while preserving Pi's accent notice shape.
+            this.#ports.dock.setNotice({ kind: "new-session", message: result.message });
+            return;
+        }
+        if (result.outcome === "completed" && (result.command === "new" || result.command === "name" || result.command === "debug")) {
+            this.#lastStatusId = undefined;
+            const presentation = { kind: result.command, message: result.message, ...(result.detail === undefined ? {} : { detail: result.detail }) };
+            this.#appendAnchored(width => renderPiShellCommandMessage(presentation, width, this.#ports.outputPad()));
+            return;
+        }
+        if (result.outcome === "completed" && this.#appendAnnouncement(result.command))
+            return;
+        // Rationale: the pinned engine links both share URLs; the workflow result carries the plain URLs.
+        const message = result.command !== "share" ? result.message
+            : result.detail ? `${linkShareUrl(result.message)}\nGist: ${piShellHyperlink(result.detail)}`
+                // Protocol: Radius shares carry only the artifact URL.
+                : linkShareUrl(result.message);
+        this.appendStatus(message);
+    }
+    /** Drops every anchored output and the status-replacement chain. */
+    reset() {
+        this.#ports.document.removeAnchored();
+        this.#statusMessages.clear();
+        this.#lastStatusId = undefined;
+    }
+    // Invariant: session info, hotkeys, and changelog draw their own components; false for any other completed command.
+    #appendPresentation(result) {
+        if (result.command === "session" && result.presentation?.kind === "session-info") {
+            this.#lastStatusId = undefined;
+            const sessionInfo = createPiShellSessionInfo(result.presentation);
+            this.#appendAnchored(width => sessionInfo.render(width), () => sessionInfo.dispose?.());
+            return true;
+        }
+        if (result.command === "hotkeys") {
+            this.#lastStatusId = undefined;
+            const presentation = this.#ports.hotkeysPresentation();
+            const hotkeys = createPiShellHotkeys(presentation.bindings, presentation.getShortcuts, presentation.profile, presentation.residentTabs);
+            this.#appendAnchored(width => hotkeys.render(width), () => hotkeys.dispose?.());
+            return true;
+        }
+        if (result.command === "changelog") {
+            this.#lastStatusId = undefined;
+            const changelog = createPiShellChangelog(result.detail ?? "No changelog entries found.");
+            this.#appendAnchored(width => changelog.render(width), () => changelog.dispose?.());
+            return true;
+        }
+        return false;
+    }
+    // Invariant: the two easter-egg announcements; false for any other command.
+    #appendAnnouncement(command) {
+        if (command === "arminsayshi") {
+            this.#lastStatusId = undefined;
+            const armin = createPiShellArmin(this.#ports.componentRuntime);
+            this.#appendAnchored(width => ["", ...armin.render(width)], () => armin.dispose?.());
+            return true;
+        }
+        if (command === "dementedelves") {
+            this.#lastStatusId = undefined;
+            const announcement = createPiShellEarendilAnnouncement();
+            this.#appendAnchored(width => ["", ...announcement.render(width)], () => announcement.dispose?.());
+            return true;
+        }
+        return false;
+    }
+    #appendAnchored(render, dispose) {
+        // Invariant: transcript-bound workflow output supersedes a pending acknowledgement.
+        this.#ports.dock.dismissNotice();
+        this.#sequence += 1;
+        const id = `workflow-status-${this.#sequence}`;
+        const component = {
+            id,
+            revision: 1,
+            render,
+            handleInput() { },
+            invalidate() { },
+            update() { },
+            setExpanded() { },
+            setOutputPad() { },
+            setHideThinkingBlock() { },
+            setMermaidRenderingMode() { },
+            setImagePresentation() { },
+            ...(dispose === undefined ? {} : { dispose }),
+        };
+        this.#ports.document.appendAnchored(id, component, this.#ports.transcriptLength());
+        this.#ports.invalidate();
+        return id;
+    }
+}
+/** "Share URL: <url>" with the URL made clickable; other share wordings pass through unchanged. */
+function linkShareUrl(message) {
+    const match = /^Share URL: (\S+)$/.exec(message);
+    return match === null ? message : `Share URL: ${piShellHyperlink(match[1])}`;
+}

package/dist/app/session-shell/workflow-router.d.ts

@@ -0,0 +1,25 @@
+import type { OwnedUiCommandResult, OwnedUiWorkflowRequest } from "../../contracts/owned-ui/index.js";
+/** The owned selectors a workflow can open in place of asking the engine to choose. */
+export interface WorkflowSelectors {
+    showScopedModelsSelector(): void;
+    showModelsDialog(initialQuery?: string): void;
+    showModelSelector(initialSearchInput?: string): void;
+    showForkSelector(): void;
+    showThinkingSelector(): Promise<void>;
+    showTrustSelector(): void;
+    showSettingsSelector(): void;
+    showSessionSelector(): Promise<void>;
+    showLoginAuthTypeSelector(): void;
+    showLoginMethodSelector(providerReference: string): void;
+    showLogoutSelector(): Promise<void>;
+    showTreeSelector(): Promise<void>;
+}
+/**
+ * Opens the owned selector a workflow request asks for when the user has not chosen yet. Returns
+ * the command result when a selector handled the request, settling once an asynchronous selector
+ * has opened, or undefined when the request goes to the engine. The decision itself is synchronous,
+ * so a request that goes to the engine reaches it in the same turn.
+ */
+export declare function openWorkflowSelector(request: OwnedUiWorkflowRequest, selectors: WorkflowSelectors, options: {
+    readonly residentTab: boolean;
+}): OwnedUiCommandResult | Promise<OwnedUiCommandResult> | undefined;

package/dist/app/session-shell/workflow-router.js

@@ -0,0 +1,39 @@
+const unchosen = (request) => request.selection === undefined && request.confirmed === undefined;
+const unchosenBare = (request) => unchosen(request) && request.argument.trim().length === 0;
+// Invariant: the routes are checked in this order, matching the order the workflows were introduced.
+const SELECTOR_ROUTES = [
+    { command: "scoped-models", pending: unchosen, open: selectors => selectors.showScopedModelsSelector() },
+    { command: "models", pending: request => request.selection === undefined, open: (selectors, request) => selectors.showModelsDialog(request.argument.trim() || undefined) },
+    { command: "model", pending: unchosenBare, open: selectors => selectors.showModelSelector() },
+    { command: "fork", pending: unchosen, open: selectors => selectors.showForkSelector() },
+    { command: "thinking", pending: request => request.selection === undefined && request.argument.trim().length === 0, open: selectors => selectors.showThinkingSelector() },
+    { command: "trust", pending: unchosen, open: selectors => selectors.showTrustSelector() },
+    { command: "settings", pending: unchosen, open: selectors => selectors.showSettingsSelector() },
+    { command: "resume", pending: unchosenBare, open: selectors => selectors.showSessionSelector() },
+    {
+        command: "login",
+        pending: unchosen,
+        open: (selectors, request) => request.argument.trim().length === 0
+            ? selectors.showLoginAuthTypeSelector()
+            : selectors.showLoginMethodSelector(request.argument),
+    },
+    { command: "logout", pending: unchosen, open: selectors => selectors.showLogoutSelector() },
+    { command: "tree", pending: unchosenBare, open: selectors => selectors.showTreeSelector() },
+];
+/**
+ * Opens the owned selector a workflow request asks for when the user has not chosen yet. Returns
+ * the command result when a selector handled the request, settling once an asynchronous selector
+ * has opened, or undefined when the request goes to the engine. The decision itself is synchronous,
+ * so a request that goes to the engine reaches it in the same turn.
+ */
+export function openWorkflowSelector(request, selectors, options) {
+    const route = SELECTOR_ROUTES.find(candidate => candidate.command === request.command && candidate.pending(request));
+    if (route === undefined)
+        return undefined;
+    if (route.command === "settings" && options.residentTab) {
+        return { outcome: "rejected", diagnostic: "Settings is available from the global Settings tab." };
+    }
+    const completed = { outcome: "completed", diagnostic: null };
+    const opened = route.open(selectors, request);
+    return opened instanceof Promise ? opened.then(() => completed) : completed;
+}

package/dist/cli/dispatch.d.ts

@@ -1,7 +1,8 @@
-import { type InteractiveLaunchIntent, type LaunchProfileId, type SessionSelection } from "../features/launch/index.js";
+import { type InteractiveLaunchIntent, type InteractiveLaunchMode, type LaunchProfileId, type SessionSelection } from "../features/launch/index.js";
 import type { CliCapabilities } from "./capabilities.js";
 import type { PackageCommandRequest } from "./packages.js";
 import type { SessionContextRequest } from "./session-context.js";
+import type { TabsRequest } from "./tabs-request.js";
 import { type PackageCliVerb, type PackageCommandNamespace, type PackageSyntaxDiagnostic } from "./package-messages.js";
 export type UpdateChannel = "stable" | "next";
 export interface CliHandlers {
@@ -10,6 +11,7 @@ export interface CliHandlers {
     readonly update: (channel: UpdateChannel, target?: string) => Promise<number>;
     readonly packages: (request: PackageCommandRequest) => Promise<number>;
     readonly sessionContext: (request: SessionContextRequest) => Promise<number>;
+    readonly tabs: (request: TabsRequest) => Promise<number>;
 }
 export interface CliOutput {
     readonly stdout: (message: string) => void;
@@ -17,6 +19,8 @@ export interface CliOutput {
 }
 export declare function cliUsage(capabilities: CliCapabilities): string;
 export declare function cliHelp(capabilities: CliCapabilities): string;
+/** Focused help for the resident-tab maintenance forms; printing it contacts no host. */
+export declare function tabsHelp(): string;
 export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput, capabilities: CliCapabilities): Promise<number>;
 export type CliCommand = {
     readonly kind: "noop";
@@ -33,6 +37,7 @@ export type CliCommand = {
 } | {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;
+    readonly launchMode: InteractiveLaunchMode;
     readonly sessionSelection?: SessionSelection;
 } | {
     readonly kind: "version";
@@ -46,6 +51,11 @@ export type CliCommand = {
 } | {
     readonly kind: "session-context";
     readonly request: SessionContextRequest;
+} | {
+    readonly kind: "tabs";
+    readonly request: TabsRequest;
+} | {
+    readonly kind: "tabs-help";
 } | {
     readonly kind: "error";
     readonly message: string;

package/dist/cli/dispatch.js

@@ -6,6 +6,7 @@ export function cliUsage(capabilities) {
         "",
         "--session <path|id>",
         "--session-dir <dir> --session <path|id>",
+        "solo",
         ...(capabilities.developmentComparison ? ["pi"] : []),
         "help",
         "version",
@@ -21,6 +22,10 @@ export function cliUsage(capabilities) {
         "session worktrees",
         "session link-worktree <path>",
         "session unlink-worktree",
+        "tabs",
+        "tabs stop <id>|--all",
+        "tabs host status|stop",
+        "tabs doctor",
     ]);
 }
 export function cliHelp(capabilities) {
@@ -30,6 +35,7 @@ export function cliHelp(capabilities) {
         `  ${command}`,
         `  ${command} --session <path|id>`,
         `  ${command} --session-dir <dir> --session <path|id>`,
+        `  ${command} solo`,
         ...(capabilities.developmentComparison ? [`  ${command} pi`] : []),
         `  ${command} help`,
         `  ${command} version`,
@@ -52,9 +58,32 @@ export function cliHelp(capabilities) {
         `  ${command} session link-worktree <path>`,
         `  ${command} session unlink-worktree`,
         "",
+        "Tabs:",
+        `  ${command} tabs`,
+        `  ${command} tabs stop <id>|--all`,
+        `  ${command} tabs host status|stop`,
+        `  ${command} tabs doctor`,
+        "",
+    ].join("\n");
+}
+/** Focused help for the resident-tab maintenance forms; printing it contacts no host. */
+export function tabsHelp() {
+    const command = PRODUCT_TEXT.commandName;
+    return [
+        "Resident tabs:",
+        `  ${command} tabs                    List running tabs`,
+        `  ${command} tabs stop <id>          Stop one tab; its session stays resumable`,
+        `  ${command} tabs stop --all         Stop every tab and keep the host`,
+        `  ${command} tabs host status        Show host identity, limits, and health counters`,
+        `  ${command} tabs host stop          Stop every tab and the host`,
+        `  ${command} tabs doctor             Write a redacted diagnostic bundle`,
+        "",
+        "Options:",
+        "  --json                     Print the versioned machine-readable report",
+        "",
     ].join("\n");
 }
-const PROFILE_WORDS = new Set(["pi"]);
+const PROFILE_WORDS = new Set(["pi", "solo"]);
 export async function dispatchCli(arguments_, handlers, output, capabilities) {
     const command = parseCliCommand(arguments_, capabilities);
     if (command.kind === "noop")
@@ -76,23 +105,29 @@ export async function dispatchCli(arguments_, handlers, output, capabilities) {
         return 2;
     }
     if (command.kind === "launch")
-        return await handlers.launch(interactiveLaunchIntent(command.profileId, command.sessionSelection));
+        return await handlers.launch(interactiveLaunchIntent(command.profileId, command.sessionSelection, command.launchMode));
     if (command.kind === "version")
         return await handlers.version();
     if (command.kind === "packages")
         return await handlers.packages(command.request);
     if (command.kind === "session-context")
         return await handlers.sessionContext(command.request);
+    if (command.kind === "tabs-help") {
+        output.stdout(tabsHelp());
+        return 0;
+    }
+    if (command.kind === "tabs")
+        return await handlers.tabs(command.request);
     return await handlers.update(command.channel, command.target);
 }
 export function parseCliCommand(arguments_, capabilities) {
     if (arguments_.length === 0)
-        return { kind: "launch", profileId: "a1" };
+        return { kind: "launch", profileId: "a1", launchMode: "tabs" };
     const [command, ...rest] = arguments_;
     if (command === "--session" || command === "--session-dir") {
         try {
             const sessionSelection = parseSessionSelection(arguments_);
-            return { kind: "launch", profileId: "a1", ...(sessionSelection === undefined ? {} : { sessionSelection }) };
+            return { kind: "launch", profileId: "a1", launchMode: "tabs", ...(sessionSelection === undefined ? {} : { sessionSelection }) };
         }
         catch (error) {
             return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse session launch: ${error instanceof Error ? error.message : String(error)}`) };
@@ -108,18 +143,57 @@ export function parseCliCommand(arguments_, capabilities) {
     if (command === "pi") {
         if (rest.length > 0)
             return parsePackageCommand(rest, "pi");
-        return capabilities.developmentComparison ? { kind: "launch", profileId: "pi" } : { kind: "noop" };
+        return capabilities.developmentComparison ? { kind: "launch", profileId: "pi", launchMode: "solo" } : { kind: "noop" };
     }
+    if (command === "solo")
+        return withoutArguments(rest, { kind: "launch", profileId: "a1", launchMode: "solo" });
     if (command === "update")
         return parseUpdate(rest);
     if (command === "session")
         return parseSessionContext(rest);
+    if (command === "tabs")
+        return parseTabs(rest);
     if (command?.startsWith("update:"))
         return { kind: "noop" };
     // Rationale: unsupported and reserved command spaces are deliberately quiet. Help is
     // explicit, and a typo must never start an interactive or maintenance path.
     return { kind: "noop" };
 }
+/** Parses `a1 tabs` before any I/O; a malformed form fails with one line and contacts no host. */
+function parseTabs(rest) {
+    if (rest.some(value => value === "--help" || value === "-h"))
+        return { kind: "tabs-help" };
+    const json = rest.includes("--json");
+    const words = rest.filter(value => value !== "--json");
+    const fail = (detail) => ({ kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse tabs: ${detail}`) });
+    const [action, value, extra] = words;
+    if (action === undefined)
+        return { kind: "tabs", request: { action: "list", json } };
+    if (action === "stop") {
+        if (value === undefined)
+            return fail("stop requires a tab id or --all.");
+        if (extra !== undefined)
+            return fail("stop accepts one tab id or --all.");
+        if (value === "--all")
+            return { kind: "tabs", request: { action: "stop-all", json } };
+        if (value.startsWith("-"))
+            return fail(`unknown option ${value}.`);
+        return { kind: "tabs", request: { action: "stop", tabId: value, json } };
+    }
+    if (action === "host") {
+        if (extra !== undefined || (value !== "status" && value !== "stop"))
+            return fail("host accepts status or stop.");
+        return { kind: "tabs", request: { action: value === "status" ? "host-status" : "host-stop", json } };
+    }
+    if (action === "doctor") {
+        if (value !== undefined)
+            return fail("doctor does not accept arguments.");
+        return { kind: "tabs", request: { action: "doctor", json } };
+    }
+    if (action.startsWith("-"))
+        return fail(`unknown option ${action}.`);
+    return fail(`unknown subcommand ${action}; use list, stop, host, or doctor.`);
+}
 function parseSessionContext(rest) {
     const [action, value, extra] = rest;
     if (action === "link-worktree") {

package/dist/cli/tabs-request.d.ts

@@ -0,0 +1,7 @@
+export type TabsAction = "list" | "stop" | "stop-all" | "host-status" | "host-stop" | "doctor";
+/** One parsed `a1 tabs` form. Parsing finishes before any host is contacted. */
+export interface TabsRequest {
+    readonly action: TabsAction;
+    readonly tabId?: string;
+    readonly json: boolean;
+}

package/dist/cli/tabs-request.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/tabs.d.ts

@@ -0,0 +1,14 @@
+import { runTerminalHostMaintenance, writeDoctorBundle } from "../foundation/resident-tabs/index.js";
+import type { TabsRequest } from "./tabs-request.js";
+export type { TabsRequest } from "./tabs-request.js";
+export interface TabsCommandOptions {
+    /** The invoking package, never a different active or retained release. */
+    readonly packageRoot?: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly stdout?: (message: string) => void;
+    readonly stderr?: (message: string) => void;
+    readonly maintenance?: typeof runTerminalHostMaintenance;
+    readonly doctor?: typeof writeDoctorBundle;
+}
+/** `a1 tabs`: inspect or stop resident tabs without attaching, and never start a host to report state. */
+export declare function runTabsCommand(request: TabsRequest, options?: TabsCommandOptions): Promise<number>;

package/dist/cli/tabs.js

@@ -0,0 +1,151 @@
+import { resolveProductPaths } from "../foundation/lifecycle/index.js";
+import { materializeRelease } from "../foundation/release/index.js";
+import { readResidentTabLaunchSettings, runTerminalHostMaintenance, writeDoctorBundle, } from "../foundation/resident-tabs/index.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../product-identity.js";
+/** `a1 tabs`: inspect or stop resident tabs without attaching, and never start a host to report state. */
+export async function runTabsCommand(request, options = {}) {
+    const environment = options.environment ?? process.env;
+    const stdout = options.stdout ?? (message => process.stdout.write(message));
+    const stderr = options.stderr ?? (message => process.stderr.write(message));
+    const paths = resolveProductPaths(environment);
+    const profileRoot = environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir;
+    const releaseRoots = await invokingReleaseRoots(paths.dataDir, options.packageRoot, environment);
+    const maintenance = options.maintenance ?? runTerminalHostMaintenance;
+    const report = await maintenance({
+        action: request.action === "doctor" ? "host-status" : request.action,
+        ...(request.tabId === undefined ? {} : { tabId: request.tabId }),
+        profileRoot,
+        dataDir: paths.dataDir,
+        runtimeDir: paths.runtimeDir,
+        releaseRoots,
+        environment,
+    });
+    if (request.action === "doctor") {
+        if (!report.stateDir) {
+            stderr(`${PRODUCT_TEXT.diagnostic(`tabs doctor could not locate resident state: ${report.message ?? report.host}`)}\n`);
+            return 1;
+        }
+        const settings = await readResidentTabLaunchSettings(environment.PI_CODING_AGENT_DIR ?? paths.configDir, PRODUCT_IDENTITY.commandName, paths.configDir, "a1");
+        const bundle = await (options.doctor ?? writeDoctorBundle)({
+            stateDir: report.stateDir,
+            hostStatus: report,
+            releaseRoots,
+            settings: { tabsAutoName: settings.tabsAutoName },
+        });
+        if (request.json)
+            stdout(`${JSON.stringify({ schema: "a1-tabs-doctor-v1", path: bundle.path, bytes: bundle.bytes, dropped: bundle.dropped })}\n`);
+        else
+            stdout(`Wrote ${bundle.path}\n`);
+        return 0;
+    }
+    if (request.json) {
+        const { exitCode: _exitCode, ...printed } = report;
+        stdout(`${JSON.stringify(printed)}\n`);
+    }
+    else {
+        const text = describe(request, report);
+        if (report.exitCode === 0)
+            stdout(text);
+        else
+            stderr(text);
+    }
+    return report.exitCode === 0 ? 0 : 1;
+}
+async function invokingReleaseRoots(dataDir, packageRoot, environment) {
+    if (!packageRoot)
+        return [];
+    if (environment[PRODUCT_IDENTITY.environment.developmentInstanceId])
+        return [packageRoot];
+    try {
+        // Invariant: immutable materialization selects exact payload bytes without activating or starting a host.
+        return [(await materializeRelease(packageRoot, dataDir)).releaseRoot];
+    }
+    catch {
+        return [];
+    }
+}
+const NO_TABS = "No resident tabs are running.\n";
+function describe(request, report) {
+    const command = PRODUCT_TEXT.commandName;
+    if (report.host === "none")
+        return NO_TABS;
+    if (report.host === "unavailable")
+        return `${PRODUCT_TEXT.diagnostic(`tabs could not run maintenance: ${report.message ?? "terminal host unavailable"}`)}\n`;
+    if (report.host === "unresponsive") {
+        return `The resident host (pid ${report.pid ?? "unknown"}) is not responding. Run \`${command} tabs host stop\` to stop it.\n`;
+    }
+    if (report.host === "incompatible") {
+        return `${PRODUCT_TEXT.diagnostic(report.message ?? "running tabs use another version")} Run \`${command} tabs host stop\` from that version.\n`;
+    }
+    if (report.host === "unverifiable" || report.host === "refused") {
+        return `${PRODUCT_TEXT.diagnostic(report.message ?? "the resident host could not be verified; nothing was changed")}\n`;
+    }
+    const result = report.result ?? {};
+    if (request.action === "list")
+        return listing(result);
+    if (request.action === "host-status")
+        return status(result);
+    if (request.action === "host-stop") {
+        if (report.host === "stopped")
+            return "Stopped every tab and the resident host.\n";
+        return `Could not stop every tab: ${remaining(result)}. The host is still running.\n`;
+    }
+    if (result.accepted === false && typeof result.message === "string") {
+        return `${PRODUCT_TEXT.diagnostic(`tabs stop: ${result.message === "unknown tab" ? `no tab ${request.tabId ?? ""}` : result.message}`)}\n`;
+    }
+    const stopped = Array.isArray(result.stopped) ? result.stopped.length : 0;
+    if (result.accepted === false)
+        return `Could not stop: ${remaining(result)}.\n`;
+    if (request.action === "stop")
+        return `Stopped tab ${request.tabId ?? ""}; its session can be resumed.\n`;
+    return stopped === 0 ? NO_TABS : `Stopped ${stopped} tab${stopped === 1 ? "" : "s"}; their sessions can be resumed.\n`;
+}
+function remaining(result) {
+    return Array.isArray(result.remaining) && result.remaining.length > 0 ? result.remaining.join(", ") : "unknown tabs";
+}
+function listing(result) {
+    const tabs = Array.isArray(result.tabs) ? result.tabs : [];
+    if (tabs.length === 0)
+        return NO_TABS;
+    const rows = [
+        ["ID", "NAME", "STATUS", "CWD", "RELEASE", "HOLDER"],
+        ...tabs.map(tab => [tab.tabId, tab.name, tab.status, tab.cwd, tab.release, tab.holderPid ?? "-"].map(value => String(value ?? "-"))),
+    ];
+    const widths = rows[0].map((_, column) => Math.max(...rows.map(row => row[column].length)));
+    return `${rows.map(row => row.map((cell, column) => column === row.length - 1 ? cell : cell.padEnd(widths[column])).join("  ")).join("\n")}\n`;
+}
+function status(result) {
+    const limits = (result.limits ?? {});
+    const counters = (result.counters ?? {});
+    const byStatus = (result.tabsByStatus ?? {});
+    const lines = [
+        `pid: ${String(result.pid ?? "-")}`,
+        `build: ${String(result.build ?? "-")}`,
+        `release: ${String(result.release ?? "-")}`,
+        `generation: ${String(result.generation ?? "-")}`,
+        `epoch: ${String(result.epoch ?? "-")}`,
+        `uptime: ${String(result.uptimeSeconds ?? "-")}s`,
+        `detachment: ${String(result.detachmentMode ?? "unknown")}${result.detachmentVerified === false ? " (not verified)" : ""}`,
+        `tabs: ${String(result.tabs ?? 0)}${Object.keys(byStatus).length > 0 ? ` (${Object.entries(byStatus).map(([key, value]) => `${key} ${String(value)}`).join(", ")})` : ""}`,
+        `clients: ${String(result.clients ?? 0)}`,
+        ...startsAndLifecycle(result),
+        `limits: ${Object.entries(limits).map(([key, value]) => `${key} ${String(value)}`).join(", ")}`,
+        `counters: ${Object.entries(counters).map(([key, value]) => `${key} ${String(value)}`).join(", ")}`,
+        ...(Array.isArray(result.logs) ? result.logs.map(path => `log: ${String(path)}`) : []),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/** Lifecycle work running this long means a terminal's tab requests are stuck. */
+const LIFECYCLE_STALL_MS = 10_000;
+function startsAndLifecycle(result) {
+    const lines = [];
+    const starts = result.starts;
+    if (starts)
+        lines.push(`starts: active ${String(starts.active ?? 0)}, waiting ${String(starts.interactiveWaiting ?? 0)}, recovering ${String(starts.recoverySlots ?? 0)}`);
+    const lifecycle = result.lifecycle;
+    if (lifecycle) {
+        const oldest = typeof lifecycle.oldestMs === "number" ? lifecycle.oldestMs : 0;
+        lines.push(`lifecycle: pending ${String(lifecycle.pending ?? 0)}, oldest ${oldest}ms${oldest > LIFECYCLE_STALL_MS ? " (stalled)" : ""}`);
+    }
+    return lines;
+}