@timurproko/a1 0.2.7-dev.767 → 0.2.7-dev.779

package/README.md

@@ -57,6 +57,12 @@ Launch A1 (profile: `~/.a1/agent`):
 a1
 ```
 
+Launch A1 in single agent mode:
+
+```text
+a1 solo
+```
+
 Show all commands:
 
 ```text
@@ -77,6 +83,30 @@ a1 pi
 
 <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
 
+## Tabs
+
+Tabs keep running after their terminal closes. List them, or stop one; its session stays resumable:
+
+```text
+a1 tabs
+a1 tabs stop <id>
+```
+
+Stop every tab and the resident host, for example before going back to single agent mode with `a1 solo`:
+
+```text
+a1 tabs host stop
+```
+
+Show host health, or write a redacted diagnostic bundle:
+
+```text
+a1 tabs host status
+a1 tabs doctor
+```
+
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
+
 ## Update
 
 Install the release:

package/bin/cli.js

@@ -69,6 +69,10 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
       },
     });
   },
+  tabs: async request => {
+    const { runTabsCommand } = await import("../dist/cli/tabs.js");
+    return await runTabsCommand(request, { packageRoot: fileURLToPath(packageRoot) });
+  },
 }, {
   stdout: message => process.stdout.write(message),
   stderr: message => process.stderr.write(message),

package/bin/tab-launch-context.d.ts

@@ -12,6 +12,8 @@ export function assignFreshSessionRuntimeId(
   createId: () => string,
 ): string;
 
+export function waitForStandbyPromotion(input: NodeJS.ReadStream, promotionFile?: string): Promise<void>;
+
 export function consumeTabLaunchContext(
   arguments_: readonly string[],
   environment: Record<string, string | undefined>,
@@ -20,4 +22,5 @@ export function consumeTabLaunchContext(
   readonly tabCredentials: TabLaunchCredentials | undefined;
   readonly tabDataDir?: string;
   readonly tabIncarnation?: number;
+  readonly tabStandby: boolean;
 };

package/bin/tab-launch-context.js

@@ -1,8 +1,14 @@
+import { existsSync } from "node:fs";
+
 const TAB_ENVIRONMENT_NAMES = ["A1_TAB_ID", "A1_TAB_TOKEN", "A1_TAB_ENDPOINT"];
 
 /** @param {string} reason */
 export function formatResidentFallbackNotice(reason) {
-  return `Resident tabs unavailable (${reason}); running a single agent.`;
+  // Protocol: a host of another generation is never replaced automatically; only the user stops it.
+  if (reason === "incompatible generation") {
+    return "A1 normal mode unavailable (running tabs use another version); running in single agent mode. Run `a1 tabs host stop` to restart them on this version.";
+  }
+  return `A1 normal mode unavailable (${reason}); running in single agent mode.`;
 }
 
 /**
@@ -17,6 +23,46 @@ export function assignFreshSessionRuntimeId(environment, name, createId) {
   return id;
 }
 
+/**
+ * Keep the standby below the session/runtime boundary until its authenticated holder promotes it.
+ * Platform: Windows ConPTY may drop the in-band marker, so the holder also creates the promotion
+ * file inside the tab's private data directory; whichever arrives first promotes the standby.
+ * @param {NodeJS.ReadStream} input
+ * @param {string} [promotionFile]
+ */
+export function waitForStandbyPromotion(input, promotionFile) {
+  return /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+    const marker = Buffer.from("\x1b]a1;standby-promote\x07");
+    let buffered = Buffer.alloc(0);
+    /** @type {NodeJS.Timeout | undefined} */
+    let poll;
+    const cleanup = () => {
+      if (poll !== undefined) clearInterval(poll);
+      input.off("data", onData);
+      input.off("error", onError);
+      input.pause();
+      if (input.isTTY) input.setRawMode(false);
+    };
+    /** @param {Error} error */
+    const onError = error => { cleanup(); reject(error); };
+    /** @param {Buffer | string} chunk */
+    const onData = chunk => {
+      const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+      buffered = Buffer.concat([buffered, bytes]).subarray(-marker.length);
+      if (buffered.equals(marker)) { cleanup(); resolve(undefined); }
+    };
+    if (input.isTTY) input.setRawMode(true);
+    input.on("data", onData);
+    input.on("error", onError);
+    input.resume();
+    if (promotionFile !== undefined) {
+      poll = setInterval(() => {
+        if (existsSync(promotionFile)) { cleanup(); resolve(undefined); }
+      }, 10);
+    }
+  }));
+}
+
 /**
  * Security: consume bridge credentials into caller-private memory and erase their inheritable
  * environment entries before any extension-capable module loads.
@@ -28,6 +74,9 @@ export function consumeTabLaunchContext(arguments_, environment) {
   const tabArgument = uiArguments.indexOf("--tab");
   const tabMode = tabArgument !== -1;
   if (tabMode) uiArguments.splice(tabArgument, 1);
+  const standbyArgument = uiArguments.indexOf("--tab-standby");
+  const tabStandby = standbyArgument !== -1;
+  if (tabStandby) uiArguments.splice(standbyArgument, 1);
   const dataArgument = uiArguments.indexOf("--tab-data-dir");
   const tabDataDir = dataArgument === -1 ? undefined : uiArguments[dataArgument + 1];
   if (dataArgument !== -1) uiArguments.splice(dataArgument, 2);
@@ -36,10 +85,10 @@ export function consumeTabLaunchContext(arguments_, environment) {
   if (incarnationArgument !== -1) uiArguments.splice(incarnationArgument, 2);
   const [tabId, token, endpoint] = TAB_ENVIRONMENT_NAMES.map(name => environment[name]);
   for (const name of TAB_ENVIRONMENT_NAMES) delete environment[name];
-  if (!tabMode) return { uiArguments, tabCredentials: undefined };
+  if (!tabMode) return { uiArguments, tabCredentials: undefined, tabStandby: false };
   if (!tabId || !token || !endpoint || !tabDataDir || tabDataDir.includes("\0")
     || typeof tabIncarnation !== "number" || !Number.isSafeInteger(tabIncarnation) || tabIncarnation < 1) {
     throw new Error("A1 tab mode requires bridge credentials, recovery directory, and incarnation");
   }
-  return { uiArguments, tabCredentials: { tabId, token, endpoint }, tabDataDir, tabIncarnation };
+  return { uiArguments, tabCredentials: { tabId, token, endpoint }, tabDataDir, tabIncarnation, tabStandby };
 }

package/bin/ui.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 
 // Security: this helper has no A1, Pi, tool, or extension dependency and erases credentials before those modules load.
-const { assignFreshSessionRuntimeId, consumeTabLaunchContext, formatResidentFallbackNotice } = await import("./tab-launch-context.js");
-const { uiArguments, tabCredentials, tabDataDir, tabIncarnation } = consumeTabLaunchContext(process.argv.slice(2), process.env);
+const { assignFreshSessionRuntimeId, consumeTabLaunchContext, formatResidentFallbackNotice, waitForStandbyPromotion } = await import("./tab-launch-context.js");
+const { uiArguments, tabCredentials, tabDataDir, tabIncarnation, tabStandby } = consumeTabLaunchContext(process.argv.slice(2), process.env);
 
 // Invariant: one terminal module identity per process, decided before any A1 or Pi module loads.
 const { installPinnedPiTuiResolver } = await import("./module-resolver.js");
 installPinnedPiTuiResolver(new URL("..", import.meta.url).pathname.replace(/^\/(.:)/, "$1").replace(/\/$/, ""));
 const startup = await import("../dist/foundation/startup/startup-runtime.js");
 startup.enableEnvironmentCompileCache(process.env);
-const { readLaunchContext } = await import("../dist/foundation/launch-context/index.js");
+const { hidesTabSettings, readLaunchContext } = await import("../dist/foundation/launch-context/index.js");
 const launchContext = readLaunchContext(process.env, "profile");
 const profile = launchContext.launchProfile;
 if (profile === undefined) throw new Error("A1 launch profile is missing");
@@ -52,6 +52,8 @@ const [
   { composeOwnedUi },
 ] = await modules;
 
+if (tabStandby) await waitForStandbyPromotion(process.stdin, tabDataDir === undefined ? undefined : join(tabDataDir, "standby-promote"));
+
 // Compatibility: before the composition uses pinned Pi's terminal stack: confirm A1 and Pi
 // resolve it to the same copy, so extensions and the owned UI share one module identity.
 identity.assertSinglePiTuiModuleAtLaunch(packageRootPath, (/** @type {string} */ message) => process.stderr.write(message));
