@zergai/ztc 0.5.0-beta.1 → 0.6.0-beta.1

package/dist/onboarding/first_run.d.ts

@@ -1,5 +1,5 @@
 import type { GitWorkingTreeStatus } from '../runtime_info.js';
-import { type TaskHandoffSnapshot } from '../session_handoff_contract.js';
+import type { RouterSessionStatus } from '../router_auth.js';
 export declare const FIRST_RUN_MESSAGE_METADATA: {
     readonly ephemeral: true;
     readonly onboarding: "first-run";
@@ -18,7 +18,13 @@ export interface FirstRunMessageLike {
 export interface FirstRunLaunchMessage {
     role: 'system';
     content: string;
-    metadata: typeof FIRST_RUN_MESSAGE_METADATA;
+    metadata: typeof FIRST_RUN_MESSAGE_METADATA & {
+        /**
+         * The welcome a launch opens on: the transcript draws the ZTC wordmark
+         * beside it and no message header, as the site's First Contact film shows it.
+         */
+        wordmark?: true;
+    };
 }
 export interface FirstRunWelcomeOptions {
     provider?: string;
@@ -34,6 +40,8 @@ export interface FirstRunWelcomeOptions {
     sessionName?: string;
     mode?: string;
     recentSession?: RecentSessionInfo;
+    /** Zerg Router login state; a ready launch without a login carries one tip. */
+    routerSession?: RouterSessionStatus;
     now?: Date;
     /** @deprecated The application header owns launch branding. */
     logo?: string;
@@ -65,13 +73,25 @@ export declare const FIRST_RUN_WORKFLOWS: readonly [{
 export declare function formatFirstRunWorkflows(): string;
 export declare function isFirstRunWelcomeMessage(message: FirstRunMessageLike | undefined): boolean;
 /** Build the display-only launch card envelope shared by both renderers. */
-export declare function createFirstRunLaunchMessage(content: string): FirstRunLaunchMessage;
+export declare function createFirstRunLaunchMessage(content: string, { wordmark }?: {
+    wordmark?: boolean;
+}): FirstRunLaunchMessage;
 export declare function excludePrintedFirstRunWelcome<T extends FirstRunMessageLike>(messages: readonly T[], printedIds: ReadonlySet<string>): T[];
 export declare function shouldDeferFirstRunScrollback(message: FirstRunMessageLike, messageCount: number): boolean;
 export declare function buildCredentialSetupMessage(): string;
-/** Keep the paste target separate from the historical checkpoint details. */
-export declare function buildSavedSessionNotice(snapshot: TaskHandoffSnapshot, profile: string): string;
-export declare function buildNoCredentialsWelcome(options?: Pick<FirstRunWelcomeOptions, 'mode'>): string;
+export interface NoCredentialsWelcomeOptions extends Pick<FirstRunWelcomeOptions, 'mode' | 'routerSession' | 'location' | 'branch' | 'gitStatus' | 'dirtyFileCount' | 'version'> {
+    /**
+     * The launch prompt opens right under this welcome and offers both ways to
+     * connect, so the welcome is the short readout alone.
+     */
+    promptFollows?: boolean;
+}
+/**
+ * A launch without a model: the readout the site's First Contact film shows
+ * (the title, the project, no runtime yet), then how to connect unless the
+ * launch prompt under it already asks. The workflows live in /help.
+ */
+export declare function buildNoCredentialsWelcome(options?: NoCredentialsWelcomeOptions): string;
 export declare function buildReadyWelcome(options?: FirstRunWelcomeOptions): string;
 export declare function buildResumedWelcome(options: ResumedWelcomeOptions): string;
 export declare function buildHelpIntroduction(): string;

package/dist/onboarding/first_run.js

@@ -1,5 +1,6 @@
 import { displayWidth, sanitizeTerminalText } from '../ui/core/text_width.js';
-import { formatTaskHandoffContext, projectTaskHandoff } from '../session_handoff_contract.js';
+import { routerLaunchTip } from './router_tips.js';
+import { LOCAL_API_KEYS_LABEL, ZERGAI_LOGIN_LABEL, ZERGAI_LOGIN_PITCH } from './zergai_login.js';
 const WELCOME_TITLE = 'Welcome to ZTC - Zerg Terminal Client.';
 const FIRST_RUN_MESSAGE_KIND = 'first-run';
 const READOUT_CONTENT_WIDTH = 76;
@@ -142,18 +143,21 @@ function formatIdentityLine(options) {
     const workspaceName = compact(options.workspaceName, 24);
     return `Identity: ${authEmail}${workspaceName ? ` · ${workspaceName}` : ''}`;
 }
-function formatRecentSession(session, now) {
+/**
+ * The readout's one pointer to saved work in this project. With `resume`, it
+ * ends on /resume, and a long title gives way so the command stays whole.
+ */
+function formatRecentSession(session, now, { resume }) {
     if (!session)
         return undefined;
-    const label = compact(singleLine(session.name) || singleLine(session.title) || session.id, 32);
-    if (!label)
-        return undefined;
     const count = normalizedCount(session.messageCount) ?? 0;
     const relativeTime = formatRelativeTime(session.updatedAt, now);
-    return {
-        line: `Recent: "${label}" · ${pluralizedCount(count, 'message')}${relativeTime ? ` · ${relativeTime}` : ''}`,
-        label,
-    };
+    const suffix = `" · ${pluralizedCount(count, 'message')}${relativeTime ? ` · ${relativeTime}` : ''}${resume ? ' · /resume' : ''}`;
+    const room = READOUT_CONTENT_WIDTH - displayWidth('Recent: "') - displayWidth(suffix);
+    const label = compact(singleLine(session.name) || singleLine(session.title) || session.id, Math.min(32, room));
+    if (!label)
+        return undefined;
+    return `Recent: "${label}${suffix}`;
 }
 function formatContextPercentage(value) {
     if (value === undefined || !Number.isFinite(value) || value < 0)
@@ -177,8 +181,9 @@ function formatReadyNextAction(options, recent) {
             ? `Next: Review ${pluralizedCount(dirtyFileCount, 'changed file')} before starting.`
             : 'Next: Review working tree changes before starting.';
     }
+    // The Recent line already ends on /resume.
     if (recent)
-        return `Next: Resume "${recent.label}" from /sessions.`;
+        return undefined;
     return 'Next: Start with /plan "Map this project."';
 }
 export function formatFirstRunWorkflows() {
@@ -195,11 +200,11 @@ export function isFirstRunWelcomeMessage(message) {
         && message.metadata.onboarding === FIRST_RUN_MESSAGE_KIND;
 }
 /** Build the display-only launch card envelope shared by both renderers. */
-export function createFirstRunLaunchMessage(content) {
+export function createFirstRunLaunchMessage(content, { wordmark = false } = {}) {
     return {
         role: 'system',
         content,
-        metadata: { ...FIRST_RUN_MESSAGE_METADATA },
+        metadata: { ...FIRST_RUN_MESSAGE_METADATA, ...(wordmark ? { wordmark: true } : {}) },
     };
 }
 export function excludePrintedFirstRunWelcome(messages, printedIds) {
@@ -213,48 +218,59 @@ export function excludePrintedFirstRunWelcome(messages, printedIds) {
 export function shouldDeferFirstRunScrollback(message, messageCount) {
     return messageCount === 1 && isFirstRunWelcomeMessage(message);
 }
+const CONNECT_ACTION = 'Connect a model: /connect';
+const SETUP_ACTION = 'Check tools and create a sample project: /setup';
+/** The two ways to reach a model, ZergAI first. */
+const CONNECTION_ROUTES = [
+    `  1. ${ZERGAI_LOGIN_LABEL}: /auth login`,
+    `     ${ZERGAI_LOGIN_PITCH} · /auth readiness · /auth billing`,
+    `  2. ${LOCAL_API_KEYS_LABEL}: /config key <provider>`,
+    '     Local Claude Code, Codex or Kimi Code login: /connect direct',
+];
 export function buildCredentialSetupMessage() {
     return [
         '⚠️  No API credentials configured.',
-        'Set up ZTC: /setup',
-        '  1. Zerg account: /auth login',
-        '     Complete signup/email verification; then /auth readiness.',
-        '     Fund personal pay-as-you-go with /auth billing; review pricing and caps.',
-        '  2. Claude Code: run `claude setup-token`, export CLAUDE_CODE_OAUTH_TOKEN, then /config provider claude_code',
-        '  3. Provider API key: /config key <api-key>',
-        'You can also set the provider-specific API key environment variable.',
+        CONNECT_ACTION,
+        ...CONNECTION_ROUTES,
+        "     A provider's API key environment variable also works.",
+        SETUP_ACTION,
     ].join('\n');
 }
-/** Keep the paste target separate from the historical checkpoint details. */
-export function buildSavedSessionNotice(snapshot, profile) {
-    const handoff = projectTaskHandoff(snapshot);
-    const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
-    const command = `${handoff.resumeCommand} --cwd ${quote(handoff.snapshot.source.cwd)} --profile ${quote(profile)}`;
-    return [
-        'Saved project work is available.',
-        'Paste into your terminal to resume:',
-        command,
-        '',
-        formatTaskHandoffContext(handoff.snapshot),
-    ].join('\n');
+/** The readout line for an expired ZergAI session; other states add none here. */
+function expiredSessionNote(session) {
+    return session === 'expired' ? [routerLaunchTip(session)] : [];
 }
+/**
+ * A launch without a model: the readout the site's First Contact film shows
+ * (the title, the project, no runtime yet), then how to connect unless the
+ * launch prompt under it already asks. The workflows live in /help.
+ */
 export function buildNoCredentialsWelcome(options = {}) {
-    const credentials = [
-        '⚠️  No credentials yet. Set up ZTC: /setup',
-        '  1. Zerg account: /auth login (finish email verification in the browser)',
-        '     Funding: /auth readiness · Pay-as-you-go and caps: /auth billing',
-        '  2. Claude Code: claude setup-token, then /config provider claude_code',
-        '  3. Provider key: /config key <api-key>',
-    ].join('\n');
-    return [WELCOME_TITLE, credentials, isPlanMode(options.mode)
-            ? 'Plan mode is active. Authenticate, then describe what to inspect.'
-            : formatFirstRunWorkflows(), ...(isPlanMode(options.mode) ? [] : ['Use /help for every command.'])].join('\n\n');
+    // With no model to name, the runtime line has room for a pre-release version whole.
+    const version = compact(options.version, 24);
+    const readout = [
+        WELCOME_TITLE,
+        formatProjectLine(options),
+        `Runtime: not configured${version ? ` · ZTC v${version}` : ''}`,
+        ...expiredSessionNote(options.routerSession),
+    ].map(fitReadoutLine).join('\n');
+    const planMode = isPlanMode(options.mode);
+    if (options.promptFollows) {
+        return planMode ? [readout, 'Plan mode is active. Connect a model, then describe what to inspect.'].join('\n\n') : readout;
+    }
+    return [
+        readout,
+        [CONNECT_ACTION, ...CONNECTION_ROUTES].join('\n'),
+        // Setup installs tools, which Plan mode refuses; Plan launch offers only connecting.
+        planMode ? 'Plan mode is active. Authenticate, then describe what to inspect.' : '/setup checks your tools · /help lists every command',
+    ].join('\n\n');
 }
 export function buildReadyWelcome(options = {}) {
     const permissionProfile = compact(options.permissionProfile, 20) || 'trusted';
     const planMode = isPlanMode(options.mode);
     const sessionName = compact(options.sessionName, 30);
-    const recent = formatRecentSession(options.recentSession, options.now);
+    // Plan mode refuses /resume, so its Recent line offers no command.
+    const recent = formatRecentSession(options.recentSession, options.now, { resume: !planMode });
     const next = formatReadyNextAction(options, recent);
     const details = [
         formatProjectLine(options),
@@ -264,7 +280,8 @@ export function buildReadyWelcome(options = {}) {
             : `Safety: ${permissionProfile} permissions · /permissions`,
         formatRuntimeLine(options),
         formatIdentityLine(options),
-        recent?.line,
+        recent,
+        options.routerSession ? routerLaunchTip(options.routerSession) : undefined,
         next,
     ].filter((line) => Boolean(line));
     return [
@@ -296,10 +313,11 @@ export function buildResumedWelcome(options) {
         planMode && context ? `Context: ${context}` : undefined,
         formatRuntimeLine(options),
         formatIdentityLine(options),
-        credentialsReady ? undefined : 'Set up ZTC: /setup',
+        ...expiredSessionNote(options.routerSession),
+        credentialsReady ? undefined : CONNECT_ACTION,
         credentialsReady
             ? undefined
-            : 'Authentication: required · /auth login or /config key <api-key>',
+            : 'Authentication: required · /auth login or /config key <provider>',
         planMode && credentialsReady
             ? 'Next: Continue the plan and review it before execution.'
             : credentialsReady

package/dist/onboarding/router_tips.d.ts

@@ -0,0 +1,7 @@
+import type { RouterSessionStatus } from '../router_auth.js';
+/** A login tip to show after this many completed turns, or none. */
+export declare function routerLoginTip(session: RouterSessionStatus, completedTurns: number): string | undefined;
+/** A tip for a failed direct-key turn: Router-billed DeepSeek works without that key. */
+export declare function routerTipForError(session: RouterSessionStatus, routed: boolean, error: string): string | undefined;
+/** The launch card's ZergAI line for a session that can already reach a model. */
+export declare function routerLaunchTip(session: RouterSessionStatus): string | undefined;

package/dist/onboarding/router_tips.js

@@ -0,0 +1,38 @@
+import { ZERGAI_LOGIN_BENEFIT, ZERGAI_LOGIN_PITCH } from './zergai_login.js';
+/** Tips for people working without a ZergAI login; signed-in users never see one. */
+const ROUTER_LOGIN_TIPS = [
+    `Tip: ${ZERGAI_LOGIN_BENEFIT.providerKeys}. Log in with ZergAI: /auth login`,
+    `Tip: ${ZERGAI_LOGIN_BENEFIT.deepSeek}. Log in with ZergAI: /auth login`,
+    `Tip: ${ZERGAI_LOGIN_BENEFIT.usage}. Log in with ZergAI: /auth login · /auth billing`,
+];
+/** The first tip follows this completed turn; later tips follow every interval after it. */
+const FIRST_TIP_TURN = 3;
+const TIP_INTERVAL_TURNS = 20;
+/** A login tip to show after this many completed turns, or none. */
+export function routerLoginTip(session, completedTurns) {
+    const sinceFirst = completedTurns - FIRST_TIP_TURN;
+    if (sinceFirst < 0 || sinceFirst % TIP_INTERVAL_TURNS !== 0)
+        return undefined;
+    switch (session) {
+        case 'signed_in': return undefined;
+        case 'expired': return 'Tip: Your ZergAI session expired. Run /auth login to log in again.';
+        case 'signed_out': return ROUTER_LOGIN_TIPS[(sinceFirst / TIP_INTERVAL_TURNS) % ROUTER_LOGIN_TIPS.length];
+    }
+}
+/** A tip for a failed direct-key turn: Router-billed DeepSeek works without that key. */
+export function routerTipForError(session, routed, error) {
+    if (session === 'signed_in' || routed)
+        return undefined;
+    return /^Authentication failed\.|Rate limit exceeded/.test(error)
+        ? `Tip: ${ZERGAI_LOGIN_BENEFIT.deepSeek}. Log in with ZergAI: /auth login`
+        : undefined;
+}
+/** The launch card's ZergAI line for a session that can already reach a model. */
+export function routerLaunchTip(session) {
+    switch (session) {
+        case 'signed_in': return undefined;
+        case 'expired': return 'ZergAI session expired · /auth login';
+        // Fits the 76-column launch readout, like the login tips it matches.
+        case 'signed_out': return `Tip: ${ZERGAI_LOGIN_PITCH}. Log in with ZergAI: /auth login`;
+    }
+}

package/dist/onboarding/setup.js

@@ -125,7 +125,7 @@ export function formatSetupReport(report) {
         lines.push(`Sample: ${safeLine(report.workspace.path)}`, `Sample session: ${report.workspace.sessionId}`, `Open the sample: /cd ${safeLine(report.workspace.path)}; then /resume ${report.workspace.sessionId}`);
     }
     if (report.status === 'needs_auth')
-        lines.push('Next: /auth login for Zerg Router, or /accounts and /config for your existing provider. Then run /setup.');
+        lines.push('Next: /connect to log in with ZergAI or use your local API keys. Directly: /auth login, or /config key <provider>. Then run /setup.');
     if (!report.agent && report.status === 'ready')
         lines.push('Next: /auth login, then /auth readiness to check personal funding. Review pay-as-you-go pricing and caps with /auth billing. Optional /setup --check-agent sends one bounded model request after confirmation.');
     lines.push('Your current project, conversation, shell configuration and PATH are preserved.');

package/dist/onboarding/wordmark.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The ZTC wordmark in the ANSI Shadow face, as the launch welcome prints it.
+ * The site's First Contact film draws these same cells as shapes
+ * (zergai/web/src/components/marketing/ztc-hero/ztcBanner.ts), its blocks in
+ * the accent and its shadow in teal.
+ */
+export declare const ZTC_WORDMARK: readonly ["███████╗████████╗ ██████╗", "╚══███╔╝╚══██╔══╝██╔════╝", "  ███╔╝    ██║   ██║     ", " ███╔╝     ██║   ██║     ", "███████╗   ██║   ╚██████╗", "╚══════╝   ╚═╝    ╚═════╝"];

package/dist/onboarding/wordmark.js

@@ -0,0 +1,14 @@
+/**
+ * The ZTC wordmark in the ANSI Shadow face, as the launch welcome prints it.
+ * The site's First Contact film draws these same cells as shapes
+ * (zergai/web/src/components/marketing/ztc-hero/ztcBanner.ts), its blocks in
+ * the accent and its shadow in teal.
+ */
+export const ZTC_WORDMARK = [
+    '███████╗████████╗ ██████╗',
+    '╚══███╔╝╚══██╔══╝██╔════╝',
+    '  ███╔╝    ██║   ██║     ',
+    ' ███╔╝     ██║   ██║     ',
+    '███████╗   ██║   ╚██████╗',
+    '╚══════╝   ╚═╝    ╚═════╝',
+];

package/dist/onboarding/zergai_login.d.ts

@@ -0,0 +1,48 @@
+import type { ZTCAuthMode, ZTCConfig } from '../config/types.js';
+import type { RouterSessionStatus } from '../router_auth.js';
+/**
+ * What a ZergAI login offers over local API keys. One owner for the copy that
+ * /connect, the launch prompt, first-run text, /model and Router tips share.
+ *
+ * Each claim is one Zerg Router guarantees (zapps/zergrouter README,
+ * pages/faq.vue, pages/index.vue and server/lib): Router keeps each
+ * provider's credential, so no key sits on this machine; DeepSeek is the one
+ * platform-funded route, on the account's pay-as-you-go billing or trial;
+ * Router logs usage, enforces per-key daily budgets, and caps Router billing
+ * monthly. Other providers need a key added in Router: Router does not fund
+ * them. Terminal and desktop ZTC read the same profile, so one login serves
+ * both. The CLI spells the product "Zerg Router", except in /model, its
+ * menu and its prompts: there it is "ZergRouter", one word like the
+ * `/model zergrouter` route, so nobody types a space.
+ */
+/** The two ways to reach a model, as /connect and the first-run text name them. */
+export declare const ZERGAI_LOGIN_LABEL = "Log in with ZergAI (recommended)";
+export declare const LOCAL_API_KEYS_LABEL = "Use your local API keys";
+/** The short pitch next to the ZergAI choice. */
+export declare const ZERGAI_LOGIN_PITCH = "Keys, budgets and usage in one place";
+/** Why /model and its menu show no ZergRouter choices before a login. */
+export declare const ROUTER_MODELS_NEED_LOGIN = "ZergRouter models appear after you log in";
+/** Each benefit by name, for surfaces that quote one (Router tips). */
+export declare const ZERGAI_LOGIN_BENEFIT: {
+    readonly oneLogin: "One ZergAI login for ZTC in the terminal and the desktop app";
+    readonly providerKeys: "Add provider keys once in Zerg Router, not on this machine";
+    readonly deepSeek: "DeepSeek ready on Zerg Router billing, no DeepSeek key needed";
+    readonly usage: "Usage history, per-key daily budgets and a monthly cap on Router billing";
+    readonly switchModels: "Switch models any time with /model";
+};
+/** The benefits listed while the ZergAI choice is highlighted or hovered. */
+export declare const ZERGAI_LOGIN_BENEFITS: readonly ["One ZergAI login for ZTC in the terminal and the desktop app", "Add provider keys once in Zerg Router, not on this machine", "DeepSeek ready on Zerg Router billing, no DeepSeek key needed", "Usage history, per-key daily budgets and a monthly cap on Router billing", "Switch models any time with /model"];
+/**
+ * True once the user chose local API keys: in /connect, or by saving the
+ * direct route (for example with /model direct). Launch does not ask them again.
+ */
+export declare function choseLocalApiKeys(config: Pick<ZTCConfig, 'onboarding'>, authMode: ZTCAuthMode): boolean;
+/**
+ * Whether launch asks how to connect. Without a ZergAI login, every launch
+ * asks unless local keys were chosen and still reach a model
+ * (`modelReachable`). An expired ZergAI login is asked again unless local
+ * keys were chosen in /connect since; a ZergAI login records its own choice,
+ * so a later expiry is never silent. The launch readout names an expired
+ * session either way.
+ */
+export declare function askHowToConnectAtLaunch(config: Pick<ZTCConfig, 'onboarding'>, authMode: ZTCAuthMode, session: RouterSessionStatus, modelReachable: boolean): boolean;

package/dist/onboarding/zergai_login.js

@@ -0,0 +1,60 @@
+/**
+ * What a ZergAI login offers over local API keys. One owner for the copy that
+ * /connect, the launch prompt, first-run text, /model and Router tips share.
+ *
+ * Each claim is one Zerg Router guarantees (zapps/zergrouter README,
+ * pages/faq.vue, pages/index.vue and server/lib): Router keeps each
+ * provider's credential, so no key sits on this machine; DeepSeek is the one
+ * platform-funded route, on the account's pay-as-you-go billing or trial;
+ * Router logs usage, enforces per-key daily budgets, and caps Router billing
+ * monthly. Other providers need a key added in Router: Router does not fund
+ * them. Terminal and desktop ZTC read the same profile, so one login serves
+ * both. The CLI spells the product "Zerg Router", except in /model, its
+ * menu and its prompts: there it is "ZergRouter", one word like the
+ * `/model zergrouter` route, so nobody types a space.
+ */
+/** The two ways to reach a model, as /connect and the first-run text name them. */
+export const ZERGAI_LOGIN_LABEL = 'Log in with ZergAI (recommended)';
+export const LOCAL_API_KEYS_LABEL = 'Use your local API keys';
+/** The short pitch next to the ZergAI choice. */
+export const ZERGAI_LOGIN_PITCH = 'Keys, budgets and usage in one place';
+/** Why /model and its menu show no ZergRouter choices before a login. */
+export const ROUTER_MODELS_NEED_LOGIN = 'ZergRouter models appear after you log in';
+/** Each benefit by name, for surfaces that quote one (Router tips). */
+export const ZERGAI_LOGIN_BENEFIT = {
+    oneLogin: 'One ZergAI login for ZTC in the terminal and the desktop app',
+    providerKeys: 'Add provider keys once in Zerg Router, not on this machine',
+    deepSeek: 'DeepSeek ready on Zerg Router billing, no DeepSeek key needed',
+    usage: 'Usage history, per-key daily budgets and a monthly cap on Router billing',
+    switchModels: 'Switch models any time with /model',
+};
+/** The benefits listed while the ZergAI choice is highlighted or hovered. */
+export const ZERGAI_LOGIN_BENEFITS = [
+    ZERGAI_LOGIN_BENEFIT.oneLogin,
+    ZERGAI_LOGIN_BENEFIT.providerKeys,
+    ZERGAI_LOGIN_BENEFIT.deepSeek,
+    ZERGAI_LOGIN_BENEFIT.usage,
+    ZERGAI_LOGIN_BENEFIT.switchModels,
+];
+/**
+ * True once the user chose local API keys: in /connect, or by saving the
+ * direct route (for example with /model direct). Launch does not ask them again.
+ */
+export function choseLocalApiKeys(config, authMode) {
+    return config.onboarding?.connectChoice === 'direct' || authMode === 'direct';
+}
+/**
+ * Whether launch asks how to connect. Without a ZergAI login, every launch
+ * asks unless local keys were chosen and still reach a model
+ * (`modelReachable`). An expired ZergAI login is asked again unless local
+ * keys were chosen in /connect since; a ZergAI login records its own choice,
+ * so a later expiry is never silent. The launch readout names an expired
+ * session either way.
+ */
+export function askHowToConnectAtLaunch(config, authMode, session, modelReachable) {
+    switch (session) {
+        case 'signed_in': return false;
+        case 'expired': return !(config.onboarding?.connectChoice === 'direct' && modelReachable);
+        case 'signed_out': return !(choseLocalApiKeys(config, authMode) && modelReachable);
+    }
+}

package/dist/prompts/subagent_worker.j2

@@ -0,0 +1,20 @@
+You are a developer on a team. Your lead assigned you the workstream below; do that workstream and report back.
+
+How to work:
+- You have at most {{ max_iterations }} steps, so act efficiently: run independent searches, reads and commands together in one step.
+{% if editing -%}
+- Make the changes your workstream needs, and only those. Check that they work (run the relevant test or command) before you report.
+{% else -%}
+- Do not change files or install anything; your job is to find out and report.
+{% endif -%}
+{% if supervised -%}
+- At each milestone, call report_progress with what you have done, what you found and what you will do next; your lead supervises from these notes.
+- Your lead may send you a message ([Message from your lead]); follow it.
+{% endif -%}
+- If the workstream cannot be done as given, stop and say why rather than guessing.
+
+Your report is all your lead will see. Keep it short and exact:
+- What you found or changed, with file paths and line numbers, and the commands you ran with their key output.
+- How you verified it, and what you could not finish or did not check. Say "not found" plainly; never invent a path, value or result.
+
+Working directory: {{ cwd }}

package/dist/prompts/tool_delegate_task.j2

@@ -1,18 +1,9 @@
-Delegate a task to a sub-agent with isolated context. This call BLOCKS until the sub-agent finishes and returns its result.
+Hand a workstream to a worker: a substantial part of the job with its own definition of done, done with its own fresh context.
 
-Use this when you need the result before you can continue (e.g. "find X so I can decide Y").
+The worker receives its workstream, your `context` (what you verified, relevant paths and commands, what was tried and failed, constraints), the original task and the environment, and nothing else you know. It reports back what it found or changed and how it verified it; its report is unverified until you check the key claim.
 
-Good for:
-- Exploring codebases to find specific patterns or files
-- Searching for usages of functions, classes, or variables
-- Reading multiple files to gather information
-- Running shell commands to investigate system state
+Run workstreams in the background (`background: true`) and keep working; reports arrive in this conversation, with a progress check at each interval while workers run. Supervise with `check: true`, `steer: {worker, message}` and `stop: <worker id>`; `collect: true` waits for the reports still pending (or the next progress check).
 
-The sub-agent runs independently and returns an unverified summary plus a bounded source-linked evidence handoff. Omission counts are explicit. Child observations stay in the child's session; they never grant parent authority. Resume an owned child using child_session_id from its handoff to list session_evidence or recall_tool_response with the original tool-call handle. Missing sources remain unknown. A handoff from another parent or workspace cannot be resumed here.
+Without `background` the call blocks until the worker finishes. Up to 4 independent workstreams can go in one call as `tasks`. `toolset: "write"` lets a worker edit files; budgets are set with `max_iterations` (steps) and `minutes`.
 
-IMPORTANT: If the user says "in the background", "while you do X", "independently", or the result is NOT needed immediately, use spawn_background_agent instead — it returns instantly so you can keep talking.
-
-Best practices:
-- Use for research/exploration tasks that would require reading many files
-- Be specific about what you want to find
-- The sub-agent has 5 iterations by default, so phrase tasks that can be completed quickly
+A single step you could take in one or two tool calls is faster to do yourself. Resume an owned child with child_session_id from its handoff to list session_evidence or recall_tool_response with its original tool-call handles.

package/dist/router_auth.d.ts

@@ -1,5 +1,9 @@
 import type { ZTCAuthMode } from './config/types.js';
 export declare const DEFAULT_ROUTER_ORIGIN = "https://zergrouter.com";
+/** A login's options with a Router name (dev, prod) turned into the --url it stands for. */
+export declare function namedRouterLoginOptions(options: readonly string[]): string[];
+/** Whether this profile holds a usable personal Zerg Router login. */
+export type RouterSessionStatus = 'signed_in' | 'expired' | 'signed_out';
 /** Local, actionable routing failures whose messages contain no remote payload. */
 export declare class RouterConfigurationError extends Error {
     readonly kind: 'configuration' | 'expired' | 'authentication_required';
@@ -7,6 +11,8 @@ export declare class RouterConfigurationError extends Error {
     get needsSignIn(): boolean;
 }
 type RouterAuthOutput = (message: string, stream: 'stdout' | 'stderr') => void;
+/** Where Router output is read: the `ztc auth` shell command or a ZTC session's /auth. */
+export type RouterAuthSurface = 'shell' | 'session';
 export interface RouterCredentials {
     origin: string;
     token: string;
@@ -18,7 +24,24 @@ export interface RouterCredentials {
         zergProxyUrl?: string;
     };
 }
+/**
+ * The routing a logout leaves. While routing still depends on this login (the
+ * mode the login set, or Zerg Router only), the settings from before the
+ * login come back; routing changed to anything else after the login stays.
+ */
+export declare function routingAfterLogout(credentials: Pick<RouterCredentials, 'origin' | 'previousConfig'>, current: {
+    authMode?: ZTCAuthMode;
+    zergProxyUrl?: string;
+}): {
+    restore: boolean;
+    authMode: ZTCAuthMode;
+};
 export declare function loadRouterCredentials(): Promise<RouterCredentials | null>;
+/** A device login that ended without approval: its grant ran out, or the person cancelled it. */
+export declare class RouterLoginEndedError extends Error {
+    readonly reason: 'expired' | 'cancelled';
+    constructor(message: string, reason: 'expired' | 'cancelled');
+}
 export interface RouterAccountReadiness {
     version: 1;
     scope: {
@@ -45,8 +68,19 @@ export interface RouterAccountReadiness {
         signIn: string;
     };
 }
-export declare function readRouterAccountReadiness(credentials: RouterCredentials): Promise<RouterAccountReadiness>;
-export declare function formatRouterAccountReadiness(account: RouterAccountReadiness): string;
+export declare function readRouterAccountReadiness(credentials: RouterCredentials, surface?: RouterAuthSurface): Promise<RouterAccountReadiness>;
+export declare function formatRouterAccountReadiness(account: RouterAccountReadiness, surface?: RouterAuthSurface): string;
+export interface RouterAuthCommandOptions {
+    /** The configured Router origin, when the caller knows overrides a fresh load would miss. */
+    origin?: string;
+    surface?: RouterAuthSurface;
+    /** Cancels a login still waiting for browser approval. */
+    signal?: AbortSignal;
+    /** Called once the browser approved the login, before it is saved; a cancel no longer applies. */
+    onApproved?: () => void;
+    /** Called once the approved login and its routing are saved, before the account readiness check. */
+    onSaved?: () => void | Promise<void>;
+}
 /** Shared Router authentication for the shell and in-session slash commands. */
-export declare function runRouterAuthCommand(args: readonly string[], output?: RouterAuthOutput): Promise<void>;
+export declare function runRouterAuthCommand(args: readonly string[], output?: RouterAuthOutput, { origin: configuredOrigin, surface, ...hooks }?: RouterAuthCommandOptions): Promise<void>;
 export {};