From 036b00022e83f1c9ed667e50b8af6fa03c897c26 Mon Sep 17 00:00:00 2001
From: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 14 Nov 2026 00:42:42 +0400
Subject: [PATCH 1/5] feat: link the focus timer to screen time sessions

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 apps/web/src/components/learning/Pomodoro.tsx | 134 ++++++-
 .../learning/ScreenTimeSettings.tsx           |  58 +++
 .../lib/__tests__/screen-time-adapter.test.ts | 346 ++++++++++++++++++
 .../lib/__tests__/screen-time-link.test.ts    | 202 ++++++++++
 .../__tests__/screen-time-pomodoro.test.tsx   | 144 ++++++++
 apps/web/src/lib/screen-time/client.ts        | 200 ++++++++++
 apps/web/src/lib/screen-time/contract.ts      |  83 +++++
 apps/web/src/lib/server/screen-time.ts        | 289 +++++++++++++++
 apps/web/src/routeTree.gen.ts                 |  21 ++
 .../web/src/routes/api/screen-time/session.ts |  54 +++
 apps/web/src/views/studio/learn.tsx           |  20 +-
 .../src/views/studio/personal-settings.tsx    |   2 +
 docs/syllo-setup.md                           |   9 +
 13 files changed, 1554 insertions(+), 8 deletions(-)
 create mode 100644 apps/web/src/components/learning/ScreenTimeSettings.tsx
 create mode 100644 apps/web/src/lib/__tests__/screen-time-adapter.test.ts
 create mode 100644 apps/web/src/lib/__tests__/screen-time-link.test.ts
 create mode 100644 apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
 create mode 100644 apps/web/src/lib/screen-time/client.ts
 create mode 100644 apps/web/src/lib/screen-time/contract.ts
 create mode 100644 apps/web/src/lib/server/screen-time.ts
 create mode 100644 apps/web/src/routes/api/screen-time/session.ts

