[world][web][cli] o11y: window-aware runs listing

.changeset/cli-runs-time-window.md

@@ -0,0 +1,5 @@
+---
+'@workflow/cli': patch
+---
+
+Add `--since`/`--until` to `workflow inspect runs`; `workflow start` and bulk `workflow cancel` name lookups now search past the backend's default 24h window.

.changeset/web-runs-infinite-scroll.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web': patch
+---
+
+Runs list: infinite scroll with SWR-cached pages (tab switches no longer refetch), a plan-aware time-window picker (default 24h), and status filtering without requiring a workflow filter.

.changeset/world-analytics-time-window.md

@@ -0,0 +1,6 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+---
+
+Support `startTime`/`endTime` on `world.analytics.runs.list` to bound the listing window.

packages/cli/src/commands/cancel.ts

@@ -13,6 +13,7 @@ import {
 } from '../lib/inspect/errors.js';
 import { cliFlags } from '../lib/inspect/flags.js';
 import { setupCliWorld } from '../lib/inspect/setup.js';
+import { planWindowStartFromResponse } from '../lib/inspect/time-window.js';
 
 export default class Cancel extends BaseCommand {
  static description =
@@ -110,18 +111,38 @@ export default class Cancel extends BaseCommand {
  // Fetch matching runs. Only metadata is needed to display and cancel, so
  // prefer the analytics read path when the backend provides one.
  const status = flags.status as WorkflowRun['status'] | undefined;
- const runList = world.analytics
- ? await world.analytics.runs.list({
+ const limit = flags.limit || 50;
+ const analytics = world.analytics;
+ const fetchMatches = async () => {
+ if (!analytics) {
+ return world.runs.list({
  status,
  workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
- })
- : await world.runs.list({
- status,
- workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
+ pagination: { limit },
  resolveData: 'none',
  });
+ }
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend), but bulk cancel must match
+ // across the plan's whole observability window — a run can sleep or
+ // wait on a hook for days without emitting recent events. Probe for
+ // the plan window bounds first, then match across them.
+ const probe = await analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ pagination: { limit: 1 },
+ });
+ const windowStart = planWindowStartFromResponse(probe);
+ return analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ ...(windowStart
+ ? { startTime: windowStart, endTime: new Date().toISOString() }
+ : {}),
+ pagination: { limit },
+ });
+ };
+ const runList = await fetchMatches();
  const runs = {
  data: runList.data.map((run) => ({
  runId: run.runId,

packages/cli/src/commands/inspect.ts

@@ -129,6 +129,22 @@ export default class Inspect extends BaseCommand {
  helpGroup: 'Filtering',
  helpLabel: '--status',
  }),
+ since: Flags.string({
+ description:
+ 'list runs active since a relative duration (30m, 12h, 7d, 2w) or timestamp; defaults to the backend window (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--since',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
+ until: Flags.string({
+ description:
+ 'end of the --since listing window, as a relative duration or timestamp; defaults to now (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--until',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
  withData: Flags.boolean({
  description:
  'include full input/output data in list views (deprecated for list views — use `inspect <resource> <id>` to view payloads)',
@@ -282,6 +298,8 @@ function toInspectOptions(flags: any): InspectCLIOptions {
  limit: flags.limit,
  workflowName: flags.workflowName,
  status: flags.status,
+ since: flags.since,
+ until: flags.until,
  withData: flags.withData,
  decrypt: flags.decrypt,
  backend: flags.backend,

packages/cli/src/lib/config/types.ts

@@ -19,6 +19,10 @@ export type InspectCLIOptions = {
  limit?: number;
  workflowName?: string;
  status?: string;
+ /** Listing window start: relative duration (12h, 7d) or timestamp (runs only) */
+ since?: string;
+ /** Listing window end: relative duration or timestamp; requires --since */
+ until?: string;
  withData?: boolean;
  backend?: string;
  disableRelativeDates?: boolean;

packages/cli/src/lib/inspect/output.ts

@@ -23,6 +23,7 @@ import {
  isEncryptedRef,
  isExpiredRef,
 } from './hydration.js';
+import { resolveTimeWindow } from './time-window.js';
 
 /**
  * Create an EncryptionKeyResolver from a World instance.
@@ -620,6 +621,17 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const resolveData = opts.withData ? 'all' : 'none';
  const status = opts.status as WorkflowRun['status'] | undefined;
 
+ // Resolve --since/--until into an explicit listing window. Only the
+ // analytics read path supports one; the runtime storage APIs have no time
+ // filter. Without the flags the backend applies its default window
+ // (trailing 24h on the Vercel backend).
+ const timeWindow = resolveTimeWindow(opts);
+ if (timeWindow && !useAnalytics) {
+ logger.warn(
+ '--since/--until require the analytics read path and are ignored by this backend.'
+ );
+ }
+
  // Determine which props to show based on withData flag
  const props = opts.withData
  ? WORKFLOW_RUN_LISTED_PROPS
@@ -639,6 +651,7 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const runs = await world.analytics.runs.list({
  workflowName: opts.workflowName,
  status,
+ ...(timeWindow ?? {}),
  pagination,
  });
  return {

packages/cli/src/lib/inspect/run.ts

@@ -2,6 +2,7 @@ import { start } from '@workflow/core/runtime';
 import { healthCheck } from '@workflow/core/runtime/helpers';
 import type { World } from '@workflow/world';
 import { logger } from '../config/log.js';
+import { planWindowStartFromResponse } from './time-window.js';
 
 interface CLICreateOpts {
  json?: boolean;
@@ -57,6 +58,23 @@ export const startRun = async (
  resolveData: 'none',
  });
  run = runList.data[0];
+
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend). When the name wasn't found
+ // there, retry across the plan's whole observability window using the
+ // window bounds from the response's page metadata.
+ if (!run && world.analytics) {
+ const windowStart = planWindowStartFromResponse(runList);
+ if (windowStart) {
+ const widened = await world.analytics.runs.list({
+ workflowName: workflowNameOrRunId,
+ startTime: windowStart,
+ endTime: new Date().toISOString(),
+ pagination: { sortOrder: 'desc', limit: 1 },
+ });
+ run = widened.data[0];
+ }
+ }
  }
 
  if (!run) {

packages/cli/src/lib/inspect/time-window.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ parseTimeInput,
+ planWindowStartFromResponse,
+ resolveTimeWindow,
+} from './time-window.js';
+
+const NOW = new Date('2026-07-07T12:00:00.000Z');
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('parseTimeInput', () => {
+ it('parses relative durations as that long ago', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(parseTimeInput('30m', 'since').toISOString()).toBe(
+ '2026-07-07T11:30:00.000Z'
+ );
+ expect(parseTimeInput('12h', 'since').toISOString()).toBe(
+ '2026-07-07T00:00:00.000Z'
+ );
+ expect(parseTimeInput('7d', 'since').toISOString()).toBe(
+ '2026-06-30T12:00:00.000Z'
+ );
+ expect(parseTimeInput('2w', 'since').toISOString()).toBe(
+ '2026-06-23T12:00:00.000Z'
+ );
+ });
+
+ it('parses absolute timestamps', () => {
+ expect(parseTimeInput('2026-07-01T00:00:00Z', 'since').toISOString()).toBe(
+ '2026-07-01T00:00:00.000Z'
+ );
+ });
+
+ it('rejects invalid values with the flag name in the error', () => {
+ expect(() => parseTimeInput('yesterday-ish', 'since')).toThrow('--since');
+ });
+});
+
+describe('resolveTimeWindow', () => {
+ it('returns undefined when neither flag is given', () => {
+ expect(resolveTimeWindow({})).toBeUndefined();
+ });
+
+ it('defaults the end to now when only --since is given', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(resolveTimeWindow({ since: '24h' })).toEqual({
+ startTime: '2026-07-06T12:00:00.000Z',
+ endTime: '2026-07-07T12:00:00.000Z',
+ });
+ });
+
+ it('rejects --until without --since', () => {
+ expect(() => resolveTimeWindow({ until: '1h' })).toThrow(
+ '--until requires --since'
+ );
+ });
+
+ it('rejects inverted windows', () => {
+ expect(() => resolveTimeWindow({ since: '1h', until: '2h' })).toThrow(
+ '--since must be earlier than --until'
+ );
+ });
+});
+
+describe('planWindowStartFromResponse', () => {
+ it('extracts the plan window start from page metadata', () => {
+ expect(
+ planWindowStartFromResponse({
+ data: [],
+ pageInfo: {
+ currentLookbackDays: 30,
+ maxLookbackDays: 30,
+ currentWindowStart: '2026-06-07T12:00:00.000Z',
+ maxWindowStart: '2026-06-07T12:00:00.000Z',
+ upgradeAvailable: false,
+ },
+ })
+ ).toBe('2026-06-07T12:00:00.000Z');
+ });
+
+ it('returns undefined without page metadata', () => {
+ expect(planWindowStartFromResponse({ data: [] })).toBeUndefined();
+ expect(planWindowStartFromResponse(null)).toBeUndefined();
+ });
+});

packages/cli/src/lib/inspect/time-window.ts

@@ -0,0 +1,69 @@
+import type { AnalyticsPageInfo } from './pagination.js';
+
+const DURATION_UNIT_MS: Record<string, number> = {
+ m: 60_000,
+ h: 3_600_000,
+ d: 86_400_000,
+ w: 604_800_000,
+};
+
+/**
+ * Parse a `--since`/`--until` value: either a relative duration (`30m`,
+ * `12h`, `7d`, `2w`, interpreted as "that long ago") or an absolute
+ * timestamp accepted by `Date`.
+ */
+export function parseTimeInput(value: string, flagName: string): Date {
+ const duration = /^(\d+)(m|h|d|w)$/.exec(value.trim());
+ if (duration) {
+ const [, amount, unit] = duration;
+ return new Date(Date.now() - Number(amount) * DURATION_UNIT_MS[unit]);
+ }
+ const absolute = new Date(value);
+ if (!Number.isNaN(absolute.getTime())) {
+ return absolute;
+ }
+ throw new Error(
+ `Invalid --${flagName} value "${value}". Use a relative duration (30m, 12h, 7d, 2w) or a timestamp (2026-07-01T00:00:00Z).`
+ );
+}
+
+/**
+ * Resolve `--since`/`--until` flags into an explicit listing window for the
+ * analytics runs API, or undefined when neither flag was given (the backend
+ * then applies its default window). Windows older than the plan's
+ * observability lookback are rejected by the backend with
+ * `observability-upgrade-required`.
+ */
+export function resolveTimeWindow(opts: {
+ since?: string;
+ until?: string;
+}): { startTime: string; endTime: string } | undefined {
+ if (!opts.since && !opts.until) return undefined;
+ if (!opts.since) {
+ throw new Error('--until requires --since.');
+ }
+ const start = parseTimeInput(opts.since, 'since');
+ const end = opts.until
+ ? parseTimeInput(opts.until, 'until')
+ : new Date(Date.now());
+ if (start.getTime() >= end.getTime()) {
+ throw new Error('--since must be earlier than --until.');
+ }
+ return { startTime: start.toISOString(), endTime: end.toISOString() };
+}
+
+/**
+ * Extract the plan observability-window start from a paginated analytics
+ * response, for widening a defaulted (recent-window) listing to the whole
+ * window the plan allows. Returns undefined when the response carries no
+ * page metadata (e.g. non-Vercel backends).
+ */
+export function planWindowStartFromResponse(
+ result: unknown
+): string | undefined {
+ if (typeof result !== 'object' || result === null) return undefined;
+ const pageInfo = (result as { pageInfo?: AnalyticsPageInfo }).pageInfo;
+ if (!pageInfo?.currentWindowStart) return undefined;
+ const start = new Date(pageInfo.currentWindowStart);
+ return Number.isNaN(start.getTime()) ? undefined : start.toISOString();
+}

.changeset/cli-runs-time-window.md

@@ -0,0 +1,5 @@
+---
+'@workflow/cli': patch
+---
+
+Add `--since`/`--until` to `workflow inspect runs`; `workflow start` and bulk `workflow cancel` name lookups now search past the backend's default 24h window.

.changeset/web-runs-infinite-scroll.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web': patch
+---
+
+Runs list: infinite scroll with SWR-cached pages (tab switches no longer refetch), a plan-aware time-window picker (default 24h), and status filtering without requiring a workflow filter.

.changeset/world-analytics-time-window.md

@@ -0,0 +1,6 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+---
+
+Support `startTime`/`endTime` on `world.analytics.runs.list` to bound the listing window.

packages/cli/src/commands/cancel.ts

@@ -13,6 +13,7 @@ import {
 } from '../lib/inspect/errors.js';
 import { cliFlags } from '../lib/inspect/flags.js';
 import { setupCliWorld } from '../lib/inspect/setup.js';
+import { planWindowStartFromResponse } from '../lib/inspect/time-window.js';
 
 export default class Cancel extends BaseCommand {
  static description =
@@ -110,18 +111,38 @@ export default class Cancel extends BaseCommand {
  // Fetch matching runs. Only metadata is needed to display and cancel, so
  // prefer the analytics read path when the backend provides one.
  const status = flags.status as WorkflowRun['status'] | undefined;
- const runList = world.analytics
- ? await world.analytics.runs.list({
+ const limit = flags.limit || 50;
+ const analytics = world.analytics;
+ const fetchMatches = async () => {
+ if (!analytics) {
+ return world.runs.list({
  status,
  workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
- })
- : await world.runs.list({
- status,
- workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
+ pagination: { limit },
  resolveData: 'none',
  });
+ }
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend), but bulk cancel must match
+ // across the plan's whole observability window — a run can sleep or
+ // wait on a hook for days without emitting recent events. Probe for
+ // the plan window bounds first, then match across them.
+ const probe = await analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ pagination: { limit: 1 },
+ });
+ const windowStart = planWindowStartFromResponse(probe);
+ return analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ ...(windowStart
+ ? { startTime: windowStart, endTime: new Date().toISOString() }
+ : {}),
+ pagination: { limit },
+ });
+ };
+ const runList = await fetchMatches();
  const runs = {
  data: runList.data.map((run) => ({
  runId: run.runId,

packages/cli/src/commands/inspect.ts

@@ -129,6 +129,22 @@ export default class Inspect extends BaseCommand {
  helpGroup: 'Filtering',
  helpLabel: '--status',
  }),
+ since: Flags.string({
+ description:
+ 'list runs active since a relative duration (30m, 12h, 7d, 2w) or timestamp; defaults to the backend window (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--since',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
+ until: Flags.string({
+ description:
+ 'end of the --since listing window, as a relative duration or timestamp; defaults to now (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--until',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
  withData: Flags.boolean({
  description:
  'include full input/output data in list views (deprecated for list views — use `inspect <resource> <id>` to view payloads)',
@@ -282,6 +298,8 @@ function toInspectOptions(flags: any): InspectCLIOptions {
  limit: flags.limit,
  workflowName: flags.workflowName,
  status: flags.status,
+ since: flags.since,
+ until: flags.until,
  withData: flags.withData,
  decrypt: flags.decrypt,
  backend: flags.backend,

packages/cli/src/lib/config/types.ts

@@ -19,6 +19,10 @@ export type InspectCLIOptions = {
  limit?: number;
  workflowName?: string;
  status?: string;
+ /** Listing window start: relative duration (12h, 7d) or timestamp (runs only) */
+ since?: string;
+ /** Listing window end: relative duration or timestamp; requires --since */
+ until?: string;
  withData?: boolean;
  backend?: string;
  disableRelativeDates?: boolean;

packages/cli/src/lib/inspect/output.ts

@@ -23,6 +23,7 @@ import {
  isEncryptedRef,
  isExpiredRef,
 } from './hydration.js';
+import { resolveTimeWindow } from './time-window.js';
 
 /**
  * Create an EncryptionKeyResolver from a World instance.
@@ -620,6 +621,17 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const resolveData = opts.withData ? 'all' : 'none';
  const status = opts.status as WorkflowRun['status'] | undefined;
 
+ // Resolve --since/--until into an explicit listing window. Only the
+ // analytics read path supports one; the runtime storage APIs have no time
+ // filter. Without the flags the backend applies its default window
+ // (trailing 24h on the Vercel backend).
+ const timeWindow = resolveTimeWindow(opts);
+ if (timeWindow && !useAnalytics) {
+ logger.warn(
+ '--since/--until require the analytics read path and are ignored by this backend.'
+ );
+ }
+
  // Determine which props to show based on withData flag
  const props = opts.withData
  ? WORKFLOW_RUN_LISTED_PROPS
@@ -639,6 +651,7 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const runs = await world.analytics.runs.list({
  workflowName: opts.workflowName,
  status,
+ ...(timeWindow ?? {}),
  pagination,
  });
  return {

packages/cli/src/lib/inspect/run.ts

@@ -2,6 +2,7 @@ import { start } from '@workflow/core/runtime';
 import { healthCheck } from '@workflow/core/runtime/helpers';
 import type { World } from '@workflow/world';
 import { logger } from '../config/log.js';
+import { planWindowStartFromResponse } from './time-window.js';
 
 interface CLICreateOpts {
  json?: boolean;
@@ -57,6 +58,23 @@ export const startRun = async (
  resolveData: 'none',
  });
  run = runList.data[0];
+
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend). When the name wasn't found
+ // there, retry across the plan's whole observability window using the
+ // window bounds from the response's page metadata.
+ if (!run && world.analytics) {
+ const windowStart = planWindowStartFromResponse(runList);
+ if (windowStart) {
+ const widened = await world.analytics.runs.list({
+ workflowName: workflowNameOrRunId,
+ startTime: windowStart,
+ endTime: new Date().toISOString(),
+ pagination: { sortOrder: 'desc', limit: 1 },
+ });
+ run = widened.data[0];
+ }
+ }
  }
 
  if (!run) {

packages/cli/src/lib/inspect/time-window.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ parseTimeInput,
+ planWindowStartFromResponse,
+ resolveTimeWindow,
+} from './time-window.js';
+
+const NOW = new Date('2026-07-07T12:00:00.000Z');
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('parseTimeInput', () => {
+ it('parses relative durations as that long ago', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(parseTimeInput('30m', 'since').toISOString()).toBe(
+ '2026-07-07T11:30:00.000Z'
+ );
+ expect(parseTimeInput('12h', 'since').toISOString()).toBe(
+ '2026-07-07T00:00:00.000Z'
+ );
+ expect(parseTimeInput('7d', 'since').toISOString()).toBe(
+ '2026-06-30T12:00:00.000Z'
+ );
+ expect(parseTimeInput('2w', 'since').toISOString()).toBe(
+ '2026-06-23T12:00:00.000Z'
+ );
+ });
+
+ it('parses absolute timestamps', () => {
+ expect(parseTimeInput('2026-07-01T00:00:00Z', 'since').toISOString()).toBe(
+ '2026-07-01T00:00:00.000Z'
+ );
+ });
+
+ it('rejects invalid values with the flag name in the error', () => {
+ expect(() => parseTimeInput('yesterday-ish', 'since')).toThrow('--since');
+ });
+});
+
+describe('resolveTimeWindow', () => {
+ it('returns undefined when neither flag is given', () => {
+ expect(resolveTimeWindow({})).toBeUndefined();
+ });
+
+ it('defaults the end to now when only --since is given', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(resolveTimeWindow({ since: '24h' })).toEqual({
+ startTime: '2026-07-06T12:00:00.000Z',
+ endTime: '2026-07-07T12:00:00.000Z',
+ });
+ });
+
+ it('rejects --until without --since', () => {
+ expect(() => resolveTimeWindow({ until: '1h' })).toThrow(
+ '--until requires --since'
+ );
+ });
+
+ it('rejects inverted windows', () => {
+ expect(() => resolveTimeWindow({ since: '1h', until: '2h' })).toThrow(
+ '--since must be earlier than --until'
+ );
+ });
+});
+
+describe('planWindowStartFromResponse', () => {
+ it('extracts the plan window start from page metadata', () => {
+ expect(
+ planWindowStartFromResponse({
+ data: [],
+ pageInfo: {
+ currentLookbackDays: 30,
+ maxLookbackDays: 30,
+ currentWindowStart: '2026-06-07T12:00:00.000Z',
+ maxWindowStart: '2026-06-07T12:00:00.000Z',
+ upgradeAvailable: false,
+ },
+ })
+ ).toBe('2026-06-07T12:00:00.000Z');
+ });
+
+ it('returns undefined without page metadata', () => {
+ expect(planWindowStartFromResponse({ data: [] })).toBeUndefined();
+ expect(planWindowStartFromResponse(null)).toBeUndefined();
+ });
+});

packages/cli/src/lib/inspect/time-window.ts

@@ -0,0 +1,69 @@
+import type { AnalyticsPageInfo } from './pagination.js';
+
+const DURATION_UNIT_MS: Record<string, number> = {
+ m: 60_000,
+ h: 3_600_000,
+ d: 86_400_000,
+ w: 604_800_000,
+};
+
+/**
+ * Parse a `--since`/`--until` value: either a relative duration (`30m`,
+ * `12h`, `7d`, `2w`, interpreted as "that long ago") or an absolute
+ * timestamp accepted by `Date`.
+ */
+export function parseTimeInput(value: string, flagName: string): Date {
+ const duration = /^(\d+)(m|h|d|w)$/.exec(value.trim());
+ if (duration) {
+ const [, amount, unit] = duration;
+ return new Date(Date.now() - Number(amount) * DURATION_UNIT_MS[unit]);
+ }
+ const absolute = new Date(value);
+ if (!Number.isNaN(absolute.getTime())) {
+ return absolute;
+ }
+ throw new Error(
+ `Invalid --${flagName} value "${value}". Use a relative duration (30m, 12h, 7d, 2w) or a timestamp (2026-07-01T00:00:00Z).`
+ );
+}
+
+/**
+ * Resolve `--since`/`--until` flags into an explicit listing window for the
+ * analytics runs API, or undefined when neither flag was given (the backend
+ * then applies its default window). Windows older than the plan's
+ * observability lookback are rejected by the backend with
+ * `observability-upgrade-required`.
+ */
+export function resolveTimeWindow(opts: {
+ since?: string;
+ until?: string;
+}): { startTime: string; endTime: string } | undefined {
+ if (!opts.since && !opts.until) return undefined;
+ if (!opts.since) {
+ throw new Error('--until requires --since.');
+ }
+ const start = parseTimeInput(opts.since, 'since');
+ const end = opts.until
+ ? parseTimeInput(opts.until, 'until')
+ : new Date(Date.now());
+ if (start.getTime() >= end.getTime()) {
+ throw new Error('--since must be earlier than --until.');
+ }
+ return { startTime: start.toISOString(), endTime: end.toISOString() };
+}
+
+/**
+ * Extract the plan observability-window start from a paginated analytics
+ * response, for widening a defaulted (recent-window) listing to the whole
+ * window the plan allows. Returns undefined when the response carries no
+ * page metadata (e.g. non-Vercel backends).
+ */
+export function planWindowStartFromResponse(
+ result: unknown
+): string | undefined {
+ if (typeof result !== 'object' || result === null) return undefined;
+ const pageInfo = (result as { pageInfo?: AnalyticsPageInfo }).pageInfo;
+ if (!pageInfo?.currentWindowStart) return undefined;
+ const start = new Date(pageInfo.currentWindowStart);
+ return Number.isNaN(start.getTime()) ? undefined : start.toISOString();
+}

.changeset/cli-runs-time-window.md

@@ -0,0 +1,5 @@
+---
+'@workflow/cli': patch
+---
+
+Add `--since`/`--until` to `workflow inspect runs`; `workflow start` and bulk `workflow cancel` name lookups now search past the backend's default 24h window.

.changeset/web-runs-infinite-scroll.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web': patch
+---
+
+Runs list: infinite scroll with SWR-cached pages (tab switches no longer refetch), a plan-aware time-window picker (default 24h), and status filtering without requiring a workflow filter.

.changeset/world-analytics-time-window.md

@@ -0,0 +1,6 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+---
+
+Support `startTime`/`endTime` on `world.analytics.runs.list` to bound the listing window.

packages/cli/src/commands/cancel.ts

@@ -13,6 +13,7 @@ import {
 } from '../lib/inspect/errors.js';
 import { cliFlags } from '../lib/inspect/flags.js';
 import { setupCliWorld } from '../lib/inspect/setup.js';
+import { planWindowStartFromResponse } from '../lib/inspect/time-window.js';
 
 export default class Cancel extends BaseCommand {
  static description =
@@ -110,18 +111,38 @@ export default class Cancel extends BaseCommand {
  // Fetch matching runs. Only metadata is needed to display and cancel, so
  // prefer the analytics read path when the backend provides one.
  const status = flags.status as WorkflowRun['status'] | undefined;
- const runList = world.analytics
- ? await world.analytics.runs.list({
+ const limit = flags.limit || 50;
+ const analytics = world.analytics;
+ const fetchMatches = async () => {
+ if (!analytics) {
+ return world.runs.list({
  status,
  workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
- })
- : await world.runs.list({
- status,
- workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
+ pagination: { limit },
  resolveData: 'none',
  });
+ }
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend), but bulk cancel must match
+ // across the plan's whole observability window — a run can sleep or
+ // wait on a hook for days without emitting recent events. Probe for
+ // the plan window bounds first, then match across them.
+ const probe = await analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ pagination: { limit: 1 },
+ });
+ const windowStart = planWindowStartFromResponse(probe);
+ return analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ ...(windowStart
+ ? { startTime: windowStart, endTime: new Date().toISOString() }
+ : {}),
+ pagination: { limit },
+ });
+ };
+ const runList = await fetchMatches();
  const runs = {
  data: runList.data.map((run) => ({
  runId: run.runId,

packages/cli/src/commands/inspect.ts

@@ -129,6 +129,22 @@ export default class Inspect extends BaseCommand {
  helpGroup: 'Filtering',
  helpLabel: '--status',
  }),
+ since: Flags.string({
+ description:
+ 'list runs active since a relative duration (30m, 12h, 7d, 2w) or timestamp; defaults to the backend window (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--since',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
+ until: Flags.string({
+ description:
+ 'end of the --since listing window, as a relative duration or timestamp; defaults to now (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--until',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
  withData: Flags.boolean({
  description:
  'include full input/output data in list views (deprecated for list views — use `inspect <resource> <id>` to view payloads)',
@@ -282,6 +298,8 @@ function toInspectOptions(flags: any): InspectCLIOptions {
  limit: flags.limit,
  workflowName: flags.workflowName,
  status: flags.status,
+ since: flags.since,
+ until: flags.until,
  withData: flags.withData,
  decrypt: flags.decrypt,
  backend: flags.backend,

packages/cli/src/lib/config/types.ts

@@ -19,6 +19,10 @@ export type InspectCLIOptions = {
  limit?: number;
  workflowName?: string;
  status?: string;
+ /** Listing window start: relative duration (12h, 7d) or timestamp (runs only) */
+ since?: string;
+ /** Listing window end: relative duration or timestamp; requires --since */
+ until?: string;
  withData?: boolean;
  backend?: string;
  disableRelativeDates?: boolean;

packages/cli/src/lib/inspect/output.ts

@@ -23,6 +23,7 @@ import {
  isEncryptedRef,
  isExpiredRef,
 } from './hydration.js';
+import { resolveTimeWindow } from './time-window.js';
 
 /**
  * Create an EncryptionKeyResolver from a World instance.
@@ -620,6 +621,17 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const resolveData = opts.withData ? 'all' : 'none';
  const status = opts.status as WorkflowRun['status'] | undefined;
 
+ // Resolve --since/--until into an explicit listing window. Only the
+ // analytics read path supports one; the runtime storage APIs have no time
+ // filter. Without the flags the backend applies its default window
+ // (trailing 24h on the Vercel backend).
+ const timeWindow = resolveTimeWindow(opts);
+ if (timeWindow && !useAnalytics) {
+ logger.warn(
+ '--since/--until require the analytics read path and are ignored by this backend.'
+ );
+ }
+
  // Determine which props to show based on withData flag
  const props = opts.withData
  ? WORKFLOW_RUN_LISTED_PROPS
@@ -639,6 +651,7 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const runs = await world.analytics.runs.list({
  workflowName: opts.workflowName,
  status,
+ ...(timeWindow ?? {}),
  pagination,
  });
  return {

packages/cli/src/lib/inspect/run.ts

@@ -2,6 +2,7 @@ import { start } from '@workflow/core/runtime';
 import { healthCheck } from '@workflow/core/runtime/helpers';
 import type { World } from '@workflow/world';
 import { logger } from '../config/log.js';
+import { planWindowStartFromResponse } from './time-window.js';
 
 interface CLICreateOpts {
  json?: boolean;
@@ -57,6 +58,23 @@ export const startRun = async (
  resolveData: 'none',
  });
  run = runList.data[0];
+
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend). When the name wasn't found
+ // there, retry across the plan's whole observability window using the
+ // window bounds from the response's page metadata.
+ if (!run && world.analytics) {
+ const windowStart = planWindowStartFromResponse(runList);
+ if (windowStart) {
+ const widened = await world.analytics.runs.list({
+ workflowName: workflowNameOrRunId,
+ startTime: windowStart,
+ endTime: new Date().toISOString(),
+ pagination: { sortOrder: 'desc', limit: 1 },
+ });
+ run = widened.data[0];
+ }
+ }
  }
 
  if (!run) {

packages/cli/src/lib/inspect/time-window.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ parseTimeInput,
+ planWindowStartFromResponse,
+ resolveTimeWindow,
+} from './time-window.js';
+
+const NOW = new Date('2026-07-07T12:00:00.000Z');
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('parseTimeInput', () => {
+ it('parses relative durations as that long ago', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(parseTimeInput('30m', 'since').toISOString()).toBe(
+ '2026-07-07T11:30:00.000Z'
+ );
+ expect(parseTimeInput('12h', 'since').toISOString()).toBe(
+ '2026-07-07T00:00:00.000Z'
+ );
+ expect(parseTimeInput('7d', 'since').toISOString()).toBe(
+ '2026-06-30T12:00:00.000Z'
+ );
+ expect(parseTimeInput('2w', 'since').toISOString()).toBe(
+ '2026-06-23T12:00:00.000Z'
+ );
+ });
+
+ it('parses absolute timestamps', () => {
+ expect(parseTimeInput('2026-07-01T00:00:00Z', 'since').toISOString()).toBe(
+ '2026-07-01T00:00:00.000Z'
+ );
+ });
+
+ it('rejects invalid values with the flag name in the error', () => {
+ expect(() => parseTimeInput('yesterday-ish', 'since')).toThrow('--since');
+ });
+});
+
+describe('resolveTimeWindow', () => {
+ it('returns undefined when neither flag is given', () => {
+ expect(resolveTimeWindow({})).toBeUndefined();
+ });
+
+ it('defaults the end to now when only --since is given', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(resolveTimeWindow({ since: '24h' })).toEqual({
+ startTime: '2026-07-06T12:00:00.000Z',
+ endTime: '2026-07-07T12:00:00.000Z',
+ });
+ });
+
+ it('rejects --until without --since', () => {
+ expect(() => resolveTimeWindow({ until: '1h' })).toThrow(
+ '--until requires --since'
+ );
+ });
+
+ it('rejects inverted windows', () => {
+ expect(() => resolveTimeWindow({ since: '1h', until: '2h' })).toThrow(
+ '--since must be earlier than --until'
+ );
+ });
+});
+
+describe('planWindowStartFromResponse', () => {
+ it('extracts the plan window start from page metadata', () => {
+ expect(
+ planWindowStartFromResponse({
+ data: [],
+ pageInfo: {
+ currentLookbackDays: 30,
+ maxLookbackDays: 30,
+ currentWindowStart: '2026-06-07T12:00:00.000Z',
+ maxWindowStart: '2026-06-07T12:00:00.000Z',
+ upgradeAvailable: false,
+ },
+ })
+ ).toBe('2026-06-07T12:00:00.000Z');
+ });
+
+ it('returns undefined without page metadata', () => {
+ expect(planWindowStartFromResponse({ data: [] })).toBeUndefined();
+ expect(planWindowStartFromResponse(null)).toBeUndefined();
+ });
+});

packages/cli/src/lib/inspect/time-window.ts

@@ -0,0 +1,69 @@
+import type { AnalyticsPageInfo } from './pagination.js';
+
+const DURATION_UNIT_MS: Record<string, number> = {
+ m: 60_000,
+ h: 3_600_000,
+ d: 86_400_000,
+ w: 604_800_000,
+};
+
+/**
+ * Parse a `--since`/`--until` value: either a relative duration (`30m`,
+ * `12h`, `7d`, `2w`, interpreted as "that long ago") or an absolute
+ * timestamp accepted by `Date`.
+ */
+export function parseTimeInput(value: string, flagName: string): Date {
+ const duration = /^(\d+)(m|h|d|w)$/.exec(value.trim());
+ if (duration) {
+ const [, amount, unit] = duration;
+ return new Date(Date.now() - Number(amount) * DURATION_UNIT_MS[unit]);
+ }
+ const absolute = new Date(value);
+ if (!Number.isNaN(absolute.getTime())) {
+ return absolute;
+ }
+ throw new Error(
+ `Invalid --${flagName} value "${value}". Use a relative duration (30m, 12h, 7d, 2w) or a timestamp (2026-07-01T00:00:00Z).`
+ );
+}
+
+/**
+ * Resolve `--since`/`--until` flags into an explicit listing window for the
+ * analytics runs API, or undefined when neither flag was given (the backend
+ * then applies its default window). Windows older than the plan's
+ * observability lookback are rejected by the backend with
+ * `observability-upgrade-required`.
+ */
+export function resolveTimeWindow(opts: {
+ since?: string;
+ until?: string;
+}): { startTime: string; endTime: string } | undefined {
+ if (!opts.since && !opts.until) return undefined;
+ if (!opts.since) {
+ throw new Error('--until requires --since.');
+ }
+ const start = parseTimeInput(opts.since, 'since');
+ const end = opts.until
+ ? parseTimeInput(opts.until, 'until')
+ : new Date(Date.now());
+ if (start.getTime() >= end.getTime()) {
+ throw new Error('--since must be earlier than --until.');
+ }
+ return { startTime: start.toISOString(), endTime: end.toISOString() };
+}
+
+/**
+ * Extract the plan observability-window start from a paginated analytics
+ * response, for widening a defaulted (recent-window) listing to the whole
+ * window the plan allows. Returns undefined when the response carries no
+ * page metadata (e.g. non-Vercel backends).
+ */
+export function planWindowStartFromResponse(
+ result: unknown
+): string | undefined {
+ if (typeof result !== 'object' || result === null) return undefined;
+ const pageInfo = (result as { pageInfo?: AnalyticsPageInfo }).pageInfo;
+ if (!pageInfo?.currentWindowStart) return undefined;
+ const start = new Date(pageInfo.currentWindowStart);
+ return Number.isNaN(start.getTime()) ? undefined : start.toISOString();
+}

.changeset/cli-runs-time-window.md

@@ -0,0 +1,5 @@
+---
+'@workflow/cli': patch
+---
+
+Add `--since`/`--until` to `workflow inspect runs`; `workflow start` and bulk `workflow cancel` name lookups now search past the backend's default 24h window.

.changeset/web-runs-infinite-scroll.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web': patch
+---
+
+Runs list: infinite scroll with SWR-cached pages (tab switches no longer refetch), a plan-aware time-window picker (default 24h), and status filtering without requiring a workflow filter.

.changeset/world-analytics-time-window.md

@@ -0,0 +1,6 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+---
+
+Support `startTime`/`endTime` on `world.analytics.runs.list` to bound the listing window.

packages/cli/src/commands/cancel.ts

@@ -13,6 +13,7 @@ import {
 } from '../lib/inspect/errors.js';
 import { cliFlags } from '../lib/inspect/flags.js';
 import { setupCliWorld } from '../lib/inspect/setup.js';
+import { planWindowStartFromResponse } from '../lib/inspect/time-window.js';
 
 export default class Cancel extends BaseCommand {
  static description =
@@ -110,18 +111,38 @@ export default class Cancel extends BaseCommand {
  // Fetch matching runs. Only metadata is needed to display and cancel, so
  // prefer the analytics read path when the backend provides one.
  const status = flags.status as WorkflowRun['status'] | undefined;
- const runList = world.analytics
- ? await world.analytics.runs.list({
+ const limit = flags.limit || 50;
+ const analytics = world.analytics;
+ const fetchMatches = async () => {
+ if (!analytics) {
+ return world.runs.list({
  status,
  workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
- })
- : await world.runs.list({
- status,
- workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
+ pagination: { limit },
  resolveData: 'none',
  });
+ }
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend), but bulk cancel must match
+ // across the plan's whole observability window — a run can sleep or
+ // wait on a hook for days without emitting recent events. Probe for
+ // the plan window bounds first, then match across them.
+ const probe = await analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ pagination: { limit: 1 },
+ });
+ const windowStart = planWindowStartFromResponse(probe);
+ return analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ ...(windowStart
+ ? { startTime: windowStart, endTime: new Date().toISOString() }
+ : {}),
+ pagination: { limit },
+ });
+ };
+ const runList = await fetchMatches();
  const runs = {
  data: runList.data.map((run) => ({
  runId: run.runId,

packages/cli/src/commands/inspect.ts

@@ -129,6 +129,22 @@ export default class Inspect extends BaseCommand {
  helpGroup: 'Filtering',
  helpLabel: '--status',
  }),
+ since: Flags.string({
+ description:
+ 'list runs active since a relative duration (30m, 12h, 7d, 2w) or timestamp; defaults to the backend window (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--since',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
+ until: Flags.string({
+ description:
+ 'end of the --since listing window, as a relative duration or timestamp; defaults to now (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--until',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
  withData: Flags.boolean({
  description:
  'include full input/output data in list views (deprecated for list views — use `inspect <resource> <id>` to view payloads)',
@@ -282,6 +298,8 @@ function toInspectOptions(flags: any): InspectCLIOptions {
  limit: flags.limit,
  workflowName: flags.workflowName,
  status: flags.status,
+ since: flags.since,
+ until: flags.until,
  withData: flags.withData,
  decrypt: flags.decrypt,
  backend: flags.backend,

packages/cli/src/lib/config/types.ts

@@ -19,6 +19,10 @@ export type InspectCLIOptions = {
  limit?: number;
  workflowName?: string;
  status?: string;
+ /** Listing window start: relative duration (12h, 7d) or timestamp (runs only) */
+ since?: string;
+ /** Listing window end: relative duration or timestamp; requires --since */
+ until?: string;
  withData?: boolean;
  backend?: string;
  disableRelativeDates?: boolean;

packages/cli/src/lib/inspect/output.ts

@@ -23,6 +23,7 @@ import {
  isEncryptedRef,
  isExpiredRef,
 } from './hydration.js';
+import { resolveTimeWindow } from './time-window.js';
 
 /**
  * Create an EncryptionKeyResolver from a World instance.
@@ -620,6 +621,17 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const resolveData = opts.withData ? 'all' : 'none';
  const status = opts.status as WorkflowRun['status'] | undefined;
 
+ // Resolve --since/--until into an explicit listing window. Only the
+ // analytics read path supports one; the runtime storage APIs have no time
+ // filter. Without the flags the backend applies its default window
+ // (trailing 24h on the Vercel backend).
+ const timeWindow = resolveTimeWindow(opts);
+ if (timeWindow && !useAnalytics) {
+ logger.warn(
+ '--since/--until require the analytics read path and are ignored by this backend.'
+ );
+ }
+
  // Determine which props to show based on withData flag
  const props = opts.withData
  ? WORKFLOW_RUN_LISTED_PROPS
@@ -639,6 +651,7 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const runs = await world.analytics.runs.list({
  workflowName: opts.workflowName,
  status,
+ ...(timeWindow ?? {}),
  pagination,
  });
  return {

packages/cli/src/lib/inspect/run.ts

@@ -2,6 +2,7 @@ import { start } from '@workflow/core/runtime';
 import { healthCheck } from '@workflow/core/runtime/helpers';
 import type { World } from '@workflow/world';
 import { logger } from '../config/log.js';
+import { planWindowStartFromResponse } from './time-window.js';
 
 interface CLICreateOpts {
  json?: boolean;
@@ -57,6 +58,23 @@ export const startRun = async (
  resolveData: 'none',
  });
  run = runList.data[0];
+
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend). When the name wasn't found
+ // there, retry across the plan's whole observability window using the
+ // window bounds from the response's page metadata.
+ if (!run && world.analytics) {
+ const windowStart = planWindowStartFromResponse(runList);
+ if (windowStart) {
+ const widened = await world.analytics.runs.list({
+ workflowName: workflowNameOrRunId,
+ startTime: windowStart,
+ endTime: new Date().toISOString(),
+ pagination: { sortOrder: 'desc', limit: 1 },
+ });
+ run = widened.data[0];
+ }
+ }
  }
 
  if (!run) {

packages/cli/src/lib/inspect/time-window.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ parseTimeInput,
+ planWindowStartFromResponse,
+ resolveTimeWindow,
+} from './time-window.js';
+
+const NOW = new Date('2026-07-07T12:00:00.000Z');
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('parseTimeInput', () => {
+ it('parses relative durations as that long ago', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(parseTimeInput('30m', 'since').toISOString()).toBe(
+ '2026-07-07T11:30:00.000Z'
+ );
+ expect(parseTimeInput('12h', 'since').toISOString()).toBe(
+ '2026-07-07T00:00:00.000Z'
+ );
+ expect(parseTimeInput('7d', 'since').toISOString()).toBe(
+ '2026-06-30T12:00:00.000Z'
+ );
+ expect(parseTimeInput('2w', 'since').toISOString()).toBe(
+ '2026-06-23T12:00:00.000Z'
+ );
+ });
+
+ it('parses absolute timestamps', () => {
+ expect(parseTimeInput('2026-07-01T00:00:00Z', 'since').toISOString()).toBe(
+ '2026-07-01T00:00:00.000Z'
+ );
+ });
+
+ it('rejects invalid values with the flag name in the error', () => {
+ expect(() => parseTimeInput('yesterday-ish', 'since')).toThrow('--since');
+ });
+});
+
+describe('resolveTimeWindow', () => {
+ it('returns undefined when neither flag is given', () => {
+ expect(resolveTimeWindow({})).toBeUndefined();
+ });
+
+ it('defaults the end to now when only --since is given', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(resolveTimeWindow({ since: '24h' })).toEqual({
+ startTime: '2026-07-06T12:00:00.000Z',
+ endTime: '2026-07-07T12:00:00.000Z',
+ });
+ });
+
+ it('rejects --until without --since', () => {
+ expect(() => resolveTimeWindow({ until: '1h' })).toThrow(
+ '--until requires --since'
+ );
+ });
+
+ it('rejects inverted windows', () => {
+ expect(() => resolveTimeWindow({ since: '1h', until: '2h' })).toThrow(
+ '--since must be earlier than --until'
+ );
+ });
+});
+
+describe('planWindowStartFromResponse', () => {
+ it('extracts the plan window start from page metadata', () => {
+ expect(
+ planWindowStartFromResponse({
+ data: [],
+ pageInfo: {
+ currentLookbackDays: 30,
+ maxLookbackDays: 30,
+ currentWindowStart: '2026-06-07T12:00:00.000Z',
+ maxWindowStart: '2026-06-07T12:00:00.000Z',
+ upgradeAvailable: false,
+ },
+ })
+ ).toBe('2026-06-07T12:00:00.000Z');
+ });
+
+ it('returns undefined without page metadata', () => {
+ expect(planWindowStartFromResponse({ data: [] })).toBeUndefined();
+ expect(planWindowStartFromResponse(null)).toBeUndefined();
+ });
+});

packages/cli/src/lib/inspect/time-window.ts

@@ -0,0 +1,69 @@
+import type { AnalyticsPageInfo } from './pagination.js';
+
+const DURATION_UNIT_MS: Record<string, number> = {
+ m: 60_000,
+ h: 3_600_000,
+ d: 86_400_000,
+ w: 604_800_000,
+};
+
+/**
+ * Parse a `--since`/`--until` value: either a relative duration (`30m`,
+ * `12h`, `7d`, `2w`, interpreted as "that long ago") or an absolute
+ * timestamp accepted by `Date`.
+ */
+export function parseTimeInput(value: string, flagName: string): Date {
+ const duration = /^(\d+)(m|h|d|w)$/.exec(value.trim());
+ if (duration) {
+ const [, amount, unit] = duration;
+ return new Date(Date.now() - Number(amount) * DURATION_UNIT_MS[unit]);
+ }
+ const absolute = new Date(value);
+ if (!Number.isNaN(absolute.getTime())) {
+ return absolute;
+ }
+ throw new Error(
+ `Invalid --${flagName} value "${value}". Use a relative duration (30m, 12h, 7d, 2w) or a timestamp (2026-07-01T00:00:00Z).`
+ );
+}
+
+/**
+ * Resolve `--since`/`--until` flags into an explicit listing window for the
+ * analytics runs API, or undefined when neither flag was given (the backend
+ * then applies its default window). Windows older than the plan's
+ * observability lookback are rejected by the backend with
+ * `observability-upgrade-required`.
+ */
+export function resolveTimeWindow(opts: {
+ since?: string;
+ until?: string;
+}): { startTime: string; endTime: string } | undefined {
+ if (!opts.since && !opts.until) return undefined;
+ if (!opts.since) {
+ throw new Error('--until requires --since.');
+ }
+ const start = parseTimeInput(opts.since, 'since');
+ const end = opts.until
+ ? parseTimeInput(opts.until, 'until')
+ : new Date(Date.now());
+ if (start.getTime() >= end.getTime()) {
+ throw new Error('--since must be earlier than --until.');
+ }
+ return { startTime: start.toISOString(), endTime: end.toISOString() };
+}
+
+/**
+ * Extract the plan observability-window start from a paginated analytics
+ * response, for widening a defaulted (recent-window) listing to the whole
+ * window the plan allows. Returns undefined when the response carries no
+ * page metadata (e.g. non-Vercel backends).
+ */
+export function planWindowStartFromResponse(
+ result: unknown
+): string | undefined {
+ if (typeof result !== 'object' || result === null) return undefined;
+ const pageInfo = (result as { pageInfo?: AnalyticsPageInfo }).pageInfo;
+ if (!pageInfo?.currentWindowStart) return undefined;
+ const start = new Date(pageInfo.currentWindowStart);
+ return Number.isNaN(start.getTime()) ? undefined : start.toISOString();
+}

.changeset/cli-runs-time-window.md

@@ -0,0 +1,5 @@
+---
+'@workflow/cli': patch
+---
+
+Add `--since`/`--until` to `workflow inspect runs`; `workflow start` and bulk `workflow cancel` name lookups now search past the backend's default 24h window.

.changeset/web-runs-infinite-scroll.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web': patch
+---
+
+Runs list: infinite scroll with SWR-cached pages (tab switches no longer refetch), a plan-aware time-window picker (default 24h), and status filtering without requiring a workflow filter.

.changeset/world-analytics-time-window.md

@@ -0,0 +1,6 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+---
+
+Support `startTime`/`endTime` on `world.analytics.runs.list` to bound the listing window.

packages/cli/src/commands/cancel.ts

@@ -13,6 +13,7 @@ import {
 } from '../lib/inspect/errors.js';
 import { cliFlags } from '../lib/inspect/flags.js';
 import { setupCliWorld } from '../lib/inspect/setup.js';
+import { planWindowStartFromResponse } from '../lib/inspect/time-window.js';
 
 export default class Cancel extends BaseCommand {
  static description =
@@ -110,18 +111,38 @@ export default class Cancel extends BaseCommand {
  // Fetch matching runs. Only metadata is needed to display and cancel, so
  // prefer the analytics read path when the backend provides one.
  const status = flags.status as WorkflowRun['status'] | undefined;
- const runList = world.analytics
- ? await world.analytics.runs.list({
+ const limit = flags.limit || 50;
+ const analytics = world.analytics;
+ const fetchMatches = async () => {
+ if (!analytics) {
+ return world.runs.list({
  status,
  workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
- })
- : await world.runs.list({
- status,
- workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
+ pagination: { limit },
  resolveData: 'none',
  });
+ }
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend), but bulk cancel must match
+ // across the plan's whole observability window — a run can sleep or
+ // wait on a hook for days without emitting recent events. Probe for
+ // the plan window bounds first, then match across them.
+ const probe = await analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ pagination: { limit: 1 },
+ });
+ const windowStart = planWindowStartFromResponse(probe);
+ return analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ ...(windowStart
+ ? { startTime: windowStart, endTime: new Date().toISOString() }
+ : {}),
+ pagination: { limit },
+ });
+ };
+ const runList = await fetchMatches();
  const runs = {
  data: runList.data.map((run) => ({
  runId: run.runId,

packages/cli/src/commands/inspect.ts

@@ -129,6 +129,22 @@ export default class Inspect extends BaseCommand {
  helpGroup: 'Filtering',
  helpLabel: '--status',
  }),
+ since: Flags.string({
+ description:
+ 'list runs active since a relative duration (30m, 12h, 7d, 2w) or timestamp; defaults to the backend window (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--since',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
+ until: Flags.string({
+ description:
+ 'end of the --since listing window, as a relative duration or timestamp; defaults to now (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--until',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
  withData: Flags.boolean({
  description:
  'include full input/output data in list views (deprecated for list views — use `inspect <resource> <id>` to view payloads)',
@@ -282,6 +298,8 @@ function toInspectOptions(flags: any): InspectCLIOptions {
  limit: flags.limit,
  workflowName: flags.workflowName,
  status: flags.status,
+ since: flags.since,
+ until: flags.until,
  withData: flags.withData,
  decrypt: flags.decrypt,
  backend: flags.backend,

packages/cli/src/lib/config/types.ts

@@ -19,6 +19,10 @@ export type InspectCLIOptions = {
  limit?: number;
  workflowName?: string;
  status?: string;
+ /** Listing window start: relative duration (12h, 7d) or timestamp (runs only) */
+ since?: string;
+ /** Listing window end: relative duration or timestamp; requires --since */
+ until?: string;
  withData?: boolean;
  backend?: string;
  disableRelativeDates?: boolean;

packages/cli/src/lib/inspect/output.ts

@@ -23,6 +23,7 @@ import {
  isEncryptedRef,
  isExpiredRef,
 } from './hydration.js';
+import { resolveTimeWindow } from './time-window.js';
 
 /**
  * Create an EncryptionKeyResolver from a World instance.
@@ -620,6 +621,17 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const resolveData = opts.withData ? 'all' : 'none';
  const status = opts.status as WorkflowRun['status'] | undefined;
 
+ // Resolve --since/--until into an explicit listing window. Only the
+ // analytics read path supports one; the runtime storage APIs have no time
+ // filter. Without the flags the backend applies its default window
+ // (trailing 24h on the Vercel backend).
+ const timeWindow = resolveTimeWindow(opts);
+ if (timeWindow && !useAnalytics) {
+ logger.warn(
+ '--since/--until require the analytics read path and are ignored by this backend.'
+ );
+ }
+
  // Determine which props to show based on withData flag
  const props = opts.withData
  ? WORKFLOW_RUN_LISTED_PROPS
@@ -639,6 +651,7 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const runs = await world.analytics.runs.list({
  workflowName: opts.workflowName,
  status,
+ ...(timeWindow ?? {}),
  pagination,
  });
  return {

packages/cli/src/lib/inspect/run.ts

@@ -2,6 +2,7 @@ import { start } from '@workflow/core/runtime';
 import { healthCheck } from '@workflow/core/runtime/helpers';
 import type { World } from '@workflow/world';
 import { logger } from '../config/log.js';
+import { planWindowStartFromResponse } from './time-window.js';
 
 interface CLICreateOpts {
  json?: boolean;
@@ -57,6 +58,23 @@ export const startRun = async (
  resolveData: 'none',
  });
  run = runList.data[0];
+
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend). When the name wasn't found
+ // there, retry across the plan's whole observability window using the
+ // window bounds from the response's page metadata.
+ if (!run && world.analytics) {
+ const windowStart = planWindowStartFromResponse(runList);
+ if (windowStart) {
+ const widened = await world.analytics.runs.list({
+ workflowName: workflowNameOrRunId,
+ startTime: windowStart,
+ endTime: new Date().toISOString(),
+ pagination: { sortOrder: 'desc', limit: 1 },
+ });
+ run = widened.data[0];
+ }
+ }
  }
 
  if (!run) {

packages/cli/src/lib/inspect/time-window.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ parseTimeInput,
+ planWindowStartFromResponse,
+ resolveTimeWindow,
+} from './time-window.js';
+
+const NOW = new Date('2026-07-07T12:00:00.000Z');
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('parseTimeInput', () => {
+ it('parses relative durations as that long ago', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(parseTimeInput('30m', 'since').toISOString()).toBe(
+ '2026-07-07T11:30:00.000Z'
+ );
+ expect(parseTimeInput('12h', 'since').toISOString()).toBe(
+ '2026-07-07T00:00:00.000Z'
+ );
+ expect(parseTimeInput('7d', 'since').toISOString()).toBe(
+ '2026-06-30T12:00:00.000Z'
+ );
+ expect(parseTimeInput('2w', 'since').toISOString()).toBe(
+ '2026-06-23T12:00:00.000Z'
+ );
+ });
+
+ it('parses absolute timestamps', () => {
+ expect(parseTimeInput('2026-07-01T00:00:00Z', 'since').toISOString()).toBe(
+ '2026-07-01T00:00:00.000Z'
+ );
+ });
+
+ it('rejects invalid values with the flag name in the error', () => {
+ expect(() => parseTimeInput('yesterday-ish', 'since')).toThrow('--since');
+ });
+});
+
+describe('resolveTimeWindow', () => {
+ it('returns undefined when neither flag is given', () => {
+ expect(resolveTimeWindow({})).toBeUndefined();
+ });
+
+ it('defaults the end to now when only --since is given', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(resolveTimeWindow({ since: '24h' })).toEqual({
+ startTime: '2026-07-06T12:00:00.000Z',
+ endTime: '2026-07-07T12:00:00.000Z',
+ });
+ });
+
+ it('rejects --until without --since', () => {
+ expect(() => resolveTimeWindow({ until: '1h' })).toThrow(
+ '--until requires --since'
+ );
+ });
+
+ it('rejects inverted windows', () => {
+ expect(() => resolveTimeWindow({ since: '1h', until: '2h' })).toThrow(
+ '--since must be earlier than --until'
+ );
+ });
+});
+
+describe('planWindowStartFromResponse', () => {
+ it('extracts the plan window start from page metadata', () => {
+ expect(
+ planWindowStartFromResponse({
+ data: [],
+ pageInfo: {
+ currentLookbackDays: 30,
+ maxLookbackDays: 30,
+ currentWindowStart: '2026-06-07T12:00:00.000Z',
+ maxWindowStart: '2026-06-07T12:00:00.000Z',
+ upgradeAvailable: false,
+ },
+ })
+ ).toBe('2026-06-07T12:00:00.000Z');
+ });
+
+ it('returns undefined without page metadata', () => {
+ expect(planWindowStartFromResponse({ data: [] })).toBeUndefined();
+ expect(planWindowStartFromResponse(null)).toBeUndefined();
+ });
+});

packages/cli/src/lib/inspect/time-window.ts

@@ -0,0 +1,69 @@
+import type { AnalyticsPageInfo } from './pagination.js';
+
+const DURATION_UNIT_MS: Record<string, number> = {
+ m: 60_000,
+ h: 3_600_000,
+ d: 86_400_000,
+ w: 604_800_000,
+};
+
+/**
+ * Parse a `--since`/`--until` value: either a relative duration (`30m`,
+ * `12h`, `7d`, `2w`, interpreted as "that long ago") or an absolute
+ * timestamp accepted by `Date`.
+ */
+export function parseTimeInput(value: string, flagName: string): Date {
+ const duration = /^(\d+)(m|h|d|w)$/.exec(value.trim());
+ if (duration) {
+ const [, amount, unit] = duration;
+ return new Date(Date.now() - Number(amount) * DURATION_UNIT_MS[unit]);
+ }
+ const absolute = new Date(value);
+ if (!Number.isNaN(absolute.getTime())) {
+ return absolute;
+ }
+ throw new Error(
+ `Invalid --${flagName} value "${value}". Use a relative duration (30m, 12h, 7d, 2w) or a timestamp (2026-07-01T00:00:00Z).`
+ );
+}
+
+/**
+ * Resolve `--since`/`--until` flags into an explicit listing window for the
+ * analytics runs API, or undefined when neither flag was given (the backend
+ * then applies its default window). Windows older than the plan's
+ * observability lookback are rejected by the backend with
+ * `observability-upgrade-required`.
+ */
+export function resolveTimeWindow(opts: {
+ since?: string;
+ until?: string;
+}): { startTime: string; endTime: string } | undefined {
+ if (!opts.since && !opts.until) return undefined;
+ if (!opts.since) {
+ throw new Error('--until requires --since.');
+ }
+ const start = parseTimeInput(opts.since, 'since');
+ const end = opts.until
+ ? parseTimeInput(opts.until, 'until')
+ : new Date(Date.now());
+ if (start.getTime() >= end.getTime()) {
+ throw new Error('--since must be earlier than --until.');
+ }
+ return { startTime: start.toISOString(), endTime: end.toISOString() };
+}
+
+/**
+ * Extract the plan observability-window start from a paginated analytics
+ * response, for widening a defaulted (recent-window) listing to the whole
+ * window the plan allows. Returns undefined when the response carries no
+ * page metadata (e.g. non-Vercel backends).
+ */
+export function planWindowStartFromResponse(
+ result: unknown
+): string | undefined {
+ if (typeof result !== 'object' || result === null) return undefined;
+ const pageInfo = (result as { pageInfo?: AnalyticsPageInfo }).pageInfo;
+ if (!pageInfo?.currentWindowStart) return undefined;
+ const start = new Date(pageInfo.currentWindowStart);
+ return Number.isNaN(start.getTime()) ? undefined : start.toISOString();
+}

.changeset/cli-runs-time-window.md

@@ -0,0 +1,5 @@
+---
+'@workflow/cli': patch
+---
+
+Add `--since`/`--until` to `workflow inspect runs`; `workflow start` and bulk `workflow cancel` name lookups now search past the backend's default 24h window.

.changeset/web-runs-infinite-scroll.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web': patch
+---
+
+Runs list: infinite scroll with SWR-cached pages (tab switches no longer refetch), a plan-aware time-window picker (default 24h), and status filtering without requiring a workflow filter.

.changeset/world-analytics-time-window.md

@@ -0,0 +1,6 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+---
+
+Support `startTime`/`endTime` on `world.analytics.runs.list` to bound the listing window.

packages/cli/src/commands/cancel.ts

@@ -13,6 +13,7 @@ import {
 } from '../lib/inspect/errors.js';
 import { cliFlags } from '../lib/inspect/flags.js';
 import { setupCliWorld } from '../lib/inspect/setup.js';
+import { planWindowStartFromResponse } from '../lib/inspect/time-window.js';
 
 export default class Cancel extends BaseCommand {
  static description =
@@ -110,18 +111,38 @@ export default class Cancel extends BaseCommand {
  // Fetch matching runs. Only metadata is needed to display and cancel, so
  // prefer the analytics read path when the backend provides one.
  const status = flags.status as WorkflowRun['status'] | undefined;
- const runList = world.analytics
- ? await world.analytics.runs.list({
+ const limit = flags.limit || 50;
+ const analytics = world.analytics;
+ const fetchMatches = async () => {
+ if (!analytics) {
+ return world.runs.list({
  status,
  workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
- })
- : await world.runs.list({
- status,
- workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
+ pagination: { limit },
  resolveData: 'none',
  });
+ }
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend), but bulk cancel must match
+ // across the plan's whole observability window — a run can sleep or
+ // wait on a hook for days without emitting recent events. Probe for
+ // the plan window bounds first, then match across them.
+ const probe = await analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ pagination: { limit: 1 },
+ });
+ const windowStart = planWindowStartFromResponse(probe);
+ return analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ ...(windowStart
+ ? { startTime: windowStart, endTime: new Date().toISOString() }
+ : {}),
+ pagination: { limit },
+ });
+ };
+ const runList = await fetchMatches();
  const runs = {
  data: runList.data.map((run) => ({
  runId: run.runId,

packages/cli/src/commands/inspect.ts

@@ -129,6 +129,22 @@ export default class Inspect extends BaseCommand {
  helpGroup: 'Filtering',
  helpLabel: '--status',
  }),
+ since: Flags.string({
+ description:
+ 'list runs active since a relative duration (30m, 12h, 7d, 2w) or timestamp; defaults to the backend window (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--since',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
+ until: Flags.string({
+ description:
+ 'end of the --since listing window, as a relative duration or timestamp; defaults to now (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--until',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
  withData: Flags.boolean({
  description:
  'include full input/output data in list views (deprecated for list views — use `inspect <resource> <id>` to view payloads)',
@@ -282,6 +298,8 @@ function toInspectOptions(flags: any): InspectCLIOptions {
  limit: flags.limit,
  workflowName: flags.workflowName,
  status: flags.status,
+ since: flags.since,
+ until: flags.until,
  withData: flags.withData,
  decrypt: flags.decrypt,
  backend: flags.backend,

packages/cli/src/lib/config/types.ts

@@ -19,6 +19,10 @@ export type InspectCLIOptions = {
  limit?: number;
  workflowName?: string;
  status?: string;
+ /** Listing window start: relative duration (12h, 7d) or timestamp (runs only) */
+ since?: string;
+ /** Listing window end: relative duration or timestamp; requires --since */
+ until?: string;
  withData?: boolean;
  backend?: string;
  disableRelativeDates?: boolean;

packages/cli/src/lib/inspect/output.ts

@@ -23,6 +23,7 @@ import {
  isEncryptedRef,
  isExpiredRef,
 } from './hydration.js';
+import { resolveTimeWindow } from './time-window.js';
 
 /**
  * Create an EncryptionKeyResolver from a World instance.
@@ -620,6 +621,17 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const resolveData = opts.withData ? 'all' : 'none';
  const status = opts.status as WorkflowRun['status'] | undefined;
 
+ // Resolve --since/--until into an explicit listing window. Only the
+ // analytics read path supports one; the runtime storage APIs have no time
+ // filter. Without the flags the backend applies its default window
+ // (trailing 24h on the Vercel backend).
+ const timeWindow = resolveTimeWindow(opts);
+ if (timeWindow && !useAnalytics) {
+ logger.warn(
+ '--since/--until require the analytics read path and are ignored by this backend.'
+ );
+ }
+
  // Determine which props to show based on withData flag
  const props = opts.withData
  ? WORKFLOW_RUN_LISTED_PROPS
@@ -639,6 +651,7 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const runs = await world.analytics.runs.list({
  workflowName: opts.workflowName,
  status,
+ ...(timeWindow ?? {}),
  pagination,
  });
  return {

packages/cli/src/lib/inspect/run.ts

@@ -2,6 +2,7 @@ import { start } from '@workflow/core/runtime';
 import { healthCheck } from '@workflow/core/runtime/helpers';
 import type { World } from '@workflow/world';
 import { logger } from '../config/log.js';
+import { planWindowStartFromResponse } from './time-window.js';
 
 interface CLICreateOpts {
  json?: boolean;
@@ -57,6 +58,23 @@ export const startRun = async (
  resolveData: 'none',
  });
  run = runList.data[0];
+
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend). When the name wasn't found
+ // there, retry across the plan's whole observability window using the
+ // window bounds from the response's page metadata.
+ if (!run && world.analytics) {
+ const windowStart = planWindowStartFromResponse(runList);
+ if (windowStart) {
+ const widened = await world.analytics.runs.list({
+ workflowName: workflowNameOrRunId,
+ startTime: windowStart,
+ endTime: new Date().toISOString(),
+ pagination: { sortOrder: 'desc', limit: 1 },
+ });
+ run = widened.data[0];
+ }
+ }
  }
 
  if (!run) {

packages/cli/src/lib/inspect/time-window.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ parseTimeInput,
+ planWindowStartFromResponse,
+ resolveTimeWindow,
+} from './time-window.js';
+
+const NOW = new Date('2026-07-07T12:00:00.000Z');
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('parseTimeInput', () => {
+ it('parses relative durations as that long ago', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(parseTimeInput('30m', 'since').toISOString()).toBe(
+ '2026-07-07T11:30:00.000Z'
+ );
+ expect(parseTimeInput('12h', 'since').toISOString()).toBe(
+ '2026-07-07T00:00:00.000Z'
+ );
+ expect(parseTimeInput('7d', 'since').toISOString()).toBe(
+ '2026-06-30T12:00:00.000Z'
+ );
+ expect(parseTimeInput('2w', 'since').toISOString()).toBe(
+ '2026-06-23T12:00:00.000Z'
+ );
+ });
+
+ it('parses absolute timestamps', () => {
+ expect(parseTimeInput('2026-07-01T00:00:00Z', 'since').toISOString()).toBe(
+ '2026-07-01T00:00:00.000Z'
+ );
+ });
+
+ it('rejects invalid values with the flag name in the error', () => {
+ expect(() => parseTimeInput('yesterday-ish', 'since')).toThrow('--since');
+ });
+});
+
+describe('resolveTimeWindow', () => {
+ it('returns undefined when neither flag is given', () => {
+ expect(resolveTimeWindow({})).toBeUndefined();
+ });
+
+ it('defaults the end to now when only --since is given', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(resolveTimeWindow({ since: '24h' })).toEqual({
+ startTime: '2026-07-06T12:00:00.000Z',
+ endTime: '2026-07-07T12:00:00.000Z',
+ });
+ });
+
+ it('rejects --until without --since', () => {
+ expect(() => resolveTimeWindow({ until: '1h' })).toThrow(
+ '--until requires --since'
+ );
+ });
+
+ it('rejects inverted windows', () => {
+ expect(() => resolveTimeWindow({ since: '1h', until: '2h' })).toThrow(
+ '--since must be earlier than --until'
+ );
+ });
+});
+
+describe('planWindowStartFromResponse', () => {
+ it('extracts the plan window start from page metadata', () => {
+ expect(
+ planWindowStartFromResponse({
+ data: [],
+ pageInfo: {
+ currentLookbackDays: 30,
+ maxLookbackDays: 30,
+ currentWindowStart: '2026-06-07T12:00:00.000Z',
+ maxWindowStart: '2026-06-07T12:00:00.000Z',
+ upgradeAvailable: false,
+ },
+ })
+ ).toBe('2026-06-07T12:00:00.000Z');
+ });
+
+ it('returns undefined without page metadata', () => {
+ expect(planWindowStartFromResponse({ data: [] })).toBeUndefined();
+ expect(planWindowStartFromResponse(null)).toBeUndefined();
+ });
+});

packages/cli/src/lib/inspect/time-window.ts

@@ -0,0 +1,69 @@
+import type { AnalyticsPageInfo } from './pagination.js';
+
+const DURATION_UNIT_MS: Record<string, number> = {
+ m: 60_000,
+ h: 3_600_000,
+ d: 86_400_000,
+ w: 604_800_000,
+};
+
+/**
+ * Parse a `--since`/`--until` value: either a relative duration (`30m`,
+ * `12h`, `7d`, `2w`, interpreted as "that long ago") or an absolute
+ * timestamp accepted by `Date`.
+ */
+export function parseTimeInput(value: string, flagName: string): Date {
+ const duration = /^(\d+)(m|h|d|w)$/.exec(value.trim());
+ if (duration) {
+ const [, amount, unit] = duration;
+ return new Date(Date.now() - Number(amount) * DURATION_UNIT_MS[unit]);
+ }
+ const absolute = new Date(value);
+ if (!Number.isNaN(absolute.getTime())) {
+ return absolute;
+ }
+ throw new Error(
+ `Invalid --${flagName} value "${value}". Use a relative duration (30m, 12h, 7d, 2w) or a timestamp (2026-07-01T00:00:00Z).`
+ );
+}
+
+/**
+ * Resolve `--since`/`--until` flags into an explicit listing window for the
+ * analytics runs API, or undefined when neither flag was given (the backend
+ * then applies its default window). Windows older than the plan's
+ * observability lookback are rejected by the backend with
+ * `observability-upgrade-required`.
+ */
+export function resolveTimeWindow(opts: {
+ since?: string;
+ until?: string;
+}): { startTime: string; endTime: string } | undefined {
+ if (!opts.since && !opts.until) return undefined;
+ if (!opts.since) {
+ throw new Error('--until requires --since.');
+ }
+ const start = parseTimeInput(opts.since, 'since');
+ const end = opts.until
+ ? parseTimeInput(opts.until, 'until')
+ : new Date(Date.now());
+ if (start.getTime() >= end.getTime()) {
+ throw new Error('--since must be earlier than --until.');
+ }
+ return { startTime: start.toISOString(), endTime: end.toISOString() };
+}
+
+/**
+ * Extract the plan observability-window start from a paginated analytics
+ * response, for widening a defaulted (recent-window) listing to the whole
+ * window the plan allows. Returns undefined when the response carries no
+ * page metadata (e.g. non-Vercel backends).
+ */
+export function planWindowStartFromResponse(
+ result: unknown
+): string | undefined {
+ if (typeof result !== 'object' || result === null) return undefined;
+ const pageInfo = (result as { pageInfo?: AnalyticsPageInfo }).pageInfo;
+ if (!pageInfo?.currentWindowStart) return undefined;
+ const start = new Date(pageInfo.currentWindowStart);
+ return Number.isNaN(start.getTime()) ? undefined : start.toISOString();
+}

.changeset/cli-runs-time-window.md

@@ -0,0 +1,5 @@
+---
+'@workflow/cli': patch
+---
+
+Add `--since`/`--until` to `workflow inspect runs`; `workflow start` and bulk `workflow cancel` name lookups now search past the backend's default 24h window.

.changeset/web-runs-infinite-scroll.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web': patch
+---
+
+Runs list: infinite scroll with SWR-cached pages (tab switches no longer refetch), a plan-aware time-window picker (default 24h), and status filtering without requiring a workflow filter.

.changeset/world-analytics-time-window.md

@@ -0,0 +1,6 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+---
+
+Support `startTime`/`endTime` on `world.analytics.runs.list` to bound the listing window.

packages/cli/src/commands/cancel.ts

@@ -13,6 +13,7 @@ import {
 } from '../lib/inspect/errors.js';
 import { cliFlags } from '../lib/inspect/flags.js';
 import { setupCliWorld } from '../lib/inspect/setup.js';
+import { planWindowStartFromResponse } from '../lib/inspect/time-window.js';
 
 export default class Cancel extends BaseCommand {
  static description =
@@ -110,18 +111,38 @@ export default class Cancel extends BaseCommand {
  // Fetch matching runs. Only metadata is needed to display and cancel, so
  // prefer the analytics read path when the backend provides one.
  const status = flags.status as WorkflowRun['status'] | undefined;
- const runList = world.analytics
- ? await world.analytics.runs.list({
+ const limit = flags.limit || 50;
+ const analytics = world.analytics;
+ const fetchMatches = async () => {
+ if (!analytics) {
+ return world.runs.list({
  status,
  workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
- })
- : await world.runs.list({
- status,
- workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
+ pagination: { limit },
  resolveData: 'none',
  });
+ }
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend), but bulk cancel must match
+ // across the plan's whole observability window — a run can sleep or
+ // wait on a hook for days without emitting recent events. Probe for
+ // the plan window bounds first, then match across them.
+ const probe = await analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ pagination: { limit: 1 },
+ });
+ const windowStart = planWindowStartFromResponse(probe);
+ return analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ ...(windowStart
+ ? { startTime: windowStart, endTime: new Date().toISOString() }
+ : {}),
+ pagination: { limit },
+ });
+ };
+ const runList = await fetchMatches();
  const runs = {
  data: runList.data.map((run) => ({
  runId: run.runId,

packages/cli/src/commands/inspect.ts

@@ -129,6 +129,22 @@ export default class Inspect extends BaseCommand {
  helpGroup: 'Filtering',
  helpLabel: '--status',
  }),
+ since: Flags.string({
+ description:
+ 'list runs active since a relative duration (30m, 12h, 7d, 2w) or timestamp; defaults to the backend window (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--since',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
+ until: Flags.string({
+ description:
+ 'end of the --since listing window, as a relative duration or timestamp; defaults to now (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--until',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
  withData: Flags.boolean({
  description:
  'include full input/output data in list views (deprecated for list views — use `inspect <resource> <id>` to view payloads)',
@@ -282,6 +298,8 @@ function toInspectOptions(flags: any): InspectCLIOptions {
  limit: flags.limit,
  workflowName: flags.workflowName,
  status: flags.status,
+ since: flags.since,
+ until: flags.until,
  withData: flags.withData,
  decrypt: flags.decrypt,
  backend: flags.backend,

packages/cli/src/lib/config/types.ts

@@ -19,6 +19,10 @@ export type InspectCLIOptions = {
  limit?: number;
  workflowName?: string;
  status?: string;
+ /** Listing window start: relative duration (12h, 7d) or timestamp (runs only) */
+ since?: string;
+ /** Listing window end: relative duration or timestamp; requires --since */
+ until?: string;
  withData?: boolean;
  backend?: string;
  disableRelativeDates?: boolean;

packages/cli/src/lib/inspect/output.ts

@@ -23,6 +23,7 @@ import {
  isEncryptedRef,
  isExpiredRef,
 } from './hydration.js';
+import { resolveTimeWindow } from './time-window.js';
 
 /**
  * Create an EncryptionKeyResolver from a World instance.
@@ -620,6 +621,17 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const resolveData = opts.withData ? 'all' : 'none';
  const status = opts.status as WorkflowRun['status'] | undefined;
 
+ // Resolve --since/--until into an explicit listing window. Only the
+ // analytics read path supports one; the runtime storage APIs have no time
+ // filter. Without the flags the backend applies its default window
+ // (trailing 24h on the Vercel backend).
+ const timeWindow = resolveTimeWindow(opts);
+ if (timeWindow && !useAnalytics) {
+ logger.warn(
+ '--since/--until require the analytics read path and are ignored by this backend.'
+ );
+ }
+
  // Determine which props to show based on withData flag
  const props = opts.withData
  ? WORKFLOW_RUN_LISTED_PROPS
@@ -639,6 +651,7 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const runs = await world.analytics.runs.list({
  workflowName: opts.workflowName,
  status,
+ ...(timeWindow ?? {}),
  pagination,
  });
  return {

packages/cli/src/lib/inspect/run.ts

@@ -2,6 +2,7 @@ import { start } from '@workflow/core/runtime';
 import { healthCheck } from '@workflow/core/runtime/helpers';
 import type { World } from '@workflow/world';
 import { logger } from '../config/log.js';
+import { planWindowStartFromResponse } from './time-window.js';
 
 interface CLICreateOpts {
  json?: boolean;
@@ -57,6 +58,23 @@ export const startRun = async (
  resolveData: 'none',
  });
  run = runList.data[0];
+
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend). When the name wasn't found
+ // there, retry across the plan's whole observability window using the
+ // window bounds from the response's page metadata.
+ if (!run && world.analytics) {
+ const windowStart = planWindowStartFromResponse(runList);
+ if (windowStart) {
+ const widened = await world.analytics.runs.list({
+ workflowName: workflowNameOrRunId,
+ startTime: windowStart,
+ endTime: new Date().toISOString(),
+ pagination: { sortOrder: 'desc', limit: 1 },
+ });
+ run = widened.data[0];
+ }
+ }
  }
 
  if (!run) {

packages/cli/src/lib/inspect/time-window.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ parseTimeInput,
+ planWindowStartFromResponse,
+ resolveTimeWindow,
+} from './time-window.js';
+
+const NOW = new Date('2026-07-07T12:00:00.000Z');
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('parseTimeInput', () => {
+ it('parses relative durations as that long ago', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(parseTimeInput('30m', 'since').toISOString()).toBe(
+ '2026-07-07T11:30:00.000Z'
+ );
+ expect(parseTimeInput('12h', 'since').toISOString()).toBe(
+ '2026-07-07T00:00:00.000Z'
+ );
+ expect(parseTimeInput('7d', 'since').toISOString()).toBe(
+ '2026-06-30T12:00:00.000Z'
+ );
+ expect(parseTimeInput('2w', 'since').toISOString()).toBe(
+ '2026-06-23T12:00:00.000Z'
+ );
+ });
+
+ it('parses absolute timestamps', () => {
+ expect(parseTimeInput('2026-07-01T00:00:00Z', 'since').toISOString()).toBe(
+ '2026-07-01T00:00:00.000Z'
+ );
+ });
+
+ it('rejects invalid values with the flag name in the error', () => {
+ expect(() => parseTimeInput('yesterday-ish', 'since')).toThrow('--since');
+ });
+});
+
+describe('resolveTimeWindow', () => {
+ it('returns undefined when neither flag is given', () => {
+ expect(resolveTimeWindow({})).toBeUndefined();
+ });
+
+ it('defaults the end to now when only --since is given', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(resolveTimeWindow({ since: '24h' })).toEqual({
+ startTime: '2026-07-06T12:00:00.000Z',
+ endTime: '2026-07-07T12:00:00.000Z',
+ });
+ });
+
+ it('rejects --until without --since', () => {
+ expect(() => resolveTimeWindow({ until: '1h' })).toThrow(
+ '--until requires --since'
+ );
+ });
+
+ it('rejects inverted windows', () => {
+ expect(() => resolveTimeWindow({ since: '1h', until: '2h' })).toThrow(
+ '--since must be earlier than --until'
+ );
+ });
+});
+
+describe('planWindowStartFromResponse', () => {
+ it('extracts the plan window start from page metadata', () => {
+ expect(
+ planWindowStartFromResponse({
+ data: [],
+ pageInfo: {
+ currentLookbackDays: 30,
+ maxLookbackDays: 30,
+ currentWindowStart: '2026-06-07T12:00:00.000Z',
+ maxWindowStart: '2026-06-07T12:00:00.000Z',
+ upgradeAvailable: false,
+ },
+ })
+ ).toBe('2026-06-07T12:00:00.000Z');
+ });
+
+ it('returns undefined without page metadata', () => {
+ expect(planWindowStartFromResponse({ data: [] })).toBeUndefined();
+ expect(planWindowStartFromResponse(null)).toBeUndefined();
+ });
+});

packages/cli/src/lib/inspect/time-window.ts

@@ -0,0 +1,69 @@
+import type { AnalyticsPageInfo } from './pagination.js';
+
+const DURATION_UNIT_MS: Record<string, number> = {
+ m: 60_000,
+ h: 3_600_000,
+ d: 86_400_000,
+ w: 604_800_000,
+};
+
+/**
+ * Parse a `--since`/`--until` value: either a relative duration (`30m`,
+ * `12h`, `7d`, `2w`, interpreted as "that long ago") or an absolute
+ * timestamp accepted by `Date`.
+ */
+export function parseTimeInput(value: string, flagName: string): Date {
+ const duration = /^(\d+)(m|h|d|w)$/.exec(value.trim());
+ if (duration) {
+ const [, amount, unit] = duration;
+ return new Date(Date.now() - Number(amount) * DURATION_UNIT_MS[unit]);
+ }
+ const absolute = new Date(value);
+ if (!Number.isNaN(absolute.getTime())) {
+ return absolute;
+ }
+ throw new Error(
+ `Invalid --${flagName} value "${value}". Use a relative duration (30m, 12h, 7d, 2w) or a timestamp (2026-07-01T00:00:00Z).`
+ );
+}
+
+/**
+ * Resolve `--since`/`--until` flags into an explicit listing window for the
+ * analytics runs API, or undefined when neither flag was given (the backend
+ * then applies its default window). Windows older than the plan's
+ * observability lookback are rejected by the backend with
+ * `observability-upgrade-required`.
+ */
+export function resolveTimeWindow(opts: {
+ since?: string;
+ until?: string;
+}): { startTime: string; endTime: string } | undefined {
+ if (!opts.since && !opts.until) return undefined;
+ if (!opts.since) {
+ throw new Error('--until requires --since.');
+ }
+ const start = parseTimeInput(opts.since, 'since');
+ const end = opts.until
+ ? parseTimeInput(opts.until, 'until')
+ : new Date(Date.now());
+ if (start.getTime() >= end.getTime()) {
+ throw new Error('--since must be earlier than --until.');
+ }
+ return { startTime: start.toISOString(), endTime: end.toISOString() };
+}
+
+/**
+ * Extract the plan observability-window start from a paginated analytics
+ * response, for widening a defaulted (recent-window) listing to the whole
+ * window the plan allows. Returns undefined when the response carries no
+ * page metadata (e.g. non-Vercel backends).
+ */
+export function planWindowStartFromResponse(
+ result: unknown
+): string | undefined {
+ if (typeof result !== 'object' || result === null) return undefined;
+ const pageInfo = (result as { pageInfo?: AnalyticsPageInfo }).pageInfo;
+ if (!pageInfo?.currentWindowStart) return undefined;
+ const start = new Date(pageInfo.currentWindowStart);
+ return Number.isNaN(start.getTime()) ? undefined : start.toISOString();
+}

.changeset/cli-runs-time-window.md

@@ -0,0 +1,5 @@
+---
+'@workflow/cli': patch
+---
+
+Add `--since`/`--until` to `workflow inspect runs`; `workflow start` and bulk `workflow cancel` name lookups now search past the backend's default 24h window.

.changeset/web-runs-infinite-scroll.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web': patch
+---
+
+Runs list: infinite scroll with SWR-cached pages (tab switches no longer refetch), a plan-aware time-window picker (default 24h), and status filtering without requiring a workflow filter.

.changeset/world-analytics-time-window.md

@@ -0,0 +1,6 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+---
+
+Support `startTime`/`endTime` on `world.analytics.runs.list` to bound the listing window.

packages/cli/src/commands/cancel.ts

@@ -13,6 +13,7 @@ import {
 } from '../lib/inspect/errors.js';
 import { cliFlags } from '../lib/inspect/flags.js';
 import { setupCliWorld } from '../lib/inspect/setup.js';
+import { planWindowStartFromResponse } from '../lib/inspect/time-window.js';
 
 export default class Cancel extends BaseCommand {
  static description =
@@ -110,18 +111,38 @@ export default class Cancel extends BaseCommand {
  // Fetch matching runs. Only metadata is needed to display and cancel, so
  // prefer the analytics read path when the backend provides one.
  const status = flags.status as WorkflowRun['status'] | undefined;
- const runList = world.analytics
- ? await world.analytics.runs.list({
+ const limit = flags.limit || 50;
+ const analytics = world.analytics;
+ const fetchMatches = async () => {
+ if (!analytics) {
+ return world.runs.list({
  status,
  workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
- })
- : await world.runs.list({
- status,
- workflowName: flags.workflowName,
- pagination: { limit: flags.limit || 50 },
+ pagination: { limit },
  resolveData: 'none',
  });
+ }
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend), but bulk cancel must match
+ // across the plan's whole observability window — a run can sleep or
+ // wait on a hook for days without emitting recent events. Probe for
+ // the plan window bounds first, then match across them.
+ const probe = await analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ pagination: { limit: 1 },
+ });
+ const windowStart = planWindowStartFromResponse(probe);
+ return analytics.runs.list({
+ status,
+ workflowName: flags.workflowName,
+ ...(windowStart
+ ? { startTime: windowStart, endTime: new Date().toISOString() }
+ : {}),
+ pagination: { limit },
+ });
+ };
+ const runList = await fetchMatches();
  const runs = {
  data: runList.data.map((run) => ({
  runId: run.runId,

packages/cli/src/commands/inspect.ts

@@ -129,6 +129,22 @@ export default class Inspect extends BaseCommand {
  helpGroup: 'Filtering',
  helpLabel: '--status',
  }),
+ since: Flags.string({
+ description:
+ 'list runs active since a relative duration (30m, 12h, 7d, 2w) or timestamp; defaults to the backend window (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--since',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
+ until: Flags.string({
+ description:
+ 'end of the --since listing window, as a relative duration or timestamp; defaults to now (only for runs)',
+ required: false,
+ helpGroup: 'Filtering',
+ helpLabel: '--until',
+ helpValue: 'DURATION|TIMESTAMP',
+ }),
  withData: Flags.boolean({
  description:
  'include full input/output data in list views (deprecated for list views — use `inspect <resource> <id>` to view payloads)',
@@ -282,6 +298,8 @@ function toInspectOptions(flags: any): InspectCLIOptions {
  limit: flags.limit,
  workflowName: flags.workflowName,
  status: flags.status,
+ since: flags.since,
+ until: flags.until,
  withData: flags.withData,
  decrypt: flags.decrypt,
  backend: flags.backend,

packages/cli/src/lib/config/types.ts

@@ -19,6 +19,10 @@ export type InspectCLIOptions = {
  limit?: number;
  workflowName?: string;
  status?: string;
+ /** Listing window start: relative duration (12h, 7d) or timestamp (runs only) */
+ since?: string;
+ /** Listing window end: relative duration or timestamp; requires --since */
+ until?: string;
  withData?: boolean;
  backend?: string;
  disableRelativeDates?: boolean;

packages/cli/src/lib/inspect/output.ts

@@ -23,6 +23,7 @@ import {
  isEncryptedRef,
  isExpiredRef,
 } from './hydration.js';
+import { resolveTimeWindow } from './time-window.js';
 
 /**
  * Create an EncryptionKeyResolver from a World instance.
@@ -620,6 +621,17 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const resolveData = opts.withData ? 'all' : 'none';
  const status = opts.status as WorkflowRun['status'] | undefined;
 
+ // Resolve --since/--until into an explicit listing window. Only the
+ // analytics read path supports one; the runtime storage APIs have no time
+ // filter. Without the flags the backend applies its default window
+ // (trailing 24h on the Vercel backend).
+ const timeWindow = resolveTimeWindow(opts);
+ if (timeWindow && !useAnalytics) {
+ logger.warn(
+ '--since/--until require the analytics read path and are ignored by this backend.'
+ );
+ }
+
  // Determine which props to show based on withData flag
  const props = opts.withData
  ? WORKFLOW_RUN_LISTED_PROPS
@@ -639,6 +651,7 @@ export const listRuns = async (world: World, opts: InspectCLIOptions = {}) => {
  const runs = await world.analytics.runs.list({
  workflowName: opts.workflowName,
  status,
+ ...(timeWindow ?? {}),
  pagination,
  });
  return {

packages/cli/src/lib/inspect/run.ts

@@ -2,6 +2,7 @@ import { start } from '@workflow/core/runtime';
 import { healthCheck } from '@workflow/core/runtime/helpers';
 import type { World } from '@workflow/world';
 import { logger } from '../config/log.js';
+import { planWindowStartFromResponse } from './time-window.js';
 
 interface CLICreateOpts {
  json?: boolean;
@@ -57,6 +58,23 @@ export const startRun = async (
  resolveData: 'none',
  });
  run = runList.data[0];
+
+ // The analytics backend defaults its listing to a recent window
+ // (trailing 24h on the Vercel backend). When the name wasn't found
+ // there, retry across the plan's whole observability window using the
+ // window bounds from the response's page metadata.
+ if (!run && world.analytics) {
+ const windowStart = planWindowStartFromResponse(runList);
+ if (windowStart) {
+ const widened = await world.analytics.runs.list({
+ workflowName: workflowNameOrRunId,
+ startTime: windowStart,
+ endTime: new Date().toISOString(),
+ pagination: { sortOrder: 'desc', limit: 1 },
+ });
+ run = widened.data[0];
+ }
+ }
  }
 
  if (!run) {

packages/cli/src/lib/inspect/time-window.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ parseTimeInput,
+ planWindowStartFromResponse,
+ resolveTimeWindow,
+} from './time-window.js';
+
+const NOW = new Date('2026-07-07T12:00:00.000Z');
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('parseTimeInput', () => {
+ it('parses relative durations as that long ago', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(parseTimeInput('30m', 'since').toISOString()).toBe(
+ '2026-07-07T11:30:00.000Z'
+ );
+ expect(parseTimeInput('12h', 'since').toISOString()).toBe(
+ '2026-07-07T00:00:00.000Z'
+ );
+ expect(parseTimeInput('7d', 'since').toISOString()).toBe(
+ '2026-06-30T12:00:00.000Z'
+ );
+ expect(parseTimeInput('2w', 'since').toISOString()).toBe(
+ '2026-06-23T12:00:00.000Z'
+ );
+ });
+
+ it('parses absolute timestamps', () => {
+ expect(parseTimeInput('2026-07-01T00:00:00Z', 'since').toISOString()).toBe(
+ '2026-07-01T00:00:00.000Z'
+ );
+ });
+
+ it('rejects invalid values with the flag name in the error', () => {
+ expect(() => parseTimeInput('yesterday-ish', 'since')).toThrow('--since');
+ });
+});
+
+describe('resolveTimeWindow', () => {
+ it('returns undefined when neither flag is given', () => {
+ expect(resolveTimeWindow({})).toBeUndefined();
+ });
+
+ it('defaults the end to now when only --since is given', () => {
+ vi.spyOn(Date, 'now').mockReturnValue(NOW.getTime());
+ expect(resolveTimeWindow({ since: '24h' })).toEqual({
+ startTime: '2026-07-06T12:00:00.000Z',
+ endTime: '2026-07-07T12:00:00.000Z',
+ });
+ });
+
+ it('rejects --until without --since', () => {
+ expect(() => resolveTimeWindow({ until: '1h' })).toThrow(
+ '--until requires --since'
+ );
+ });
+
+ it('rejects inverted windows', () => {
+ expect(() => resolveTimeWindow({ since: '1h', until: '2h' })).toThrow(
+ '--since must be earlier than --until'
+ );
+ });
+});
+
+describe('planWindowStartFromResponse', () => {
+ it('extracts the plan window start from page metadata', () => {
+ expect(
+ planWindowStartFromResponse({
+ data: [],
+ pageInfo: {
+ currentLookbackDays: 30,
+ maxLookbackDays: 30,
+ currentWindowStart: '2026-06-07T12:00:00.000Z',
+ maxWindowStart: '2026-06-07T12:00:00.000Z',
+ upgradeAvailable: false,
+ },
+ })
+ ).toBe('2026-06-07T12:00:00.000Z');
+ });
+
+ it('returns undefined without page metadata', () => {
+ expect(planWindowStartFromResponse({ data: [] })).toBeUndefined();
+ expect(planWindowStartFromResponse(null)).toBeUndefined();
+ });
+});

packages/cli/src/lib/inspect/time-window.ts

@@ -0,0 +1,69 @@
+import type { AnalyticsPageInfo } from './pagination.js';
+
+const DURATION_UNIT_MS: Record<string, number> = {
+ m: 60_000,
+ h: 3_600_000,
+ d: 86_400_000,
+ w: 604_800_000,
+};
+
+/**
+ * Parse a `--since`/`--until` value: either a relative duration (`30m`,
+ * `12h`, `7d`, `2w`, interpreted as "that long ago") or an absolute
+ * timestamp accepted by `Date`.
+ */
+export function parseTimeInput(value: string, flagName: string): Date {
+ const duration = /^(\d+)(m|h|d|w)$/.exec(value.trim());
+ if (duration) {
+ const [, amount, unit] = duration;
+ return new Date(Date.now() - Number(amount) * DURATION_UNIT_MS[unit]);
+ }
+ const absolute = new Date(value);
+ if (!Number.isNaN(absolute.getTime())) {
+ return absolute;
+ }
+ throw new Error(
+ `Invalid --${flagName} value "${value}". Use a relative duration (30m, 12h, 7d, 2w) or a timestamp (2026-07-01T00:00:00Z).`
+ );
+}
+
+/**
+ * Resolve `--since`/`--until` flags into an explicit listing window for the
+ * analytics runs API, or undefined when neither flag was given (the backend
+ * then applies its default window). Windows older than the plan's
+ * observability lookback are rejected by the backend with
+ * `observability-upgrade-required`.
+ */
+export function resolveTimeWindow(opts: {
+ since?: string;
+ until?: string;
+}): { startTime: string; endTime: string } | undefined {
+ if (!opts.since && !opts.until) return undefined;
+ if (!opts.since) {
+ throw new Error('--until requires --since.');
+ }
+ const start = parseTimeInput(opts.since, 'since');
+ const end = opts.until
+ ? parseTimeInput(opts.until, 'until')
+ : new Date(Date.now());
+ if (start.getTime() >= end.getTime()) {
+ throw new Error('--since must be earlier than --until.');
+ }
+ return { startTime: start.toISOString(), endTime: end.toISOString() };
+}
+
+/**
+ * Extract the plan observability-window start from a paginated analytics
+ * response, for widening a defaulted (recent-window) listing to the whole
+ * window the plan allows. Returns undefined when the response carries no
+ * page metadata (e.g. non-Vercel backends).
+ */
+export function planWindowStartFromResponse(
+ result: unknown
+): string | undefined {
+ if (typeof result !== 'object' || result === null) return undefined;
+ const pageInfo = (result as { pageInfo?: AnalyticsPageInfo }).pageInfo;
+ if (!pageInfo?.currentWindowStart) return undefined;
+ const start = new Date(pageInfo.currentWindowStart);
+ return Number.isNaN(start.getTime()) ? undefined : start.toISOString();
+}