@zenalexa/unicli 0.224.1 → 0.225.1

package/dist/engine/cookie-source.js

@@ -0,0 +1,207 @@
+/**
+ * @owner       src::engine::cookie-source
+ * @does        Multi-source cookie acquisition that surfaces the REAL cause of a
+ *              miss (keychain denied / corrupt file / v20 encryption / CDP
+ *              unavailable) as a typed outcome, instead of collapsing every
+ *              failure to null.
+ * @needs       node:fs, node:path, ./chromium-cookies (lazy), ./cookie-extractor (lazy)
+ * @feeds       src::engine::cookies (loadCookies/loadCookiesWithCDP/acquireCookies
+ *              projections), src::engine::executor (auth error detail)
+ * @breaks      never throws from loadCookiesWithDiagnostics — failures become
+ *              CookieLoadOutcome {status:"error", reasons}; readDiskCookies is total
+ * @invariants  exactly one of loaded|absent|error; "absent" ⇒ no source errored
+ *              (genuinely not logged in); "error" ⇒ ≥1 source had a real failure
+ * @side-effects readDiskCookies reads fs; default sources read browser DB / CDP
+ * @perf        disk O(file); browser tries installed browsers in order, stops on hit
+ * @concurrency stateless; sources own their own IO
+ * @test        tests/unit/engine/cookie-source.test.ts
+ * @stability   experimental
+ * @since       2026-05-30
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+const SITE_RE = /^[a-zA-Z0-9._-]+$/;
+export function cookieDir() {
+    return (process.env.UNICLI_COOKIE_DIR ??
+        join(process.env.HOME ?? "~", ".unicli", "cookies"));
+}
+/**
+ * Read the on-disk cookie file, distinguishing absent from corrupt. The old
+ * loadCookies collapsed a truncated / wrong-shaped file to null ("no auth"),
+ * hiding the real cause; this returns a typed corrupt with a detail.
+ */
+export function readDiskCookies(site) {
+    if (!SITE_RE.test(site)) {
+        return { kind: "corrupt", detail: `invalid site name "${site}"` };
+    }
+    const path = join(cookieDir(), `${site}.json`);
+    if (!existsSync(path))
+        return { kind: "absent" };
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        return {
+            kind: "corrupt",
+            detail: `cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "corrupt", detail: `${path} is not valid JSON` };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { kind: "corrupt", detail: `${path} is not a {name: value} object` };
+    }
+    return { kind: "ok", cookies: parsed };
+}
+/** Resolve the cookie domain the same way the legacy loader did. */
+export function resolveCookieDomain(site, domain) {
+    let resolved = domain ?? site.replace(/_/g, ".");
+    if (!resolved.includes("."))
+        resolved = `${resolved}.com`;
+    return resolved;
+}
+async function defaultReadBrowser(domain) {
+    let mod;
+    try {
+        mod = await import("./chromium-cookies.js");
+    }
+    catch (err) {
+        return {
+            kind: "error",
+            reasons: [
+                {
+                    source: "browser",
+                    code: "module_load_failed",
+                    detail: err instanceof Error ? err.message : String(err),
+                },
+            ],
+        };
+    }
+    const installed = mod.detectInstalledBrowsers();
+    if (installed.length === 0)
+        return { kind: "none" };
+    const reasons = [];
+    for (const browser of installed) {
+        try {
+            const record = mod.readCookiesAsRecord({ browser, domain });
+            if (Object.keys(record).length > 0)
+                return { kind: "ok", cookies: record };
+        }
+        catch (err) {
+            const code = err instanceof mod.ChromiumCookieError
+                ? err.code
+                : "browser_read_failed";
+            reasons.push({
+                source: "browser",
+                code,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return reasons.length > 0 ? { kind: "error", reasons } : { kind: "none" };
+}
+async function defaultReadCdp(domain) {
+    const { extractCookiesViaCDP } = await import("./cookie-extractor.js");
+    return extractCookiesViaCDP(domain);
+}
+export const defaultCookieSources = {
+    readDisk: readDiskCookies,
+    readBrowser: defaultReadBrowser,
+    readCdp: defaultReadCdp,
+};
+/**
+ * Acquire cookies across disk → browser → CDP, collecting the real cause of
+ * each source's failure. Never throws: a miss with no underlying fault is
+ * "absent"; a miss where a source actually errored (Keychain denial, corrupt
+ * file, v20 encryption, CDP down) is "error" with the reasons.
+ *
+ * Domain precedence and the disk-first / browser / CDP order match the legacy
+ * loadCookiesWithCDP exactly, so the projection wrappers preserve behavior.
+ */
+export async function loadCookiesWithDiagnostics(site, domain, sources = defaultCookieSources, opts = {}) {
+    const reasons = [];
+    // Refresh-after-401 skips disk: the on-disk cookies are exactly the stale
+    // ones that just failed, so re-acquisition must go straight to the live
+    // browser / CDP sources.
+    if (!opts.skipDisk) {
+        const disk = sources.readDisk(site);
+        if (disk.kind === "ok") {
+            return { status: "loaded", source: "disk", cookies: disk.cookies };
+        }
+        if (disk.kind === "corrupt") {
+            reasons.push({
+                source: "disk",
+                code: "corrupt_file",
+                detail: disk.detail,
+            });
+        }
+    }
+    const cookieDomain = resolveCookieDomain(site, domain);
+    if (process.env.UNICLI_COOKIE_NO_BROWSER !== "1") {
+        const browser = await sources.readBrowser(cookieDomain);
+        if (browser.kind === "ok" && Object.keys(browser.cookies).length > 0) {
+            return { status: "loaded", source: "browser", cookies: browser.cookies };
+        }
+        if (browser.kind === "error")
+            reasons.push(...browser.reasons);
+    }
+    try {
+        const cdp = await sources.readCdp(cookieDomain);
+        if (Object.keys(cdp).length > 0) {
+            return { status: "loaded", source: "cdp", cookies: cdp };
+        }
+    }
+    catch (err) {
+        reasons.push({
+            source: "cdp",
+            code: "cdp_unavailable",
+            detail: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return reasons.length > 0
+        ? { status: "error", reasons }
+        : { status: "absent" };
+}
+/**
+ * Turn a non-loaded outcome into an agent-actionable message + suggestion.
+ * This is where the no-silent-failure win is spent: Keychain denial, v20
+ * encryption, and a corrupt file each get a DISTINCT next step instead of the
+ * legacy one-size-fits-all "run unicli auth setup".
+ */
+export function describeCookieFailure(outcome, site, domain) {
+    const d = resolveCookieDomain(site, domain);
+    if (outcome.status === "absent") {
+        return {
+            message: `No cookies found for "${site}".`,
+            suggestion: `Sign in to https://${d} in Chrome, then run: unicli auth import ${site} --domain ${d}`,
+            retryable: false,
+        };
+    }
+    const codes = outcome.reasons.map((r) => `${r.source}:${r.code}`).join(", ");
+    const has = (code) => outcome.reasons.some((r) => r.code === code);
+    let suggestion;
+    if (has("keychain_denied")) {
+        suggestion = `Chrome cookie decryption was denied by the macOS Keychain. Grant access when prompted, or run: unicli auth import ${site} --domain ${d}`;
+    }
+    else if (has("encryption_unsupported")) {
+        suggestion = `Chrome's app-bound encryption (v20) blocks direct cookie reads. Start Chrome via "unicli browser start" (CDP path), or run: unicli auth import ${site} --domain ${d}`;
+    }
+    else if (has("corrupt_file")) {
+        suggestion = `The saved cookie file is unreadable. Re-import: unicli auth import ${site} --domain ${d}`;
+    }
+    else {
+        suggestion = `Could not acquire cookies (${codes}). Sign in to https://${d}, then run: unicli auth import ${site} --domain ${d}`;
+    }
+    return {
+        message: `Failed to load cookies for "${site}" — ${codes}.`,
+        suggestion,
+        retryable: false,
+    };
+}
+//# sourceMappingURL=cookie-source.js.map

