@indigoai-us/hq-cloud 6.15.0 → 6.15.1

package/src/vault-client.ts

@@ -1,1694 +0,0 @@
-/**
- * VaultClient — typed SDK for vault-service membership operations (VLT-7 US-001).
- *
- * Wraps vault-service HTTP API with shared auth, retry, and typed errors.
- * Colocated with hq-cloud so /invite, /promote, /accept and future commands
- * share one client instead of each rolling its own HTTP layer.
- */
-
-import type { ClientInfo, VaultServiceConfig } from "./types.js";
-import { buildClientHeaders } from "./client-info.js";
-import { emitCloudTelemetry } from "./telemetry-events.js";
-import { z } from "zod";
-import { accessTokenFingerprint } from "./cognito-auth.js";
-
-// ---------------------------------------------------------------------------
-// Error classes
-// ---------------------------------------------------------------------------
-
-export class VaultClientError extends Error {
-  constructor(
-    message: string,
-    public readonly statusCode: number,
-    public readonly body?: string,
-  ) {
-    super(message);
-    this.name = "VaultClientError";
-  }
-}
-
-export class VaultAuthError extends VaultClientError {
-  constructor(
-    message = "Authentication failed — session expired or invalid",
-    public readonly tokenFingerprint?: string,
-  ) {
-    super(message, 401);
-    this.name = "VaultAuthError";
-  }
-}
-
-export class VaultPermissionDeniedError extends VaultClientError {
-  constructor(message = "Permission denied — admin role required") {
-    super(message, 403);
-    this.name = "VaultPermissionDeniedError";
-  }
-}
-
-export class VaultNotFoundError extends VaultClientError {
-  constructor(message = "Resource not found") {
-    super(message, 404);
-    this.name = "VaultNotFoundError";
-  }
-}
-
-export class VaultConflictError extends VaultClientError {
-  constructor(message = "Conflict — resource already exists or was already accepted") {
-    super(message, 409);
-    this.name = "VaultConflictError";
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export type MembershipRole = "owner" | "admin" | "member" | "guest";
-export type MembershipStatus = "pending" | "active" | "revoked";
-
-export interface Membership {
-  membershipKey: string;
-  personUid: string;
-  companyUid: string;
-  role: MembershipRole;
-  status: MembershipStatus;
-  allowedPrefixes?: string[];
-  inviteToken?: string;
-  invitedBy: string;
-  invitedAt: string;
-  acceptedAt?: string;
-  revokedAt?: string;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface CreateInviteInput {
-  personUid?: string;
-  inviteeEmail?: string;
-  companyUid: string;
-  role: MembershipRole;
-  allowedPrefixes?: string[];
-  invitedBy: string;
-}
-
-export interface CreateInviteResult {
-  membership: Membership;
-  inviteToken: string;
-}
-
-export interface AcceptInviteResult {
-  membership: Membership;
-}
-
-export interface UpdateRoleInput {
-  membershipKey: string;
-  newRole: MembershipRole;
-  allowedPrefixes?: string[];
-  updaterUid: string;
-  /** Required so the server can authorize the caller as admin/owner of the company. */
-  companyUid: string;
-}
-
-export interface EntityInfo {
-  uid: string;
-  slug: string;
-  type: string;
-  /** Human-readable display name — surfaced in UIs that list companies. */
-  name?: string;
-  bucketName?: string;
-  status: string;
-  createdAt: string;
-}
-
-/**
- * Pick the caller's OWN entity for the `--personal` slot when the runner is an
- * agent machine identity (username `machine-agt_*`, idToken
- * `custom:entityType=agent` / `custom:entityUid=agt_*`).
- *
- * The person-only `pickCanonicalPersonEntity` filters `type === "person"`, so
- * an agent's own entity (`type: "agent"`) is dropped and `--personal` for an
- * agent emits `setup-needed` — never reaching the STS vend / S3 read (the
- * US-004 hard-gate finding). This selector resolves the agent's own entity by
- * matching `selfUid` (the `custom:entityUid` claim) against the self-listing
- * the agent sees, so the personal slot resolves to `hq-vault-agt-<uid>`.
- *
- * Returns null when no entity matches the claimed self-uid (the caller then
- * falls back to the person-only pick / `setup-needed`, exactly as before).
- */
-export function pickAgentSelfEntity(
-  list: EntityInfo[],
-  selfUid: string,
-): EntityInfo | null {
-  if (!selfUid) return null;
-  const own = list.find((e) => e.uid === selfUid && e.type === "agent");
-  return own ?? null;
-}
-
-export function pickCanonicalPersonEntity(
-  list: EntityInfo[],
-): EntityInfo | null {
-  // Defensive filter — callers today pass `entity.listByType("person")` so this is
-  // a no-op, but a future caller passing a mixed list would otherwise silently get
-  // back a non-person entity.
-  const persons = list.filter((e) => e.type === "person");
-  if (persons.length === 0) return null;
-  const sorted = [...persons].sort((a, b) => {
-    const ac = (a.createdAt as string | undefined) ?? "";
-    const bc = (b.createdAt as string | undefined) ?? "";
-    if (ac !== bc) return ac < bc ? -1 : 1;
-    return a.uid < b.uid ? -1 : 1;
-  });
-  return sorted[0];
-}
-
-export interface PendingInviteByEmail {
-  membershipKey: string;
-  companyUid: string;
-  role: MembershipRole;
-  inviteToken?: string;
-  invitedBy: string;
-  invitedAt: string;
-}
-
-export interface CreateEntityInput {
-  type: "person" | "company";
-  slug: string;
-  name: string;
-  email?: string;
-  ownerUid?: string;
-}
-
-export interface CreateEntityResult {
-  entity: EntityInfo;
-}
-
-// -- Browse-vs-sync types (US-002, US-003, US-004) -----------------------
-
-/**
- * Source kind for an explicit per-company file-ACL grant. Mirrors the
- * server enum in hq-pro `vault-service/handlers/files-grants.ts`.
- *
- * `'open'` collapses two server-side shapes that are indistinguishable to
- * the caller — the legacy `acl.open === true` floor and an explicit
- * `granteeType: 'company-wide'` row. Both mean "every active member of
- * this company sees this prefix".
- */
-export type GrantSource = "creator" | "person" | "email" | "group" | "open";
-
-/** Permission level surfaced on a grant row. Matches `AclPermission`. */
-export type GrantPermission = "read" | "write" | "admin";
-
-/**
- * One row in the response of `GET /v1/files/grants?company={uid}`.
- *
- * Role-bypass (owner/admin) entries are intentionally excluded by the
- * server — this is the caller's EXPLICIT grant graph, not the full set
- * of prefixes they can touch by virtue of role.
- */
-export interface ExplicitGrant {
-  companyUid: string;
-  path: string;
-  permission: GrantPermission;
-  source: GrantSource;
-}
-
-/** Presign operation: download / upload / delete. */
-export type PresignOp = "get" | "put" | "delete";
-
-/** One object's metadata as returned by GET /v1/files/list. */
-export interface VaultListedObject {
-  key: string;
-  size: number;
-  lastModified: string | null;
-  /**
-   * S3 ETag (quotes stripped) or null. Load-bearing for sync change-
-   * detection: the client stores it as remote-content identity and compares
-   * it to decide pull/skip/delete-safety — the same role `RemoteFile.etag`
-   * plays on the STS path. Mirrors the hq-pro `files/list` field (PR #269).
-   */
-  etag: string | null;
-  permission: GrantPermission;
-}
-
-/** One key in a batch presign request. */
-export interface PresignKeyInput {
-  key: string;
-  op?: PresignOp;
-  contentType?: string;
-  /** Custom object metadata to sign into a PUT (x-amz-meta-*). */
-  metadata?: Record<string, string>;
-  /**
-   * Conditional-write fence for a PUT presign (S3 conditional writes). When
-   * the server supports it (hq-pro files-presign follow-up), it signs
-   * `If-Match: "<etag>"` / `If-None-Match: *` into the URL and echoes the
-   * header in the result row's `headers` for verbatim replay. Servers that
-   * predate the field ignore it — the PUT stays unconditional, never broken.
-   */
-  ifMatch?: string;
-  ifNoneMatch?: "*";
-}
-
-/** One result row from POST /v1/files/presign (per key, request order). */
-export interface PresignResultRow {
-  key: string;
-  op: PresignOp;
-  /** Present on success: the presigned URL. */
-  url?: string;
-  /**
-   * Present on a PUT success: the EXACT headers to send on the PUT so the
-   * SigV4 signature matches (Content-Type, SSE-KMS, every x-amz-meta-*).
-   */
-  headers?: Record<string, string>;
-  expiresIn?: number;
-  expiresAt?: string;
-  /** Present on per-key denial/validation failure. */
-  error?: string;
-  code?: string;
-}
-
-/**
- * Effective sync mode for a single membership. Mirrors the server's
- * resolved view from `GET /v1/memberships/{id}/sync-config`:
- *
- *   - `shared` — sync only `shared/` and the caller's `personal/` prefix
- *   - `all`    — sync every prefix the caller has read access to
- *   - `custom` — sync the explicit `customPaths` list (server validates)
- *
- * `isDefault: true` means no row exists in DDB and the server is
- * falling back to its built-in default (currently `'all'` for legacy
- * memberships created pre-US-003). When `true`, `updatedAt`/`updatedBy`
- * are absent because there's no row to attribute.
- */
-export type SyncMode = "shared" | "all" | "custom";
-
-export interface MembershipSyncConfig {
-  membershipId: string;
-  syncMode: SyncMode;
-  customPaths?: string[];
-  /**
-   * `true` when the server returned the built-in default because no
-   * sync-config row exists for this membership. PUT always returns
-   * `false` — writing the row is what makes it non-default.
-   */
-  isDefault: boolean;
-  /** Present only when a sync-config row exists (i.e. `isDefault: false`). */
-  updatedAt?: string;
-  /** Present only when a sync-config row exists. PersonUid of the writer. */
-  updatedBy?: string;
-}
-
-/**
- * Input shape for {@link VaultClient.setMembershipSyncConfig}. The server
- * validates the combination — `customPaths` is required when `syncMode`
- * is `'custom'` and rejected otherwise.
- */
-export interface SetMembershipSyncConfigInput {
-  syncMode: SyncMode;
-  customPaths?: string[];
-}
-
-// -- Raw vend (legacy POST /vend, purpose-aware after US-009) -------------
-
-/**
- * Why the caller is requesting STS-scoped credentials. Mirrors the
- * hq-pro vault-service enum (`src/vault-service/policy-builder.ts`).
- *
- *   - `'sync'`   — background machine sync. Role-bypass MUST NOT widen
- *     the path set: credentials are scoped to exactly the requested
- *     paths (which the sync engine has already narrowed via US-005).
- *   - `'browse'` — interactive exploration (hq-console Explore,
- *     `hq files browse`, admin spelunking). Admin/owner role-bypass
- *     APPLIES — the caller may receive credentials covering paths
- *     beyond their explicit ACL grants.
- *
- * The server defaults missing/empty to `'sync'` (the safer choice).
- * The client doesn't mirror that default — every caller should be
- * explicit about its intent so audit rows are accurate.
- */
-export type VendPurpose = "sync" | "browse";
-
-export type VaultOperation = "read-only" | "read-write" | "staged-write";
-
-/**
- * Input shape for {@link VaultClient.vend}. The server validates
- * combinations — e.g. `purpose: 'sync'` rejects bucket-wide `'*'` paths
- * as defense in depth against role-bypass widening on the sync path.
- */
-export interface VendInput {
-  paths: string[];
-  operations: VaultOperation;
-  /** Why these credentials are being vended. See {@link VendPurpose}. */
-  purpose: VendPurpose;
-  /** STS session lifetime in seconds. Server default is 900 (15m). */
-  duration?: number;
-}
-
-export interface VendCredentials {
-  accessKeyId: string;
-  secretAccessKey: string;
-  sessionToken: string;
-  /** ISO-8601 STS-native expiration string. */
-  expiration: string;
-}
-
-export interface VendResult {
-  credentials: VendCredentials;
-  /** Echo of the server-resolved paths after ACL intersection. */
-  paths: string[];
-  operations: VaultOperation;
-  /** Echo of the effective purpose (server-defaulted to 'sync' if absent). */
-  purpose: VendPurpose;
-  /**
-   * Size of the rendered IAM session policy in characters. Lets the
-   * caller detect when it's nearing the 2048-char IAM ceiling so it can
-   * fan out across multiple vends or shrink its path set.
-   */
-  policySize: number;
-  requestId?: string;
-}
-
-// -- STS child vending (VLT-8) --------------------------------------------
-
-export type TaskAction = "read" | "write";
-
-export interface TaskScope {
-  /** S3 key prefixes the child may access (e.g. ["drafts/"]). */
-  allowedPrefixes: string[];
-  /** Defaults to ["read", "write"]. Use ["read"] for read-only children. */
-  allowedActions?: TaskAction[];
-}
-
-export interface VendChildInput {
-  companyUid: string;
-  /** ULID generated by the parent task. Flows into STS session name for audit. */
-  taskId: string;
-  /** Short human-readable description (<256 chars). Logged alongside the session. */
-  taskDescription: string;
-  taskScope: TaskScope;
-  /**
-   * Child session duration in seconds. Defaults to 900 on the server — AWS STS
-   * AssumeRole enforces a 900s floor. The task-scoped policy is the security
-   * boundary, not the duration.
-   */
-  durationSeconds?: number;
-}
-
-export interface StsChildCredentials {
-  accessKeyId: string;
-  secretAccessKey: string;
-  sessionToken: string;
-}
-
-export interface VendChildResult {
-  credentials: StsChildCredentials;
-  /** STS session name: `${parentPersonUid}--task--${taskId}` — used in CloudTrail.
-   *  (Dash-separated because AWS STS `roleSessionName` disallows colons.) */
-  sessionName: string;
-  /** ISO-8601 session expiration. */
-  expiresAt: string;
-}
-
-// ---------------------------------------------------------------------------
-// Usage telemetry (hq-pro `/v1/usage` + `/v1/usage/opt-in`)
-// ---------------------------------------------------------------------------
-
-export interface TelemetryOptInResponse {
-  enabled: boolean;
-  updatedAt: string | null;
-  /**
-   * `true` when the person row carries NO `telemetryOptIn` attribute — i.e. the
-   * consent question has never been answered server-side. Distinct from
-   * `enabled: false`, which is a deliberate opt-OUT.
-   *
-   * Optional because older servers omit it entirely. Absent is treated as
-   * `false`, so a client talking to one behaves exactly as before — no
-   * self-heal, no surprise writes.
-   */
-  unset?: boolean;
-  /**
-   * The `prs_*` uid this answer belongs to — i.e. the authenticated caller.
-   *
-   * Needed because the local consent cache is a per-MACHINE file: if two people
-   * sign in under the same OS user it holds whoever answered last. A client
-   * must not replay it for a different account. Optional (older servers omit
-   * it), and absence means the replay cannot be proven safe, so it is skipped.
-   */
-  personUid?: string;
-}
-
-export interface UsageBatch {
-  machineId: string;
-  installerVersion: string;
-  /**
-   * Sanitized event rows. Each row is a plain object containing only the
-   * fields in the server's KEEP allowlist (sessionId, timestamp, uuid, cwd,
-   * gitBranch, userType, model, inputTokens, outputTokens,
-   * cacheCreationInputTokens, cacheReadInputTokens, and the optional
-   * companyUid edge-attribution field — US-002). Any extra field is
-   * rejected by hq-pro with `unexpected-event-field`, so the sanitizer in
-   * `./telemetry.ts` is the only thing allowed to produce these.
-   */
-  events: Array<Record<string, unknown>>;
-}
-
-export interface UsageIngestResult {
-  ok: boolean;
-  written: number;
-  skipped: Array<{ index: number; code: string; error: string }>;
-}
-
-// ---------------------------------------------------------------------------
-// Cloud action telemetry (hq-pro `/v1/telemetry/events`)
-// ---------------------------------------------------------------------------
-
-export interface RawTelemetryEventInput {
-  eventName: string;
-  app: "hq-cloud";
-  source: string;
-  occurredAt: string;
-  companyUid?: string;
-  agentUid?: string;
-  sessionId?: string;
-  schemaVersion?: 1;
-  properties?: Record<string, unknown>;
-}
-
-export interface TelemetryEventsBatch {
-  /**
-   * Action events emitted by sync/CLI surfaces. `personUid` MUST NOT appear in
-   * either the batch or any event — hq-pro resolves the caller server-side from
-   * the Cognito JWT and rejects client-supplied person identifiers.
-   */
-  events: RawTelemetryEventInput[];
-}
-
-/**
- * Normalized response shape for `POST /v1/telemetry/events`.
- *
- * hq-pro response contract v1 uses the established ingest fields (`ok`,
- * `written`, `skipped`). The decoder also accepts the briefly deployed
- * `{ accepted, deduped }` shape so clients remain compatible while the server
- * rollout catches up.
- */
-export type TelemetryEventsIngestResult = UsageIngestResult;
-
-// ---------------------------------------------------------------------------
-// Skill-invocation telemetry (hq-pro `/v1/skill-invocations`)
-// ---------------------------------------------------------------------------
-
-export interface SkillInvocationBatch {
-  machineId: string;
-  installerVersion: string;
-  /**
-   * Skill-invocation event rows. Each row contains only the fields in the
-   * server's KEEP allowlist (skill, source, sessionId, timestamp, uuid, cwd,
-   * hasArgs, the optional companyUid edge-attribution field — US-002, and the
-   * optional skillVersion content-hash marker — US-015). Raw argument text is
-   * never included — see the privacy note in `./skill-telemetry.ts`. Any extra
-   * field is rejected by hq-pro with `unexpected-event-field`, so the extractor
-   * in `./skill-telemetry.ts` is the only thing allowed to produce these.
-   */
-  events: Array<Record<string, unknown>>;
-}
-
-/** Same wire shape as `UsageIngestResult`; aliased for call-site clarity. */
-export type SkillInvocationIngestResult = UsageIngestResult;
-
-// ---------------------------------------------------------------------------
-// Outcome events (hq-pro `/v1/outcome-events`)
-// ---------------------------------------------------------------------------
-
-export interface OutcomeEventsBatch {
-  /**
-   * Outcome-event rows. Each row is a plain object containing only the fields
-   * in the server's KEEP allowlist (type, occurredAt, companyUid, repo, branch,
-   * dedupeKey, and the type-specific refs projectName / storyId). Unlike the
-   * usage/skill batch, this batch carries NO machineId/installerVersion — the
-   * ingest handler (`apps/hq-pro/src/vault-service/handlers/outcome-events.ts`)
-   * accepts only `{ events }`. `personUid` MUST NOT appear on the batch or any
-   * event — hq-pro resolves the caller server-side from the Cognito JWT and
-   * REJECTS a body-supplied person identifier. Any field outside the allowlist
-   * is rejected with a 4xx `invalid-event`, so the emitter in
-   * `./outcome-telemetry.ts` is the only thing allowed to produce these.
-   */
-  events: Array<Record<string, unknown>>;
-}
-
-export interface OutcomeEventsIngestResult {
-  ok: boolean;
-  /** Rows newly written this request. */
-  written: number;
-  /** Rows collapsed by the server-side conditional put (idempotent replay). */
-  deduped: number;
-}
-
-// ---------------------------------------------------------------------------
-// Retry config
-// ---------------------------------------------------------------------------
-
-const MAX_RETRIES = 3;
-const BASE_DELAY_MS = 500;
-
-interface VaultRequestOptions {
-  timeoutMs?: number;
-  maxRetries?: number;
-}
-
-function isTransient(status: number): boolean {
-  return status === 429 || status >= 500;
-}
-
-async function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// ---------------------------------------------------------------------------
-// Response schemas
-// ---------------------------------------------------------------------------
-
-type VaultResponseSchema<T> = z.ZodType<T>;
-
-const membershipRoleSchema = z.enum(["owner", "admin", "member", "guest"]);
-const membershipStatusSchema = z.enum(["pending", "active", "revoked"]);
-const grantPermissionSchema = z.enum(["read", "write", "admin"]);
-const grantSourceSchema = z.enum(["creator", "person", "email", "group", "open"]);
-const presignOpSchema = z.enum(["get", "put", "delete"]);
-const syncModeSchema = z.enum(["shared", "all", "custom"]);
-const vendPurposeSchema = z.enum(["sync", "browse"]);
-const vaultOperationSchema = z.enum(["read-only", "read-write", "staged-write"]);
-
-// Membership/entity rows are intentionally permissive on field optionality:
-// current command tests and server flows use short rows outside sync decisions.
-const membershipSchema = z
-  .object({
-    membershipKey: z.string().optional(),
-    personUid: z.string().optional(),
-    companyUid: z.string().optional(),
-    role: membershipRoleSchema.optional(),
-    status: membershipStatusSchema.optional(),
-    allowedPrefixes: z.array(z.string()).optional(),
-    inviteToken: z.string().optional(),
-    invitedBy: z.string().optional(),
-    invitedAt: z.string().optional(),
-    acceptedAt: z.string().optional(),
-    revokedAt: z.string().optional(),
-    createdAt: z.string().optional(),
-    updatedAt: z.string().optional(),
-  })
-  .strip() as unknown as VaultResponseSchema<Membership>;
-
-const entityInfoSchema = z
-  .object({
-    uid: z.string(),
-    slug: z.string(),
-    type: z.string(),
-    name: z.string().optional(),
-    bucketName: z.string().optional(),
-    status: z.string(),
-    createdAt: z.string().optional(),
-  })
-  .strip() as unknown as VaultResponseSchema<EntityInfo>;
-
-const pendingInviteByEmailSchema: VaultResponseSchema<PendingInviteByEmail> = z
-  .object({
-    membershipKey: z.string(),
-    companyUid: z.string(),
-    role: membershipRoleSchema,
-    inviteToken: z.string().optional(),
-    invitedBy: z.string(),
-    invitedAt: z.string(),
-  })
-  .strip();
-
-const explicitGrantSchema: VaultResponseSchema<ExplicitGrant> = z
-  .object({
-    companyUid: z.string(),
-    path: z.string(),
-    permission: grantPermissionSchema,
-    source: grantSourceSchema,
-  })
-  .strip();
-
-const vaultListedObjectSchema: VaultResponseSchema<VaultListedObject> = z
-  .object({
-    key: z.string(),
-    size: z.number(),
-    lastModified: z.string().nullable(),
-    etag: z.string().nullable(),
-    permission: grantPermissionSchema,
-  })
-  .strip();
-
-const presignResultRowSchema: VaultResponseSchema<PresignResultRow> = z
-  .object({
-    key: z.string(),
-    op: presignOpSchema,
-    url: z.string().optional(),
-    headers: z.record(z.string(), z.string()).optional(),
-    expiresIn: z.number().optional(),
-    expiresAt: z.string().optional(),
-    error: z.string().optional(),
-    code: z.string().optional(),
-  })
-  .strip();
-
-const membershipSyncConfigSchema: VaultResponseSchema<MembershipSyncConfig> = z
-  .object({
-    membershipId: z.string(),
-    syncMode: syncModeSchema,
-    customPaths: z.array(z.string()).optional(),
-    isDefault: z.boolean(),
-    updatedAt: z.string().optional(),
-    updatedBy: z.string().optional(),
-  })
-  .strip();
-
-const vendCredentialsSchema: VaultResponseSchema<VendCredentials> = z
-  .object({
-    accessKeyId: z.string(),
-    secretAccessKey: z.string(),
-    sessionToken: z.string(),
-    expiration: z.string(),
-  })
-  .strip();
-
-const stsCredentialsSchema: VaultResponseSchema<StsChildCredentials> = z
-  .object({
-    accessKeyId: z.string(),
-    secretAccessKey: z.string(),
-    sessionToken: z.string(),
-  })
-  .strip();
-
-const telemetryOptInResponseSchema: VaultResponseSchema<TelemetryOptInResponse> =
-  z
-    .object({
-      enabled: z.boolean().default(false),
-      updatedAt: z.string().nullable().default(null),
-      personUid: z.string().optional(),
-      // `.optional()`, NOT `.default(false)`: an older server omits this field,
-      // and materializing it would change the parsed response shape for every
-      // legacy caller. Callers test `unset === true`, so absent reads as
-      // "not unset" and the self-heal path is skipped, which is the pre-existing
-      // behaviour exactly.
-      unset: z.boolean().optional(),
-    })
-    .strip();
-
-/**
- * `POST /v1/usage/opt-in` acknowledgement.
- *
- * `applied` is absent on older servers (which always wrote unconditionally), so
- * it stays optional and callers treat absence as "the write landed".
- */
-const telemetryOptInAckSchema: VaultResponseSchema<{ ok: boolean; applied?: boolean }> = z
-  .object({ ok: z.boolean().default(true), applied: z.boolean().optional() })
-  .strip();
-
-const usageIngestResultSchema: VaultResponseSchema<UsageIngestResult> = z
-  .object({
-    ok: z.boolean(),
-    written: z.number(),
-    skipped: z.array(
-      z
-        .object({
-          index: z.number(),
-          code: z.string(),
-          error: z.string(),
-        })
-        .strip(),
-    ),
-  })
-  .strip();
-
-const outcomeEventsIngestResultSchema: VaultResponseSchema<OutcomeEventsIngestResult> = z
-  .object({
-    ok: z.boolean(),
-    written: z.number().nonnegative(),
-    // Older/partial servers may omit `deduped`; default to 0 so a 2xx that
-    // reports only `written` still decodes (best-effort, matches usage rollout).
-    deduped: z.number().nonnegative().optional().transform((v) => v ?? 0),
-  })
-  .strip() as unknown as VaultResponseSchema<OutcomeEventsIngestResult>;
-
-/**
- * Accept the canonical v1 response and the previous raw-event aliases, then
- * normalize at this boundary so telemetry remains best-effort during rollout.
- */
-const telemetryEventsIngestResultSchema: VaultResponseSchema<TelemetryEventsIngestResult> = z
-  .object({
-    contractVersion: z.literal(1).optional(),
-    ok: z.boolean().optional(),
-    written: z.number().nonnegative().optional(),
-    skipped: z
-      .array(
-        z
-          .object({
-            index: z.number(),
-            code: z.string(),
-            error: z.string(),
-          })
-          .strip(),
-      )
-      .optional(),
-    // Compatibility aliases emitted by hq-pro before response contract v1.
-    accepted: z.number().nonnegative().optional(),
-    deduped: z.number().nonnegative().optional(),
-  })
-  .refine(
-    (value) =>
-      value.ok !== undefined || value.written !== undefined || value.accepted !== undefined,
-    { message: "telemetry ingest response has no recognized result fields" },
-  )
-  .transform((value) => ({
-    ok: value.ok ?? true,
-    written: value.written ?? value.accepted ?? 0,
-    skipped: value.skipped ?? [],
-  }));
-
-const createInviteResponseSchema: VaultResponseSchema<CreateInviteResult> = z
-  .object({
-    membership: membershipSchema,
-    inviteToken: z.string(),
-  })
-  .strip();
-
-const acceptInviteResponseSchema: VaultResponseSchema<AcceptInviteResult> = z
-  .object({
-    membership: membershipSchema,
-  })
-  .strip();
-
-const membershipsResponseSchema: VaultResponseSchema<{ memberships: Membership[] }> =
-  z
-    .object({
-      memberships: z.array(membershipSchema),
-    })
-    .strip();
-
-const pendingInvitesByEmailResponseSchema: VaultResponseSchema<{
-  invites?: PendingInviteByEmail[];
-}> = z
-  .object({
-    invites: z.array(pendingInviteByEmailSchema).optional(),
-  })
-  .strip();
-
-const membersResponseSchema: VaultResponseSchema<{ members: Membership[] }> = z
-  .object({
-    members: z.array(membershipSchema),
-  })
-  .strip();
-
-const membershipResponseSchema: VaultResponseSchema<{ membership: Membership }> =
-  z
-    .object({
-      membership: membershipSchema,
-    })
-    .strip();
-
-const invitesResponseSchema: VaultResponseSchema<{ invites: Membership[] }> = z
-  .object({
-    invites: z.array(membershipSchema),
-  })
-  .strip();
-
-const explicitGrantsResponseSchema: VaultResponseSchema<{
-  grants?: ExplicitGrant[];
-  computedAt: string;
-}> = z
-  .object({
-    grants: z.array(explicitGrantSchema).optional(),
-    computedAt: z.string(),
-  })
-  .strip();
-
-const listFilesResponseSchema: VaultResponseSchema<{
-  objects: VaultListedObject[];
-  cursor: string | null;
-  truncated: boolean;
-}> = z
-  .object({
-    objects: z.array(vaultListedObjectSchema).default([]),
-    cursor: z.string().nullable().default(null),
-    truncated: z.boolean().default(false),
-  })
-  .strip();
-
-const presignResponseSchema: VaultResponseSchema<{
-  results: PresignResultRow[];
-  expiresAt: string;
-}> = z
-  .object({
-    results: z.array(presignResultRowSchema),
-    expiresAt: z.string(),
-  })
-  .strip();
-
-const entityResponseSchema: VaultResponseSchema<{ entity: EntityInfo }> = z
-  .object({
-    entity: entityInfoSchema,
-  })
-  .strip();
-
-const checkSlugMeResponseSchema: VaultResponseSchema<{
-  available: boolean;
-  conflictingCompanyUid?: string;
-}> = z
-  .object({
-    available: z.boolean(),
-    conflictingCompanyUid: z.string().optional(),
-  })
-  .strip();
-
-const createEntityResponseSchema: VaultResponseSchema<CreateEntityResult> = z
-  .object({
-    entity: entityInfoSchema,
-  })
-  .strip();
-
-const entitiesResponseSchema: VaultResponseSchema<{ entities?: EntityInfo[] }> =
-  z
-    .object({
-      entities: z.array(entityInfoSchema).optional(),
-    })
-    .strip();
-
-const provisionBucketResponseSchema: VaultResponseSchema<{
-  bucketName: string;
-  kmsKeyId: string;
-}> = z
-  .object({
-    bucketName: z.string(),
-    kmsKeyId: z.string(),
-  })
-  .strip();
-
-const vendResponseSchema: VaultResponseSchema<VendResult> = z
-  .object({
-    credentials: vendCredentialsSchema,
-    paths: z.array(z.string()),
-    operations: vaultOperationSchema,
-    purpose: vendPurposeSchema,
-    policySize: z.number(),
-    requestId: z.string().optional(),
-  })
-  .strip();
-
-const stsVendResponseSchema: VaultResponseSchema<{
-  credentials: StsChildCredentials;
-  expiresAt: string;
-}> = z
-  .object({
-    credentials: stsCredentialsSchema,
-    expiresAt: z.string(),
-  })
-  .strip();
-
-const vendChildResponseSchema: VaultResponseSchema<VendChildResult> = z
-  .object({
-    credentials: stsCredentialsSchema,
-    sessionName: z.string(),
-    expiresAt: z.string(),
-  })
-  .strip();
-
-const emptyObjectResponseSchema = z.object({}).strip();
-
-function summarizeZodIssues(issues: readonly z.core.$ZodIssue[]): string {
-  return issues
-    .map((issue) => {
-      const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
-      return `${path}: ${issue.message}`;
-    })
-    .join("; ");
-}
-
-function companyUidFromMembershipId(membershipId: string): string | undefined {
-  const parts = membershipId.split("#");
-  const candidate = parts.length > 1 ? parts[parts.length - 1] : undefined;
-  return candidate?.startsWith("cmp_") ? candidate : undefined;
-}
-
-// ---------------------------------------------------------------------------
-// VaultClient
-// ---------------------------------------------------------------------------
-
-export class VaultClient {
-  private readonly apiUrl: string;
-  private readonly getAuthToken: () => Promise<string>;
-  private readonly clientInfo: ClientInfo | undefined;
-
-  constructor(config: VaultServiceConfig) {
-    this.apiUrl = config.apiUrl.replace(/\/+$/, "");
-    // Normalize string|getter into a single async getter so the request path
-    // doesn't have to branch. Static strings still work — they just produce a
-    // getter that returns the same value forever (suitable for short-lived
-    // tools and tests). Long-running callers pass a getter that re-reads
-    // `~/.hq/cognito-tokens.json` via `getValidAccessToken`, which is what
-    // makes the request layer self-heal across token refreshes.
-    const tok = config.authToken;
-    this.getAuthToken =
-      typeof tok === "function"
-        ? async () => tok()
-        : async () => tok;
-    this.clientInfo = config.clientInfo;
-  }
-
-  // -- Membership operations ------------------------------------------------
-
-  async createInvite(input: CreateInviteInput): Promise<CreateInviteResult> {
-    const data = await this.post(
-      "/membership/invite",
-      input,
-      createInviteResponseSchema,
-    );
-    return data;
-  }
-
-  async acceptInvite(token: string, personUid: string): Promise<AcceptInviteResult> {
-    const data = await this.post(
-      "/membership/accept",
-      { token, personUid },
-      acceptInviteResponseSchema,
-    );
-    return data;
-  }
-
-  /**
-   * Revoke a membership. The handler needs both the membershipKey AND the
-   * companyUid so it can authorize the caller as admin/owner of the company
-   * before performing the revoke. (We can't infer companyUid from the key
-   * alone without an extra DDB read, and the caller already knows it.)
-   */
-  async revokeMembership(membershipKey: string, companyUid: string): Promise<void> {
-    await this.post(
-      "/membership/revoke",
-      { membershipKey, companyUid },
-      emptyObjectResponseSchema,
-    );
-  }
-
-  /**
-   * List the caller's own active memberships.
-   *
-   * Server infers the caller's identity from the Cognito JWT `sub` claim and
-   * returns the union of active memberships across every person entity owned
-   * by that sub (orphan-tolerant — prior failed provisioning runs can leave
-   * multiple `prs_*` rows for the same Cognito identity).
-   *
-   * Returns `[]` — NOT a 404 — when the caller has no person entity yet.
-   * This lets `hq-sync-runner` distinguish "signed in but not bootstrapped"
-   * (empty array → emit `setup-needed`) from "auth broken" (throws
-   * VaultAuthError) without catching HTTP errors for flow control.
-   *
-   * Backed by `GET /membership/me` (see hq-pro ADR-0002).
-   */
-  async listMyMemberships(): Promise<Membership[]> {
-    const data = await this.get("/membership/me", membershipsResponseSchema);
-    return data.memberships;
-  }
-
-  /**
-   * List the caller's email-keyed pending invites. Server reads the email
-   * from the Cognito JWT, so no parameters are needed client-side.
-   *
-   * Used on first sign-in (installer + sync-runner) to detect invites that
-   * were sent to the caller's email before they had a person entity. Pair
-   * with {@link claimPendingInvitesByEmail} to rewrite those rows once the
-   * person exists.
-   */
-  async listMyPendingInvitesByEmail(): Promise<PendingInviteByEmail[]> {
-    const data = await this.get(
-      "/membership/pending-by-email",
-      pendingInvitesByEmailResponseSchema,
-    );
-    return data.invites ?? [];
-  }
-
-  /**
-   * Rewrite every email-keyed pending invite for the caller's email so it
-   * becomes personUid-keyed. Idempotent — zero-cost for returning users who
-   * have no pending invites. The caller's email is inferred from the JWT.
-   */
-  async claimPendingInvitesByEmail(personUid: string): Promise<void> {
-    await this.post(
-      "/membership/claim-by-email",
-      { personUid },
-      emptyObjectResponseSchema,
-    );
-  }
-
-  async listMembersOfCompany(companyUid: string): Promise<Membership[]> {
-    const data = await this.get(
-      `/membership/company/${encodeURIComponent(companyUid)}`,
-      membersResponseSchema,
-    );
-    return data.members;
-  }
-
-  async updateRole(input: UpdateRoleInput): Promise<Membership> {
-    const data = await this.post(
-      "/membership/role",
-      input,
-      membershipResponseSchema,
-    );
-    return data.membership;
-  }
-
-  async listPendingInvites(companyUid: string): Promise<Membership[]> {
-    const data = await this.get(
-      `/membership/company/${encodeURIComponent(companyUid)}/pending`,
-      invitesResponseSchema,
-    );
-    return data.invites;
-  }
-
-  // -- Browse-vs-sync (US-002, US-003, US-004) -----------------------------
-
-  /**
-   * List the caller's EXPLICIT per-company file-ACL grants. Backed by
-   * `GET /v1/files/grants?company={companyUid}` (hq-pro US-002).
-   *
-   * Role-bypass (owner/admin) entries are excluded server-side — the
-   * response is the caller's actual grant graph, not the full set of
-   * prefixes they can touch by virtue of role. Used by the
-   * browse-vs-sync UI to render an honest grant graph and by the
-   * sync engine to narrow what it pulls.
-   *
-   * Returns `[]` (NOT a 404) when the caller has no explicit grants in
-   * this company, so call sites can treat "empty graph" as a normal
-   * state without catching errors.
-   */
-  async listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]> {
-    const data = await this.get(
-      `/v1/files/grants?company=${encodeURIComponent(companyUid)}`,
-      explicitGrantsResponseSchema,
-    );
-    return data.grants ?? [];
-  }
-
-  // -- Presigned-URL transport (vault list + presign) ----------------------
-
-  /**
-   * ACL-filtered list of objects under `prefix`. Backed by
-   * `GET /v1/files/list?company=&prefix=&cursor=`. Returns only the keys the
-   * caller can read, each with metadata (size, lastModified, permission), plus
-   * an opaque `cursor` for the next page (null when exhausted). Page the cursor
-   * until it is null.
-   */
-  async listFiles(
-    companyUid: string,
-    prefix?: string,
-    cursor?: string,
-  ): Promise<{
-    objects: VaultListedObject[];
-    cursor: string | null;
-    truncated: boolean;
-  }> {
-    const qs = new URLSearchParams({ company: companyUid });
-    if (prefix) qs.set("prefix", prefix);
-    if (cursor) qs.set("cursor", cursor);
-    const data = await this.get(
-      `/v1/files/list?${qs.toString()}`,
-      listFilesResponseSchema,
-    );
-    return {
-      objects: data.objects,
-      cursor: data.cursor,
-      truncated: data.truncated,
-    };
-  }
-
-  /**
-   * Batch-mint presigned get/put/delete URLs. Backed by
-   * `POST /v1/files/presign`. Authorization is PER KEY — denied/invalid keys
-   * come back as `results[i].error` (the call itself succeeds), so callers must
-   * inspect each row. PUT rows carry `headers` the client must replay verbatim.
-   */
-  async presign(input: {
-    companyUid: string;
-    op?: PresignOp;
-    expiresIn?: number;
-    keys: PresignKeyInput[];
-  }): Promise<{ results: PresignResultRow[]; expiresAt: string }> {
-    return this.post(
-      `/v1/files/presign`,
-      {
-        company: input.companyUid,
-        ...(input.op ? { op: input.op } : {}),
-        ...(input.expiresIn ? { expiresIn: input.expiresIn } : {}),
-        keys: input.keys,
-      },
-      presignResponseSchema,
-    );
-  }
-
-  /**
-   * Read the effective sync-mode for a single membership. Backed by
-   * `GET /v1/memberships/{id}/sync-config` (hq-pro US-003).
-   *
-   * The server resolves the effective view — when no row exists for the
-   * membership it returns the built-in default with `isDefault: true`
-   * and omits `updatedAt`/`updatedBy`. Callers should treat `isDefault:
-   * true` as "no explicit config yet" rather than special-casing 404.
-   *
-   * Authorization: caller must own the membership OR hold admin/owner
-   * on the company that the membership belongs to. The server 404s
-   * tombstoned/revoked memberships.
-   */
-  async getMembershipSyncConfig(
-    membershipId: string,
-  ): Promise<MembershipSyncConfig> {
-    return this.get(
-      `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
-      membershipSyncConfigSchema,
-    );
-  }
-
-  /**
-   * Write the sync-mode for a single membership. Backed by
-   * `PUT /v1/memberships/{id}/sync-config` (hq-pro US-003).
-   *
-   * Server validates: `customPaths` is required when `syncMode` is
-   * `'custom'` and rejected otherwise. The returned row reflects the
-   * persisted state with `isDefault: false` (writing the row is what
-   * makes it non-default) and the server-assigned `updatedAt` +
-   * `updatedBy`.
-   */
-  async setMembershipSyncConfig(
-    membershipId: string,
-    partial: SetMembershipSyncConfigInput,
-  ): Promise<MembershipSyncConfig> {
-    const companyUid = companyUidFromMembershipId(membershipId);
-    try {
-      const result = await this.request(
-        "PUT",
-        `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
-        partial,
-        membershipSyncConfigSchema,
-      );
-      void emitCloudTelemetry(this, {
-        eventName: "membership_sync_config_changed",
-        source: "vault-client",
-        ...(companyUid ? { companyUid } : {}),
-        properties: {
-          syncMode: result.syncMode,
-          customPathCount: result.customPaths?.length ?? 0,
-          result: "success",
-          defaultState: result.isDefault ? "default" : "configured",
-        },
-      });
-      return result;
-    } catch (err) {
-      void emitCloudTelemetry(this, {
-        eventName: "membership_sync_config_changed",
-        source: "vault-client",
-        ...(companyUid ? { companyUid } : {}),
-        properties: {
-          syncMode: partial.syncMode,
-          customPathCount: partial.customPaths?.length ?? 0,
-          result: "failure",
-        },
-      });
-      throw err;
-    }
-  }
-
-  // -- Entity operations ----------------------------------------------------
-
-  readonly entity = {
-    get: async (uid: string): Promise<EntityInfo> => {
-      const data = await this.get(
-        `/entity/${encodeURIComponent(uid)}`,
-        entityResponseSchema,
-      );
-      return data.entity;
-    },
-
-    /**
-     * Legacy global slug lookup. Under the per-user-namespace model on
-     * hq-pro (PR indigoai-us/hq-pro#67, live in prod 2026-05-15) the
-     * server-side handler now uses `requireUnique: true` — this method
-     * returns a single entity when only one tenant holds the slug, 404s
-     * when nobody does, or 409s with `SlugNotUniqueError` and a list of
-     * colliding `uids` when more than one tenant holds it. Most CLI
-     * call sites have moved to `findInMyNamespace` (which respects the
-     * caller's effective namespace); only flows that genuinely want a
-     * global lookup (admin tooling) should still use this method.
-     */
-    findBySlug: async (type: string, slug: string): Promise<EntityInfo> => {
-      const data = await this.get(
-        `/entity/by-slug/${encodeURIComponent(type)}/${encodeURIComponent(slug)}`,
-        entityResponseSchema,
-      );
-      return data.entity;
-    },
-
-    /**
-     * Resolve an entity by slug within the CALLER's namespace
-     * (owned ∪ active-member-of, soft-deleted excluded). Hits the new
-     * `GET /entity/check-slug/me?type=&slug=` endpoint added in PR 67.
-     *
-     * Returns the full entity when present in the caller's namespace,
-     * or `null` when the slug isn't theirs — even if some OTHER user
-     * happens to own a company with the same slug. This is what every
-     * "find my-company by slug" flow wants under the per-user model;
-     * `findBySlug`'s global semantic would over-match (return a
-     * stranger's entity) or 409 (multi-tenant slug) in those cases.
-     */
-    findInMyNamespace: async (
-      type: string,
-      slug: string,
-    ): Promise<EntityInfo | null> => {
-      const check = await this.get(
-        `/entity/check-slug/me?type=${encodeURIComponent(type)}&slug=${encodeURIComponent(slug)}`,
-        checkSlugMeResponseSchema,
-      );
-      if (check.available || !check.conflictingCompanyUid) return null;
-      return this.entity.get(check.conflictingCompanyUid);
-    },
-
-    create: async (input: CreateEntityInput): Promise<EntityInfo> => {
-      const data = await this.post("/entity", input, createEntityResponseSchema);
-      return data.entity;
-    },
-
-    /** Return every entity of `type` owned by the caller (scoped by JWT). */
-    listByType: async (type: string): Promise<EntityInfo[]> => {
-      const data = await this.get(
-        `/entity/by-type/${encodeURIComponent(type)}`,
-        entitiesResponseSchema,
-      );
-      return data.entities ?? [];
-    },
-  };
-
-  // -- Identity bootstrap ---------------------------------------------------
-
-  /**
-   * Return the caller's person entity, creating it if one does not exist.
-   *
-   * Mirrors the installer's `ensurePersonEntity` bootstrap (`vault-handoff.ts`):
-   * pre-condition for {@link claimPendingInvitesByEmail}, which needs a
-   * concrete `personUid` to rewrite the email-keyed rows against.
-   *
-   * The slug is derived from `displayName`; if slugification yields an empty
-   * string, falls back to `user-<last-8-of-ownerSub>` so the POST always has
-   * a non-empty slug.
-   */
-  async ensureMyPersonEntity(hints: {
-    ownerSub: string;
-    displayName: string;
-  }): Promise<EntityInfo> {
-    const existing = await this.entity.listByType("person");
-    const pick = pickCanonicalPersonEntity(existing);
-    if (pick !== null) return pick;
-
-    const slug =
-      hints.displayName
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 63) || `user-${hints.ownerSub.slice(-8).toLowerCase()}`;
-
-    return this.entity.create({
-      type: "person",
-      name: hints.displayName,
-      slug,
-    });
-  }
-
-  // -- Provisioning operations (VLT-2) -----------------------------------------
-
-  async provisionBucket(companyUid: string): Promise<{ bucketName: string; kmsKeyId: string }> {
-    const data = await this.post(
-      "/provision/bucket",
-      { companyUid },
-      provisionBucketResponseSchema,
-    );
-    return data;
-  }
-
-  // -- Raw vend (POST /vend) ------------------------------------------------
-
-  /**
-   * POST `/vend` — vend STS-scoped credentials for an explicit path list.
-   *
-   * This is the legacy raw-vend endpoint (distinct from `/sts/vend`,
-   * `/sts/vend-self`, and `/sts/vend-child`). Per US-009 it accepts a
-   * `purpose` discriminator that controls whether admin/owner
-   * role-bypass widens the resulting session policy beyond the
-   * caller's explicit ACL grants:
-   *
-   *   - `purpose: 'browse'` — role-bypass APPLIES (interactive
-   *     `hq files browse`, admin spelunking).
-   *   - `purpose: 'sync'`   — role-bypass SUPPRESSED (background sync;
-   *     credentials are scoped to exactly what the caller has explicitly
-   *     been granted, regardless of role).
-   *
-   * The server defaults missing/empty to `'sync'` but every first-party
-   * caller should be explicit so audit attribution is correct.
-   *
-   * Used by `hq files browse`/`hq files cat` (US-008) to peek at vault
-   * objects without ever materialising them under `companies/{co}/`.
-   */
-  async vend(input: VendInput): Promise<VendResult> {
-    return this.post("/vend", input, vendResponseSchema);
-  }
-
-  // -- STS operations (VLT-8) -----------------------------------------------
-
-  readonly sts = {
-    /**
-     * Vend membership-scoped credentials for a company the caller belongs to.
-     * Backed by the vault-service `POST /sts/vend` route — the multi-tenant
-     * path that resolves the company's per-entity bucket and builds the
-     * session policy from the caller's role + ACL grants server-side
-     * (owner/admin get full-access, member/guest get per-prefix scoping).
-     *
-     * This is the correct path for interactive reads (`hq files browse`/`cat`):
-     * the legacy `POST /vend` ({@link VaultClient.vend}) assumes a single
-     * static bucket and is non-functional in multi-tenant production.
-     */
-    vend: async (input: {
-      companyUid: string;
-      durationSeconds?: number;
-    }): Promise<{
-      credentials: {
-        accessKeyId: string;
-        secretAccessKey: string;
-        sessionToken: string;
-      };
-      expiresAt: string;
-    }> => {
-      return this.post("/sts/vend", input, stsVendResponseSchema);
-    },
-    /**
-     * Vend task-scoped child credentials strictly narrower than the caller's
-     * own membership. Backed by the vault-service `POST /sts/vend-child`
-     * route (kebab-case to match the rest of the vault-service API).
-     *
-     * The child policy is intersected with the caller's membership on the
-     * server — if `taskScope.allowedPrefixes` requests anything the parent
-     * can't see, the server throws ScopeExceedsParentError before calling STS.
-     *
-     * Session name format: `${parentPersonUid}--task--${taskId}` — this lands
-     * in CloudTrail verbatim, so every child S3 action can be traced back to
-     * the parent task for incident response.
-     */
-    vendChild: async (input: VendChildInput): Promise<VendChildResult> => {
-      const data = await this.post("/sts/vend-child", input, vendChildResponseSchema);
-      return data;
-    },
-    vendSelf: async (input: { personUid: string; durationSeconds?: number }): Promise<{
-      credentials: { accessKeyId: string; secretAccessKey: string; sessionToken: string };
-      expiresAt: string;
-    }> => {
-      return this.post("/sts/vend-self", input, stsVendResponseSchema);
-    },
-  };
-
-  // -- Usage telemetry ------------------------------------------------------
-  //
-  // The server resolves `personUid` from the JWT (`extractCallerSub` →
-  // `resolveCallerPersonUid` in hq-pro `src/vault-service/handlers/_shared.ts`)
-  // and explicitly rejects any request body that carries a top-level
-  // `personUid`. So clients only send `{ machineId, installerVersion, events }`
-  // — tenant isolation is preserved no matter how this client is wrapped.
-
-  /**
-   * `GET /v1/usage/opt-in` — read whether the authenticated caller has opted
-   * in to per-event usage telemetry. Defaults to `false` server-side when the
-   * person row carries no `telemetryOptIn` field. Callers should treat any
-   * thrown error as "unknown — fall back to the local gate" rather than
-   * either yes or no; see `./telemetry.ts::collectAndSendTelemetry`.
-   */
-  async getTelemetryOptIn(): Promise<TelemetryOptInResponse> {
-    return this.get("/v1/usage/opt-in", telemetryOptInResponseSchema);
-  }
-
-  /**
-   * `POST /v1/usage/opt-in` — record the authenticated caller's consent.
-   *
-   * The installer is the primary writer (it owns the consent prompt). This
-   * client-side setter exists so the sync runner can RE-ASSERT a consent the
-   * user already gave locally but which never reached the server: the
-   * installer's write fires before the person entity exists and 404s on
-   * `no-person-entity`, so the answer survives only in `~/.hq/menubar.json`.
-   * See `./telemetry.ts::collectAndSendTelemetry`, which calls this ONLY when
-   * the server reports `unset` — never over an explicit opt-out.
-   *
-   * `onlyIfUnset` makes the server write conditional on the consent still never
-   * having been recorded. The self-heal MUST pass it: reading `unset` and
-   * replaying the answer are two separate requests, so without the condition
-   * another device could record a real opt-out in between and this replay would
-   * silently overwrite it. A deliberate user choice omits the flag so it always
-   * wins. The response's `applied` reports whether the write landed.
-   */
-  async setTelemetryOptIn(
-    enabled: boolean,
-    opts?: { onlyIfUnset?: boolean },
-  ): Promise<{ applied: boolean }> {
-    const ack = await this.post(
-      "/v1/usage/opt-in",
-      opts?.onlyIfUnset ? { enabled, onlyIfUnset: true } : { enabled },
-      telemetryOptInAckSchema,
-    );
-    // Older servers answer `{ ok: true }` with no `applied`; they also write
-    // unconditionally, so a 2xx there means the write did land.
-    return { applied: ack.applied ?? true };
-  }
-
-  /**
-   * `POST /v1/usage` — upload a batch of sanitized telemetry events.
-   *
-   * `personUid` MUST NOT appear in the batch — server-side resolution from
-   * the JWT is the only path. The server caps the body at 256 KiB and the
-   * event list at 100 rows; the collector in `./telemetry.ts` enforces a
-   * 1 MiB pre-flush cap which is the binding limit in practice.
-   */
-  async postUsage(batch: UsageBatch): Promise<UsageIngestResult> {
-    return this.post("/v1/usage", batch, usageIngestResultSchema);
-  }
-
-  /**
-   * `POST /v1/skill-invocations` — upload a batch of skill-invocation events.
-   *
-   * Same trust + size model as `postUsage`: `personUid` MUST NOT appear in the
-   * batch (server resolves it from the JWT). Gated by the same telemetry
-   * opt-in as `/v1/usage`.
-   */
-  async postSkillInvocations(
-    batch: SkillInvocationBatch,
-  ): Promise<SkillInvocationIngestResult> {
-    return this.post("/v1/skill-invocations", batch, usageIngestResultSchema);
-  }
-
-  /**
-   * `POST /v1/outcome-events` — upload a batch of delivery-outcome events
-   * (story-completed / project-shipped, per outcome-leaderboard US-004).
-   *
-   * Same trust model as `postUsage`: `personUid` MUST NOT appear on the batch
-   * or any event — hq-pro resolves the caller from the JWT and rejects a
-   * body-supplied person identifier. Gated by the same telemetry opt-in as
-   * `/v1/usage`. Server-side conditional PutItem on the composite dedupeKey
-   * makes re-syncs and multi-machine replays idempotent (they count as
-   * `deduped`, never a double-write).
-   */
-  async postOutcomeEvents(
-    batch: OutcomeEventsBatch,
-  ): Promise<OutcomeEventsIngestResult> {
-    return this.post("/v1/outcome-events", batch, outcomeEventsIngestResultSchema);
-  }
-
-  /**
-   * `POST /v1/telemetry/events` — upload a capped batch of hq-cloud ACTION
-   * events.
-   *
-   * Same trust model as `postUsage`: `personUid` MUST NOT appear in the body;
-   * hq-pro resolves the caller from the JWT and validates any `companyUid`
-   * against the caller's memberships. This endpoint is for server/CLI action
-   * telemetry and is not gated by the personal `/v1/usage` opt-in flag.
-   */
-  async postTelemetryEvents(
-    batch: TelemetryEventsBatch,
-    options: { timeoutMs?: number } = {},
-  ): Promise<TelemetryEventsIngestResult> {
-    return this.post("/v1/telemetry/events", batch, telemetryEventsIngestResultSchema, {
-      timeoutMs: options.timeoutMs ?? 1500,
-      maxRetries: 0,
-    });
-  }
-
-  // -- HTTP primitives with retry -------------------------------------------
-
-  private async get<T>(path: string, schema: VaultResponseSchema<T>): Promise<T> {
-    return this.request("GET", path, undefined, schema);
-  }
-
-  private async post<T>(
-    path: string,
-    body: unknown | undefined,
-    schema: VaultResponseSchema<T>,
-    options?: VaultRequestOptions,
-  ): Promise<T> {
-    return this.request("POST", path, body, schema, options);
-  }
-
-  private async request<T>(
-    method: string,
-    path: string,
-    body: unknown,
-    schema: VaultResponseSchema<T>,
-    options: VaultRequestOptions = {},
-  ): Promise<T> {
-    let lastError: Error | undefined;
-    const maxRetries = options.maxRetries ?? MAX_RETRIES;
-    // A 401 is not in isTransient() because most 401s are genuinely terminal.
-    // But one shape of 401 is fully recoverable: the access token expired
-    // between the caller resolving it and this request landing. Callers that
-    // pass a getter (getValidAccessToken) can mint a fresh token on demand, so
-    // we re-resolve once and retry IF the token actually changed. Static-string
-    // callers get the same value back and fall through to the throw, so this
-    // costs them nothing. Bounded to one attempt: a genuinely bad credential
-    // must not turn into a retry storm against the authorizer.
-    let authRetried = false;
-    // The auth retry gets its own budget rather than borrowing from the
-    // transient one. Sharing had two defects: a 401 early on left fewer
-    // retries for later 5xx, and a 401 on the FINAL attempt set the flag,
-    // hit `continue`, and fell out of the loop having never actually retried.
-    let maxAttempts = maxRetries;
-    // Backoff exists to let a rate limit or a struggling server recover.
-    // Neither applies to a token swap, so the auth retry goes out immediately.
-    let noBackoffAt = -1;
-
-    for (let attempt = 0; attempt <= maxAttempts; attempt++) {
-      if (attempt > 0 && attempt !== noBackoffAt) {
-        const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
-        await sleep(delay);
-      }
-
-      const authToken = await this.getAuthToken();
-      const headers: Record<string, string> = {
-        Authorization: `Bearer ${authToken}`,
-        Accept: "application/json",
-        ...buildClientHeaders(this.clientInfo),
-      };
-
-      const init: RequestInit = { method, headers };
-      const controller =
-        options.timeoutMs !== undefined && options.timeoutMs > 0
-          ? new AbortController()
-          : undefined;
-      let timeout: ReturnType<typeof setTimeout> | undefined;
-      if (controller) {
-        timeout = setTimeout(() => controller.abort(), options.timeoutMs);
-        timeout.unref?.();
-        init.signal = controller.signal;
-      }
-
-      if (body !== undefined) {
-        headers["Content-Type"] = "application/json";
-        init.body = JSON.stringify(body);
-      }
-
-      let res: Response;
-      try {
-        res = await fetch(`${this.apiUrl}${path}`, init);
-      } catch (err) {
-        lastError = err instanceof Error ? err : new Error(String(err));
-        if (attempt < maxAttempts) continue;
-        throw lastError;
-      } finally {
-        if (timeout !== undefined) clearTimeout(timeout);
-      }
-
-      if (res.ok) {
-        if (res.status === 204) return undefined as T;
-        const responseBody = await res.text();
-        let decoded: unknown;
-        try {
-          decoded = JSON.parse(responseBody);
-        } catch (err) {
-          throw new VaultClientError(
-            `Invalid JSON response from vault-service for ${method} ${path}`,
-            502,
-            err instanceof Error ? err.message : responseBody,
-          );
-        }
-
-        const parsed = schema.safeParse(decoded);
-        if (!parsed.success) {
-          throw new VaultClientError(
-            `Invalid response from vault-service for ${method} ${path}: ${summarizeZodIssues(parsed.error.issues)}`,
-            502,
-            responseBody,
-          );
-        }
-
-        return parsed.data;
-      }
-
-      const responseBody = await res.text();
-
-      // Expired-token 401 → re-resolve once and retry with the fresh token.
-      // Residual gap (deliberate): if the local cache still considers the token
-      // valid — clock skew, or a server-side revocation the client can't see —
-      // the getter returns the same string and we fall through to the throw.
-      // Fixing that needs a force-refresh hook on the token getter contract.
-      if (res.status === 401 && !authRetried) {
-        authRetried = true;
-        const refreshed = await this.getAuthToken().catch(() => undefined);
-        if (refreshed && refreshed !== authToken) {
-          lastError = this.mapError(res.status, responseBody, authToken);
-          maxAttempts++; // free retry — must not eat the transient budget
-          noBackoffAt = attempt + 1;
-          continue;
-        }
-      }
-
-      // Non-retryable errors → throw immediately
-      if (!isTransient(res.status)) {
-        throw this.mapError(res.status, responseBody, authToken);
-      }
-
-      // Retryable — store and loop
-      lastError = this.mapError(res.status, responseBody, authToken);
-    }
-
-    throw lastError ?? new VaultClientError("Request failed after retries", 500);
-  }
-
-  private mapError(
-    status: number,
-    body: string,
-    authToken?: string,
-  ): VaultClientError {
-    const message = this.extractMessage(body);
-
-    switch (status) {
-      case 401:
-        return new VaultAuthError(
-          message,
-          authToken ? accessTokenFingerprint(authToken) : undefined,
-        );
-      case 403:
-        return new VaultPermissionDeniedError(message);
-      case 404:
-        return new VaultNotFoundError(message);
-      case 409:
-        return new VaultConflictError(message);
-      default:
-        return new VaultClientError(message || `Request failed with status ${status}`, status, body);
-    }
-  }
-
-  private extractMessage(body: string): string {
-    try {
-      const parsed = JSON.parse(body) as { message?: string; error?: string };
-      return parsed.message ?? parsed.error ?? body;
-    } catch {
-      return body;
-    }
-  }
-}