claude-code-infinite 1.0.20 → 1.0.22

package/dist/diagnostics.js

@@ -0,0 +1,316 @@
+/**
+ * Client diagnostics: why a session stalls, without ever sending its content
+ * (polychat plans/2026-10-16_PLAN_ccc_client_diagnostics.md).
+ *
+ * What is sent: ccc / Claude Code / Node versions, install method, OS and arch,
+ * terminal type, locale, and lifecycle and error events made of enums, status
+ * codes, sizes and timings (diagnostics-schema.ts is the allowlist; polychat
+ * enforces it again). Never prompts, paths, hostnames, usernames, env values,
+ * keys or error message text.
+ *
+ * Hard constraints, like reqlog.ts: never throw and never block. Events go into
+ * a capped in-memory queue; batches are POSTed fire-and-forget (every
+ * FLUSH_INTERVAL_MS, after the sign-in prompt, and at shutdown under a short
+ * bound); a failed POST drops its batch.
+ *
+ * Off with CCC_NO_DIAGNOSTICS=1, `"diagnostics": false` in the config,
+ * DO_NOT_TRACK=1, or Claude Code's DISABLE_TELEMETRY /
+ * CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC.
+ */
+import { randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import { join } from "node:path";
+import { DIAGNOSTICS_SCHEMA, TERMINALS, TURN_TYPES, errnoName, errorClassName, sanitizeContext, sanitizeEvent, threePartVersion, } from "./diagnostics-schema.js";
+export const DIAGNOSTICS_PATH = "/v1/ccc/diagnostics";
+export const INSTALL_ID_FILE = "install_id";
+export const FLUSH_INTERVAL_MS = 30_000;
+export const MAX_QUEUE = 200;
+export const BATCH_SIZE = 50;
+export const SEND_TIMEOUT_MS = 3_000;
+export const SHUTDOWN_FLUSH_MS = 1_000;
+/** Repeats of one error kind (event + status) reported per process. */
+export const MAX_REPEATS = 5;
+const OPT_OUT_ENV = [
+    "CCC_NO_DIAGNOSTICS", "DO_NOT_TRACK", "DISABLE_TELEMETRY",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC",
+];
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** False when any opt-out is set. */
+export function diagnosticsEnabled(env, config) {
+    if (config.diagnostics === false)
+        return false;
+    return !OPT_OUT_ENV.some((name) => envFlagSet(env[name]));
+}
+export class Diagnostics {
+    opts;
+    enabled;
+    /** True when this launch created the install id (the machine's first run). */
+    firstRun;
+    /** Events dropped because the queue was full. */
+    dropped = 0;
+    installId;
+    queue = [];
+    inFlight = new Set();
+    repeats = new Map();
+    context = {};
+    apiKey;
+    timer;
+    constructor(opts) {
+        this.opts = opts;
+        const env = opts.env ?? process.env;
+        let enabled = diagnosticsEnabled(env, opts.config ?? {});
+        const install = enabled ? readOrCreateInstallId(opts.configDir) : null;
+        if (install === null)
+            enabled = false;
+        this.enabled = enabled;
+        this.installId = install?.id ?? null;
+        this.firstRun = install?.created === true;
+        this.apiKey = opts.apiKey;
+        if (enabled)
+            this.context = sanitizeContext(environmentContext(env, opts.clientVersion));
+    }
+    setApiKey(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /** Add context fields (allowlisted; later values win). */
+    setContext(fields) {
+        if (!this.enabled)
+            return;
+        try {
+            this.context = { ...this.context, ...sanitizeContext(fields) };
+        }
+        catch {
+            // Never break the caller.
+        }
+    }
+    record(name, fields = {}) {
+        if (!this.enabled)
+            return;
+        try {
+            const event = sanitizeEvent(name, fields, this.now());
+            if (event === null)
+                return;
+            if (this.queue.length >= (this.opts.maxQueue ?? MAX_QUEUE)) {
+                this.dropped++;
+                return;
+            }
+            this.queue.push(event);
+        }
+        catch {
+            // Never break the caller.
+        }
+    }
+    /** Like record, but at most MAX_REPEATS times per `key` in this process. */
+    recordLimited(key, name, fields = {}) {
+        const seen = this.repeats.get(key) ?? 0;
+        if (seen >= MAX_REPEATS)
+            return;
+        this.repeats.set(key, seen + 1);
+        this.record(name, fields);
+    }
+    /** Flush every FLUSH_INTERVAL_MS without keeping the process alive. */
+    start() {
+        if (!this.enabled || this.timer)
+            return;
+        this.timer = setInterval(() => this.flushNow(), this.opts.flushIntervalMs ?? FLUSH_INTERVAL_MS);
+        this.timer.unref();
+    }
+    /** Send what is queued now; fire-and-forget. */
+    flushNow() {
+        if (!this.enabled)
+            return;
+        while (this.queue.length > 0) {
+            this.track(this.send(this.queue.splice(0, BATCH_SIZE)));
+        }
+    }
+    /** Shutdown: send what is queued and wait for in-flight sends, at most `timeoutMs`. */
+    async flush(timeoutMs = SHUTDOWN_FLUSH_MS) {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.flushNow();
+        if (this.inFlight.size === 0)
+            return;
+        let timer;
+        await Promise.race([
+            Promise.allSettled([...this.inFlight]),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+    }
+    /** The exact JSON body a batch of these events is sent as (tests read it). */
+    batchBody(events) {
+        return JSON.stringify({
+            schema: DIAGNOSTICS_SCHEMA, install_id: this.installId, context: this.context, events,
+        });
+    }
+    async send(events) {
+        try {
+            const doFetch = this.opts.fetchImpl ?? fetch;
+            await doFetch(`${this.opts.baseUrl.replace(/\/$/, "")}${DIAGNOSTICS_PATH}`, {
+                method: "POST",
+                headers: this.headers(),
+                body: this.batchBody(events),
+                signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+            });
+        }
+        catch {
+            // Dropped: diagnostics never retry or surface errors.
+        }
+    }
+    headers() {
+        return {
+            "content-type": "application/json",
+            "x-client": this.opts.clientName,
+            "x-client-version": this.opts.clientVersion,
+            ...(this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}),
+        };
+    }
+    track(sending) {
+        this.inFlight.add(sending);
+        void sending.finally(() => this.inFlight.delete(sending));
+    }
+    now() {
+        return (this.opts.now ?? Date.now)();
+    }
+}
+/**
+ * Tee for the request log: every record still goes to `inner` unchanged, and a
+ * few named numeric/enum fields of some records become diagnostics events.
+ * Records are never copied: they can hold content (client.systemHead, URLs).
+ */
+export class DiagnosticsRequestSink {
+    inner;
+    diagnostics;
+    firstRequest = false;
+    firstTurn = false;
+    constructor(inner, diagnostics) {
+        this.inner = inner;
+        this.diagnostics = diagnostics;
+    }
+    log(record) {
+        this.inner?.log(record);
+        try {
+            this.observe(record);
+        }
+        catch {
+            // Diagnostics never break the request log.
+        }
+    }
+    observe(record) {
+        if (record.kind === "messages")
+            this.observeMessages(record);
+        else if (record.kind === "memtree")
+            this.observeMemtree(record);
+    }
+    observeMessages(rec) {
+        if (rec.turnType === "foreign")
+            return;
+        const ccVersion = threePartVersion(rec.client?.ccVersion);
+        if (ccVersion)
+            this.diagnostics.setContext({ cc_version: ccVersion });
+        const fields = {
+            status: rec.upstreamStatus, turn_type: turnType(rec.turnType), ttfb_ms: rec.ttfbMs,
+            total_ms: rec.totalMs, request_kb: kb(rec.requestBytes),
+        };
+        if (!this.firstRequest) {
+            this.firstRequest = true;
+            this.diagnostics.record("first_request", fields);
+        }
+        if (!this.firstTurn && rec.client?.turnOrigin === "human") {
+            this.firstTurn = true;
+            this.diagnostics.record("first_turn", fields);
+        }
+        this.observeMessageErrors(rec, fields);
+    }
+    observeMessageErrors(rec, fields) {
+        const status = rec.upstreamStatus;
+        if (typeof status === "number" && status >= 400) {
+            this.diagnostics.recordLimited(`upstream:${status}`, "upstream_error", fields);
+        }
+        if (rec.compress?.timedOut) {
+            this.diagnostics.recordLimited("compress_timeout", "compress_timeout", { ms: rec.compress.ms, request_kb: kb(rec.requestBytes) });
+        }
+    }
+    observeMemtree(rec) {
+        if (rec.ok)
+            return;
+        this.diagnostics.recordLimited(`memtree:${rec.status ?? "none"}`, "memtree_error", {
+            status: rec.status, index_only: rec.indexOnly, ms: rec.ms, request_kb: kb(rec.requestBytes),
+        });
+    }
+}
+/** Record a launcher error by code only: Node's errno and class name, never its message. */
+export function recordError(diagnostics, code, err) {
+    const e = err;
+    diagnostics.record("error", {
+        code,
+        errno: errnoName(e?.code),
+        error_name: errorClassName(e?.name),
+    });
+}
+/** The install id, created (0600) on first use; null when it cannot be read or written. */
+export function readOrCreateInstallId(configDir) {
+    const file = join(configDir, INSTALL_ID_FILE);
+    try {
+        const existing = readFileSync(file, "utf-8").trim();
+        if (UUID_RE.test(existing))
+            return { id: existing, created: false };
+    }
+    catch {
+        // Missing: create it below.
+    }
+    try {
+        mkdirSync(configDir, { recursive: true, mode: 0o700 });
+        const id = randomUUID();
+        writeFileSync(file, `${id}\n`, { mode: 0o600 });
+        chmodSync(file, 0o600);
+        return { id, created: true };
+    }
+    catch {
+        return null;
+    }
+}
+/** Environment context; every value is mapped onto an allowlisted shape. */
+export function environmentContext(env, cccVersion) {
+    return {
+        ccc_version: threePartVersion(cccVersion),
+        node: threePartVersion(process.versions.node),
+        os: process.platform,
+        os_release: /^\d{1,4}(?:\.\d{1,6}){0,2}/.exec(os.release())?.[0],
+        arch: process.arch,
+        terminal: terminalName(env),
+        locale: localeName(),
+        wsl: process.platform === "linux" && (env.WSL_DISTRO_NAME !== undefined || env.WSL_INTEROP !== undefined),
+    };
+}
+export function terminalName(env) {
+    const raw = env.TERM_PROGRAM;
+    if (!raw)
+        return env.WT_SESSION ? "Windows_Terminal" : "none";
+    const known = TERMINALS.find((t) => t.toLowerCase() === raw.toLowerCase());
+    return known ?? "other";
+}
+export function localeName() {
+    try {
+        const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+        return /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?$/.test(locale) ? locale : "other";
+    }
+    catch {
+        return "other";
+    }
+}
+function turnType(value) {
+    return TURN_TYPES.includes(value) ? value : "other";
+}
+function kb(bytes) {
+    return typeof bytes === "number" ? Math.round(bytes / 1024) : undefined;
+}
+function envFlagSet(value) {
+    return value !== undefined && /^(1|true|yes|on)$/i.test(value.trim());
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/first-tree.d.ts

@@ -0,0 +1,11 @@
+import type { FirstTreeIntro } from "./hooks.js";
+import type { MemtreeLinkStore } from "./memtree-links.js";
+export declare const FIRST_TREE_MARKER_FILE = "first-tree-shown.json";
+export declare class FirstTreeMarker implements FirstTreeIntro {
+    private readonly linkStore?;
+    readonly filePath: string;
+    constructor(linkStore?: Pick<MemtreeLinkStore, "hasOtherSession"> | undefined, filePath?: string);
+    isFirstEver(sessionId: string | undefined): boolean;
+    markShown(_sessionId: string | undefined): void;
+}
+//# sourceMappingURL=first-tree.d.ts.map

package/dist/first-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-tree.d.ts","sourceRoot":"","sources":["../src/first-tree.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D,qBAAa,eAAgB,YAAW,cAAc;IAElD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM;gBADR,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,YAAA,EAC7D,QAAQ,GAAE,MAA0D;IAG/E,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;IASnD,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAUhD"}

package/dist/first-tree.js

@@ -0,0 +1,45 @@
+/**
+ * Whether the user has ever been shown a MemTree, so the first tree they ever
+ * see can say what to do with it (FIRST_EVER_HINT). A marker file in the ccc
+ * config dir records that it was shown. A user who had trees before this
+ * notice existed has pages in memtree-links.json for other sessions, and so
+ * counts as having seen one.
+ *
+ * Every failure reads as "not the first": the hint is a nicety, and showing it
+ * twice is worse than never.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getConfigDir } from "./config.js";
+export const FIRST_TREE_MARKER_FILE = "first-tree-shown.json";
+export class FirstTreeMarker {
+    linkStore;
+    filePath;
+    constructor(linkStore, filePath = path.join(getConfigDir(), FIRST_TREE_MARKER_FILE)) {
+        this.linkStore = linkStore;
+        this.filePath = filePath;
+    }
+    isFirstEver(sessionId) {
+        try {
+            if (fs.existsSync(this.filePath))
+                return false;
+            return !this.linkStore?.hasOtherSession(sessionId);
+        }
+        catch {
+            return false;
+        }
+    }
+    markShown(_sessionId) {
+        try {
+            if (fs.existsSync(this.filePath))
+                return;
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+            const shownAt = new Date().toISOString();
+            fs.writeFileSync(this.filePath, JSON.stringify({ shownAt }), { mode: 0o600, flag: "wx" });
+        }
+        catch {
+            // Another ccc wrote it first, or the dir is read-only: either way, done.
+        }
+    }
+}
+//# sourceMappingURL=first-tree.js.map

package/dist/first-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-tree.js","sourceRoot":"","sources":["../src/first-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAE9D,MAAM,OAAO,eAAe;IAEP;IACR;IAFX,YACmB,SAAqD,EAC7D,WAAmB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,sBAAsB,CAAC;QAD5D,cAAS,GAAT,SAAS,CAA4C;QAC7D,aAAQ,GAAR,QAAQ,CAA4D;IAC5E,CAAC;IAEJ,WAAW,CAAC,SAA6B;QACvC,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC/C,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,SAAS,CAAC,UAA8B;QACtC,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAAE,OAAO;YACzC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACzC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5F,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;QAC3E,CAAC;IACH,CAAC;CACF"}

package/dist/hooks.d.ts

@@ -12,6 +12,17 @@ export declare const MESSAGE_DISPLAY_MIN_VERSION = "2.1.166";
 export declare const TRAILER_LABEL = "\u2022 MemTree \u00B7";
 /** Label on a line that carries a MemTree page link. */
 export declare const LINK_LABEL = "\u2022 MemTree";
+/** What the link is, said next to the label when a tree is news. */
+export declare const LINK_DESCRIPTION = "this session's memory map";
+/**
+ * The one-time notice for a session's first tree: set apart from the routine
+ * link (leaf, bold) and saying in one line why it is worth opening. Kept short
+ * enough to fit 80 columns after Claude Code's "Stop says: " label.
+ */
+export declare const FIRST_TREE_TITLE = "\uD83C\uDF3F First MemTree ready";
+export declare const FIRST_TREE_VALUE = "a searchable map of this session so far";
+/** Added under the first tree a user ever sees: what to do with it. */
+export declare const FIRST_EVER_HINT = "Open it, or paste the link to any agent to give it this session's context";
 /**
  * Closes every URL line. Terminal linkifiers run a bare URL into whatever is
  * drawn right after it when the row joins the next one: a URL that ended a
@@ -73,6 +84,15 @@ export interface SuccessLink {
      */
     note?: string;
 }
+/**
+ * Introduces the first tree of each session (see FIRST_TREE_TITLE). Answers
+ * whether this is the user's first tree ever, and hears when the intro was
+ * shown. Failures never break a hook.
+ */
+export interface FirstTreeIntro {
+    isFirstEver(sessionId: string | undefined): boolean;
+    markShown(sessionId: string | undefined): void;
+}
 /**
  * Where the trailer (`• MemTree · <link>`) is shown: under every finished
  * assistant message (with Stop as the fallback for a turn that rendered no
@@ -154,6 +174,7 @@ export declare class NoticeDeliveryQueue {
     private readonly delivered;
     private trailer;
     private trailerPlacement;
+    private firstTreeIntro;
     /** Key of the last trailer shown; a different key is announced as new. */
     constructor(ttlMs?: number, now?: () => number, color?: boolean);
     /** Replace stale delivery state when a new main human prompt is submitted. */
@@ -180,6 +201,11 @@ export declare class NoticeDeliveryQueue {
      * link is always at the bottom of the screen.
      */
     setTrailer(resolve: LinkResolver | null, placement?: TrailerPlacement): void;
+    /**
+     * Announce the first link a session shows with the one-time first-tree
+     * notice instead of the routine trailer. Off (null) by default.
+     */
+    setFirstTreeIntro(intro: FirstTreeIntro | null): void;
     queuePrefix(text: NoticeText, onDelivered?: () => void, promptId?: string): void;
     queueSuffix(text: NoticeText, onDelivered?: () => void, promptId?: string): void;
     /**
@@ -205,6 +231,8 @@ export declare class NoticeDeliveryQueue {
      * does not repeat the same link.
      */
     private renderSuccess;
+    /** No link has been shown for this session yet, and the first-tree intro is on. */
+    private isFirstLink;
     /** The session's current link, shown or not. Resolver failures never break a hook. */
     private currentLink;
     /** The link if its key changed since last shown, without marking it. Resolver failures never break a hook. */
@@ -216,6 +244,15 @@ export declare class NoticeDeliveryQueue {
      * marks the key as seen. Resolver failures never break a hook.
      */
     private renderTrailer;
+    /** A link that is news: green label, then what it is (dim). */
+    private newLinkLabel;
+    /**
+     * The session's first tree: bold leaf title, the value in one line, the
+     * URL below; for the user's first tree ever, one dim line on what to do.
+     */
+    private firstTreeNotice;
+    /** Call the first-tree intro; a throwing one never breaks a hook. */
+    private askIntro;
     /** The link notice with its note dim. */
     private linkNotice;
     private styleDim;

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks.js

@@ -15,6 +15,17 @@ export const MESSAGE_DISPLAY_MIN_VERSION = "2.1.166";
 export const TRAILER_LABEL = "• MemTree ·";
 /** Label on a line that carries a MemTree page link. */
 export const LINK_LABEL = "• MemTree";
+/** What the link is, said next to the label when a tree is news. */
+export const LINK_DESCRIPTION = "this session's memory map";
+/**
+ * The one-time notice for a session's first tree: set apart from the routine
+ * link (leaf, bold) and saying in one line why it is worth opening. Kept short
+ * enough to fit 80 columns after Claude Code's "Stop says: " label.
+ */
+export const FIRST_TREE_TITLE = "🌿 First MemTree ready";
+export const FIRST_TREE_VALUE = "a searchable map of this session so far";
+/** Added under the first tree a user ever sees: what to do with it. */
+export const FIRST_EVER_HINT = "Open it, or paste the link to any agent to give it this session's context";
 /**
  * Closes every URL line. Terminal linkifiers run a bare URL into whatever is
  * drawn right after it when the row joins the next one: a URL that ended a
@@ -42,6 +53,7 @@ const ANSI_GREEN = "\x1b[32m";
 const ANSI_YELLOW = "\x1b[33m";
 const ANSI_DEFAULT_FOREGROUND = "\x1b[39m";
 const ANSI_DIM = "\x1b[2m";
+const ANSI_BOLD = "\x1b[1m";
 const ANSI_NORMAL_INTENSITY = "\x1b[22m";
 const STARTUP_NOTICE_FILE = "startup-notice.json";
 const RESUME_RELAY_FILE = "resume-link.mjs";
@@ -156,6 +168,7 @@ export class NoticeDeliveryQueue {
     delivered = new Map();
     trailer = null;
     trailerPlacement = "message";
+    firstTreeIntro = null;
     /** Key of the last trailer shown; a different key is announced as new. */
     constructor(ttlMs = DEFAULT_NOTICE_TTL_MS, now = Date.now, color = terminalSupportsColor()) {
         this.ttlMs = ttlMs;
@@ -184,7 +197,7 @@ export class NoticeDeliveryQueue {
         this.deliveryFor(sessionId).trailer = link.key;
         this.deliveryFor(sessionId).trailerUrl = link.link;
         this.deliveryFor(sessionId).link = link.key;
-        return this.linkNotice(this.styleSuccess(LINK_LABEL), link);
+        return this.linkNotice(this.newLinkLabel(), link);
     }
     /** Whether the next success line would carry a link not shown before. */
     linkPending(sessionId) {
@@ -200,6 +213,13 @@ export class NoticeDeliveryQueue {
         this.trailer = resolve;
         this.trailerPlacement = placement;
     }
+    /**
+     * Announce the first link a session shows with the one-time first-tree
+     * notice instead of the routine trailer. Off (null) by default.
+     */
+    setFirstTreeIntro(intro) {
+        this.firstTreeIntro = intro;
+    }
     queuePrefix(text, onDelivered, promptId) {
         this.pending = {
             createdAt: this.now(),
@@ -339,11 +359,22 @@ export class NoticeDeliveryQueue {
         const link = this.currentLink(sessionId);
         if (link === undefined)
             return this.styleSuccess(text);
-        this.deliveryFor(sessionId).link = link.key;
-        this.deliveryFor(sessionId).successPage = noticePageIdentity(link.link);
-        this.deliveryFor(sessionId).trailer = link.key;
-        this.deliveryFor(sessionId).trailerUrl = link.link;
-        return `${this.styleSuccess(text)}\n${urlLine(link.link)}`;
+        // The session's first link may arrive with a compression: introduce it here,
+        // since marking it delivered below keeps the trailer from ever doing so.
+        const first = this.isFirstLink(sessionId);
+        const delivered = this.deliveryFor(sessionId);
+        delivered.link = link.key;
+        delivered.successPage = noticePageIdentity(link.link);
+        delivered.trailer = link.key;
+        delivered.trailerUrl = link.link;
+        const below = first ? this.firstTreeNotice(link.link, sessionId) : urlLine(link.link);
+        return `${this.styleSuccess(text)}\n${below}`;
+    }
+    /** No link has been shown for this session yet, and the first-tree intro is on. */
+    isFirstLink(sessionId) {
+        const delivered = this.deliveryFor(sessionId);
+        return this.firstTreeIntro !== null && delivered.trailer === undefined &&
+            delivered.link === undefined && delivered.trailerUrl === undefined;
     }
     /** The session's current link, shown or not. Resolver failures never break a hook. */
     currentLink(sessionId) {
@@ -395,11 +426,40 @@ export class NoticeDeliveryQueue {
         // "turn": one line per user turn, and only when the index changed.
         if (this.trailerPlacement === "turn" && !isNew)
             return undefined;
-        this.deliveryFor(sessionId).trailer = link.key;
-        this.deliveryFor(sessionId).trailerUrl = link.link;
-        const label = isNew ? this.styleSuccess(LINK_LABEL) : this.styleDim(LINK_LABEL);
+        const first = this.isFirstLink(sessionId);
+        delivered.trailer = link.key;
+        delivered.trailerUrl = link.link;
+        if (first)
+            return this.firstTreeNotice(link.link, sessionId);
+        const label = isNew ? this.newLinkLabel() : this.styleDim(LINK_LABEL);
         return this.linkNotice(label, link);
     }
+    /** A link that is news: green label, then what it is (dim). */
+    newLinkLabel() {
+        return `${this.styleSuccess(LINK_LABEL)} · ${this.styleDim(LINK_DESCRIPTION)}`;
+    }
+    /**
+     * The session's first tree: bold leaf title, the value in one line, the
+     * URL below; for the user's first tree ever, one dim line on what to do.
+     */
+    firstTreeNotice(url, sessionId) {
+        const title = this.color
+            ? `${ANSI_BOLD}${this.styleSuccess(FIRST_TREE_TITLE)}${ANSI_NORMAL_INTENSITY}`
+            : FIRST_TREE_TITLE;
+        const notice = linkLines(title, url, FIRST_TREE_VALUE);
+        const firstEver = this.askIntro((intro) => intro.isFirstEver(sessionId)) === true;
+        this.askIntro((intro) => intro.markShown(sessionId));
+        return firstEver ? `${notice}\n  ${this.styleDim(FIRST_EVER_HINT)}` : notice;
+    }
+    /** Call the first-tree intro; a throwing one never breaks a hook. */
+    askIntro(call) {
+        try {
+            return this.firstTreeIntro ? call(this.firstTreeIntro) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** The link notice with its note dim. */
     linkNotice(label, link) {
         return linkLines(label, link.link, link.note && this.styleDim(link.note));