> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase24-session05-scheduler-first-run-live-progress-controls/spec.md).

# Session Specification

**Session ID**: `phase24-session05-scheduler-first-run-live-progress-controls` **Phase**: 24 - Trend Finder Outlier Signal Upgrade **Status**: Complete **Created**: 2026-06-08 **Completed**: 2026-06-08

***

## 1. Session Overview

This session turns Trend Finder refreshes from a command-first workflow into an observable local operation. The scoped scheduler job, command aliases, private run state, and local run button already exist, but the browser currently shows only coarse run phases while cadence, latest scheduler state, first-run readiness, skipped states, and recurring spend projection remain split across CLI output and documentation.

The work builds on Phase 24 Sessions 01 through 04. Source-local signals, delta-aware enrichment and spend summaries, browser-safe evidence asset boundaries, and reviewed source setup are now in place. Session 05 uses those foundations to show scheduler cadence/status, source setup readiness, runtime readiness, run-now state, and sanitized live stage progress in the Trend Finder surfaces that operators already use.

The implementation must preserve the existing command-line scheduler paths and private state boundaries. Browser-visible scheduler and progress data may show safe labels, cadence choices, timer intent, latest-run status, warning counts, generated-data freshness, stage IDs, stage labels, elapsed time, and bounded per-source counts. It must not expose raw logs, prompts, provider responses, Actor inputs, Dataset rows, account auth, credential values, raw stdout/stderr, private file paths, or scheduler internals.

***

## 2. Objectives

