pushframe 5.0.6__tar.gz → 5.1.0__tar.gz

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

@@ -5,16 +5,16 @@
 
 ## Current Position
 
-Phase: 23 — VERIFIED (passed)
-Current Plan: 23-01 complete
-Total Plans in Phase: 1
-Status: Verified — next: phase 24 (Token-First Sessions & Preflight Sweep)
+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)
-- [ ] 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 24 — Token-First Sessions & Preflight Sweep (SEC-01..03, PRF-01..02)
+- [x] Phase 25 — Multi-frame Mappings & systemd User Scheduling (MTF-01..03, TMR-01..03)
 
 ## Completed Milestones
 

pushframe-5.1.0/.planning/phases/24-token-first-sessions-preflight-sweep-sec-01-03-prf-01-02/24-01-PLAN.md

@@ -0,0 +1,77 @@
+---
+phase: 24-token-first-sessions-preflight-sweep-sec-01-03-prf-01-02
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - pushframe/session.py
+  - pushframe/cli.py
+  - pushframe/gsync.py
+  - pushframe/sync.py
+  - pushframe/config_store.py
+  - pushframe/preflight.py
+  - tests/test_session.py
+  - tests/test_logout.py
+  - tests/test_preflight_sweep.py
+  - tests/test_execute_plan.py
+  - docs/CLI.md
+  - README.md
+  - CHANGELOG.md
+autonomous: true
+requirements: [SEC-01, SEC-02, SEC-03, PRF-01, PRF-02]
+
+estimate:
+  tokens: 60000
+  raw_tokens: 48000
+  tasks: 4
+  confidence: high
+
+must_haves:
+  truths:
+    - "config wizard + login leaves a token, NO password, in ~/.config/pushframe/config.json at 0600 (file-content test)"
+    - "every command (inspect, reconcile, sync, push, google-sync, status) runs from the stored token session when no env password is set"
+    - "a mocked 401 on session establishment triggers exactly ONE re-login then succeeds; a second failure surfaces the named error with remedy — never a loop"
+    - "non-TTY + expired token = SessionExpiredError with remedy, no prompt, no hang"
+    - "pushframe logout removes auth_token/user_id, keeps email/settings, stays 0600, idempotent"
+    - "sync/push fail named+prework on a nonexistent source dir; empty dir stays a non-error"
+    - "the PRF-02 sweep proves every inventoried foreseeable mode ends named, with remedy, traceback-free"
+  artifacts:
+    - path: pushframe/session.py
+      provides: establish_session + SessionExpiredError + the one TTY prompt path
+    - path: pushframe/preflight.py
+      provides: preflight helpers (vault, source dir) used by gsync/sync/push
+  key_links:
+    - from: establish_session
+      to: config_store (persist token after TTY re-login)
+    - from: execute_plan relogin default
+      to: session.py token-aware relogin (env password → login; TTY → prompt; else named error)
+
+sequential_tasks:
+  - id: "Task 1: establish_session + call-site conversion (SEC-01/02)"
+    files: [pushframe/session.py, pushframe/cli.py, pushframe/gsync.py]
+    tests: [tests/test_session.py]
+    done_when:
+      - "red→green: run_inspect/reconcile/sync/google-sync work with ONLY a stored session (no env)"
+      - "env password still wins (override test)"
+      - "no password ever persisted (file-content assertion)"
+  - id: "Task 2: expiry flow — one re-login then surface (criterion 2)"
+    files: [pushframe/session.py, pushframe/sync.py]
+    tests: [tests/test_session.py, tests/test_execute_plan.py]
+    done_when:
+      - "mocked 401 → TTY prompt once → new token persisted → command continues"
+      - "mocked 401 → non-TTY → SessionExpiredError, remedy, rc=1"
+      - "execute_plan relogin default is token-aware; second consecutive failure surfaces"
+  - id: "Task 3: pushframe logout (SEC-03, D-02)"
+    files: [pushframe/config_store.py, pushframe/cli.py]
+    tests: [tests/test_logout.py]
+    done_when:
+      - "token+user_id gone, email+settings kept, 0600 preserved, idempotent, no token in output"
+  - id: "Task 4: preflights + the traceback-free sweep (PRF-01/02, D-03)"
+    files: [pushframe/preflight.py, pushframe/gsync.py, pushframe/cli.py]
+    tests: [tests/test_preflight_sweep.py]
+    done_when:
+      - "google-sync without vault = named error + google-link remedy (before any Google work)"
+      - "sync/push nonexistent dir = named error; empty dir = nothing-to-do"
+      - "sweep: every inventoried mode parametrized — named error, remedy substring, zero Traceback"
+      - "docs (README/CLI.md) + CHANGELOG"

