@yadsh/dsh-qa-surface 0.7.3 → 0.8.0

package/lib/types/client/markdown/blocks.d.ts

@@ -0,0 +1,74 @@
+/**
+ * GFM block grammar for the chat renderer: the container and leaf blocks the
+ * assistant's answers actually use, parsed here and handed to `render.tsx` as
+ * plain data. Text inside a leaf block stays raw Markdown — `parseInline`
+ * resolves it at render time — so one block pass feeds every inline consumer.
+ *
+ * The grammar is deliberately a subset of CommonMark: nested containers and
+ * lazy continuation are supported, while the pathological corners (HTML
+ * blocks, setext inside lists, link reference definitions spanning lines) stay
+ * out. Raw HTML never becomes a block: a tag line is a paragraph whose inline
+ * pass leaves the tag as literal text.
+ */
+/** `#`-through-`######` heading levels. */
+export type HeadingDepth = 1 | 2 | 3 | 4 | 5 | 6;
+/** Column alignment carried by a table's delimiter row. */
+export type TableAlign = "left" | "center" | "right";
+/** One list item: its own blocks plus the checkbox a task item declares. */
+export interface MarkdownListItem {
+    readonly blocks: readonly MarkdownBlock[];
+    readonly task: boolean;
+    readonly checked: boolean;
+}
+/** A block-level node; `text` fields hold raw inline Markdown. */
+export type MarkdownBlock = {
+    readonly kind: "paragraph";
+    readonly text: string;
+} | {
+    readonly kind: "heading";
+    readonly depth: HeadingDepth;
+    readonly text: string;
+} | {
+    readonly kind: "code";
+    readonly text: string;
+    readonly lang?: string;
+} | {
+    readonly kind: "quote";
+    readonly blocks: readonly MarkdownBlock[];
+} | {
+    readonly kind: "list";
+    readonly ordered: boolean;
+    readonly start: number;
+    readonly loose: boolean;
+    readonly items: readonly MarkdownListItem[];
+} | {
+    readonly kind: "table";
+    readonly align: readonly TableAlign[];
+    readonly head: readonly string[];
+    readonly rows: readonly (readonly string[])[];
+} | {
+    readonly kind: "rule";
+};
+/** A parsed document: its blocks plus the reference targets they resolve. */
+export interface ParsedMarkdown {
+    readonly blocks: readonly MarkdownBlock[];
+    /** Link/image definitions by upper-cased identifier. */
+    readonly definitions: ReadonlyMap<string, string>;
+}
+/** Split one table row into trimmed cells, honoring escaped pipes. */
+export declare function splitTableRow(line: string): string[];
+/**
+ * Parse a whole document.
+ * @param text - Markdown source with any line endings.
+ * @returns Blocks plus the definitions the inline pass resolves against.
+ */
+export declare function parseMarkdown(text: string): ParsedMarkdown;
+/**
+ * Parse the blocks of one container (document, quote, or list item).
+ * @param lines - Container lines, already de-indented by the caller.
+ * @param definitions - Document-wide definition accumulator.
+ * @param depth - Container nesting depth.
+ * @returns The container's blocks.
+ */
+export declare function parseBlocks(lines: readonly string[], definitions: Map<string, string>, depth: number): MarkdownBlock[];
+//# sourceMappingURL=blocks.d.ts.map

package/lib/types/client/markdown/highlight.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The chat renderer's syntax highlighter: a small tokenizer over per-language
+ * keyword/comment/string tables, not a grammar engine. The original UI runs
+ * shiki; its grammar modules alone cost ~1.6 MB, which a self-contained plugin
+ * bundle cannot carry, so this scanner covers the shapes that carry meaning in
+ * an answer — comments, strings, numbers, keywords — and leaves the rest of the
+ * line in the foreground color. Colors come from the host theme's
+ * `--shiki-token-*` custom properties, so a fenced block here matches a fenced
+ * block in the assistant's own transcript in both light and dark themes.
+ *
+ * An unknown or absent language renders plain: never an error, never a guess.
+ */
+/** Token categories the stylesheet colors. */
+export type HighlightClass = "comment" | "string" | "keyword" | "number" | "constant" | "meta" | "tag" | "attr" | "key" | "insert" | "delete" | "hunk";
+/** One colored run of a code line. */
+export interface HighlightSpan {
+    readonly text: string;
+    readonly cls?: HighlightClass;
+}
+/** One code line as colored runs. */
+export type HighlightLine = readonly HighlightSpan[];
+/**
+ * Highlight one fenced block.
+ * @param code - The fence's source text.
+ * @param lang - The fence's info string.
+ * @returns One {@link HighlightLine} per source line.
+ */
+export declare function highlightLines(code: string, lang: string | undefined): HighlightLine[];
+//# sourceMappingURL=highlight.d.ts.map