diff --git a/apps/web/src/components/learning/Pomodoro.tsx b/apps/web/src/components/learning/Pomodoro.tsx
index dab57aa..64a8852 100644
--- a/apps/web/src/components/learning/Pomodoro.tsx
+++ b/apps/web/src/components/learning/Pomodoro.tsx
@@ -2,6 +2,7 @@ import {
     createContext,
     useContext,
     useEffect,
+    useMemo,
     useRef,
     useState,
     type ReactNode,
@@ -12,6 +13,18 @@ import {
     putPersonalEntry,
     usePersonalData,
 } from "@/lib/personal/store";
+import {
+    createFocusSync,
+    focusIntent,
+    screenTimeApi,
+    useScreenTimeLink,
+    type StudyFocus,
+} from "@/lib/screen-time/client";
+import {
+    SCREEN_TIME_SOURCE,
+    screenTimeMessage,
+    type ScreenTimeStatus,
+} from "@/lib/screen-time/contract";
 
 const sessionSchema = z.object({
     mode: z.enum(["focus", "break"]),
@@ -27,9 +40,35 @@ const Context = createContext<{
     toggle: () => void;
     reset: () => void;
     configure: (kind: "focus" | "rest", value: number) => void;
+    linked: boolean;
+    linkStatus: ScreenTimeStatus | null;
 } | null>(null);
+const StudyFocusContext = createContext<
+    ((focus: StudyFocus | null) => void) | null
+>(null);
 const KEY = "syllo:pomodoro-session";
 
+/**
+ * The lesson page reports the open lesson through this hook so a running focus
+ * period can name its Screen Time session and keep the lesson's sites allowed.
+ * The setter lives outside the timer context so ticks never re-render the page,
+ * and the last lesson stays the goal after the page unmounts.
+ */
+export function useStudyFocus(focus: StudyFocus | null) {
+    const setStudy = useContext(StudyFocusContext);
+    const key = focus ? [focus.goal, ...focus.resourceUrls].join("\n") : "";
+    const focusRef = useRef(focus);
+    focusRef.current = focus;
+    useEffect(() => {
+        setStudy?.(focusRef.current);
+    }, [key, setStudy]);
+}
+
+/**
+ * Owns the timer state for the whole app and mirrors it to Screen Time when
+ * the user linked the two. The sync only sends on real intent changes, never
+ * on the per-second tick.
+ */
 export default function PomodoroProvider({
     children,
 }: {
@@ -41,8 +80,24 @@ export default function PomodoroProvider({
     const rest = entry?.kind === "timer" ? entry.data.rest : 5;
     const [session, setSession] = useState<Session>(initial);
     const [loaded, setLoaded] = useState(false);
+    const [study, setStudy] = useState<StudyFocus | null>(null);
+    const [linked] = useScreenTimeLink();
+    const [linkStatus, setLinkStatus] = useState<ScreenTimeStatus | null>(null);
     const sessionRef = useRef(session);
     sessionRef.current = session;
+    const syncRef = useRef<ReturnType<typeof createFocusSync> | null>(null);
+    if (syncRef.current === null)
+        syncRef.current = createFocusSync({
+            send: (intent) =>
+                intent.kind === "start"
+                    ? screenTimeApi.start({
+                          goal: intent.goal,
+                          durationSeconds: intent.durationSeconds,
+                          resourceUrls: intent.resourceUrls,
+                      })
+                    : screenTimeApi.stop(),
+            onStatus: setLinkStatus,
+        });
     useEffect(() => {
         try {
             const raw = localStorage.getItem(KEY);
@@ -121,26 +176,86 @@ export default function PomodoroProvider({
             endAt: null,
         });
     }
+    // Ticks only change `remaining`, so this intent identity stays put between
+    // real state changes and the effect below never re-sends on a tick.
+    const intent = useMemo(
+        () =>
+            focusIntent(
+                { mode: session.mode, endAt: session.endAt },
+                study,
+            ),
+        [session.mode, session.endAt, study],
+    );
+    useEffect(() => {
+        if (!loaded) return;
+        const sync = syncRef.current;
+        if (!sync) return;
+        if (linked) sync.update(intent);
+        else {
+            sync.release();
+            setLinkStatus(null);
+        }
+    }, [loaded, linked, intent]);
     return (
-        <Context.Provider
-            value={{ session, focus, rest, toggle, reset, configure }}
-        >
-            {children}
-        </Context.Provider>
+        <StudyFocusContext.Provider value={setStudy}>
+            <Context.Provider
+                value={{
+                    session,
+                    focus,
+                    rest,
+                    toggle,
+                    reset,
+                    configure,
+                    linked,
+                    linkStatus,
+                }}
+            >
+                {children}
+            </Context.Provider>
+        </StudyFocusContext.Provider>
     );
 }
 
+/**
+ * The timer card on the lesson page. When the Screen Time link is on it shows
+ * whether the local app is blocking distractions, and otherwise stays a plain
+ * timer.
+ */
 export function Pomodoro() {
     const timer = useContext(Context);
     if (!timer) return null;
-    const { session, focus, rest, toggle, reset, configure } = timer;
+    const {
+        session,
+        focus,
+        rest,
+        toggle,
+        reset,
+        configure,
+        linked,
+        linkStatus,
+    } = timer;
+    const runningFocus = session.mode === "focus" && session.endAt !== null;
+    const blocking =
+        linked &&
+        runningFocus &&
+        linkStatus?.kind === "ready" &&
+        linkStatus.session?.source === SCREEN_TIME_SOURCE;
     const minutes = String(Math.floor(session.remaining / 60)).padStart(2, "0");
     const seconds = String(session.remaining % 60).padStart(2, "0");
     return (
         <section className="sy-pomodoro">
             <div className="sy-pomodoro-head">
                 <h2>Pomodoro</h2>
-                <span>{session.mode === "focus" ? "Focus" : "Break"}</span>
+                <span
+                    title={
+                        blocking
+                            ? "Screen Time is blocking distractions"
+                            : undefined
+                    }
+                >
+                    {session.mode === "focus" ? "Focus" : "Break"}
+                    {blocking ? " · Screen Time" : ""}
+                </span>
             </div>
             <div
                 className="sy-timer-clock"
@@ -157,6 +272,11 @@ export function Pomodoro() {
                     Reset
                 </button>
             </div>
+            {linked && runningFocus && linkStatus?.kind !== "ready" ? (
+                <p className="sy-form-hint" role="status">
+                    {screenTimeMessage(linkStatus)}
+                </p>
+            ) : null}
             <div className="sy-timer-settings">
                 <label>
                     Focus · min
diff --git a/apps/web/src/components/learning/ScreenTimeSettings.tsx b/apps/web/src/components/learning/ScreenTimeSettings.tsx
new file mode 100644
index 0000000..2a62e25
--- /dev/null
+++ b/apps/web/src/components/learning/ScreenTimeSettings.tsx
@@ -0,0 +1,58 @@
+import { useCallback, useEffect, useState } from "react";
+import SettingsSection from "@/components/layout/SettingsSection";
+import { Switch } from "@/components/ui/switch";
+import { screenTimeApi, useScreenTimeLink } from "@/lib/screen-time/client";
+import {
+    screenTimeMessage,
+    type ScreenTimeStatus,
+} from "@/lib/screen-time/contract";
+
+/**
+ * The Settings page row that links the Pomodoro timer to the Screen Time app
+ * on this computer. Reachability is reported under the toggle whether or not
+ * the link is on.
+ */
+export default function ScreenTimeSettings() {
+    const [linked, setLinked] = useScreenTimeLink();
+    const [status, setStatus] = useState<ScreenTimeStatus | null>(null);
+    const check = useCallback(() => {
+        setStatus(null);
+        void screenTimeApi.status().then(setStatus);
+    }, []);
+    useEffect(() => {
+        check();
+    }, [check]);
+    return (
+        <SettingsSection
+            title="Screen Time"
+            description={
+                <>
+                    Block distracting apps and sites while a focus period runs.
+                    Choose what stays allowed in Screen Time; Syllo and your
+                    lesson’s links always stay open. This works only when Syllo
+                    runs on the same computer as Screen Time, not from a hosted
+                    Syllo.
+                </>
+            }
+        >
+            <div className="flex items-start justify-between gap-4">
+                <p className="text-sm text-text">
+                    Start a Screen Time session with each focus period
+                </p>
+                <Switch
+                    aria-label="Link Screen Time to focus periods"
+                    checked={linked}
+                    onCheckedChange={setLinked}
+                />
+            </div>
+            <p className="sy-form-hint" role="status">
+                {screenTimeMessage(status)}
+            </p>
+            <div className="sy-card-actions">
+                <button className="sy-button quiet" onClick={check}>
+                    Check again
+                </button>
+            </div>
+        </SettingsSection>
+    );
+}
diff --git a/apps/web/src/lib/__tests__/screen-time-adapter.test.ts b/apps/web/src/lib/__tests__/screen-time-adapter.test.ts
new file mode 100644
index 0000000..e5e386f
--- /dev/null
+++ b/apps/web/src/lib/__tests__/screen-time-adapter.test.ts
@@ -0,0 +1,346 @@
+import http from "node:http";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+    allowSitesFor,
+    connectionFilePath,
+    getFocusStatus,
+    startFocusSession,
+    stopFocusSession,
+} from "@/lib/server/screen-time";
+
+const TOKEN = "test-token";
+const SESSION = {
+    id: "s1",
+    goal: "Study",
+    source: "syllo",
+    mode: "block",
+    apps: ["Mail"],
+    sites: ["example.com"],
+    allowSites: ["localhost"],
+    startedAt: "2026-01-01T00:00:00.000Z",
+    endsAt: "2026-01-01T00:25:00.000Z",
+};
+
+interface RecordedRequest {
+    method: string | undefined;
+    url: string | undefined;
+    token: string | string[] | undefined;
+    body: unknown;
+}
+
+let server: http.Server;
+let requests: RecordedRequest[];
+let responder: (request: RecordedRequest) => {
+    status: number;
+    payload: unknown;
+};
+let port: number;
+let dir: string;
+let connectionPath: string;
+
+beforeEach(async () => {
+    requests = [];
+    responder = () => ({ status: 200, payload: { session: null } });
+    server = http.createServer((req, res) => {
+        let raw = "";
+        req.on("data", (chunk) => {
+            raw += chunk;
+        });
+        req.on("end", () => {
+            let body: unknown;
+            try {
+                body = JSON.parse(raw);
+            } catch {
+                body = undefined;
+            }
+            const recorded: RecordedRequest = {
+                method: req.method,
+                url: req.url,
+                token: req.headers["x-tally-token"],
+                body,
+            };
+            requests.push(recorded);
+            const { status, payload } = responder(recorded);
+            res.writeHead(status, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(payload));
+        });
+    });
+    await new Promise<void>((resolve) => {
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string")
+        throw new Error("test server has no port");
+    port = address.port;
+    dir = await mkdtemp(path.join(tmpdir(), "syllo-screen-time-"));
+    connectionPath = path.join(dir, "screen-time", "connection.json");
+});
+
+afterEach(async () => {
+    await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+    });
+    await rm(dir, { recursive: true, force: true });
+});
+
+async function writeConnection(overrides: Record<string, unknown> = {}) {
+    await mkdir(path.dirname(connectionPath), { recursive: true });
+    await writeFile(
+        connectionPath,
+        JSON.stringify({
+            version: 1,
+            url: `http://127.0.0.1:${port}`,
+            token: TOKEN,
+            pid: process.pid,
+            ...overrides,
+        }),
+    );
+}
+
+describe("screen time http adapter", () => {
+    it("reports ready with no session and sends the token", async () => {
+        await writeConnection();
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "ready", session: null });
+        expect(requests).toHaveLength(1);
+        expect(requests[0].method).toBe("GET");
+        expect(requests[0].url).toBe("/api/v1/focus/session");
+        expect(requests[0].token).toBe(TOKEN);
+    });
+
+    it("starts a session with only goal, source, duration and allowSites", async () => {
+        await writeConnection();
+        responder = () => ({ status: 201, payload: { session: SESSION } });
+        const status = await startFocusSession(
+            {
+                goal: "Read chapter 4",
+                durationSeconds: 1500,
+                allowSites: ["localhost"],
+            },
+            { connectionPath },
+        );
+        expect(status).toEqual({ kind: "ready", session: SESSION });
+        const body = requests[0].body;
+        if (typeof body !== "object" || body === null)
+            throw new Error("expected a JSON body");
+        expect(Object.keys(body).sort()).toEqual([
+            "allowSites",
+            "durationSeconds",
+            "goal",
+            "source",
+        ]);
+        expect(body).toMatchObject({
+            goal: "Read chapter 4",
+            source: "syllo",
+            durationSeconds: 1500,
+            allowSites: ["localhost"],
+        });
+    });
+
+    it("stops a session with a source-scoped delete", async () => {
+        await writeConnection();
+        await expect(
+            stopFocusSession({ connectionPath }),
+        ).resolves.toEqual({ kind: "ready", session: null });
+        expect(requests[0].method).toBe("DELETE");
+        expect(requests[0].url).toBe("/api/v1/focus/session?source=syllo");
+    });
+
+    it("maps a 409 to busy with the other session", async () => {
+        await writeConnection();
+        const other = { ...SESSION, source: "other-app" };
+        responder = () => ({ status: 409, payload: { session: other } });
+        const status = await startFocusSession(
+            { goal: "g", durationSeconds: 60, allowSites: [] },
+            { connectionPath },
+        );
+        expect(status).toEqual({ kind: "busy", session: other });
+    });
+
+    it("reports not-running when the directory exists without a file", async () => {
+        await mkdir(path.dirname(connectionPath), { recursive: true });
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "not-running" });
+        expect(requests).toHaveLength(0);
+    });
+
+    it("reports not-installed when the directory is missing", async () => {
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "not-installed" });
+        expect(requests).toHaveLength(0);
+    });
+
+    it("reports unavailable for a file that is not JSON", async () => {
+        await mkdir(path.dirname(connectionPath), { recursive: true });
+        await writeFile(connectionPath, "not json");
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "unavailable" });
+        expect(requests).toHaveLength(0);
+    });
+
+    it("refuses a non-loopback url and sends nothing", async () => {
+        await writeConnection({ url: "http://example.com" });
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "unavailable" });
+        expect(requests).toHaveLength(0);
+    });
+
+    it("reports not-running when the port is closed", async () => {
+        const dead = http.createServer();
+        await new Promise<void>((resolve) => {
+            dead.listen(0, "127.0.0.1", resolve);
+        });
+        const deadAddress = dead.address();
+        if (deadAddress === null || typeof deadAddress === "string")
+            throw new Error("dead server has no port");
+        const deadPort = deadAddress.port;
+        await new Promise<void>((resolve) => {
+            dead.close(() => resolve());
+        });
+        await writeConnection({ url: `http://127.0.0.1:${deadPort}` });
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "not-running" });
+    });
+
+    it("reports not-running for a dead pid without calling http", async () => {
+        await writeConnection({ pid: 2147483646 });
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "not-running" });
+        expect(requests).toHaveLength(0);
+    });
+
+    it("maps 404 to outdated", async () => {
+        await writeConnection();
+        responder = () => ({ status: 404, payload: { error: "gone" } });
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "outdated" });
+    });
+
+    it("maps a 200 with a junk body to outdated", async () => {
+        await writeConnection();
+        responder = () => ({ status: 200, payload: { junk: true } });
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "outdated" });
+    });
+
+    it("maps 401 to unavailable", async () => {
+        await writeConnection();
+        responder = () => ({ status: 401, payload: { error: "bad token" } });
+        await expect(
+            getFocusStatus({ connectionPath }),
+        ).resolves.toEqual({ kind: "unavailable" });
+    });
+});
+
+describe("connectionFilePath", () => {
+    const home = path.join("home", "user");
+
+    it("uses APPDATA on win32 and falls back to the profile", () => {
+        expect(
+            connectionFilePath({
+                platform: "win32",
+                env: { APPDATA: path.join("C:", "roaming") },
+                home,
+            }),
+        ).toBe(path.join("C:", "roaming", "screen-time", "connection.json"));
+        expect(
+            connectionFilePath({ platform: "win32", env: {}, home }),
+        ).toBe(
+            path.join(
+                home,
+                "AppData",
+                "Roaming",
+                "screen-time",
+                "connection.json",
+            ),
+        );
+    });
+
+    it("uses Application Support on darwin", () => {
+        expect(
+            connectionFilePath({ platform: "darwin", env: {}, home }),
+        ).toBe(
+            path.join(
+                home,
+                "Library",
+                "Application Support",
+                "screen-time",
+                "connection.json",
+            ),
+        );
+    });
+
+    it("honours XDG_CONFIG_HOME and falls back to ~/.config on linux", () => {
+        expect(
+            connectionFilePath({
+                platform: "linux",
+                env: { XDG_CONFIG_HOME: path.join("xdg", "cfg") },
+                home,
+            }),
+        ).toBe(path.join("xdg", "cfg", "screen-time", "connection.json"));
+        expect(
+            connectionFilePath({ platform: "linux", env: {}, home }),
+        ).toBe(path.join(home, ".config", "screen-time", "connection.json"));
+    });
+});
+
+describe("allowSitesFor", () => {
+    it("puts the Syllo host first and strips ports", () => {
+        expect(
+            allowSitesFor({
+                requestHost: "localhost:3000",
+                resourceUrls: [],
+            }),
+        ).toEqual(["localhost"]);
+        expect(
+            allowSitesFor({ requestHost: "[::1]:3000", resourceUrls: [] }),
+        ).toEqual(["[::1]"]);
+    });
+
+    it("normalizes www, case and trailing dots", () => {
+        expect(
+            allowSitesFor({
+                requestHost: null,
+                resourceUrls: ["https://WWW.Example.COM./page"],
+            }),
+        ).toEqual(["example.com"]);
+    });
+
+    it("adds youtube.com for youtube short and nocookie hosts", () => {
+        expect(
+            allowSitesFor({
+                requestHost: null,
+                resourceUrls: [
+                    "https://youtu.be/abc",
+                    "https://www.youtube-nocookie.com/embed/abc",
+                ],
+            }),
+        ).toEqual(["youtu.be", "youtube.com", "youtube-nocookie.com"]);
+    });
+
+    it("skips non-http urls and dedupes", () => {
+        expect(
+            allowSitesFor({
+                requestHost: "example.com:3000",
+                resourceUrls: [
+                    "ftp://files.example.com/a",
+                    "not a url",
+                    "https://example.com/x",
+                    "https://example.com/y",
+                ],
+            }),
+        ).toEqual(["example.com"]);
+    });
+});
diff --git a/apps/web/src/lib/__tests__/screen-time-link.test.ts b/apps/web/src/lib/__tests__/screen-time-link.test.ts
new file mode 100644
index 0000000..5289f36
--- /dev/null
+++ b/apps/web/src/lib/__tests__/screen-time-link.test.ts
@@ -0,0 +1,202 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+    createFocusSync,
+    focusIntent,
+    type FocusIntent,
+} from "@/lib/screen-time/client";
+import type { ScreenTimeStatus } from "@/lib/screen-time/contract";
+
+type SendIntent =
+    | { kind: "stop" }
+    | {
+          kind: "start";
+          goal: string;
+          resourceUrls: string[];
+          durationSeconds: number;
+      };
+
+const READY: ScreenTimeStatus = { kind: "ready", session: null };
+
+function makeSync(now: () => number = () => 0) {
+    const sent: SendIntent[] = [];
+    const statuses: ScreenTimeStatus[] = [];
+    let gate: Promise<void> | null = null;
+    const send = (intent: SendIntent): Promise<ScreenTimeStatus> => {
+        sent.push(intent);
+        return gate ? gate.then(() => READY) : Promise.resolve(READY);
+    };
+    const sync = createFocusSync({
+        send,
+        onStatus: (status) => statuses.push(status),
+        now,
+    });
+    return {
+        sent,
+        statuses,
+        sync,
+        hold: (pending: Promise<void> | null) => {
+            gate = pending;
+        },
+    };
+}
+
+describe("focusIntent", () => {
+    it("stops for an idle timer and a running break", () => {
+        expect(
+            focusIntent({ mode: "focus", endAt: null }, null),
+        ).toEqual({ kind: "stop" });
+        expect(
+            focusIntent({ mode: "break", endAt: 1000 }, null),
+        ).toEqual({ kind: "stop" });
+    });
+
+    it("starts for a running focus with a fallback goal", () => {
+        expect(
+            focusIntent({ mode: "focus", endAt: 1000 }, null),
+        ).toEqual({
+            kind: "start",
+            goal: "Study session",
+            resourceUrls: [],
+            endAt: 1000,
+        });
+    });
+
+    it("uses the lesson goal and resources", () => {
+        expect(
+            focusIntent(
+                { mode: "focus", endAt: 1000 },
+                { goal: "  Kerning  ", resourceUrls: ["https://a.test"] },
+            ),
+        ).toEqual({
+            kind: "start",
+            goal: "Kerning",
+            resourceUrls: ["https://a.test"],
+            endAt: 1000,
+        });
+    });
+});
+
+describe("createFocusSync", () => {
+    it("sends the first update even when it is a stop", () => {
+        const { sent, sync } = makeSync();
+        sync.update({ kind: "stop" });
+        expect(sent).toEqual([{ kind: "stop" }]);
+    });
+
+    it("does not resend an unchanged intent", async () => {
+        const { sent, statuses, sync } = makeSync();
+        const start: FocusIntent = {
+            kind: "start",
+            goal: "g",
+            resourceUrls: [],
+            endAt: 60_000,
+        };
+        sync.update(start);
+        sync.update(start);
+        await vi.waitFor(() => expect(statuses).toHaveLength(1));
+        sync.update({ kind: "stop" });
+        sync.update({ kind: "stop" });
+        await vi.waitFor(() => expect(statuses).toHaveLength(2));
+        expect(sent).toHaveLength(2);
+    });
+
+    it("sends stop on pause and start on resume", async () => {
+        const { sent, statuses, sync } = makeSync();
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 60_000 });
+        await vi.waitFor(() => expect(statuses).toHaveLength(1));
+        sync.update({ kind: "stop" });
+        await vi.waitFor(() => expect(statuses).toHaveLength(2));
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 90_000 });
+        await vi.waitFor(() => expect(statuses).toHaveLength(3));
+        expect(sent.map((i) => i.kind)).toEqual(["start", "stop", "start"]);
+    });
+
+    it("derives durationSeconds from endAt at send time", () => {
+        const { sent, sync } = makeSync(() => 10_000);
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 70_500 });
+        expect(sent[0]).toEqual({
+            kind: "start",
+            goal: "g",
+            resourceUrls: [],
+            durationSeconds: 61,
+        });
+    });
+
+    it("sends a stop instead when endAt already passed", () => {
+        const { sent, sync } = makeSync(() => 80_000);
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 70_000 });
+        expect(sent).toEqual([{ kind: "stop" }]);
+    });
+
+    it("coalesces updates while a request is in flight", async () => {
+        const { sent, sync, hold } = makeSync();
+        let release!: () => void;
+        hold(new Promise<void>((resolve) => (release = resolve)));
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 60_000 });
+        sync.update({ kind: "start", goal: "h", resourceUrls: [], endAt: 70_000 });
+        sync.update({ kind: "stop" });
+        expect(sent).toHaveLength(1);
+        release();
+        await vi.waitFor(() => expect(sent).toHaveLength(2));
+        expect(sent[1]).toEqual({ kind: "stop" });
+    });
+
+    it("reports unavailable when send rejects and keeps working", async () => {
+        const statuses: ScreenTimeStatus[] = [];
+        let fail = true;
+        const send = (): Promise<ScreenTimeStatus> =>
+            fail ? Promise.reject(new Error("down")) : Promise.resolve(READY);
+        const sync = createFocusSync({
+            send,
+            onStatus: (status) => statuses.push(status),
+            now: () => 0,
+        });
+        sync.update({ kind: "stop" });
+        await vi.waitFor(() => expect(statuses).toHaveLength(1));
+        expect(statuses[0]).toEqual({ kind: "unavailable" });
+        fail = false;
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 60_000 });
+        await vi.waitFor(() => expect(statuses).toHaveLength(2));
+        expect(statuses[1]).toEqual(READY);
+    });
+
+    it("release stops only after a start and re-arms the next update", async () => {
+        const { sent, statuses, sync } = makeSync();
+        sync.release();
+        expect(sent).toHaveLength(0);
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 60_000 });
+        await vi.waitFor(() => expect(statuses).toHaveLength(1));
+        sync.release();
+        await vi.waitFor(() => expect(sent).toHaveLength(2));
+        expect(sent[1]).toEqual({ kind: "stop" });
+        await vi.waitFor(() => expect(statuses).toHaveLength(2));
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 90_000 });
+        await vi.waitFor(() => expect(sent).toHaveLength(3));
+    });
+
+    it("drops a queued start when released while a stop is in flight", async () => {
+        const { sent, statuses, sync, hold } = makeSync();
+        let resolve!: () => void;
+        hold(new Promise<void>((done) => (resolve = done)));
+        sync.update({ kind: "stop" });
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 60_000 });
+        sync.release();
+        resolve();
+        await vi.waitFor(() => expect(statuses).toHaveLength(1));
+        await new Promise((done) => setTimeout(done, 0));
+        expect(sent).toEqual([{ kind: "stop" }]);
+    });
+
+    it("lets a later stop replace a queued start", async () => {
+        const { sent, statuses, sync, hold } = makeSync();
+        let resolve!: () => void;
+        hold(new Promise<void>((done) => (resolve = done)));
+        sync.update({ kind: "stop" });
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 60_000 });
+        sync.update({ kind: "stop" });
+        resolve();
+        await vi.waitFor(() => expect(statuses).toHaveLength(1));
+        await new Promise((done) => setTimeout(done, 0));
+        expect(sent).toEqual([{ kind: "stop" }]);
+    });
+});
diff --git a/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx b/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
new file mode 100644
index 0000000..86a4674
--- /dev/null
+++ b/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
@@ -0,0 +1,144 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import PomodoroProvider, { Pomodoro } from "@/components/learning/Pomodoro";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const LINK_KEY = "syllo:screen-time-link";
+const SESSION_KEY = "syllo:pomodoro-session";
+
+interface FetchCall {
+    method: string;
+    url: string;
+    body: unknown;
+}
+
+let calls: FetchCall[];
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+    localStorage.clear();
+    calls = [];
+    vi.stubGlobal(
+        "fetch",
+        vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+            let body: unknown;
+            try {
+                body =
+                    typeof init?.body === "string"
+                        ? JSON.parse(init.body)
+                        : undefined;
+            } catch {
+                body = undefined;
+            }
+            calls.push({
+                method: init?.method ?? "GET",
+                url: String(input),
+                body,
+            });
+            return Promise.resolve(
+                new Response(
+                    JSON.stringify({ kind: "ready", session: null }),
+                    {
+                        status: 200,
+                        headers: { "Content-Type": "application/json" },
+                    },
+                ),
+            );
+        }),
+    );
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+});
+
+afterEach(async () => {
+    await act(async () => {
+        root.unmount();
+    });
+    container.remove();
+    vi.unstubAllGlobals();
+});
+
+async function render() {
+    await act(async () => {
+        root.render(
+            <PomodoroProvider>
+                <Pomodoro />
+            </PomodoroProvider>,
+        );
+    });
+}
+
+async function click(text: string) {
+    const button = Array.from(container.querySelectorAll("button")).find(
+        (el) => el.textContent === text,
+    );
+    if (!button) throw new Error(`no button labelled ${text}`);
+    await act(async () => {
+        button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+}
+
+function storeSession(session: Record<string, unknown>) {
+    localStorage.setItem(SESSION_KEY, JSON.stringify(session));
+}
+
+describe("pomodoro screen time link", () => {
+    it("posts a session for the full focus period on Start", async () => {
+        localStorage.setItem(LINK_KEY, "on");
+        await render();
+        await click("Start");
+        const post = calls.find((call) => call.method === "POST");
+        expect(post).toBeDefined();
+        expect(post?.url).toBe("/api/screen-time/session");
+        if (typeof post?.body !== "object" || post.body === null)
+            throw new Error("expected a JSON body");
+        expect(post.body).toMatchObject({
+            goal: "Study session",
+            durationSeconds: 1500,
+            resourceUrls: [],
+        });
+    });
+
+    it("deletes the session on Pause", async () => {
+        localStorage.setItem(LINK_KEY, "on");
+        await render();
+        await click("Start");
+        await click("Pause");
+        expect(calls[calls.length - 1].method).toBe("DELETE");
+        expect(calls[calls.length - 1].url).toBe("/api/screen-time/session");
+    });
+
+    it("reposts the remaining time for a stored running focus", async () => {
+        localStorage.setItem(LINK_KEY, "on");
+        storeSession({
+            mode: "focus",
+            remaining: 300,
+            endAt: Date.now() + 300_000,
+        });
+        await render();
+        const post = calls.find((call) => call.method === "POST");
+        expect(post).toBeDefined();
+        if (typeof post?.body !== "object" || post.body === null)
+            throw new Error("expected a JSON body");
+        expect(post.body).toMatchObject({ durationSeconds: 300 });
+    });
+
+    it("sends a stop for a stored idle timer so nothing keeps blocking", async () => {
+        localStorage.setItem(LINK_KEY, "on");
+        storeSession({ mode: "focus", remaining: 1500, endAt: null });
+        await render();
+        expect(calls).toHaveLength(1);
+        expect(calls[0].method).toBe("DELETE");
+    });
+
+    it("stays silent when the link is off", async () => {
+        await render();
+        await click("Start");
+        expect(calls).toHaveLength(0);
+    });
+});
diff --git a/apps/web/src/lib/screen-time/client.ts b/apps/web/src/lib/screen-time/client.ts
new file mode 100644
index 0000000..3170e4e
--- /dev/null
+++ b/apps/web/src/lib/screen-time/client.ts
@@ -0,0 +1,200 @@
+import { useSyncExternalStore } from "react";
+import { fetchPrivateApi } from "@/lib/private-api-fetch";
+import {
+    screenTimeStatusSchema,
+    type FocusStartRequest,
+    type ScreenTimeStatus,
+} from "./contract";
+
+const PATH = "/api/screen-time/session";
+const LINK_KEY = "syllo:screen-time-link";
+const REQUEST_TIMEOUT_MS = 5000;
+
+async function callApi(init: RequestInit): Promise<ScreenTimeStatus> {
+    try {
+        const response = await fetchPrivateApi(PATH, {
+            ...init,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok) return { kind: "unavailable" };
+        const parsed = screenTimeStatusSchema.safeParse(await response.json());
+        return parsed.success ? parsed.data : { kind: "unavailable" };
+    } catch {
+        return { kind: "unavailable" };
+    }
+}
+
+/**
+ * Talk to Syllo's Screen Time route. Every call resolves a status and never
+ * throws, so callers can render the union directly.
+ */
+export const screenTimeApi = {
+    status: () => callApi({ method: "GET" }),
+    start: (input: FocusStartRequest) =>
+        callApi({
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        }),
+    stop: () => callApi({ method: "DELETE" }),
+};
+
+const listeners = new Set<() => void>();
+
+function readLinked(): boolean {
+    try {
+        return localStorage.getItem(LINK_KEY) === "on";
+    } catch {
+        return false;
+    }
+}
+
+function subscribe(listener: () => void): () => void {
+    listeners.add(listener);
+    const onStorage = (event: StorageEvent) => {
+        if (event.key === null || event.key === LINK_KEY) listener();
+    };
+    window.addEventListener("storage", onStorage);
+    return () => {
+        listeners.delete(listener);
+        window.removeEventListener("storage", onStorage);
+    };
+}
+
+/**
+ * The per-browser "link Screen Time to the timer" toggle. It is stored in
+ * localStorage only and never syncs. Writes notify every listener in this tab;
+ * the storage event covers other tabs.
+ */
+export function useScreenTimeLink(): readonly [
+    boolean,
+    (on: boolean) => void,
+] {
+    const linked = useSyncExternalStore(subscribe, readLinked, () => false);
+    const setLinked = (on: boolean) => {
+        try {
+            if (on) localStorage.setItem(LINK_KEY, "on");
+            else localStorage.removeItem(LINK_KEY);
+        } catch {
+            /* Storage may be blocked; the toggle just stays off. */
+        }
+        for (const listener of listeners) listener();
+    };
+    return [linked, setLinked] as const;
+}
+
+/** What the current lesson contributes to a focus session request. */
+export type StudyFocus = { goal: string; resourceUrls: string[] };
+
+/** What the timer wants Screen Time to do after a state change. */
+export type FocusIntent =
+    | { kind: "stop" }
+    | { kind: "start"; goal: string; resourceUrls: string[]; endAt: number };
+
+/**
+ * Map timer state to a Screen Time intent. Only a running focus period starts
+ * a session; breaks, pauses and idle all stop it.
+ */
+export function focusIntent(
+    session: { mode: "focus" | "break"; endAt: number | null },
+    study: StudyFocus | null,
+): FocusIntent {
+    if (session.mode === "focus" && session.endAt !== null)
+        return {
+            kind: "start",
+            goal: (study?.goal.trim() || "Study session").slice(0, 200),
+            resourceUrls: study?.resourceUrls ?? [],
+            endAt: session.endAt,
+        };
+    return { kind: "stop" };
+}
+
+type SendIntent =
+    | { kind: "stop" }
+    | {
+          kind: "start";
+          goal: string;
+          resourceUrls: string[];
+          durationSeconds: number;
+      };
+
+function intentKey(intent: FocusIntent): string {
+    if (intent.kind === "stop") return "stop";
+    return JSON.stringify({
+        goal: intent.goal,
+        resourceUrls: [...intent.resourceUrls].sort(),
+        endAt: intent.endAt,
+    });
+}
+
+/**
+ * Turn the intent stream into ordered requests: dedupe repeats, keep one
+ * request in flight, coalesce to the latest pending intent, and translate
+ * rejections into the unavailable status. The first update always sends, so a
+ * reloaded page reconciles Screen Time with the stored timer.
+ */
+export function createFocusSync({
+    send,
+    onStatus,
+    now = Date.now,
+}: {
+    send: (intent: SendIntent) => Promise<ScreenTimeStatus>;
+    onStatus: (status: ScreenTimeStatus) => void;
+    now?: () => number;
+}) {
+    let lastKey: string | null = null;
+    let inFlight = false;
+    let pending: FocusIntent | null = null;
+    let lastSentStart = false;
+
+    function dispatch(intent: FocusIntent): void {
+        let outgoing: SendIntent;
+        if (intent.kind === "stop") {
+            outgoing = { kind: "stop" };
+        } else {
+            const durationSeconds = Math.ceil((intent.endAt - now()) / 1000);
+            outgoing =
+                durationSeconds <= 0
+                    ? { kind: "stop" }
+                    : {
+                          kind: "start",
+                          goal: intent.goal,
+                          resourceUrls: intent.resourceUrls,
+                          durationSeconds,
+                      };
+        }
+        inFlight = true;
+        lastSentStart = outgoing.kind === "start";
+        send(outgoing)
+            .then(onStatus)
+            .catch(() => onStatus({ kind: "unavailable" }))
+            .finally(() => {
+                inFlight = false;
+                const next = pending;
+                pending = null;
+                if (next !== null) update(next);
+            });
+    }
+
+    function update(intent: FocusIntent): void {
+        const key = intentKey(intent);
+        if (inFlight) {
+            // Whatever is queued loses to the newest intent, including "the
+            // same as what is already being sent".
+            pending = key === lastKey ? null : intent;
+            return;
+        }
+        if (key === lastKey) return;
+        lastKey = key;
+        dispatch(intent);
+    }
+
+    function release(): void {
+        pending = null;
+        if (lastSentStart) update({ kind: "stop" });
+        lastKey = null;
+        lastSentStart = false;
+    }
+
+    return { update, release };
+}
diff --git a/apps/web/src/lib/screen-time/contract.ts b/apps/web/src/lib/screen-time/contract.ts
new file mode 100644
index 0000000..db29244
--- /dev/null
+++ b/apps/web/src/lib/screen-time/contract.ts
@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+/** Source name Syllo sends so Screen Time can tell its sessions apart. */
+export const SCREEN_TIME_SOURCE = "syllo";
+
+/**
+ * A focus session as Screen Time reports it. Extra keys are ignored so newer
+ * Screen Time versions stay readable.
+ */
+export const focusSessionSchema = z.looseObject({
+    id: z.string(),
+    goal: z.string(),
+    source: z.string(),
+    mode: z.enum(["allow", "block"]),
+    apps: z.array(z.string()),
+    sites: z.array(z.string()),
+    allowSites: z.array(z.string()),
+    startedAt: z.string(),
+    endsAt: z.string(),
+});
+export type FocusSession = z.infer<typeof focusSessionSchema>;
+
+/**
+ * What Syllo's own API reports to the browser. `ready` is reachable (the
+ * session may belong to another source), `busy` is a rejected start, and the
+ * rest explain why Screen Time cannot be used.
+ */
+export const screenTimeStatusSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("ready"),
+        session: focusSessionSchema.nullable(),
+    }),
+    z.object({
+        kind: z.literal("busy"),
+        session: focusSessionSchema.nullable(),
+    }),
+    z.object({ kind: z.literal("not-installed") }),
+    z.object({ kind: z.literal("not-running") }),
+    z.object({ kind: z.literal("outdated") }),
+    z.object({ kind: z.literal("unavailable") }),
+]);
+export type ScreenTimeStatus = z.infer<typeof screenTimeStatusSchema>;
+
+/** Body the browser sends when a focus period should start a session. */
+export const focusStartRequestSchema = z.object({
+    goal: z.string().trim().min(1).max(200),
+    durationSeconds: z.number().int().min(1).max(14400),
+    resourceUrls: z.array(z.string().max(2048)).max(100),
+});
+export type FocusStartRequest = z.infer<typeof focusStartRequestSchema>;
+
+/** One line of user-facing copy for each Screen Time status. */
+export function screenTimeMessage(status: ScreenTimeStatus | null): string {
+    if (status === null) return "Checking for Screen Time…";
+    switch (status.kind) {
+        case "ready": {
+            const session = status.session;
+            if (!session) return "Screen Time is running.";
+            if (session.source === SCREEN_TIME_SOURCE) {
+                const time = new Date(session.endsAt).toLocaleTimeString([], {
+                    hour: "numeric",
+                    minute: "2-digit",
+                });
+                return `Focus session on until ${time}.`;
+            }
+            return "Screen Time is running another focus session.";
+        }
+        case "busy":
+            return "Screen Time is busy with another focus session. Your timer keeps going.";
+        case "not-installed":
+            return "Screen Time isn't installed on this computer.";
+        case "not-running":
+            return "Screen Time isn't running. Open it to block distractions.";
+        case "outdated":
+            return "Update Screen Time to use focus sessions.";
+        case "unavailable":
+            return "Screen Time couldn't be reached. Your timer still works.";
+        default: {
+            const _exhaustive: never = status;
+            return _exhaustive;
+        }
+    }
+}
diff --git a/apps/web/src/lib/server/screen-time.ts b/apps/web/src/lib/server/screen-time.ts
new file mode 100644
index 0000000..a8d4a2c
--- /dev/null
+++ b/apps/web/src/lib/server/screen-time.ts
@@ -0,0 +1,289 @@
+import { readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import {
+    focusSessionSchema,
+    SCREEN_TIME_SOURCE,
+    type ScreenTimeStatus,
+} from "@/lib/screen-time/contract";
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"]);
+const REQUEST_TIMEOUT_MS = 1500;
+const MAX_ALLOW_SITES = 50;
+
+interface Connection {
+    base: string;
+    token: string;
+    pid: number;
+}
+
+const connectionSchema = z.object({
+    version: z.literal(1),
+    url: z.string(),
+    token: z.string().min(1),
+    pid: z.number().int().positive(),
+});
+
+/** Where Screen Time writes its connection file on each platform. */
+export function connectionFilePath({
+    platform,
+    env,
+    home,
+}: {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    home: string;
+}): string {
+    switch (platform) {
+        case "win32":
+            return path.join(
+                env.APPDATA ?? path.join(home, "AppData", "Roaming"),
+                "screen-time",
+                "connection.json",
+            );
+        case "darwin":
+            return path.join(
+                home,
+                "Library",
+                "Application Support",
+                "screen-time",
+                "connection.json",
+            );
+        default:
+            return path.join(
+                env.XDG_CONFIG_HOME ?? path.join(home, ".config"),
+                "screen-time",
+                "connection.json",
+            );
+    }
+}
+
+function hasCode(error: unknown, code: string): boolean {
+    return (
+        typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code
+    );
+}
+
+/**
+ * Read and validate the connection file. Any failure resolves to a status so
+ * callers never send the token anywhere a tampered file points to.
+ */
+async function readConnection(
+    connectionPath: string,
+): Promise<Connection | ScreenTimeStatus> {
+    let raw: string;
+    try {
+        raw = await readFile(connectionPath, "utf8");
+    } catch (error) {
+        if (!hasCode(error, "ENOENT")) return { kind: "unavailable" };
+        try {
+            await stat(path.dirname(connectionPath));
+            return { kind: "not-running" };
+        } catch {
+            return { kind: "not-installed" };
+        }
+    }
+    let json: unknown;
+    try {
+        json = JSON.parse(raw);
+    } catch {
+        return { kind: "unavailable" };
+    }
+    const parsed = connectionSchema.safeParse(json);
+    if (!parsed.success) return { kind: "unavailable" };
+    let url: URL;
+    try {
+        url = new URL(parsed.data.url);
+    } catch {
+        return { kind: "unavailable" };
+    }
+    if (url.protocol !== "http:" || !LOOPBACK_HOSTS.has(url.hostname))
+        return { kind: "unavailable" };
+    return { base: url.origin, token: parsed.data.token, pid: parsed.data.pid };
+}
+
+/** A stale connection file often outlives the app; EPERM still means alive. */
+function processAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        return hasCode(error, "EPERM");
+    }
+}
+
+function resolvePath(options?: { connectionPath?: string }): string {
+    return (
+        options?.connectionPath ??
+        connectionFilePath({
+            platform: process.platform,
+            env: process.env,
+            home: os.homedir(),
+        })
+    );
+}
+
+async function parseBody(response: Response): Promise<unknown> {
+    try {
+        return await response.json();
+    } catch {
+        return undefined;
+    }
+}
+
+/** Status codes that mean something other than "reachable". */
+function mapFailureStatus(response: Response): ScreenTimeStatus {
+    if (
+        response.status === 404 ||
+        response.status === 405 ||
+        response.status === 501
+    )
+        return { kind: "outdated" };
+    return { kind: "unavailable" };
+}
+
+async function callScreenTime(
+    connectionPath: string,
+    method: "GET" | "POST" | "DELETE",
+    body?: unknown,
+): Promise<Response | ScreenTimeStatus> {
+    const connection = await readConnection(connectionPath);
+    if ("kind" in connection) return connection;
+    if (!processAlive(connection.pid)) return { kind: "not-running" };
+    const query = method === "DELETE" ? `?source=${SCREEN_TIME_SOURCE}` : "";
+    try {
+        return await fetch(
+            `${connection.base}/api/v1/focus/session${query}`,
+            {
+                method,
+                headers: {
+                    "X-Tally-Token": connection.token,
+                    ...(body === undefined
+                        ? {}
+                        : { "Content-Type": "application/json" }),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            },
+        );
+    } catch {
+        return { kind: "not-running" };
+    }
+}
+
+const sessionResponseSchema = z.object({
+    session: focusSessionSchema.nullable(),
+});
+
+/** Report what Screen Time is doing right now, per the API route's GET. */
+export async function getFocusStatus(options?: {
+    connectionPath?: string;
+}): Promise<ScreenTimeStatus> {
+    const result = await callScreenTime(resolvePath(options), "GET");
+    if (!(result instanceof Response)) return result;
+    if (!result.ok) return mapFailureStatus(result);
+    const parsed = sessionResponseSchema.safeParse(await parseBody(result));
+    return parsed.success
+        ? { kind: "ready", session: parsed.data.session }
+        : { kind: "outdated" };
+}
+
+/**
+ * Ask Screen Time to start a focus session. Only goal, source, duration and
+ * allowed sites go over; the user's saved app and site rules stay in Screen
+ * Time.
+ */
+export async function startFocusSession(
+    {
+        goal,
+        durationSeconds,
+        allowSites,
+    }: {
+        goal: string;
+        durationSeconds: number;
+        allowSites: string[];
+    },
+    options?: { connectionPath?: string },
+): Promise<ScreenTimeStatus> {
+    const result = await callScreenTime(resolvePath(options), "POST", {
+        goal,
+        source: SCREEN_TIME_SOURCE,
+        durationSeconds,
+        allowSites,
+    });
+    if (!(result instanceof Response)) return result;
+    if (result.status === 409) {
+        const parsed = sessionResponseSchema.safeParse(
+            await parseBody(result),
+        );
+        return {
+            kind: "busy",
+            session: parsed.success ? parsed.data.session : null,
+        };
+    }
+    if (!result.ok) return mapFailureStatus(result);
+    const parsed = sessionResponseSchema.safeParse(await parseBody(result));
+    return parsed.success
+        ? { kind: "ready", session: parsed.data.session }
+        : { kind: "outdated" };
+}
+
+/** End Syllo's focus session without touching another source's. */
+export async function stopFocusSession(options?: {
+    connectionPath?: string;
+}): Promise<ScreenTimeStatus> {
+    const result = await callScreenTime(resolvePath(options), "DELETE");
+    if (!(result instanceof Response)) return result;
+    if (!result.ok) return mapFailureStatus(result);
+    const parsed = z
+        .object({ session: z.null() })
+        .safeParse(await parseBody(result));
+    return parsed.success
+        ? { kind: "ready", session: null }
+        : { kind: "outdated" };
+}
+
+/**
+ * Sites Syllo asks Screen Time to keep reachable: the host serving Syllo plus
+ * the lesson's resource hosts. YouTube embeds need youtube.com alongside the
+ * nocookie and short-link hosts.
+ */
+export function allowSitesFor({
+    requestHost,
+    resourceUrls,
+}: {
+    requestHost: string | null;
+    resourceUrls: string[];
+}): string[] {
+    const sites: string[] = [];
+    const push = (hostname: string) => {
+        let host = hostname.toLowerCase();
+        if (host.startsWith("www.")) host = host.slice(4);
+        host = host.replace(/\.+$/, "");
+        if (!host) return;
+        sites.push(host);
+        if (host === "youtu.be" || host.endsWith("youtube-nocookie.com"))
+            sites.push("youtube.com");
+    };
+    if (requestHost) {
+        try {
+            push(new URL(`http://${requestHost}`).hostname);
+        } catch {
+            /* An unreadable Host header contributes nothing. */
+        }
+    }
+    for (const value of resourceUrls) {
+        try {
+            const url = new URL(value);
+            if (url.protocol === "http:" || url.protocol === "https:")
+                push(url.hostname);
+        } catch {
+            /* Skip resource URLs that are not absolute http(s) links. */
+        }
+    }
+    return [...new Set(sites)].slice(0, MAX_ALLOW_SITES);
+}
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index 204e28d..a6fd29d 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -38,6 +38,7 @@ import { Route as ApiScoutResourcesRouteImport } from './routes/api/scout/resour
 import { Route as ApiScoutSettingsRouteImport } from './routes/api/scout/settings'
 import { Route as ApiScoutSourcesRouteImport } from './routes/api/scout/sources'
 import { Route as ApiScoutStartRouteImport } from './routes/api/scout/start'
+import { Route as ApiScreenTimeSessionRouteImport } from './routes/api/screen-time/session'
 import { Route as ApiSrsSaveRouteImport } from './routes/api/srs/save'
 import { Route as ApiScoutPacksIdRouteImport } from './routes/api/scout/packs.$id'
 import { Route as ApiScoutPacksIdApproveRouteImport } from './routes/api/scout/packs.$id.approve'
@@ -185,6 +186,11 @@ const ApiScoutStartRoute = ApiScoutStartRouteImport.update({
   path: '/api/scout/start',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiScreenTimeSessionRoute = ApiScreenTimeSessionRouteImport.update({
+  id: '/api/screen-time/session',
+  path: '/api/screen-time/session',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiSrsSaveRoute = ApiSrsSaveRouteImport.update({
   id: '/api/srs/save',
   path: '/api/srs/save',
@@ -229,6 +235,7 @@ export interface FileRoutesByFullPath {
   '/api/scout/settings': typeof ApiScoutSettingsRoute
   '/api/scout/sources': typeof ApiScoutSourcesRoute
   '/api/scout/start': typeof ApiScoutStartRoute
+  '/api/screen-time/session': typeof ApiScreenTimeSessionRoute
   '/api/srs/save': typeof ApiSrsSaveRoute
   '/api/scout/packs/$id': typeof ApiScoutPacksIdRouteWithChildren
   '/api/scout/packs/$id/approve': typeof ApiScoutPacksIdApproveRoute
@@ -261,6 +268,7 @@ export interface FileRoutesByTo {
   '/api/scout/settings': typeof ApiScoutSettingsRoute
   '/api/scout/sources': typeof ApiScoutSourcesRoute
   '/api/scout/start': typeof ApiScoutStartRoute
+  '/api/screen-time/session': typeof ApiScreenTimeSessionRoute
   '/api/srs/save': typeof ApiSrsSaveRoute
   '/api/scout/packs/$id': typeof ApiScoutPacksIdRouteWithChildren
   '/api/scout/packs/$id/approve': typeof ApiScoutPacksIdApproveRoute
@@ -296,6 +304,7 @@ export interface FileRoutesById {
   '/api/scout/settings': typeof ApiScoutSettingsRoute
   '/api/scout/sources': typeof ApiScoutSourcesRoute
   '/api/scout/start': typeof ApiScoutStartRoute
+  '/api/screen-time/session': typeof ApiScreenTimeSessionRoute
   '/api/srs/save': typeof ApiSrsSaveRoute
   '/api/scout/packs/$id': typeof ApiScoutPacksIdRouteWithChildren
   '/api/scout/packs/$id/approve': typeof ApiScoutPacksIdApproveRoute
@@ -330,6 +339,7 @@ export interface FileRouteTypes {
     | '/api/scout/settings'
     | '/api/scout/sources'
     | '/api/scout/start'
+    | '/api/screen-time/session'
     | '/api/srs/save'
     | '/api/scout/packs/$id'
     | '/api/scout/packs/$id/approve'
@@ -362,6 +372,7 @@ export interface FileRouteTypes {
     | '/api/scout/settings'
     | '/api/scout/sources'
     | '/api/scout/start'
+    | '/api/screen-time/session'
     | '/api/srs/save'
     | '/api/scout/packs/$id'
     | '/api/scout/packs/$id/approve'
@@ -396,6 +407,7 @@ export interface FileRouteTypes {
     | '/api/scout/settings'
     | '/api/scout/sources'
     | '/api/scout/start'
+    | '/api/screen-time/session'
     | '/api/srs/save'
     | '/api/scout/packs/$id'
     | '/api/scout/packs/$id/approve'
@@ -416,6 +428,7 @@ export interface RootRouteChildren {
   ApiScoutSettingsRoute: typeof ApiScoutSettingsRoute
   ApiScoutSourcesRoute: typeof ApiScoutSourcesRoute
   ApiScoutStartRoute: typeof ApiScoutStartRoute
+  ApiScreenTimeSessionRoute: typeof ApiScreenTimeSessionRoute
   ApiSrsSaveRoute: typeof ApiSrsSaveRoute
   ApiScoutPacksIdRoute: typeof ApiScoutPacksIdRouteWithChildren
 }
@@ -625,6 +638,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiScoutStartRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/screen-time/session': {
+      id: '/api/screen-time/session'
+      path: '/api/screen-time/session'
+      fullPath: '/api/screen-time/session'
+      preLoaderRoute: typeof ApiScreenTimeSessionRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/srs/save': {
       id: '/api/srs/save'
       path: '/api/srs/save'
@@ -725,6 +745,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiScoutSettingsRoute: ApiScoutSettingsRoute,
   ApiScoutSourcesRoute: ApiScoutSourcesRoute,
   ApiScoutStartRoute: ApiScoutStartRoute,
+  ApiScreenTimeSessionRoute: ApiScreenTimeSessionRoute,
   ApiSrsSaveRoute: ApiSrsSaveRoute,
   ApiScoutPacksIdRoute: ApiScoutPacksIdRouteWithChildren,
 }
diff --git a/apps/web/src/routes/api/screen-time/session.ts b/apps/web/src/routes/api/screen-time/session.ts
new file mode 100644
index 0000000..d22ad28
--- /dev/null
+++ b/apps/web/src/routes/api/screen-time/session.ts
@@ -0,0 +1,54 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { focusStartRequestSchema } from "@/lib/screen-time/contract";
+import {
+    allowSitesFor,
+    getFocusStatus,
+    startFocusSession,
+    stopFocusSession,
+} from "@/lib/server/screen-time";
+
+/**
+ * Browser-facing proxy for the local Screen Time app. The token stays in the
+ * connection file on this server; only the status union crosses to the
+ * browser. Status kinds are data, not HTTP errors, so they return 200.
+ */
+export const Route = createFileRoute("/api/screen-time/session")({
+    server: {
+        handlers: {
+            GET: async () => Response.json(await getFocusStatus()),
+            POST: async ({ request }) => {
+                let body: unknown;
+                try {
+                    body = await request.json();
+                } catch {
+                    return Response.json(
+                        { success: false, error: "Send a JSON body." },
+                        { status: 400 },
+                    );
+                }
+                const parsed = focusStartRequestSchema.safeParse(body);
+                if (!parsed.success)
+                    return Response.json(
+                        { success: false, error: "Invalid focus session request." },
+                        { status: 400 },
+                    );
+                const requestHost =
+                    request.headers
+                        .get("x-forwarded-host")
+                        ?.split(",")[0]
+                        .trim() ?? request.headers.get("host");
+                return Response.json(
+                    await startFocusSession({
+                        goal: parsed.data.goal,
+                        durationSeconds: parsed.data.durationSeconds,
+                        allowSites: allowSitesFor({
+                            requestHost,
+                            resourceUrls: parsed.data.resourceUrls,
+                        }),
+                    }),
+                );
+            },
+            DELETE: async () => Response.json(await stopFocusSession()),
+        },
+    },
+});
diff --git a/apps/web/src/views/studio/learn.tsx b/apps/web/src/views/studio/learn.tsx
index 972407c..16e34c8 100644
--- a/apps/web/src/views/studio/learn.tsx
+++ b/apps/web/src/views/studio/learn.tsx
@@ -43,7 +43,8 @@ import {
     usePersonalData,
 } from "@/lib/personal/store";
 import StudyVideo from "@/components/learning/StudyVideo";
-import { Pomodoro } from "@/components/learning/Pomodoro";
+import { Pomodoro, useStudyFocus } from "@/components/learning/Pomodoro";
+import type { StudyFocus } from "@/lib/screen-time/client";
 import ReviewComposer from "@/components/learning/ReviewComposer";
 import TermComposer from "@/components/learning/TermComposer";
 import {
@@ -203,6 +204,23 @@ export default function LearnPage({
     const tabId = (key: TabKey) => `${uid}-tab-${key}`;
     const panelId = (key: TabKey) => `${uid}-panel-${key}`;
 
+    // The Pomodoro provider uses this to name the Screen Time session and to
+    // keep the lesson's links reachable while blocking runs.
+    const studyFocus = useMemo<StudyFocus | null>(() => {
+        if (!item) return null;
+        const title = item.task.title || item.task.text;
+        const goal = [title, item.sectionTitle].filter(Boolean).join(" · ");
+        const resourceUrls = [
+            ...item.resources.map((resource) => resource.url),
+            ...(videoResource ? [videoResource.url] : []),
+        ].flatMap((value) => {
+            const safe = safeResourceUrl(value);
+            return safe ? [safe] : [];
+        });
+        return { goal, resourceUrls };
+    }, [item, videoResource]);
+    useStudyFocus(studyFocus);
+
     useEffect(() => {
         if (!activeId || !activeRoadmap) return;
         const stored = getPersonalSnapshot()[`study:${activeRoadmap}:${activeId}`];
diff --git a/apps/web/src/views/studio/personal-settings.tsx b/apps/web/src/views/studio/personal-settings.tsx
index 366c73d..2954574 100644
--- a/apps/web/src/views/studio/personal-settings.tsx
+++ b/apps/web/src/views/studio/personal-settings.tsx
@@ -3,6 +3,7 @@ import { Copy, Download } from "lucide-react";
 import { toast } from "sonner";
 import { z } from "zod";
 import SyncSettings from "@/components/sync/SyncSettings";
+import ScreenTimeSettings from "@/components/learning/ScreenTimeSettings";
 import SettingsSection from "@/components/layout/SettingsSection";
 import {
     getPersonalSnapshot,
@@ -173,6 +174,7 @@ export default function PersonalSettingsPage() {
                 </form>
             </SettingsSection>
             <SyncSettings />
+            <ScreenTimeSettings />
             <SettingsSection
                 title="Your data"
                 description={
diff --git a/docs/syllo-setup.md b/docs/syllo-setup.md
index 209ba52..d2b9361 100644
--- a/docs/syllo-setup.md
+++ b/docs/syllo-setup.md
@@ -63,6 +63,14 @@ Scout reads captions from your machine, caches source text in `.data/syllo.db`,
 
 Scout's flow is goal, source review, draft roadmap, then your explicit approval. Review cards are suggestions until kept. You can add URLs manually without an AI key. Optional creator RSS checks are off on a fresh database; if enabled, they run at 03:00 Asia/Dubai while the local worker runs. They only suggest links and do not rewrite approved roadmaps.
 
+## Screen Time focus link
+
+Syllo can start a focus session in the Screen Time app while a Pomodoro focus period runs. Screen Time then blocks your chosen distracting apps and sites. Pausing, resetting, or ending the period stops the session.
+
+Turn it on in Settings. It is off by default. Syllo tells Screen Time your goal, how long the period runs, and which sites stay open: Syllo itself and the lesson's links. Your app and site rules stay configured in Screen Time.
+
+This works only when Syllo runs on the same computer as Screen Time. A hosted Syllo cannot reach it, and there is no pairing step. The Screen Time token stays in the connection file on Syllo's server and never reaches the browser. The timer keeps working when Screen Time is not installed or not running.
+
 ## Where data lives
 
 | Data | Local storage | Optional cloud |
@@ -73,6 +81,7 @@ Scout's flow is goal, source review, draft roadmap, then your explicit approval.
 | Original workspace before the new bridge | `syllo:workspace-before-personal-v1` | Excluded |
 | Scout drafts, sources, transcripts, jobs | Local `.data/syllo.db` SQLite file | Excluded |
 | AI keys | Browser settings or worker environment | Excluded |
+| Screen Time link setting | `syllo:screen-time-link` in localStorage | Excluded |
 
 Settings exports metadata and the legacy workspace backup. EPUB binaries and API keys are excluded; retain your original books. Restore merges newer metadata by record timestamp. Sync uses the newest revision of each record, including deletion markers; simultaneous edits to the same record do not merge individual fields. Signing out keeps this device's local cache.
 

From 85de0e942ec3262416822628eca602a775b881b3 Mon Sep 17 00:00:00 2001
From: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 14 Nov 2026 00:53:49 +0400
Subject: [PATCH 2/5] fix: tighten screen time link storage and youtube hosts

---
 .../lib/__tests__/screen-time-adapter.test.ts |  9 ++++
 .../__tests__/screen-time-pomodoro.test.tsx   | 42 ++++++++++++++++---
 apps/web/src/lib/screen-time/client.ts        | 22 +++++++---
 apps/web/src/lib/server/screen-time.ts        |  6 ++-
 docs/syllo-setup.md                           |  2 +-
 5 files changed, 67 insertions(+), 14 deletions(-)

diff --git a/apps/web/src/lib/__tests__/screen-time-adapter.test.ts b/apps/web/src/lib/__tests__/screen-time-adapter.test.ts
index e5e386f..2c020de 100644
--- a/apps/web/src/lib/__tests__/screen-time-adapter.test.ts
+++ b/apps/web/src/lib/__tests__/screen-time-adapter.test.ts
@@ -330,6 +330,15 @@ describe("allowSitesFor", () => {
         ).toEqual(["youtu.be", "youtube.com", "youtube-nocookie.com"]);
     });
 
+    it("does not unlock youtube.com for lookalike nocookie hosts", () => {
+        expect(
+            allowSitesFor({
+                requestHost: null,
+                resourceUrls: ["https://evil-youtube-nocookie.com/x"],
+            }),
+        ).toEqual(["evil-youtube-nocookie.com"]);
+    });
+
     it("skips non-http urls and dedupes", () => {
         expect(
             allowSitesFor({
diff --git a/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx b/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
index 86a4674..2add8e4 100644
--- a/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
+++ b/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
@@ -3,10 +3,11 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import PomodoroProvider, { Pomodoro } from "@/components/learning/Pomodoro";
+import { useScreenTimeLink } from "@/lib/screen-time/client";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
-const LINK_KEY = "syllo:screen-time-link";
+const LINK_KEY = "syllo:screen-time-link:v1";
 const SESSION_KEY = "syllo:pomodoro-session";
 
 interface FetchCall {
@@ -19,7 +20,13 @@ let calls: FetchCall[];
 let container: HTMLDivElement;
 let root: Root;
 
-beforeEach(() => {
+/** Subscribes to the link store so a storage event can reset its cache. */
+function LinkProbe() {
+    useScreenTimeLink();
+    return null;
+}
+
+beforeEach(async () => {
     localStorage.clear();
     calls = [];
     vi.stubGlobal(
@@ -53,6 +60,16 @@ beforeEach(() => {
     container = document.createElement("div");
     document.body.appendChild(container);
     root = createRoot(container);
+    // The link flag is cached in the module; a storage event clears the cache
+    // while the probe keeps a subscription alive.
+    await act(async () => {
+        root.render(<LinkProbe />);
+    });
+    await act(async () => {
+        window.dispatchEvent(
+            new StorageEvent("storage", { key: LINK_KEY }),
+        );
+    });
 });
 
 afterEach(async () => {
@@ -73,6 +90,19 @@ async function render() {
     });
 }
 
+/**
+ * Turn the link on the way another tab would: write the key, then notify
+ * listeners through a storage event so the module cache picks it up.
+ */
+async function linkOn() {
+    localStorage.setItem(LINK_KEY, "on");
+    await act(async () => {
+        window.dispatchEvent(
+            new StorageEvent("storage", { key: LINK_KEY }),
+        );
+    });
+}
+
 async function click(text: string) {
     const button = Array.from(container.querySelectorAll("button")).find(
         (el) => el.textContent === text,
@@ -89,7 +119,7 @@ function storeSession(session: Record<string, unknown>) {
 
 describe("pomodoro screen time link", () => {
     it("posts a session for the full focus period on Start", async () => {
-        localStorage.setItem(LINK_KEY, "on");
+        await linkOn();
         await render();
         await click("Start");
         const post = calls.find((call) => call.method === "POST");
@@ -105,7 +135,7 @@ describe("pomodoro screen time link", () => {
     });
 
     it("deletes the session on Pause", async () => {
-        localStorage.setItem(LINK_KEY, "on");
+        await linkOn();
         await render();
         await click("Start");
         await click("Pause");
@@ -114,7 +144,7 @@ describe("pomodoro screen time link", () => {
     });
 
     it("reposts the remaining time for a stored running focus", async () => {
-        localStorage.setItem(LINK_KEY, "on");
+        await linkOn();
         storeSession({
             mode: "focus",
             remaining: 300,
@@ -129,7 +159,7 @@ describe("pomodoro screen time link", () => {
     });
 
     it("sends a stop for a stored idle timer so nothing keeps blocking", async () => {
-        localStorage.setItem(LINK_KEY, "on");
+        await linkOn();
         storeSession({ mode: "focus", remaining: 1500, endAt: null });
         await render();
         expect(calls).toHaveLength(1);
diff --git a/apps/web/src/lib/screen-time/client.ts b/apps/web/src/lib/screen-time/client.ts
index 3170e4e..69259bc 100644
--- a/apps/web/src/lib/screen-time/client.ts
+++ b/apps/web/src/lib/screen-time/client.ts
@@ -7,7 +7,7 @@ import {
 } from "./contract";
 
 const PATH = "/api/screen-time/session";
-const LINK_KEY = "syllo:screen-time-link";
+const LINK_KEY = "syllo:screen-time-link:v1";
 const REQUEST_TIMEOUT_MS = 5000;
 
 async function callApi(init: RequestInit): Promise<ScreenTimeStatus> {
@@ -40,19 +40,28 @@ export const screenTimeApi = {
 };
 
 const listeners = new Set<() => void>();
+// localStorage reads show up on every timer tick through the snapshot, so the
+// value is cached in memory and only re-read after a real change.
+let cached: boolean | null = null;
 
 function readLinked(): boolean {
-    try {
-        return localStorage.getItem(LINK_KEY) === "on";
-    } catch {
-        return false;
+    if (cached === null) {
+        try {
+            cached = localStorage.getItem(LINK_KEY) === "on";
+        } catch {
+            cached = false;
+        }
     }
+    return cached;
 }
 
 function subscribe(listener: () => void): () => void {
     listeners.add(listener);
     const onStorage = (event: StorageEvent) => {
-        if (event.key === null || event.key === LINK_KEY) listener();
+        if (event.key === null || event.key === LINK_KEY) {
+            cached = null;
+            listener();
+        }
     };
     window.addEventListener("storage", onStorage);
     return () => {
@@ -78,6 +87,7 @@ export function useScreenTimeLink(): readonly [
         } catch {
             /* Storage may be blocked; the toggle just stays off. */
         }
+        cached = on;
         for (const listener of listeners) listener();
     };
     return [linked, setLinked] as const;
diff --git a/apps/web/src/lib/server/screen-time.ts b/apps/web/src/lib/server/screen-time.ts
index a8d4a2c..8ea47ef 100644
--- a/apps/web/src/lib/server/screen-time.ts
+++ b/apps/web/src/lib/server/screen-time.ts
@@ -266,7 +266,11 @@ export function allowSitesFor({
         host = host.replace(/\.+$/, "");
         if (!host) return;
         sites.push(host);
-        if (host === "youtu.be" || host.endsWith("youtube-nocookie.com"))
+        if (
+            host === "youtu.be" ||
+            host === "youtube-nocookie.com" ||
+            host.endsWith(".youtube-nocookie.com")
+        )
             sites.push("youtube.com");
     };
     if (requestHost) {
diff --git a/docs/syllo-setup.md b/docs/syllo-setup.md
index d2b9361..1e42810 100644
--- a/docs/syllo-setup.md
+++ b/docs/syllo-setup.md
@@ -81,7 +81,7 @@ This works only when Syllo runs on the same computer as Screen Time. A hosted Sy
 | Original workspace before the new bridge | `syllo:workspace-before-personal-v1` | Excluded |
 | Scout drafts, sources, transcripts, jobs | Local `.data/syllo.db` SQLite file | Excluded |
 | AI keys | Browser settings or worker environment | Excluded |
-| Screen Time link setting | `syllo:screen-time-link` in localStorage | Excluded |
+| Screen Time link setting | `syllo:screen-time-link:v1` in localStorage | Excluded |
 
 Settings exports metadata and the legacy workspace backup. EPUB binaries and API keys are excluded; retain your original books. Restore merges newer metadata by record timestamp. Sync uses the newest revision of each record, including deletion markers; simultaneous edits to the same record do not merge individual fields. Signing out keeps this device's local cache.
 

From 2d108a648c894865a279d57b94b835ca3afc12f3 Mon Sep 17 00:00:00 2001
From: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 14 Nov 2026 00:54:09 +0400
Subject: [PATCH 3/5] docs: correct the blocked-storage comment on the link
 toggle

---
 apps/web/src/lib/screen-time/client.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/src/lib/screen-time/client.ts b/apps/web/src/lib/screen-time/client.ts
index 69259bc..a1c2602 100644
--- a/apps/web/src/lib/screen-time/client.ts
+++ b/apps/web/src/lib/screen-time/client.ts
@@ -85,7 +85,7 @@ export function useScreenTimeLink(): readonly [
             if (on) localStorage.setItem(LINK_KEY, "on");
             else localStorage.removeItem(LINK_KEY);
         } catch {
-            /* Storage may be blocked; the toggle just stays off. */
+            /* Storage may be blocked; the choice then holds for this visit. */
         }
         cached = on;
         for (const listener of listeners) listener();

From 2d9c902e3cb29c07bd93c670cb8cf55fa6662dcc Mon Sep 17 00:00:00 2001
From: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 14 Nov 2026 01:54:00 +0400
Subject: [PATCH 4/5] fix: notice when screen time ends a focus session

---
 apps/web/src/components/learning/Pomodoro.tsx |  46 ++++++-
 .../lib/__tests__/screen-time-link.test.ts    |  28 +++++
 .../__tests__/screen-time-pomodoro.test.tsx   | 117 ++++++++++++++++--
 apps/web/src/lib/screen-time/client.ts        |  28 ++++-
 4 files changed, 208 insertions(+), 11 deletions(-)

diff --git a/apps/web/src/components/learning/Pomodoro.tsx b/apps/web/src/components/learning/Pomodoro.tsx
index 64a8852..cdecbf8 100644
--- a/apps/web/src/components/learning/Pomodoro.tsx
+++ b/apps/web/src/components/learning/Pomodoro.tsx
@@ -83,6 +83,7 @@ export default function PomodoroProvider({
     const [study, setStudy] = useState<StudyFocus | null>(null);
     const [linked] = useScreenTimeLink();
     const [linkStatus, setLinkStatus] = useState<ScreenTimeStatus | null>(null);
+    const [tracking, setTracking] = useState(false);
     const sessionRef = useRef(session);
     sessionRef.current = session;
     const syncRef = useRef<ReturnType<typeof createFocusSync> | null>(null);
@@ -96,7 +97,13 @@ export default function PomodoroProvider({
                           resourceUrls: intent.resourceUrls,
                       })
                     : screenTimeApi.stop(),
-            onStatus: setLinkStatus,
+            onStatus: (status) => {
+                setLinkStatus(status);
+                setTracking(
+                    status.kind === "ready" &&
+                        status.session?.source === SCREEN_TIME_SOURCE,
+                );
+            },
         });
     useEffect(() => {
         try {
@@ -194,8 +201,45 @@ export default function PomodoroProvider({
         else {
             sync.release();
             setLinkStatus(null);
+            setTracking(false);
         }
     }, [loaded, linked, intent]);
+    const runningFocus = session.mode === "focus" && session.endAt !== null;
+    // While our session is believed on, watch for the user ending it in Screen
+    // Time so the label drops instead of claiming a block that is not there.
+    useEffect(() => {
+        if (!linked || !runningFocus || !tracking) return;
+        const sync = syncRef.current;
+        if (!sync) return;
+        let cancelled = false;
+        const poll = async () => {
+            const before = sync.version();
+            const result = await screenTimeApi.status();
+            if (cancelled || sync.version() !== before) return;
+            if (
+                result.kind === "ready" &&
+                result.session?.source === SCREEN_TIME_SOURCE
+            ) {
+                setLinkStatus(result);
+            } else if (result.kind === "ready") {
+                sync.markEnded();
+                setTracking(false);
+                setLinkStatus(result);
+            } else {
+                setLinkStatus(result);
+            }
+        };
+        const timer = setInterval(() => void poll(), 20_000);
+        const onVisible = () => {
+            if (document.visibilityState === "visible") void poll();
+        };
+        document.addEventListener("visibilitychange", onVisible);
+        return () => {
+            cancelled = true;
+            clearInterval(timer);
+            document.removeEventListener("visibilitychange", onVisible);
+        };
+    }, [linked, runningFocus, tracking]);
     return (
         <StudyFocusContext.Provider value={setStudy}>
             <Context.Provider
diff --git a/apps/web/src/lib/__tests__/screen-time-link.test.ts b/apps/web/src/lib/__tests__/screen-time-link.test.ts
index 5289f36..5d9a036 100644
--- a/apps/web/src/lib/__tests__/screen-time-link.test.ts
+++ b/apps/web/src/lib/__tests__/screen-time-link.test.ts
@@ -199,4 +199,32 @@ describe("createFocusSync", () => {
         await new Promise((done) => setTimeout(done, 0));
         expect(sent).toEqual([{ kind: "stop" }]);
     });
+
+    it("never re-sends a period the user ended in screen time", async () => {
+        const { sent, statuses, sync } = makeSync();
+        const start = (goal: string, endAt: number): FocusIntent => ({
+            kind: "start",
+            goal,
+            resourceUrls: [],
+            endAt,
+        });
+        sync.update(start("g", 60_000));
+        await vi.waitFor(() => expect(statuses).toHaveLength(1));
+        sync.markEnded();
+        sync.update(start("renamed", 60_000));
+        await new Promise((done) => setTimeout(done, 0));
+        expect(sent).toHaveLength(1);
+        sync.update(start("g", 90_000));
+        await vi.waitFor(() => expect(sent).toHaveLength(2));
+    });
+
+    it("bumps its version for each dispatch", async () => {
+        const { statuses, sync } = makeSync();
+        expect(sync.version()).toBe(0);
+        sync.update({ kind: "stop" });
+        expect(sync.version()).toBe(1);
+        await vi.waitFor(() => expect(statuses).toHaveLength(1));
+        sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 60_000 });
+        expect(sync.version()).toBe(2);
+    });
 });
diff --git a/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx b/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
index 2add8e4..a3d85f8 100644
--- a/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
+++ b/apps/web/src/lib/__tests__/screen-time-pomodoro.test.tsx
@@ -2,13 +2,30 @@
 import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import PomodoroProvider, { Pomodoro } from "@/components/learning/Pomodoro";
-import { useScreenTimeLink } from "@/lib/screen-time/client";
+import PomodoroProvider, {
+    Pomodoro,
+    useStudyFocus,
+} from "@/components/learning/Pomodoro";
+import {
+    useScreenTimeLink,
+    type StudyFocus,
+} from "@/lib/screen-time/client";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
 const LINK_KEY = "syllo:screen-time-link:v1";
 const SESSION_KEY = "syllo:pomodoro-session";
+const SYLLO_SESSION = {
+    id: "s1",
+    goal: "Study session",
+    source: "syllo",
+    mode: "block",
+    apps: [],
+    sites: [],
+    allowSites: [],
+    startedAt: "2026-01-01T00:00:00.000Z",
+    endsAt: "2026-01-01T00:25:00.000Z",
+};
 
 interface FetchCall {
     method: string;
@@ -17,6 +34,7 @@ interface FetchCall {
 }
 
 let calls: FetchCall[];
+let reply: unknown;
 let container: HTMLDivElement;
 let root: Root;
 
@@ -26,9 +44,16 @@ function LinkProbe() {
     return null;
 }
 
+/** Reports a lesson focus to the provider like the Learn page does. */
+function StudyProbe({ focus }: { focus: StudyFocus | null }) {
+    useStudyFocus(focus);
+    return null;
+}
+
 beforeEach(async () => {
     localStorage.clear();
     calls = [];
+    reply = { kind: "ready", session: null };
     vi.stubGlobal(
         "fetch",
         vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
@@ -47,13 +72,10 @@ beforeEach(async () => {
                 body,
             });
             return Promise.resolve(
-                new Response(
-                    JSON.stringify({ kind: "ready", session: null }),
-                    {
-                        status: 200,
-                        headers: { "Content-Type": "application/json" },
-                    },
-                ),
+                new Response(JSON.stringify(reply), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }),
             );
         }),
     );
@@ -77,6 +99,7 @@ afterEach(async () => {
         root.unmount();
     });
     container.remove();
+    vi.useRealTimers();
     vi.unstubAllGlobals();
 });
 
@@ -171,4 +194,80 @@ describe("pomodoro screen time link", () => {
         await click("Start");
         expect(calls).toHaveLength(0);
     });
+
+    it("drops the label when the session is ended in screen time", async () => {
+        vi.useFakeTimers();
+        await linkOn();
+        reply = { kind: "ready", session: SYLLO_SESSION };
+        await act(async () => {
+            root.render(
+                <PomodoroProvider>
+                    <StudyProbe focus={{ goal: "One", resourceUrls: [] }} />
+                    <Pomodoro />
+                </PomodoroProvider>,
+            );
+        });
+        await click("Start");
+        expect(container.textContent).toContain("Screen Time");
+        reply = { kind: "ready", session: null };
+        await act(async () => {
+            vi.advanceTimersByTime(20_000);
+        });
+        expect(container.textContent).not.toContain("Screen Time");
+        expect(container.textContent).toContain("Pause");
+        await act(async () => {
+            vi.advanceTimersByTime(20_000);
+        });
+        await act(async () => {
+            root.render(
+                <PomodoroProvider>
+                    <StudyProbe focus={{ goal: "Two", resourceUrls: [] }} />
+                    <Pomodoro />
+                </PomodoroProvider>,
+            );
+        });
+        expect(calls.filter((call) => call.method === "POST")).toHaveLength(1);
+        expect(calls.filter((call) => call.method === "GET")).toHaveLength(1);
+    });
+
+    it("checks again when the tab becomes visible", async () => {
+        vi.useFakeTimers();
+        await linkOn();
+        reply = { kind: "ready", session: SYLLO_SESSION };
+        await render();
+        await click("Start");
+        const before = calls.filter(
+            (call) => call.method === "GET",
+        ).length;
+        await act(async () => {
+            document.dispatchEvent(new Event("visibilitychange"));
+        });
+        expect(
+            calls.filter((call) => call.method === "GET").length,
+        ).toBe(before + 1);
+    });
+
+    it("stays silent when the link is off, even as time passes", async () => {
+        vi.useFakeTimers();
+        await render();
+        await click("Start");
+        await act(async () => {
+            vi.advanceTimersByTime(60_000);
+        });
+        expect(calls).toHaveLength(0);
+    });
+
+    it("does not poll when the start was declined", async () => {
+        vi.useFakeTimers();
+        await linkOn();
+        reply = { kind: "busy", session: null };
+        await render();
+        await click("Start");
+        await act(async () => {
+            vi.advanceTimersByTime(60_000);
+        });
+        expect(
+            calls.filter((call) => call.method === "GET"),
+        ).toHaveLength(0);
+    });
 });
diff --git a/apps/web/src/lib/screen-time/client.ts b/apps/web/src/lib/screen-time/client.ts
index a1c2602..adf5553 100644
--- a/apps/web/src/lib/screen-time/client.ts
+++ b/apps/web/src/lib/screen-time/client.ts
@@ -156,6 +156,9 @@ export function createFocusSync({
     let inFlight = false;
     let pending: FocusIntent | null = null;
     let lastSentStart = false;
+    let lastStartEndAt: number | null = null;
+    let endedAt: number | null = null;
+    let dispatches = 0;
 
     function dispatch(intent: FocusIntent): void {
         let outgoing: SendIntent;
@@ -173,6 +176,9 @@ export function createFocusSync({
                           durationSeconds,
                       };
         }
+        if (intent.kind === "start" && outgoing.kind === "start")
+            lastStartEndAt = intent.endAt;
+        dispatches += 1;
         inFlight = true;
         lastSentStart = outgoing.kind === "start";
         send(outgoing)
@@ -188,6 +194,15 @@ export function createFocusSync({
 
     function update(intent: FocusIntent): void {
         const key = intentKey(intent);
+        if (endedAt !== null) {
+            // The user ended this session in Screen Time; a start for the
+            // same period is remembered but never re-sent.
+            if (intent.kind === "start" && intent.endAt === endedAt) {
+                lastKey = key;
+                return;
+            }
+            endedAt = null;
+        }
         if (inFlight) {
             // Whatever is queued loses to the newest intent, including "the
             // same as what is already being sent".
@@ -199,12 +214,23 @@ export function createFocusSync({
         dispatch(intent);
     }
 
+    /** How many requests went out; callers discard poll results from before. */
+    function version(): number {
+        return dispatches;
+    }
+
+    /** Stop re-sending the current period after Screen Time ended it. */
+    function markEnded(): void {
+        endedAt = lastStartEndAt;
+    }
+
     function release(): void {
         pending = null;
+        endedAt = null;
         if (lastSentStart) update({ kind: "stop" });
         lastKey = null;
         lastSentStart = false;
     }
 
-    return { update, release };
+    return { update, release, markEnded, version };
 }

From 0603231c0260f052d3f6f08bae8b7e4ffed0d1c3 Mon Sep 17 00:00:00 2001
From: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 14 Nov 2026 01:54:42 +0400
Subject: [PATCH 5/5] fix: match screen time goal and duration limits

---
 .../lib/__tests__/screen-time-adapter.test.ts | 49 ++++++++++++++
 .../lib/__tests__/screen-time-link.test.ts    | 66 ++++++++++++++++++-
 apps/web/src/lib/screen-time/client.ts        | 31 ++++++---
 apps/web/src/lib/screen-time/contract.ts      | 24 ++++++-
 apps/web/src/lib/server/screen-time.ts        | 20 +++++-
 docs/syllo-setup.md                           |  2 +-
 6 files changed, 177 insertions(+), 15 deletions(-)

diff --git a/apps/web/src/lib/__tests__/screen-time-adapter.test.ts b/apps/web/src/lib/__tests__/screen-time-adapter.test.ts
index 2c020de..0d1494e 100644
--- a/apps/web/src/lib/__tests__/screen-time-adapter.test.ts
+++ b/apps/web/src/lib/__tests__/screen-time-adapter.test.ts
@@ -3,6 +3,7 @@ import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { z } from "zod";
 import {
     allowSitesFor,
     connectionFilePath,
@@ -150,6 +151,54 @@ describe("screen time http adapter", () => {
         expect(requests[0].url).toBe("/api/v1/focus/session?source=syllo");
     });
 
+    it("trims a long goal to the screen time limit", async () => {
+        await writeConnection();
+        const separated = `${"A".repeat(150)} · ${"B".repeat(150)}`;
+        await startFocusSession(
+            { goal: separated, durationSeconds: 60, allowSites: [] },
+            { connectionPath },
+        );
+        const sent = z
+            .object({ goal: z.string() })
+            .parse(requests[0].body).goal;
+        expect(sent).toBe(`${"A".repeat(150)}…`);
+        expect(sent.length).toBeLessThanOrEqual(200);
+        await startFocusSession(
+            { goal: "x".repeat(250), durationSeconds: 60, allowSites: [] },
+            { connectionPath },
+        );
+        const hard = z
+            .object({ goal: z.string() })
+            .parse(requests[1].body).goal;
+        expect(hard).toHaveLength(200);
+        expect(hard.endsWith("…")).toBe(true);
+    });
+
+    it("falls back for a blank goal and clamps a long duration", async () => {
+        await writeConnection();
+        await startFocusSession(
+            { goal: "   ", durationSeconds: 50_000, allowSites: [] },
+            { connectionPath },
+        );
+        expect(requests[0].body).toMatchObject({
+            goal: "Study session",
+            durationSeconds: 43_200,
+        });
+    });
+
+    it("maps a delete 409 to the session that is actually running", async () => {
+        await writeConnection();
+        const other = { ...SESSION, source: "other-app" };
+        responder = () => ({ status: 409, payload: { session: other } });
+        await expect(
+            stopFocusSession({ connectionPath }),
+        ).resolves.toEqual({ kind: "ready", session: other });
+        responder = () => ({ status: 409, payload: { junk: true } });
+        await expect(
+            stopFocusSession({ connectionPath }),
+        ).resolves.toEqual({ kind: "ready", session: null });
+    });
+
     it("maps a 409 to busy with the other session", async () => {
         await writeConnection();
         const other = { ...SESSION, source: "other-app" };
diff --git a/apps/web/src/lib/__tests__/screen-time-link.test.ts b/apps/web/src/lib/__tests__/screen-time-link.test.ts
index 5d9a036..483f417 100644
--- a/apps/web/src/lib/__tests__/screen-time-link.test.ts
+++ b/apps/web/src/lib/__tests__/screen-time-link.test.ts
@@ -4,7 +4,11 @@ import {
     focusIntent,
     type FocusIntent,
 } from "@/lib/screen-time/client";
-import type { ScreenTimeStatus } from "@/lib/screen-time/contract";
+import {
+    focusGoal,
+    focusStartRequestSchema,
+    type ScreenTimeStatus,
+} from "@/lib/screen-time/contract";
 
 type SendIntent =
     | { kind: "stop" }
@@ -227,4 +231,64 @@ describe("createFocusSync", () => {
         sync.update({ kind: "start", goal: "g", resourceUrls: [], endAt: 60_000 });
         expect(sync.version()).toBe(2);
     });
+
+    it("skips a start with under a minute left", async () => {
+        const { sent, sync } = makeSync(() => 40_000);
+        sync.update({
+            kind: "start",
+            goal: "g",
+            resourceUrls: [],
+            endAt: 70_000,
+        });
+        await new Promise((done) => setTimeout(done, 0));
+        expect(sent).toHaveLength(0);
+        expect(sync.version()).toBe(0);
+    });
+
+    it("clamps the duration to the screen time maximum", () => {
+        const { sent, sync } = makeSync(() => 0);
+        sync.update({
+            kind: "start",
+            goal: "g",
+            resourceUrls: [],
+            endAt: 50_000_000,
+        });
+        expect(sent[0]).toMatchObject({
+            kind: "start",
+            durationSeconds: 43_200,
+        });
+    });
+});
+
+describe("focusGoal", () => {
+    it("collapses whitespace and falls back when blank", () => {
+        expect(focusGoal("   ")).toBe("Study session");
+        expect(focusGoal("  Kern   ing \n basics ")).toBe("Kern ing basics");
+    });
+
+    it("cuts long goals at a word boundary and marks them", () => {
+        const separated = `${"A".repeat(150)} · ${"B".repeat(150)}`;
+        expect(focusGoal(separated)).toBe(`${"A".repeat(150)}…`);
+        const solid = focusGoal("x".repeat(250));
+        expect(solid).toHaveLength(200);
+        expect(solid.endsWith("…")).toBe(true);
+        expect(focusGoal("short")).toBe("short");
+    });
+
+    it("rejects a requested duration under a minute", () => {
+        expect(
+            focusStartRequestSchema.safeParse({
+                goal: "g",
+                durationSeconds: 30,
+                resourceUrls: [],
+            }).success,
+        ).toBe(false);
+        expect(
+            focusStartRequestSchema.safeParse({
+                goal: "g",
+                durationSeconds: 60,
+                resourceUrls: [],
+            }).success,
+        ).toBe(true);
+    });
 });
diff --git a/apps/web/src/lib/screen-time/client.ts b/apps/web/src/lib/screen-time/client.ts
index adf5553..04793f2 100644
--- a/apps/web/src/lib/screen-time/client.ts
+++ b/apps/web/src/lib/screen-time/client.ts
@@ -1,6 +1,9 @@
 import { useSyncExternalStore } from "react";
 import { fetchPrivateApi } from "@/lib/private-api-fetch";
 import {
+    focusGoal,
+    MAX_FOCUS_SECONDS,
+    MIN_FOCUS_SECONDS,
     screenTimeStatusSchema,
     type FocusStartRequest,
     type ScreenTimeStatus,
@@ -112,7 +115,7 @@ export function focusIntent(
     if (session.mode === "focus" && session.endAt !== null)
         return {
             kind: "start",
-            goal: (study?.goal.trim() || "Study session").slice(0, 200),
+            goal: focusGoal(study?.goal ?? ""),
             resourceUrls: study?.resourceUrls ?? [],
             endAt: session.endAt,
         };
@@ -166,15 +169,23 @@ export function createFocusSync({
             outgoing = { kind: "stop" };
         } else {
             const durationSeconds = Math.ceil((intent.endAt - now()) / 1000);
-            outgoing =
-                durationSeconds <= 0
-                    ? { kind: "stop" }
-                    : {
-                          kind: "start",
-                          goal: intent.goal,
-                          resourceUrls: intent.resourceUrls,
-                          durationSeconds,
-                      };
+            if (durationSeconds <= 0) {
+                outgoing = { kind: "stop" };
+            } else if (durationSeconds < MIN_FOCUS_SECONDS) {
+                // Under a minute left: Screen Time would refuse anyway, so
+                // stay quiet instead of sending a doomed start.
+                return;
+            } else {
+                outgoing = {
+                    kind: "start",
+                    goal: intent.goal,
+                    resourceUrls: intent.resourceUrls,
+                    durationSeconds: Math.min(
+                        durationSeconds,
+                        MAX_FOCUS_SECONDS,
+                    ),
+                };
+            }
         }
         if (intent.kind === "start" && outgoing.kind === "start")
             lastStartEndAt = intent.endAt;
diff --git a/apps/web/src/lib/screen-time/contract.ts b/apps/web/src/lib/screen-time/contract.ts
index db29244..097fe92 100644
--- a/apps/web/src/lib/screen-time/contract.ts
+++ b/apps/web/src/lib/screen-time/contract.ts
@@ -41,14 +41,36 @@ export const screenTimeStatusSchema = z.discriminatedUnion("kind", [
 ]);
 export type ScreenTimeStatus = z.infer<typeof screenTimeStatusSchema>;
 
+export const MIN_FOCUS_SECONDS = 60;
+export const MAX_FOCUS_SECONDS = 43_200;
+
 /** Body the browser sends when a focus period should start a session. */
 export const focusStartRequestSchema = z.object({
     goal: z.string().trim().min(1).max(200),
-    durationSeconds: z.number().int().min(1).max(14400),
+    durationSeconds: z
+        .number()
+        .int()
+        .min(MIN_FOCUS_SECONDS)
+        .max(MAX_FOCUS_SECONDS),
     resourceUrls: z.array(z.string().max(2048)).max(100),
 });
 export type FocusStartRequest = z.infer<typeof focusStartRequestSchema>;
 
+/**
+ * The goal shown in Screen Time. Blank lessons fall back to a generic label;
+ * long goals are cut on a word boundary so the result always fits 200 chars.
+ */
+export function focusGoal(raw: string): string {
+    const goal = raw.trim().replace(/\s+/g, " ");
+    if (!goal) return "Study session";
+    if (goal.length <= 200) return goal;
+    const lastSpace = goal.lastIndexOf(" ", 199);
+    const cut = goal
+        .slice(0, lastSpace >= 120 ? lastSpace : 199)
+        .replace(/[\s·]+$/u, "");
+    return `${cut}…`;
+}
+
 /** One line of user-facing copy for each Screen Time status. */
 export function screenTimeMessage(status: ScreenTimeStatus | null): string {
     if (status === null) return "Checking for Screen Time…";
diff --git a/apps/web/src/lib/server/screen-time.ts b/apps/web/src/lib/server/screen-time.ts
index 8ea47ef..a41906d 100644
--- a/apps/web/src/lib/server/screen-time.ts
+++ b/apps/web/src/lib/server/screen-time.ts
@@ -3,7 +3,10 @@ import os from "node:os";
 import path from "node:path";
 import { z } from "zod";
 import {
+    focusGoal,
     focusSessionSchema,
+    MAX_FOCUS_SECONDS,
+    MIN_FOCUS_SECONDS,
     SCREEN_TIME_SOURCE,
     type ScreenTimeStatus,
 } from "@/lib/screen-time/contract";
@@ -210,9 +213,12 @@ export async function startFocusSession(
     options?: { connectionPath?: string },
 ): Promise<ScreenTimeStatus> {
     const result = await callScreenTime(resolvePath(options), "POST", {
-        goal,
+        goal: focusGoal(goal),
         source: SCREEN_TIME_SOURCE,
-        durationSeconds,
+        durationSeconds: Math.min(
+            MAX_FOCUS_SECONDS,
+            Math.max(MIN_FOCUS_SECONDS, durationSeconds),
+        ),
         allowSites,
     });
     if (!(result instanceof Response)) return result;
@@ -238,6 +244,16 @@ export async function stopFocusSession(options?: {
 }): Promise<ScreenTimeStatus> {
     const result = await callScreenTime(resolvePath(options), "DELETE");
     if (!(result instanceof Response)) return result;
+    if (result.status === 409) {
+        // Not our session to stop: report whatever is running instead.
+        const parsed = sessionResponseSchema.safeParse(
+            await parseBody(result),
+        );
+        return {
+            kind: "ready",
+            session: parsed.success ? parsed.data.session : null,
+        };
+    }
     if (!result.ok) return mapFailureStatus(result);
     const parsed = z
         .object({ session: z.null() })
diff --git a/docs/syllo-setup.md b/docs/syllo-setup.md
index 1e42810..87261b8 100644
--- a/docs/syllo-setup.md
+++ b/docs/syllo-setup.md
@@ -67,7 +67,7 @@ Scout's flow is goal, source review, draft roadmap, then your explicit approval.
 
 Syllo can start a focus session in the Screen Time app while a Pomodoro focus period runs. Screen Time then blocks your chosen distracting apps and sites. Pausing, resetting, or ending the period stops the session.
 
-Turn it on in Settings. It is off by default. Syllo tells Screen Time your goal, how long the period runs, and which sites stay open: Syllo itself and the lesson's links. Your app and site rules stay configured in Screen Time.
+Turn it on in Settings. It is off by default. Syllo tells Screen Time your goal, how long the period runs, and which sites stay open: Syllo itself and the lesson's links. Your app and site rules stay configured in Screen Time. A focus period with under a minute left does not start a session. Ending the session in Screen Time leaves the Syllo timer running.
 
 This works only when Syllo runs on the same computer as Screen Time. A hosted Syllo cannot reach it, and there is no pairing step. The Screen Time token stays in the connection file on Syllo's server and never reaches the browser. The timer keeps working when Screen Time is not installed or not running.