@timurproko/a1 0.2.6 → 0.2.7-dev.1222

package/dist/app/session-shell/viewport-layout.js

@@ -0,0 +1,160 @@
+import { heldNativeHyperlinkStyle } from "../../ui/components/spans.js";
+/**
+ * Bare A1's custom viewport: a bounded transcript viewport above the dock, composed by the session
+ * viewport controller. It owns the snapshot that lets a safe keystroke repaint only the dock.
+ */
+export class ViewportLayout {
+    #ports;
+    #snapshot;
+    #fullCompositions = 0;
+    #dockOnlyCompositions = 0;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    invalidate() {
+        this.#snapshot = undefined;
+    }
+    composed() {
+        return this.#snapshot;
+    }
+    compositions() {
+        return { full: this.#fullCompositions, dockOnly: this.#dockOnlyCompositions };
+    }
+    render(width) {
+        const { viewport, input, dockChrome } = this.#ports;
+        const height = Math.max(0, this.#ports.rows());
+        const dock = this.#ports.dock(width);
+        const copyAcknowledgement = dockChrome.renderCopyAcknowledgement(width);
+        // Invariant: auto/always own one stable final-column gutter. Every scrollable
+        // surface ends before it; the dock remains full-width and hidden mode returns it.
+        const documentWidth = viewport.config.scrollbarAppearance === "hidden"
+            ? width
+            : Math.max(1, width - 1);
+        const document = this.#ports.document(documentWidth);
+        const steeringRows = this.#ports.queued(documentWidth);
+        const releaseBanner = dockChrome.renderReleaseBanner(this.#ports.diagnostics(), documentWidth);
+        // Rationale: the release notice rides the bottom-aligned tail directly above Working, so it
+        // never displaces transcript content and scrolls away with the live status.
+        // Invariant: when idle the banner's last row sits on the line Working would occupy.
+        const statusRows = [...releaseBanner?.rows ?? [], ...this.#ports.liveStatus(documentWidth)];
+        const transientSignature = transientRowsSignature(steeringRows, statusRows);
+        const snapshot = this.#snapshot;
+        // Invariant: paint-only feedback may cover either viewport or dock cells, so
+        // ordinary dock-only reuse cannot safely omit its overlay composition.
+        const dockInputCandidate = input.dockInputCandidate && copyAcknowledgement === undefined;
+        // Concurrency: input may change after a keyboard receipt but before its paint.
+        // Capture only the live inputs this composition will actually represent.
+        const inputSurface = input.surface;
+        const dockRows = dock.rows;
+        const dockStartRow = height - dockRows.length + 1;
+        const copyableDockRows = this.#copyableDockRows(dock);
+        this.#placeInputFrames(dock, width, height, dockStartRow);
+        const viewportRevision = viewport.presentationRevision;
+        const selectionRevision = viewport.selectionRevision;
+        const pointerPosition = viewport.pointerPosition;
+        input.takeDockInputCandidate();
+        let frame = dockInputCandidate
+            && snapshot !== undefined
+            && snapshot.width === width
+            && snapshot.height === height
+            && snapshot.documentRows === document.rows
+            && snapshot.transientSignature === transientSignature
+            && snapshot.promptAnchors === document.promptAnchors
+            && snapshot.dockLength === dockRows.length
+            && snapshot.inputSurface === inputSurface
+            && snapshot.viewportRevision === viewportRevision
+            && snapshot.selectionRevision === selectionRevision
+            ? viewport.composeDockOnly(dockRows, width, height, copyableDockRows)
+            : null;
+        if (frame === null) {
+            frame = viewport.compose({
+                // Performance: do not copy the complete document on unchanged dock-only input.
+                // Steering and Working retain their one non-persistent viewport-tail ownership.
+                documentRows: [...document.rows, ...steeringRows, ...statusRows],
+                ...(viewport.transcriptPointerSelecting
+                    ? { paintDocumentRow: heldNativeHyperlinkStyle }
+                    : {}),
+                // Invariant: this boundary tracks persistent transcript rows for streaming and
+                // geometry; transient Steering and Working rows remain complete-frame selectable.
+                selectableDocumentRowCount: document.rows.length,
+                ...(document.liveTailStartRow === undefined ? {} : { liveTailStartRow: document.liveTailStartRow }),
+                bottomAlignedTailRowCount: steeringRows.length + statusRows.length,
+                dockRows,
+                copyableDockRows,
+                promptAnchors: document.promptAnchors,
+                width,
+                height,
+                // Invariant: the control belongs immediately above the complete dock and
+                // floats over transient viewport content rather than consuming a dock row.
+                bottomControlRow: Math.max(0, height - Math.min(height, dockRows.length) - 1),
+                ...(copyAcknowledgement === undefined || height <= 0 ? {} : {
+                    frameOverlay: {
+                        row: Math.max(1, Math.min(height, dockStartRow + dock.inputOffset - 1)),
+                        text: copyAcknowledgement,
+                    },
+                }),
+                theme: this.#ports.theme,
+            });
+            this.#fullCompositions += 1;
+        }
+        else
+            this.#dockOnlyCompositions += 1;
+        dockChrome.locateReleaseClose(frame, releaseBanner, document.rows.length + steeringRows.length + statusRows.length, statusRows.length);
+        this.#snapshot = {
+            width,
+            height,
+            documentRows: document.rows,
+            transientSignature,
+            promptAnchors: document.promptAnchors,
+            dockLength: dockRows.length,
+            inputSurface,
+            // Invariant: a callback during composition cannot bless older rows with its
+            // newer revision. Its ordinary pending render will publish the newer state.
+            viewportRevision,
+            selectionRevision: frame.descriptor.selectionRevision,
+            pointerPosition,
+        };
+        this.#ports.onFrame?.(frame);
+        return frame.rows;
+    }
+    #copyableDockRows(dock) {
+        // Rationale: rendered chip tags are lossy presentation (truncated labels), so a frame drag over
+        // a draft holding chips stays visual-only; editor-owned word/line selection still copies the
+        // expanded chip text through its semantic route.
+        const draft = this.#ports.input.usesEditor ? this.#ports.editor.getText() : "";
+        const promptCopyRows = draft.length > 0
+            && !draft.split("\n").some(line => this.#ports.promptChips.atomicRanges(line).length > 0)
+            ? Math.max(0, dock.inputRows - 2)
+            : 0;
+        return [
+            ...dock.copyableMessageRows,
+            ...Array.from({ length: promptCopyRows }, (_value, index) => ({
+                row: dock.editorOffset + index + 1,
+                prompt: index === 0 ? "first" : "continuation",
+            })),
+            ...Array.from({ length: dock.footerRows }, (_value, index) => ({
+                row: dock.rows.length - dock.footerRows + index,
+            })),
+        ];
+    }
+    // Invariant: pointer routing needs the replacement surface's frame, or the editor's rows when it is active.
+    #placeInputFrames(dock, width, height, dockStartRow) {
+        const { viewport, input } = this.#ports;
+        viewport.setInputSurfaceFrame(input.usesEditor ? undefined : {
+            component: input.surface,
+            columnStart: 1,
+            columnEnd: width,
+            rowStart: Math.max(1, dockStartRow + dock.editorOffset),
+            rowEnd: Math.min(height, dockStartRow + dock.editorOffset + dock.inputRows - 1),
+        });
+        viewport.setEditorPointerFrame(input.usesEditor
+            ? {
+                rowStart: dockStartRow + dock.editorOffset,
+                rowEnd: dockStartRow + dock.editorOffset + dock.inputRows - 1,
+            }
+            : undefined);
+    }
+}
+function transientRowsSignature(steeringRows, statusRows) {
+    return `${steeringRows.length}\u0000${steeringRows.join("\u0000")}\u0001${statusRows.length}\u0000${statusRows.join("\u0000")}`;
+}

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

@@ -0,0 +1,33 @@
+import type { ImageAttachmentError, OwnedUiWorkflowMessage, OwnedUiWorkflowResult } from "../../contracts/owned-ui/index.js";
+import { type PiShellHotkeysPresentation } from "../../integrations/pi/components/shell-presenters-info.js";
+import type { DockChrome } from "./dock-chrome.js";
+import type { TranscriptDocument } from "./transcript-document.js";
+export interface WorkflowOutputPorts {
+    readonly customViewport: boolean;
+    readonly document: Pick<TranscriptDocument, "lastId" | "anchorOf" | "invalidate" | "appendAnchored" | "removeAnchored">;
+    readonly dock: Pick<DockChrome, "setNotice" | "dismissNotice">;
+    /** How many semantic transcript blocks precede new output; workflow output anchors after them. */
+    transcriptLength(): number;
+    outputPad(): 0 | 1;
+    hotkeysPresentation(): PiShellHotkeysPresentation;
+    readonly componentRuntime: {
+        getColumns(): number;
+        getRows(): number;
+        requestRender(): void;
+    };
+    /** Output changed what the shell draws; the root invalidates. */
+    invalidate(): void;
+}
+/**
+ * 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 declare class WorkflowOutput {
+    #private;
+    constructor(ports: WorkflowOutputPorts);
+    appendStatus(message: string): void;
+    appendMessage(message: OwnedUiWorkflowMessage, errorCode?: ImageAttachmentError["code"]): void;
+    appendResult(result: OwnedUiWorkflowResult, errorCode?: ImageAttachmentError["code"]): void;
+    /** Drops every anchored output and the status-replacement chain. */
+    reset(): void;
+}

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>;