> 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/phases/phase_15/session_04_agent_aggregate_scheduler_job.md).

# Session 04: Agent Aggregate Scheduler Job

**Session ID**: `phase15-session04-agent-aggregate-scheduler-job` **Status**: Complete **Estimated Tasks**: \~14 **Estimated Duration**: 2-4 hours

***

## Objective

Add a scheduler job that refreshes local host/agent/dashboard data without running Trend Finder extension collectors.

This is the scheduler-wiring half of the original agent aggregate work. It uses the orchestration extracted in Session 03 and the merge writer from Session 02.

***

## Scope

### In Scope (MVP)

* Add `agent-aggregate` to the scheduler job registry
* Define reviewed cadence candidates and default cadence
* Add the scheduler handler for host/local aggregate refresh
* Add package scripts for agent scheduler run/status
* Update status copy, command hints, and docs
* Tests for registry order, handler wiring, status output, freshness, and collector isolation
* Compatibility decision for whether existing `scheduler:run` remains full aggregate or aliases to the scoped job

### Out of Scope

* Trend Finder scoped scheduler job
* Timer installation or systemd reconciliation
* Changing the full compatibility aggregate command

***

## Detailed Tasks

1. Add `agent-aggregate` to the scheduler job registry.
2. Give `agent-aggregate` the reviewed cadence candidates: hourly, every 2 hours, and every 4 hours.
3. Default `agent-aggregate` to `every-4-hours`.
4. Add an internal scheduler handler for `agent-aggregate`.
5. Use the host/local aggregate helper that skips extension collectors.
6. Preserve Dream projection loading in the host/local refresh path.
7. Preserve local agent, session, config, memory, and integration assembly.
8. Write only the host/local owned live-data branches through the shared merge writer.
9. Add package scripts for `scheduler:agents:run` and `scheduler:agents:status`.
10. Decide whether existing `scheduler:run` remains full aggregate or aliases to `agent-aggregate`; document the compatibility choice.
11. Update status copy and command hints.
12. Update tests for registry order, handler wiring, status output, and generated-data freshness.
13. Verify that `agent-aggregate` does not run Trend Finder collectors.
14. Verify the job uses scheduler run state, logs, timeout, and locks like existing scheduler jobs.
15. Run focused scheduler and aggregate tests.

***

## Prerequisites

* [ ] Session 03 complete.
* [ ] Host/local aggregate helper can skip extension collectors.

***

## Deliverables

1. `agent-aggregate` registry entry and handler.
2. Agent scheduler package scripts.
3. Tests proving host/local refresh preserves Trend Finder data.

***

## Handoff Gate

* [ ] Registry metadata, handler wiring, package scripts, status copy, run state, logs, timeout, and locks are complete.
* [ ] Tests prove the agent job refreshes host/local data without running Trend Finder.
* [ ] Status distinguishes registry enabled defaults, local timer intent, and actual latest run state.

***

## Success Criteria

* [ ] Agent scheduler run refreshes local host/agent data.
* [ ] Existing Trend Finder extension data is preserved.
* [ ] Status clearly separates registry defaults, local timer intent, and latest run state.
* [ ] `scheduler:agents:run` refreshes local host/agent data and preserves existing Trend Finder extension data.


---

# 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/phases/phase_15/session_04_agent_aggregate_scheduler_job.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.