1. Add a browser-safe Trend Finder scheduler status contract for cadence, timer intent, latest scoped run, skipped/failed states, first-run state, and recurring spend projection.
2. Add token-gated local scheduler status/cadence bridge behavior that reads and writes only reviewed scheduler config fields for the Trend Finder job.
3. Add a first-run checklist that combines extension enablement, credential readiness, reviewed source setup, runtime readiness, generated data, run-now action, and Engine Replay review.
4. Add sanitized live stage progress during active Trend Finder runs by reusing the Engine Replay stage taxonomy and bounded per-source counters.
5. Update Trend Finder pipeline, UI, and runtime/provenance docs to describe implemented scheduler status, cadence controls, live progress, and privacy boundaries.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase24-session01-source-local-scoring-signals` - Provides source-local signal and Engine Replay summary patterns used in setup/progress readiness.
* [x] `phase24-session02-delta-aware-enrichment-spend-accounting` - Provides spend summaries that scheduler cadence must project.
* [x] `phase24-session03-browser-safe-evidence-assets-file-hardening` - Provides hardened loopback bridge and browser-safe asset boundary precedents.
* [x] `phase24-session04-source-setup-target-configuration` - Provides reviewed source setup state and target readiness needed by the first-run checklist.

### Required Tools/Knowledge

* Existing scheduler registry, operator status projection, local config parser, run-state writer, and command aliases.
* Current `/__run_trend_finder` Vite middleware and `src/lib/async-trend-finder-run.ts` status model.
* Current Trend Finder run hook, run-control presentation model, Sources view, Engine Replay view, runtime readiness panel, source setup panel, and spend projection schema.
* Engine Replay decision stage taxonomy and sanitized trace labels.

### Environment Requirements

* Bun 1.3.14 project toolchain from `.bun-version`.
* Dev bridge behavior runs on loopback Vite middleware only.
* Private scheduler config remains gitignored at `data/ai-os.scheduler.json`.
* Existing scheduler commands remain supported: `bun run scheduler:trend-finder:run` and `bun run scheduler:trend-finder:status`.
* Browser payloads and bridge responses must not expose raw logs, prompts, provider responses, Actor inputs, Dataset rows, account auth, credential values, raw stdout/stderr, token-shaped strings, or private paths.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder can read browser-safe scheduler status for the scoped `trend-finder` job, including cadence label/detail, cadence source, timer intent, local config warnings, command hints, latest run status, warning count, generated-data freshness, and first-run/unreadable states.
* Trend Finder can update local cadence/timer intent for only reviewed `trend-finder` scheduler candidates through a loopback-only, token-gated bridge with schema-validated input, duplicate-trigger prevention, atomic writes, no-store responses, and redacted diagnostics.
* Trend Finder can project recurring spend from Session 02 spend summaries using the selected scheduler cadence, while showing explicit cadence-unavailable, projected, exact, estimated, mixed, unavailable, and not-applicable states.
* Trend Finder can render a first-run checklist covering extension enablement, credential presence, reviewed source setup, runtime readiness, source config, generated data, run-now action, latest scheduler status, and Engine Replay review.
* Trend Finder can surface live run progress during `running` with current stage, completed stages, elapsed time, cancellation/overlap states, and bounded per-source counts when available.
* Trend Finder docs can describe scheduler status/cadence UI, first-run checklist behavior, live stage progress, recurring spend projection, and browser-safety boundaries.

### Out of Scope (Deferred)

* Installing or managing systemd/cron timers from the browser - *Reason: operator timer installation remains explicit and command/documentation driven.*
* Removing or bypassing command-line scheduler workflows - *Reason: existing scheduler commands remain the authoritative local operation path.*
* Exposing raw scheduler logs, process stdout/stderr, prompts, provider responses, Actor/Dataset internals, account auth, or private run-state files to the browser - *Reason: browser output stays sanitized.*
* Adding arbitrary scheduler jobs or unreviewed cadence expressions - *Reason: this session only covers the reviewed Trend Finder scheduler job.*
* Adding Signal Workbench triage or static Brief export behavior - *Reason: Sessions 06 and 07 own those surfaces.*

***

## 5. Technical Approach

### Architecture

Add a focused script-side Trend Finder scheduler status helper around `buildTrendFinderSchedulerStatus`. It should convert existing operator status into a browser-safe scheduler setup state, merge cadence with spend projection inputs, and validate local config mutation requests for the reviewed `trend-finder` job only. The helper should preserve existing config parser compatibility and reject unknown jobs, unsupported fields, raw calendar expressions, unsafe values, invalid cadence IDs, malformed JSON, and oversized requests.

Add a token-gated Vite bridge for scheduler status and cadence updates. The bridge should use the same loopback/token/no-store posture as the existing Trend Finder source setup and asset bridges. Responses should contain safe status labels, warning counts, command hints, latest-run summaries, cadence candidates, timer intent, and diagnostics only. Mutations should be atomic and idempotent, and the UI should revalidate after success or failure.

On the browser side, add additive scheduler/progress schemas, a scheduler status client/hook, scheduler view models, first-run checklist components, and live progress rendering inside the existing Trend Finder run control and Sources/Engine Replay surfaces. Live progress should reuse Engine Replay decision stage IDs and labels. If stage streaming is unavailable, the UI must fall back to the current coarse lifecycle and latest safe scheduler status.

### Design Patterns

* Existing parser compatibility: local scheduler config writes must remain accepted by `readSchedulerLocalConfig`.
* Static reviewed scheduler candidates: UI can choose only registry-provided cadence IDs for `trend-finder`.
* Fail-closed local bridge: require loopback, token validation, bounded bodies, schema validation, atomic writes, and safe error mapping.
* Typed degradation over throws: represent missing config, invalid config, first-run, skipped, blocked, failed, timeout, and unavailable progress states explicitly.
* Engine Replay taxonomy reuse: use existing decision stage IDs and labels for live progress instead of inventing a separate pipeline model.
* Script-only runtime boundary: keep logs, process output, scheduler files, credentials, prompts, source internals, and provider responses out of browser code.

### Technology Stack

* TypeScript with Bun script runtime.
* Vitest for script helper, bridge, schema, hook/view-model, and UI tests.
* Zod for browser-safe scheduler status/progress parsing and mutation validation.
* React 19 with existing Tailwind/Radix conventions for dense operational UI.
* Vite local middleware for dev-only loopback bridge registration.

***

## 6. Deliverables

### Files to Create

| File                                                                         | Purpose                                                                                                       | Est. Lines |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/trend-finder-scheduler-status.ts`                               | Browser-safe scheduler status, cadence mutation validation, atomic local config writes, and spend projection. | \~340      |
| `scripts/lib/trend-finder-scheduler-status-bridge.ts`                        | Loopback/token-gated bridge for scheduler status GET and cadence/timer mutations.                             | \~260      |
| `scripts/lib/__tests__/trend-finder-scheduler-status.test.ts`                | Helper tests for status projection, cadence validation, spend projection, redaction, and config writes.       | \~280      |
| `scripts/lib/__tests__/trend-finder-scheduler-status-bridge.test.ts`         | Bridge tests for auth, methods, malformed input, validation, write failures, headers, and redaction.          | \~240      |
| `src/extensions/trend-finder/scheduler-status.ts`                            | Browser-safe scheduler status/progress schemas, endpoint constants, and request helpers.                      | \~260      |
| `src/extensions/trend-finder/use-scheduler-status.ts`                        | Hook for loading, mutating, polling, and revalidating scheduler status.                                       | \~200      |
| `src/extensions/trend-finder/components/scheduler-first-run-panel.tsx`       | First-run checklist and scheduler cadence/status controls for Trend Finder surfaces.                          | \~300      |
| `src/extensions/trend-finder/components/live-run-progress.tsx`               | Live stage progress rendering using Engine Replay stage IDs and bounded counts.                               | \~240      |
| `src/extensions/trend-finder/components/__tests__/scheduler-status.test.tsx` | Schema, hook, first-run panel, cadence, and progress UI tests.                                                | \~280      |