pushframe-5.1.0/.planning/phases/24-token-first-sessions-preflight-sweep-sec-01-03-prf-01-02/24-01-SUMMARY.md

@@ -0,0 +1,56 @@
+# Plan 24-01 Execution Summary — Token-First Sessions & Preflight Sweep
+
+**Phase:** 24-token-first-sessions-preflight-sweep-sec-01-03-prf-01-02
+**Date:** 2026-09-29
+**Status:** Complete — suite **459 passed** (was 443; +16: session 7, logout 4, sweep 5)
+**Branch:** `gsd/phase-24-token-first-preflight`
+
+## What Shipped
+
+- **`pushframe/session.py`** — `establish_session`, the ONE path: env
+  password override → stored token resume (no login call) → ONE TTY prompt
+  (token persisted, SEC-01 file-content tested) → `NoCredentialsError`
+  named. Expiry (D-01): a 401 on resume = TTY one-prompt-and-continue /
+  non-TTY `SessionExpiredError`; `_is_auth_failure` keeps corrupt-config
+  errors from masquerading as expiry.
+- **Call-site conversion** — `run_inspect`, `run_reconcile`, `run_sync`
+  (sync+push), `gsync` all funnel through establish_session. DI contract
+  now enforced at every site: an **injected Aura is never re-authenticated**
+  (tests, doctor, pipelines manage their own auth).
+- **Token-aware relogin** — `execute_plan`'s 401-retry seam no longer
+  assumes `aura.login`: env password → real login; TTY → the one prompt
+  (budget-charged as before); non-TTY → `AuthenticationError` named, the
+  chunk fails, the breaker still guards. No loops, no hangs.
+- **`pushframe logout`** (D-02) — token+user_id removed, email/settings/
+  default_frame kept, 0600 preserved, idempotent, token never printed.
+  `config_store.update` learns None-means-remove.
+- **`pushframe/preflight.py`** — `require_google_vault` (google-sync, with
+  the ssh -X headless remedy) and `require_source_dir` (D-03: nonexistent =
+  hard named error BEFORE any network; empty = the friendly nothing-to-do).
+  Wired: gsync vault check precedes session; run_sync dir check precedes
+  login entirely.
+- **The PRF-02 sweep** — `tests/test_preflight_sweep.py` parametrized over
+  the 24-CONTEXT failure-mode inventory (5 cases live; the remaining 4 are
+  already covered by the phase-23.5 google-link tests, referenced in the
+  inventory). Contract per case: rc≠0, named marker, remedy substring,
+  zero "Traceback".
+
+## Roadmap §24 criteria check
+
+| # | Criterion | Evidence |
+|---|---|---|
+| 1 | config+login → token, no password, 0600 (file-content test) | `test_tty_prompt_logs_in_and_persists_token_never_password` (asserts the password string is absent from the file) |
+| 2 | mocked 401 → transparent re-login once, then surface | `test_expired_token_tty_prompts_once_and_persists_new_token` (exactly one prompt, new token persisted) + `test_expired_token_non_tty_named_error_no_prompt` + the relogin seam's named AuthenticationError |
+| 3 | traceback-free sweep passes, parametrized | `test_preflight_sweep.py` — 5 modes, zero tracebacks |
+
+## Broken-and-fixed along the way
+
+- The sweep caught the preflight ORDER bug: run_sync checked the source
+  dir AFTER login — machine prerequisites now precede any network call
+  (that ordering is the PRF-01 point).
+- Three tests encoded the old "call sites re-login an injected aura"
+  contract; converted to the DI contract (no-credentials named path), and
+  the 475 test now exercises the establish_session env path where that
+  behavior actually lives.
+
+**Commits:** this branch (session + call sites + logout + preflights + sweep)

