lost-sessions 0.0.0.dev0__tar.gz → 0.2.0__tar.gz

lost_sessions-0.2.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: lost_sessions
+Version: 0.2.0
+Summary: Recover agent sessions that a reboot dropped, with pluggable session managers
+Author: Steve Morin
+Author-email: Steve Morin <steve.morin@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: click>=8.1.0
+Requires-Dist: pluggy>=1.5.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: textual>=8,<9
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/smorinlabs/lost-sessions
+Project-URL: Repository, https://github.com/smorinlabs/lost-sessions
+Project-URL: Documentation, https://lost-sessions.readthedocs.io/en/latest/
+Project-URL: Changelog, https://github.com/smorinlabs/lost-sessions/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/smorinlabs/lost-sessions/issues
+Description-Content-Type: text/markdown
+
+# lost-sessions
+
+Recover the agent sessions a reboot dropped. `lost-sessions` finds Claude Code,
+Codex, Muse and OpenCode sessions that started before the last boot and that no
+session manager will restore, then prints their resume commands or reopens
+them in Herdr or Rex.
+
+Agents and session managers are plugins, the way
+[`simonw/llm`](https://llm.datasette.io/en/stable/plugins/) does plugins. The
+six built-ins use the same interface a third-party `lost-sessions-<name>`
+package uses.
+
+## Install
+
+```bash
+uv tool install "lost-sessions @ git+https://github.com/smorinlabs/lost-sessions"
+```
+
+This installs the latest `main`. Python 3.13 or later. macOS and Linux. Tagged
+releases, and a PyPI package, follow once publishing is set up.
+
+## Use
+
+| Command | What it does |
+|---|---|
+| `lost-sessions recover` | Interactive menu: choose Print, Rex or Herdr for each dropped session, then run them all |
+| `lost-sessions list` | Numbered list of the dropped sessions in the window |
+| `lost-sessions open REF… --print\|--rex\|--herdr [--focus [REF]]` | Print or open sessions without the menu; `REF@DEST` picks a destination |
+| `lost-sessions workspaces` | The Herdr workspaces and Rex sessions you can open sessions in |
+| `lost-sessions history [--json]` | Every action taken, from `${XDG_STATE_HOME:-~/.local/state}/lost-sessions/history.jsonl` |
+| `lost-sessions inventory [--json]` | Read-only inventory of every agent session on this machine |
+| `lost-sessions plugins [--all]` | Installed plugins, as JSON |
+| `lost-sessions install PKG…` / `uninstall PKG…` | Add or remove plugins in the `uv tool` install |
+
+The window is every session that started before the last boot and was active
+since its start: by default 00:00 on the day before the boot. `--since` sets
+that start, as a date (`--since 2026-11-09`) or a duration back from now
+(`--since 3d`); pick an earlier start to widen the window. Running sessions
+and sessions a manager restores are hidden unless `--all`.
+
+## Library
+
+```python
+from lost_sessions.inventory import collect, select
+
+inventory = collect()  # an Inventory: sessions, census, sources, failed
+for session in select(inventory, live=True):
+    print(session.tool, session.id, session.resume)
+```
+
+## Plugins
+
+See [Writing plugins](docs/source/reference/plugins.md) for the hooks, the
+`AgentTool` and `SessionManager` contracts, and how to test and install a
+plugin. The design is in
+[design 0006](docs/design/0006-lost-sessions-plugin-design.md).
+
+## Develop
+
+```bash
+make bootstrap   # bare machines only: just + uv
+just setup       # dev environment and git hooks
+just check       # tests, lint, types, import contracts
+```
+
+See [AGENTS.md](AGENTS.md) for the full workflow.

lost_sessions-0.2.0/README.md

@@ -0,0 +1,66 @@
+# lost-sessions
+
+Recover the agent sessions a reboot dropped. `lost-sessions` finds Claude Code,
+Codex, Muse and OpenCode sessions that started before the last boot and that no
+session manager will restore, then prints their resume commands or reopens
+them in Herdr or Rex.
+
+Agents and session managers are plugins, the way
+[`simonw/llm`](https://llm.datasette.io/en/stable/plugins/) does plugins. The
+six built-ins use the same interface a third-party `lost-sessions-<name>`
+package uses.
+
+## Install
+
+```bash
+uv tool install "lost-sessions @ git+https://github.com/smorinlabs/lost-sessions"
+```
+
+This installs the latest `main`. Python 3.13 or later. macOS and Linux. Tagged
+releases, and a PyPI package, follow once publishing is set up.
+
+## Use
+
+| Command | What it does |
+|---|---|
+| `lost-sessions recover` | Interactive menu: choose Print, Rex or Herdr for each dropped session, then run them all |
+| `lost-sessions list` | Numbered list of the dropped sessions in the window |
+| `lost-sessions open REF… --print\|--rex\|--herdr [--focus [REF]]` | Print or open sessions without the menu; `REF@DEST` picks a destination |
+| `lost-sessions workspaces` | The Herdr workspaces and Rex sessions you can open sessions in |
+| `lost-sessions history [--json]` | Every action taken, from `${XDG_STATE_HOME:-~/.local/state}/lost-sessions/history.jsonl` |
+| `lost-sessions inventory [--json]` | Read-only inventory of every agent session on this machine |
+| `lost-sessions plugins [--all]` | Installed plugins, as JSON |
+| `lost-sessions install PKG…` / `uninstall PKG…` | Add or remove plugins in the `uv tool` install |
+
+The window is every session that started before the last boot and was active
+since its start: by default 00:00 on the day before the boot. `--since` sets
+that start, as a date (`--since 2026-11-09`) or a duration back from now
+(`--since 3d`); pick an earlier start to widen the window. Running sessions
+and sessions a manager restores are hidden unless `--all`.
+
+## Library
+
+```python
+from lost_sessions.inventory import collect, select
+
+inventory = collect()  # an Inventory: sessions, census, sources, failed
+for session in select(inventory, live=True):
+    print(session.tool, session.id, session.resume)
+```
+
+## Plugins
+
+See [Writing plugins](docs/source/reference/plugins.md) for the hooks, the
+`AgentTool` and `SessionManager` contracts, and how to test and install a
+plugin. The design is in
+[design 0006](docs/design/0006-lost-sessions-plugin-design.md).
+
+## Develop
+
+```bash
+make bootstrap   # bare machines only: just + uv
+just setup       # dev environment and git hooks
+just check       # tests, lint, types, import contracts
+```
+
+See [AGENTS.md](AGENTS.md) for the full workflow.

lost_sessions-0.2.0/pyproject.toml

@@ -0,0 +1,236 @@
+[project]
+name = "lost_sessions"
+version = "0.2.0"
+description = "Recover agent sessions that a reboot dropped, with pluggable session managers"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "click>=8.1.0",
+    "pluggy>=1.5.0",
+    "pydantic>=2.0.0",
+    "textual>=8,<9",
+]
+
+[[project.authors]]
+name = "Steve Morin"
+email = "steve.morin@gmail.com"
+
+[project.scripts]
+lost-sessions = "lost_sessions.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/smorinlabs/lost-sessions"
+Repository = "https://github.com/smorinlabs/lost-sessions"
+Documentation = "https://lost-sessions.readthedocs.io/en/latest/"
+Changelog = "https://github.com/smorinlabs/lost-sessions/blob/main/CHANGELOG.md"
+Issues = "https://github.com/smorinlabs/lost-sessions/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.1.0",
+    "ty>=0.0.1a16",
+    "ruff>=0.1.0",
+    "types-Pygments",
+    "cogapp",
+    "bandit>=1.8.0",
+    "codespell>=2.4.0",
+    "editorconfig-checker>=3.0.0",
+    "yamllint>=1.35.0",
+    "pip-audit>=2.9.0",
+    "twine>=6.1.0",
+    "syrupy>=4.8.0",
+    "import-linter>=2.0",
+    "pytest-xdist>=3.6",
+    "pytest-timeout>=2.3",
+    "pytest-randomly>=3.15",
+    "hypothesis>=6.100",
+]
+docs = [
+    "sphinx>=7.0.0",
+    "sphinx-rtd-theme",
+    "furo",
+    "myst-parser",
+    "sphinx-autodoc-typehints",
+    "cogapp",
+    "sphinx-copybutton",
+    "sphinx-autobuild",
+    "sphinxext-opengraph",
+]
+
+[build-system]
+requires = ["uv_build>=0.5,<1.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "lost_sessions"
+module-root = "src"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+fix = true
+exclude = [
+    ".git",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "docs/source/conf.py",
+    "src/lost_sessions/_version.py",
+    "prototypes",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "B",
+    "C4",
+    "UP",
+    "N",
+    "RUF",
+    "W",
+    "YTT",
+    "S",
+    "ANN",
+]
+ignore = [
+    "E501",
+    "W293",
+]
+unfixable = []
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 88
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"tests/*" = [
+    "S101",
+    "S105",
+    "S106",
+    "S603",
+    "S607",
+    "ANN",
+    "F811",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.pyright]
+include = [
+    "src/lost_sessions",
+    "tests",
+]
+exclude = [
+    "**/node_modules",
+    "**/__pycache__",
+]
+typeCheckingMode = "strict"
+pythonVersion = "3.13"
+useLibraryCodeForTypes = true
+reportMissingImports = true
+reportMissingTypeStubs = true
+reportUnknownParameterType = true
+reportUnknownArgumentType = true
+reportUnknownLambdaType = true
+reportUnknownVariableType = true
+reportUnknownMemberType = true
+reportMissingTypeArgument = true
+reportInvalidTypeVarUse = true
+reportUnnecessaryIsInstance = true
+reportUnnecessaryCast = true
+reportUnnecessaryComparison = true
+reportDuplicateImport = true
+reportPrivateUsage = "warning"
+reportUnusedImport = true
+reportUnusedVariable = true
+reportUnusedFunction = true
+reportUnusedClass = true
+
+[tool.pyright.defineConstant]
+DEBUG = true
+
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.rules]
+ambiguous-protocol-member = "error"
+blanket-ignore-comment = "error"
+invalid-ignore-comment = "error"
+ignore-comment-unknown-rule = "error"
+ineffective-final = "error"
+invalid-enum-member-annotation = "error"
+invalid-named-tuple-override = "error"
+
+[tool.ty.terminal]
+error-on-warning = false
+
+[tool.bandit]
+exclude_dirs = [
+    "tests",
+    ".venv",
+    "build",
+    "dist",
+]
+skips = []
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+markers = [
+    "live: requires external services",
+    "slow: takes >1s",
+]
+addopts = "-m 'not live and not slow'"
+strict_markers = true
+timeout = 60
+timeout_method = "thread"
+
+[tool.coverage.run]
+branch = true
+
+[tool.codespell]
+skip = ".git,.venv,build,dist,node_modules,uv.lock,bun.lock,*.lock,docs/_build,*.svg,*.cast,.ruff_cache,.pytest_cache,.mypy_cache,.ty_cache,*.log"
+ignore-words-list = "ans,porjects,unparseable,wit"
+check-filenames = true
+check-hidden = false
+
+[tool.importlinter]
+root_package = "lost_sessions"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "lost-sessions is a CLI: no web framework imports"
+type = "forbidden"
+source_modules = ["lost_sessions"]
+forbidden_modules = [
+    "fastapi",
+    "starlette",
+    "uvicorn",
+]
+
+[[tool.importlinter.contracts]]
+name = "core reaches built-in plugins only through the plugin manager"
+type = "forbidden"
+source_modules = [
+    "lost_sessions.cli",
+    "lost_sessions.hookspecs",
+    "lost_sessions.plugins",
+]
+forbidden_modules = ["lost_sessions.default_plugins"]