package/lib/types/client/markdown/inline.d.ts

@@ -0,0 +1,40 @@
+/**
+ * GFM inline grammar for the chat renderer: code spans, emphasis, links,
+ * images, autolinks, and the two line-break flavors. Emphasis follows the
+ * CommonMark intent (a closer must match its opener's delimiter run, `_` never
+ * opens inside a word) rather than the full delimiter-stack algorithm — the
+ * shapes this grammar cannot express are the pathological ones, and they
+ * degrade to literal text instead of mangling the sentence.
+ */
+/** One inline node; `children` nodes nest. */
+export type MarkdownInline = {
+    readonly kind: "text";
+    readonly value: string;
+} | {
+    readonly kind: "softbreak";
+} | {
+    readonly kind: "break";
+} | {
+    readonly kind: "code";
+    readonly value: string;
+} | {
+    readonly kind: "strong" | "em" | "del";
+    readonly children: readonly MarkdownInline[];
+} | {
+    readonly kind: "link";
+    readonly href: string;
+    readonly children: readonly MarkdownInline[];
+} | {
+    readonly kind: "image";
+    readonly src: string;
+    readonly alt: string;
+};
+/**
+ * Parse the inline content of one leaf block.
+ * @param text - Raw inline Markdown, newlines included.
+ * @param definitions - Link/image definitions collected by the block pass.
+ * @param depth - Inline nesting depth.
+ * @returns The inline nodes in document order.
+ */
+export declare function parseInline(text: string, definitions: ReadonlyMap<string, string>, depth?: number): MarkdownInline[];
+//# sourceMappingURL=inline.d.ts.map

package/lib/types/client/markdown/render.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+import { type MarkdownSourceContext } from "./source-chip.js";
+/**
+ * Render markdown source as semantic React elements. Raw HTML never enters the
+ * DOM (a tag is literal text), link and image destinations pass a protocol
+ * allowlist, and a source the owning message knows about becomes a chip
+ * instead of a plain link or code token.
+ * @param text - Assistant-authored markdown.
+ * @param context - Source resolution handed down by the owning message.
+ * @returns The document's blocks.
+ */
+export declare function renderMarkdown(text: string, context: MarkdownSourceContext): ReactNode[];
+//# sourceMappingURL=render.d.ts.map

package/lib/types/client/markdown/source-chip.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+import type { QaSource } from "../../types.js";
+import { type QaSourceRefs } from "../components/source-refs.js";
+/** Inline source awareness handed down from the owning assistant message. */
+export interface MarkdownSourceContext {
+    readonly refs?: QaSourceRefs;
+    /** Open a path-backed source in the sources drawer's detail view. */
+    readonly onSourceOpen?: (source: QaSource) => void;
+}
+/**
+ * One inline source footnote: a pill over the matched link or path with a
+ * hover/focus preview card (title, target, snippet). A URL-backed source is
+ * an anchor that opens right away; a path-backed one is a button whose click
+ * the owner routes to the sources drawer. The hover card stays out of the
+ * chip's accessible name and rides along as its description instead.
+ */
+export declare function SourceChip({ source, label, href, onOpen, }: {
+    readonly source: QaSource;
+    readonly label: string;
+    readonly href?: string;
+    readonly onOpen?: (source: QaSource) => void;
+}): ReactNode;
+/**
+ * The chip a path-backed inline-code token earns, or undefined when the token
+ * names no known source. A URL-backed token is a chip that opens right away.
+ */
+export declare function codeChip(value: string, context: MarkdownSourceContext): ReactNode | undefined;
+/** The chip a matched markdown link earns, or undefined when it matches none. */
+export declare function linkChip(href: string, label: string, context: MarkdownSourceContext): ReactNode | undefined;
+/** http(s)/mailto destinations only; images are narrowed further to http(s). */
+export declare function safeHref(value: string): string | undefined;
+//# sourceMappingURL=source-chip.d.ts.map

