SeedPass/memory-update.md

Memory Update (2026-03-01)

Nostr backup failure observability

• handle_post_to_nostr() previously printed only a generic ❌ Sync failed… when sync_vault() returned None, even if nostr_client.last_error had useful detail.
• PasswordManager.sync_vault_async() swallowed exceptions and returned None without reliably setting nostr_client.last_error, making root-cause diagnosis hard from CLI.

Changes made

• Updated sync_vault_async() to copy exception text into nostr_client.last_error before returning None.
• Updated handle_post_to_nostr() to include nostr_client.last_error in user-visible failure output and log line when available.
• Added regression tests:
  • test_handle_post_failure_shows_nostr_error
  • test_sync_vault_sets_last_error_on_exception

Testing note

• Could not run pytest in this environment because pytest is not installed (python3 -m pytest -> No module named pytest).

Nostr namespace reset workflow

• Added Nostr Settings menu actions for profile-scoped reset operations:
  • 8. Reset Nostr sync state clears manifest_id, delta_since, and last_sync_ts while preserving nostr_account_idx.
  • 9. Start fresh Nostr namespace (new key index) increments nostr_account_idx, clears sync metadata, and reinitializes the Nostr client when available.
• This provides a first-class path for users who want to ignore legacy Nostr history and publish/retrieve only new data under current deterministic behavior.
• Added tests for both handlers and menu dispatch to prevent regressions.

Documentation updates for Nostr reset workflow

• Added docs/nostr_namespace_reset.md documenting menu options 8 (reset sync state) and 9 (start fresh namespace), plus validation steps for robust publish/restore.
• Linked the new guide from docs/nostr_setup.md, docs/README.md, and root README.md.
• Exposed the guide in website docs navigation via landing/docs.html (Nostr Namespace Reset).

Nostr sync failure after namespace increment

• Root-cause pattern: when profile offline_mode is enabled, sync_vault_async() exits early and previously returned None without a helpful message, so UI showed only ❌ Sync failed….
• Fixes:
  • PasswordManager.sync_vault_async() now sets nostr_client.last_error for early-return cases (offline_mode, missing encrypted index, and missing publish result).
  • main.handle_post_to_nostr() now explicitly reports offline mode when no detailed error is present.
• Regression tests added:
  • src/tests/test_post_sync_messages.py::test_handle_post_failure_offline_mode_message
  • src/tests/test_background_vault_sync_paths.py::test_sync_vault_async_sets_offline_error
• Verified with local venv:
  • ./.venv/bin/pytest -q src/tests/test_post_sync_messages.py
  • ./.venv/bin/pytest -q src/tests/test_background_vault_sync_paths.py

Entry model expansion: document kind + universal date fields

• Added a new document entry kind across core enum, TUI, API, CLI, and agent secret resolution.
• Added universal date_added and date_modified fields for all entry kinds.
  • Creation now sets both fields.
  • Modification preserves date_added and updates date_modified.
  • Legacy entries are normalized in _load_index() by deriving date fields from modified_ts/updated.
• TUI now supports Document creation via a built-in line editor with basic commands (p, a, i <n>, e <n>, d <n>, w, q).
• Added document-specific display and edit flows in manager/display services.

Sync/policy compatibility notes

• Updated deterministic merge kind matrix to include document fields (content, file_type) for equal-timestamp backfill behavior.
• Agent defaults now include document in non-private allow-kinds, and agent secret resolution returns document content for document entries.

Tests and docs

• Added/updated tests for:
  • document entry roundtrip and CLI add command
  • universal date field presence/update semantics across all entry kinds
  • API create/modify behavior for document
  • large document Nostr sync roundtrip
• Added docs/entry_types.md and updated README/docs index and sync conflict docs.
• Verified with:
  • ./.venv/bin/pytest -q src/tests/test_cli_entry_add_commands.py src/tests/test_entry_add.py src/tests/test_entry_types_roundtrip.py src/tests/test_modify_entry_validation.py src/tests/test_api.py src/tests/test_api_new_endpoints.py src/tests/test_full_sync_roundtrip.py
  • Result: 141 passed.

Document file import/export workflows

• Added document file I/O at core layer:
  • EntryManager.import_document_file(path, ...)
  • EntryManager.export_document_file(index, output_path=None, overwrite=False)
• Added TUI support:
  • Add Entry > Document now supports New Document and Import Document File.
  • Document entry actions now include Export Document to File.