package/dist/engine/cookie-source.js.map

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

package/dist/engine/cookies.d.ts

@@ -1,12 +1,24 @@
 /**
- * Cookie file reader for authenticated adapters.
- *
- * Cookies are stored as JSON in ~/.unicli/cookies/<site>.json
- * Each file contains { "cookie_name": "value", ... }
+ * @owner       src::engine::cookies
+ * @does        Cookie front door for adapters — thin projections over the
+ *              structured acquisition core in cookie-source.ts (disk read,
+ *              header formatting, multi-source load, refresh).
+ * @needs       ./cookie-source, ./cookie-extractor (saveCookies)
+ * @feeds       adapters (loadCookiesWithCDP/formatCookieHeader), executor,
+ *              dispatch/social (refreshCookiesFromBrowser), commands/auth
+ * @breaks      loadCookies/loadCookiesWithCDP return null on miss (back-compat);
+ *              acquireCookies returns a typed CookieLoadOutcome that names the
+ *              real cause — callers that need the cause use acquireCookies
+ * @invariants  loadCookiesWithCDP cookies === acquireCookies(...).cookies on load
+ * @side-effects acquireCookies persists browser/CDP cookies to disk (best-effort)
+ * @test        tests/unit/engine/cookie-source.test.ts, cookie-refresh-format.test.ts
+ * @stability   stable
+ * @since       2026-05-30
  */