@@ -76,6 +78,7 @@ Promise.resolve().then(async () => {
         cwd: process.cwd(),
         profileId,
         ownedSurfaces,
+        ...(hidesTabSettings(launchContext) ? { hideTabSettings: true } : {}),
         ...(processInspector === null ? {} : { inspectProcess: pid => processInspector.observe(pid) }),
         projectTrustPrompt: createConsoleProjectTrustPrompt({ presentation: profile === "a1" ? "bare" : "comparison" }),
         sessionForkPrompt: createConsoleSessionForkPrompt(),

package/dist/app/session-shell/session-shell-root.d.ts

@@ -46,7 +46,6 @@ export interface OwnedUiShellEngineOptions {
     /** Resident tab quit routes detach the outer client without stopping this engine session. */
     readonly residentTab?: {
         requestDetach(): Promise<boolean>;
-        requestRestart?(): Promise<boolean>;
         reportStatus?(status: "working" | "idle" | "stalled"): void;
         readonly stallNoticeSeconds?: number;
         admit?(input: {
@@ -218,6 +217,8 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly keybindings?: PiKeybindingsHost;
         readonly promptImageLimit?: () => number;
         readonly skillsPresentation?: () => "collapse" | "expand";
+        /** A resident tab chip already shows the session name, so its footer omits the duplicate. */
+        readonly footerSessionName?: boolean;
     }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: OwnedUiTranscriptRendererPort, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
     setEditorPaddingX(padding: number): void;
     setAutocompleteMaxVisible(maxVisible: number): void;

package/dist/app/session-shell/session-shell-root.js

@@ -119,7 +119,7 @@ export class OwnedUiSessionShellRoot {
             frame: progressStatusFrame,
         }, handlers);
         this.#status.setProgressPresentation(this.#customViewport ? "custom-viewport" : "pinned");
-        this.#footer = createPiShellFooter(this.#viewWithExtensionStatuses(view), cwd, this.#customViewport ? "a1" : "pi", () => this.#footerLevel);
+        this.#footer = createPiShellFooter(this.#viewWithExtensionStatuses(view), cwd, this.#customViewport ? "a1" : "pi", () => this.#footerLevel, handlers.footerSessionName ?? true);
         this.editor = createPiShellEditor({
             ...handlers,
             keybindingProfile: this.#customViewport ? "a1" : "pi",
@@ -916,7 +916,7 @@ export class OwnedUiSessionShellRoot {
         if (result.command === "hotkeys" && result.outcome === "completed") {
             this.#lastWorkflowStatusId = undefined;
             const presentation = this.hotkeysPresentation();
-            const hotkeys = createPiShellHotkeys(presentation.bindings, presentation.getShortcuts, presentation.profile);
+            const hotkeys = createPiShellHotkeys(presentation.bindings, presentation.getShortcuts, presentation.profile, presentation.residentTabs);
             this.#appendAnchoredWorkflowComponent(width => hotkeys.render(width), () => hotkeys.dispose?.());
             return;
         }

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

@@ -188,6 +188,7 @@ export class OwnedUiSessionPresenter {
                     replacementSurfaceActive: !this.root.usesDefaultInputSurface(),
                 }),
                 enableDockInputReuse: inputPresentation?.viewportReuse !== false,
+                footerSessionName: this.#residentTabOptions === undefined,
                 persistentHistory: this.#customViewport && promptHistory !== undefined,
                 ...(promptHistory === undefined ? {} : { historyEditor: promptHistory.editor }),
                 onSubmit: text => { void this.submit(text).catch(() => this.#reportSubmissionError()); },
@@ -1276,7 +1277,7 @@ export class OwnedUiSessionPresenter {
             this.#residentStalled = true;
             resident.reportStatus?.("stalled");
             const minutes = Math.max(1, Math.round(seconds / 60));
-            this.root.appendWorkflowStatus(`No progress for ${minutes} min — Esc interrupts · /restart-tab restarts`);
+            this.root.appendWorkflowStatus(`No progress for ${minutes} min — Esc interrupts · use the tab restart action to restart`);
             this.#terminal.requestRender();
         }, seconds * 1_000);
         this.#residentProgressTimer.unref?.();
@@ -1759,7 +1760,8 @@ export class OwnedUiSessionPresenter {
         this.#dialogId = dialog.id;
     }
     hotkeysPresentation() {
-        return this.root.hotkeysPresentation();
+        const presentation = this.root.hotkeysPresentation();
+        return this.#residentTabOptions === undefined ? presentation : { ...presentation, residentTabs: true };
     }
     async #slashCommand(text) {
         const body = text.slice(1).trim();
@@ -1768,12 +1770,6 @@ export class OwnedUiSessionPresenter {
         const argument = separator < 0 ? "" : body.slice(separator + 1).trimStart();
         if (this.#routeHost?.claims(name))
             return this.#openOwnedRoute(name);
-        if (name === "restart-tab" && this.#residentTabOptions?.requestRestart !== undefined) {
-            const accepted = await this.#residentTabOptions.requestRestart().catch(() => false);
-            this.root.appendWorkflowStatus(accepted ? "Restarting resident tab…" : "Resident tab restart is unavailable.");
-            this.#terminal.requestRender();
-            return accepted ? { outcome: "completed", diagnostic: null } : rejected("resident tab restart is unavailable");
-        }
         if (this.#isWorkflowRoute(name))
             return this.runWorkflow({ command: name, argument });
         if (this.#skillsCollapsed()) {

package/dist/app/session-shell/shell-host.d.ts

@@ -98,6 +98,8 @@ export declare class OwnedUiTerminalHost implements OwnedUiTerminalHostContract<
     active(): OwnedUiHostedPresenter | null;
     requestRender(from: OwnedUiHostedPresenter, force?: boolean): void;
     start(): void;
+    /** Hidden resident tabs retain engine/status work but stop producing terminal animation frames. */
+    setPresentationVisible(visible: boolean): void;
     /** Closes one presenter. Closing the last one ends the terminal. */
     close(presenter: OwnedUiHostedPresenter): Promise<void>;
     dispose(): Promise<void>;

package/dist/app/session-shell/shell-host.js

@@ -42,6 +42,8 @@ export class OwnedUiTerminalHost {
     #focused = false;
     #pointerReporting = false;
     #started = false;
+    #presentationVisible = true;
+    #releaseVisibilityHold;
     #ending;
     constructor(options) {
         this.#customViewport = options.layout === "custom-viewport";
@@ -147,7 +149,7 @@ export class OwnedUiTerminalHost {
         return this.#active;
     }
     requestRender(from, force = false) {
-        if (from === this.#active)
+        if (this.#presentationVisible && from === this.#active)
             this.runtime.requestRender(force);
     }
     start() {
@@ -155,9 +157,26 @@ export class OwnedUiTerminalHost {
             return;
         this.#started = true;
         this.runtime.start();
+        if (!this.#presentationVisible)
+            this.#releaseVisibilityHold = this.runtime.beginPresentationHold();
         if (this.#customViewport)
             this.#setPointerReporting(true);
     }
+    /** Hidden resident tabs retain engine/status work but stop producing terminal animation frames. */
+    setPresentationVisible(visible) {
+        if (this.#presentationVisible === visible)
+            return;
+        this.#presentationVisible = visible;
+        if (!this.#started || this.#ending !== undefined)
+            return;
+        if (visible) {
+            this.#releaseVisibilityHold?.();
+            this.#releaseVisibilityHold = undefined;
+        }
+        else if (this.#releaseVisibilityHold === undefined) {
+            this.#releaseVisibilityHold = this.runtime.beginPresentationHold();
+        }
+    }
     /** Closes one presenter. Closing the last one ends the terminal. */
     close(presenter) {
         if (this.#ending !== undefined || !this.#presenters.has(presenter))

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 running package root; its terminal host is a candidate after the active 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>;