• Added automation surfaces:
  • CLI: entry import-document, entry export-document
  • API: POST /api/v1/entry/document/import, POST /api/v1/entry/{id}/document/export
• Regression coverage added for core file roundtrip, CLI commands, and API endpoints.

Agent document import/export commands

• Added dedicated agent CLI commands:
  • seedpass agent document-import --file <path>
  • seedpass agent document-export <query> (or --entry-id)
• Enforcement model for both commands:
  • Requires --fingerprint and non-interactive auth broker password resolution.
  • Denies unless policy allow_export_import is enabled.
  • Denies unless document kind is policy-allowed (allow_kinds / kind export check).
  • Supports scoped token enforcement with operation scopes (import for import, export for export).
  • Export honors approval gates when policy requires export approval.
  • Emits structured JSON responses and append-only audit events for granted/denied outcomes.
• Discovery updates:
  • Added document_io command hints to agent bootstrap-context payload.
  • Added document_io section to seedpass capabilities --format json security features.
• Added CLI tests for:
  • token-scoped agent document import success path
  • token-scoped agent document export success path
  • bootstrap context includes document command hints
• Environment note: could not run pytest in this shell because pytest is unavailable (python3 -m pytest reports module missing).

Test environment note (2026-03-01)

• Repo .venv already had pytest and typer; upgraded to pytest 9.0.2 and typer 0.24.1.
• New agent document I/O tests initially failed due mocked policy normalization (empty rules caused normalized allow_kinds to become empty).
• Fixed tests by adding explicit allow rule for document in mocked policies.
• Verification run:
  • .venv/bin/pytest -q src/tests/test_document_file_io.py src/tests/test_cli_entry_add_commands.py src/tests/test_api_new_endpoints.py src/tests/test_entry_types_roundtrip.py src/tests/test_full_sync_roundtrip.py src/tests/test_cli_agent_mode.py
  • Result: 150 passed.

Full-suite regression repair after document rollout

• Ran full suite after enabling agent document I/O and found 12 regressions (mostly stale tests).
• Fixed regressions by updating tests for:
  • new document add-menu option/mocks (handle_add_document),
  • expanded EntryService.modify_entry kwargs,
  • universal date_added/date_modified and custom_fields fields in entry expectations,
  • list_entries(sort_by="updated") relying on modified_ts,
  • legacy decrypt fallback monkeypatches to accept salt argument and revised iteration-call expectations.
• Verification: .venv/bin/pytest -q src/tests => 891 passed, 11 skipped.

Knowledge graph links integration (entry relationships)

• Added first-class graph edges to every entry via shared links field (list of {target_id, relation, note}).
• Implemented core link operations in EntryManager:
  • add_link(entry_id, target_id, relation, note)
  • remove_link(entry_id, target_id, relation=None)
  • get_links(entry_id) with resolved target label/kind.
• Added normalization/defaulting for links in index load path, including cache-return normalization to prevent stale in-memory schemas.
• Extended modify_entry(..., links=...) to allow full links replacement with validation.
• Search now matches link metadata (relation, note) and linked target labels, enabling graph-style discovery from existing index scans.
• Sync conflict equal-timestamp union now includes links alongside tags and custom_fields for deterministic convergence.
• Added API endpoints:
  • GET /api/v1/entry/{id}/links
  • POST /api/v1/entry/{id}/links
  • DELETE /api/v1/entry/{id}/links and PUT /api/v1/entry/{id} now accepts links.
• Added CLI graph commands:
  • seedpass entry link-add
  • seedpass entry links
  • seedpass entry link-remove plus entry modify --links-json.
• Documentation updated in README.md, docs/entry_types.md, and docs/sync_conflict_contract.md.
• Validation:
  • Focused suite: 140 passed
  • Full suite: 895 passed, 11 skipped.

Website/docs refresh for graph features

• Added dedicated graph docs page: docs/entry_graph.md.
• Updated docs indexes/navigation:
  • docs/README.md now lists entry_graph.md.
  • landing/docs.html sidebar now includes Entry Graph.
• Updated landing page feature cards (landing/index.html) to highlight:
  • Entry Graph Links
  • Graph-Aware Entry Ops CLI commands
• Updated docs cross-links:
  • docs/entry_types.md points to docs/entry_graph.md.
• Updated README feature bullets to include Entry Graph Links.

Landing graph example + help-hint refresh

