timer_native_controls_test.dart checks state-dependent
shell registrations, disabled in-flight controls, route disposal, a long-running
clock under enlarged text, and Vietnamese Pomodoro labels. Actual native
session timing and dock transition smoothness require device verification;
widget tests do not establish either.
Focus Time and Pomodoro (planned)
Focus Time is part of time tracking; there is no separate focus store. A Pomodoro focus interval is an ordinary tracking session, linked to a task when started from one, and taggedpomodoro. Focus Time totals (today, last
week, the month and a seven-day chart) are tracker statistics filtered to
those sessions.
Breaks between intervals are control phases, not tracked work, so billing and
productivity totals do not change.
Pomodoro becomes a first-class timer on mobile and web with:
- configurable focus, short-break and long-break lengths;
- a long break after a configurable number of intervals;
- auto-start for breaks and for focus;
- phase-end notifications;
- task linking.
Shared Pomodoro preparation is inactive
The private time-tracker control foundation prepares actor/workspace-scoped configuration only. Its schema requiresmode=off, phase=idle, and no deadline;
its service-only RPCs initialize, read, and update configuration with revision
checks. Browser roles cannot read, write, or execute those RPCs. Configuration
contains positive integer minute durations up to 180 and a cycle length up to
24, with explicit boolean automation choices. These are foundation storage
bounds, not a change to the current mobile or web controls.
A repeated latest command with identical input returns its existing revision;
a stale revision or reused command with different input fails. An optional
prepared-session reference must belong to the same actor and workspace. It is
an inert reference, not a live session binding: existing session deletion stays
possible. The foundation changes no tracked work, breaks, approval policy,
client timer, settings preference, notification delivery, or scheduler.
Activation requires a later reviewed contract that normalizes Web, Track,
quick-start, AI, direct-write and approval lifecycle paths under the same lock
order and atomically updates phase and existing tracker accounting. This
foundation is a prerequisite and does not deliver cross-platform Pomodoro or
completion while every client is closed.
The time-tracker-control-contract.yaml workflow checks out the exact source,
replays the complete schema in the repository-owned isolated lifecycle, runs
time-tracker-control.sql with strict TAP validation, and runs actual concurrent
configuration-CAS and command-replay races. It then generates actual public
schema types as an exact-SHA artifact and requires owned lifecycle cleanup.
No generated type file is hand-edited. The new private preparation objects do
not imply new public API types.
Focused runner tests can run through ttr resources run -- node --test apps/database/scripts/time-tracker-control-contract.test.mjs apps/database/scripts/programming-database-tap.test.mjs. The full SQL verifier
starts a disposable database and belongs in exact-head CI or an explicitly
admitted host; it must not be run under a no-local-setup restriction. Local
script tests alone are not schema, SQL concurrency, device, or production proof.
Unwired OFF-only replacement boundary
A private service-only operation can atomically close the expected running session and start its replacement while the existing control is OFF and idle. No mobile, web, quick-start or AI caller uses it. It carries a separate operation revision and retained input-bound command receipt; configuration revision is unchanged. A receipt reports its applied result, including an older replay, and does not claim to describe the latest session. The operation acquires the existing actor/workspace advisory key before control, linked requests, session and break rows. One database timestamp captured after contention closes and starts work. Existing accounting and policy triggers remain in force; closing work supplies canonical integer elapsed seconds from that same clock before the existing productivity trigger executes. To close already-running work older than a positive edit threshold, only that canonical close update uses a transaction-local update-limit bypass; the prior value is restored before the new insert and on close failure. Other policy guards and legacy triggers remain unchanged. A future-starting running row or any open break for that actor/workspace, including a paused session’s break, is rejected without mutation or work credit. Historical breaks must already be completed; this operation never closes them automatically. Any failure rolls back session writes, operation revision and receipt. Browser roles cannot call the operation, and even the service role cannot directly mutate its private bookkeeping tables. Full-schema catalog assertions retain an explicit baseline of legacy writers, RLS policies, triggers and FK actions, including the task-workspace guard and approval activity/notification effects. Unexpected drift fails validation. This baseline intentionally leaves writer closure open: the new operation cannot become authoritative until legacy direct writes, bypass RPCs and every lifecycle caller use a consistent boundary. CI executes real pgTAP and two-connection CAS, replay and shared-scope contention tests with actual type generation and cleanup. The replacement pgTAP fixture reuses the workspace creator membership inserted byadd_ws_creator, and checks it again before the edit-threshold scenario.
It must not insert that same membership a second time.
Shared phase/settings, pause/resume/skip, deadline reconciliation, cross-client
realtime and background notification behavior remain separate prerequisites.
This unwired boundary provides no all-clients-closed completion or device proof.
Device Pomodoro
The Timer tab has a Pomodoro panel. Start focus begins a focus phase for the timer’s current title and linked task. Start focus on a board task row does the same for that task.- Sessions. A focus phase is an ordinary time-tracking session started, paused, resumed and stopped through the existing tracker API. Breaks are not tracked work.
- Lengths. Phase lengths, the long-break cycle and the auto-start choices come from the existing Pomodoro settings in Settings > Apps > Timer.
- Waiting phases. A phase that does not auto-start waits, and Start focus or Resume begins it. A waiting focus phase starts its session only then.
- Controls. Pause, Resume, Skip and Stop act on the current phase. Stop closes a focus phase’s session.
- Phase-end notification. The end of a running phase schedules one local notification, which opens the Timer. A newer phase replaces it, and pausing or stopping cancels it. If notifications are turned off, the in-app countdown still ends the phase.
- Single device. The countdown, deadline and cycle position are stored on this device for the signed-in account. Another account’s stored Pomodoro is discarded at sign-in, and other devices and the web do not see the phase. No migration is involved.
- Missed phase ends. A phase that ended more than a minute ago (the app was asleep or closed, or a timer fired late) ended unattended. Unattended phases end when the app opens or resumes; the phase timer, restore and resume all go through one serialized reconcile. Focus never auto-starts after an unattended end, so no session is created for time nobody was there for. A focus session that does start counts its deadline from its real start. A late-stopped session is trimmed back to the phase deadline only when that deadline is after the session’s start, and only when the workspace’s edit rules allow it.
- The real session. Before ending, pausing, resuming or stopping a focus phase, the app re-reads the tracker. Pausing and resuming on the main Timer issues a new session id that the server links only to the session right before it, so the app stores each new id it finds and follows that chain (it also does so on every reconcile).
- Which session belongs to the phase. A session is the phase’s when it has the stored id or was resumed from it. A session for the phase’s task also counts, but only if it started while the phase was running. The phase records each run, from each start or resume to the next pause, so a session started during a pause is never claimed. A session the user starts by hand after the phase ended or paused is never stopped, trimmed or adopted. The app never stops a stale id or an unrelated session.
- Resuming with another timer running. Resume will not start a session while an unrelated one runs, because the server would close the user’s timer. It explains instead.
- Stop. Stop clears the device Pomodoro first, then stops the phase’s session. A session already stopped elsewhere counts as stopped, so the Pomodoro can never get stuck.
- Replacing a session. Pomodoro Start focus asks before replacing a running or paused session, as Start focus on a task row does. A paused one is stopped first (closing its break) and put back if the start fails.
- Starting a phase. The whole start runs under the Pomodoro’s lock, so a phase end cannot interleave. Settings load before any session changes, and a failure afterwards ends the new session and puts the replaced one back, so no orphan session is left. If the new session cannot be stopped again, the start reports that it may still be running instead of failing quietly; a failed restore keeps the original error.
pomodoro tag. This
includes Start focus on a task row. The session API accepts tags: lowercase
slugs, at most 10, stored in the existing tags column.
Focus Time on the You tab is all tracked time linked to a task
(task_id set), Pomodoro or not (decided 2026-10-26). The stats endpoint takes two optional
filters: taskLinked=true (Focus Time) and tag (for example pomodoro,
kept as a capability). With either, it computes today, the week from Monday,
the month, daily activity and the streak from the matching sessions, in the
user’s timezone. This is done in TypeScript, so the stats database function
is unchanged and there is no migration. One difference from the unfiltered
stats: a session counts on the local day it started. The Timer’s own
statistics still count all tracked time.
Shared, cross-device phases need the database contract flagged in the native
pass plan (phase 7, a draft PR).
Regression coverage: pomodoro_controller_test.dart runs against a fake
tracker that behaves like the server. It covers:
- a sleep across many cycles with both auto-starts on, and late timers;
- focus deadlines counted from the real start;
- no trimming before a session’s start;
- stale and unrelated sessions, resume chains of several cycles, and manual sessions after a phase ends or pauses;
startFocusconcurrent with a phase end, and settings that fail to load;- stop when the session ended elsewhere;
- paused replacement;
- concurrent restores and account isolation;
- the on-time natural end.
pomodoro_panel_test.dartcovers the panel flow and 320dp at 2x text.task_board_row_actions_flows_test.dartcovers Start focus. Widget tests do not establish notification delivery or timing on devices.
pomodoro_waiting_focus_test.dart verifies that a waiting or automatic focus phase
leaves an unrelated running timer intact.
Offline preparation
Withmobile_offline and offline_read_time_tracker enabled (default off),
mobile prepares categories, running/paused session state, active break, the five
most recent sessions, stats, the first ten history sessions for the current week,
period stats and workspace settings. History retains the API cursor and has-more
metadata. Lists are capped at 200 items, with stricter session page limits;
the complete download is capped at 1 MiB. Responses are validated together before
cache publication. Exceeding a cap shows “Not available offline”.
Offline settings records the last successful synchronization time.
Other periods and pages require a previous cached read or connectivity.
Regression coverage: time_tracker_offline_preparation_test.dart.
Preparation and screen reads share the inclusive history-period builder and the
Calendar first-day preference/locale resolver. Default opening prepares the current
week; explicit route history contexts use their own previously cached responses.
Preparing the current first page preserves other periods, cursors, and unrelated
time_tracker.data keys. Cold-cubit and retained-cursor regressions live in
time_tracker_offline_preparation_test.dart.