package/lib/types/client/markdown/use-transient-flag.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A boolean that turns on for a fixed window and drops back off — the
+ * "Скопировано" flash and its siblings. The pending timer lives in a ref and
+ * is cleared by the unmount cleanup, so a pulse fired right before the block
+ * leaves the DOM never schedules a state update on it, and re-pulsing restarts
+ * the window instead of stacking timers.
+ */
+export declare function useTransientFlag(windowMs: number): {
+    readonly on: boolean;
+    readonly pulse: () => void;
+};
+//# sourceMappingURL=use-transient-flag.d.ts.map

package/lib/types/client/role/RoleSelector.d.ts

@@ -8,7 +8,17 @@ export interface QaRoleSelectorProps {
 }
 /** Visible only when the account can actually choose between profiles. */
 export declare function QaRoleSelector(props: QaRoleSelectorProps): import("react/jsx-runtime").JSX.Element | null;
-export declare function QaAdminPreviewBanner({ role }: {
+/**
+ * The banner that keeps a preview from being mistaken for an ordinary chat.
+ *
+ * It carries the way out as well: while previewing, the header's role selector
+ * is hidden — the previewed profile need not be one the account holds — so
+ * without a control here the only exit was the browser's Back button, and a new
+ * chat meanwhile ran as the previewed profile instead of the account's default.
+ * @param props - the previewed role's name, and how to leave the preview.
+ */
+export declare function QaAdminPreviewBanner(props: {
     readonly role: string;
+    readonly onExit?: () => void;
 }): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=RoleSelector.d.ts.map

package/lib/types/client/role/preview.d.ts

@@ -0,0 +1,109 @@
+import type { QaSubrole } from "../../types.js";
+/**
+ * The administrator preview mode, as a property of the history entry.
+ *
+ * "Preview as role" navigates to the chat route carrying a marker in the
+ * history state. Deriving the mode from the entry — instead of latching it in
+ * component state — is what lets the browser's own Back button leave the
+ * preview, and what keeps a preview from outliving its entry: while the mode
+ * was latched, every later new chat in that browser tab was created as a
+ * preview of the previewed profile, silently ignoring the account's default
+ * profile, with the role selector hidden and only a corner banner to say so.
+ */
+/** One preview in force: the role and the name it was previewed under. */
+export interface QaAdminPreview {
+    readonly roleId: string;
+    readonly name: string;
+}
+interface PreviewState {
+    readonly qaPreview: string;
+    readonly qaPreviewName: string;
+}
+/** The history state a "Preview as role" navigation carries. */
+export declare function previewEntryState(role: Pick<QaSubrole, "id" | "name">): PreviewState;
+/**
+ * The preview one history entry asks for, or undefined for an ordinary entry.
+ *
+ * Home of an older Host or of a cleared entry carries no marker at all, and a
+ * marker whose role id cannot be read is ignored rather than guessed: the name
+ * is cosmetic, so an entry written before names travelled with the marker
+ * still previews, under its role id.
+ */
+export declare function readPreviewEntry(state: unknown): QaAdminPreview | undefined;
+export type QaPreviewTransition = {
+    readonly kind: "enter";
+    readonly preview: QaAdminPreview;
+} | {
+    readonly kind: "leave";
+} | {
+    readonly kind: "keep";
+};
+/**
+ * What the surface should do with the preview mode for one history entry.
+ *
+ * Only an administrator can preview, so an entry that asks for one while an
+ * ordinary account is signed in leaves the mode instead of entering it — the
+ * marker survives in the browser's history across a sign-out, and latching it
+ * again would hand the next account a chat under a profile it was never
+ * assigned.
+ * @param input - the entry's state, the preview in force, and who is signed in.
+ * @returns enter, leave, or keep, so the caller only writes state it must.
+ */
+export declare function planPreviewTransition(input: {
+    readonly state: unknown;
+    readonly preview: QaAdminPreview | null;
+    readonly isAdmin: boolean;
+}): QaPreviewTransition;
+/** The slice of the browser the preview needs; a test injects its own. */
+export interface QaPreviewBrowser {
+    readonly state: unknown;
+    pushState(data: unknown, unused: string, url?: string | null): void;
+    replaceState(data: unknown, unused: string, url?: string | null): void;
+    /** Subscribe to browser navigation; returns the unsubscribe. */
+    onPopState(listener: () => void): () => void;
+}
+export interface QaAdminPreviewOptions {
+    /** Only an administrator may preview; anyone else leaves the mode. */
+    readonly isAdmin: boolean;
+    /** The account's own default profile, restored when a preview ends. */
+    readonly fallbackSubrole: string | null;
+    /** The chat route a preview navigation returns to. */
+    readonly previewUrl: string;
+    /** Called with the profile the next chat must use; null when none is known. */
+    readonly onSelect: (roleId: string | null) => void;
+    /**
+     * Re-checked on every browser navigation AND whenever this changes: an
+     * in-app navigation to the chat route arrives without a `popstate` event.
+     */
+    readonly routeKey: string;
+    readonly target?: QaPreviewBrowser;
+}
+export interface QaAdminPreviewMode {
+    /** The preview in force right now, if any. */
+    readonly preview: QaAdminPreview | null;
+    /** Enter the preview of one role, as the administration console asks. */
+    readonly enter: (role: Pick<QaSubrole, "id" | "name">) => void;
+    /**
+     * End the mode because the chat on screen is not a preview, leaving the
+     * history entry alone: going Back to it is entering the preview again.
+     */
+    readonly clear: () => void;
+    /** End the mode for good, as the administrator asked from the banner. */
+    readonly leave: () => void;
+}
+/**
+ * The administrator preview mode of one browser tab.
+ *
+ * The mode is a property of the history entry, so entering and leaving it
+ * follows the browser: the console pushes an entry that carries the preview,
+ * every navigation back to an entry without one ends the mode, and only an
+ * administrator can hold it. The alternative — reading the marker once and
+ * latching it in component state — kept the mode alive for the whole tab, and
+ * since the role selector is hidden while previewing, later new chats silently
+ * ran as the previewed profile instead of the account's default one.
+ * @param options - who is signed in, the account default, and the history.
+ * @returns the preview in force plus the two explicit transitions.
+ */
+export declare function useQaAdminPreview(options: QaAdminPreviewOptions): QaAdminPreviewMode;
+export {};
+//# sourceMappingURL=preview.d.ts.map

package/lib/types/index.d.ts

@@ -68,7 +68,11 @@ export declare class QaSurface extends TypertRemoteService {
     accountsLogin(email: string, password: string): QaAccountSession;
     /** Identity probe; safe to call with an empty or expired token. */
     accountsWhoami(token: string): QaWhoamiResult;
-    /** Migrate a browser's local chat index into server-side ownership. */
+    /**
+     * Migrate a browser's local chat index into server-side ownership. The
+     * access service owns the filter: a delegated session in that index is not a
+     * chat and is never claimed.
+     */
     accountsClaimSessions(token: string, sessionIds: readonly string[]): QaClaimResult;
     /** The token user's owned session ids; the sidebar list authority. */
     accountsOwnedSessions(token: string): {

package/lib/types/lockdown-policy.d.ts

@@ -25,4 +25,20 @@ export declare function qaToolPolicyPlan(allow: readonly string[], isMounted: (t
  *   stays as unchecked as any allow-listed one, and no less.
  */
 export declare function qaToolDenial(allowed: ReadonlySet<string>, toolName: string, dynamicNames?: readonly string[]): string | undefined;
+/**
+ * The conversation-wide ceiling, applied to every agent of an attested chat.
+ *
+ * A scoped restriction and a scoped guard cover the scope that owns them and
+ * that scope's descendants. A delegated child is composed from the parent's
+ * PRESET, so the parent agent's own layers never enter the child's chain: the
+ * child is bounded by its preset `toolFilter` alone, and an expert can
+ * therefore hold — and call — a tool the subrole never granted the chat. This
+ * check is the ceiling the whole conversation shares: the subrole's reach,
+ * visible tools plus the grantable ones, so a skill may still hand a tool to a
+ * delegated assistant, but nothing may exceed what the role could ever grant.
+ * @param ceiling - names reachable anywhere in this conversation.
+ * @param toolName - the tool the model is trying to call.
+ * @returns the denial reason, or `undefined` when the call is within reach.
+ */
+export declare function qaCeilingDenial(ceiling: ReadonlySet<string>, toolName: string): string | undefined;
 //# sourceMappingURL=lockdown-policy.d.ts.map

package/lib/types/provenance/host-store.d.ts

@@ -35,9 +35,13 @@ export declare class QaProvenanceHost {
     constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, store?: QaProvenanceSnapshotStore, onPersistenceError?: (error: unknown) => void);
     dispose(): void;
     /**
-     * Drop every per-session record of one chat. Long-lived servers outlive
-     * their sessions by weeks; without this the collector, snapshot, call and
-     * lineage maps grow with every chat and turn forever.
+     * Drop the in-memory per-session records of one chat. Long-lived servers
+     * outlive their sessions by weeks; without this the collector, snapshot,
+     * call and lineage maps grow with every chat and turn forever. The durable
+     * snapshot file is intentionally kept: `session/disposed` also fires for
+     * runtime teardown of a chat that still exists and will be reopened, and
+     * its stored turns are what let the transcript show sources after a Host
+     * restart. Growth of the file is bounded by the snapshot store's caps.
      */
     private forget;
     private forgetAll;

package/lib/types/provenance/retention.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Retention contract for durable provenance.
+ *
+ * This module is deliberately free of Node imports: the resolved default
+ * config reaches the browser bundle through `resolve-config`, and a single
+ * `node:fs` import here would break that bundle at runtime.
+ */
+/**
+ * What a sharded provenance store keeps. Every bound counts turns, shards or
+ * days; zero means "keep everything" for that bound.
+ */
+export interface QaProvenanceRetention {
+    /** Newest turns kept per chat. */
+    readonly maxTurnsPerSession: number;
+    /** Chats kept, most recently written first. */
+    readonly maxSessions: number;
+    /** Chats untouched for longer than this are dropped. */
+    readonly maxAgeDays: number;
+    /** How often a write may trigger the directory sweep. */
+    readonly sweepIntervalMinutes: number;
+}
+/**
+ * Defaults sized for a QA deployment: one chat is worth a few hundred turns, a
+ * fortnight of chats is worth keeping, and an untouched month is finished.
+ */
+export declare const DEFAULT_QA_PROVENANCE_RETENTION: QaProvenanceRetention;
+/** Bounds the configuration validator enforces, mirrored for the CLI. */
+export declare const QA_PROVENANCE_RETENTION_LIMITS: Readonly<{
+    maxTurnsPerSession: {
+        min: number;
+        max: number;
+    };
+    maxSessions: {
+        min: number;
+        max: number;
+    };
+    maxAgeDays: {
+        min: number;
+        max: number;
+    };
+    sweepIntervalMinutes: {
+        min: number;
+        max: number;
+    };
+}>;
+//# sourceMappingURL=retention.d.ts.map

package/lib/types/provenance/snapshot-store.d.ts

@@ -1,23 +1,79 @@
+import { type QaProvenanceRetention } from "./retention.js";
 import type { QaTurnSources } from "./types.js";
 export interface QaProvenanceSnapshotStore {
     list(sessionId: string): readonly QaTurnSources[];
     put(bundle: QaTurnSources): void;
+    /**
+     * Drop one session's snapshots. The host store wires this to the session's
+     * disposal, which is what keeps the durable file from growing with every
+     * chat a long-lived server ever served.
+     */
+    drop(sessionId: string): void;
+}
+/**
+ * Retention bounds and their defaults live in a Node-free module: the resolved
+ * default config reaches the browser bundle, and this file does not.
+ */
+export { DEFAULT_QA_PROVENANCE_RETENTION, QA_PROVENANCE_RETENTION_LIMITS, } from "./retention.js";
+export type { QaProvenanceRetention } from "./retention.js";
+/** What one directory sweep did, for the maintenance command and the tests. */
+export interface QaProvenanceSweepResult {
+    readonly scanned: number;
+    readonly droppedByAge: number;
+    readonly droppedByCount: number;
 }
 /** Process-local store used by tests and explicit ephemeral deployments. */
 export declare class MemoryQaProvenanceSnapshotStore implements QaProvenanceSnapshotStore {
     private readonly sessions;
     list(sessionId: string): readonly QaTurnSources[];
     put(bundle: QaTurnSources): void;
+    drop(sessionId: string): void;
 }
-/** Default durable provenance path, deliberately outside Harness journals. */
-export declare function defaultQaProvenanceFilePath(): string;
-/** Atomically persists per-turn QA source snapshots in plugin-owned storage. */
+/** Default durable provenance directory, deliberately outside Harness journals. */
+export declare function defaultQaProvenanceDirectoryPath(): string;
+/** The pre-sharding monolith, migrated on first use and then left alone. */
+export declare function defaultLegacyProvenanceFilePath(): string;
+/**
+ * Durable provenance, one file per chat.
+ *
+ * The read API is per-session and nothing enumerates every chat, so a shard is
+ * exactly the unit a writer touches: a turn rewrites one chat's history rather
+ * than every chat's. Empty turns collapse to their numbers and each shard is
+ * bounded by `QaProvenanceRetention`, so neither a long chat nor a long-lived
+ * deployment can make a single write grow without limit.
+ *
+ * The store is the only writer of its directory, and no cache sits in front of
+ * it: every read goes to disk.
+ */
 export declare class FileQaProvenanceSnapshotStore implements QaProvenanceSnapshotStore {
-    private readonly filePath;
-    constructor(filePath?: string);
+    private readonly directoryPath;
+    private readonly retention;
+    private readonly legacyFilePath;
+    private migrated;
+    private lastSweepAt;
+    constructor(directoryPath?: string, retention?: () => QaProvenanceRetention, legacyFilePath?: string);
     list(sessionId: string): readonly QaTurnSources[];
     put(bundle: QaTurnSources): void;
-    private load;
-    private persist;
+    drop(sessionId: string): void;
+    /**
+     * Drop shards the retention policy no longer covers: untouched for
+     * `maxAgeDays`, then everything past the `maxSessions` most recent ones.
+     *
+     * `keep` names the chat whose shard must survive the sweep — a caller that
+     * swept right after writing it would otherwise be able to delete the very
+     * bundle it just stored.
+     */
+    sweep(keep?: string): QaProvenanceSweepResult;
+    /**
+     * Split the pre-sharding monolith into shards exactly once, then rename it
+     * out of the way. A shard that already exists wins the merge, so a retried
+     * migration cannot lose turns that arrived after the first attempt.
+     */
+    private migrateLegacyOnce;
+    private shardPath;
+    private readShard;
+    private writeShard;
+    private removeShard;
+    private maybeSweep;
 }
 //# sourceMappingURL=snapshot-store.d.ts.map

package/lib/types/questions.d.ts

@@ -68,6 +68,11 @@ export declare class QaQuestionGate {
      * parked request is authoritative: a label the question never offered is
      * dropped, and a free-text answer replaces the choice in a single-select
      * rather than accompanying it, so the model only ever reads a real answer.
+     *
+     * The payload arrives over the wire from the browser, so its shape is
+     * untrusted: a non-array, a non-object entry, or a non-array/non-string
+     * selection is folded into the refusal/skip semantics instead of crashing
+     * the gate with a TypeError.
      */
     answer(sessionId: string, requestId: string, answers: readonly QaQuestionAnswerItem[]): boolean;
     /** Close a request without answering it. */

package/lib/types/secure-session.d.ts

@@ -1,6 +1,7 @@
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { Context } from "@deepseek-ai/cordis";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import { type QaSessionFacts } from "./accounts/store.js";
 import type { QaResolvedSessionPolicy } from "./access/service.js";
 import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
 /**
@@ -9,7 +10,7 @@ import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
  * pair or throw the coarse `QaAttestationError`; see {@link QaAccounts}.
  */
 export interface QaAccountsGate {
-    enforceSessionAccess(token: string, sessionId: string): {
+    enforceSessionAccess(token: string, sessionId: string, facts?: QaSessionFacts): {
         readonly id: string;
     } | undefined;
     userWorkspace(userId: string, registeredWorkspacePath: string): string;
@@ -47,7 +48,17 @@ export declare class QaPolicyAdmission {
      */
     private readonly attested;
     private readonly workspaceAccess;
+    /**
+     * Every name reachable anywhere in one QA conversation, keyed by session id.
+     *
+     * The chat's agent and the agents delegated from it share one entry —
+     * children inherit it when their session is created — because the ceiling is
+     * a property of the conversation, not of one scope. See
+     * {@link qaCeilingDenial} for why a scoped restriction cannot express it.
+     */
+    private readonly ceilings;
     private readonly disposeWorkspaceGuard;
+    private readonly disposeCeilingGuard;
     constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger, accounts?: QaAccountsGate | undefined, 
     /**
      * Names the QA tool catalog attached to one agent after its activation
@@ -100,6 +111,21 @@ export declare class QaPolicyAdmission {
      * mismatch"), and the adoption and permission checks stay the gate.
      */
     private liveAgent;
+    /**
+     * The Host-registered facts of one session, for the accounts gate's bounded
+     * auto-claim. A session this process has not materialized (a chat of an
+     * earlier Host run, reached before its agent exists) yields no facts and
+     * keeps the historical unbounded claim.
+     */
+    private sessionFacts;
+    /**
+     * Account identity and ownership are checked before any policy work: an
+     * invalid token must not learn whether a session exists or how the
+     * deployment composes. Independent of lockdown — a deployment may gate
+     * users without pinning the policy, and the gate itself no-ops while
+     * accounts are disabled.
+     */
+    private accessOwner;
     secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
     /**
      * Mask one agent down to the policy's tool names, for the account-free path