@rockhopper-co/mcp-server 0.5.0 → 0.7.0

package/dist/auth/device-grant-client.js

@@ -0,0 +1,138 @@
+/**
+ * ENG-1444 / KI-081 — RFC 8628 device-grant client.
+ *
+ * Talks to the backend's `POST /auth/device/{code,token}` endpoints
+ * (introduced in ENG-1384 PR 1, `Rockhopper-Co/backend#473`). Used by
+ * the mcp-server CLI when no PAT env var is set and no OAuth bundle
+ * is stored in the OS keychain.
+ *
+ * Surfaces a single entrypoint, `runDeviceGrantFlow`, that:
+ *
+ *   1. Calls `/auth/device/code` to get a (deviceCode, userCode) pair.
+ *   2. Emits the user-facing `userCode` + verification URI to stderr
+ *      (LLM clients pick this up via stdout's stderr passthrough).
+ *   3. Polls `/auth/device/token` at the server-specified interval,
+ *      respecting RFC 8628 § 3.5 `slow_down` (bumps interval +5s) and
+ *      `authorization_pending` (continues polling).
+ *   4. Resolves with the access-token bundle on success, rejects on
+ *      `access_denied` / `expired_token` / network failure.
+ *
+ * No external HTTP dependency — uses globalThis.fetch (Node 18+).
+ * `fetchImpl` + `sleep` + `onUserCode` are injectable for tests.
+ */
+export class DeviceGrantError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DeviceGrantError';
+    }
+}
+/* v8 ignore next 2 -- trivial setTimeout wrapper; tests inject a sleep stub via `opts.sleep` */
+const DEFAULT_SLEEP = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const DEFAULT_ON_USER_CODE = (info) => {
+    process.stderr.write('\nRockhopper — sign in to authorize this MCP client.\n' +
+        `Open: ${info.verificationUriComplete}\n` +
+        `(or visit ${info.verificationUri} and enter code: ${info.userCode})\n\n`);
+};
+/**
+ * Issue a fresh device code + user code pair.
+ */
+export async function requestDeviceCode(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await fetchImpl(`${opts.baseUrl}/auth/device/code`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ clientId: opts.clientId }),
+        });
+    }
+    catch (e) {
+        throw new DeviceGrantError('network_error', `Failed to reach ${opts.baseUrl}/auth/device/code: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!res.ok) {
+        throw new DeviceGrantError('unknown', `Device-code request failed with HTTP ${res.status}`);
+    }
+    return (await res.json());
+}
+/**
+ * Internal: one polling round-trip. Returns the token bundle on
+ * success, or a sentinel describing why the server isn't ready yet.
+ */
+export async function pollOnce(opts, deviceCode) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await fetchImpl(`${opts.baseUrl}/auth/device/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ deviceCode, clientId: opts.clientId }),
+        });
+    }
+    catch (e) {
+        throw new DeviceGrantError('network_error', `Failed to reach ${opts.baseUrl}/auth/device/token: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (res.ok) {
+        return {
+            kind: 'success',
+            bundle: (await res.json()),
+        };
+    }
+    // RFC 8628 error mapping. Body shape is `{ error, error_description }`
+    // per the backend (Rockhopper's exception filter unwraps it — see
+    // memory `project_backend_badrequest_unwraps_payload`).
+    let body = {};
+    try {
+        body = await res.json();
+    }
+    catch {
+        // Non-JSON error body — fall through to 'unknown'.
+    }
+    switch (body.error) {
+        case 'authorization_pending':
+            return { kind: 'pending' };
+        case 'slow_down':
+            return { kind: 'slow_down' };
+        case 'access_denied':
+            throw new DeviceGrantError('access_denied', body.error_description ?? 'Device code denied.');
+        case 'expired_token':
+            throw new DeviceGrantError('expired_token', body.error_description ?? 'Device code expired before approval.');
+        default:
+            throw new DeviceGrantError('unknown', `Unexpected device-grant error (HTTP ${res.status}): ${body.error ?? 'no error code'}`);
+    }
+}
+/**
+ * Full flow — request code, print to stderr, poll until success or
+ * fatal error. Returns the access-token bundle on success.
+ *
+ * `interval` (seconds, server-supplied) becomes the poll cadence.
+ * `slow_down` responses bump the interval by RFC's recommended +5s.
+ * Total wall time is bounded by the server-supplied `expiresIn`.
+ */
+export async function runDeviceGrantFlow(opts) {
+    const sleep = opts.sleep ?? DEFAULT_SLEEP;
+    const onUserCode = opts.onUserCode ?? DEFAULT_ON_USER_CODE;
+    const code = await requestDeviceCode(opts);
+    onUserCode({
+        userCode: code.userCode,
+        verificationUri: code.verificationUri,
+        verificationUriComplete: code.verificationUriComplete,
+    });
+    let intervalMs = code.interval * 1000;
+    const deadline = Date.now() + code.expiresIn * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const result = await pollOnce(opts, code.deviceCode);
+        if (result.kind === 'success') {
+            return result.bundle;
+        }
+        if (result.kind === 'slow_down') {
+            // RFC 8628 § 3.5 — increase interval by 5s and retry.
+            intervalMs += 5_000;
+        }
+        // 'pending' just continues at the current interval.
+    }
+    throw new DeviceGrantError('expired_token', `Device code expired (waited ${code.expiresIn}s without approval).`);
+}
+//# sourceMappingURL=device-grant-client.js.map

package/dist/auth/device-grant-client.js.map

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

package/dist/auth/resolve-auth.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ENG-1444 / KI-081 — auth resolution for the mcp-server CLI.
+ *
+ * Decides where the bearer token comes from on each launch, in order:
+ *
+ *   1. `ROCKHOPPER_TOKEN` env var — Personal Access Token. Headless /
+ *      CI / scripted scenarios. Same path as pre-OAuth releases.
+ *   2. Stored OAuth bundle in the OS keychain (token-store). The user
+ *      previously completed the device-grant flow; if the access
+ *      token is still valid, use it.
+ *   3. Device-grant flow — issues a fresh code, prints the user code
+ *      + verification URI to stderr, polls for approval, persists the
+ *      resulting bundle to the keychain for next time.
+ *
+ * Returns `{ accessToken, source }` where `source` is one of
+ * `'pat' | 'stored-oauth' | 'device-grant'` for logging / debugging.
+ *
+ * Heavy dependencies (token store, device-grant flow, env reads) are
+ * injectable for tests.
+ */
+import { runDeviceGrantFlow } from './device-grant-client.js';
+import { isExpired as defaultIsExpired, type OAuthTokenBundle } from './token-store.js';
+export type AuthSource = 'pat' | 'stored-oauth' | 'device-grant';
+export interface ResolvedAuth {
+    accessToken: string;
+    source: AuthSource;
+}
+export interface ResolveAuthOptions {
+    baseUrl: string;
+    /** Defaults to `'mcp-stdio'`. */
+    clientId?: string;
+    /** Typically `process.env.ROCKHOPPER_TOKEN`. */
+    patFromEnv?: string;
+    /** Override for tests. */
+    tokenStoreGet?: () => Promise<OAuthTokenBundle | null>;
+    /** Override for tests. */
+    tokenStoreSet?: (bundle: OAuthTokenBundle) => Promise<void>;
+    /** Override for tests. */
+    tokenStoreClear?: () => Promise<void>;
+    /** Override for tests. */
+    isExpiredFn?: typeof defaultIsExpired;
+    /** Override for tests. Defaults to `runDeviceGrantFlow`. */
+    deviceGrantFlow?: typeof runDeviceGrantFlow;
+    /** Optional stderr logger; defaults to `process.stderr.write` line-suffixed. */
+    log?: (msg: string) => void;
+}
+export declare class AuthResolutionError extends Error {
+    readonly code: 'pat_malformed' | 'device_grant_failed' | 'token_store_failure';
+    constructor(code: 'pat_malformed' | 'device_grant_failed' | 'token_store_failure', message: string);
+}
+export declare function resolveAuth(opts: ResolveAuthOptions): Promise<ResolvedAuth>;
+//# sourceMappingURL=resolve-auth.d.ts.map

package/dist/auth/resolve-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-auth.d.ts","sourceRoot":"","sources":["../../src/auth/resolve-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,kBAAkB,EAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,SAAS,IAAI,gBAAgB,EAE7B,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,cAAc,GAAG,cAAc,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACvD,0BAA0B;IAC1B,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,0BAA0B;IAC1B,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,0BAA0B;IAC1B,WAAW,CAAC,EAAE,OAAO,gBAAgB,CAAC;IACtC,4DAA4D;IAC5D,eAAe,CAAC,EAAE,OAAO,kBAAkB,CAAC;IAC5C,gFAAgF;IAChF,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAChB,eAAe,GACf,qBAAqB,GACrB,qBAAqB;gBAHT,IAAI,EAChB,eAAe,GACf,qBAAqB,GACrB,qBAAqB,EACzB,OAAO,EAAE,MAAM;CAKlB;AAKD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,YAAY,CAAC,CAgFvB"}

package/dist/auth/resolve-auth.js

@@ -0,0 +1,100 @@
+/**
+ * ENG-1444 / KI-081 — auth resolution for the mcp-server CLI.
+ *
+ * Decides where the bearer token comes from on each launch, in order:
+ *
+ *   1. `ROCKHOPPER_TOKEN` env var — Personal Access Token. Headless /
+ *      CI / scripted scenarios. Same path as pre-OAuth releases.
+ *   2. Stored OAuth bundle in the OS keychain (token-store). The user
+ *      previously completed the device-grant flow; if the access
+ *      token is still valid, use it.
+ *   3. Device-grant flow — issues a fresh code, prints the user code
+ *      + verification URI to stderr, polls for approval, persists the
+ *      resulting bundle to the keychain for next time.
+ *
+ * Returns `{ accessToken, source }` where `source` is one of
+ * `'pat' | 'stored-oauth' | 'device-grant'` for logging / debugging.
+ *
+ * Heavy dependencies (token store, device-grant flow, env reads) are
+ * injectable for tests.
+ */
+import { DeviceGrantError, runDeviceGrantFlow, } from './device-grant-client.js';
+import { clearTokens as defaultClearTokens, getTokens as defaultGetTokens, isExpired as defaultIsExpired, setTokens as defaultSetTokens, } from './token-store.js';
+const PAT_PREFIX = 'rh_pat_';
+export class AuthResolutionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AuthResolutionError';
+    }
+}
+/* v8 ignore next -- trivial stderr wrapper; tests inject a log stub via `opts.log` */
+const DEFAULT_LOG = (msg) => process.stderr.write(`${msg}\n`);
+export async function resolveAuth(opts) {
+    const clientId = opts.clientId ?? 'mcp-stdio';
+    const log = opts.log ?? DEFAULT_LOG;
+    const tokenStoreGet = opts.tokenStoreGet ?? defaultGetTokens;
+    const tokenStoreSet = opts.tokenStoreSet ?? defaultSetTokens;
+    const tokenStoreClear = opts.tokenStoreClear ?? defaultClearTokens;
+    const isExpiredFn = opts.isExpiredFn ?? defaultIsExpired;
+    const deviceGrantFlow = opts.deviceGrantFlow ?? runDeviceGrantFlow;
+    // 1. PAT env var — takes precedence; matches pre-OAuth behavior.
+    if (opts.patFromEnv) {
+        if (!opts.patFromEnv.startsWith(PAT_PREFIX)) {
+            throw new AuthResolutionError('pat_malformed', `ROCKHOPPER_TOKEN does not look like a valid Personal Access Token. Tokens start with "${PAT_PREFIX}".`);
+        }
+        return { accessToken: opts.patFromEnv, source: 'pat' };
+    }
+    // 2. Stored OAuth bundle.
+    let stored = null;
+    try {
+        stored = await tokenStoreGet();
+    }
+    catch (e) {
+        // Keychain backend missing or locked. Don't abort yet — fall through
+        // to device-grant. If THAT fails too, surface a combined error.
+        log(`Could not read OS keychain (${e instanceof Error ? e.message : String(e)}). Falling back to device-grant flow.`);
+    }
+    if (stored && !isExpiredFn(stored)) {
+        return { accessToken: stored.accessToken, source: 'stored-oauth' };
+    }
+    if (stored) {
+        // Expired bundle — clear it and proceed.
+        try {
+            await tokenStoreClear();
+        }
+        catch {
+            // Non-fatal — overwrite on the upcoming setTokens.
+        }
+    }
+    // 3. Device-grant flow.
+    let bundle;
+    try {
+        bundle = await deviceGrantFlow({
+            baseUrl: opts.baseUrl,
+            clientId,
+        });
+    }
+    catch (e) {
+        if (e instanceof DeviceGrantError) {
+            throw new AuthResolutionError('device_grant_failed', `Device-grant flow failed (${e.code}): ${e.message}`);
+        }
+        throw new AuthResolutionError('device_grant_failed', `Device-grant flow failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // Persist for next launch. Storage failure is non-fatal — the
+    // current token still works, the user just re-runs the flow next
+    // time.
+    try {
+        await tokenStoreSet({
+            accessToken: bundle.accessToken,
+            refreshToken: bundle.refreshToken,
+            expiresAt: Date.now() + bundle.expiresIn * 1000,
+        });
+    }
+    catch (e) {
+        log(`Warning: could not persist OAuth token to OS keychain (${e instanceof Error ? e.message : String(e)}). You may need to re-authenticate on the next launch.`);
+    }
+    return { accessToken: bundle.accessToken, source: 'device-grant' };
+}
+//# sourceMappingURL=resolve-auth.js.map

package/dist/auth/resolve-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-auth.js","sourceRoot":"","sources":["../../src/auth/resolve-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,WAAW,IAAI,kBAAkB,EACjC,SAAS,IAAI,gBAAgB,EAC7B,SAAS,IAAI,gBAAgB,EAC7B,SAAS,IAAI,gBAAgB,GAE9B,MAAM,kBAAkB,CAAC;AAE1B,MAAM,UAAU,GAAG,SAAS,CAAC;AA6B7B,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAE1B;IADlB,YACkB,IAGS,EACzB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QANC,SAAI,GAAJ,IAAI,CAGK;QAIzB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,sFAAsF;AACtF,MAAM,WAAW,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;AAEtE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAwB;IAExB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,WAAW,CAAC;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,WAAW,CAAC;IACpC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,gBAAgB,CAAC;IAC7D,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,gBAAgB,CAAC;IAC7D,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,kBAAkB,CAAC;IACnE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,gBAAgB,CAAC;IACzD,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,kBAAkB,CAAC;IAEnE,iEAAiE;IACjE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,mBAAmB,CAC3B,eAAe,EACf,yFAAyF,UAAU,IAAI,CACxG,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACzD,CAAC;IAED,0BAA0B;IAC1B,IAAI,MAAM,GAA4B,IAAI,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;IACjC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,qEAAqE;QACrE,gEAAgE;QAChE,GAAG,CACD,+BAA+B,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,uCAAuC,CACjH,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,MAAM,EAAE,CAAC;QACX,yCAAyC;QACzC,IAAI,CAAC;YACH,MAAM,eAAe,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,IAAI,MAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,eAAe,CAAC;YAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,gBAAgB,EAAE,CAAC;YAClC,MAAM,IAAI,mBAAmB,CAC3B,qBAAqB,EACrB,6BAA6B,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,EAAE,CACrD,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,mBAAmB,CAC3B,qBAAqB,EACrB,6BAA6B,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAC1E,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,iEAAiE;IACjE,QAAQ;IACR,IAAI,CAAC;QACH,MAAM,aAAa,CAAC;YAClB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,GAAG,IAAI;SAChD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CACD,0DAA0D,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,wDAAwD,CAC7J,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;AACrE,CAAC"}

package/dist/auth/token-store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ENG-1444 / KI-081 — RFC 8628 device-grant token storage.
+ *
+ * Wraps `keytar` to persist OAuth tokens in the OS-native keychain
+ * (Keychain on macOS, Credential Manager on Windows, libsecret on
+ * Linux). The mcp-server is spawned by AI clients (Cursor, Claude
+ * Desktop) and survives across client launches, so tokens must live
+ * outside the process.
+ *
+ * One bundle per machine — there's no multi-user concept inside a
+ * single mcp-server install. If the user re-runs the device-grant
+ * flow, the prior bundle is overwritten.
+ *
+ * Linux without libsecret installed will throw on first keytar call
+ * (the native binding loads but the backend lookup fails). The CLI
+ * surfaces a clear remediation message ("apt-get install
+ * libsecret-tools" etc.) — we do NOT silently fall back to plaintext
+ * file storage. Encrypted file fallback may land in a follow-up.
+ */
+export interface OAuthTokenBundle {
+    accessToken: string;
+    /** Optional — backend does not currently issue refresh tokens (ENG-1446). */
+    refreshToken?: string;
+    /** Epoch milliseconds. Null means "no expiry set" — treat as expired. */
+    expiresAt: number | null;
+}
+/**
+ * Read the persisted OAuth bundle. Returns null if no bundle is stored
+ * OR if the stored value is malformed (corrupted entry — treat as
+ * "no tokens" and let the CLI initiate a fresh device flow).
+ */
+export declare function getTokens(): Promise<OAuthTokenBundle | null>;
+/**
+ * Persist the OAuth bundle, overwriting any prior bundle.
+ */
+export declare function setTokens(bundle: OAuthTokenBundle): Promise<void>;
+/**
+ * Delete any persisted bundle. Safe to call when nothing is stored
+ * (keytar returns false; we ignore the return).
+ */
+export declare function clearTokens(): Promise<void>;
+/**
+ * `true` if `bundle.expiresAt` is in the past (or null). Pure helper —
+ * the device-grant client wires this into its refresh-on-expiry logic.
+ *
+ * A small safety margin (60s by default) treats tokens about to expire
+ * as already expired, so the client refreshes BEFORE the API rejects
+ * the next call.
+ */
+export declare function isExpired(bundle: OAuthTokenBundle, marginMs?: number, now?: number): boolean;
+//# sourceMappingURL=token-store.d.ts.map

package/dist/auth/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../src/auth/token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgDH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAmBlE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvE;AAED;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAGjD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,gBAAgB,EACxB,QAAQ,SAAS,EACjB,GAAG,SAAa,GACf,OAAO,CAGT"}

package/dist/auth/token-store.js

@@ -0,0 +1,98 @@
+/**
+ * ENG-1444 / KI-081 — RFC 8628 device-grant token storage.
+ *
+ * Wraps `keytar` to persist OAuth tokens in the OS-native keychain
+ * (Keychain on macOS, Credential Manager on Windows, libsecret on
+ * Linux). The mcp-server is spawned by AI clients (Cursor, Claude
+ * Desktop) and survives across client launches, so tokens must live
+ * outside the process.
+ *
+ * One bundle per machine — there's no multi-user concept inside a
+ * single mcp-server install. If the user re-runs the device-grant
+ * flow, the prior bundle is overwritten.
+ *
+ * Linux without libsecret installed will throw on first keytar call
+ * (the native binding loads but the backend lookup fails). The CLI
+ * surfaces a clear remediation message ("apt-get install
+ * libsecret-tools" etc.) — we do NOT silently fall back to plaintext
+ * file storage. Encrypted file fallback may land in a follow-up.
+ */
+let _keytar = null;
+let _keytarErr = null;
+async function loadKeytar() {
+    if (_keytar)
+        return _keytar;
+    /* v8 ignore next */
+    if (_keytarErr)
+        throw _keytarErr;
+    try {
+        _keytar = await import('keytar');
+        return _keytar;
+    }
+    catch (e) {
+        /* v8 ignore next 9 -- runtime dlopen failure (Linux without libsecret); the catch can't be reached via vi.mock since the mock factory always resolves successfully. Behavior is covered by the CLI's end-to-end behavior on platforms where the import genuinely fails. */
+        const reason = e instanceof Error ? e.message : String(e);
+        _keytarErr = new Error(`OS keychain unavailable (${reason}). ` +
+            'On Linux, install libsecret (e.g. `apt-get install libsecret-1-dev` on Debian/Ubuntu, ' +
+            '`dnf install libsecret` on Fedora). Or set ROCKHOPPER_TOKEN to a Personal Access Token ' +
+            'to use PAT auth instead of OAuth.');
+        throw _keytarErr;
+    }
+}
+const KEYTAR_SERVICE = 'rockhopper-mcp';
+const KEYTAR_ACCOUNT = 'oauth-tokens';
+/**
+ * Read the persisted OAuth bundle. Returns null if no bundle is stored
+ * OR if the stored value is malformed (corrupted entry — treat as
+ * "no tokens" and let the CLI initiate a fresh device flow).
+ */
+export async function getTokens() {
+    const keytar = await loadKeytar();
+    const raw = await keytar.getPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.accessToken !== 'string')
+            return null;
+        return {
+            accessToken: parsed.accessToken,
+            refreshToken: typeof parsed.refreshToken === 'string'
+                ? parsed.refreshToken
+                : undefined,
+            expiresAt: typeof parsed.expiresAt === 'number' ? parsed.expiresAt : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the OAuth bundle, overwriting any prior bundle.
+ */
+export async function setTokens(bundle) {
+    const keytar = await loadKeytar();
+    await keytar.setPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT, JSON.stringify(bundle));
+}
+/**
+ * Delete any persisted bundle. Safe to call when nothing is stored
+ * (keytar returns false; we ignore the return).
+ */
+export async function clearTokens() {
+    const keytar = await loadKeytar();
+    await keytar.deletePassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+}
+/**
+ * `true` if `bundle.expiresAt` is in the past (or null). Pure helper —
+ * the device-grant client wires this into its refresh-on-expiry logic.
+ *
+ * A small safety margin (60s by default) treats tokens about to expire
+ * as already expired, so the client refreshes BEFORE the API rejects
+ * the next call.
+ */
+export function isExpired(bundle, marginMs = 60_000, now = Date.now()) {
+    if (bundle.expiresAt === null)
+        return true;
+    return bundle.expiresAt - marginMs <= now;
+}
+//# sourceMappingURL=token-store.js.map

package/dist/auth/token-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.js","sourceRoot":"","sources":["../../src/auth/token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAsBH,IAAI,OAAO,GAAwB,IAAI,CAAC;AACxC,IAAI,UAAU,GAAiB,IAAI,CAAC;AAEpC,KAAK,UAAU,UAAU;IACvB,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,oBAAoB;IACpB,IAAI,UAAU;QAAE,MAAM,UAAU,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACjC,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,2QAA2Q;QAC3Q,MAAM,MAAM,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC1D,UAAU,GAAG,IAAI,KAAK,CACpB,4BAA4B,MAAM,KAAK;YACrC,wFAAwF;YACxF,yFAAyF;YACzF,mCAAmC,CACtC,CAAC;QACF,MAAM,UAAU,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,cAAc,GAAG,gBAAgB,CAAC;AACxC,MAAM,cAAc,GAAG,cAAc,CAAC;AAUtC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IACrE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,OAAO,MAAM,EAAE,WAAW,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACzD,OAAO;YACL,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,YAAY,EACV,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ;gBACrC,CAAC,CAAC,MAAM,CAAC,YAAY;gBACrB,CAAC,CAAC,SAAS;YACf,SAAS,EACP,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;SACjE,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAwB;IACtD,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,MAAM,MAAM,CAAC,WAAW,CACtB,cAAc,EACd,cAAc,EACd,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CACvB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,MAAM,MAAM,CAAC,cAAc,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CACvB,MAAwB,EACxB,QAAQ,GAAG,MAAM,EACjB,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAEhB,IAAI,MAAM,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,MAAM,CAAC,SAAS,GAAG,QAAQ,IAAI,GAAG,CAAC;AAC5C,CAAC"}

package/dist/cli.js

@@ -1,22 +1,42 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ApiClient } from './api-client.js';
+import { AuthResolutionError, resolveAuth, } from './auth/resolve-auth.js';
 import { createServer } from './server.js';
 const ROCKHOPPER_API_URL = process.env.ROCKHOPPER_API_URL || 'https://api.rockhopper.co';
-const ROCKHOPPER_TOKEN = process.env.ROCKHOPPER_TOKEN;
-if (!ROCKHOPPER_TOKEN) {
-    console.error('Error: ROCKHOPPER_TOKEN environment variable is required.\n' +
-        'Create a Personal Access Token in Rockhopper Settings and set it as ROCKHOPPER_TOKEN.');
-    process.exit(1);
+// ENG-1444: auth resolution order is
+//   1. ROCKHOPPER_TOKEN env var (Personal Access Token — headless / CI)
+//   2. Stored OAuth bundle in the OS keychain (prior device-grant flow)
+//   3. Device-grant flow (prints code to stderr, polls for approval)
+let resolved;
+try {
+    resolved = await resolveAuth({
+        baseUrl: ROCKHOPPER_API_URL,
+        patFromEnv: process.env.ROCKHOPPER_TOKEN,
+    });
 }
-if (!ROCKHOPPER_TOKEN.startsWith('rh_pat_')) {
-    console.error('Error: ROCKHOPPER_TOKEN does not look like a valid Personal Access Token.\n' +
-        'Tokens start with "rh_pat_". Check that the full token was copied correctly.');
+catch (err) {
+    if (err instanceof AuthResolutionError) {
+        if (err.code === 'pat_malformed') {
+            console.error(`Error: ${err.message}`);
+            console.error('Tokens start with "rh_pat_". Check that the full token was copied correctly.');
+        }
+        else if (err.code === 'device_grant_failed') {
+            console.error(`Error: Could not complete sign-in.\n${err.message}`);
+            console.error('You can also set ROCKHOPPER_TOKEN to a Personal Access Token (Settings → Personal Access Tokens) and re-launch.');
+        }
+        else {
+            console.error(`Error: ${err.message}`);
+        }
+    }
+    else {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    }
     process.exit(1);
 }
 const apiClient = new ApiClient({
     baseUrl: ROCKHOPPER_API_URL,
-    token: ROCKHOPPER_TOKEN,
+    token: resolved.accessToken,
 });
 try {
     await apiClient.getMe();
@@ -24,8 +44,14 @@ try {
 catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes('401') || msg.includes('403')) {
-        console.error('Error: ROCKHOPPER_TOKEN is invalid or expired.\n' +
-            'Create a new Personal Access Token in Rockhopper Settings and set it as ROCKHOPPER_TOKEN.');
+        if (resolved.source === 'pat') {
+            console.error('Error: ROCKHOPPER_TOKEN is invalid or expired.\n' +
+                'Create a new Personal Access Token in Rockhopper Settings and set it as ROCKHOPPER_TOKEN.');
+        }
+        else {
+            console.error(`Error: Stored OAuth token is invalid (source: ${resolved.source}).\n` +
+                'Re-launch the MCP server — it will run the device-grant flow again.');
+        }
     }
     else {
         console.error(`Error: Could not reach Rockhopper API at ${ROCKHOPPER_API_URL}.\n` +

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,kBAAkB,GACtB,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,2BAA2B,CAAC;AAChE,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;AAEtD,IAAI,CAAC,gBAAgB,EAAE,CAAC;IACtB,OAAO,CAAC,KAAK,CACX,6DAA6D;QAC3D,uFAAuF,CAC1F,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;IAC5C,OAAO,CAAC,KAAK,CACX,6EAA6E;QAC3E,8EAA8E,CACjF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC;IAC9B,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAE,gBAAgB;CACxB,CAAC,CAAC;AAEH,IAAI,CAAC;IACH,MAAM,SAAS,CAAC,KAAK,EAAE,CAAC;AAC1B,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,CAAC,KAAK,CACX,kDAAkD;YAChD,2FAA2F,CAC9F,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CACX,4CAA4C,kBAAkB,KAAK;YACjE,YAAY,GAAG,EAAE,CACpB,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AAEvC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EACL,mBAAmB,EACnB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,kBAAkB,GACtB,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,2BAA2B,CAAC;AAEhE,qCAAqC;AACrC,wEAAwE;AACxE,wEAAwE;AACxE,qEAAqE;AACrE,IAAI,QAAQ,CAAC;AACb,IAAI,CAAC;IACH,QAAQ,GAAG,MAAM,WAAW,CAAC;QAC3B,OAAO,EAAE,kBAAkB;QAC3B,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;KACzC,CAAC,CAAC;AACL,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,IAAI,GAAG,YAAY,mBAAmB,EAAE,CAAC;QACvC,IAAI,GAAG,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACvC,OAAO,CAAC,KAAK,CACX,8EAA8E,CAC/E,CAAC;QACJ,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,qBAAqB,EAAE,CAAC;YAC9C,OAAO,CAAC,KAAK,CAAC,uCAAuC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACpE,OAAO,CAAC,KAAK,CACX,iHAAiH,CAClH,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CACX,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC;IAC9B,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAE,QAAQ,CAAC,WAAW;CAC5B,CAAC,CAAC;AAEH,IAAI,CAAC;IACH,MAAM,SAAS,CAAC,KAAK,EAAE,CAAC;AAC1B,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YAC9B,OAAO,CAAC,KAAK,CACX,kDAAkD;gBAChD,2FAA2F,CAC9F,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CACX,iDAAiD,QAAQ,CAAC,MAAM,MAAM;gBACpE,qEAAqE,CACxE,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CACX,4CAA4C,kBAAkB,KAAK;YACjE,YAAY,GAAG,EAAE,CACpB,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AAEvC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/dist/prompts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CA4MvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAuNvE"}

package/dist/prompts/index.js

@@ -7,17 +7,20 @@ export function registerPrompts(server, api) {
             fileMsId: z.string().describe('Platform ID of the enrolled file'),
         },
     }, async ({ fileMsId }) => {
-        const [file, versions, changes] = await Promise.all([
+        const [file, versions, changesPage] = await Promise.all([
             api.getEnrolledFile(fileMsId),
             api.getFileVersions(fileMsId),
-            api.getUnattributedChanges(fileMsId),
+            // KI-097: switched to cursor-paginated route. Top-of-prompt summary
+            // uses `totalCount` for the full file count; the per-cell preview
+            // uses up to 20 rows from this first page (sufficient for a recap).
+            api.getUnattributedChangesPaginated(fileMsId),
         ]);
         const recentVersions = versions.slice(0, 5);
         const versionSummary = recentVersions
             .map((v) => `- v${v.majorVersion}.${v.minorVersion}.${v.patchVersion}: ${v.description || 'No description'} (${v.createdAt})`)
             .join('\n');
-        const changeSummary = changes.length
-            ? changes
+        const changeSummary = changesPage.changes.length
+            ? changesPage.changes
                 .slice(0, 20)
                 .map((c) => `- ${c.sheetName}!${c.cellAddress}: ${JSON.stringify(c.oldValue)} → ${JSON.stringify(c.newValue)}`)
                 .join('\n')
@@ -30,7 +33,7 @@ export function registerPrompts(server, api) {
                         type: 'text',
                         text: `Summarize the recent activity on the file "${file.name}".\n\n` +
                             `## Recent Versions (last ${recentVersions.length} of ${versions.length})\n${versionSummary}\n\n` +
-                            `## Unattributed Changes (${changes.length} total)\n${changeSummary}\n\n` +
+                            `## Unattributed Changes (${changesPage.totalCount} total)\n${changeSummary}\n\n` +
                             `Provide a concise summary of what has changed recently, who made changes, and any notable patterns.`,
                     },
                 },
@@ -115,11 +118,14 @@ export function registerPrompts(server, api) {
             fileMsId: z.string().describe('Platform ID of the enrolled file'),
         },
     }, async ({ fileMsId }) => {
-        const [file, versions, comments, changes] = await Promise.all([
+        const [file, versions, comments, changesPage] = await Promise.all([
             api.getEnrolledFile(fileMsId),
             api.getFileVersions(fileMsId),
             api.getFileComments(fileMsId),
-            api.getUnattributedChanges(fileMsId),
+            // KI-097: switched to cursor-paginated route. The file-overview
+            // prompt only displays a total count, so we use `totalCount` from
+            // the first page — no need to fetch every row.
+            api.getUnattributedChangesPaginated(fileMsId),
         ]);
         const latestVersion = versions[0];
         let reviews = [];
@@ -127,7 +133,12 @@ export function registerPrompts(server, api) {
             reviews = await api.getReviewsForVersion(latestVersion.internalId);
         }
         const unresolvedComments = comments.filter((c) => !c.resolved);
-        const pendingReviews = reviews.filter((r) => r.status !== 'approved' && r.status !== 'rejected');
+        // Backend's ReviewRequestStatus enum is uppercase (PENDING/APPROVED/CANCELLED).
+        // Prior code compared against lowercase 'approved' and a nonexistent 'rejected',
+        // so APPROVED + CANCELLED reviews were silently classified as pending (sibling
+        // of KI-099). Match positive intent — "pending = PENDING" — with defensive
+        // .toUpperCase() so the check survives future backend casing flips.
+        const pendingReviews = reviews.filter((r) => r.status?.toUpperCase() === 'PENDING');
         return {
             messages: [
                 {
@@ -145,7 +156,7 @@ export function registerPrompts(server, api) {
                                 : 'No versions yet.\n') +
                             `\n## Comments: ${comments.length} total, ${unresolvedComments.length} unresolved\n` +
                             `## Reviews: ${reviews.length} total, ${pendingReviews.length} pending\n` +
-                            `## Unattributed Changes: ${changes.length}\n\n` +
+                            `## Unattributed Changes: ${changesPage.totalCount}\n\n` +
                             `Provide a status report highlighting anything that needs attention.`,
                     },
                 },