### Files to Modify

| File                                                           | Changes                                                                                              | Est. Lines |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `src/lib/async-trend-finder-run.ts`                            | Expose bounded safe status/progress snapshots without raw stdout/stderr.                             | \~90       |
| `vite.config.ts`                                               | Register scheduler status bridge and add safe progress/status response handling around run endpoint. | \~120      |
| `src/extensions/trend-finder/run-control.ts`                   | Add live stage progress, scheduler status labels, skipped/completed message handling, and fallbacks. | \~160      |
| `src/extensions/trend-finder/hooks/use-trend-finder-run.ts`    | Poll safe progress/status during active runs with cleanup on scope exit for all acquired resources.  | \~170      |
| `src/extensions/trend-finder/components/trend-run-control.tsx` | Render live progress, latest scheduler status, and cancellation/overlap states accessibly.           | \~140      |
| `src/extensions/trend-finder/views/sources-view.tsx`           | Render first-run checklist near Source Setup and source health controls.                             | \~90       |
| `src/extensions/trend-finder/views/engine-replay-view.tsx`     | Show latest scheduler status/progress context without reading private logs.                          | \~80       |
| `src/extensions/trend-finder/schema.ts`                        | Add additive scheduler status and recurring spend projection defaults.                               | \~140      |
| `src/extensions/trend-finder/view-model.ts`                    | Project scheduler checklist, cadence labels, live progress, and recurring spend labels.              | \~160      |
| `src/extensions/trend-finder/fixtures.ts`                      | Add first-run, skipped, failed, configured, projected-spend, and active-progress fixture states.     | \~120      |
| `src/data/live-data.example.json`                              | Add additive fallback scheduler/progress/spend projection shape.                                     | \~70       |
| `docs/extensions/trend-finder-pipeline.md`                     | Document scheduler status/cadence UI, first-run checklist, live progress, and command boundaries.    | \~130      |
| `docs/extensions/trend-finder-ui-surfaces.md`                  | Document first-run checklist, run progress UI, and setup ergonomics.                                 | \~120      |
| `docs/extensions/trend-finder-runtime-and-provenance.md`       | Document sanitized live progress, scheduler status labels, spend projection, and privacy boundary.   | \~120      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Scheduler status UI shows Trend Finder cadence, cadence source, timer intent, local config warnings, latest scoped run, skipped/failed/blocked states, generated-data freshness, and first-run state.
* [ ] Cadence/timer mutations can update only reviewed `trend-finder` scheduler fields and preserve unrelated local scheduler config entries.
* [ ] First-run checklist clearly guides a fresh local clone from disabled or unconfigured state to first successful scoped run and Engine Replay review.
* [ ] Run control shows live current stage, completed stages, elapsed time, overlap/cancel states, and bounded per-source counts when available.
* [ ] Run control falls back cleanly to coarse lifecycle and latest scheduler status when live progress streaming is unavailable.
* [ ] Recurring spend projection uses selected scheduler cadence and marks unavailable or estimated values explicitly.
* [ ] Browser-visible state never exposes raw logs, prompts, provider responses, Actor inputs, Dataset rows, account auth, credential values, raw stdout/stderr, token-shaped strings, or private paths.

### Testing Requirements

* [ ] Unit tests cover scheduler status projection, cadence validation, timer intent, first-run/unreadable/skipped/failed states, spend projection, redaction, and atomic config writes.
* [ ] Bridge tests cover method rejection, loopback enforcement, token checks, oversized bodies, malformed JSON, invalid cadence payloads, write failures, safe headers, duplicate-trigger prevention, and redacted diagnostics.
* [ ] Schema/view-model/hook/UI tests cover scheduler defaults, loading, empty, error, offline, first-run, configured, skipped, live-progress, cancel, overlap, and fallback states.
* [ ] Focused Trend Finder tests, scheduler tests, app typecheck, script typecheck, docs formatting, ASCII validation, and git diff check pass.

### Non-Functional Requirements

* [ ] Scheduler status bridge responses stay `no-store`, same-origin, and loopback/token gated.
* [ ] Live progress polling cleans up timers, abort controllers, and pending requests on scope exit.
* [ ] Scheduler/progress payloads remain bounded and additive inside the shared extension payload budget.
* [ ] UI controls are accessible, keyboard usable, and stable across mobile and desktop layouts.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.

