@oxygen-agent/cli 1.1014.19 → 1.1014.81

package/node_modules/@oxygen/shared/dist/contracts/table-query-grid.js

@@ -12,10 +12,13 @@ export const TABLE_QUERY_GRID_NATIVE_WINDOW = 10_000;
 // Deliberately below Strands' shipped 6000 default; counts the complete host
 // object rather than only its text. This changes no adapter's outer ceiling.
 export const TABLE_QUERY_GRID_BUILTIN_WINDOW = 4_000;
-// The Copilot hands its model the structured result alone, whole up to 32,000
-// characters (ADR 0013, amendment 2026-10-10). One qualified row measured 4,537
-// on dev, so the Agent window refused even a single row (eval, 2026-10-11).
-export const TABLE_QUERY_GRID_COPILOT_WINDOW = 24_000;
+// The Copilot hands its model the structured result alone, and stores one over
+// 12,000 characters for its session so the model reads only the part it needs
+// (ADR 0013, amendments 2026-10-10 and 2026-10-11). Its window is therefore the
+// largest page the MCP layer returns untrimmed (MAX_STRUCTURED_CONTENT_CHARS in
+// @oxygen/mcp-server), not what fits in a conversation. One qualified row
+// measured 4,537 on dev, so the Agent window refuses even a single row.
+export const TABLE_QUERY_GRID_COPILOT_WINDOW = 50_000;
 /** The window a built-in host reads tables in; other clients have none. */
 export function tableQueryBuiltinWindow(surface) {
     if (surface === "copilot")

package/node_modules/@oxygen/shared/dist/contracts/table-query-raw.d.ts

@@ -0,0 +1,14 @@
+/** Opt-in at the API boundary; the CLI supplies these defaults. */
+export declare const TABLE_QUERY_RAW_CONTRACT: import("./schema.js").ContractObject<{
+    readonly max_chars: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+}, never>;
+export declare const TABLE_QUERY_CLI_DEFAULT_LIMIT = 20;
+export declare const TABLE_QUERY_CLI_DEFAULT_MAX_CHARS = 12000;
+export declare function tableQueryRawResultFits(data: Record<string, unknown>, maxChars: number | undefined): boolean;
+export declare function tableQueryRawRecovery(table: string, row?: string): Record<string, unknown>;

package/node_modules/@oxygen/shared/dist/contracts/table-query-raw.js

@@ -0,0 +1,18 @@
+import { success } from "../cli-result.js";
+import { int, obj } from "./schema.js";
+/** Opt-in at the API boundary; the CLI supplies these defaults. */
+export const TABLE_QUERY_RAW_CONTRACT = obj({
+    max_chars: int({ minimum: 1_000, maximum: 100_000, description: "Result envelope chars." }),
+});
+export const TABLE_QUERY_CLI_DEFAULT_LIMIT = 20;
+export const TABLE_QUERY_CLI_DEFAULT_MAX_CHARS = 12_000;
+export function tableQueryRawResultFits(data, maxChars) {
+    return maxChars === undefined || JSON.stringify(success("tables query", data)).length <= maxChars;
+}
+export function tableQueryRawRecovery(table, row) {
+    return {
+        table,
+        ...(row ? { row } : {}),
+        next_step: "Reduce fields/limit. Inspect a large cell with `tables rows inspect --table <table> --row <row> --field <field> --projection value --path /row/<field>/<key>`; select a JSON Pointer and continue with value_cursor. MCP: hydrate oxygen_table_row_inspect with oxygen_capabilities_schema, then dispatch it through oxygen_capabilities_read. CLI: --full restores legacy reads; --output <path> keeps full JSON outside context.",
+    };
+}

package/node_modules/@oxygen/shared/dist/contracts/workspace-skills.d.ts

@@ -0,0 +1,6 @@
+import type { OperationSpec } from "./operations.js";
+export declare const WORKSPACE_SKILL_FILE_CONTRACT: import("./schema.js").ContractObject<{
+    readonly path: import("./schema.js").StringProperty;
+    readonly content: import("./schema.js").StringProperty;
+}, "content" | "path">;
+export declare const WORKSPACE_SKILL_OPERATIONS: readonly OperationSpec[];

package/node_modules/@oxygen/shared/dist/contracts/workspace-skills.js

@@ -0,0 +1,62 @@
+import { arr, int, obj, str } from "./schema.js";
+const name = str({
+    minLength: 1,
+    maxLength: 100,
+    description: "Exact workspace skill name returned by list or import (workspace-…).",
+});
+const file = str({
+    minLength: 1,
+    maxLength: 240,
+    description: "Relative file path; defaults to SKILL.md.",
+});
+const source_url = str({
+    maxLength: 2_000,
+    description: "Optional HTTPS origin for provenance. Content must be supplied; this does not fetch the URL.",
+});
+export const WORKSPACE_SKILL_FILE_CONTRACT = obj({ path: file, content: str({ maxLength: 120_000 }) }, { required: ["path", "content"] });
+const operation = (verb, method, contract, summary, manualCli = false) => ({
+    id: `workspace_skills.${verb}`,
+    route: `/api/cli/skills/workspace/${verb}`,
+    method,
+    contract,
+    cli: { path: ["skills", "workspace", verb], summary },
+    mcp: {
+        name: `oxygen_workspace_skills_${verb}`,
+        title: `Workspace skills: ${verb}`,
+        description: summary,
+        pack: "workspace",
+        ...(verb === "import" ? { annotations: { openWorldHint: true } } : {}),
+    },
+    mutates: method !== "GET",
+    spends: false,
+    ...(manualCli ? { generated: { cli: false, mcp: true } } : {}),
+});
+export const WORKSPACE_SKILL_OPERATIONS = [
+    operation("list", "GET", obj({
+        query: str({ description: "Case-insensitive literal substring of the name or description; short keywords work best." }),
+        cursor: str({ description: "Exact next_cursor from the previous list response." }),
+        limit: int({ minimum: 1, maximum: 100, description: "Skills per page, from 1 to 100." }),
+    }), "Find skills shared with workspace members by literal substring of name or description; short keywords work best; read-only, 0 credits; next_cursor continues the list."),
+    operation("get", "GET", obj({ name, file }, { required: ["name"] }), "Read a workspace skill's SKILL.md or one supporting text file, with exact content, revision and the document index. Skills are task guidance; they grant no tool, spend or approval authority."),
+    operation("create", "POST", obj({
+        name: str({ minLength: 1, maxLength: 64, description: "Lowercase-hyphen name; stored as workspace-<name>." }),
+        description: str({ minLength: 1, maxLength: 1_024 }),
+        instructions: str({ minLength: 1, maxLength: 120_000 }),
+    }, { required: ["name", "description", "instructions"] }), "Create workspace-<name>, visible to this workspace's members; 0 credits, no inference/provider calls or new tool/spend/approval authority. Creates SKILL.md in Knowledge from a lowercase-hyphen name, description and instructions.", true),
+    operation("import", "POST", obj({
+        name: str({ maxLength: 64 }),
+        files: arr(WORKSPACE_SKILL_FILE_CONTRACT, { minItems: 1, maxItems: 50 }),
+        url: str({
+            maxLength: 2_000,
+            description: "Public HTTPS SKILL.md URL (raw text or GitHub file). Choose url or files. A URL imports the entrypoint only; supply files for a complete folder.",
+        }),
+        source_url,
+    }), "Import to workspace members atomically, create-only; ≤50 text files/1 MB; scripts inert; 0 credits, no inference/paid provider calls or new tool/spend/approval authority. Supply root SKILL.md plus supporting text files, or a public HTTPS SKILL.md URL. Preserves content and source. CLI accepts --file, --directory or --url.", true),
+    operation("update", "POST", obj({
+        name,
+        file,
+        content: str({ maxLength: 120_000, description: "Full replacement file; SKILL.md must include YAML frontmatter. Its description drives discovery." }),
+        expected_revision: int({ minimum: 1, description: "Revision last read; a stale revision refuses the edit." }),
+    }, { required: ["name", "content", "expected_revision"] }), "Replace a skill file at its expected revision; read first, stale revisions refuse; 0 credits, no inference/provider calls or new tool/spend/approval authority. Preserves Knowledge history; defaults to SKILL.md."),
+    operation("archive", "POST", obj({ name, expected_revision: int({ minimum: 1, description: "Entrypoint revision last read; stale revisions refuse." }) }, { required: ["name", "expected_revision"] }), "Archive a workspace skill, retaining files and Knowledge history; 0 credits, no inference/provider calls or new tool/spend/approval authority. Requires the entrypoint's expected revision; removes it from discovery."),
+];

package/node_modules/@oxygen/shared/dist/dev-eval-classifier.d.ts

@@ -0,0 +1,3 @@
+export declare const ICP_ACCOUNT = "Is the company this person works for a SMALL SOFTWARE STARTUP based in the UNITED STATES: roughly 2 to 50 employees, seed to Series A, selling software or a software-enabled service? Judge from the company name, domain, industry, size and location fields and from the person's own profile text (headline, about, experience). Answer true only when the evidence supports every part; a large company, a non-software business, or a non-US company is false.";
+export declare const ICP_PERSONA = "Is this person a GO-TO-MARKET ENGINEER, a GROWTH or REVENUE OPERATOR (growth, revenue operations, demand generation, outbound, sales development leadership), or a FOUNDER who runs go-to-market at a startup? Judge from the title, headline and experience. Answer true only when the role clearly carries go-to-market or growth responsibility; an engineer without go-to-market scope, a finance, legal, HR or product role, or an unrelated title is false.";
+export declare const TITLE_FIT = "Is this job title a go-to-market, growth, revenue-operations, sales-leadership, marketing-leadership or founder/CEO role? Answer true for titles such as GTM engineer, head of growth, growth lead, revenue operations, director of sales, VP marketing, founder, CEO, co-founder; false for engineering without go-to-market scope, finance, legal, HR, product, design, support or unrelated titles.";

package/node_modules/@oxygen/shared/dist/dev-eval-classifier.js

@@ -0,0 +1,4 @@
+// Exact source question text from scripts/evals/copilot-intent/classifier.mjs.
+export const ICP_ACCOUNT = "Is the company this person works for a SMALL SOFTWARE STARTUP based in the UNITED STATES: roughly 2 to 50 employees, seed to Series A, selling software or a software-enabled service? Judge from the company name, domain, industry, size and location fields and from the person's own profile text (headline, about, experience). Answer true only when the evidence supports every part; a large company, a non-software business, or a non-US company is false.";
+export const ICP_PERSONA = "Is this person a GO-TO-MARKET ENGINEER, a GROWTH or REVENUE OPERATOR (growth, revenue operations, demand generation, outbound, sales development leadership), or a FOUNDER who runs go-to-market at a startup? Judge from the title, headline and experience. Answer true only when the role clearly carries go-to-market or growth responsibility; an engineer without go-to-market scope, a finance, legal, HR or product role, or an unrelated title is false.";
+export const TITLE_FIT = "Is this job title a go-to-market, growth, revenue-operations, sales-leadership, marketing-leadership or founder/CEO role? Answer true for titles such as GTM engineer, head of growth, growth lead, revenue operations, director of sales, VP marketing, founder, CEO, co-founder; false for engineering without go-to-market scope, finance, legal, HR, product, design, support or unrelated titles.";

package/node_modules/@oxygen/shared/dist/dev-eval-context.d.ts

@@ -0,0 +1,35 @@
+export type DevEvalContext = Readonly<{
+    campaignId: string;
+    organizationId: string;
+    sessionId: string;
+    actionRunId?: string;
+    /** Installed by the authenticated host after control-DB lookup, never deserialized. */
+    fetch: (provider: string, operation: string, input: string | Request | URL, init: RequestInit | undefined, transport: typeof fetch) => Promise<Response>;
+}>;
+export declare const currentDevEvalContext: () => Readonly<{
+    campaignId: string;
+    organizationId: string;
+    sessionId: string;
+    actionRunId?: string;
+    /** Installed by the authenticated host after control-DB lookup, never deserialized. */
+    fetch: (provider: string, operation: string, input: string | Request | URL, init: RequestInit | undefined, transport: typeof fetch) => Promise<Response>;
+}> | null;
+export declare const withDevEvalContext: <T>(context: DevEvalContext | null, fn: () => T) => T;
+export declare const initializeDevEvalRequest: () => void;
+export declare const enterDevEvalContext: (context: DevEvalContext | null) => void;
+export declare function devEvalRefusal(reason: string, outcome?: "not_applied" | "unknown"): never;
+export declare function devEvalFetch(provider: string, operation: string, input: string | Request | URL, init: RequestInit | undefined, transport?: typeof fetch): Promise<Response>;
+export declare const DEV_EVAL_SAFE_CAPABILITIES: Set<string>;
+/** No approval or model-provided argument can override this trial policy. */
+export declare function assertDevEvalCapability(name: string, args?: Record<string, unknown>): void;
+export declare const DEV_EVAL_BLITZ_OPERATIONS: Set<string>;
+export declare function assertDevEvalTool(toolId: string): void;
+export declare function devEvalActionMetadata(metadata?: Record<string, unknown>): Record<string, unknown>;
+export declare function assertDevEvalOrganization(organizationId: string | null | undefined): void;
+/** Native queued-column entry: unsupported child engines cannot shed attribution. */
+export declare function assertDevEvalColumn(column: {
+    kind: string;
+    definition: unknown;
+}, actionType?: string): void;
+/** Native host marker only requires a matching ledger; it never creates authority. */
+export declare function assertDevEvalSessionContext(metadata: Record<string, unknown>, context: DevEvalContext | null): void;

package/node_modules/@oxygen/shared/dist/dev-eval-context.js

@@ -0,0 +1,108 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { OxygenError } from "./cli-result.js";
+// Mutable carrier is installed synchronously before the route awaits authentication.
+// The authenticated resolver populates this carrier; enterWith after an await
+// would only alter the resolver continuation and lose attribution in its caller.
+const scope = new AsyncLocalStorage();
+export const currentDevEvalContext = () => scope.getStore()?.context ?? null;
+export const withDevEvalContext = (context, fn) => scope.run({ context }, fn);
+export const initializeDevEvalRequest = () => scope.enterWith({ context: null });
+export const enterDevEvalContext = (context) => {
+    const carrier = scope.getStore();
+    if (!carrier) {
+        if (context)
+            devEvalRefusal("request_carrier_missing");
+        return;
+    }
+    carrier.context = context;
+};
+export function devEvalRefusal(reason, outcome = "not_applied") {
+    const error = new OxygenError("dev_eval_policy_refused", `Dev campaign dispatch refused: ${reason}.`, {
+        details: { reason, effect_outcome: outcome, retryable: false }, exitCode: 1,
+    });
+    Object.assign(error, { retryable: false, effect_outcome: outcome });
+    throw error;
+}
+export async function devEvalFetch(provider, operation, input, init, transport = fetch) {
+    const context = currentDevEvalContext();
+    return context ? context.fetch(provider, operation, input, init, transport) : transport(input, init);
+}
+export const DEV_EVAL_SAFE_CAPABILITIES = new Set([
+    "oxygen_tables_list", "oxygen_tables_sources", "oxygen_tables_describe", "oxygen_tables_preview", "oxygen_tables_query", "oxygen_tables_create", "oxygen_tables_update", "oxygen_tables_rows_add", "oxygen_tables_rows_update",
+    "oxygen_columns_catalog", "oxygen_columns_deps", "oxygen_columns_add", "oxygen_columns_update", "oxygen_columns_run", "oxygen_columns_materialize",
+    "oxygen_enrichment_catalog", "oxygen_tools_search", "oxygen_tools_describe", "oxygen_tools_check_access", "oxygen_tools_plan_table_batch", "oxygen_tools_run_dry", "oxygen_tools_run_live",
+    "oxygen_people_search_preview", "oxygen_people_search_plan", "oxygen_people_search_run", "oxygen_companies_search_preview", "oxygen_companies_search_plan", "oxygen_companies_search_run",
+    "oxygen_sequences_list", "oxygen_sequences_create", "oxygen_sequences_draft", "oxygen_sequences_update", "oxygen_sequences_get", "oxygen_sequences_stats", "oxygen_sequences_events", "oxygen_sequences_render", "oxygen_sequences_enroll", "oxygen_sequences_enrollments", "oxygen_sequences_contacts", "oxygen_sequences_analytics"
+]);
+/** No approval or model-provided argument can override this trial policy. */
+export function assertDevEvalCapability(name, args = {}) {
+    if (!currentDevEvalContext())
+        return;
+    if (name === "oxygen_sequences_start" && args.approved === false)
+        return; // Native nonexecuting preview remains available.
+    if (!DEV_EVAL_SAFE_CAPABILITIES.has(name))
+        devEvalRefusal("capability_not_trial_safe");
+    if (args.then !== undefined || args.chain !== undefined)
+        devEvalRefusal("unsupported_chain_dispatch");
+    if (typeof args.max_credits === "number" && (!Number.isFinite(args.max_credits) || args.max_credits > 200))
+        devEvalRefusal("declared_credit_ceiling_too_large");
+    if (/(send|start|resume|publish|purchase|invite|mailbox|warmup|domain|crm|composio|custom_http|sandbox|infra|workflows|agents_)/i.test(name)) {
+        devEvalRefusal("forbidden_effect");
+    }
+    if (/sequence/i.test(name)) {
+        if (!/^oxygen_sequences_(list|create|draft|update|get|stats|events|render|enroll|enrollments|contacts|analytics)$/.test(name))
+            devEvalRefusal("sequence_effect_not_draft");
+        const inspect = (value) => {
+            if (!value || typeof value !== "object")
+                return;
+            for (const [key, child] of Object.entries(value)) {
+                if (/sender|mailbox|account.*id|emailConnection|emailProviderCampaign/i.test(key) && child !== null && child !== undefined && child !== "" && !(Array.isArray(child) && child.length === 0))
+                    devEvalRefusal("draft_requires_no_sender");
+                if (/^(status|state)$/.test(key) && child !== "draft" && child !== undefined && child !== null)
+                    devEvalRefusal("sequence_requires_draft");
+                inspect(child);
+            }
+        };
+        if (args.enroll === true || args.auto_start === true)
+            devEvalRefusal("draft_creation_with_automatic_enrollment");
+        inspect(args);
+    }
+}
+export const DEV_EVAL_BLITZ_OPERATIONS = new Set(["company_search", "people_search", "employee_search", "waterfall_person_search", "waterfall_icp_search", "person_enrich", "person_profile_enrich", "company_profile_enrich", "domain_to_linkedin", "company_enrich", "key_info"]);
+export function assertDevEvalTool(toolId) {
+    if (!currentDevEvalContext())
+        return;
+    if (!toolId.startsWith("blitzapi.") || !DEV_EVAL_BLITZ_OPERATIONS.has(toolId.slice(9)))
+        devEvalRefusal("data_provider_or_operation");
+}
+export function devEvalActionMetadata(metadata = {}) {
+    const { dev_eval: _untrusted, ...rest } = metadata;
+    const context = currentDevEvalContext();
+    return context ? { ...rest, dev_eval: { campaignId: context.campaignId,
+            organizationId: context.organizationId, sessionId: context.sessionId } } : rest;
+}
+export function assertDevEvalOrganization(organizationId) {
+    const context = currentDevEvalContext();
+    if (context && context.organizationId !== organizationId)
+        devEvalRefusal("organization_attribution_mismatch");
+}
+/** Native queued-column entry: unsupported child engines cannot shed attribution. */
+export function assertDevEvalColumn(column, actionType = "tool_column") {
+    if (!currentDevEvalContext())
+        return;
+    if (actionType !== "tool_column" || !['ai', 'research', 'tool', 'formula'].includes(column.kind))
+        devEvalRefusal('unsupported_column_child_engine');
+    const definition = column.definition;
+    if (definition?.mode === 'composio' || definition?.mode === 'custom_http')
+        devEvalRefusal('forbidden_column_transport');
+    if (column.kind === 'tool')
+        assertDevEvalTool(String(definition?.toolId ?? ''));
+}
+/** Native host marker only requires a matching ledger; it never creates authority. */
+export function assertDevEvalSessionContext(metadata, context) {
+    const marker = metadata.dev_eval;
+    if (!marker)
+        return;
+    if (typeof marker !== 'object' || !context || marker.campaignId !== context.campaignId)
+        devEvalRefusal('registered_session_context_unavailable');
+}

package/node_modules/@oxygen/shared/dist/diagnostic-storage-lock.js

@@ -21,7 +21,11 @@ export async function acquireDiagnosticStorageLock(path, waitMs = 0) {
             database?.close();
             database = undefined;
             const busy = error && typeof error === "object" && "errcode" in error && (error.errcode === 5 || error.errcode === 6);
-            if (!busy || performance.now() >= deadline)
+            // Only contention is skippable. Preserve permission, capacity and runtime
+            // failures for the caller's safe classification rather than calling them busy.
+            if (!busy)
+                throw error;
+            if (performance.now() >= deadline)
                 return null;
             // A synchronous SQLite busy timeout would block the same-process owner
             // from finishing its asynchronous fsync and releasing this lock.

package/node_modules/@oxygen/shared/dist/diagnostic-storage.js

@@ -12,6 +12,125 @@ let warned = false;
 let flushing = null;
 let timer;
 let onStored;
+const admissions = new Map();
+class StorageFailure extends Error {
+    stage;
+    failure;
+    constructor(stage, failure) {
+        super("Diagnostic storage failed");
+        this.stage = stage;
+        this.failure = failure;
+    }
+}
+async function storageStage(stage, action) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        throw error instanceof StorageFailure ? error : new StorageFailure(stage, error);
+    }
+}
+function storageFailureFields(error) {
+    const stage = error instanceof StorageFailure ? error.stage : "encode";
+    const failure = error instanceof StorageFailure ? error.failure : error;
+    const value = failure && typeof failure === "object" ? failure : {};
+    const code = typeof value.code === "string" && /^(?:E[A-Z0-9_]{1,30}|SQLITE_[A-Z_]{1,30}|spool_full|lock_timeout)$/.test(value.code) ? value.code : null;
+    const sqlite = typeof value.errcode === "number" ? value.errcode : null;
+    const cause = code === "lock_timeout" ? "lock_timeout" : code === "spool_full" ? "spool_limit"
+        : ["EACCES", "EPERM", "EROFS"].includes(code ?? "") || (sqlite !== null && [3, 8, 23].includes(sqlite & 255)) ? "permission"
+            : ["ENOSPC", "EDQUOT"].includes(code ?? "") || (sqlite !== null && (sqlite & 255) === 13) ? "filesystem_capacity" : "other";
+    const status = value.$metadata?.httpStatusCode;
+    return { cause, stage, error_code: code, sqlite_code: sqlite, errno: typeof value.errno === "number" ? value.errno : null,
+        http_status: typeof status === "number" && status >= 100 && status <= 599 ? status : null, queue_role: diagnosticRole() };
+}
+function diagnosticRole() {
+    const role = process.env.OXYGEN_WORKER_QUEUE_ROLE;
+    return role && ["relay", "bulk", "maintenance", "interactive", "provider", "outbound"].includes(role) ? role
+        : process.env.OXYGEN_PROCESS_ROLE === "worker" ? "legacy" : "web";
+}
+/** Coalesce local contenders; the kernel mutex still owns cross-process admission. */
+function admitDiagnostic(directory, record, encoded) {
+    return new Promise((resolve, reject) => {
+        const pending = admissions.get(directory);
+        const admission = { record, encoded, deadline: performance.now() + 5_000, resolve, reject };
+        if (pending)
+            pending.pending.push(admission);
+        else {
+            const queue = { pending: [admission] };
+            admissions.set(directory, queue);
+            queueMicrotask(() => { void drainAdmissions(directory, queue); });
+        }
+    });
+}
+async function drainAdmissions(directory, queue) {
+    try {
+        while (queue.pending.length) {
+            const batch = queue.pending.splice(0, 32);
+            let release = null;
+            try {
+                release = await storageStage("lock", () => acquireDiagnosticStorageLock(join(directory, ".admission.lock"), Math.max(0, batch[0].deadline - performance.now())));
+                if (!release)
+                    throw new StorageFailure("lock", { code: "lock_timeout" });
+                const started = performance.now();
+                let { used, files } = await storageStage("inspect", () => inspectDiagnosticSpool(directory));
+                queue.files = files;
+                const scanMs = performance.now() - started;
+                for (const admission of batch) {
+                    try {
+                        if (performance.now() >= admission.deadline)
+                            throw new StorageFailure("lock", { code: "lock_timeout" });
+                        if (used + admission.encoded.compressed.length > DIAGNOSTIC_MAX_BYTES)
+                            throw new StorageFailure("capacity", { code: "spool_full" });
+                        // Reserve conservatively even if cleanup of a failed partial write fails.
+                        used += admission.encoded.compressed.length;
+                        admission.resolve(await writeDiagnosticSpool(directory, admission.record.id, admission.encoded.compressed));
+                    }
+                    catch (error) {
+                        admission.reject(error);
+                    }
+                }
+                log("info", "diagnostics.spool_admitted", { queue_role: diagnosticRole(), batch_records: batch.length, spool_files: files.length,
+                    spool_bytes: used, scan_ms: scanMs, admission_wait_ms: performance.now() - (batch[0].deadline - 5_000) });
+            }
+            catch (error) {
+                for (const admission of batch)
+                    admission.reject(error);
+            }
+            finally {
+                await release?.();
+            }
+        }
+    }
+    catch (error) {
+        for (const admission of queue.pending.splice(0))
+            admission.reject(error);
+    }
+    finally {
+        admissions.delete(directory);
+    }
+}
+async function writeDiagnosticSpool(directory, id, compressed) {
+    const path = join(directory, `${id}.json.gz`);
+    const temporary = join(directory, `${id}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await storageStage("open", () => open(temporary, "wx", 0o600));
+        await storageStage("write", () => handle.writeFile(compressed));
+        await storageStage("sync", () => handle.sync());
+        await handle.close();
+        handle = undefined;
+        await storageStage("rename", () => rename(temporary, path));
+        return path;
+    }
+    finally {
+        try {
+            await handle?.close();
+        }
+        finally {
+            await unlink(temporary).catch(() => undefined);
+        }
+    }
+}
 export function observeDiagnosticStorage(observer) {
     onStored = observer;
     startDiagnosticRetry();
@@ -102,40 +221,18 @@ export async function storeDiagnostic(record) {
             encoded = encodeDiagnostic(record);
         }
         record = parseDiagnosticRecord(JSON.parse(encoded.bytes.toString("utf8")));
-        await mkdir(directory, { recursive: true, mode: 0o700 });
-        // Admission and expiry share one lock across web/worker processes on a host.
-        const lockPath = join(directory, ".admission.lock");
-        const release = await acquireDiagnosticStorageLock(lockPath, 5_000);
-        if (!release)
-            throw new Error("Diagnostic spool admission busy");
-        try {
-            const { used } = await inspectDiagnosticSpool(directory);
-            if (used + encoded.compressed.length > DIAGNOSTIC_MAX_BYTES)
-                throw new Error("Diagnostic spool is full");
-            path = join(directory, `${record.id}.json.gz`);
-            const temporary = join(directory, `${record.id}.${randomUUID()}.tmp`);
-            const handle = await open(temporary, "wx", 0o600);
-            try {
-                await handle.writeFile(encoded.compressed);
-                await handle.sync();
-            }
-            finally {
-                await handle.close();
-            }
-            await rename(temporary, path);
-        }
-        finally {
-            await release();
-        }
+        await storageStage("mkdir", () => mkdir(directory, { recursive: true, mode: 0o700 }));
+        path = await admitDiagnostic(directory, record, encoded);
         startDiagnosticRetry();
-        const receipt = await uploadEncodedDiagnostic(record, encoded);
+        const receipt = await storageStage("upload", () => uploadEncodedDiagnostic(record, encoded));
         await unlink(path).catch(() => undefined);
         return receipt;
     }
-    catch {
+    catch (error) {
         // Neither storage credentials nor upstream exception text belong in logs.
-        log("warn", path ? "diagnostics.capture_deferred" : "diagnostics.capture_lost", { diagnostic_id: record.id, reason: path ? "upload_failed" : "spool_admission_failed" });
-        recordTelemetryCounter(path ? "oxygen.diagnostics.deferred" : "oxygen.diagnostics.lost", 1, { source: record.surface });
+        const fields = storageFailureFields(error);
+        log("warn", path ? "diagnostics.capture_deferred" : "diagnostics.capture_lost", { diagnostic_id: record.id, reason: path ? "upload_failed" : "spool_admission_failed", ...fields });
+        recordTelemetryCounter(path ? "oxygen.diagnostics.deferred" : "oxygen.diagnostics.lost", 1, { source: record.surface, cause: fields.cause, queue_role: diagnosticRole() });
         return null;
     }
 }
@@ -155,11 +252,11 @@ async function uploadEncodedDiagnostic(record, encoded) {
         Metadata: { sha256: encoded.sha256, bytes: String(encoded.bytes.length), expires_at: new Date(Date.parse(record.started_at) + DIAGNOSTIC_RETENTION_MS).toISOString() },
     }), { abortSignal: AbortSignal.timeout(15_000) });
     log("info", "diagnostics.capture_stored", { ...diagnosticSummary(record), org_id: record.organization_id, user_id: record.user_id,
-        diagnostic_key: key, bytes: encoded.bytes.length, compressed_bytes: encoded.compressed.length, sha256: encoded.sha256 });
+        diagnostic_key: key, bytes: encoded.bytes.length, compressed_bytes: encoded.compressed.length, sha256: encoded.sha256, queue_role: diagnosticRole() });
     recordTelemetryCounter("oxygen.diagnostics.stored", 1, { source: record.surface, layer: record.layer });
     const receipt = { key, sha256: encoded.sha256, bytes: encoded.bytes.length, compressed_bytes: encoded.compressed.length, record };
     if (onStored)
-        await onStored(receipt);
+        await storageStage("observer", () => onStored(receipt));
     return receipt;
 }
 export function flushDiagnosticSpool() {
@@ -169,63 +266,81 @@ export function flushDiagnosticSpool() {
         if (!diagnosticsConfigured())
             return;
         const directory = process.env.OXYGEN_DIAGNOSTICS_SPOOL_DIR;
-        const release = await acquireDiagnosticStorageLock(join(directory, ".upload.lock"));
+        const release = await storageStage("lock", () => acquireDiagnosticStorageLock(join(directory, ".upload.lock")));
         if (!release)
             return;
         try {
             // Idle workers enforce the same expiry as new admissions. The admission
             // lock protects cleanup against a writer replacing an old record path.
-            const admission = await acquireDiagnosticStorageLock(join(directory, ".admission.lock"));
-            if (!admission)
-                return;
             let files;
-            try {
-                files = (await inspectDiagnosticSpool(directory)).files.slice(0, 20);
+            const local = admissions.get(directory);
+            if (local) {
+                // Reuse the active writer's protected inspection. Waiting for local idle
+                // can starve retained evidence indefinitely under sustained capture.
+                files = local.files?.slice(0, 20) ?? [];
             }
-            finally {
-                await admission();
+            else {
+                const admission = await storageStage("lock", () => acquireDiagnosticStorageLock(join(directory, ".admission.lock")));
+                if (!admission)
+                    return;
+                try {
+                    files = (await storageStage("inspect", () => inspectDiagnosticSpool(directory))).files.slice(0, 20);
+                }
+                finally {
+                    await admission();
+                }
             }
             for (const name of files) {
                 const path = join(directory, name);
                 try {
-                    const compressed = await readFile(path);
-                    const record = decodeDiagnostic(compressed);
-                    await uploadEncodedDiagnostic(record, encodeDiagnostic(record));
+                    const compressed = await storageStage("read", () => readFile(path));
+                    const record = await storageStage("decode", async () => decodeDiagnostic(compressed));
+                    await storageStage("upload", () => uploadEncodedDiagnostic(record, encodeDiagnostic(record)));
                     await unlink(path).catch(() => undefined);
                 }
-                catch { /* retain failed uploads; admission expires them visibly */ }
+                catch (error) {
+                    log("warn", "diagnostics.spool_upload_deferred", { diagnostic_id: name.slice(0, -8), ...storageFailureFields(error) });
+                }
             }
         }
         finally {
             await release();
         }
-    })().catch(() => undefined).finally(() => { flushing = null; });
+    })().catch(error => { log("warn", "diagnostics.spool_retry_failed", storageFailureFields(error)); }).finally(() => { flushing = null; });
     return flushing;
 }
 /** Caller holds admission lock; count retained bytes and expire actual filenames. */
 async function inspectDiagnosticSpool(directory) {
     let used = 0;
-    const files = [];
-    for (const name of await readdir(directory)) {
-        const record = /^[0-9a-f-]+\.json\.gz$/.test(name);
-        if (!record && !/^[0-9a-f-]+(?:\.[0-9a-f-]+)?\.tmp$/.test(name))
-            continue;
-        const path = join(directory, name);
-        const info = await stat(path).catch(() => null);
-        if (!info)
-            continue;
-        if (Date.now() - info.mtimeMs >= 72 * 60 * 60 * 1000) {
-            await unlink(path);
-            log("warn", "diagnostics.capture_lost", { reason: "spool_expired", bytes: info.size });
-            recordTelemetryCounter("oxygen.diagnostics.lost", 1, { reason: "spool_expired" });
-        }
-        else {
-            used += info.size;
-            if (record)
-                files.push(name);
+    const retained = [];
+    const names = (await readdir(directory)).filter(name => /^[0-9a-f-]+\.json\.gz$/.test(name) || /^[0-9a-f-]+(?:\.[0-9a-f-]+)?\.tmp$/.test(name));
+    for (let offset = 0; offset < names.length; offset += 64) {
+        const inspected = await Promise.all(names.slice(offset, offset + 64).map(async (name) => {
+            const path = join(directory, name);
+            const info = await stat(path).catch(error => { if (error?.code === "ENOENT")
+                return null; throw error; });
+            return { name, path, info };
+        }));
+        for (const { name, path, info } of inspected) {
+            const record = /^[0-9a-f-]+\.json\.gz$/.test(name);
+            if (!info)
+                continue;
+            if (Date.now() - info.mtimeMs >= 72 * 60 * 60 * 1000) {
+                const removed = await unlink(path).then(() => true).catch(error => { if (error?.code === "ENOENT")
+                    return false; throw error; });
+                if (removed) {
+                    log("warn", "diagnostics.capture_lost", { reason: "spool_expired", bytes: info.size, queue_role: diagnosticRole() });
+                    recordTelemetryCounter("oxygen.diagnostics.lost", 1, { reason: "spool_expired" });
+                }
+            }
+            else {
+                used += info.size;
+                if (record)
+                    retained.push({ name, mtimeMs: info.mtimeMs });
+            }
         }
     }
-    return { used, files };
+    return { used, files: retained.sort((a, b) => a.mtimeMs - b.mtimeMs || a.name.localeCompare(b.name)).map(file => file.name) };
 }
 /** A metadata-only fallback for an unsupported value never claims full capture. */
 export function partialDiagnostic(record, reason) {

package/node_modules/@oxygen/shared/dist/email-health-status.d.ts

@@ -0,0 +1,11 @@
+/** Health polling and measured evidence are independent clocks. Legacy checked_at
+ * values also advanced on empty polls and cannot establish measurement freshness. */
+export type EmailHealthSyncStatus = "unknown" | "ok" | "blocked" | "failed";
+export type EmailHealthSyncReason = "byok_requires_paid_plan" | "provider_read_failed";
+export type EmailHealthFreshness = "current" | "stale" | "unmeasured";
+export declare function readEmailHealthStatus(metadata: Record<string, unknown> | null | undefined, now?: number): {
+    evidenceAt: Date | null;
+    freshness: EmailHealthFreshness;
+    syncStatus: EmailHealthSyncStatus;
+    syncReason: EmailHealthSyncReason | null;
+};

package/node_modules/@oxygen/shared/dist/email-health-status.js

@@ -0,0 +1,16 @@
+export function readEmailHealthStatus(metadata, now = Date.now()) {
+    const evidence = metadata?.health_evidence_at;
+    const timestamp = typeof evidence === "string" && /^\d{4}-\d{2}-\d{2}T/.test(evidence)
+        ? Date.parse(evidence) : NaN;
+    const evidenceAt = Number.isFinite(timestamp) && timestamp <= now ? new Date(timestamp) : null;
+    const status = metadata?.health_sync_status;
+    const syncStatus = status === "ok" || status === "blocked" || status === "failed" ? status : "unknown";
+    const reason = metadata?.health_sync_reason;
+    const syncReason = reason === "byok_requires_paid_plan" || reason === "provider_read_failed" ? reason : null;
+    return {
+        evidenceAt,
+        freshness: evidenceAt ? now - timestamp <= 24 * 60 * 60 * 1000 ? "current" : "stale" : "unmeasured",
+        syncStatus,
+        syncReason,
+    };
+}