pushframe 5.0.5__tar.gz → 5.0.7__tar.gz

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

@@ -5,15 +5,15 @@
 
 ## 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: 24 — VERIFIED (passed)
+Current Plan: 24-01 complete
+Total Plans in Phase: 1 (phase 24)
+Status: Verified — next: phase 25 (Multi-frame + systemd)
 
 ## 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)
+- [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)
 
 ## Completed Milestones

pushframe-5.0.7/.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.0.7/.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.0.7/.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.0.7/.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.0.7/.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.0.5 → pushframe-5.0.7}/CHANGELOG.md

@@ -16,6 +16,44 @@ frames; it is not affiliated with Aura Frames Inc.
 
 - (v5.1 work will land here)
 
+## [5.0.7] — 2026-09-29
+
+### Added (phase 24: Token-First Sessions & Preflight Sweep)
+
+- **One session path for every command** (SEC-01/02): `inspect`,
+  `reconcile`, `sync`, `push` and `google-sync` now run from the stored
+  token session (0600) with no password and no login call; env vars stay
+  the override; a terminal session gets ONE password prompt whose token is
+  persisted (SEC-01: the password is never written anywhere — file-content
+  tested); non-interactive runs without credentials fail named.
+- **Token expiry** (D-01): a 401 while resuming the stored session prompts
+  once in a terminal (new token persisted, command continues) and raises
+  `SessionExpiredError` with the remedy in scheduled runs. `execute_plan`'s
+  401-retry relogin is token-aware (it previously assumed a password).
+- **`pushframe logout`** (SEC-03, D-02): deletes the stored token (and only
+  the token) — email and settings survive, mode stays 0600, idempotent.
+- **Preflights** (PRF-01, D-03): `google-sync` checks the vault up front
+  (remedy: `google-link` + the headless ssh -X recipe); `sync`/`push` fail
+  named on a nonexistent source directory BEFORE any network call (an
+  empty directory remains a friendly "nothing to do").
+- **The traceback-free sweep** (PRF-02): a parametrized test over the
+  failure-mode inventory proves every foreseeable mode ends named, with a
+  remedy, and never a traceback.
+
+### Changed
+
+- DI contract, now enforced everywhere: a call site NEVER re-authenticates
+  an injected Aura (tests, `doctor`, pipelines). Login-failure shapes are
+  owned by the session path.
+
+## [5.0.6] — 2026-09-29
+- **`pushframe doctor`** — the field write-probe the venus regressions
+  demanded: one 4×4 test image through the REAL write path (S3 +
+  select_asset + batch_update), verify + cleanup, then a GO/NO-GO verdict
+  with the 401 body classified. `--no-write` for reads-only. Closes the
+  release gap: green tests + green journeys never proved THIS machine can
+  write TODAY.
+
 ## [5.0.5] — 2026-09-29
 
 ### Added
@@ -50,6 +88,40 @@ frames; it is not affiliated with Aura Frames Inc.
 - The abort message on the 5-consecutive-failures breaker now states what
   to expect: confirmed items ARE on the frame, the next run recognizes
   them and will not upload them twice, wait ~30 min before retrying.
+- **Scoped-trip honesty** (second venus regression): `pushframe status`
+  staying green does NOT mean writes will work — the anti-abuse trip can
+  be scoped to the assets surface (write endpoints AND the
+  `asset_for_local_identifier` verify-probe read) while login/frames keep
+  answering. The abort message no longer suggests status as an all-clear;
+  it prescribes 60+ min from the abort and a single, solitary retry call.
+- **"Request Unauthenticated" + logout:true identified as the trip's
+  disguise** (fourth venus regression, decisive capture): the body arrived
+  on a FRESH token immediately after a successful re-login, one item after
+  a doctor probe had WRITTEN fine — so Pushd's "Request Unauthenticated"
+  here means "we refuse your writes (trip)", not "your token is bad". The
+  classifier now pins this exact body to the wait-60+-min verdict and
+  warns against a pointless re-login.
+- **First-occurrence trip stop**: a write 401 carrying that proven body
+  aborts the run IMMEDIATELY (`TripDetectedError`) — no iterating to the
+  5-failure backstop, no re-login, no resend (all feed the trip). Budget
+  force-reconciled; the message states what is confirmed on the frame and
+  that the next run resumes cleanly. (Also fixed en route: TripDetected
+  propagates through every chunk-level handler — the generic per-chunk
+  attribution branch would otherwise swallow it as ordinary failures.)
+- **`google-sync --batch-size N`**: the trip keys on per-batch volume (a
+  1-item doctor write passed seconds before a 50-item chunk was refused),
+  so an operator can stay under the detection threshold (e.g. 10).
+  Forwarded only when supplied — the historical default (50) otherwise
+  rules. The anti-trip drill (doctor → wait → batch-size) is documented in
+  docs/CLI.md.
+- **401 bodies are captured and classified** (third venus regression): an
+  HTTP 401 exception now carries the server's response body (redacted
+  through the same filter as request logs, truncated to 300 chars, also
+  debug-logged) — so per-item failure reasons, verify-probe errors and the
+  consecutive-failures abort all show WHY the write was refused. The abort
+  classifies the body: a silent/generic envelope reads as the anti-abuse
+  trip (wait 60+ min, single retry); a body naming the token/session reads
+  as a token problem (re-login, retry once, do not wait an hour).
 
 ### Changed
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pushframe
-Version: 5.0.5
+Version: 5.0.7
 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.5 → pushframe-5.0.7}/docs/CLI.md