• Added a visual graph snippet block to landing architecture section (landing/index.html) showing linked entries and graph query behavior.
• Styled graph snippet in landing/style.css (.graph-snippet) to match the terminal UI aesthetic.
• Expanded help/discovery surfaces for users and agents:
  • seedpass capabilities now includes a knowledge_graph security feature block with CLI/API graph commands and sync/search behavior.
  • Capabilities API discovery now lists /api/v1/entry/{id}/links.
  • Capabilities text output now explicitly mentions graph links and document workflows.
  • Capabilities help_hints now include graph/document command pointers.
  • agent bootstrap-context now includes commands.knowledge_graph hints.
  • Root CLI help string now mentions document I/O and entry graph links.
• Verification:
  • .venv/bin/pytest -q src/tests/test_typer_cli.py -k "capabilities_text or capabilities_json" src/tests/test_cli_agent_mode.py -k "bootstrap_context"
  • Result: 2 passed.

TUI v2 scaffold kickoff on beta

• Added docs/tui_v2_plan.md with phased migration plan, risk controls, and testing strategy for Textual-based TUI v2.
• Added experimental CLI command seedpass tui2 and diagnostics mode seedpass tui2 --check.
• Added new runtime-check/launcher scaffold package at src/seedpass/tui_v2/.
• Updated discoverability/docs surfaces:
  • docs/README.md includes tui_v2_plan.md
  • landing/docs.html includes TUI v2 Plan
  • README.md discovery snippet includes seedpass tui2 --check
  • capabilities root commands/help hints include tui2
• Validation:
  • py_compile for updated modules
  • pytest capabilities tests (2 passed)
  • .venv smoke run confirms seedpass tui2 --check emits runtime diagnostics.
• 2026-03-01: TUI v2 phase 1 moved from placeholder to functional read-only Textual shell. seedpass tui2 now passes a lazy entry_service_factory so vault/service init only happens when Textual is actually available, preventing unnecessary prompts on unavailable runtimes.
• Added focused CLI tests in src/tests/test_typer_cli.py for tui2 --check, unavailable + no fallback exit path, and legacy fallback fingerprint forwarding.
• 2026-03-01: TUI v2 phase 2 slice added in seedpass/tui_v2/app.py: archive/restore action (a), document editor mode (e) with save/cancel (Ctrl+S/Esc), and a persistent status line for operation feedback.
• Document editor uses TextArea when available and falls back to single-line input if unavailable, keeping runtime compatibility across Textual versions.
• 2026-03-01: TUI v2 gained Ctrl+P command palette with command parsing (help, open, search, filter, archive/restore, edit-doc/save-doc/cancel-edit, link-add, link-rm, refresh).
• Added a graph links panel in the right view that renders current entry links via EntryService.get_links and updates after palette link mutations.
• 2026-03-01: TUI v2 graph navigation expanded with relation-aware link filtering (l or link-filter) and quick neighbor traversal ([/] to change selected link, o or link-open to jump to target entry).
• Link panel now tracks selection state and displays active relation filter + selected link position to support KB-style navigation in large graphs.
• 2026-03-01: Phase 4 kickoff added docs/tui_v2_parity_checklist.md and linked it in docs indexes (docs/README.md, landing/docs.html) to track legacy-vs-v2 cutover readiness.
• TUI v2 large-vault UX/perf pass: entry list pagination (200/page, p/n, palette page-next/page-prev/page <n>) and document detail preview truncation (content_truncated) to avoid rendering extremely large payloads in the detail pane.
• 2026-03-01: TUI v2 error/recovery pass added unified failure recording (_record_failure) and retry workflow (x key + palette retry) across init/search/select/link/save/archive paths.
• Recovery hints are now included in status messages (for example, "Press 'x' to retry") and Phase 4 docs mark error/recovery flow work complete.
• 2026-03-01: Added docs/tui_v2_cutover_decision.md with explicit recommendation to keep legacy default for next release, required cutover gates, staged rollout, and rollback plan for switching seedpass default to TUI v2.
• Updated phase tracking docs to mark the cutover timing decision item complete and linked the memo in docs indexes.
• 2026-03-01: Began cutover-gate automation by extracting testable TUI v2 helpers (parse_palette_command, pagination_window, truncate_entry_for_display) from tui_v2/app.py.
• Added src/tests/test_tui_v2_helpers.py with coverage for palette parsing edge cases, pagination normalization, and large-vault pagination smoke sizes up to 50k rows.
• 2026-03-01: Added Textual interaction tests in src/tests/test_tui_v2_textual_interactions.py for pagination/search, document edit+save, link add/remove + neighbor open, and retry-after-failure.
• Introduced a test hook in launch_tui2(..., app_hook=...) so tests can capture and pilot the Textual app instance without starting a live terminal run.
• 2026-03-01: Added CI-like large-vault validation with explicit thresholds in src/tests/test_tui_v2_large_vault_validation.py (10k rows standard, 50k rows under --stress).
• Added docs docs/tui_v2_large_vault_validation.md with exact commands and budgets; parity checklist now marks large-vault CI-like validation complete.
• 2026-03-01: Added deterministic TUI v2 parity scenarios across entry kinds in src/tests/test_tui_v2_parity_scenarios.py (kind filters, archive/restore roundtrip, non-document edit guard).
• Completed help/docs alignment gate: updated seedpass tui2 help text, capabilities hints for keybindings/palette (Ctrl+P, p/n, x), and docs discoverability commands (seedpass tui2 --help/--check).
• 2026-03-01: Switched default root CLI interactive routing to TUI v2 in seedpass.cli.main (when no subcommand), with automatic legacy fallback when Textual runtime is unavailable.
• Added explicit one-release override flag --legacy-tui and updated test coverage (test_typer_cli.py) for default TUI v2 launch, forced legacy path, and root fallback behavior.
• 2026-03-01: UX pass for TUI v2 added help overlay (?), quick jump input (j), pane focus switching (1/2/3) with visual focus borders, mode-tagged status line, and an activity log panel of recent actions.
• Added document dirty-state UX improvements (Edit mode [*] marker, no-op save guard) and updated Textual interaction/parity tests for Textual 8-compatible action-driven control paths.
• 2026-03-01: Visual polish pass for TUI v2 updated panel styling hierarchy (stronger status/pane contrast), refined left-panel summaries, improved help overlay readability, and added labeled headers for entry/detail and links sections.
• UI copy now emphasizes current selection/filter context while keeping deterministic action affordances unchanged; full TUI-focused test slice remains green.
• 2026-03-01: Reduced TUI v2 status noise by deduplicating repeated status messages before appending to status bar/activity log.
• Verified critical coverage gate against existing full coverage artifact (artifacts/coverage/coverage.json): all default threshold modules pass (main/core manager/core encryption/core migrations).