lost_sessions-0.2.0/pyproject.toml.orig

@@ -0,0 +1,300 @@
+# Copyright (c) 2026, Steve Morin
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+[project]
+name = "lost_sessions"
+# ITM-070 — static version (ADR-06 cutover). release-please bumps this.
+version = "0.2.0"
+description = "Recover agent sessions that a reboot dropped, with pluggable session managers"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT" # PEP 639 license expression (ITM-070, round-19).
+authors = [{ name = "Steve Morin", email = "steve.morin@gmail.com" }]
+classifiers = [
+  # ITM-070 — round-19. py3.13+ only (per ITM-033 floor); MIT classifier
+  # intentionally omitted (PEP 639 license expression above is the single
+  # source of truth — duplication would drift).
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "click>=8.1.0",
+  "pluggy>=1.5.0",     # plugin manager, as in simonw/llm (design Section 4)
+  "pydantic>=2.0.0",   # every data object is a Pydantic model (design Q-G2)
+  "textual>=8,<9",     # the `recover` menu; imported lazily
+]
+
+# ITM-063 — PEP 735 dependency-groups (round-13 decision). Replaces
+# [project.optional-dependencies] dev+docs. Install via `uv sync --group <name>`.
+[dependency-groups]
+dev = [
+  "pytest>=7.0.0",
+  "pytest-cov>=4.1.0",
+  "ty>=0.0.1a16",        # per ADR-03 (pre-1.0; bump as needed)
+  "ruff>=0.1.0",
+  "types-Pygments",
+  "cogapp",
+  # WL-001 — hook/CI tools pinned via uv.lock (run with `uv run`, not floating
+  # `uvx`), so local hooks and CI use the same version and upgrades arrive as
+  # reviewable dependabot PRs instead of surprise breakage.
+  "bandit>=1.8.0",
+  "codespell>=2.4.0",
+  "editorconfig-checker>=3.0.0",
+  "yamllint>=1.35.0",
+  "pip-audit>=2.9.0",            # WL-014 — `just audit` + scheduled dep-audit workflow
+  "twine>=6.1.0",                # WL-004 — dist metadata check in the build-smoke CI job
+  "syrupy>=4.8.0",               # WL-023 — CLI --help snapshot tests
+  "import-linter>=2.0",          # HEX-30 — architectural layer/boundary rules
+  # Testing-strategy shortlist (ADR-0019).
+  "pytest-xdist>=3.6",     # WL-008 — parallel test execution (`-n auto`)
+  "pytest-timeout>=2.3",   # WL-009 — per-test timeout guard (hung test fails loud)
+  "pytest-randomly>=3.15", # WL-010 — randomized order surfaces inter-test coupling
+  "hypothesis>=6.100",     # WL-013 — property-based tests at parse/serialize seams
+]
+
+docs = [
+  "sphinx>=7.0.0",
+  "sphinx-rtd-theme",
+  "furo",
+  "myst-parser",
+  "sphinx-autodoc-typehints",
+  "cogapp",
+  "sphinx-copybutton",
+  "sphinx-autobuild",
+  "sphinxext-opengraph",      # https://github.com/wpilibsuite/sphinxext-opengraph
+]
+
+
+[project.scripts]
+lost-sessions = "lost_sessions.cli:main"
+
+# ITM-072 — package metadata URLs (round 19).
+[project.urls]
+Homepage = "https://github.com/smorinlabs/lost-sessions"
+Repository = "https://github.com/smorinlabs/lost-sessions"
+Documentation = "https://lost-sessions.readthedocs.io/en/latest/"
+Changelog = "https://github.com/smorinlabs/lost-sessions/blob/main/CHANGELOG.md"
+Issues = "https://github.com/smorinlabs/lost-sessions/issues"
+
+# ITM-073 — uv_build (ADR-06 cutover; replaces Hatchling + hatch-vcs).
+[build-system]
+requires = ["uv_build>=0.5,<1.0"]
+build-backend = "uv_build"
+
+# ITM-074 — uv_build module configuration.
+# Template uses a flat layout (package at repo root, not src/) — must set
+# module-root = "" so uv_build doesn't expect src/lost_sessions/.
+[tool.uv.build-backend]
+module-name = "lost_sessions"
+# src/ layout (Decision 1) — package now lives at src/lost_sessions/.
+module-root = "src"
+
+[tool.ruff]
+# ITM-018 reconciled config (round-2). Merge: template's stricter rule
+# selection + source's ignore rationale. target-version reflects ITM-033
+# Python-floor bump.
+target-version = "py313"
+line-length = 88
+
+lint.select = [
+  "E",   # pycodestyle errors
+  "F",   # pyflakes
+  "I",   # isort
+  "B",   # flake8-bugbear
+  "C4",  # flake8-comprehensions
+  "UP",  # pyupgrade
+  "N",   # pep8-naming
+  "RUF", # Ruff-specific rules
+  "W",   # pycodestyle warnings
+  "YTT", # flake8-2020
+  "S",   # flake8-bandit
+  "ANN", # flake8-annotations — enforce annotation *presence* (P03; the gap ty
+  # deliberately does NOT check). Scoped to the package via
+  # per-file-ignores below; tests/ are exempt.
+]
+
+# Source's ignore rationale (round-2): line-length handled by formatter;
+# template-applicable subset adopted (B904/B007 omitted — source-specific
+# patterns that don't apply here).
+lint.ignore = [
+  "E501", # line too long (formatter owns this)
+  "W293", # whitespace on blank line (formatter owns trim_trailing)
+]
+lint.unfixable = [] # Rules that should not be fixed automatically
+
+# Allow autofix behavior for specific rules
+fix = true
+
+# Exclude files/folders
+exclude = [
+  ".git",
+  ".venv",
+  "__pycache__",
+  "build",
+  "dist",
+  "docs/source/conf.py",
+  "src/lost_sessions/_version.py",
+  "prototypes",                          # P0004 template-press engine prototypes (own lint config in template-press)
+]
+# Per-file-ignores
+[tool.ruff.lint.pycodestyle]
+max-line-length = 88
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"] # Ignore unused imports in __init__.py files
+"tests/*" = [
+  "S101",
+  "S105",
+  "S106",
+  "S603",
+  "S607",
+  "ANN",
+  "F811",
+] # asserts + annotations optional; tests drive the CLI and stand-ins via subprocess;
+# F811: importing a pytest fixture and naming it as a parameter is the normal pattern
+# S101: assert statements removed under -O — security risk if assert is the only gate.
+# S105/S106: hardcoded password strings/variables in code.
+
+# ITM-018 — explicit format config (round-2; mirrors source). Values match Ruff
+# defaults but being explicit prevents silent drift if defaults change.
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+# Pyright/Pylance (IDE) strict type checking — formerly pyrightconfig.json.
+# CI typechecking runs ty (ADR-03); this section drives the VS Code Pyright
+# extension and ad-hoc `pyright` runs.
+[tool.pyright]
+include = ["src/lost_sessions", "tests"]
+exclude = ["**/node_modules", "**/__pycache__"]
+defineConstant = { DEBUG = true }
+typeCheckingMode = "strict"
+pythonVersion = "3.13"
+useLibraryCodeForTypes = true
+reportMissingImports = true
+reportMissingTypeStubs = true
+reportUnknownParameterType = true
+reportUnknownArgumentType = true
+reportUnknownLambdaType = true
+reportUnknownVariableType = true
+reportUnknownMemberType = true
+reportMissingTypeArgument = true
+reportInvalidTypeVarUse = true
+reportUnnecessaryIsInstance = true
+reportUnnecessaryCast = true
+reportUnnecessaryComparison = true
+reportDuplicateImport = true
+reportPrivateUsage = "warning"
+reportUnusedImport = true
+reportUnusedVariable = true
+reportUnusedFunction = true
+reportUnusedClass = true
+
+# ty (Astral) is the CI type-check authority (ADR-03). ty is rule-based, not
+# strict-mode-based: its correctness core already defaults to `error`, so this
+# block only promotes the handful of quality rules that ship below `error`.
+# Each was verified against the pinned ty (see uv.lock, 0.0.61): running
+# `ty check --error <rule> src/lost_sessions/` passes for each.
+# `error-on-warning` is set explicitly to false below (not left implicit): a
+# dependency `deprecated` warning must not fail every fork's CI, and pinning the
+# value keeps CI deterministic across ty upgrades (its default is version-
+# sensitive pre-1.0). `strict-literal-narrowing` is left off as an optional
+# stricter knob. See projects/P03-type-precision-uplevel.md.
+[tool.ty.environment]
+python-version = "3.13" # matches requires-python floor; explicit for determinism
+
+[tool.ty.rules]
+ambiguous-protocol-member = "error"      # core/ports.py exposes Protocol ports
+blanket-ignore-comment = "error"         # every `# ty: ignore` must name its rule
+invalid-ignore-comment = "error"
+ignore-comment-unknown-rule = "error"
+ineffective-final = "error"
+invalid-enum-member-annotation = "error"
+invalid-named-tuple-override = "error"
+
+[tool.ty.terminal]
+error-on-warning = false # warnings (e.g. `deprecated`) inform; they don't gate CI
+
+# ITM-027 — bandit config (round 3). Tests legitimately use `assert`
+# (pytest convention) — exclude_dirs covers tests/.
+[tool.bandit]
+exclude_dirs = ["tests", ".venv", "build", "dist"]
+skips = []                                         # No global skips; add with rationale only.
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+# Marker taxonomy (ITM-046, round-9 decision).
+# `live` = requires external services; `slow` = takes >1s.
+# Default `addopts` excludes both — run full suite with `pytest -m ""`.
+markers = ["live: requires external services", "slow: takes >1s"]
+addopts = "-m 'not live and not slow'"
+strict_markers = true
+# WL-009 — a hung test fails loudly instead of burning a CI slot. `thread`
+# method (not the POSIX-only signal default) so the cap also holds on the
+# Windows matrix leg. A genuinely slow test overrides via
+# `@pytest.mark.timeout(N)`.
+timeout = 60
+timeout_method = "thread"
+# WL-010 (pytest-randomly) reorders tests each run with a printed, replayable
+# seed (`-p randomly --randomly-seed=…`) to surface hidden inter-test coupling;
+# it needs no config. Parallelism (WL-008, `-n auto`) is opt-in per invocation
+# (`just test -n auto`, and the CI full-suite + canary runs) rather than in
+# default addopts, so the fast local inner loop keeps clean `-x`/pdb behaviour.
+
+# Branch coverage (ADR-0019): count both-arms of every branch, not just line
+# execution, so the Codecov gate (WL-005) catches untested conditionals.
+[tool.coverage.run]
+branch = true
+
+# ITM-015 — codespell. US English baseline (default builtin="clear,rare"); empty
+# ignore list — add terms only when intentional. Decided round 9.
+[tool.codespell]
+skip = ".git,.venv,build,dist,node_modules,uv.lock,bun.lock,*.lock,docs/_build,*.svg,*.cast,.ruff_cache,.pytest_cache,.mypy_cache,.ty_cache,*.log"
+# *.log: raw run output, not prose.
+ignore-words-list = "ans,porjects,unparseable,wit"
+# ans: variable name used in prompt-handling code; codespell wants to "fix"
+# it to "and". Whitelist to keep the short variable name.
+# porjects: the deliberate typo example in the superseded ADR 0007.
+# wit: WebAssembly Interface Types, in docs/research/0001.
+check-filenames = true
+check-hidden = false
+
+# import-linter: architectural import rules for this package. Run via
+# `uv run lint-imports`; wired into `just check` and CI (import-boundaries).
+[tool.importlinter]
+root_package = "lost_sessions"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "lost-sessions is a CLI: no web framework imports"
+type = "forbidden"
+source_modules = ["lost_sessions"]
+forbidden_modules = ["fastapi", "starlette", "uvicorn"]
+
+[[tool.importlinter.contracts]]
+name = "core reaches built-in plugins only through the plugin manager"
+type = "forbidden"
+source_modules = ["lost_sessions.cli", "lost_sessions.hookspecs", "lost_sessions.plugins"]
+forbidden_modules = ["lost_sessions.default_plugins"]