opencode-swarm 7.25.0 → 7.25.2

package/README.md

@@ -684,14 +684,28 @@ File rotates automatically at 10MB to `.swarm/telemetry.jsonl.1`.
 </details>
 
 <details>
-<summary><strong>Save Plan Tool: Target Workspace Requirement</strong></summary>
+<summary><strong>Working Directory Requirement: No process.cwd() Fallback</strong></summary>
 
-The `save_plan` tool requires an explicit target workspace path. It does **not** fall back to `process.cwd()`.
+All Swarm tools that accept a `working_directory` parameter **require an explicit path**. They do **not** fall back to `process.cwd()`. This prevents `.swarm` state from being created in project subdirectories when the host process's working directory differs from the actual project root (issue [#922](https://github.com/zaxbysauce/opencode-swarm/issues/922)).
 
-### Explicit Workspace Requirement
+### Defense-in-Depth
 
-- The `working_directory` parameter must be provided
-- Providing no value or relying on implicit directory resolution will result in deterministic failure
+This safety guarantee is implemented in two layers:
+
+1. **Fast-path filter** (`resolveWorkingDirectory` in `src/tools/resolve-working-directory.ts`) — validates all incoming `working_directory` values for null-byte injection, path traversal, Windows device paths, and subdirectory containment before any file system access
+2. **Canonical write-time guard** (`validateProjectRoot` in `src/evidence/manager.ts`) — uses `realpathSync` to canonicalize paths at evidence-write time, catching any symlink-based subdirectory bypasses that slip past the fast-path filter
+
+### Tools That Require Explicit working_directory
+
+The following tools require an explicit `working_directory` and reject subdirectory paths:
+
+- `save_plan`
+- `update_task_status`
+- `declare_scope`
+- `pre_check_batch`
+- `test_impact`
+- `mutation_test`
+- `diff_summary`
 
 ### Failure Conditions
 
@@ -700,20 +714,34 @@ The `save_plan` tool requires an explicit target workspace path. It does **not**
 | Missing (`undefined` / `null`) | Fails with: "Target workspace is required" |
 | Empty or whitespace-only | Fails with: "Target workspace cannot be empty or whitespace" |
 | Path traversal (`..`) | Fails with: "Target workspace cannot contain path traversal" |
+| Subdirectory of project root | Fails with: "...is a subdirectory of fallback..." |
+| Windows device path | Fails with: "Windows device paths are not allowed" |
 
 ### Usage Contract
 
-When using `save_plan`, always pass a valid `working_directory`:
+When using any affected tool, always pass a valid `working_directory`:
 
 ```typescript
+// save_plan example
 save_plan({
   title: "My Project",
   swarm_id: "mega",
   phases: [{ id: 1, name: "Setup", tasks: [{ id: "1.1", description: "Initialize project" }] }],
+  working_directory: "/path/to/project"  // Required - no process.cwd() fallback
+})
+
+// update_task_status example
+update_task_status({
+  task_id: "1.1",
+  status: "completed",
   working_directory: "/path/to/project"  // Required - no fallback
 })
 ```
 
+### Stray .swarm Detection
+
+`/swarm doctor` now detects and reports stray `.swarm` directories found in project subdirectories (created by older versions or misconfigured tools). It offers cleanup guidance to prevent state pollution.
+
 </details>
 
 <details>