2026-03-01 Determinism test infrastructure hardening

• Added a dedicated determinism lane with scripts/run_determinism_tests.sh and wired scripts/run_ci_tests.sh to run it by default (DETERMINISM_GATE=1, disable with DETERMINISM_GATE=0).
• Added pytest marker support for determinism (pyproject.toml, src/tests/conftest.py) and a --determinism-only selector that skips non-determinism tests.
• Expanded deterministic regression vectors in src/tests/test_deterministic_artifact_regression.py:
  • pinned entropy-stream SHA-256 vectors for indexes 0,1,352,1024
  • pinned password outputs for policy variants (default, safe specials, no specials, exclude ambiguous, restricted special charset)
• Marked existing deterministic suites so they run in the determinism lane: password helpers/policy plus seed, SSH, PGP, and Nostr determinism tests.
• Verified determinism lane now executes 23 focused tests and fails fast on derivation drift.

2026-03-01 Determinism gates + cross-process + size-tier sync tests

• Added scripts/check_determinism_suite.py and wired it into scripts/run_determinism_tests.sh.
• Determinism gate now enforces both a minimum test count (DETERMINISM_MIN_TESTS, default 25) and required determinism files, preventing accidental suite erosion.
• Added unit tests for determinism gate parser logic in src/tests/test_check_determinism_suite.py.
• Added cross-process determinism regression in src/tests/test_cross_process_determinism.py; derives artifacts in separate Python processes and asserts exact JSON identity.
• Expanded size-tier sync integrity coverage:
  • src/tests/test_document_file_io.py includes large document import/export and portable backup restore invariance checks (hash/equality).
  • src/tests/test_full_sync_roundtrip.py includes parameterized large document Nostr sync roundtrip with content hash checks.
  • src/tests/test_nostr_snapshot.py includes chunk hash and gzip roundtrip integrity across multiple payload size tiers.
• Current determinism lane status after updates: 43 passed, 916 skipped.

2026-03-01 TUI v2 agent harness + deep coverage expansion

