@quenty/nevermore-cli 4.43.4 → 4.44.0

package/src/utils/open-cloud/open-cloud-client.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as fs from 'fs/promises';
-import { OpenCloudClient } from './open-cloud-client.js';
+import {
+  OpenCloudClient,
+  getTaskReturnValues,
+  type LuauTask,
+} from './open-cloud-client.js';
 import type { RateLimiter } from './rate-limiter.js';
 
 vi.mock('@quenty/cli-output-helpers', () => ({
@@ -367,3 +371,153 @@ describe('OpenCloudClient.resolveLatestPlaceVersionAsync', () => {
     ).rejects.toThrowError(/unparseable version path/);
   });
 });
+
+describe('getTaskReturnValues', () => {
+  function makeTask(overrides: Partial<LuauTask>): LuauTask {
+    return {
+      path: 'universes/1/places/2/versions/3/luau-execution-session-tasks/4',
+      createTime: '2026-01-01T00:00:00Z',
+      updateTime: '2026-01-01T00:01:00Z',
+      user: 'users/1',
+      state: 'COMPLETE',
+      script: 'return 1',
+      ...overrides,
+    };
+  }
+
+  it('returns the values natively typed, one entry per returned value', () => {
+    // Roblox serializes the return value itself, so a returned table arrives as
+    // real nested JSON — there is no JSON string to parse a second time.
+    const task = makeTask({
+      output: {
+        results: [{ slug: 'maid', counts: { passed: 1014 } }, 'str', 42, true],
+      },
+    });
+
+    expect(getTaskReturnValues(task)).toEqual([
+      { slug: 'maid', counts: { passed: 1014 } },
+      'str',
+      42,
+      true,
+    ]);
+  });
+
+  it('reports an empty result when the task returned nothing', () => {
+    expect(getTaskReturnValues(makeTask({ output: {} }))).toEqual([]);
+  });
+
+  it('reports undefined when a failed task carried no output at all', () => {
+    // An oversize return value fails the task with no output and no error
+    // message, so "nothing came back to read" has to stay distinguishable from
+    // "the script returned nothing" — only the former can fall back to logs.
+    const task = makeTask({ state: 'FAILED', output: undefined });
+
+    expect(getTaskReturnValues(task)).toBeUndefined();
+  });
+});
+
+describe('OpenCloudClient.getRawTaskLogsAsync', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  /**
+   * Page the logs endpoint the way the real one does: many messages inside each
+   * `luauExecutionSessionTaskLog`, and pagination over those entries rather than
+   * over messages.
+   */
+  function makeLogsLimiter(
+    pages: Array<Array<string[]>>,
+    urls: string[] = []
+  ): RateLimiter {
+    return {
+      fetchAsync: vi.fn(async (url: string | URL) => {
+        urls.push(String(url));
+        const page = pages[urls.length - 1] ?? [];
+        return new Response(
+          JSON.stringify({
+            luauExecutionSessionTaskLogs: page.map((messages) => ({
+              structuredMessages: messages.map((message) => ({
+                message,
+                createTime: '2026-08-27T00:00:00.38Z',
+                messageType: 'OUTPUT',
+              })),
+            })),
+            ...(urls.length < pages.length
+              ? { nextPageToken: `token-${urls.length}` }
+              : {}),
+          }),
+          { status: 200 }
+        );
+      }),
+    } as unknown as RateLimiter;
+  }
+
+  it('counts pages, entries and messages separately', async () => {
+    // Entries are not lines: the endpoint's page size applies to the log
+    // objects, each of which carries many messages. Conflating the two reads a
+    // 2-entry response as a 2-line run.
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeLogsLimiter([[['a', 'b', 'c'], ['d']], [['e', 'f']]]),
+    });
+
+    const fetched = await client.getRawTaskLogsAsync('universes/1/tasks/2');
+
+    expect(fetched.text).toBe('a\nb\nc\nd\ne\nf');
+    expect(fetched.stats).toEqual({
+      requests: 2,
+      pages: 2,
+      entries: 3,
+      messages: 6,
+      chars: 11,
+    });
+  });
+
+  it('counts every attempt when empty logs were retried', async () => {
+    // The retry is invisible in the text it eventually returns, so a run whose
+    // logs only showed up on the third ask looks exactly like one that answered
+    // immediately. It is the difference between a slow API and a silent run.
+    vi.spyOn(global, 'setTimeout').mockImplementation((fn: () => void) => {
+      fn();
+      return 0 as unknown as NodeJS.Timeout;
+    });
+
+    // One unpaged response per attempt: two empty, then the logs. A limiter
+    // that pages would fold all three into a single attempt and prove nothing.
+    let attempt = 0;
+    const rateLimiter = {
+      fetchAsync: vi.fn(async () => {
+        attempt++;
+        return new Response(
+          JSON.stringify({
+            luauExecutionSessionTaskLogs:
+              attempt < 3
+                ? []
+                : [
+                    {
+                      structuredMessages: [
+                        {
+                          message: 'late',
+                          createTime: '2026-08-27T00:00:00.38Z',
+                          messageType: 'OUTPUT',
+                        },
+                      ],
+                    },
+                  ],
+          }),
+          { status: 200 }
+        );
+      }),
+    } as unknown as RateLimiter;
+
+    const client = new OpenCloudClient({ apiKey: 'test-key', rateLimiter });
+
+    const fetched = await client.getRawTaskLogsAsync('universes/1/tasks/2');
+
+    expect(fetched.text).toBe('late');
+    expect(fetched.stats.requests).toBe(3);
+    expect(fetched.stats.pages).toBe(1);
+    expect(fetched.stats.messages).toBe(1);
+  });
+});

