agent-folder-workspace 0.1.0__tar.gz → 0.1.2__tar.gz

{agent_folder_workspace-0.1.0 → agent_folder_workspace-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-folder-workspace
-Version: 0.1.0
+Version: 0.1.2
 Summary: Offline, lazy, agent-oriented exploration of heterogeneous folders
 Author-email: Dark Light <darklight@noreply.com>
 License-Expression: Apache-2.0
@@ -32,12 +32,12 @@ Description-Content-Type: text/markdown
 
 # agent-folder-workspace
 
-`agent-folder-workspace` presents one local directory as a stable, paginated
-node hierarchy for agents. It discovers file metadata first and opens document
+`agent-folder-workspace` presents local directories as stable, paginated node
+hierarchies for agents. It discovers file metadata first and opens document
 bodies only when a caller expands or reads a node. The default parser path is
 local Python code: Microsoft Office and LibreOffice are not required.
 
-> **Project status:** `0.1.0` is an alpha contract. Read-only exploration and
+> **Project status:** `0.1.2` is an alpha contract. Read-only exploration and
 > byte access are implemented; editing, rendering, OCR, and complete semantic
 > coverage of every supported container are not.
 
@@ -92,7 +92,9 @@ adapters, and caching:
    adapters and enforce one deadline across startup, queueing, IPC, and parsing.
 5. `SizedLru` retains bounded decoded pages in memory. `ContentIndex` stores an
    optional per-workspace SQLite search index in the application cache.
-6. The Python API, Typer CLI, and FastMCP stdio server share the same workspace
+6. `WorkspaceManager` gives one FastMCP process a bounded registry of active and
+   explicitly addressed workspace roots.
+7. The Python API, Typer CLI, and FastMCP stdio server share the same workspace
    methods and versioned response contracts.
 
 Node IDs are deterministic hashes of relative and logical paths; they do not
@@ -131,7 +133,7 @@ archive, XML, and structural limits. It is frozen and rejects unknown fields.
 The package exports a stable
 error hierarchy (`FolderWorkspaceError`, `InputValidationError`,
 `NodeNotFoundError`, `StaleCursorError`, and `ResourceLimitError`) and six
-versioned wire models:
+document wire models plus three workspace-selection models:
 
 - `CapabilityReportV1`
 - `ContentPageV1`
@@ -139,6 +141,9 @@ versioned wire models:
 - `NodePageV1`
 - `NodeV1`
 - `SearchPageV1`
+- `WorkspaceCloseV1`
+- `WorkspaceHandleV1`
+- `WorkspaceListV1`
 
 Committed JSON Schemas live in
 `src/agent_folder_workspace/schemas/`. Regenerate them with
@@ -147,7 +152,7 @@ Pydantic's `model_json_schema()` output.
 
 ## MCP server
 
-Run one stdio server for one root:
+Run one stdio server with an initial root:
 
 ```console
 folderws mcp --root ./documents
@@ -155,6 +160,10 @@ folderws mcp --root ./documents
 
 The server exposes exactly these tools:
 
+- `open_workspace`
+- `list_workspaces`
+- `activate_workspace`
+- `close_workspace`
 - `workspace_info`
 - `list_children`
 - `get_node`
@@ -165,16 +174,40 @@ The server exposes exactly these tools:
 - `refresh_workspace`
 - `probe_backends`
 
+`open_workspace(path)` accepts an explicit absolute directory, returns an opaque,
+process-lifetime `workspace_id`, and makes that workspace active. Existing tools
+accept an optional `workspace_id`; omission uses the active workspace. Opening
+the same canonical root again reuses its ID. `list_workspaces`,
+`activate_workspace`, and `close_workspace` manage the registry. One process
+holds at most eight workspaces and never evicts one silently.
+
+On Windows, runtime selection accepts `C:\Documents`, `C:/Documents`, UNC paths,
+and Git Bash paths such as `/c/Documents`. Relative external paths are rejected.
+The initial CLI root remains compatible with relative paths such as `.`.
+
 Results use the same versioned models as the Python API. A method that is absent
 from an injected workspace implementation returns a structured
 `capability_unavailable` response instead of failing server construction.
+Expected workspace/parser failures and unexpected tool exceptions become
+structured results; a later MCP request remains available. PDF decoding remains
+lazy and isolated in bounded parser workers.
 
 The transport is stdio. There is no HTTP listener, authentication layer, or
-multi-root broker. The process and its MCP client share the operating-system
-permissions of the account that launched `folderws`; choose the root narrowly.
+network broker. The process and its MCP client share the operating-system
+permissions of the account that launched `folderws`; open roots narrowly.
 
 ## CLI
 
+All commands accept global options before the subcommand:
+`folderws [--quiet | --verbose] [--log-file PATH] COMMAND ...`. Human status,
+progress, warnings, and errors are written to stderr; the JSON reports from
+`doctor`, `index`, `clear-cache`, and `install-opencode` remain unadorned on
+stdout. MCP keeps stdout exclusively for JSON-RPC. By default, durable UTF-8
+logs are written to `platformdirs`' user log directory as `folderws.log`, with
+5 MiB rotation and three backups. An explicit log file must not be a symbolic
+link, junction, or reparse-point destination; ordinary log permission failures
+fall back to stderr-only operation.
+
 ```console
 # Serve a folder to an MCP client over stdio
 folderws mcp --root DIR
@@ -289,6 +322,8 @@ The normal Python parser path is offline and read-only. It does not upload
 documents and does not execute document macros. Important controls include:
 
 - roots that are symbolic links or reparse points are rejected;
+- external roots are opened only by an explicit `open_workspace` call, are
+  bounded to eight per process, and receive process-lifetime opaque IDs;
 - child links are not followed by default, and resolved sources must remain
   under the selected root;
 - SQLite files are opened with `mode=ro` and `PRAGMA query_only=ON`;
@@ -375,7 +410,7 @@ The detailed coverage and per-format caveats are in
   rendering. A hard parent timeout cannot guarantee cleanup of a vendor process
   that is itself stuck below COM or LibreOffice process control.
 - The stated 100,000-node and warm p95 performance figures are design targets,
-  not certified guarantees in `0.1.0`; CI covers correctness across Windows,
+  not certified guarantees in `0.1.2`; CI covers correctness across Windows,
   Linux, and macOS but does not emulate a specific Windows-x64 SSD workload.
 
 ## Development

{agent_folder_workspace-0.1.0 → agent_folder_workspace-0.1.2}/README.md

@@ -1,11 +1,11 @@
 # agent-folder-workspace
 
-`agent-folder-workspace` presents one local directory as a stable, paginated
-node hierarchy for agents. It discovers file metadata first and opens document
+`agent-folder-workspace` presents local directories as stable, paginated node
+hierarchies for agents. It discovers file metadata first and opens document
 bodies only when a caller expands or reads a node. The default parser path is
 local Python code: Microsoft Office and LibreOffice are not required.
 
-> **Project status:** `0.1.0` is an alpha contract. Read-only exploration and
+> **Project status:** `0.1.2` is an alpha contract. Read-only exploration and
 > byte access are implemented; editing, rendering, OCR, and complete semantic
 > coverage of every supported container are not.
 
@@ -60,7 +60,9 @@ adapters, and caching:
    adapters and enforce one deadline across startup, queueing, IPC, and parsing.
 5. `SizedLru` retains bounded decoded pages in memory. `ContentIndex` stores an
    optional per-workspace SQLite search index in the application cache.
-6. The Python API, Typer CLI, and FastMCP stdio server share the same workspace
+6. `WorkspaceManager` gives one FastMCP process a bounded registry of active and
+   explicitly addressed workspace roots.
+7. The Python API, Typer CLI, and FastMCP stdio server share the same workspace
    methods and versioned response contracts.
 
 Node IDs are deterministic hashes of relative and logical paths; they do not
@@ -99,7 +101,7 @@ archive, XML, and structural limits. It is frozen and rejects unknown fields.
 The package exports a stable
 error hierarchy (`FolderWorkspaceError`, `InputValidationError`,
 `NodeNotFoundError`, `StaleCursorError`, and `ResourceLimitError`) and six
-versioned wire models:
+document wire models plus three workspace-selection models:
 
 - `CapabilityReportV1`
 - `ContentPageV1`
@@ -107,6 +109,9 @@ versioned wire models:
 - `NodePageV1`
 - `NodeV1`
 - `SearchPageV1`
+- `WorkspaceCloseV1`
+- `WorkspaceHandleV1`
+- `WorkspaceListV1`
 
 Committed JSON Schemas live in
 `src/agent_folder_workspace/schemas/`. Regenerate them with
@@ -115,7 +120,7 @@ Pydantic's `model_json_schema()` output.
 
 ## MCP server
 
-Run one stdio server for one root:
+Run one stdio server with an initial root:
 
 ```console
 folderws mcp --root ./documents
@@ -123,6 +128,10 @@ folderws mcp --root ./documents
 
 The server exposes exactly these tools:
 
+- `open_workspace`
+- `list_workspaces`
+- `activate_workspace`
+- `close_workspace`
 - `workspace_info`
 - `list_children`
 - `get_node`
@@ -133,16 +142,40 @@ The server exposes exactly these tools:
 - `refresh_workspace`
 - `probe_backends`
 
+`open_workspace(path)` accepts an explicit absolute directory, returns an opaque,
+process-lifetime `workspace_id`, and makes that workspace active. Existing tools
+accept an optional `workspace_id`; omission uses the active workspace. Opening
+the same canonical root again reuses its ID. `list_workspaces`,
+`activate_workspace`, and `close_workspace` manage the registry. One process
+holds at most eight workspaces and never evicts one silently.
+
+On Windows, runtime selection accepts `C:\Documents`, `C:/Documents`, UNC paths,
+and Git Bash paths such as `/c/Documents`. Relative external paths are rejected.
+The initial CLI root remains compatible with relative paths such as `.`.
+
 Results use the same versioned models as the Python API. A method that is absent
 from an injected workspace implementation returns a structured
 `capability_unavailable` response instead of failing server construction.
+Expected workspace/parser failures and unexpected tool exceptions become
+structured results; a later MCP request remains available. PDF decoding remains
+lazy and isolated in bounded parser workers.
 
 The transport is stdio. There is no HTTP listener, authentication layer, or
-multi-root broker. The process and its MCP client share the operating-system
-permissions of the account that launched `folderws`; choose the root narrowly.
+network broker. The process and its MCP client share the operating-system
+permissions of the account that launched `folderws`; open roots narrowly.
 
 ## CLI
 
+All commands accept global options before the subcommand:
+`folderws [--quiet | --verbose] [--log-file PATH] COMMAND ...`. Human status,
+progress, warnings, and errors are written to stderr; the JSON reports from
+`doctor`, `index`, `clear-cache`, and `install-opencode` remain unadorned on
+stdout. MCP keeps stdout exclusively for JSON-RPC. By default, durable UTF-8
+logs are written to `platformdirs`' user log directory as `folderws.log`, with
+5 MiB rotation and three backups. An explicit log file must not be a symbolic
+link, junction, or reparse-point destination; ordinary log permission failures
+fall back to stderr-only operation.
+
 ```console
 # Serve a folder to an MCP client over stdio
 folderws mcp --root DIR
@@ -257,6 +290,8 @@ The normal Python parser path is offline and read-only. It does not upload
 documents and does not execute document macros. Important controls include:
 
 - roots that are symbolic links or reparse points are rejected;
+- external roots are opened only by an explicit `open_workspace` call, are
+  bounded to eight per process, and receive process-lifetime opaque IDs;
 - child links are not followed by default, and resolved sources must remain
   under the selected root;
 - SQLite files are opened with `mode=ro` and `PRAGMA query_only=ON`;
@@ -343,7 +378,7 @@ The detailed coverage and per-format caveats are in
   rendering. A hard parent timeout cannot guarantee cleanup of a vendor process
   that is itself stuck below COM or LibreOffice process control.
 - The stated 100,000-node and warm p95 performance figures are design targets,
-  not certified guarantees in `0.1.0`; CI covers correctness across Windows,
+  not certified guarantees in `0.1.2`; CI covers correctness across Windows,
   Linux, and macOS but does not emulate a specific Windows-x64 SSD workload.
 
 ## Development

{agent_folder_workspace-0.1.0 → agent_folder_workspace-0.1.2}/docs/architecture.md

@@ -7,7 +7,8 @@ tests, not this prose alone, define the wire contract.
 
 ```mermaid
 flowchart LR
-    Client["Python, CLI, or MCP client"] --> Workspace["FolderWorkspace"]
+    Client["Python, CLI, or MCP client"] --> Session["WorkspaceManager"]
+    Session --> Workspace["FolderWorkspace"]
     Workspace --> Registry["NodeRegistry metadata tree"]
     Workspace --> Manager["AdapterManager"]
     Manager --> Direct["Direct text, CSV, and binary paths"]
@@ -31,7 +32,7 @@ is an explicit diagnostic path.
 
 `models.py` contains strict Pydantic models. Wire-level models carry
 `schema_version="1.0"`; unknown fields are rejected and non-finite numbers are
-not accepted. The six top-level exported models have committed JSON Schemas in
+not accepted. The nine top-level exported models have committed JSON Schemas in
 `src/agent_folder_workspace/schemas/`.
 
 `errors.py` provides stable exception categories, and `ids.py` creates node IDs
@@ -192,9 +193,18 @@ copies.
 
 The Python API returns model instances and raises the public error hierarchy.
 The FastMCP server serializes model responses with `model_dump(mode="json")`
-and exposes a fixed nine-tool stdio surface. Its capability dispatcher resolves
-workspace methods at call time so reduced injected implementations return a
-structured `capability_unavailable` error.
+and exposes a fixed thirteen-tool stdio surface. `WorkspaceManager` owns at
+most eight roots, opaque process-lifetime IDs, canonical-root deduplication,
+active selection, and deterministic cleanup. Existing tools accept an optional
+workspace ID and otherwise route to the active root. Its capability dispatcher
+resolves workspace methods at call time so reduced injected implementations
+return a structured `capability_unavailable` error.
+
+MCP tool boundaries translate public workspace errors to stable error codes and
+sanitize unexpected failures behind a correlation ID. This leaves the stdio
+transport usable for a later request. Risky PDF and container semantics remain
+inside parser workers; opening or listing a filesystem root does not decode
+their payloads.
 
 The Typer CLI provides MCP serving, backend diagnostics, indexing, cache
 clearing, and managed OpenCode integration installation. OpenCode resources are
@@ -218,8 +228,10 @@ enterprise policy, add-in, crash, or vendor defect.
 
 ## Security boundaries
 
-- The selected root is the filesystem authority boundary; the library does not
-  implement per-node authorization.
+- Every selected root is a separate filesystem authority boundary; the library
+  does not implement per-node authorization.
+- Runtime roots require an explicit absolute path. Windows native, slash-style,
+  UNC, and Git Bash drive paths normalize before registry deduplication.
 - The default MCP transport is local stdio; operating-system permissions govern
   the process and client.
 - `read_binary` intentionally reveals file bytes inside the root.

agent_folder_workspace-0.1.2/docs/superpowers/plans/2026-07-22-console-logging.md

@@ -0,0 +1,270 @@
+# Console Logging Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add durable, safe, cross-platform console and file logging to `folderws` without changing JSON stdout or MCP stdio contracts.
+
+**Architecture:** A focused `console_logging.py` module owns handler setup, safe log-path selection, redaction, lifecycle context, and throttled progress. The Typer root callback initializes it once, command functions emit lifecycle events, and a `main()` entrypoint translates package and unexpected exceptions into stable exits while preserving Click/Typer behavior. `FolderWorkspace.index_content()` exposes an optional callback so the CLI can report bounded progress without affecting Python or MCP callers.
+
+**Tech Stack:** Python 3.11+, stdlib `logging`/`RotatingFileHandler`, Typer/Click, platformdirs, pytest, Ruff, strict Mypy, Hatchling.
+
+---
+
+### Task 1: Implement and verify the complete logging contract
+
+**Files:**
+- Create: `src/agent_folder_workspace/console_logging.py`
+- Create: `tests/test_console_logging.py`
+- Modify: `src/agent_folder_workspace/cli.py`
+- Modify: `src/agent_folder_workspace/__main__.py`
+- Modify: `src/agent_folder_workspace/workspace.py:1010`
+- Modify: `pyproject.toml:41`
+- Modify: `README.md:145`
+- Modify: `docs/windows.md:20`
+
+- [ ] **Step 1: Write failing unit tests for logging setup, path safety, rotation, and redaction**
+
+  Add tests which import the wished-for API below, configure it against `tmp_path`, write records, flush handlers, and assert that secrets are absent from both console and file output:
+
+  ```python
+  from agent_folder_workspace.console_logging import (
+      LoggingConfigurationError,
+      configure_logging,
+      default_log_file,
+      redact_text,
+      shutdown_logging,
+  )
+
+  def test_redact_text_hides_known_secret_shapes() -> None:
+      value = "api-key=secret OPENAI_API_KEY=sk-test Authorization: Bearer token"
+      redacted = redact_text(value)
+      assert "secret" not in redacted
+      assert "sk-test" not in redacted
+      assert "token" not in redacted
+
+  def test_configure_logging_writes_human_console_to_stderr_and_debug_to_file(
+      tmp_path: Path, capsys: pytest.CaptureFixture[str]
+  ) -> None:
+      state = configure_logging(log_file=tmp_path / "folderws.log")
+      logger = logging.getLogger("agent_folder_workspace.test")
+      logger.info("visible status")
+      logger.debug("durable detail")
+      shutdown_logging(state)
+      captured = capsys.readouterr()
+      assert captured.out == ""
+      assert "visible status" in captured.err
+      assert "durable detail" in (tmp_path / "folderws.log").read_text(encoding="utf-8")
+  ```
+
+  Cover default path resolution via a monkeypatched platform log directory, `quiet` showing only errors, `verbose` showing debug, three 5 MiB rotating backups, a linked/reparse terminal or parent raising `LoggingConfigurationError`, an unwritable file falling back without aborting, and Windows-style lexical path text not crashing formatting. Keep each test isolated by calling `shutdown_logging()`.
+
+- [ ] **Step 2: Run the new logging tests and verify RED**
+
+  Run: `pytest tests/test_console_logging.py -v`
+
+  Expected: collection fails because `agent_folder_workspace.console_logging` does not exist.
+
+- [ ] **Step 3: Implement the focused logging module minimally**
+
+  Implement these typed public interfaces and private helpers in `console_logging.py`:
+
+  ```python
+  @dataclass(frozen=True)
+  class LoggingState:
+      correlation_id: str
+      log_file: Path | None
+      handlers: tuple[logging.Handler, ...]
+
+  class LoggingConfigurationError(ValueError):
+      pass
+
+  def default_log_file() -> Path:
+      return Path(user_log_dir("agent-folder-workspace", appauthor=False)) / "folderws.log"
+
+  def redact_text(value: object) -> str: ...
+
+  def configure_logging(
+      *, quiet: bool = False, verbose: bool = False, log_file: Path | None = None
+  ) -> LoggingState: ...
+
+  def shutdown_logging(state: LoggingState | None = None) -> None: ...
+  ```
+
+  Use a package-root logger with propagation disabled, a stderr `StreamHandler`, and a UTF-8 `RotatingFileHandler(maxBytes=5 * 1024 * 1024, backupCount=3)`. File level is DEBUG; console level is ERROR for quiet, DEBUG for verbose, INFO otherwise. Refuse any destination for which `first_unsafe_component()` returns a component. Create parent directories only after validation, revalidate before opening, and catch ordinary file-handler setup failures so console logging remains available with one warning. Redact bearer tokens and values associated with case-insensitive names containing `api_key`, `apikey`, `token`, `secret`, `password`, or `authorization`. Formatting and redaction must fall back to safe type names instead of raising.
+
+- [ ] **Step 4: Run logging tests and verify GREEN**
+
+  Run: `pytest tests/test_console_logging.py -v`
+
+  Expected: all tests pass.
+
+- [ ] **Step 5: Write failing tests for deterministic workspace index progress**
+
+  In `tests/test_search_cache.py`, create a workspace with two readable files and one adapter failure, then call the wished-for callback contract:
+
+  ```python
+  events: list[tuple[int, int, int]] = []
+  info = workspace.index_content(progress=lambda done, total, failed: events.append((done, total, failed)))
+  assert events[-1] == (3, 3, 1)
+  assert [event[0] for event in events] == [1, 2, 3]
+  assert info.total_files == 3
+  ```
+
+  Also assert that `workspace.index_content()` with no callback remains valid.
+
+- [ ] **Step 6: Run the progress tests and verify RED**
+
+  Run: `pytest tests/test_search_cache.py -v`
+
+  Expected: the callback test fails because `index_content()` does not accept `progress`.
+
+- [ ] **Step 7: Add the optional progress callback to the workspace API**
+
+  Change the signature and loop without changing exception swallowing:
+
+  ```python
+  def index_content(
+      self,
+      *,
+      progress: Callable[[int, int, int], None] | None = None,
+  ) -> WorkspaceInfoV1:
+      files = self._file_nodes()
+      failed = 0
+      for completed, file_node in enumerate(files, start=1):
+          index.begin_file(file_node)
+          try:
+              self._index_file(file_node, index)
+          except (FolderWorkspaceError, OSError, ValueError):
+              failed += 1
+          else:
+              index.finish_file(file_node.id)
+          if progress is not None:
+              progress(completed, len(files), failed)
+      return self.workspace_info()
+  ```
+
+  Import `Callable` from `collections.abc`. Never invoke the callback with paths or content.
+
+- [ ] **Step 8: Run the progress tests and verify GREEN**
+
+  Run: `pytest tests/test_search_cache.py -v`
+
+  Expected: all progress and existing search/cache tests pass.
+
+- [ ] **Step 9: Write failing CLI contract tests before changing CLI code**
+
+  Extend `tests/test_console_logging.py` and `tests/test_mcp_cli_installer.py` to prove:
+
+  ```python
+  result = CliRunner().invoke(app, ["--log-file", str(log_file), "doctor"])
+  assert result.exit_code == 0
+  json.loads(result.stdout)
+  assert "command=doctor" in result.stderr
+
+  conflict = CliRunner().invoke(app, ["--quiet", "--verbose", "doctor"])
+  assert conflict.exit_code == 2
+
+  quiet = CliRunner().invoke(app, ["--quiet", "--log-file", str(log_file), "doctor"])
+  assert quiet.stderr == ""
+  json.loads(quiet.stdout)
+  ```
+
+  Add tests for command start/completion and elapsed time, selected roots/targets, install conflict exit 2, known `FolderWorkspaceError` declared exit code, an `OSError` exit 1 with concise stderr, unexpected failure exit 1 with a correlation ID and no traceback on stderr but a traceback in the file, and throttled `index` progress including final counts. Assert secrets passed in exception messages are redacted. Exercise `main()` directly for translated errors.
+
+  For MCP purity, run the command with a monkeypatched `run_mcp` that writes a JSON-RPC line to stdout and logs an INFO record; assert stdout contains only the JSON-RPC line and the human record is on stderr. Assert that Click usage errors and explicit `typer.Exit` retain native exit codes.
+
+- [ ] **Step 10: Run CLI tests and verify RED**
+
+  Run: `pytest tests/test_console_logging.py tests/test_mcp_cli_installer.py -v`
+
+  Expected: failures show missing global options, lifecycle output, entrypoint wrapper, and CLI progress wiring.
+
+- [ ] **Step 11: Integrate logging into Typer and the package entrypoints**
+
+  Add a root callback with `--quiet`, `--verbose`, and `--log-file`; reject the option conflict with `typer.BadParameter`. Store `LoggingState` in `typer.Context.obj`. Add a lifecycle context manager and throttled progress reporter in `console_logging.py` with these interfaces:
+
+  ```python
+  @contextmanager
+  def command_lifecycle(command: str, **safe_fields: object) -> Iterator[None]: ...
+
+  class IndexProgressReporter:
+      def __call__(self, completed: int, total: int, failed: int) -> None: ...
+  ```
+
+  The reporter emits the first event, final event, failures, and bounded intermediate events (at most once per second or every 100 files), while unit tests can inject a clock and interval. Wrap each command body in `command_lifecycle`, logging only safe paths/counts/flags. For `index`, call `workspace.index_content(progress=IndexProgressReporter(...))` directly and preserve the stable JSON result using `_jsonable` behavior; keep late capability handling if the method is unavailable.
+
+  Implement:
+
+  ```python
+  def main() -> None:
+      try:
+          app(standalone_mode=False)
+      except (click.UsageError, click.Abort):
+          raise
+      except click.exceptions.Exit as error:
+          raise SystemExit(error.exit_code) from error
+      except FolderWorkspaceError as error:
+          log_expected_failure(error)
+          raise SystemExit(error.exit_code) from error
+      except (OSError, subprocess.SubprocessError) as error:
+          log_expected_failure(error)
+          raise SystemExit(1) from error
+      except Exception as error:
+          log_unexpected_failure(error)
+          raise SystemExit(1) from error
+      finally:
+          shutdown_logging()
+  ```
+
+  Adapt exception handling as required by actual Typer behavior, but preserve native usage/help and explicit exit behavior. Update `pyproject.toml` to `folderws = "agent_folder_workspace.cli:main"` and `__main__.py` to call `main()`. Ensure unexpected tracebacks use only the file handler; stderr gets a concise redacted correlation ID and log path.
+
+- [ ] **Step 12: Run CLI tests and verify GREEN**
+
+  Run: `pytest tests/test_console_logging.py tests/test_mcp_cli_installer.py -v`
+
+  Expected: all tests pass and JSON/MCP stdout assertions remain exact.
+
+- [ ] **Step 13: Document the global logging behavior**
+
+  Add the following command synopsis and operational notes to README and Windows docs:
+
+  ```console
+  folderws [--quiet | --verbose] [--log-file PATH] COMMAND [ARGS]...
+  ```
+
+  State that human output is stderr, JSON/MCP remains stdout, default logs use the platform user log directory with three 5 MiB backups, `--quiet` retains errors, `--verbose` adds console diagnostics, and a custom log path must not traverse symlinks/junctions/reparse points. Include PowerShell and Git Bash examples with paths containing spaces.
+
+- [ ] **Step 14: Run focused static and formatting gates**
+
+  Run:
+
+  ```bash
+  ruff format src/agent_folder_workspace/console_logging.py src/agent_folder_workspace/cli.py src/agent_folder_workspace/workspace.py tests/test_console_logging.py tests/test_mcp_cli_installer.py tests/test_search_cache.py
+  ruff check src/agent_folder_workspace/console_logging.py src/agent_folder_workspace/cli.py src/agent_folder_workspace/workspace.py tests/test_console_logging.py tests/test_mcp_cli_installer.py tests/test_search_cache.py
+  mypy --no-incremental
+  ```
+
+  Expected: formatting makes no further changes on a second check, Ruff reports no errors, and Mypy reports success.
+
+- [ ] **Step 15: Run all release gates and installed-wheel smoke tests**
+
+  Run:
+
+  ```bash
+  python scripts/generate_json_schemas.py --check
+  ruff format --check src scripts tests
+  ruff check --no-cache .
+  mypy --no-incremental
+  pytest
+  rm -rf dist
+  python -m build --no-isolation
+  python -m twine check dist/*
+  python scripts/check_wheel.py dist --install-smoke
+  python scripts/check_wheel.py --reproducible
+  ```
+
+  Expected: every command exits 0; the fresh-wheel CLI smoke confirms `folderws --help`, JSON stdout, stderr logging, explicit `--log-file`, and MCP importability. If Twine is not installed, use an isolated temporary environment to install it rather than adding it as a runtime dependency.
+
+- [ ] **Step 16: Commit the implementation**
+
+  Stage only the files listed above and commit through the repository's required commit-policy helper with a title such as `Add durable folder workspace logging` and bullets covering protocol-safe stderr/file logging, progress/error diagnostics, and verification coverage.