@@ -12,6 +12,7 @@ talks to the frame over your local network — everything goes through your Aura
 ## Contents
 
 - [Global usage](#global-usage)
+- [`doctor`](#doctor--can-this-machine-write-today)
 - [`config`](#config--set-up-credentials-and-settings-once)
 - [`status`](#status--check-credentials-and-list-frames)
 - [`inspect`](#inspect--look-at-one-frame)
@@ -25,6 +26,22 @@ talks to the frame over your local network — everything goes through your Aura
 
 ## Global usage
 
+One session path (phase 24): every command authenticates the same way —
+`PUSHFRAME_EMAIL`/`PUSHFRAME_PASSWORD` env (override; discouraged for
+humans), else the **stored token session** from `pushframe config` (no
+login call, no password), else ONE interactive password prompt whose token
+is persisted (the password is never written anywhere). Non-interactive runs
+never prompt: without any credential they fail named with the remedy.
+
+On an expired token: a terminal session prompts once and continues; a
+scheduled run reports `SessionExpiredError` with the remedy.
+
+### `pushframe logout`
+
+Deletes the stored session token — and only the token. Your email and
+settings stay (the next `pushframe config` proposes your email). Idempotent;
+token material is never printed.
+
 ```
 usage: pushframe [-h] [--version] [--debug] {status,inspect,sync,push} ...
 
@@ -70,6 +87,45 @@ Resolution rules:
 Ambiguity is never resolved silently, so a loose substring can't quietly target the wrong
 frame.
 
+## `doctor` — can this machine write today?
+
+The pre-flight gate for any long write run. Offline tests and install
+journeys cannot prove a real WRITE lands on a real frame from THIS machine,
+THIS IP, today — the anti-abuse layer can be scoped per-IP/per-surface
+(venus, 2026-09: reads green, writes 401). Doctor probes exactly that,
+deliberately, with one 4×4 test image:
+
+```bash
+pushframe doctor            # session → frames → WRITE probe → verify → cleanup
+pushframe doctor --no-write # session + frames reads only (zero writes)
+pushframe doctor --frame "Cadre"
+```
+
+Five checks, one unambiguous verdict: **GO** (writes work from here, now —
+launch the sync) or **NO-GO** with the captured 401 server body and its
+classification (anti-abuse trip vs token problem). Charges ~6 write-budget
+tokens; safe to repeat; never run it in CI.
+
+### When the anti-abuse layer refuses your writes
+
+Pushd's anti-abuse layer can refuse writes while reads and login keep
+working (proven venus, 2026-09). The refusal body says
+`"Request Unauthenticated"` — **that is the trip's disguise, not a token
+problem**. pushframe recognizes it and stops on the FIRST refusal (no
+retry, no re-login — both feed the trip). The drill:
+
+1. `pushframe doctor` before any sync (GO = the write surface is open NOW)
+2. Trip detected → wait **60+ min** from the stop, then `pushframe doctor` again
+3. If doctor passes but a sync still trips immediately, lower the per-batch
+   volume — the trip keys on batch size (a 1-item write may pass where a
+   50-item chunk is refused):
+   ```bash
+   pushframe google-sync Cadre --frame "Cadre de Fabrice" --apply --yes --batch-size 10
+   ```
+
+Progress is never lost: only confirmed writes are remembered, and the next
+run uploads the remainder once — never twice.
+
 ## `config` — set up credentials and settings once
 
 The conversational alternative to hand-managed environment variables. Every value

{pushframe-5.0.5 → pushframe-5.0.7}/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.5"
+__version__ = "5.0.7"