+import { type CookieLoadOutcome } from "./cookie-source.js";
 /**
- * Load cookies for a site from disk.
- * Returns null if file doesn't exist or is malformed.
+ * Load cookies for a site from disk. Returns null when the file is absent OR
+ * unreadable; callers needing to tell those apart use `acquireCookies`.
  */
 export declare function loadCookies(site: string): Record<string, string> | null;
 /**
@@ -14,32 +26,27 @@ export declare function loadCookies(site: string): Record<string, string> | null
  * Example: "SESSDATA=abc; bili_jct=def"
  */
 export declare function formatCookieHeader(cookies: Record<string, string>): string;
-/**
- * Validate that a cookie file has all required keys.
- */
+/** Validate that a cookie file has all required keys. */
 export declare function validateCookies(site: string, requiredKeys: string[]): {
     valid: boolean;
     missing: string[];
 };
+/** Get the cookie directory path (for display in auth commands). */
+export declare function getCookieDir(): string;
 /**
- * Get the cookie directory path (for display in auth commands).
+ * Acquire cookies across disk → browser → CDP, returning the structured outcome
+ * (loaded / absent / error+reasons). On a non-disk load, persists to
+ * ~/.unicli/cookies for offline reuse. This is the front door for callers that
+ * need to surface WHY acquisition failed (Keychain denial, v20 encryption,
+ * corrupt file) instead of a bare null.
  */