• Added scripts/ai_tui2_agent_test.py as a deterministic agent-style TUI v2 harness using Textual pilot mode; emits timestamped JSON reports in artifacts/agent_tui2_test/.
• Added test/process documentation: docs/agent_test_format.md with repeatable commands for TUI v2, legacy interactive harness, CLI/CUI, API, and determinism gate runs.
• Fixed legacy harness invalid-input regression after Document type addition: in scripts/ai_tui_agent_test.py, Add Entry invalid choice now uses 99 instead of 9.
• Added src/tests/test_tui_v2_action_matrix.py to exercise broad TUI v2 action and palette paths (including guards/failure/retry/event handlers).
• Fixed a real TUI v2 help-overlay bug in src/seedpass/tui_v2/app.py where [/] text triggered Textual markup parsing errors (MarkupError).
• Latest TUI v2 focused coverage run:
  • Command: test helper/interactions/parity/large-vault/action-matrix suites with --cov=seedpass.tui_v2.app
  • Result: 25 passed, 2 skipped
  • Coverage: 86% for src/seedpass/tui_v2/app.py (up from ~57%).
• Harness validation results:
  • scripts/ai_tui2_agent_test.py --scenario extended: passed
  • scripts/ai_tui_agent_test.py --scenario core: passed

2026-03-01 Installer + TUI v2 preflight fix (gray-screen mitigation)

• Root cause found for "blank/gray screen" reports: TUI v2 was initializing PasswordManager inside Textual mount via entry_service_factory, so password/setup prompts could occur behind the Textual screen and appear as a frozen UI.
• Updated src/seedpass/cli/__init__.py to pre-initialize entry service before launching Textual (_prime_tui2_service), then pass the ready service into launch_tui2.
• Added explicit fallback/error behavior:
  • default seedpass: preflight failures now fall back to legacy TUI with details.
  • seedpass tui2 --no-fallback-legacy: preflight failures now return exit code 1 with a clear error.
• Updated installer scripts/install.sh to run seedpass tui2 --check after install and warn when Textual runtime is unavailable, plus print a legacy fallback hint for users seeing blank/gray startup.
• Added regression coverage in src/tests/test_typer_cli.py for preflight behavior and adapted existing TUI launch tests to mock preflight service creation.

2026-03-01 TUI v2 parity slice: reveal + QR integration

• Added Textual TUI v2 sensitive-data actions:
  • Keybindings: v reveal selected secret, g show QR.
  • Palette commands: reveal, qr.
• Implemented reveal support for entry kinds: password, seed, managed_account, totp.
• Implemented QR rendering in-app (ASCII QR panel) for:
  • TOTP (otpauth:// payload)
  • Seed / managed account seed (SeedQR digit payload)
• Added a dedicated #secret-detail panel in the right pane and reset-on-selection behavior to avoid stale secret display.
• Extended core EntryService API with deterministic seed retrieval methods used by TUI v2:
  • get_seed_phrase(entry_id)
  • get_managed_account_seed(entry_id)
• Added/updated tests for helper QR rendering, TUI reveal/QR workflows, and service wrappers; targeted suite passed.

2026-03-01 TUI v2 parity slice: SSH/PGP/Nostr + secret mode behavior

• Extended TUI v2 sensitive reveal support to additional kinds: ssh, pgp, and nostr.
• Added legacy-aligned confirmation semantics in TUI v2:
  • reveal confirm required for high-risk reveals (seed, managed_account, ssh, pgp).
  • qr private confirm required for Nostr private-key QR rendering.
• Added qr mode parsing (qr [public|private] [confirm]) and retained default safe behavior (public for Nostr).
• Integrated secret-mode behavior into TUI reveal flow:
  • when secret mode is enabled, reveal copies sensitive value to clipboard and avoids on-screen plaintext output for that reveal.
• Expanded EntryService API for TUI parity and safe abstraction from manager internals:
  • get_ssh_key_pair, get_pgp_key, get_nostr_key_pair
  • get_secret_mode_enabled, get_clipboard_clear_delay, copy_to_clipboard
• Added/updated tests covering confirmation-gated flows, Nostr private QR confirmation, and secret-mode clipboard behavior.

2026-03-01 TUI v2 visual alignment with landing page

• Updated Textual TUI v2 default styling to mirror landing-page palette tokens:
  • background: #080a0c / panel: #0d1114
  • primary text: #97b8a6 / bright text: #daf2e5
  • accent borders/focus: #58f29d, #2abf75, #274533, #1a3024
• Styled Header/Footer/Input/ListView/ListItem focus/selection states to reduce default Textual blue and align with SeedPass mint-green terminal aesthetic.
• Added website-style icon semantics into TUI copy and sensitive panel titles (key/mobile/network/lock/bolt/document/users/seed mappings) to improve visual continuity between landing and app.