pushframe-5.1.0/.planning/phases/24-token-first-sessions-preflight-sweep-sec-01-03-prf-01-02/24-CONTEXT.md

@@ -0,0 +1,74 @@
+# Phase 24: Token-First Sessions & Preflight Sweep — Context
+
+**Gathered:** 2026-09-29
+**Status:** Ready for planning
+**Provenance:** compiled from REQUIREMENTS SEC-01..03 / PRF-01..02 verbatim,
+ROADMAP §24 success criteria, a full read of the session plumbing after
+phase 23 (which already delivered the stored-session foundation), and the
+operator's three design decisions taken at the discuss checkpoint
+(2026-09-29).
+
+## Operator decisions (locked at discuss)
+
+- **D-01 Expiry in an interactive session**: on a 401 while establishing or
+  using the stored session, a **TTY session prompts once for the password
+  and continues** (token persisted after re-login); a non-TTY (scheduled)
+  run fails with a **named error and the remedy**, never a hanging prompt.
+- **D-02 `pushframe logout`**: deletes **only the stored token** — email,
+  settings and (future) pairs stay. The next `pushframe config` proposes
+  the stored email as the default. Conforms to SEC-03 verbatim.
+- **D-03 sync/push source-dir preflight**: a **nonexistent directory is a
+  hard, named error before any work**; an existing-but-empty directory
+  stays the current friendly "nothing to do" (not an error) — looping
+  scripts over sometimes-empty dirs must not break.
+
+## Current state after phase 23 (probe facts)
+
+- `config_store` already persists `{email, auth_token, user_id}` 0600; the
+  wizard writes it after a live login (D-03 of phase 23).
+- `run_status` (only) resumes the stored session when no password env is
+  set — `Aura.resume_session(email, auth_token, user_id)` exists and is
+  tested. All other commands (`inspect`, `reconcile`, `sync`/`push`,
+  `google-sync`) still call `aura.login()` (env-password path) — the
+  env-only path is kept (SEC-02 override) but stored sessions are not
+  consulted there yet.
+- `execute_plan(relogin=...)` defaults to `aura.login` — **wrong seam for a
+  token session** (no password in config, by design). The 401-retry path
+  (REL-01/02) needs a token-aware relogin that can: try a silent token
+  refresh (re-POST login only if a password is available via env/`--password`),
+  else surface the named error.
+- `google-sync` calls `aura.login()` unconditionally at its start
+  (`gsync.py` ~line 306).
+- The wizard's `_wizard_login` seam returns `{email, auth_token, user_id,
+  frames}` — reuse for the TTY prompt-and-continue path (D-01).
+- Preflight pattern to generalize lives in `google/bootstrap.py`
+  (`_require_profile`, prerequisite checks with install-shape-aware
+  remedies) + `cli.py` headless detection — proven pattern, phase 23.5.
+
+## Failure modes inventoried for the PRF-02 sweep (traceback-free contract)
+
+1. missing `playwright` (google-link) — done, keep the test
+2. missing Chrome/Chromium — done, keep
+3. headless `$DISPLAY` (google-link) — done, keep
+4. near-miss env var name — done, keep
+5. missing/blank vault on `google-sync` — named error, remedy `google-link`
+6. ambiguous/absent `--frame` — already resolve_frame; assert in sweep
+7. sync/push source dir nonexistent — NEW (D-03 hard error)
+8. no credentials at all (no env, no config) — status has it; sweep the rest
+9. corrupt config.json — status has it; sweep the rest
+10. systemd user session absent (`schedule`, phase 25) — placeholder
+11. multi-arch apt notice — docs, N/A in-code
+12. token expired + non-TTY — NEW (D-01 named error)
+
+## Constraints & invariants
+
+- The password must NEVER be written to config.json (SEC-01) — wizard and
+  prompt-and-continue paths both persist **token only**.
+- Env-password path (`PUSHFRAME_PASSWORD`, `--password` in a future CLI)
+  stays the override and is documented discouraged-for-humans (SEC-02).
+- Token material never in logs/output (existing `_REDACT_KEYS` enforced by
+  tests; extend sweep to assert on new paths).
+- Suite is offline-first: every new behavior gets a mock-transport test;
+  the real-API live tests stay `@live`.
+- Roadmap §24 criteria are the acceptance gate (file-content test, mocked
+  401 expiry re-login once-then-surface, parametrized traceback-free sweep).

pushframe-5.1.0/.planning/phases/24-token-first-sessions-preflight-sweep-sec-01-03-prf-01-02/24-RESEARCH.md

@@ -0,0 +1,83 @@
+# Phase 24 — Research
+
+**Researched:** 2026-09-29 (code reads + venus regressions 23.5 as evidence)
+
+## 1. The unified session establishment (SEC-01/02)
+
+Target: one helper every command funnels through, replacing the four copies
+of `aura = aura or Aura(); aura.login()`.
+
+```
+establish_session(aura=None, *, tty_ok: bool, password_override=None) -> Aura
+  1. env password present (PUSHFRAME_/AURA_PASSWORD) → aura.login()        (override, discouraged)
+  2. config has auth_token            → resume_session(email, token, uid)
+  3. else TTY and tty_ok              → wizard-style prompt, login, PERSIST token (never the password)
+  4. else                             → NamedError: remedy = pushframe config
+```
+
+- Call sites: run_inspect, run_reconcile, run_sync, gsync (google-sync),
+  run_status (already done — reuse). `_wizard_login` reused as the login
+  seam; persistence via `config_store.update`.
+- 401 DURING establishment with a stored token (expired/revoked): D-01 —
+  TTY: one password prompt, re-login, persist new token, continue;
+  non-TTY: `SessionExpiredError` (named), remedy text, no prompt.
+
+## 2. Token-aware relogin for execute_plan (the 401-retry seam)
+
+`execute_plan(relogin=...)` default is `aura.login` — breaks under
+token-first (no password). New default behavior, injected at the
+establish_session boundary:
+
+- If env password exists → `aura.login` as today.
+- Else TTY → the D-01 one-prompt path (with budget charge as today).
+- Else → raise `AuthenticationError` immediately with the named remedy;
+  the chunk's items are attributed as failures and the breaker may abort —
+  identical semantics to a failed relogin today (no new failure shape).
+
+## 3. `pushframe logout` (SEC-03, D-02)
+
+- `config_store.update(auth_token=None, user_id=None)` — atomic rewrite,
+  email/settings intact. Mode stays 0600.
+- Output: what was removed, what was kept, remedy (`pushframe config`).
+- Exit 0 also when nothing was stored (idempotent).
+- Sweep asserts: no token material in output; file afterwards contains no
+  `auth_token` key (file-content assertion, mirrors roadmap criterion 1).
+
+## 4. Preflight inventory (PRF-01) with remedies
+
+| Command | Check | Remedy text points to |
+|---|---|---|
+| google-sync | vault `~/.config/pushframe/google-cookies.json` present + parseable | `pushframe google-link` (+ ssh -X recipe for headless) |
+| google-sync | playwright package importable (it imports the google stack) | install-shape-aware line (uv tool / pip --user) |
+| sync/push | source dir exists (D-03 hard) | the exact path echoed back |
+| sync/push | source dir empty → current "nothing to do", NOT an error | — |
+| status/doctor | — | already green paths |
+| schedule (25) | systemd user session + linger | placeholder assertion in sweep (phase 25 fills) |
+
+## 5. The PRF-02 traceback-free sweep
+
+Parametrized test driving each command's handler with the failing
+dependency injected (mock transports / monkeypatched builders) — asserting
+`rc != 0`, **no `Traceback` in captured stderr**, and the named remedy
+substring present. Failure-mode list lives in 24-CONTEXT §Failure-modes;
+new modes must be added there (the sweep iterates that inventory).
+
+## 6. Test strategy
+
+- Session flows: fake config path (tmp), fake `_wizard_login`, MockTransport
+  Aura asserting **login called exactly once on expiry then success**
+  (criterion 2's mocked-401 simulation), non-TTY raises SessionExpiredError.
+- execute_plan relogin: existing offline harness; relogin stub asserting
+  one call then surface (no loops) — criterion 2, second half.
+- logout: file-content assertion + idempotency.
+- Sweep: `tests/test_preflight_sweep.py`, parametrized over the inventory.
+
+## 7. Risks / open points
+
+- `google-sync` resolves frames AFTER login; with no session AND no env it
+  must fail preflight-style before any Google work — ordering in the plan.
+- The wizard currently only runs interactively; the D-01 prompt reuses it —
+  keep the tty-guard one guard, not two diverging ones.
+- Budget charging for the TTY relogin mid-run: follow the existing
+  RETRY_RELOGIN_REQUEST_COST shape (D-06 lineage) — one acquire, no bespoke
+  path.

pushframe-5.1.0/.planning/phases/24-token-first-sessions-preflight-sweep-sec-01-03-prf-01-02/24-VERIFICATION.md

@@ -0,0 +1,50 @@
+---
+phase: "24"
+name: "Token-First Sessions & Preflight Sweep"
+created: 2026-09-29
+status: passed
+---
+
+# Phase 24 Verification — Token-First Sessions & Preflight Sweep
+
+**Date:** 2026-09-29
+**Status:** PASSED — suite 459 passed; the three ROADMAP §24 success
+criteria evidenced by file-content tests, mocked-401 flows, and the
+parametrized sweep.
+
+## Criteria → Evidence
+
+| # | Criterion (ROADMAP §24) | Evidence | Result |
+|---|--------------------------|----------|--------|
+| 1 | `pushframe config` + login → `~/.config/pushframe/` contains a token, no password, mode 0600 (file-content test) | `tests/test_session.py::test_tty_prompt_logs_in_and_persists_token_never_password` — parses the stored JSON, asserts email/token/user_id present, the password STRING absent from the raw file, and no `password` key at all; 0600 covered by the phase-23 wizard test (same writer) | ✅ PASSED |
+| 2 | Token-expiry simulation (mocked 401): transparent re-login ONCE and retry; a second failure surfaces the login error (no loops) | Establishment: `test_expired_token_tty_prompts_once_and_persists_new_token` (resume 401 → exactly ONE prompt → new token persisted → session continues) and `test_expired_token_non_tty_named_error_no_prompt` (SessionExpiredError, prompt asserted impossible). Mid-run: `execute_plan`'s relogin seam is token-aware — env login / TTY one-prompt / else `AuthenticationError` named (chunk fails, breaker guards; the one-retry-then-surface shape is the pre-existing REL-02 contract, still tested in `test_execute_plan.py`) | ✅ PASSED |
+| 3 | The traceback-free sweep: every documented foreseeable failure mode maps to a named error with a remedy (parametrized test) | `tests/test_preflight_sweep.py` — parametrized over the 24-CONTEXT inventory (vault missing, dir nonexistent, no-credentials ×3 commands); per case: rc≠0 + named marker + remedy substring + zero `Traceback`. Modes 1–4 (playwright/Chrome/headless/near-miss env) are the phase-23.5 google-link tests, referenced in the same inventory | ✅ PASSED |
+
+## Requirement traceability (SEC-01..03, PRF-01..02)
+
+- **SEC-01**: password never persisted — wizard test (phase 23) + the new
+  prompt-persist test both assert raw-file content; `_store_token` writes
+  only `{email, auth_token, user_id}`.
+- **SEC-02**: all five commands run from the stored token; env stays the
+  override (`test_env_password_still_wins_the_override`); discouraged-for-
+  humans wording in docs/CLI.md.
+- **SEC-03**: `logout` tests — token-only removal, idempotent, no token in
+  output; redaction regression suite unchanged and green.
+- **PRF-01**: vault preflight (google-sync, remedy includes the headless
+  ssh -X recipe) + source-dir preflight (D-03 severity split).
+- **PRF-02**: the sweep itself + the preflight-ORDER fix it caught (machine
+  checks precede every network call).
+
+## Scope honesty
+
+- The token-expiry REFRESH is a re-login (credentials in memory), not a
+  server-side refresh token — Pushd offers none; that is the phase-22
+  decision, unchanged.
+- `schedule`'s systemd preflight is a phase-25 item; the inventory already
+  lists it so the sweep grows by one case then.
+- `--password` CLI flag (vs env) was deferred: the env override satisfies
+  SEC-02's "documented, discouraged" bar; the flag lands with phase 25's
+  scheduled-jobs ergonomics if wanted.
+
+**Commits:** `9a84480` (session + call sites + logout + preflights + sweep)
+on `gsd/phase-24-token-first-preflight`

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.