-export declare function getCookieDir(): string;
+export declare function acquireCookies(site: string, domain?: string, opts?: {
+    skipDisk?: boolean;
+}): Promise<CookieLoadOutcome>;
 /**
- * Load cookies with multi-source fallback.
- *
- * Precedence (each falls through silently to the next on miss):
- *   1. ~/.unicli/cookies/<site>.json       — explicit user import
- *   2. browser local DB (Chrome/Arc/Dia/…) — direct SQLite read, no browser launch
- *   3. CDP                                  — connects to Chrome debug port (legacy)
- *
- * The browser disk source is the new default for `strategy: cookie` adapters:
- * it works whether the browser is open or closed, never opens a new tab, and
- * needs neither extension nor daemon. Successful reads are persisted to
- * ~/.unicli/cookies for offline reuse.
- *
- * Set `UNICLI_COOKIE_NO_BROWSER=1` to skip the browser-disk step (e.g., in CI
- * where the macOS Keychain prompt would block).
+ * Load cookies with multi-source fallback (disk → browser DB → CDP). Returns
+ * null on any miss. Behavior-compatible with every existing adapter consumer;
+ * the structured cause is available via `acquireCookies`.
  */
 export declare function loadCookiesWithCDP(site: string, domain?: string): Promise<Record<string, string> | null>;
 export interface CookieRefreshResult {
@@ -51,5 +58,10 @@ export interface CookieRefreshResult {
     cookies?: string[];
     suggestion?: string;
 }
+/**
+ * Re-acquire cookies from the live browser / CDP after an auth failure. Skips
+ * the on-disk file (those are the stale cookies that just failed) and reports
+ * the real cause on failure rather than a generic message.
+ */
 export declare function refreshCookiesFromBrowser(site: string, domain?: string): Promise<CookieRefreshResult>;
 //# sourceMappingURL=cookies.d.ts.map

package/dist/engine/cookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/engine/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAmBvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAMvC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAwCxC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAUD,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,CAAC,CA2D9B"}
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/engine/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAG5B;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAGvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI1E;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAKvC;AAED,oEAAoE;AACpE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,iBAAiB,CAAC,CAgB5B;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAGxC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,CAAC,CA+B9B"}

package/dist/engine/cookies.js

@@ -1,39 +1,29 @@
 /**
- * Cookie file reader for authenticated adapters.
- *
- * Cookies are stored as JSON in ~/.unicli/cookies/<site>.json
- * Each file contains { "cookie_name": "value", ... }
+ * @owner       src::engine::cookies
+ * @does        Cookie front door for adapters — thin projections over the
+ *              structured acquisition core in cookie-source.ts (disk read,
+ *              header formatting, multi-source load, refresh).
+ * @needs       ./cookie-source, ./cookie-extractor (saveCookies)
+ * @feeds       adapters (loadCookiesWithCDP/formatCookieHeader), executor,
+ *              dispatch/social (refreshCookiesFromBrowser), commands/auth
+ * @breaks      loadCookies/loadCookiesWithCDP return null on miss (back-compat);
+ *              acquireCookies returns a typed CookieLoadOutcome that names the
+ *              real cause — callers that need the cause use acquireCookies
+ * @invariants  loadCookiesWithCDP cookies === acquireCookies(...).cookies on load
+ * @side-effects acquireCookies persists browser/CDP cookies to disk (best-effort)
+ * @test        tests/unit/engine/cookie-source.test.ts, cookie-refresh-format.test.ts
+ * @stability   stable
+ * @since       2026-05-30
  */
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { extractCookiesViaCDP, saveCookies as saveCookiesToDisk, } from "./cookie-extractor.js";
-function cookieDir() {
-    return (process.env.UNICLI_COOKIE_DIR ??
-        join(process.env.HOME ?? "~", ".unicli", "cookies"));
-}
+import { cookieDir, describeCookieFailure, loadCookiesWithDiagnostics, readDiskCookies, resolveCookieDomain, } from "./cookie-source.js";
+import { saveCookies as saveCookiesToDisk } from "./cookie-extractor.js";
 /**
- * Load cookies for a site from disk.
- * Returns null if file doesn't exist or is malformed.
+ * Load cookies for a site from disk. Returns null when the file is absent OR
+ * unreadable; callers needing to tell those apart use `acquireCookies`.
  */
 export function loadCookies(site) {
-    if (!/^[a-zA-Z0-9._-]+$/.test(site))
-        return null;
-    const path = join(cookieDir(), `${site}.json`);
-    if (!existsSync(path))
-        return null;
-    try {
-        const raw = readFileSync(path, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== "object" ||
-            parsed === null ||
-            Array.isArray(parsed)) {
-            return null;
-        }
-        return parsed;
-    }
-    catch {
-        return null;
-    }
+    const read = readDiskCookies(site);
+    return read.kind === "ok" ? read.cookies : null;
 }
 /**
  * Format cookies as an HTTP Cookie header value.
@@ -44,9 +34,7 @@ export function formatCookieHeader(cookies) {
         .map(([k, v]) => `${k}=${v}`)
         .join("; ");
 }
-/**
- * Validate that a cookie file has all required keys.
- */
+/** Validate that a cookie file has all required keys. */
 export function validateCookies(site, requiredKeys) {
     const cookies = loadCookies(site);
     if (!cookies)
@@ -54,77 +42,44 @@ export function validateCookies(site, requiredKeys) {
     const missing = requiredKeys.filter((k) => !(k in cookies));
     return { valid: missing.length === 0, missing };
 }
-/**
- * Get the cookie directory path (for display in auth commands).
- */
+/** Get the cookie directory path (for display in auth commands). */
 export function getCookieDir() {
     return cookieDir();
 }
 /**
- * Load cookies with multi-source fallback.
- *
- * Precedence (each falls through silently to the next on miss):
- *   1. ~/.unicli/cookies/<site>.json       — explicit user import
- *   2. browser local DB (Chrome/Arc/Dia/…) — direct SQLite read, no browser launch
- *   3. CDP                                  — connects to Chrome debug port (legacy)
- *
- * The browser disk source is the new default for `strategy: cookie` adapters:
- * it works whether the browser is open or closed, never opens a new tab, and
- * needs neither extension nor daemon. Successful reads are persisted to
- * ~/.unicli/cookies for offline reuse.
- *
- * Set `UNICLI_COOKIE_NO_BROWSER=1` to skip the browser-disk step (e.g., in CI
- * where the macOS Keychain prompt would block).
+ * Acquire cookies across disk → browser → CDP, returning the structured outcome
+ * (loaded / absent / error+reasons). On a non-disk load, persists to
+ * ~/.unicli/cookies for offline reuse. This is the front door for callers that
+ * need to surface WHY acquisition failed (Keychain denial, v20 encryption,
+ * corrupt file) instead of a bare null.
  */
-export async function loadCookiesWithCDP(site, domain) {
-    // 1. ~/.unicli/cookies first
-    const diskCookies = loadCookies(site);
-    if (diskCookies)
-        return diskCookies;
-    // Resolve the cookie domain once for both browser and CDP paths.
-    let cookieDomain = domain ?? site.replace(/_/g, ".");
-    if (!cookieDomain.includes(".")) {
-        cookieDomain = `${cookieDomain}.com`;
-    }
-    // 2. Direct browser disk read (no launch, no CDP, no extension).
-    if (process.env.UNICLI_COOKIE_NO_BROWSER !== "1") {
-        const browserCookies = await loadFromInstalledBrowser(cookieDomain);
-        if (browserCookies && Object.keys(browserCookies).length > 0) {
-            try {
-                saveCookiesToDisk(site, browserCookies);
-            }
-            catch {
-                // Non-fatal — caller still gets the cookies.
-            }
-            return browserCookies;
+export async function acquireCookies(site, domain, opts = {}) {
+    const outcome = await loadCookiesWithDiagnostics(site, domain, undefined, opts);
+    if (outcome.status === "loaded" && outcome.source !== "disk") {
+        try {
+            saveCookiesToDisk(site, outcome.cookies);
         }
-    }
-    // 3. CDP fallback for users running Chrome with --remote-debugging-port.
-    try {
-        const cdpCookies = await extractCookiesViaCDP(cookieDomain);
-        if (Object.keys(cdpCookies).length > 0) {
-            try {
-                saveCookiesToDisk(site, cdpCookies);
-            }
-            catch {
-                // Non-fatal: disk write failed but we still have the cookies
-            }
-            return cdpCookies;
+        catch {
+            // REASON: persistence is best-effort; the cookies are already usable for
+            // this run, and the next run re-acquires from the same live source.
         }
     }
-    catch {
-        // CDP not available — fall through
-    }
-    return null;
+    return outcome;
 }
-function persistCookies(site, cookies) {
-    try {
-        saveCookiesToDisk(site, cookies);
-    }
-    catch {
-        // Non-fatal: callers can still retry because browser/CDP remains readable.
-    }
+/**
+ * Load cookies with multi-source fallback (disk → browser DB → CDP). Returns
+ * null on any miss. Behavior-compatible with every existing adapter consumer;
+ * the structured cause is available via `acquireCookies`.
+ */
+export async function loadCookiesWithCDP(site, domain) {
+    const outcome = await acquireCookies(site, domain);
+    return outcome.status === "loaded" ? outcome.cookies : null;
 }
+/**
+ * Re-acquire cookies from the live browser / CDP after an auth failure. Skips
+ * the on-disk file (those are the stale cookies that just failed) and reports
+ * the real cause on failure rather than a generic message.
+ */
 export async function refreshCookiesFromBrowser(site, domain) {
     if (!/^[a-zA-Z0-9._-]+$/.test(site)) {
         return {
@@ -134,77 +89,23 @@ export async function refreshCookiesFromBrowser(site, domain) {
             suggestion: "Site names must contain only letters, digits, dot, dash, or underscore.",
         };
     }
-    let cookieDomain = domain ?? site.replace(/_/g, ".");
-    if (!cookieDomain.includes(".")) {
-        cookieDomain = `${cookieDomain}.com`;
-    }
-    if (process.env.UNICLI_COOKIE_NO_BROWSER !== "1") {
-        const browserCookies = await loadFromInstalledBrowser(cookieDomain);
-        if (browserCookies && Object.keys(browserCookies).length > 0) {
-            persistCookies(site, browserCookies);
-            return {
-                ok: true,
-                site,
-                domain: cookieDomain,
-                source: "browser",
-                cookieCount: Object.keys(browserCookies).length,
-                cookies: Object.keys(browserCookies),
-            };
-        }
-    }
-    try {
-        const cdpCookies = await extractCookiesViaCDP(cookieDomain);
-        if (Object.keys(cdpCookies).length > 0) {
-            persistCookies(site, cdpCookies);
-            return {
-                ok: true,
-                site,
-                domain: cookieDomain,
-                source: "cdp",
-                cookieCount: Object.keys(cdpCookies).length,
-                cookies: Object.keys(cdpCookies),
-            };
-        }
-    }
-    catch {
+    const cookieDomain = resolveCookieDomain(site, domain);
+    const outcome = await acquireCookies(site, domain, { skipDisk: true });
+    if (outcome.status === "loaded") {
         return {
-            ok: false,
+            ok: true,
             site,
             domain: cookieDomain,
-            suggestion: `Open https://${cookieDomain} in the browser, complete login or challenge, then run: unicli auth import ${site} --domain ${cookieDomain}`,
+            source: outcome.source === "cdp" ? "cdp" : "browser",
+            cookieCount: Object.keys(outcome.cookies).length,
+            cookies: Object.keys(outcome.cookies),
         };
     }
     return {
         ok: false,
         site,
         domain: cookieDomain,
-        suggestion: `No cookies found for ${cookieDomain}. Sign in to https://${cookieDomain}, then run: unicli auth import ${site} --domain ${cookieDomain}`,
+        suggestion: describeCookieFailure(outcome, site, domain).suggestion,
     };
 }
-/**
- * Try each installed Chromium browser in priority order until one yields
- * cookies for the domain. Failures (browser not installed, Keychain denied,
- * unsupported encryption) fall through silently — the next source handles it.
- */
-async function loadFromInstalledBrowser(domain) {
-    let mod;
-    try {
-        mod = await import("./chromium-cookies.js");
-    }
-    catch {
-        return null;
-    }
-    const installed = mod.detectInstalledBrowsers();
-    for (const browser of installed) {
-        try {
-            const record = mod.readCookiesAsRecord({ browser, domain });
-            if (Object.keys(record).length > 0)
-                return record;
-        }
-        catch {
-            // Move on to the next browser.
-        }
-    }
-    return null;
-}
 //# sourceMappingURL=cookies.js.map

package/dist/engine/cookies.js.map

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

package/dist/engine/delivery/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @owner   src/engine/delivery/index.ts
  * @does    Exposes the internal objective-level delivery kernel.
- * @needs   src/engine/delivery/planner.ts, src/engine/delivery/repair.ts, src/engine/delivery/session.ts, src/engine/delivery/trajectory.ts, src/engine/delivery/types.ts
+ * @needs   src/engine/delivery/planner.ts, src/engine/delivery/repair.ts, src/engine/delivery/session.ts, src/engine/delivery/spec.ts, src/engine/delivery/trajectory.ts, src/engine/delivery/types.ts
  * @feeds   tests and future command surfaces that orchestrate objective delivery.
  * @breaks  Missing exports hide the delivery state machine from integration layers.
  * @invariants exports are side-effect free and preserve the delivery module boundary.
@@ -15,6 +15,7 @@
 export * from "./planner.js";
 export * from "./repair.js";
 export * from "./session.js";
+export * from "./spec.js";
 export * from "./trajectory.js";
 export * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/delivery/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/delivery/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/delivery/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC"}

package/dist/engine/delivery/index.js

@@ -1,7 +1,7 @@
 /**
  * @owner   src/engine/delivery/index.ts
  * @does    Exposes the internal objective-level delivery kernel.
- * @needs   src/engine/delivery/planner.ts, src/engine/delivery/repair.ts, src/engine/delivery/session.ts, src/engine/delivery/trajectory.ts, src/engine/delivery/types.ts
+ * @needs   src/engine/delivery/planner.ts, src/engine/delivery/repair.ts, src/engine/delivery/session.ts, src/engine/delivery/spec.ts, src/engine/delivery/trajectory.ts, src/engine/delivery/types.ts
  * @feeds   tests and future command surfaces that orchestrate objective delivery.
  * @breaks  Missing exports hide the delivery state machine from integration layers.
  * @invariants exports are side-effect free and preserve the delivery module boundary.
@@ -15,6 +15,7 @@
 export * from "./planner.js";
 export * from "./repair.js";
 export * from "./session.js";
+export * from "./spec.js";
 export * from "./trajectory.js";
 export * from "./types.js";
 //# sourceMappingURL=index.js.map