fix(timeline): nominate an episode image whenever cited evidence has one

The Rematch gaming session came back with no picture even though it cited an
observation carrying a frame: `representative_evidence_id` was described as
"optional", to be left null "when no suitable image is available", and the agent
read a gaming session as not needing one. Four of thirteen episodes got an image
on a day where ninety-one evidence items advertised one.

It is now stated as what it is — how an episode gets its picture on the timeline
— with null reserved for an episode citing no image-bearing evidence at all.
PROMPT_VERSION and the shipped pin move to v10 so existing days re-run.

Author: AnkushMalaker

backends/advanced/src/advanced_omi_backend/services/timeline/prompt.py

@@ -2,7 +2,7 @@
 
 import json
 
-PROMPT_VERSION = "timeline-episodes-v6"
+PROMPT_VERSION = "timeline-episodes-v10"
 
 
 OUTPUT_SCHEMA = {
@@ -143,6 +143,22 @@ def build_prompt(output_path: str) -> str:
   because they are adjacent. Use separate episodes, or a parent session with supported
   child events, when the evidence distinguishes them.
 - Episodes may overlap; long passive media and simultaneous foreground work can coexist.
+- One activity spans every modality that evidences it. When screen and audio evidence
+  cover the same stretch of the same activity, cite both from one episode. Do not emit an
+  audio episode running alongside a screen episode for the same minutes — that is a
+  modality split, not two events.
+- Only create a standalone audio episode when no concurrent foreground activity explains
+  the sound. "Background audio continued" beside a game, call, or meeting episode covering
+  those same minutes is the split this rule forbids.
+- Role is a property of each evidence item, not of the episode. One episode may cite
+  `media_content` output audio, `uncertain` microphone input, and `application_state`
+  screen evidence together; the people and application named by any of them belong in
+  that episode's entities.
+- When cited evidence names a person, use that name in the title, summary, and entities.
+  Never replace a name that appears in the evidence with a placeholder such as "a
+  friend", "someone", or "another person". Use a generic term only when no name was
+  captured. Uncertainty about a claim belongs in `confidence` and the assertion's role,
+  not in blurring who was there.
 - Use quiet, idle, ambient, or unknown episodes when evidence genuinely supports them.
 - `output` audio/transcripts are media or system content, never the user's statements.
 - `input` audio is uncertain unless speaker evidence supports user attribution.
@@ -158,11 +174,17 @@ def build_prompt(output_path: str) -> str:
 - Account for every evidence-bearing interval with one or more episodes or an explicit
   `unassigned_interval`. Unassigned intervals must be positive and inside this day.
 - Never return both `episodes` and `unassigned_intervals` empty when evidence exists.
-- `representative_evidence_id` is optional and, when set, must name image evidence
-  already cited by that episode. Use null when no suitable image is available.
+- `representative_evidence_id` is how an episode gets its picture on the timeline. Set
+  it whenever the episode cites any evidence carrying an `image_filename`, choosing the
+  frame that best depicts what the episode was; only use null when none of the evidence
+  it cites has one. It must name evidence that episode already cites.
 - Never invent an evidence ID. Chronicle tracks authoritative window coverage itself;
   do not echo window IDs into the result.
 - Salience is display value, not confidence.
 - Express optional episode metadata as short string key/value entries in `attributes`.
 - Prefer a few coherent episodes over arbitrary periodic fragments.
+- Confirmed episodes, when supplied, are settled by the person whose day this is. Treat
+  their intervals as already accounted for: do not re-segment them, do not emit an
+  episode overlapping them, and do not list their time as unassigned. You may still cite
+  evidence inside a confirmed interval from an episode that mostly lies outside it.
 """

backends/advanced/tests/test_timeline_prompt.py

@@ -1,3 +1,7 @@
+from pathlib import Path
+
+import yaml
+
 from advanced_omi_backend.services.timeline.prompt import (
     OUTPUT_SCHEMA,
     PROMPT_VERSION,
@@ -27,10 +31,53 @@ def test_timeline_output_schema_requires_grounded_episodes_and_assertions():
     assert assertion["properties"]["evidence_ids"]["minItems"] == 1
 
 
+def test_prompt_version_is_pinned():
+    """Changing the prompt text without bumping this leaves cached runs on the old rules.
+
+    Asserted once, here — not inside each content test, where two of them disagreeing is
+    the only thing a second copy can achieve.
+    """
+
+    assert PROMPT_VERSION == "timeline-episodes-v10"
+
+
 def test_prompt_treats_observations_as_coarse_sessions_without_cross_app_merging():
     prompt = build_prompt("result.json")
 
-    assert PROMPT_VERSION == "timeline-episodes-v6"
     assert "coarse application session" in prompt
     assert "Do not merge distinct foreground applications" in prompt
     assert "manufacture periodic sub-events" in prompt
+
+
+def test_prompt_tells_the_agent_to_leave_confirmed_intervals_alone():
+    prompt = build_prompt("result.json")
+
+    assert "Confirmed episodes" in prompt
+    assert "do not re-segment them" in prompt
+
+
+def test_prompt_keeps_one_activity_in_one_episode_across_modalities():
+    """A game with a friend must not split into a screen episode and an audio episode."""
+
+    prompt = build_prompt("result.json")
+
+    assert "One activity spans every modality that evidences it" in prompt
+    assert "modality split, not two events" in prompt
+    assert (
+        "Only create a standalone audio episode when no concurrent foreground" in prompt
+    )
+
+
+def test_shipped_config_pins_the_same_prompt_version():
+    """Run identity comes from config, not this constant — they must not drift.
+
+    `request_timeline_analysis` keys a run on `timeline.prompt_version` from
+    `config/defaults.yml`. A prompt edit that bumps only the constant changes nothing:
+    completed days stay cached on the old rules and no reanalysis is triggered.
+    """
+
+    defaults = yaml.safe_load(
+        (Path(__file__).resolve().parents[3] / "config" / "defaults.yml").read_text()
+    )
+
+    assert defaults["timeline"]["prompt_version"] == PROMPT_VERSION

config/defaults.yml

@@ -926,7 +926,10 @@ cron_jobs:
   timeline_analysis:
     description: "Reconcile changed current-day capture evidence into semantic episodes"
     enabled: true
-    schedule: "*/30 * * * *"
+    # Every run regenerates the whole day from scratch — there is no incremental merge —
+    # so a tight cadence re-does the same work and reshuffles episode ids each time.
+    # Analysis is also available on demand from the Timeline page.
+    schedule: "0 */4 * * *"
 
 observation_curation:
   codex:
@@ -935,15 +938,26 @@ observation_curation:
     timeout_seconds: 600
 
 timeline:
-  window_minutes: 20
+  # Window size is a capacity knob, not a semantic one — the prompt treats windows as
+  # coverage units that must never become episode boundaries. It sets how many files
+  # one agent pass must read: 20min/3overlap put a full day at 85 windows, which never
+  # once produced episodes, while days under ~18 windows nearly always succeeded.
+  # 60min puts a full day at 26. The per-window text cap is raised to match so fewer,
+  # larger windows do not truncate more evidence than the old layout carried.
+  window_minutes: 60
   overlap_minutes: 3
-  max_text_chars_per_window: 30000
+  max_text_chars_per_window: 60000
   max_anchor_images_per_window: 4
   executor: codex
-  prompt_version: timeline-episodes-v6
+  # Run identity. Must match services/timeline/prompt.py's PROMPT_VERSION; changing the
+  # prompt text without bumping both leaves completed days cached on the old rules.
+  prompt_version: timeline-episodes-v10
   codex:
     model: gpt-5.6-luna
-    reasoning_effort: low
+    # `low` was chosen for cost, but a pass that returns no episodes costs a full run
+    # (~600k input tokens) and delivers nothing — the cheap setting was the expensive
+    # one. An empty result now escalates one step and retries.
+    reasoning_effort: medium
     # Reuse the memory agent's container-aware sandbox choice. Rootless Podman
     # deployments set that to danger-full-access because the container itself is
     # the isolation boundary and nested bubblewrap cannot start there.