package/src/utils/open-cloud/open-cloud-client.ts

@@ -7,6 +7,30 @@ import {
   parseTestLogs,
   type ParsedTestLogs,
 } from '../testing/test-log-parser.js';
+import { type LogFetchStats } from '../testing/log-fetch-stats.js';
+
+/**
+ * One engine message, with the severity Open Cloud reported for it.
+ *
+ * A message is not a line: an error arrives with its whole traceback attached,
+ * so `message` can span several. `messageType` is OUTPUT, WARNING or ERROR.
+ */
+export interface TaskLogMessage {
+  message: string;
+  messageType?: string;
+}
+
+/** A task's log text together with what the fetch had to do to collect it. */
+export interface TaskLogFetch {
+  text: string;
+  stats: LogFetchStats;
+  /**
+   * The same output as `text`, still split into typed messages. Kept because
+   * severity is the API's to state and cannot be recovered from the joined
+   * text: a traceback's continuation lines look like ordinary output.
+   */
+  messages: TaskLogMessage[];
+}
 
 export interface LuauTask {
   path: string;
@@ -22,12 +46,38 @@ export interface LuauTask {
     | 'FAILED';
   script: string;
   timeout?: string;
-  /** Script return value (populated on COMPLETE). */
-  output?: { results?: Array<{ value?: string }> };
+  /**
+   * What the script returned, populated on COMPLETE. `results` is a flat array
+   * of the returned values — `return t, "s", 42` arrives as three entries —
+   * natively typed: Roblox serializes them itself, so a returned Lua table is
+   * real nested JSON here, not a JSON string. (Which is also why a script must
+   * not JSONEncode its result: that lands as a double-encoded string.)
+   *
+   * Absent whenever the task produced no result. A FAILED task carries no
+   * `output` at all, with no error message explaining why — and an oversize
+   * return value (~4MB observed; ~2MB still arrives complete) fails the task
+   * exactly that way rather than truncating the value.
+   */
+  output?: { results?: unknown[] };
   /** Error details (populated on FAILED). */
   error?: { code?: string; message?: string };
 }
 
+/**
+ * The values a finished task's script returned, or `undefined` when the task
+ * reported no result at all.
+ *
+ * The distinction matters: `undefined` means nothing came back to read, so a
+ * caller can fall back to the task's logs, while `[]` means the task did report
+ * a result and the script returned nothing — no fallback will find more.
+ */
+export function getTaskReturnValues(task: LuauTask): unknown[] | undefined {
+  if (!task.output) {
+    return undefined;
+  }
+  return task.output.results ?? [];
+}
+
 export interface OpenCloudClientOptions {
   apiKey: string | (() => Promise<string>);
   rateLimiter: RateLimiter;
@@ -316,22 +366,32 @@ export class OpenCloudClient {
 
   async getTaskLogsAsync(taskPath: string): Promise<ParsedTestLogs> {
     const raw = await this.getRawTaskLogsAsync(taskPath);
-    return parseTestLogs(raw);
+    return parseTestLogs(raw.text);
   }
 
   /**
-   * Fetch raw log text from a completed Luau execution task.
+   * Fetch raw log text from a completed Luau execution task, along with the
+   * shape of the fetch that produced it.
+   *
    * Retries a few times if the API returns empty logs, since the test runner
-   * always produces at least some output.
+   * always produces at least some output. The reported `requests` count spans
+   * every attempt, so a fetch that only filled in on its third try says so.
    */
-  async getRawTaskLogsAsync(taskPath: string): Promise<string> {
+  async getRawTaskLogsAsync(taskPath: string): Promise<TaskLogFetch> {
     const maxAttempts = 3;
     const retryDelayMs = 1000;
+    let requests = 0;
 
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      const logs = await this._fetchRawLogsAsync(taskPath);
-      if (logs || attempt === maxAttempts) {
-        return logs;
+      const fetched = await this._fetchRawLogsAsync(taskPath);
+      requests += fetched.stats.requests;
+
+      if (fetched.text || attempt === maxAttempts) {
+        return {
+          text: fetched.text,
+          stats: { ...fetched.stats, requests },
+          messages: fetched.messages,
+        };
       }
       await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
     }
@@ -340,12 +400,12 @@ export class OpenCloudClient {
     return this._fetchRawLogsAsync(taskPath);
   }
 
-  private async _fetchRawLogsAsync(taskPath: string): Promise<string> {
+  private async _fetchRawLogsAsync(taskPath: string): Promise<TaskLogFetch> {
     const apiKey = await this._resolveApiKeyAsync();
     // Arrival order, deliberately. Do not sort by createTime: every print in a
     // single frame shares one value, so it cannot order them anyway, and the
     // fractional digit count varies, so comparing the strings reorders them.
-    const messages: string[] = [];
+    const messages: TaskLogMessage[] = [];
     let pageToken: string | undefined;
     let pagesFetched = 0;
     let entriesFetched = 0;
@@ -383,9 +443,16 @@ export class OpenCloudClient {
 
       for (const entry of data.luauExecutionSessionTaskLogs ?? []) {
         if (entry.structuredMessages?.length) {
-          messages.push(...entry.structuredMessages.map((msg) => msg.message));
+          messages.push(
+            ...entry.structuredMessages.map((msg) => ({
+              message: msg.message,
+              messageType: msg.messageType,
+            }))
+          );
         } else if (entry.messages?.length) {
-          messages.push(...entry.messages);
+          // The flat view carries no severity, which stays absent rather than
+          // being guessed at.
+          messages.push(...entry.messages.map((message) => ({ message })));
         }
       }
 
@@ -394,17 +461,26 @@ export class OpenCloudClient {
       pageToken = data.nextPageToken || undefined;
     } while (pageToken);
 
-    const text = messages.join('\n');
+    const text = messages.map((entry) => entry.message).join('\n');
+
+    const stats: LogFetchStats = {
+      requests: pagesFetched,
+      pages: pagesFetched,
+      entries: entriesFetched,
+      messages: messages.length,
+      chars: text.length,
+    };
 
     // Log volume is the prime suspect when engine output goes missing between
     // the task and the parser, and the parser cannot tell a short run from a
-    // truncated fetch. Record what arrived so a real run can settle it.
+    // truncated fetch. Handed out with the text rather than only printed, so
+    // the diagnostic that finds the output missing can say what the fetch saw.
     OutputHelper.verbose(
-      `[open-cloud] Task logs: ${pagesFetched} page(s), ${entriesFetched} entries, ` +
-        `${messages.length} messages, ${text.length} chars`
+      `[open-cloud] Task logs: ${stats.pages} page(s), ${stats.entries} entries, ` +
+        `${stats.messages} messages, ${stats.chars} chars`
     );
 
-    return text;
+    return { text, stats, messages };
   }
 
   /**

package/src/utils/open-cloud/open-cloud-logs.characterization.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Characterization tests for how Open Cloud actually delivers a Luau execution
+ * task's logs and return value. Nothing here tests our code: every assertion is
+ * a claim about Roblox's behaviour that our log handling is built on, written
+ * so the claim fails out loud if Roblox changes it.
+ *
+ * These claims decide real things — whether a truncated run is worth
+ * re-fetching, whether `maxPageSize` is worth sending, whether a batch package
+ * with no output was dropped or never ran — and none of them are documented by
+ * Roblox. Prose in a gotchas file cannot notice when it goes stale. This can.
+ *
+ * Disabled by default: it spends real Open Cloud quota. To run it:
+ *
+ *   NEVERMORE_CHARACTERIZATION=1 npm test -- open-cloud-logs
+ *
+ * It reads the key through the same credential store the CLI uses, so
+ * `nevermore auth login` is the only setup. The universe and place default to
+ * the nevermore-test-runner test target and can be pointed elsewhere with
+ * NEVERMORE_CHARACTERIZATION_UNIVERSE / _PLACE.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { loadStoredApiKeyAsync } from '@quenty/nevermore-cli-helpers';
+import {
+  OpenCloudClient,
+  getTaskReturnValues,
+  type LuauTask,
+} from './open-cloud-client.js';
+import { RateLimiter } from './rate-limiter.js';
+
+const ENABLED = process.env.NEVERMORE_CHARACTERIZATION === '1';
+
+/** The nevermore-test-runner test target, which exists to be run against. */
+const UNIVERSE_ID = Number(
+  process.env.NEVERMORE_CHARACTERIZATION_UNIVERSE ?? 9716264427
+);
+const PLACE_ID = Number(
+  process.env.NEVERMORE_CHARACTERIZATION_PLACE ?? 138951894938783
+);
+
+const LINES_THAT_FIT = 5_000;
+const LINES_AT_CAPACITY = 8_000;
+const LINES_THAT_OVERFLOW_LESS = 10_000;
+const LINES_THAT_OVERFLOW = 20_000;
+
+/**
+ * Retention is bounded by memory, and each retained message costs this many
+ * bytes beyond its own text — timestamp, type and framing. Derived by holding
+ * the print count at 20,000 and varying only the payload width, then solving
+ * `chars + k * messages` for the k that makes that budget constant.
+ */
+const PER_MESSAGE_OVERHEAD_BYTES = 47;
+
+/** A printed line that names its own position, so survivors identify themselves. */
+const SEQ = new RegExp('^SEQ (' + String.raw`\d` + '+)');
+
+describe.runIf(ENABLED)('Open Cloud task log delivery', () => {
+  let client: OpenCloudClient;
+  let placeVersion: number;
+
+  beforeAll(async () => {
+    const apiKey = await loadStoredApiKeyAsync();
+    if (!apiKey) {
+      throw new Error(
+        'No stored Open Cloud API key. Run `nevermore auth login` first.'
+      );
+    }
+
+    client = new OpenCloudClient({ apiKey, rateLimiter: new RateLimiter() });
+    placeVersion = await client.resolveLatestPlaceVersionAsync(
+      UNIVERSE_ID,
+      PLACE_ID,
+      'saved'
+    );
+  }, 120_000);
+
+  /**
+   * Run a task printing `lines` numbered messages, each optionally padded to
+   * widen it, and report what came back.
+   */
+  async function printLinesAsync(lines: number, padChars = 0) {
+    const script = padChars
+      ? `local pad = string.rep("p", ${padChars}) for i = 1, ${lines} do print("SEQ " .. i .. " " .. pad) end`
+      : `for i = 1, ${lines} do print("SEQ " .. i) end`;
+
+    const task = await client.createExecutionTaskAsync(
+      UNIVERSE_ID,
+      PLACE_ID,
+      placeVersion,
+      script,
+      300_000
+    );
+    const completed = await client.pollTaskCompletionAsync(task.path);
+    expect(completed.state).toBe('COMPLETE');
+
+    const fetched = await client.getRawTaskLogsAsync(completed.path);
+    const seq = fetched.text
+      .split('\n')
+      .map((line) => SEQ.exec(line.trim())?.[1])
+      .filter((n): n is string => n !== undefined)
+      .map(Number);
+
+    return { task: completed, ...fetched, seq };
+  }
+
+  /** Bytes the buffer spent on what it kept, per-message overhead included. */
+  function retainedBudget(run: { stats: { chars: number; messages: number } }) {
+    return run.stats.chars + PER_MESSAGE_OVERHEAD_BYTES * run.stats.messages;
+  }
+
+  it('delivers a small run complete and in order', async () => {
+    const run = await printLinesAsync(LINES_THAT_FIT);
+
+    expect(run.seq).toHaveLength(LINES_THAT_FIT);
+    expect(run.seq[0]).toBe(1);
+    expect(run.seq[run.seq.length - 1]).toBe(LINES_THAT_FIT);
+    // Arrival order is chronological, so no client-side sort is needed — and
+    // sorting by createTime would be wrong, since a whole frame shares one.
+    expect(run.seq).toEqual([...run.seq].sort((a, b) => a - b));
+  }, 300_000);
+
+  it('truncates a large run by dropping the head, keeping a contiguous tail', async () => {
+    // Says a short log is missing output rather than proof a run printed
+    // little, and rules out the loss being a page we failed to request — an
+    // unrequested page would have held the head. It is why the batch parser
+    // closes sections on their END marker.
+    const run = await printLinesAsync(LINES_THAT_OVERFLOW);
+
+    expect(run.seq.length).toBeLessThan(LINES_THAT_OVERFLOW);
+    expect(run.seq[run.seq.length - 1]).toBe(LINES_THAT_OVERFLOW);
+    expect(run.seq[0]).toBeGreaterThan(1);
+    expect(run.seq).toEqual(
+      Array.from({ length: run.seq.length }, (_, i) => run.seq[0] + i)
+    );
+  }, 300_000);
+
+  it('bounds retention by memory, not by number of print calls', async () => {
+    // Both runs make exactly the same number of print calls. If the buffer held
+    // a fixed number of messages they would retain the same count; the padded
+    // one keeps a small fraction of it, so the budget is bytes.
+    const narrow = await printLinesAsync(LINES_THAT_OVERFLOW);
+    const wide = await printLinesAsync(LINES_THAT_OVERFLOW, 500);
+
+    expect(wide.stats.messages).toBeLessThan(narrow.stats.messages / 5);
+    expect(wide.stats.chars).toBeGreaterThan(narrow.stats.chars);
+
+    // And it is one budget in both: bytes kept, plus a fixed cost per message,
+    // lands on the same number however wide the messages are. ~450 KB.
+    expect(retainedBudget(wide)).toBeGreaterThan(retainedBudget(narrow) * 0.95);
+    expect(retainedBudget(wide)).toBeLessThan(retainedBudget(narrow) * 1.05);
+    expect(retainedBudget(narrow)).toBeGreaterThan(400_000);
+    expect(retainedBudget(narrow)).toBeLessThan(500_000);
+  }, 300_000);
+
+  it('keeps the same amount however much is printed, at one message width', async () => {
+    // The corollary: at a fixed message size, printing twice as much does not
+    // get twice as much back. A long run cannot be made to report itself by
+    // printing more carefully, which is why counts travel in the return value.
+    const atCapacity = await printLinesAsync(LINES_AT_CAPACITY);
+    expect(atCapacity.seq).toHaveLength(LINES_AT_CAPACITY);
+
+    const over = await printLinesAsync(LINES_THAT_OVERFLOW_LESS);
+    const wayOver = await printLinesAsync(LINES_THAT_OVERFLOW);
+
+    expect(over.seq.length).toBeLessThan(LINES_THAT_OVERFLOW_LESS);
+    expect(wayOver.seq.length).toBeLessThan(LINES_THAT_OVERFLOW);
+    expect(wayOver.seq.length).toBeGreaterThan(over.seq.length * 0.9);
+    expect(wayOver.seq.length).toBeLessThan(over.seq.length * 1.1);
+  }, 300_000);
+
+  it('returns only what the task printed, with nothing of its own mixed in', async () => {
+    // Rules out engine or internal messages taking room in the buffer: every
+    // message that came back is one of ours, so a retained count short of a
+    // round number is the byte budget, not foreign output.
+    const run = await printLinesAsync(LINES_THAT_OVERFLOW);
+
+    expect(run.seq).toHaveLength(run.stats.messages);
+  }, 300_000);
+
+  it('delivers the same messages structured or flat, and never a second page', async () => {
+    // Why we send no maxPageSize, and why the view is a free choice: asking for
+    // 10 still returns the whole window in one page. A page size that counted
+    // messages would cap this at 10 and hand back a token for the rest.
+    const run = await printLinesAsync(LINES_THAT_OVERFLOW);
+
+    const structured = await fetchOnePageAsync(run.task.path, {
+      view: 'STRUCTURED',
+    });
+    const flat = await fetchOnePageAsync(run.task.path, {});
+
+    // Same messages in the same order — the view changes the envelope, not the
+    // delivery.
+    expect(flat.messages).toEqual(structured.messages);
+    expect(structured.messages).toHaveLength(run.stats.messages);
+
+    const variants: Array<Record<string, string>> = [
+      { view: 'STRUCTURED', maxPageSize: '10' },
+      { view: 'STRUCTURED', maxPageSize: '100' },
+      { maxPageSize: '10' },
+    ];
+
+    for (const params of variants) {
+      const page = await fetchOnePageAsync(run.task.path, params);
+      expect(page.nextPageToken).toBeUndefined();
+      expect(page.messages).toEqual(structured.messages);
+    }
+  }, 300_000);
+
+  it('delivers a large return value, but drops the task entirely past a limit', async () => {
+    // Why the returned failure list is capped rather than trusted to arrive: an
+    // oversize return value does not come back truncated, it takes the whole
+    // run with it — and such a task carries no output and no message saying so,
+    // which is why "nothing came back" must stay distinguishable from "the
+    // script returned nothing".
+    const twoMegabytes = await returnStringAsync(2 * 1024 * 1024);
+    expect(twoMegabytes.state).toBe('COMPLETE');
+    expect(getTaskReturnValues(twoMegabytes)).toHaveLength(1);
+
+    const fiveMegabytes = await returnStringAsync(5 * 1024 * 1024);
+    expect(fiveMegabytes.state).not.toBe('COMPLETE');
+    expect(getTaskReturnValues(fiveMegabytes)).toBeUndefined();
+  }, 300_000);
+
+  /** Run a task returning a string of `bytes`, and wait for whatever happens. */
+  async function returnStringAsync(bytes: number): Promise<LuauTask> {
+    const task = await client.createExecutionTaskAsync(
+      UNIVERSE_ID,
+      PLACE_ID,
+      placeVersion,
+      `return string.rep("x", ${bytes})`,
+      300_000
+    );
+
+    // Returns on any terminal state, failure included — which is one of the
+    // outcomes under test here, not an error.
+    return client.pollTaskCompletionAsync(task.path);
+  }
+
+  /**
+   * One raw request, bypassing the client so the query can be varied. Returns
+   * only what the claims above are about.
+   */
+  async function fetchOnePageAsync(
+    taskPath: string,
+    params: Record<string, string>
+  ): Promise<{ nextPageToken?: string; messages: string[] }> {
+    const apiKey = (await loadStoredApiKeyAsync())!;
+    const url = new URL(`https://apis.roblox.com/cloud/v2/${taskPath}/logs`);
+    for (const [key, value] of Object.entries(params)) {
+      url.searchParams.set(key, value);
+    }
+
+    const response = await fetch(url.toString(), {
+      headers: { 'X-API-Key': apiKey },
+    });
+    expect(response.ok).toBe(true);
+
+    const data = (await response.json()) as {
+      luauExecutionSessionTaskLogs?: Array<{
+        messages?: string[];
+        structuredMessages?: Array<{ message: string }>;
+      }>;
+      nextPageToken?: string;
+    };
+
+    const messages: string[] = [];
+    for (const entry of data.luauExecutionSessionTaskLogs ?? []) {
+      if (entry.structuredMessages?.length) {
+        messages.push(...entry.structuredMessages.map((m) => m.message));
+      } else if (entry.messages?.length) {
+        messages.push(...entry.messages);
+      }
+    }
+
+    return { nextPageToken: data.nextPageToken || undefined, messages };
+  }
+});

package/src/utils/package-manager-utils.test.ts

@@ -106,6 +106,33 @@ describe('package-manager-utils', () => {
       expect(await detectPackageManagerAsync(root)).toBe('pnpm');
     });
 
+    it('ignores a lockfile sitting in the home directory', async () => {
+      // npm leaves a package-lock.json behind after one `npm install` run in a
+      // home directory, and walking to the filesystem root adopted it — every
+      // project below it then installed with the one tool that rejects this
+      // repo's `workspace:` ranges. This test was the symptom: the temp dir
+      // lives under the home directory on Windows, so "defaults to pnpm" here
+      // failed on a machine that had one and passed everywhere else.
+      const home = await fs.realpath(os.homedir());
+      const marker = path.join(home, 'package-lock.json');
+      const alreadyThere = await fs
+        .access(marker)
+        .then(() => true)
+        .catch(() => false);
+
+      if (!alreadyThere) {
+        await fs.writeFile(marker, '{}');
+      }
+
+      try {
+        expect(await detectPackageManagerAsync(root)).toBe('pnpm');
+      } finally {
+        if (!alreadyThere) {
+          await fs.rm(marker, { force: true });
+        }
+      }
+    });
+
     it('still honors an npm project', async () => {
       await writeFileAsync('package.json', JSON.stringify({ name: 'game' }));
       await writeFileAsync('package-lock.json', '{}');