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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-folder-workspace
-Version: 0.1.1
+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.1` 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,13 +174,27 @@ 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
 
@@ -299,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`;
@@ -385,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.1`; 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.1 → 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.1` 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,13 +142,27 @@ 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
 
@@ -267,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`;
@@ -353,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.1`; 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.1 → 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-23-runtime-workspace-selection.md

@@ -0,0 +1,384 @@
+# Runtime Workspace Selection 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:** Let one OpenCode MCP process open, identify, activate, route to, and close multiple local folder workspaces while containing PDF/tool failures without terminating the transport.
+
+**Architecture:** Add a focused `WorkspaceManager` between FastMCP handlers and existing `FolderWorkspace` objects. The manager owns opaque session IDs, canonical-root deduplication, the active workspace, bounded lifecycle, and Windows/Git-Bash path normalization; document parsing remains unchanged behind existing parser workers. FastMCP tools route through the manager and convert expected or unexpected operation failures into stable JSON payloads so a later request remains usable.
+
+**Tech Stack:** Python 3.11-3.14, Pydantic v2 contracts, FastMCP stdio, pytest, pypdf/pdfplumber, Ruff, strict Mypy.
+
+---
+
+### Task 1: Versioned workspace-selection contracts
+
+**Files:**
+- Modify: `src/agent_folder_workspace/models.py`
+- Modify: `src/agent_folder_workspace/__init__.py`
+- Create: `src/agent_folder_workspace/schemas/WorkspaceHandleV1.schema.json`
+- Create: `src/agent_folder_workspace/schemas/WorkspaceListV1.schema.json`
+- Create: `src/agent_folder_workspace/schemas/WorkspaceCloseV1.schema.json`
+- Modify: `tests/test_contracts.py`
+- Modify: `tests/test_distribution.py`
+
+- [ ] **Step 1: Write failing model-contract tests**
+
+Add tests that validate an opaque workspace handle, a list response with one active ID, and a close
+response:
+
+```python
+handle = afw.WorkspaceHandleV1(
+    workspace_id="ws_0123456789abcdef0123456789abcdef",
+    root="/documents",
+    active=True,
+    workspace_info=workspace_info,
+)
+listing = afw.WorkspaceListV1(
+    active_workspace_id=handle.workspace_id,
+    workspaces=[handle],
+)
+closed = afw.WorkspaceCloseV1(
+    closed_workspace_id="ws_abcdefabcdefabcdefabcdefabcdefab",
+    active_workspace_id=handle.workspace_id,
+)
+assert listing.workspaces[0].workspace_info == workspace_info
+assert closed.active_workspace_id == handle.workspace_id
+```
+
+Extend `PUBLIC_SCHEMAS` with all three models.
+
+- [ ] **Step 2: Run the focused tests and confirm missing models**
+
+Run: `python3 -m pytest tests/test_contracts.py tests/test_distribution.py::test_committed_json_schemas_match_the_public_v1_contracts -q`
+
+Expected: failure because `WorkspaceHandleV1`, `WorkspaceListV1`, and `WorkspaceCloseV1` do not exist.
+
+- [ ] **Step 3: Add strict Pydantic contracts and public exports**
+
+Add:
+
+```python
+class WorkspaceHandleV1(ContractModel):
+    schema_version: Literal["1.0"] = "1.0"
+    workspace_id: str = Field(pattern=r"^ws_[0-9a-f]{32}$")
+    root: str = Field(min_length=1, max_length=32_768)
+    active: bool
+    workspace_info: WorkspaceInfoV1
+
+
+class WorkspaceListV1(ContractModel):
+    schema_version: Literal["1.0"] = "1.0"
+    active_workspace_id: str = Field(pattern=r"^ws_[0-9a-f]{32}$")
+    workspaces: list[WorkspaceHandleV1]
+
+
+class WorkspaceCloseV1(ContractModel):
+    schema_version: Literal["1.0"] = "1.0"
+    closed_workspace_id: str = Field(pattern=r"^ws_[0-9a-f]{32}$")
+    active_workspace_id: str = Field(pattern=r"^ws_[0-9a-f]{32}$")
+```
+
+Export the types from `agent_folder_workspace.__init__`.
+
+- [ ] **Step 4: Generate schemas and run focused tests**
+
+Run: `python3 scripts/generate_json_schemas.py`
+
+Run: `python3 -m pytest tests/test_contracts.py tests/test_distribution.py::test_committed_json_schemas_match_the_public_v1_contracts -q`
+
+Expected: all selected tests pass.
+
+- [ ] **Step 5: Commit the contract slice**
+
+Stage only the model, export, schema, and selected test files. Commit through the repository commit
+policy with title `Add workspace selection contracts`.
+
+### Task 2: Bounded workspace manager and Windows path normalization
+
+**Files:**
+- Create: `src/agent_folder_workspace/workspace_manager.py`
+- Create: `tests/test_workspace_manager.py`
+
+- [ ] **Step 1: Write failing manager lifecycle and routing tests**
+
+Cover initial registration, same-root deduplication, active selection, explicit lookup, close
+fallback, final-workspace refusal, eight-workspace limit, partial-open cleanup, and idempotent
+manager close. Use a fake factory whose workspace records `close()` calls.
+
+The public manager interface used by tests is:
+
+```python
+manager = WorkspaceManager(initial_root, initial_workspace=fake, factory=factory)
+opened = manager.open_workspace(other_root)
+assert manager.active_workspace_id == opened.workspace_id
+assert manager.workspace(opened.workspace_id) is factory.created[other_root]
+assert manager.workspace() is factory.created[other_root]
+assert manager.close_workspace(opened.workspace_id).active_workspace_id != opened.workspace_id
+manager.close()
+```
+
+- [ ] **Step 2: Write failing Windows/Git-Bash path tests**
+
+Test the pure helper without changing the host OS:
+
+```python
+assert normalize_workspace_path_text(r"C:\Docs\PDF", windows=True) == r"C:\Docs\PDF"
+assert normalize_workspace_path_text("C:/Docs/PDF", windows=True) == r"C:\Docs\PDF"
+assert normalize_workspace_path_text("/c/Docs/PDF", windows=True) == r"C:\Docs\PDF"
+assert normalize_workspace_path_text("//server/share/PDF", windows=True) == r"\\server\share\PDF"
+```
+
+Also prove that relative paths are rejected before the factory is called. Node IDs remain
+deterministic per relative/logical path; explicit workspace IDs disambiguate equivalent trees,
+while signed cursors fail when routed to another workspace.
+
+- [ ] **Step 3: Run tests and confirm the module is missing**
+
+Run: `python3 -m pytest tests/test_workspace_manager.py -q`
+
+Expected: collection failure because `workspace_manager` does not exist.
+
+- [ ] **Step 4: Implement `WorkspaceManager`**
+
+Use a private entry dataclass and two indexes:
+
+```python
+@dataclass(slots=True)
+class _WorkspaceEntry:
+    workspace_id: str
+    root: Path
+    workspace: object
+
+
+class WorkspaceManager:
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        initial_workspace: object | None = None,
+        factory: Callable[[str | Path], object] = FolderWorkspace.open,
+        max_workspaces: int = 8,
+    ) -> None: ...
+
+    def open_workspace(self, path: str | Path) -> WorkspaceHandleV1: ...
+    def list_workspaces(self) -> WorkspaceListV1: ...
+    def activate_workspace(self, workspace_id: str) -> WorkspaceHandleV1: ...
+    def close_workspace(self, workspace_id: str) -> WorkspaceCloseV1: ...
+    def workspace(self, workspace_id: str | None = None) -> object: ...
+    def close(self) -> None: ...
+```
+
+Generate IDs with `f"ws_{uuid.uuid4().hex}"`. Canonicalize through the successfully opened
+workspace's `.root` when available, otherwise through the validated absolute request. Update
+recency only after successful operations, never evict silently, and preserve the current active ID
+when an open attempt fails.
+
+- [ ] **Step 5: Run manager tests**
+
+Run: `python3 -m pytest tests/test_workspace_manager.py -q`
+
+Expected: all manager tests pass.
+
+- [ ] **Step 6: Commit the manager slice**
+
+Stage `workspace_manager.py` and `test_workspace_manager.py`. Commit through the policy with title
+`Manage multiple folder workspaces`.
+
+### Task 3: MCP routing and failure containment
+
+**Files:**
+- Modify: `src/agent_folder_workspace/mcp_server.py`
+- Modify: `tests/test_mcp_cli_installer.py`
+
+- [ ] **Step 1: Write failing public-tool and routing tests**
+
+Update the expected tool set with:
+
+```python
+{
+    "open_workspace",
+    "list_workspaces",
+    "activate_workspace",
+    "close_workspace",
+}
+```
+
+Call `open_workspace` on a second temporary directory, capture its ID, verify omitted IDs use it,
+then pass the initial ID explicitly and verify the call reaches the initial fake workspace.
+Exercise optional `workspace_id` on `workspace_info`, `list_children`, `get_node`, `read_content`,
+`read_binary`, `search_content`, `index_content`, and `refresh_workspace`.
+
+- [ ] **Step 2: Write failing structured-error keepalive tests**
+
+Use a fake workspace that raises `InputValidationError("bad PDF")`, then one that raises
+`RuntimeError("parser exploded")`. Assert:
+
+```python
+assert result["ok"] is False
+assert result["error"]["code"] in {"input_validation_error", "internal_error"}
+assert _call_tool(server, "workspace_info", {})["scan_state"] == "ready"
+```
+
+Verify messages are sanitized and no traceback or document content enters the result.
+
+- [ ] **Step 3: Run focused MCP tests and confirm failures**
+
+Run: `python3 -m pytest tests/test_mcp_cli_installer.py -q`
+
+Expected: failures for the missing tools, missing optional IDs, and uncontained errors.
+
+- [ ] **Step 4: Route FastMCP handlers through `WorkspaceManager`**
+
+Construct one manager in `create_mcp_server`, register four management tools, and add
+`workspace_id: str | None = None` as the final parameter of every workspace-specific existing
+tool. Resolve with:
+
+```python
+selected = manager.workspace(workspace_id)
+return call_workspace_capability(selected, capability, *args, **kwargs)
+```
+
+Keep `probe_backends` global. Attach the manager to the server for deterministic ownership tests,
+and make `run_mcp` close the manager exactly once in `finally`.
+
+- [ ] **Step 5: Add stable error payloads**
+
+Add a deterministic helper and wrap capability invocation:
+
+```python
+def _error_code(error: FolderWorkspaceError) -> str:
+    name = type(error).__name__.removesuffix("Error")
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower() + "_error"
+
+
+try:
+    return _jsonable(method(*args, **kwargs))
+except FolderWorkspaceError as error:
+    return {
+        "ok": False,
+        "error": {
+            "code": _error_code(error),
+            "message": redact_text(error),
+        },
+    }
+except Exception as error:
+    correlation_id = uuid.uuid4().hex
+    logger.exception("mcp tool failed correlation_id=%s", correlation_id)
+    return {
+        "ok": False,
+        "error": {
+            "code": "internal_error",
+            "message": "Unexpected workspace failure",
+            "correlation_id": correlation_id,
+        },
+    }
+```
+
+Apply the same boundary to manager tools. Never catch `BaseException`, so normal process
+termination and cancellation semantics remain intact.
+
+- [ ] **Step 6: Run focused MCP and manager tests**
+
+Run: `python3 -m pytest tests/test_mcp_cli_installer.py tests/test_workspace_manager.py -q`
+
+Expected: all selected tests pass.
+
+- [ ] **Step 7: Commit the MCP slice**
+
+Stage `mcp_server.py` and `test_mcp_cli_installer.py`. Commit through the policy with title
+`Route MCP tools by workspace ID`.
+
+### Task 4: Single-PDF MCP regression and parser survival
+
+**Files:**
+- Create: `tests/test_mcp_pdf_survival.py`
+- Modify: `tests/test_parser_workers.py`
+- Modify: `src/agent_folder_workspace/adapters/pdf.py` only if a new unhandled parser exception is proven
+- Modify: `src/agent_folder_workspace/parser_workers.py` only if a worker-restart test proves a lifecycle defect
+
+- [ ] **Step 1: Add a valid single-PDF MCP test**
+
+Create a one-page PDF with `PdfWriter`, open its directory through `open_workspace`, list the root,
+expand the PDF, read a bounded page, and then call `workspace_info` again. Assert every response is
+successful and the server remains usable.
+
+- [ ] **Step 2: Add malformed/encrypted/oversized PDF keepalive tests**
+
+Parameterize fixtures for `b""`, a truncated `%PDF-` body, encrypted `PdfWriter` output, and a PDF
+larger than a deliberately small `max_content_cache_bytes`. For each fixture, trigger the PDF
+hierarchy read, assert a structured error or locked diagnostic, and make a successful
+`workspace_info` call on the same server afterward.
+
+- [ ] **Step 3: Add parser exception and abnormal-exit survival tests**
+
+Inject a worker target that returns an unexpected remote exception and one that exits before
+replying. Assert `ParserWorkerFailure`, verify a replacement worker can complete a later request,
+and confirm closing the pool is bounded and idempotent.
+
+- [ ] **Step 4: Run the regression tests**
+
+Run: `python3 -m pytest tests/test_mcp_pdf_survival.py tests/test_parser_workers.py -q`
+
+Expected: all survival tests pass. If a failure proves an adapter or worker defect, make the
+smallest production change in the listed file and rerun this command.
+
+- [ ] **Step 5: Commit the PDF survival slice**
+
+Stage the new tests and only production files changed by a proven failing test. Commit through the
+policy with title `Keep MCP alive after PDF failures`.
+
+### Task 5: OpenCode guidance, documentation, and release gates
+
+**Files:**
+- Modify: `src/agent_folder_workspace/opencode/skill/SKILL.md`
+- Modify: `README.md`
+- Modify: `docs/architecture.md`
+- Modify: `docs/windows.md`
+- Modify: `tests/test_mcp_cli_installer.py`
+- Modify: `tests/test_distribution.py`
+
+- [ ] **Step 1: Add failing installed-resource assertions**
+
+Assert the generated skill directs the model to call `open_workspace` for a user-approved external
+absolute path, retain `workspace_id`, use the active default for concise calls, and close unused
+workspaces. Assert README/distribution payloads contain the runtime-selection documentation.
+
+- [ ] **Step 2: Update the bundled skill and documentation**
+
+Document the four management tools, optional workspace IDs, eight-workspace bound, ID lifetime,
+Git Bash path form, root security, and PDF error behavior. Retain the instruction to call
+`workspace_info` first when no external root is requested.
+
+- [ ] **Step 3: Run documentation/resource tests**
+
+Run: `python3 -m pytest tests/test_mcp_cli_installer.py tests/test_distribution.py -q`
+
+Expected: all selected tests pass.
+
+- [ ] **Step 4: Run all quality gates**
+
+Run:
+
+```bash
+python3 scripts/generate_json_schemas.py --check
+python3 -m ruff check .
+python3 -m mypy
+python3 -m pytest
+SOURCE_DATE_EPOCH=315532800 python3 -m build --no-isolation
+python3 scripts/check_wheel.py dist --install-smoke
+python3 scripts/check_wheel.py --reproducible
+git diff --check
+```
+
+Expected: every command exits zero.
+
+- [ ] **Step 5: Record the Windows acceptance requirement**
+
+Update the Beads child issue with the exact Git Bash/OpenCode harness command and mark the remote
+Windows observation as pending until it runs on Windows. Do not claim the original field failure is
+reproduced or fixed solely from macOS tests.
+
+- [ ] **Step 6: Commit the documentation and verified release slice**
+
+Stage only the skill, documentation, test, schema, and necessary metadata files. Commit through the
+policy with title `Document runtime workspace selection`.