@yadsh/dsh-qa-surface 0.7.4 → 0.9.0

package/lib/types/access/capability-catalog.d.ts

@@ -1,5 +1,6 @@
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { Context } from "@deepseek-ai/cordis";
+import type { ScopeKey } from "@deepseek-ai/dsh-scope";
 import type { SkillSummary } from "@deepseek-ai/dsh-skill";
 import type { QaCapabilityDescriptor, QaSkillDescriptor } from "../types.js";
 export interface CapabilityCatalogSnapshot {
@@ -19,10 +20,36 @@ export declare class QaCapabilityCatalog {
     private readonly additionalToolNames;
     /** Role ids used to report unknown subrole ids in skill metadata. */
     private readonly knownSubroles;
+    /**
+     * The viewing scope an administrator's catalog is read with, for callers
+     * that have no agent of their own. Skills and tools an agent preset mounts
+     * (a kit's skill catalog, the preset's tool family) live in that preset's
+     * scope, so a global-only read reported an almost empty catalog: the
+     * administrator could neither see nor grant what every chat mounts.
+     * Resolving the scope may compose the preset; a failure degrades to the
+     * global view instead of failing the page.
+     */
+    private readonly presetScope;
     constructor(ctx: Context, additionalToolNames?: () => readonly string[], 
     /** Role ids used to report unknown subrole ids in skill metadata. */
-    knownSubroles?: () => readonly string[]);
+    knownSubroles?: () => readonly string[], 
+    /**
+     * The viewing scope an administrator's catalog is read with, for callers
+     * that have no agent of their own. Skills and tools an agent preset mounts
+     * (a kit's skill catalog, the preset's tool family) live in that preset's
+     * scope, so a global-only read reported an almost empty catalog: the
+     * administrator could neither see nor grant what every chat mounts.
+     * Resolving the scope may compose the preset; a failure degrades to the
+     * global view instead of failing the page.
+     */
+    presetScope?: () => Promise<ScopeKey | undefined>);
     snapshot(agent?: Agent): Promise<CapabilityCatalogSnapshot>;
+    /**
+     * The scope an administrator's catalog is read with. A deployment that pins
+     * QA chats to an agent preset gets that preset's standing scope; without a
+     * pinned preset there is no scope to borrow, and the read stays global.
+     */
+    private resolvePresetScope;
     /**
      * Read `metadata.qa-surface` of every discovered skill.
      *

package/lib/types/access/role-repository.d.ts

@@ -1,11 +1,27 @@
 import type { QaAccessAuditEvent, QaCapabilityConfig, QaCapabilitySelection, QaSkillAssignmentOverride, QaSubrole } from "../types.js";
 export declare function defaultCapabilityFilePath(): string;
-/** Atomic, externally reloadable source of truth for roles and their audit. */
+/** The pre-SQLite policy file, imported once on first use. */
+export declare function defaultLegacyCapabilityFilePath(): string;
+/**
+ * Atomic, externally reloadable source of truth for roles and their audit.
+ *
+ * The policy is one row and a change appends one row beside it, so an edit
+ * writes what it changed instead of rewriting a growing document — the cost of
+ * an administrative change no longer depends on how long the deployment has
+ * been administering anything.
+ *
+ * Only the configuration is cached. An audit trail carries the full policy
+ * that preceded each change, so reading it is reserved for the callers that
+ * ask for it, and dropped whenever another process writes.
+ */
 export declare class QaRoleRepository {
     readonly filePath: string;
-    private file;
-    private fileStamp;
+    private readonly storage;
+    private config;
+    private auditCache;
+    private observedDataVersion;
     constructor(filePath?: string);
+    close(): void;
     snapshot(): QaCapabilityConfig;
     audit(): readonly QaAccessAuditEvent[];
     create(actorId: string, input: QaSubrole): QaSubrole;
@@ -16,7 +32,7 @@ export declare class QaRoleRepository {
      * Replace one skill's administrator overlay.
      *
      * An overlay with nothing left to declare is removed outright, so clearing a
-     * row in the administration surface leaves the file as if it was never set.
+     * row in the administration surface leaves the store as if it was never set.
      * @param actorId - the administrator performing the change.
      * @param input - the overlay as edited in the browser.
      * @returns every overlay in force after the change.
@@ -24,9 +40,24 @@ export declare class QaRoleRepository {
     updateSkillOverride(actorId: string, input: QaSkillAssignmentOverride): readonly QaSkillAssignmentOverride[];
     recordAssignment(actorId: string, targetId: string, before: unknown, after: unknown): void;
     private replace;
+    /** Append one change and trim the trail to its newest events. */
     private appendAudit;
-    private reload;
-    private load;
-    private persist;
+    private writeConfig;
+    private readConfig;
+    private readAudit;
+    private readDataVersion;
+    /**
+     * Re-read the policy when another process wrote it. The `qa-admin` surfaces
+     * and this store share one database, so a configuration an administrator
+     * just saved must be the one the next policy resolution sees.
+     */
+    private refresh;
+    /**
+     * Import a pre-SQLite `qa-capability-policies.json` exactly once, then rename
+     * it aside. A configuration the database already holds wins: a leftover file
+     * must not silently revert an administrator's policy.
+     */
+    importLegacyFile(legacyFilePath: string): void;
+    private assertImportArrived;
 }
 //# sourceMappingURL=role-repository.d.ts.map

package/lib/types/access/service.d.ts

@@ -1,9 +1,11 @@
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { Context } from "@deepseek-ai/cordis";
+import type { ScopeKey } from "@deepseek-ai/dsh-scope";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import type { QaAccounts } from "../accounts/store.js";
 import type { QaAgentToolGrants } from "../enforcement/tool-grants.js";
-import type { QaAccessAdminSnapshot, QaCapabilityConfig, QaCapabilityDescriptor, QaCapabilitySelection, QaCurrentAccess, QaEffectiveCapabilityPolicy, QaSessionAccess, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaAccessAdminSnapshot, QaCapabilityConfig, QaCapabilityDescriptor, QaCapabilitySelection, QaClaimResult, QaCurrentAccess, QaEffectiveCapabilityPolicy, QaSessionAccess, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaSessionLogReader } from "../admin/session-log.js";
 import { QaCapabilityCatalog, type CapabilityCatalogSnapshot } from "./capability-catalog.js";
 import { QaRoleRepository } from "./role-repository.js";
 export interface QaResolvedSessionPolicy {
@@ -21,16 +23,109 @@ export interface QaResolvedSessionPolicy {
 }
 /** Server-only orchestration of roles, assignments, discovery and snapshots. */
 export declare class QaAccessService {
+    private readonly ctx;
     private readonly options;
     readonly roles: QaRoleRepository;
     readonly catalog: QaCapabilityCatalog;
+    private lastOwnershipSweepAt;
+    /** The sweep in flight, so a burst of readers runs one listing, not ten. */
+    private ownershipSweep;
+    /**
+     * Sessions the Host has listed as delegated children of another session.
+     * The live registry answers for a child that is running right now; this
+     * cache answers for the ones that finished and were dismantled, which is the
+     * state a browser meets when it opens an old subagent transcript.
+     */
+    private readonly delegatedSessions;
+    private lastDelegatedSweepAt;
+    private delegatedSweep;
     constructor(ctx: Context, options: {
         readonly accounts: () => QaAccounts | undefined;
         readonly config: () => ResolvedQaSurfaceConfig;
         readonly logger: PluginLogger;
         readonly repository?: QaRoleRepository;
         readonly dynamicToolNames?: () => readonly string[];
+        /**
+         * The viewing scope an administrator's catalog is read with. Skills and
+         * tools a deployment mounts through an agent preset live in that
+         * preset's scope, so a global-only catalog left the operator unable to
+         * see — or grant — what every QA chat actually mounts.
+         */
+        readonly presetScope?: () => Promise<ScopeKey | undefined>;
+        /**
+         * Durable session listing, used to tell a chat from a delegated child
+         * across Host runs. Without it the lineage answer degrades to the live
+         * registry, which knows nothing about a session this process has not
+         * materialized — the sweep then reclaims nothing rather than guessing.
+         */
+        readonly sessionLog?: QaSessionLogReader;
+        /**
+         * Called with the ids of chats the Harness no longer knows, once their
+         * ownership records are reclaimed. The record is the auth boundary, not
+         * the whole of what the deployment kept about a chat: ratings, reviews
+         * and queue entries are keyed by conversation, and they outlive their
+         * chat unless the caller drops them here.
+         */
+        readonly onVanishedSessions?: (sessionIds: readonly string[]) => void;
     });
+    /**
+     * Whether the Host can prove this session is a delegated child: a subagent's
+     * session, which is an implementation detail of one answer and never a chat.
+     * Used to refuse one wherever conversations are listed or claimed.
+     */
+    isDelegatedChild(sessionId: string): boolean;
+    /**
+     * The Host-registered facts of one session, for the accounts store's
+     * bounded auto-claim. Absent facts (the session registry is unavailable,
+     * or this chat is not materialized here) keep the historical claim.
+     */
+    private sessionFacts;
+    /**
+     * Reclaim ownership records of chats the Harness no longer knows.
+     *
+     * Nothing else removes them: the browser's "delete chat" hides a chat in one
+     * browser, and a record outlives its session forever, so a year of QA traffic
+     * accumulates one row per chat ever created. The sweep is throttled, runs
+     * off the reservation path and off the review reads, and is skipped entirely
+     * when the Harness cannot say what exists — an unanswerable question is
+     * never a licence to delete an auth boundary.
+     *
+     * What exists is both halves of the Harness's own knowledge: the sessions
+     * this process has open and the ones its storage still holds. The live store
+     * alone would make a cold chat — one nobody has opened since the last
+     * restart — look deleted, and the sweep would reclaim records of chats that
+     * are merely quiet. A listing that cannot see stored sessions therefore
+     * reclaims nothing.
+     *
+     * @returns the sweep, for callers that want to await it (tests, and the
+     * review reads that must show the console what still exists).
+     */
+    sweepVanishedOwnership(): Promise<void>;
+    private runOwnershipSweep;
+    /**
+     * Migrate a browser's local chat index into server-side ownership.
+     *
+     * A delegated session is not a chat: claiming one would write exactly the
+     * ownership record the admission refuses to create and put a subagent's
+     * transcript in the account's chat list. Its ids are left out of the batch
+     * and reported, so a stale browser index cannot reintroduce the record.
+     */
+    claimSessions(token: string, sessionIds: readonly string[]): QaClaimResult;
+    /**
+     * Reclaim ownership records that point at delegated sessions, and remember
+     * which sessions are children while doing it.
+     *
+     * Records like this are residue of the paths that used to claim a session
+     * without knowing its lineage: each one keeps a subagent's transcript in the
+     * chat list of whoever opened it. Only positively identified children lose
+     * their record, so a listing that cannot be read reclaims nothing, and every
+     * other record stays the auth boundary it is.
+     *
+     * @returns the sweep, for callers that want to await it (tests).
+     */
+    reclaimDelegatedSessions(): Promise<void>;
+    /** Throttled, off the critical path, and never awaited by a request. */
+    private maybeSweepDelegatedSessions;
     current(token: string): QaCurrentAccess;
     session(token: string, sessionId: string): QaSessionAccess;
     reserveSession(token: string, sessionId: string, requestedSubrole: string | null, adminPreview: boolean): import("../types.js").QaAccountUserPublic;
@@ -47,9 +142,17 @@ export declare class QaAccessService {
     deleteSubrole(token: string, id: string, replacementId: string | null): void;
     updateCommon(token: string, input: QaCapabilitySelection): QaCapabilitySelection;
     updateAssignment(token: string, userId: string, input: QaUserAccess): QaUserAccess;
+    /** The accounts store, or the refusal this operation names. */
     private requireAccounts;
-    /** The activation diagnostic is runtime plumbing, not an administrator grant. */
-    private systemRequiredTools;
+    /**
+     * Tools every session resolves regardless of the role it runs under: the
+     * deployment's pinned allow-list plus the activation diagnostic.
+     *
+     * Readable outside the service because the administration surface reports a
+     * profile's effective capabilities next to the configured ones, and the
+     * pinned set is part of that answer whatever the profile says.
+     */
+    systemRequiredTools(): readonly string[];
     private requireAdmin;
 }
 export declare function validateCapabilityConfig(config: QaCapabilityConfig): QaCapabilityConfig;

package/lib/types/account-remotes.d.ts

@@ -1,6 +1,6 @@
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import { QaAccounts } from "./accounts/store.js";
-import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaClaimResult, QaOwnershipEntry, QaWhoamiResult, ResolvedQaSurfaceConfig } from "./types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaOwnershipEntry, QaWhoamiResult, ResolvedQaSurfaceConfig } from "./types.js";
 /**
  * Host-side bodies of the account remotes the `QaSurface` service exposes.
  * The `@Remote`-decorated signatures stay on the service class (typert code
@@ -23,9 +23,13 @@ export interface QaAccountRemotes {
     login(email: string, password: string): QaAccountSession;
     /** Identity probe; safe to call with an empty or expired token. */
     whoami(token: string): QaWhoamiResult;
-    /** Migrate a browser's local chat index into server-side ownership. */
-    claimSessions(token: string, sessionIds: readonly string[]): QaClaimResult;
-    /** The token user's owned session ids; the sidebar list authority. */
+    /**
+     * The token user's owned session ids; the sidebar list authority.
+     *
+     * Migrating a browser's local chat index is NOT here: it has to refuse a
+     * delegated session, which takes session lineage, and that lives in
+     * `QaAccessService.claimSessions` — one entry point, no path around it.
+     */
     ownedSessions(token: string): {
         readonly ids: readonly string[];
     };

package/lib/types/accounts/database.d.ts

@@ -0,0 +1,84 @@
+import { SqliteDatabase } from "@yadsh/dsh-plugin-kit/sqlite";
+import type { QaSkillActivationRecord } from "../types.js";
+import { type AccountsFile, type StoredOwnership, type StoredUser } from "./file.js";
+/** One ownership record as it is written, before it becomes a row. */
+export interface OwnershipWrite {
+    readonly sessionId: string;
+    readonly owner: StoredOwnership;
+}
+/**
+ * The deployment's accounts, as tables.
+ *
+ * The stores this replaces were one JSON document read, parsed and rewritten
+ * whole on every mutation — so a chat being opened rewrote every account and
+ * every chat the deployment had ever seen, and the cost of that write grew with
+ * the deployment's age. Here a mutation touches the row it changes: opening a
+ * chat inserts one ownership row, and the file's size stops being a per-turn
+ * cost.
+ *
+ * Cross-process freshness survives the change. The `qa-accounts` CLI writes the
+ * same database from a second process, so the in-memory model is invalidated by
+ * `PRAGMA data_version`, which SQLite bumps exactly when *another* connection
+ * commits — the same guarantee the previous mtime-and-size stamp provided, with
+ * no file read to notice it.
+ */
+export declare class QaAccountsDatabase {
+    readonly filePath: string;
+    readonly storage: SqliteDatabase;
+    private observedDataVersion;
+    constructor(filePath: string);
+    /** The token secret, creating one for a database that has none yet. */
+    get secret(): string;
+    /** True while the in-memory model a caller holds is still current. */
+    get unchangedSinceLoad(): boolean;
+    /** Take the current data version as the baseline a caller's model reflects. */
+    markLoaded(): void;
+    /** Every account, ownership record and skill activation, in one read. */
+    loadAll(): AccountsFile;
+    /** Append one account, preserving the order accounts are listed in. */
+    insertUser(user: StoredUser): void;
+    /** Replace one account's row in place. */
+    updateUser(user: StoredUser): void;
+    /** Record a successful sign-in without rewriting the account. */
+    touchLogin(userId: string, at: string): void;
+    /** Claim one chat for an account. */
+    insertOwnership(sessionId: string, owner: StoredOwnership): void;
+    /** Claim many chats at once, which is how a browser's index migrates. */
+    insertOwnershipMany(rows: readonly OwnershipWrite[]): void;
+    /** Rewrite an existing chat's pinned role, preview flag or snapshot. */
+    updateOwnership(sessionId: string, owner: StoredOwnership): void;
+    /** Forget chats: a rolled-back reservation, or a chat the Harness lost. */
+    deleteOwnership(sessionIds: readonly string[]): void;
+    /**
+     * Append one skill activation and keep the newest `limit` of them. The list
+     * is bounded because a long session may activate skills many times, and the
+     * oldest entries stop being interesting long before the store does.
+     */
+    appendSkillActivation(sessionId: string, entry: QaSkillActivationRecord, limit: number): readonly QaSkillActivationRecord[];
+    /**
+     * Import a pre-SQLite `qa-accounts.json` exactly once, then rename it away.
+     *
+     * The import is verified *inside* the transaction and before the file is
+     * retired — every account and every ownership record must have arrived, and
+     * the token secret must be the one the file carried — because a silent
+     * partial import would either lock accounts out or hand a chat to the wrong
+     * owner. A database that already holds accounts is never overwritten by a
+     * leftover file.
+     */
+    importLegacyFile(legacyFilePath: string | undefined): AccountsFile | undefined;
+    private assertImportArrived;
+    close(): void;
+    private hasAccounts;
+    private readDataVersion;
+    private ensureSecret;
+    /** The account columns, in the order both write statements bind them. */
+    private accountColumns;
+    private writeUser;
+    private writeOwnership;
+    /** One row per distinct policy; the digest is the policy's content. */
+    private writeSnapshot;
+    /** Drop snapshots no chat refers to any more, so the table cannot drift up. */
+    private gcSnapshots;
+    private parseLegacyFile;
+}
+//# sourceMappingURL=database.d.ts.map

package/lib/types/accounts/errors.d.ts

@@ -3,7 +3,13 @@
  * marker pattern the attestation path established; the browser maps them to
  * audience-safe copy and the precise cause stays in the Host logs.
  */
-export type QaAccountsErrorReason = "auth-required" | "admin-required" | "forbidden" | "invalid-credentials" | "account-disabled" | "email-taken" | "invalid-email" | "invalid-display-name" | "invalid-profile" | "profile-disabled" | "invalid-starters" | "starters-disabled" | "invalid-role" | "weak-password" | "registration-disabled" | "rate-limited" | "session-owned-elsewhere";
+export type QaAccountsErrorReason = "auth-required" | "admin-required" | "forbidden" | "invalid-credentials" | "account-disabled" | "email-taken" | "invalid-email" | "invalid-display-name" | "invalid-profile" | "profile-disabled" | "invalid-starters" | "starters-disabled" | "invalid-role" | "weak-password" | "registration-disabled" | "rate-limited" | "session-owned-elsewhere"
+/** The conversation a deletion names is not one this deployment knows. */
+ | "conversation-unknown"
+/** The Harness still holds the conversation open, so its log would come back. */
+ | "conversation-live"
+/** This deployment cannot remove stored conversations at all. */
+ | "conversation-not-removable";
 export declare class QaAccountsError extends Error {
     readonly reason: QaAccountsErrorReason;
     constructor(reason: QaAccountsErrorReason, message: string);

package/lib/types/accounts/file.d.ts

@@ -1,13 +1,12 @@
-import type { Stats } from "node:fs";
 import type { QaAccountRole, QaEffectiveCapabilityPolicy, QaSkillActivationRecord, QaUserAccess } from "../types.js";
-/** One account's self-declared profile as it rests in the accounts file. */
+/** One account's self-declared profile as it rests in the accounts store. */
 export interface StoredProfile {
     fullName?: string;
     identities?: Record<string, string>;
     instructions?: string;
     updatedAt?: string;
 }
-/** One account's starter buttons as they rest in the accounts file. */
+/** One account's starter buttons as they rest in the accounts store. */
 export interface StoredStarters {
     items?: {
         label?: string;
@@ -53,51 +52,30 @@ export interface StoredOwnership {
     /** Skill activations in order: what the model gained, and when it gained it. */
     readonly skillActivations?: readonly QaSkillActivationRecord[];
 }
+/**
+ * The accounts model as the store holds it in memory, hydrated from the
+ * database and invalidated by `PRAGMA data_version` when another process
+ * writes. Snapshots appear inline here: the storage layer is what keeps one
+ * copy per distinct policy, not the callers.
+ */
 export interface AccountsFile {
     readonly version: 1;
-    /** HMAC key for account tokens; rotated on password change by rewriting it. */
+    /** HMAC key for account tokens; created on first use. */
     readonly secret: string;
     readonly users: StoredUser[];
     readonly ownership: Record<string, StoredOwnership>;
 }
-/** mtime+size pair identifying one on-disk version of the accounts file. */
-export interface FileStamp {
-    readonly mtimeMs: number;
-    readonly size: number;
-}
-/**
- * Where the last-seen stamp lives. Load and persist keep it current in place,
- * so a caller holds one mutable ref instead of threading the stamp through
- * every read-modify-write.
- */
-export interface FileStampRef {
-    current: FileStamp;
-}
-/** A stamp no real file can match, so the first load always reads the disk. */
-export declare function createFileStampRef(): FileStampRef;
-export declare function stampOf(stat: Stats): FileStamp;
-/** The accounts file lives next to the DSH home the launcher exports. */
+/** The accounts database lives next to the DSH home the launcher exports. */
 export declare function defaultAccountsFilePath(): string;
 /**
- * Read the accounts file, or create it on first run with a fresh token
- * secret. The stamp ref is left pointing at the version just read.
- */
-export declare function loadAccountsFile(filePath: string, stamp: FileStampRef): AccountsFile;
-/**
- * Persist the accounts file atomically (temp file + rename) and leave the
- * stamp ref pointing at the freshly written version.
+ * Where the pre-SQLite accounts file lived. It is imported on first use and
+ * then renamed aside, so a deployment upgrades without re-registering anyone.
  */
-export declare function persistAccountsFile(filePath: string, file: AccountsFile, stamp: FileStampRef): void;
+export declare function defaultLegacyAccountsFilePath(): string;
 /**
- * The qa-accounts CLI runs in its own process against the same file. Re-read
- * it whenever it changed on disk, before every read or read-modify-write:
- * without this a running Host would keep honoring tokens the CLI revoked
- * and its next save would resurrect the CLI's change from a stale snapshot.
- * One file, one writer at a time remains the deployment's discipline; LAN
- * scale keeps the stat per operation trivial.
- *
- * Returns the freshly loaded file, or undefined when the caller should keep
- * serving its in-memory state.
+ * A stable digest of one capability policy, so two chats admitted under the
+ * same policy share a stored snapshot. Keys are sorted because object key order
+ * is an artefact of construction, not part of the policy.
  */
-export declare function reloadAccountsFileIfChanged(filePath: string, stamp: FileStampRef): AccountsFile | undefined;
+export declare function snapshotDigest(value: unknown): string;
 //# sourceMappingURL=file.d.ts.map

package/lib/types/accounts/store.d.ts

@@ -1,5 +1,5 @@
 import type { QaAccountIdentityField, QaAccountProfile, QaAccountProfileInput, QaAccountRole, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaAccessUser, QaAdminAccountRow, QaClaimResult, QaEffectiveCapabilityPolicy, QaOwnershipEntry, QaSkillActivationRecord, QaUserAccess, QaWhoamiResult } from "../types.js";
-import type { StoredOwnership, StoredUser } from "./file.js";
+import { type StoredOwnership, type StoredUser } from "./file.js";
 export { QaAccountsError } from "./errors.js";
 export type { QaAccountsErrorReason } from "./errors.js";
 export { defaultAccountsFilePath } from "./file.js";
@@ -15,18 +15,45 @@ export interface QaAccountsOptions {
      * omitting the list (the operator CLI) checks the key shape alone.
      */
     readonly identityFields?: readonly QaAccountIdentityField[];
+    /**
+     * Where a pre-SQLite accounts file may still live. Defaults to the `.json`
+     * sibling of the database; pass an explicit path when a deployment kept it
+     * somewhere else.
+     */
+    readonly legacyFilePath?: string;
 }
 /**
- * Host authority for QA accounts: the file-backed user list, the session
- * ownership map and the HMAC account tokens. All mutations are synchronous
- * and persisted atomically (temp file + rename); LAN scale keeps this trivial.
+ * What the caller knows about the live session it is gating. The store is
+ * file-backed and session-agnostic; the Host supplies these facts so the
+ * first-come auto-claim can refuse what it must not attach silently. Absent
+ * facts (the operator CLI, a session the Host has not materialized) keep the
+ * historical unbounded claim.
+ */
+export interface QaSessionFacts {
+    /** Epoch ms the Host recorded as the session's creation. */
+    readonly createdAt?: number;
+    /** True when the session is a delegated child of another chat. */
+    readonly hasParent?: boolean;
+}
+/**
+ * How long an unowned session stays claimable at access time. Mirrors the
+ * admission bootstrap window: a session older than this has either user
+ * history or a settled composition, so silently attaching it to whoever
+ * asked first would hand over a conversation nobody assigned to them.
+ * Owners are unaffected — their claim already exists in the file.
+ */
+export declare const QA_SESSION_CLAIM_WINDOW_MS = 120000;
+/**
+ * Host authority for QA accounts: the account list, the session ownership map
+ * and the HMAC account tokens. Mutations are synchronous and land as the rows
+ * they change, in one transaction each.
  *
- * The class is the facade: token mechanics live in token.ts, the file format
- * and its atomic persistence plus the external-change probe in file.ts, and
- * the credential rules shared by registration and the operator CLI in
- * credentials.ts.
+ * The class is the facade: token mechanics live in token.ts, the tables and the
+ * legacy import in database.ts, and the credential rules shared by registration
+ * and the operator CLI in credentials.ts.
  */
 export declare class QaAccounts {
+    /** The database this store reads and writes. */
     readonly filePath: string;
     private file;
     private readonly authAttempts;
@@ -35,18 +62,26 @@ export declare class QaAccounts {
     private readonly allowRegistration;
     /** Character cap on a stored profile's agent guidance. */
     private readonly instructionsMaxLength;
-    /** Declared handle fields; undefined lets an operator write any shape-valid key. */
-    private readonly identityFields;
-    /** mtime+size of the file as of the last load; the external-change probe. */
-    private readonly fileStamp;
-    constructor(filePath: string | undefined, options: QaAccountsOptions);
+    /** Whether a deployment declares which identity handles an account may hold. */
+    readonly identityFields: readonly QaAccountIdentityField[] | undefined;
     /**
-     * Re-read the accounts file when it changed on disk, before every read or
-     * read-modify-write. The probe itself and its cross-process rationale live
-     * with the file layer (reloadAccountsFileIfChanged).
+     * The store's tables. Every mutation writes the rows it changes and the
+     * in-memory model is refreshed only when another process wrote — which is
+     * what keeps the cost of opening a chat independent of the deployment's age.
+     */
+    private readonly database;
+    constructor(configuredPath: string | undefined, options: QaAccountsOptions);
+    /** Close the underlying database; the store is unusable afterwards. */
+    close(): void;
+    /**
+     * Re-read the model when another process wrote the database, before every
+     * read or read-modify-write. The `qa-accounts` CLI runs in its own process
+     * against the same file, so without this a running Host would keep honoring
+     * tokens the CLI revoked. SQLite bumps `PRAGMA data_version` exactly when a
+     * *different* connection commits, which is the probe the previous
+     * mtime-and-size stamp of the JSON file used to provide.
      */
     private reloadIfChanged;
-    private save;
     private pruneAuthAttempts;
     private assertAuthBudget;
     private userByEmail;
@@ -64,8 +99,15 @@ export declare class QaAccounts {
      * Ownership gate for one session: claim unowned sessions for the requesting
      * user (first come, first served — the pre-accounts migration path), refuse
      * foreign sessions unless the caller administers the deployment.
+     *
+     * The auto-claim is bounded when the caller can describe the live session
+     * ({@link QaSessionFacts}): a delegated subagent session is never claimed,
+     * and a session past the freshness window is refused instead of silently
+     * attached to whoever opened it first. Both refusals keep the file intact —
+     * the session stays unowned, so the operator CLI or a deliberate future
+     * claim can still resolve it.
      */
-    ensureSessionAccess(token: string, sessionId: string): QaAccountUserPublic;
+    ensureSessionAccess(token: string, sessionId: string, facts?: QaSessionFacts): QaAccountUserPublic;
     /**
      * Atomically reserve a Host-generated session id for the token user before
      * the Session exists. Browser callers therefore never get a race window in
@@ -81,6 +123,48 @@ export declare class QaAccounts {
     claimSessions(token: string, sessionIds: readonly string[]): QaClaimResult;
     /** Session ids owned by the token's user, most recently claimed first. */
     ownedSessionIds(token: string): readonly string[];
+    /**
+     * Drop ownership records of sessions that are not chats at all.
+     *
+     * A delegated subagent session is an implementation detail of one answer:
+     * nothing legitimately owns one, so no grace period applies and every named
+     * id loses its record. Only ids the caller positively identified are
+     * touched — a record is an auth boundary, and an id that merely looks odd
+     * keeps its owner. What this reclaims is residue: records written before the
+     * claim and attestation paths learned to refuse a delegated child, each one
+     * keeping a subagent's session in some account's chat list.
+     *
+     * @param sessionIds - the ids the caller identified as delegated children.
+     * @returns the session ids whose records were dropped.
+     */
+    pruneDelegatedOwnership(sessionIds: ReadonlySet<string>): readonly string[];
+    /**
+     * Drop the ownership records of the named sessions, whatever their lineage.
+     *
+     * This is the record half of a deletion: the caller has already established
+     * that these sessions are gone (or is removing them as part of the same
+     * act), so the auth boundary goes with them. Nothing here decides anything —
+     * the sweeps above own the judgments, and both end in this.
+     *
+     * @param sessionIds - the ids whose records are dropped.
+     * @returns the session ids whose records were actually there.
+     */
+    forgetSessions(sessionIds: ReadonlySet<string>): readonly string[];
+    /**
+     * Drop ownership records for chats the Harness no longer knows.
+     *
+     * An ownership record is a chat's auth boundary — `ensureSessionAccess`
+     * claims an unowned session for whoever asks first — so a record is removed
+     * only when the caller reports the session gone *and* the claim is older
+     * than `graceHours`. A reservation racing its own creation therefore keeps
+     * its owner, and a live chat never becomes claimable by someone else. What
+     * this reclaims is the residue of deleted chats, which nothing else removes.
+     *
+     * @param isLive - whether the Harness still knows this session.
+     * @param graceHours - youngest claim the sweep may touch.
+     * @returns the session ids whose records were dropped.
+     */
+    pruneVanishedSessions(isLive: (sessionId: string) => boolean, graceHours: number): readonly string[];
     /**
      * Every ownership entry with the owner's display name resolved at read
      * time, oldest claim first. Admin-only: this is the cross-user view the
@@ -131,7 +215,14 @@ export declare class QaAccounts {
         readonly adminPreview?: boolean;
         readonly capabilitySnapshot?: QaEffectiveCapabilityPolicy;
     }[];
-    /** Replace one account's authorization role, addressed by stable id. */
+    /**
+     * Replace one account's authorization role, addressed by stable id.
+     *
+     * The union is re-checked here even though the type names it: the value
+     * arrives from the browser's admin console over the wire, and a role outside
+     * the union would be stored as-is and then crash every later permission
+     * check (`PERMISSIONS[role]` lookup) for that account.
+     */
     setAccessRole(userId: string, role: QaAccountRole): QaAccountUserPublic;
     /**
      * Disable or enable one account by id. Same semantics as the operator