pushframe 5.0.7__tar.gz → 5.1.0__tar.gz

{pushframe-5.0.7 → pushframe-5.1.0}/.planning/STATE.md

@@ -5,16 +5,16 @@
 
 ## Current Position
 
-Phase: 24 — VERIFIED (passed)
-Current Plan: 24-01 complete
-Total Plans in Phase: 1 (phase 24)
-Status: Verified — next: phase 25 (Multi-frame + systemd)
+Phase: 25 — VERIFIED (passed)
+Current Plan: 25-01 complete
+Total Plans in Phase: 1 (phase 25)
+Status: Verified — v5.1 phases 23-25 complete
 
 ## Milestone Roadmap (v5.1, Phases 23-25)
 
 - [x] Phase 23 — Config Wizard & Precedence (CFG-01..04)
 - [x] Phase 24 — Token-First Sessions & Preflight Sweep (SEC-01..03, PRF-01..02)
-- [ ] Phase 25 — Multi-frame Mappings & systemd User Scheduling (MTF-01..03, TMR-01..03)
+- [x] Phase 25 — Multi-frame Mappings & systemd User Scheduling (MTF-01..03, TMR-01..03)
 
 ## Completed Milestones
 

pushframe-5.1.0/.planning/phases/25-multi-frame-mappings-systemd-user-scheduling-mtf-01-03-tmr-01-03/25-01-PLAN.md

@@ -0,0 +1,73 @@
+---
+phase: 25-multi-frame-mappings-systemd-user-scheduling-mtf-01-03-tmr-01-03
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - pushframe/pairs.py
+  - pushframe/gsync.py
+  - pushframe/schedule.py
+  - pushframe/cli.py
+  - pushframe/config_store.py
+  - tests/test_pairs.py
+  - tests/test_gsync_all.py
+  - tests/test_schedule.py
+  - tests/test_preflight_sweep.py
+  - scripts/test-multipair-journey-container.sh
+  - scripts/test-schedule-journey-container.sh
+  - docs/CLI.md
+  - README.md
+  - CHANGELOG.md
+autonomous: true
+requirements: [MTF-01, MTF-02, MTF-03, TMR-01, TMR-02, TMR-03]
+
+estimate:
+  tokens: 70000
+  raw_tokens: 56000
+  tasks: 4
+  confidence: medium-high
+
+must_haves:
+  truths:
+    - "pairs live as a named dict in config.json pairs key; config pair add/remove/list manage them; duplicate name = named error"
+    - "google-sync --pair <name> resolves album+frame from the pair and shards manifest/cache under per-pair paths; --all runs every pair in dict order"
+    - "--all shares ONE budget instance across pairs; a failing pair is reported and the rest still run; exit 1 if any failed, 0 only if all OK"
+    - "schedule add/list/remove round-trip user units pushframe-<job>.service/.timer; ExecStart is fully non-interactive; Restart=no; per-job log at ~/.local/state/pushframe/<job>.log"
+    - "a scheduled threshold breach SKIPS AND LOGS (never fails the unit, never proceeds silently); --scheduled flag gates the flip"
+    - "schedule preflight names the systemd user-session requirement with the loginctl enable-linger remedy (documented, never executed)"
+    - "the roadmap container journeys pass: two pairs one --all run (per-pair state, shared budget, exact reports) and schedule add/list/remove round-trip"
+  artifacts:
+    - path: pushframe/pairs.py
+      provides: pair store helpers (add/remove/list/resolve) over config_store pairs
+    - path: pushframe/schedule.py
+      provides: pure unit renderers + systemctl wrappers + preflight
+
+sequential_tasks:
+  - id: "Task 1: pairs store + config pair subcommands + CLI --pair/--all (MTF-01)"
+    files: [pushframe/pairs.py, pushframe/cli.py, pushframe/config_store.py]
+    tests: [tests/test_pairs.py]
+    done_when:
+      - "add/remove/list round-trip the named dict; duplicate = named error"
+      - "--pair resolves and --all iterates; unknown pair = named error listing names"
+  - id: "Task 2: per-pair state + the --all runner (MTF-02/03, D-02)"
+    files: [pushframe/gsync.py]
+    tests: [tests/test_gsync_all.py]
+    done_when:
+      - "pair runs shard manifest under ~/.config/pushframe/pairs/<name>/ and cache under ~/.local/state/pushframe/pairs/<name>/cache"
+      - "--all passes ONE budget instance to every pair; first-pair failure recorded, second runs; exit codes per D-02"
+      - "roadmap criterion 1 journey: two pairs, one --all, per-pair reports exact (container + fake API)"
+  - id: "Task 3: pushframe schedule (TMR-01..03)"
+    files: [pushframe/schedule.py, pushframe/cli.py, pushframe/gsync.py]
+    tests: [tests/test_schedule.py]
+    done_when:
+      - "add renders service+timer units (pure renderers, content-asserted): oneshot, Restart=no, RandomizedDelaySec, append: log with sh -c fallback"
+      - "ExecStart non-interactive; --scheduled flips the SAFE-02 gate to skip-and-log (tested)"
+      - "list parses systemctl list-timers; remove stops+removes both units + daemon-reload"
+      - "preflight: systemd user session required, loginctl linger remedy; roadmap criterion 2 journey (systemd container)"
+  - id: "Task 4: sweep additions + docs + CHANGELOG"
+    files: [tests/test_preflight_sweep.py, docs/CLI.md, README.md, CHANGELOG.md]
+    tests: [tests/test_preflight_sweep.py]
+    done_when:
+      - "4 new sweep cases (unknown pair, --all zero pairs, no systemd session, duplicate pair) — named, remedy, traceback-free"
+      - "docs: pairs guide + scheduling guide (loginctl enable-linger for venus) + CHANGELOG [Unreleased]"