***

## 8. Implementation Notes

### Key Considerations

* Keep `bun run scheduler:trend-finder:run` and `bun run scheduler:trend-finder:status` as the canonical local scheduler commands.
* Use `buildTrendFinderSchedulerStatus` as the safe starting point for browser status projection, then deliberately reduce fields before sending them to the UI.
* Reuse the existing `data/ai-os.scheduler.json` shape and preserve other job entries when writing Trend Finder cadence/timer settings.
* Reuse Engine Replay decision stage IDs for live progress so the long `running` phase and post-run replay tell the same story.
* Treat live progress as best-effort. Missing progress should not block a run or imply a failure when the scheduler job is still active.

### Potential Challenges

* Stage markers are not currently emitted as a browser-safe stream: implement bounded snapshots and fallback behavior before exposing UI controls.
* Scheduler local config is shared across jobs: write atomically and preserve unrelated job entries to avoid clobbering agent aggregate or Dream settings.
* Existing async process status captures stdout/stderr: never pass raw lines to the browser; derive allowed stage/counter labels only.
* Cadence projection can imply exact billing when it is only estimated: preserve exact/estimated/mixed/unavailable labels from spend summaries.

### Relevant Considerations

* \[P02] **Extension payloads and demo labels stay bounded**: Scheduler and progress additions must stay capped, additive, and explicit.
* \[P11] **Scheduler state/log privacy boundary**: Status surfaces may expose only safe labels, statuses, durations, exit codes, warning counts, lock outcomes, and freshness metadata.
* \[P15] **Aggregate collection must stay budgeted**: Scheduler cadence and recurring spend projection must keep source/runtime cost consequences visible.
* \[P05] **Script-only runtime boundary**: Auth, transport, analyst, scoring, snapshot, enrichment, cache, and source helpers stay out of browser code.
* \[P00] **Do not document planned features as implemented**: Docs must describe only the scheduler/progress behavior that lands in this session.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* In-flight run or cadence controls can double-submit and race local config writes if pending states are not enforced.
* Polling or progress streams can leak resources after navigation unless timers, abort controllers, and subscriptions are cleaned up.
* Error, skipped, blocked, offline, and unavailable-progress states can be mistaken for successful generation unless labels and recovery hints are explicit.

***

## 9. Testing Strategy

### Unit Tests

* Scheduler status projection from success, warning-only, degraded, failed, timeout, blocked, skipped, first-run, and unreadable private run states.
* Cadence/timer mutation validation and atomic local scheduler config writes.
* Recurring spend projection from exact, estimated, mixed, unavailable, and not-applicable spend summaries.
* Redaction checks for raw logs, paths, credentials, prompts, Actor/Dataset labels, stdout/stderr, and token-shaped strings.

### Integration Tests

* Bridge GET and mutation requests with loopback/token checks, headers, malformed JSON, invalid cadence IDs, write failure, and duplicate-trigger prevention.
* Run hook polling cleanup, active progress updates, cancellation, overlap, offline, and fallback behavior.
* UI wiring in Sources, Run Control, and Engine Replay with fixture-backed scheduler/progress states.

### Manual Testing

* Start the dev server, open Trend Finder Sources and Trends, inspect the first-run checklist, change cadence/timer intent locally, run Trend Finder, watch progress update, cancel/retry once, and verify Engine Replay shows the latest safe status after completion.

### Edge Cases

* Missing `data/ai-os.scheduler.json`.
* Invalid scheduler config JSON.
* Unknown scheduler job entries mixed with valid Trend Finder config.
* Extension disabled causing skipped latest run.
* Active aggregate or Dream run causing overlap block.
* Browser offline during status load or active run.
* Progress unavailable while scheduler job still completes.
* Spend exactness mixed across sources at a projected cadence.

***

## 10. Dependencies

### External Libraries

* Zod: existing schema validation dependency.
* React Query/live-data hooks: existing runtime data refresh pattern.
* Vitest and happy-dom: existing test stack.

### Other Sessions

* **Depends on**: `phase24-session01-source-local-scoring-signals`, `phase24-session02-delta-aware-enrichment-spend-accounting`, `phase24-session03-browser-safe-evidence-assets-file-hardening`, `phase24-session04-source-setup-target-configuration`
* **Depended by**: `phase24-session06-signal-workbench-and-local-triage`, `phase24-session07-static-brief-export`, `phase24-session08-cross-surface-documentation-and-reference-mode`, `phase24-session09-end-to-end-validation-and-release-hardening`

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase24-session05-scheduler-first-run-live-progress-controls/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.