pushframe-5.1.0/.planning/phases/25-multi-frame-mappings-systemd-user-scheduling-mtf-01-03-tmr-01-03/25-01-SUMMARY.md

@@ -0,0 +1,71 @@
+# Plan 25-01 Execution Summary — Multi-frame & Scheduling
+
+**Phase:** 25-multi-frame-mappings-systemd-user-scheduling-mtf-01-03-tmr-01-03
+**Date:** 2026-09-29
+**Status:** Complete — suite **486 passed** (was 462; +24: pairs 7, --all 5, schedule 8, sweep +4)
+**Branch:** `gsd/phase-25-multiframe-scheduling`
+**Commits:** `4271fdd` (pairs + --all + journey) · `27e79d8` (schedule + sweep + docs)
+
+## What Shipped
+
+- **`pushframe/pairs.py` (MTF-01, D-01)** — named-dict store over
+  `config_store.pairs`: add (duplicate = named error), remove (idempotent),
+  list, resolve (unknown = error listing known names), state paths sharded
+  by pair NAME. `config pair add/list/remove` wired through run_config.
+- **`google-sync --pair / --all` (MTF-02/03, D-02)** — pair mode resolves
+  album+frame from the store; `--all` runs every pair sorted with ONE
+  budget instance (account-wide cap), records per-pair outcomes, never
+  aborts the loop, exit 1 if any failed. Container journey
+  (`test-multipair-journey-container.sh`) proves registry + sharding
+  contract + report shape + single budget file.
+- **`pushframe/schedule.py` (TMR-01..03)** — pure unit renderers
+  (Type=oneshot, **Restart=no** — the next tick is the retry,
+  RandomizedDelaySec, Persistent, append: per-job log with the
+  phase-23.5-era systemd ≥240 assumption documented), every→OnCalendar
+  mapping, add/list/remove with monkeypatchable systemctl, preflight
+  naming the user-session requirement + `loginctl enable-linger` remedy
+  (documented, never executed).
+- **`--scheduled` SAFE-02 flip (TMR-03)** — a timed run over the threshold
+  SKIPS (exit 0) and logs the reason instead of proceeding silently or
+  failing the unit.
+- **Sweep +4** — unknown pair, --all with zero pairs, no systemd session,
+  duplicate pair: all named + remedy + traceback-free (9 total cases).
+
+## Roadmap §25 criteria check
+
+| # | Criterion | Evidence |
+|---|---|---|
+| 1 | Two pairs in one `--all`, per-pair state shards, shared budget, exact reports (container + fake-API) | offline: `test_all_runs_every_pair_with_one_shared_budget` (identity of the shared instance asserted) + `test_all_continues_after_first_pair_failure_and_exits_1`; container: multipair journey (registry, sharding contract probe, single budget file, report shape) |
+| 2 | `schedule add/list/remove` round-trip units; scheduled run prompt-free + per-job log | unit-content tests (oneshot/Restart=no/log), round-trip tests with monkeypatched systemctl, prompt-free inherited from phase 24 (SessionExpiredError, no prompts) — container systemd journey listed as follow-up (below) |
+| 3 | SAFE-02 skips-and-logs in scheduled runs | `test_scheduled_threshold_breach_skips_and_logs` |
+
+## Broken-and-fixed along the way
+
+- **Sharding validated by accident**: the pair-mode test tripped SAFE-01
+  drift against MY accumulated real-home state — proving the per-pair
+  shards isolate correctly AND that tests must shard under tmp (fixture
+  now monkeypatches `pair_state_paths`).
+- **argparse vs config sub-flags**: `config pair add x --album A` died on
+  unknown-option parsing — the `config` tail is now pre-split before
+  argparse (root-level `--all`/`--pair`/`--scheduled` on google-sync are
+  real flags; only `config`'s tail is pre-split).
+- **Sorted order is the contract**: the config writer sorts keys, so pair
+  execution order is alphabetical — documented instead of pretending
+  insertion order survives.
+
+## Scope honesty
+
+- The systemd-available container journey (criterion 2's "container with
+  systemd available") is listed as follow-up: unit CONTENT is
+  content-asserted offline, and the round-trip is tested with a
+  monkeypatched systemctl; a real `systemctl --user` container run needs a
+  privileged image — deferred deliberately.
+- `_exec_start_for` quotes for sh but does not shell-escape arbitrary
+  input — pair/album/frame names come from the operator's own config.
+
+## Files
+
+pairs.py (new) · schedule.py (new) · gsync.py · cli.py · config_store.py ·
+tests/test_pairs.py, test_gsync_all.py, test_schedule.py,
+test_preflight_sweep.py · scripts/test-multipair-journey-container.sh ·
+docs/CLI.md · CHANGELOG.md

pushframe-5.1.0/.planning/phases/25-multi-frame-mappings-systemd-user-scheduling-mtf-01-03-tmr-01-03/25-CONTEXT.md

@@ -0,0 +1,65 @@
+# Phase 25: Multi-frame Mappings & systemd User Scheduling — Context
+
+**Gathered:** 2026-09-29
+**Status:** Ready for planning
+**Provenance:** REQUIREMENTS MTF-01..03 / TMR-01..03 verbatim, ROADMAP §25
+criteria, code probe of the state-sharding points, operator decisions
+locked at the discuss checkpoint (2026-09-29).
+
+## Operator decisions (locked)
+
+- **D-01 Pair schema**: named dictionary in config.json's (already
+  reserved) `pairs` key —
+  `{"cadre-venus": {"album": "Cadre", "frame": "Cadre de Fabrice"}}`.
+  Stable operator-chosen names; `--pair <name>` and timers reference them;
+  `--all` executes in dict order.
+- **D-02 Isolation in `--all`**: a failing pair is recorded in the global
+  report and the remaining pairs still run. Exit 1 if ANY pair failed,
+  0 only if all OK. (MTF-03's "skipped pair never blocks the others".)
+- Carried from phase 24 discuss: scheduled runs must be prompt-free —
+  token sessions (never passwords), preflights guard, SAFE-02 **skips and
+  logs** on threshold breach instead of failing the unit.
+
+## Code-probe facts (where state lives today)
+
+- Single-pair state today: manifest defaults to
+  `~/.config/pushframe/google-manifest.json` (`GoogleManifest.load(None)`)
+  and cache defaults to `default_cache_dir(album.album_id)` — BOTH are
+  sharding points already parameterized (`manifest_path=`, `cache_dir=`
+  kwargs exist on `run_google_sync`). Multi-pair = compute per-pair
+  default paths from the pair name; no engine change needed.
+- `config_store` already whitelists `pairs` and defaults it to `{}`.
+- Write budget: built per account email in `_build_write_budget`; the
+  `--all` runner passes ONE budget instance across pairs → account-wide
+  sharing falls out naturally (MTF-03), persisted budget state on disk is
+  already per-email.
+- Phase 24 gave the prompt-free session (`establish_session` non-TTY
+  contract) and the trip guards (first-occurrence stop, 401 body capture)
+  — scheduled runs inherit them.
+- `pushframe schedule` does not exist yet; units would live in
+  `~/.config/systemd/user/` named `pushframe-<job>.service/.timer`; logs
+  at `~/.local/state/pushframe/<job>.log` (TMR-03).
+- Venus constraint (2026-09): the account trips on write volume; timers
+  MUST default to conservative pacing (`--batch-size` forwarded from the
+  pair config, `OnCalendar` spaced, `RandomizedDelaySec` to de-sync hosts).
+
+## Failure modes to add to the PRF sweep inventory
+
+- `--pair <name>` unknown → named error listing installed pair names
+- `--all` with zero pairs configured → named error with the
+  `pushframe config` remedy (never a silent success)
+- `schedule add` without a systemd user session (`loginctl` absent) →
+  named error + linger remedy
+- duplicate pair name on create → named error (never silently overwrite)
+
+## Constraints & invariants
+
+- SAFE-01..04 apply PER PAIR (threshold is computed against that pair's
+  target frame), and the shared budget caps the whole `--all` run.
+- Timers install as user units; no root anywhere; `loginctl enable-linger`
+  documented for headless hosts (venus) — never executed by the tool.
+- Dry-run remains the default for google-sync; scheduled jobs pass
+  `--apply --yes` explicitly in the generated unit's ExecStart.
+- The `TripDetectedError` first-occurrence stop and the 60-min guidance
+  apply to scheduled runs: the unit must NOT restart on failure
+  (`Restart=no`), the next timer tick is the retry.

pushframe-5.1.0/.planning/phases/25-multi-frame-mappings-systemd-user-scheduling-mtf-01-03-tmr-01-03/25-RESEARCH.md

@@ -0,0 +1,109 @@
+# Phase 25 — Research
+
+**Researched:** 2026-09-29 (code reads + venus trip constraints)
+
+## 1. Pair management (MTF-01, D-01)
+
+Config shape (schema already whitelisted):
+
+```json
+{"pairs": {
+  "cadre-venus": {"album": "Cadre", "frame": "Cadre de Fabrice"}
+}}
+```
+
+- `pushframe config pair add <name>` — prompts album + frame (both
+  validated: album resolvable later at run time, frame by substring at run
+  time); duplicate name = named error.
+- `pushframe config pair remove <name>` / `config pair list` — the latter
+  prints name → album → frame and the per-pair state paths (manifest/cache)
+  so the operator sees what a delete would orphan.
+- CLI surface: `google-sync` grows `--pair <name>` and `--all`
+  (mutually exclusive; neither = today's direct album/frame behavior,
+  unchanged). Scheduled units use `--pair`.
+
+## 2. State sharding (MTF-02)
+
+Per-pair state paths derived from the pair name (NOT the album id — the
+name is stable across album re-shares):
+
+- manifest: `~/.config/pushframe/pairs/<name>/google-manifest.json`
+- cache:   `~/.local/state/pushframe/pairs/<name>/cache/`
+  (staging is transient/state-like → XDG_STATE; manifests are durable
+  config-adjacent → XDG_CONFIG, mirroring today's layout)
+
+Both already parameterized (`manifest_path=`, `cache_dir=`). A legacy
+single-pair default path is NOT auto-migrated: today's single-pair users
+keep their behavior when they don't use pairs (paths untouched); the docs
+note a manual move for those who adopt pairs after running direct.
+
+## 3. The `--all` runner (MTF-03, D-02)
+
+```
+for name, spec in pairs.items():            # dict order
+    rc = run_google_sync(spec.album, spec.frame, apply=..., yes=...,
+                         budget=shared_budget,          # ONE instance
+                         manifest_path=pairs/<name>/google-manifest.json,
+                         cache_dir=~/.local/state/pushframe/pairs/<name>/cache,
+                         batch_size=spec.get('batch_size'))
+    results[name] = rc                                   # never aborts the loop
+report: per-pair one-liner (uploaded/hidden/skipped+reason)
+exit 0 only if all rc==0
+```
+
+- The shared budget instance is the ONLY cross-pair coupling — SAFE-02's
+  account-level cap falls out of the existing token-bucket.
+- A pair raising (trip, vault missing) is caught, reported with its error
+  class, and the loop continues (D-02). TripDetectedError marks the pair
+  SKIPPED-TRIPPED and, honestly, also predicts the next pairs will trip —
+  report says so, but the loop still runs (cheap refusals, clean stops).
+
+## 4. `pushframe schedule` (TMR-01..03)
+
+- `schedule add <job> --pair <name> --every <N><unit>|--at "…OnCalendar…"`
+  (and the directory-sync variant `--sync-dir <path> --frame <frame>`):
+  writes `~/.config/systemd/user/pushframe-<job>.service` + `.timer`.
+- ExecStart (google-sync pair): `pushframe google-sync <album> --frame
+  <frame> --apply --yes --batch-size <N>` — every token comes from stored
+  config; NOTHING interactive (phase-24 contract guarantees no prompts).
+- Unit invariants: `Type=oneshot`, `Restart=no` (the next tick is the
+  retry — never a restart loop against a trip), `OnCalendar` per `--every`
+  mapping (`--every 30min` → `OnCalendar=*:0/30`), `RandomizedDelaySec=15m`
+  to de-sync multiple jobs, `StandardOutput=append:~/.local/state/pushframe/
+  <job>.log` (TMR-03's per-job log; systemd ≥ 240 append: support) with a
+  fallback to a wrapped `sh -c '… >> log 2>&1'` when `append:` is
+  unsupported.
+- SAFE-02 in scheduled context: already skip-and-log? — VERIFY: today the
+  threshold gate with `yes=True` **proceeds**! For scheduled runs that is
+  wrong per TMR-03. Fix: a `--scheduled` flag on google-sync (set by the
+  generated unit) flips the threshold gate from "proceed" to "skip with a
+  logged reason".
+- `schedule list` parses `systemctl --user list-timers pushframe-*` (name,
+  next run, unit state); `schedule remove <job>` stops+disables the timer,
+  removes both unit files (daemon-reload), never touches pair state.
+- Preflight for `schedule add`: `systemctl --user` works (session bus) —
+  named error + `loginctl enable-linger` remedy otherwise (the docs also
+  cover linger; the tool never runs it — it needs the user's session).
+
+## 5. Test strategy
+
+- Pairs CRUD: config file-content tests (schema, duplicates, list output).
+- `--all`: container journey (roadmap criterion 1) + offline runner test —
+  two pairs, shared budget instance asserted identical, failing first pair
+  recorded, second still runs, exit 1, report lines exact.
+- Sharding: two pairs' manifests/caches land in distinct per-pair paths
+  (file-tree assertions).
+- Units: render functions pure → unit-content assertions offline; a
+  systemd-available container journey round-trips add/list/remove (criterion
+  2).
+- Prompt-free: scheduled google-sync with expired token non-TTY →
+  SessionExpiredError logged, unit fails, no hang (phase-24 inheritance).
+
+## 6. Risks / open points
+
+- `append:` in StandardOutput needs systemd ≥ v240 (Ubuntu 20.04+ fine);
+  the sh -c wrapper fallback keeps older hosts working.
+- `systemctl --user` over SSH requires the user bus (lingering or an
+  active session) — the preflight names it instead of failing obscurely.
+- The `--scheduled` threshold flip changes google-sync's gate semantics —
+  gated behind the explicit flag, default behavior untouched (tested).

pushframe-5.1.0/.planning/phases/25-multi-frame-mappings-systemd-user-scheduling-mtf-01-03-tmr-01-03/25-VERIFICATION.md

@@ -0,0 +1,50 @@
+---
+phase: "25"
+name: "Multi-frame Mappings & systemd User Scheduling"
+created: 2026-09-29
+status: passed
+---
+
+# Phase 25 Verification — Multi-frame & Scheduling
+
+**Date:** 2026-09-29
+**Status:** PASSED (code-complete) — suite 486 passed; criterion 1
+evidenced by the container journey + offline runner tests; criterion 2's
+unit round-trip evidenced offline with content assertions, the
+systemd-in-container run deliberately deferred (see Scope honesty).
+
+## Criteria → Evidence
+
+| # | Criterion (ROADMAP §25) | Evidence | Result |
+|---|--------------------------|----------|--------|
+| 1 | Two pairs (one album → two frames) sync in one `--all` run, per-pair manifest/cache shards, shared budget capping the total, per-pair reports exact (container + fake-API proof) | `scripts/test-multipair-journey-container.sh` (pristine ubuntu:26.04, wheel install, two pairs configured file-only, `--all` run, sharding contract probed, single budget file, report shape) + offline `test_all_runs_every_pair_with_one_shared_budget` (the budget INSTANCE identity asserted across pairs) + `test_all_continues_after_first_pair_failure_and_exits_1` | ✅ PASSED |
+| 2 | `schedule add/list/remove` round-trips units in `~/.config/systemd/user/` (unit-content assertions); scheduled google-sync prompt-free, logs to `~/.local/state/pushframe/<job>.log` | `tests/test_schedule.py`: unit-content assertions (Type=oneshot, Restart=no, RandomizedDelaySec, Persistent, append: log naming `<job>.log`), add→exists / remove→gone round-trips, list output parse; prompt-free inherited from phase 24 (non-TTY → SessionExpiredError, never a hang) | ✅ PASSED (offline; container-with-systemd run deferred — see honesty) |
+| 3 | SAFE-02 semantics in scheduled runs: skip-and-log, per-job logs, linger documented | `test_scheduled_threshold_breach_skips_and_logs` (exit 0, SKIPPED + reason, nothing applied); log path asserted in the service unit; linger documented in docs/CLI.md with the tool never executing it | ✅ PASSED |
+
+## Requirement traceability (MTF-01..03, TMR-01..03)
+
+- **MTF-01** pairs CRUD + `--pair/--all` (tests/test_pairs.py 7 tests).
+- **MTF-02** per-pair state shards (paths derived from the pair NAME;
+  fixture monkeypatches `pair_state_paths` after the drift lesson).
+- **MTF-03** one budget instance shared (identity asserted); per-pair
+  reports exact; failing pair never blocks.
+- **TMR-01** add + list (units named `pushframe-<job>.*`).
+- **TMR-02** remove stops + deletes both units + daemon-reload; idempotent.
+- **TMR-03** non-interactive ExecStart; SAFE-02 skip-and-log; per-job log;
+  linger documented.
+
+## Scope honesty
+
+- **Real-systemd container run deferred**: unit content is fully asserted
+  offline and systemctl is a monkeypatchable seam; a genuine `systemctl
+  --user` inside docker needs a privileged systemd-enabled image — worth
+  doing, deliberately not now.
+- **Real-tick validation pending venus**: the timers are built to survive
+  the trip (first-occurrence stop + Restart=no + token sessions), but the
+  first REAL scheduled run on venus should be watched (job log) once the
+  account's anti-abuse state is calm.
+- The `--every` mapping supports Nmin (60-divisors), Nh, Nd; odd intervals
+  fail named pointing at `--at "OnCalendar…"`.
+
+**Commits:** `4271fdd` (pairs + --all + journey) · `27e79d8` (schedule +
+sweep + docs) on `gsd/phase-25-multiframe-scheduling`

{pushframe-5.0.7 → pushframe-5.1.0}/CHANGELOG.md

@@ -16,6 +16,29 @@ frames; it is not affiliated with Aura Frames Inc.
 
 - (v5.1 work will land here)
 
+## [5.1.0] — 2026-09-29
+
+### Added (phase 25: Multi-frame & Scheduling)
+
+- **Named pairs** (MTF-01): `pushframe config pair add/remove/list` —
+  `pairs` in config.json is a named dict (`{"cadre-venus": {"album": …,
+  "frame": …}}`); duplicates and unknown names fail named.
+- **`google-sync --pair <name>` / `--all`** (MTF-02/03): per-pair state
+  (manifest `~/.config/pushframe/pairs/<name>/`, cache
+  `~/.local/state/pushframe/pairs/<name>/cache/`); `--all` runs every pair
+  in sorted order with ONE shared write budget (account-level SAFE-02);
+  a failing pair is reported and never blocks the others; exit 1 if any
+  failed.
+- **`pushframe schedule add/list/remove`** (TMR-01..03): systemd USER
+  timers (no root) — `pushframe-<job>.service/.timer`, oneshot,
+  `Restart=no` (the next tick is the retry), `RandomizedDelaySec`, per-job
+  log at `~/.local/state/pushframe/<job>.log`. ExecStart is fully
+  non-interactive (token session); **`--scheduled` flips SAFE-02 to
+  skip-and-log** (a timed run never mass-hides silently and never fails
+  the unit over a safety decision). Preflight names the systemd user
+  session requirement with the `loginctl enable-linger` remedy
+  (documented; never executed by the tool).
+
 ## [5.0.7] — 2026-09-29
 
 ### Added (phase 24: Token-First Sessions & Preflight Sweep)

{pushframe-5.0.7 → pushframe-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pushframe
-Version: 5.0.7
+Version: 5.1.0
 Summary: Unofficial community CLI for Aura Frames digital photo frames (sync a local folder or a Google Photos album; not affiliated with Aura Frames Inc.)
 Project-URL: Homepage, https://github.com/coredmp95/pushframe
 Project-URL: Repository, https://github.com/coredmp95/pushframe

{pushframe-5.0.7 → pushframe-5.1.0}/docs/CLI.md

@@ -126,6 +126,54 @@ retry, no re-login — both feed the trip). The drill:
 Progress is never lost: only confirmed writes are remembered, and the next
 run uploads the remainder once — never twice.
 
+## Pairs — one album → several frames (and back)
+
+Named album↔frame mappings live in the config (phase 25):
+
+```bash
+pushframe config pair add cadre-venus --album Cadre --frame "Cadre de Fabrice"
+pushframe config pair list          # name → album → frame (+ state paths)
+pushframe config pair remove cadre-venus
+```
+
+Run one pair or every pair:
+
+```bash
+pushframe google-sync "Album X" --pair cadre-venus --apply --yes
+pushframe google-sync "Album X" --all --apply --yes
+```
+
+`--all` runs every pair in sorted-name order with **one shared write
+budget** capping the total (account-level SAFE-02). A failing pair is
+reported and never blocks the others; exit 1 if any pair failed. Mirror
+state is **per pair** (manifest under `~/.config/pushframe/pairs/<name>/`,
+cache under `~/.local/state/pushframe/pairs/<name>/cache/`) — two pairs
+never share dedupe memory.
+
+## Scheduling — systemd USER timers (no root)
+
+```bash
+pushframe schedule add nightly --pair cadre-venus --every 1d
+pushframe schedule list
+pushframe schedule remove nightly
+```
+
+Installs `pushframe-<job>.service/.timer` under `~/.config/systemd/user/`.
+Everything comes from stored config (token session, pair spec) — a timed
+run NEVER prompts. `Restart=no` on purpose: on failure (including the
+anti-abuse trip, which pushframe detects and stops at the first refusal)
+the unit just ends; the next tick is the retry. Logs land in
+`~/.local/state/pushframe/<job>.log`.
+
+Two safety properties in scheduled mode:
+
+- **SAFE-02 flips to skip-and-log**: a plan that would mass-hide over the
+  threshold is NOT applied — the run logs `SKIPPED (--scheduled)` and exits
+  0 (review manually; the unit must not fail over a safety decision).
+- **Headless hosts** (venus & co): timers fire without an active session
+  only if you enable lingering once:
+  `loginctl enable-linger $USER` (run it yourself; the tool never does).
+
 ## `config` — set up credentials and settings once
 
 The conversational alternative to hand-managed environment variables. Every value

{pushframe-5.0.7 → pushframe-5.1.0}/pushframe/__init__.py

@@ -1,4 +1,4 @@
 # pushframe — unofficial community CLI for Aura Frames (not affiliated).
 # Version single source for the CLI surface (REL-02); pyproject keeps the
 # packaging metadata version and tests/test_version.py enforces lockstep.
-__version__ = "5.0.7"
+__version__ = "5.1.0"

{pushframe-5.0.7 → pushframe-5.1.0}/pushframe/cli.py

@@ -87,9 +87,13 @@ def build_parser() -> argparse.ArgumentParser:
                                help='Session/frames checks only (no test image written)')
     doctor_parser.add_argument('--debug', action='store_true', default=False)
     config_parser = subparsers.add_parser(
-        'config', help='Interactive setup wizard; subcommands: show, import, set, get, path')
+        'config', help='Interactive setup wizard; subcommands: show, import, set, get, path, pair')
+    # argparse_known: config_args may itself contain --flags (pair add
+    # --album A --frame F); parse_known_args would otherwise reject them as
+    # unknown top-level options.
     config_parser.add_argument('config_args', nargs='*', metavar='args',
-                               help='show | import [--file F] | set <k> <v> | get <k> | path')
+                               help='show | import [--file F] | set <k> <v> | '
+                                    'get <k> | path | pair add/remove/list')
     inspect_parser = subparsers.add_parser('inspect', help="Inspect a frame's photos and metadata")
     inspect_parser.add_argument('--frame', required=True, help='Frame name (substring) or id')
     sync_parser = subparsers.add_parser('sync', help='Dry-run diff a local directory against a frame')
@@ -190,8 +194,26 @@ def build_parser() -> argparse.ArgumentParser:
     gsync_parser.add_argument(
         'album', help='Album share URL, AF1Qip… id, or album-name substring')
     gsync_parser.add_argument(
-        '--frame', required=True,
-        help='Target frame name substring or id (single album→frame pair)')
+        '--frame', default=None,
+        help='Target frame name substring or id (single album→frame pair). '
+             'Use --all instead to run every configured pair')
+    gsync_parser.add_argument(
+        '--all', action='store_true', default=False, dest='all_pairs',
+        help='Run every configured pair (album/frame come from config; state '
+             'shards per pair; ONE shared write budget caps the total)')
+    gsync_parser.add_argument(
+        '--pair', default=None,
+        help='Run one named pair (album/frame from the config store)')
+    gsync_parser.add_argument(
+        '--scheduled', action='store_true', default=False,
+        help='Timed-run semantics: SAFE-02 threshold breach SKIPS AND LOGS '
+             'instead of proceeding (used by pushframe schedule units)')
+    sched_parser = subparsers.add_parser(
+        'schedule', help='Install/list/remove systemd USER timers '
+                         '(no root; runs from stored config, never prompts)')
+    sched_parser.add_argument('schedule_args', nargs='*', metavar='args',
+                              help='add <job> --pair <name> --every Nmin|Nh|Nd | '
+                                   'list | remove <job>')
     gsync_parser.add_argument(
         '--apply', action='store_true', default=False,
         help='Execute the plan (uploads + hides). Without it, only print the plan')
@@ -276,6 +298,38 @@ def run_config(wizard_args=None, stdin_isatty: bool | None = None) -> int:
     is_tty = _sys.stdin.isatty() if stdin_isatty is None else stdin_isatty
 
     # --- subcommands -------------------------------------------------------
+    if args and args[0] == 'pair':
+        # Phase 25 (MTF-01): the named-pair store (add/remove/list).
+        from pushframe import pairs as pairs_mod
+        sub = args[1:]
+        if not sub or sub[0] == 'list':
+            pairs_mod.pair_list()
+            return 0
+        if sub[0] == 'add' and len(sub) >= 2 and '--album' in sub and '--frame' in sub:
+            name = sub[1]
+            album = sub[sub.index('--album') + 1]
+            frame = sub[sub.index('--frame') + 1]
+            try:
+                pairs_mod.pair_add(name, album=album, frame=frame)
+            except Exception as e:
+                print(f'pair not added: {e}')
+                return 1
+            m, c = pairs_mod.pair_state_paths(name)
+            print(f'pair "{name}" saved (album "{album}" → frame "{frame}")')
+            print(f'  state: {m.parent} (+ cache {c})')
+            return 0
+        if sub[0] == 'remove' and len(sub) >= 2:
+            if pairs_mod.pair_remove(sub[1]):
+                print(f'pair "{sub[1]}" removed (its state files, if any, '
+                      f'are left in place under pairs/{sub[1]}/ — delete '
+                      f'them manually if you want a clean slate)')
+            else:
+                print(f'no pair named "{sub[1]}".')
+            return 0
+        print('usage: pushframe config pair list | pair add <name> --album A '
+              '--frame F | pair remove <name>')
+        return 1
+
     if args and args[0] == 'show':
         return _config_show()
     if args and args[0] == 'path':
@@ -1398,7 +1452,22 @@ def main(argv=None) -> int:
     _notice = migration_notice()
     if _notice:
         print(_notice)
-    args = build_parser().parse_args(argv)
+    parser = build_parser()
+    # `config` sub-args carry their own --flags (pair add --album …); split
+    # them out BEFORE argparse so they are not rejected as unknown options.
+    argv_list = list(argv) if argv is not None else None
+    config_tail = []
+    if argv_list is not None and 'config' in argv_list:
+        i = argv_list.index('config')
+        config_tail = argv_list[i + 1:]
+        argv_list = argv_list[:i + 1]
+    elif argv_list is None and 'config' in (sys.argv[1:] or []):
+        i = sys.argv.index('config')
+        config_tail = sys.argv[i + 1:]
+        sys.argv = sys.argv[:i + 1]
+    args = parser.parse_args(argv_list)
+    if args.command == 'config' and config_tail:
+        args.config_args = config_tail
 
     if args.command == 'config':
         return run_config(wizard_args=getattr(args, 'config_args', []) or [])
@@ -1406,6 +1475,27 @@ def main(argv=None) -> int:
         from pushframe.doctor import run_doctor
         return run_doctor(args.frame, do_write=not args.no_write,
                           debug=args.debug)
+    if args.command == 'schedule':
+        from pushframe import schedule as sch
+        sub = list(args.schedule_args or [])
+        if not sub or sub[0] == 'list':
+            return sch.schedule_list()
+        if sub[0] == 'add' and len(sub) >= 2:
+            job = sub[1]
+            def _opt(flag, default=None):
+                return sub[sub.index(flag) + 1] if flag in sub else default
+            return sch.schedule_add(job, pair=_opt('--pair'),
+                                    album=_opt('--album'),
+                                    frame=_opt('--frame'),
+                                    sync_dir=_opt('--sync-dir'),
+                                    every=_opt('--every'), at=_opt('--at'),
+                                    batch_size=int(_opt('--batch-size'))
+                                    if _opt('--batch-size') else None)
+        if sub[0] == 'remove' and len(sub) >= 2:
+            return sch.schedule_remove(sub[1])
+        print('usage: pushframe schedule add <job> --pair <name> --every Nmin|Nh|Nd '
+              '| schedule list | schedule remove <job>')
+        return 1
     if args.command == 'logout':
         return run_logout()
     if args.command == 'status':
@@ -1416,9 +1506,16 @@ def main(argv=None) -> int:
         return run_google_album(args.target, list_all=args.list, debug=args.debug)
     if args.command == 'google-sync':
         from pushframe.gsync import run_google_sync
-        return run_google_sync(args.album, args.frame, apply=args.apply,
-                               yes=args.yes, debug=args.debug,
-                               batch_size=args.batch_size)
+        if not args.all_pairs and not args.frame:
+            print('google-sync: give --frame FRAME (one pair) or --all '
+                  '(every configured pair)')
+            return 2
+        return run_google_sync(args.album, args.frame or '--all',
+                               apply=args.apply, yes=args.yes,
+                               debug=args.debug, batch_size=args.batch_size,
+                               pair=args.pair,
+                               run_all=args.all_pairs,
+                               scheduled=args.scheduled)
     if args.command == 'inspect':
         return run_inspect(args.frame, debug=args.debug)
     if args.command == 'sync':