clawmini 0.0.8 → 0.0.9

package/docs/25_e2e_test_improvements/prd.md

@@ -0,0 +1,43 @@
+# Product Requirements Document: E2E Test Framework Improvements
+
+## Vision
+To dramatically improve the speed, reliability, and developer experience of the Clawmini CLI end-to-end (E2E) test suite. By migrating from isolated, process-heavy polling tests to a modern, event-driven, shared-daemon architecture, we will reduce test execution time, eliminate filesystem flakiness, and provide a highly readable, declarative API for future test development.
+
+## Product / Market Background
+Currently, the E2E tests for the Clawmini CLI rely on a heavily isolated setup where almost every test file spins up its own temporary directory and its own instance of the daemon. Tests rely on filesystem mutations (using `fs.readFileSync` and `fs.writeFileSync`) and manual polling of `.jsonl` log files to verify behavior. 
+
+This approach has led to:
+1. **Slow Execution:** Spawning new Node processes for the CLI and starting/stopping the daemon repeatedly is incredibly time-consuming.
+2. **Flakiness:** Polling the filesystem using `setTimeout` and `vi.waitFor` is susceptible to race conditions, OS-level I/O delays, and timeouts.
+3. **Poor Developer Experience (DX):** Writing new tests requires copying extensive boilerplate to manage file paths, sanitize JSON, and manually invoke the CLI for setup tasks.
+
+## Use Cases
+1. **Adding a New CLI Feature Test:** A developer needs to write an E2E test for a new feature (e.g., a new policy approval flow). They use a fluent `TestEnvironment` API to easily inject mock agents, trigger the flow, and seamlessly await specific system events.
+2. **Refactoring the Core Daemon:** A developer makes a sweeping change to message routing. They run the entire E2E suite locally, which now completes in seconds rather than minutes because it uses a shared background daemon.
+3. **Testing Subagent Behaviors:** A developer verifies that a subagent correctly spawns a child process. They rely on the framework to automatically inject `clawmini-lite.js` into the test agent's `$PATH`, abstracting away the complex setup logic.
+
+## Requirements
+
+### 1. Unified Test Environment API
+- Introduce a high-level `TestEnvironment` or `TestFixture` class to manage E2E test setup.
+- **CLI-First Setup:** The environment should prefer using standard CLI commands (e.g., `clawmini agents add`, `clawmini chats add`) to configure the workspace state, falling back to manual file edits (e.g., for `policies.json`) only when the CLI does not expose that capability.
+- **Fluent Assertions/Waiters:** Provide domain-specific waiter functions (e.g., `await env.chat('default').waitForMessage({ role: 'system', event: 'policy_approved' })`) rather than relying on regex parsing of log files.
+
+### 2. Event-Driven State Verification (Replacing Filesystem Polling)
+- Tests must **stop polling `chat.jsonl` files**.
+- Leverage the existing Server-Sent Events (SSE) endpoint exposed by the daemon (currently used by adapters).
+- The test framework should connect an SSE client to the daemon and buffer events, allowing tests to asynchronously await specific message events in real-time. This increases test speed and accurately simulates how adapters interact with the daemon.
+
+### 3. Shared Daemon Architecture
+- Transition the test runner from a "one daemon per test suite" model to a "shared daemon" model.
+- A single daemon instance should be started during Vitest's `globalSetup` (or via a shared before-all hook) and reused across multiple test suites where feasible.
+- Tests must be designed to not fatally pollute the shared state. Where deep mutation is required, tests can run sequentially or utilize isolated chat/agent namespaces.
+
+### 4. Simplified Subagent Mocking
+- Remove the manual, verbose setup logic previously required for testing subagents (e.g., manually exporting the lite script and symlinking it to a `bin` folder).
+- Utilize the newly built-in feature where a designated test environment automatically exports `clawmini-lite.js` and injects it into the agent's `$PATH`. 
+- Provide a simple configuration toggle in the test fixture (e.g., `await env.enableSubagentEnvironment()`) to activate this feature.
+
+## Security & Privacy Concerns
+- **Port Conflicts:** When running tests in parallel, ensure the shared daemon or any isolated daemons bind to random available ports (`port: 0`) to prevent `EADDRINUSE` errors. The test framework must accurately capture the bound port and route test API requests accordingly.
+- **Isolation Boundaries:** If using a shared daemon, care must be taken to ensure test data (chats, agents, policies) does not leak between parallel runs in a way that causes false positives/negatives. Unique identifiers (e.g., UUID-suffixed chat names) should be generated by the `TestEnvironment` API.

package/docs/25_e2e_test_improvements/questions.md

@@ -0,0 +1,12 @@
+# Questions
+
+1. **Test Environment API:** Do you agree that we should build a more robust `TestEnvironment` or `TestFixture` class/helper to encapsulate the boilerplate of setting up the `.clawmini` workspace (creating directories, editing `settings.json`, adding policies/agents) and managing the CLI/daemon lifecycle?
+   * **Answer:** Yes, this direction seems good.
+2. **Polling vs. Events:** Currently, we poll `.jsonl` files on disk. This is a bit slow and flaky. Would you prefer we keep polling (but maybe optimize the helper functions) or should we add a test-only event stream (like an SSE endpoint or a local IPC socket) to the daemon to push events to the test runner?
+   * **Answer:** Use the existing SSE endpoint that the daemon exposes for adapters. It would be faster and more realistic.
+3. **Daemon Lifecycle:** In many tests, we start and stop the daemon per test or per suite. It takes time. Are you open to running a shared daemon where possible, or do you prefer the strict isolation of a fresh daemon + fresh directory for every test suite (the current approach)?
+   * **Answer:** Yes, running one daemon would be a big win.
+4. **Subagents Mocking:** We use `clawmini-lite.js` inside shell commands to mock subagents. Is this approach considered realistic enough, or do we want to provide actual mocked subagent binaries/scripts as part of the test harness?
+   * **Answer:** The verbosity should be reduced by using the built-in feature where an environment exports `clawmini-lite.js` and adds it to the `$PATH` for the agent.
+5. **JSON/Filesystem Mutation Abstraction:** I noticed across `cron.test.ts`, `environments.test.ts`, and others, there's significant use of `fs.readFileSync` and `fs.writeFileSync` to write simple JSON configs or scripts. This confirms the need for an abstracted setup layer. Should this test harness layer expose high-level domain operations like `env.addAgent({ ... })` or low-level generic file editors like `env.writeJson('path', payload)`?
+   * **Answer:** Ideally expose high-level domain operations that use the CLI wherever possible, and fall back on file editing only where necessary.

package/docs/25_e2e_test_improvements/tickets-2.md

@@ -0,0 +1,22 @@
+# E2E Test Improvements Tickets (Part 2)
+
+## Step 1: Migrate Remaining Tests to the New API
+- **Description**: Systematically refactor all remaining existing E2E tests to use the `TestEnvironment` API and the new SSE-based event waiting mechanism. Remove all manual file read/write polling.
+- **Verification**:
+  - Ensure the full E2E test suite passes reliably.
+  - Run `npm run validate`.
+- **Status**: not started
+
+## Step 2: Implement Shared Daemon Architecture
+- **Description**: Transition the E2E suite to use a shared daemon model. The daemon should be spun up during Vitest's `globalSetup` (or a shared hook), binding to `port: 0` to prevent collisions. Ensure tests leverage the `TestEnvironment`'s unique namespaces to avoid state leakage.
+- **Verification**:
+  - Run the entire test suite and verify a significant reduction in overall execution time. Check that tests pass without `EADDRINUSE` errors.
+  - Run `npm run validate`.
+- **Status**: not started
+
+## Step 3: Simplified Subagent Mocking
+- **Description**: Remove manual subagent shell-script scaffolding from tests. Introduce a configuration toggle (e.g., `enableSubagentEnvironment()`) in the test fixture to automatically inject `clawmini-lite.js` into the test agent's `$PATH` via the new built-in feature.
+- **Verification**:
+  - Verify that tests involving subagents still pass with the new streamlined setup.
+  - Run `npm run validate`.
+- **Status**: not started

package/docs/25_e2e_test_improvements/tickets.md

@@ -0,0 +1,22 @@
+# E2E Test Improvements Tickets (Part 1)
+
+## Step 1: Implement the Unified Test Environment API
+- **Description**: Create a high-level `TestEnvironment` or `TestFixture` class that abstracts the setup of E2E tests. It should provide methods to configure the workspace using standard CLI commands (e.g., `clawmini agents add`, `clawmini chats add`) and fallback to file edits where necessary. It should handle generating unique namespaces/IDs for isolated testing.
+- **Verification**: 
+  - Write unit tests for the new `TestEnvironment` class to verify its setup logic.
+  - Run `npm run validate`.
+- **Status**: complete
+
+## Step 2: Implement Event-Driven State Verification (SSE)
+- **Description**: Extend the `TestEnvironment` class to connect an SSE client to the daemon's existing endpoint. Buffer incoming events and implement fluent assertion/waiter functions (e.g., `waitForMessage(predicate)`) to replace filesystem polling.
+- **Verification**:
+  - Test the SSE client integration against a running daemon manually or via unit tests.
+  - Run `npm run validate`.
+- **Status**: complete
+
+## Step 3: Migrate a Single Test to the New API
+- **Description**: Refactor one specific E2E test file (e.g., `src/cli/e2e/messages.test.ts`) to use the `TestEnvironment` API and the new SSE-based event waiting mechanism. Remove all manual file read/write polling from this specific test.
+- **Verification**:
+  - Ensure the migrated E2E test passes reliably.
+  - Run `npm run validate`.
+- **Status**: complete

package/docs/25_policy_cwd/development_log.md

@@ -0,0 +1,30 @@
+# Development Log
+
+## Ticket 1: Schema and Type Updates
+Starting work on Ticket 1. Need to update:
+- `src/shared/config.ts`
+- `src/shared/policies.ts`
+- `src/cli/lite.ts`
+- `src/daemon/api/agent-router.ts`
+
+**Update:** Completed updates to `EnvironmentSchema` (added `baseDir`) and `PolicyRequest` (added `cwd`). Updated `clawmini-lite.js` (`src/cli/lite.ts`) to capture `process.cwd()` and pass it to `createPolicyRequest.mutate()`. Also updated `src/daemon/policy-request-service.ts` to fix a strict TypeScript error (`exactOptionalPropertyTypes`) when setting `cwd` conditionally.
+Ran `npm run validate` and all checks passed. Ticket 1 is complete.
+
+## Ticket 2: Smart Output Handling & CLI Output
+This ticket was found to be completely implemented already via a previous PR (`src/daemon/policy-utils.ts` now intercepts `stdout/stderr` writing to `./tmp`, and the tests pass), so the status was marked Complete.
+
+## Ticket 3: Path Translation Logic
+Implemented `translateSandboxPath(sandboxCwd, baseDir, agentDir)` in `src/daemon/policy-utils.ts`.
+- Handles stripping `baseDir` from `sandboxCwd` properly.
+- Checks if the resulting path stays within `agentDir` via `pathIsInsideDir` for security.
+- Comprehensive unit tests added to `src/daemon/policy-utils.test.ts`.
+- `npm run format` was executed.
+- Executed `npm run validate` successfully. All checks and tests (including new ones) have passed. Ticket 3 is marked Complete.
+
+## Ticket 4: Context-Aware Execution Integration
+- Found that `translateSandboxPath` was causing `ENOENT` in the `requests.test.ts` e2e test when `baseDir` was undefined and `sandboxCwd` was an absolute path outside the `agentDir`.
+- Fixed the E2E test `requests.test.ts` by ensuring `lite-env-dumper` is executed within its `agentDir` rather than the `e2eDir`, allowing `pathIsInsideDir` to validate correctly.
+- Confirmed the fix for the previous failure: `should synchronously output execution result for auto-approved policy`.
+- Validated the E2E test `context-cwd.test.ts` where the agent navigates to a subdirectory (`cd foo`) and invokes a `print-cwd` policy, effectively checking context-aware execution logic in `slash-policies.ts`.
+- Verified `hostCwd` fallback mapping to `agentDir`.
+- Executed `npm run validate` and resolved all linter/format issues. All E2E and unit tests passed. Ticket 4 is marked Complete.

package/docs/25_policy_cwd/notes.md

@@ -0,0 +1,28 @@
+# Policy CWD & Output File Notes
+
+## Current Implementation
+
+- `clawmini-lite.js` is the standalone client injected into environments. It runs inside the sandbox (e.g., Cladding, macOS).
+- `clawmini-lite.js request <cmd>` is handled in `src/cli/lite.ts`, which calls `client.createPolicyRequest.mutate(...)` on the TRPC API.
+- The `createPolicyRequest` procedure in `src/daemon/api/agent-router.ts` receives the command, args, and file mappings.
+- The request is stored as a `PolicyRequest` (defined in `src/shared/policies.ts`).
+- When a policy is approved, `src/daemon/routers/slash-policies.ts` executes the command using `executeRequest` (from `src/daemon/policy-utils.ts`), passing `getWorkspaceRoot()` as the `cwd`.
+- `executeRequest` also uses `getWorkspaceRoot()` for auto-approved policies.
+
+## Path Translation
+
+- `src/daemon/api/router-utils.ts` has `resolveAgentDir(agentId, workspaceRoot)` which returns the host directory for an agent.
+- Environments are defined in `src/shared/config.ts` (`EnvironmentSchema`).
+- The prompt suggests adding a property to environments (like `baseDir`) to indicate what the environment considers its root (e.g., `/home/user`).
+- If an environment specifies `baseDir: '/home/user'`, and `clawmini-lite.js` reports `cwd` as `/home/user/project/src`, the daemon can translate this by stripping `/home/user` and resolving the rest against the agent's host directory (`agentDir`).
+- How does the daemon know which environment the agent is running in? The chat settings or agent settings might define the environment.
+
+## Output File
+
+- A new option `--output-file <path>` (or similar) will be added to `clawmini-lite.js request`.
+- The prompt asks to figure out a standard way to pass the output of both stdout and stderr.
+- Possibilities:
+  1. Interleave stdout and stderr into one file.
+  2. Output them as a JSON structure `{ "stdout": "...", "stderr": "..." }`.
+  3. Support separate arguments like `--stdout-file <path>` and `--stderr-file <path>`.
+  4. Write standard output to the file, and standard error to the console (or vice versa).

package/docs/25_policy_cwd/prd.md

@@ -0,0 +1,77 @@
+# Product Requirements Document (PRD): Policy Execution Context and Output Handling
+
+## Vision
+
+To enhance the reliability and usability of policy requests within Clawmini's sandboxed environments. This is achieved by ensuring policies execute in the correct working directory relative to the agent's sandbox, and by improving how large policy execution outputs (stdout/stderr) are returned to the agent, preventing truncation issues and keeping the chat history clean.
+
+## Product / Market Background
+
+Currently, when a sandboxed agent uses `clawmini-lite.js request <policy>`, the daemon executes the policy in the root directory of the workspace, regardless of where the agent invoked the command inside its sandbox. This causes friction, as agents often expect commands to run in their current working directory (`cwd`) and must resort to passing absolute paths as arguments.
+
+Furthermore, if a policy generates a large amount of output, including it directly in the JSON response or chat message can overwhelm the context window or result in truncated logs. A robust mechanism to handle varying sizes of standard output and standard error is necessary.
+
+## Use Cases
+
+1. **Context-Aware Policy Execution:** An agent running in a macOS proxy environment navigates to `~/project/src` inside its sandbox and issues a policy request. The host daemon translates `~/project/src` to the corresponding host directory (e.g., `/Users/tbuckley/projects/agent-1/project/src`) and executes the policy command there.
+2. **Handling Large Output Logs:** A policy request performs a large build task that outputs 5000 characters to `stdout`. Instead of returning the massive text directly in the message, the daemon saves the output to a temporary file (e.g., `./tmp/stdout-<id>.txt` within the agent's directory) and responds with a summary: "stdout is 5000 characters, saved to ./tmp/stdout-<id>.txt".
+
+## Requirements
+
+### 1. Environment `baseDir` Configuration
+
+- The `EnvironmentSchema` (in `src/shared/config.ts`) must be updated to include an optional `baseDir` string property.
+- `baseDir` represents the root path _inside_ the sandbox that maps to the agent's root directory on the host.
+- If `baseDir` is undefined, the system assumes the sandbox shares the host filesystem (no path translation required).
+
+### 2. Path Translation for Policy Execution
+
+- `clawmini-lite.js` (specifically `src/cli/lite.ts`) must capture its current working directory (`process.cwd()`) and send it as part of the `createPolicyRequest` mutation.
+- The `PolicyRequest` type must be updated to include an optional `cwd` property.
+- When the daemon executes an approved policy (both manual and auto-approved), it must translate the requested `cwd` from the sandbox perspective to an absolute path on the host.
+- **Translation Logic:** If the environment has a `baseDir` defined (e.g., `/home/user`), and the requested `cwd` starts with that `baseDir` (e.g., `/home/user/foo`), the daemon strips the `baseDir` and resolves the remainder (`/foo`) against the agent's root directory on the host (`agentDir`).
+- The translated path must be validated to ensure it does not break out of the agent's allowed workspace directory. If it attempts to escape the directory, execution should fail safely.
+- The policy must be executed with the translated directory as its `cwd` instead of `getWorkspaceRoot()`.
+
+### 3. Smart Output Handling
+
+- The response mechanism for policy execution (both the CLI output from `clawmini-lite.js` and the chat messages sent back to the agent) must dynamically handle `stdout` and `stderr`.
+- For `stdout` and `stderr` independently:
+  - If the output length is **less than 500 characters**, include it directly in the message payload as text.
+  - If the output length is **greater than or equal to 500 characters**, the daemon must:
+    1. Create a file inside the agent's local `./tmp/` directory (e.g., `./tmp/stdout-<id>.txt` or `./tmp/stderr-<id>.txt`).
+    2. Write the full output to this file.
+    3. Include a reference string in the message payload instead of the raw text, formatted as: `stdout is <length> characters, saved to ./tmp/stdout-<id>.txt`. (Substitute `stderr` as appropriate).
+
+### 4. Updates to `clawmini-lite.js` Output
+
+- `clawmini-lite.js request` must output the results to the terminal so the agent can read them.
+- If the output was saved to a file, the CLI must print the reference string (e.g., "stdout is 1234 characters, saved to ./tmp/stdout-foo.txt") so the agent knows where to find the data.
+- The `executeRequest` result must return the structured info needed to determine if the output was inline or saved to a file.
+
+## Technical Details & Architecture Notes
+
+- Modifying `createPolicyRequest` in `src/daemon/api/agent-router.ts` to accept `cwd`.
+- The `Environment` definition will be accessed via the active chat settings or agent definition to resolve `baseDir`.
+- Update `src/daemon/routers/slash-policies.ts` and auto-approve logic to invoke the path translation helper.
+- Update `executeSafe` or the caller in `executeRequest` to write to `./tmp/` and construct the modified response payload.
+
+## Privacy, Security, and Accessibility Concerns
+
+- **Security (Path Traversal):** The path translation mechanism must rigorously ensure the final translated host path is strictly within the agent's assigned directory on the host (`pathIsInsideDir`). A malicious agent could manipulate the sandbox `cwd` to escape the directory if `baseDir` replacement isn't carefully validated.
+- **Security (File Permissions):** Temporary output files written to `./tmp/` must be readable by the agent running within the sandbox.
+- **Resource Limits:** Large outputs saved to `./tmp/` should be reasonably sized. While file limits aren't explicitly requested here, writing massive outputs should be monitored to prevent disk exhaustion.
+
+## Testing & Validation
+
+We will use explicit End-to-End (E2E) tests leveraging the `debug` agent template (which echoes executed commands and their output) to validate this behavior:
+
+1. **Context-Aware `cwd` Test:**
+   - Define a policy that runs `pwd` and has autoApprove:true.
+   - Start an agent using the `debug` template.
+   - Using `clawmini-lite.js` within a sub-directory of the agent (e.g., `cd foo && clawmini-lite.js request pwd`), request the `pwd` policy.
+   - Validate that the policy prints the correct mapped subdirectory path (i.e. resolving to `foo` inside the agent's host directory, not the workspace root).
+2. **Smart Output Length Tests:**
+   - Define a policy that generates short output (< 500 chars) and one that generates long output (>= 500 chars), both with autoApprove:true.
+   - For the short output policy, validate that the output is included directly inline within the response.
+   - For the long output policy, validate that the direct output text is suppressed and instead the response contains the correctly formatted reference string: `stdout is <length> characters, saved to ./tmp/stdout-<id>.txt`. Ensure the file is created in the expected location.
+   - Ensure the agent can run `more ./tmp/stdout-<id>.txt` to read the contents.

package/docs/25_policy_cwd/questions.md

@@ -0,0 +1,6 @@
+# Questions
+
+1. What should we name the property in `EnvironmentSchema` that represents the base directory inside the sandbox? (e.g., `baseDir`, `sandboxRoot`, `targetDir`)
+A: `baseDir`. It should be optional, and if unspecified we assume the environment and host share the same filesystem, so a path within the environment is the same as outside.
+2. Regarding the output file for `clawmini-lite.js request` ("We should figure out a standard way to pass the output of both stdout and stderr"): would you prefer separate flags (e.g., `--stdout-file` and `--stderr-file`), a single file interleaving both streams, or a single JSON file containing `{ "stdout": "...", "stderr": "..." }`?
+A: Instead of letting it specify a file, we instead look at the length of stdout/stderr. For each, we check if it's <500 characters and include it in the message if so. If >=500 characters, we create a tmp file (like inside the agent's directory in a ./tmp/ folder) and include the path + total length of the output in the message, like "stdout is 1234 characters, saved to ./tmp/stdout-foo.txt".

package/docs/25_policy_cwd/tickets.md

@@ -0,0 +1,77 @@
+# Policy CWD & Output Tickets
+
+## Ticket 1: Schema and Type Updates
+**Status**: Complete
+
+**Tasks:**
+- Update `src/shared/config.ts` (`EnvironmentSchema`) to include an optional `baseDir` string property.
+- Update `src/shared/policies.ts` (`PolicyRequest`) to include an optional `cwd` string property.
+- Update `src/cli/lite.ts` to capture `process.cwd()` and include it when calling `createPolicyRequest.mutate(...)`.
+- Update `src/daemon/api/agent-router.ts` (`createPolicyRequest` procedure) to accept the new `cwd` parameter.
+
+**Verification:**
+- Run `npm run validate` to ensure TypeScript compilation, linting, and formatting pass without errors.
+
+## Ticket 2: Smart Output Handling & CLI Output
+**Status**: Complete
+
+**Tasks:**
+- Write an E2E test using the `debug` agent template that creates two auto-approved policies: one generating < 500 characters of output, and one generating >= 500 characters. 
+- Ensure the E2E test fails (Red phase).
+- Update `executeRequest` (or the underlying execution logic in `src/daemon/policy-utils.ts`) to intercept `stdout` and `stderr`.
+- If the output is < 500 chars, return it inline.
+- If the output is >= 500 chars:
+  - Write it to `./tmp/stdout-<id>.txt` (or stderr) inside the agent's host directory.
+  - Return the summary string: `stdout is <length> characters, saved to ./tmp/stdout-<id>.txt`.
+- Update `src/cli/lite.ts` to output the returned string or inline output to the terminal so the agent can read it.
+- Ensure the E2E test passes (Green phase).
+
+**Verification:**
+- The new Smart Output E2E test passes.
+- Run `npm run validate` to ensure all checks pass.
+
+## Ticket 3: Path Translation Logic
+**Status**: Complete
+
+**Tasks:**
+- Create a path translation helper function (e.g., in `src/daemon/api/router-utils.ts` or `src/daemon/policy-utils.ts`) that takes the sandbox `cwd`, environment `baseDir`, and host `agentDir`.
+- Implement logic to strip `baseDir` from `cwd` and resolve the remainder against `agentDir`.
+- Implement security validation to ensure the resulting path does not escape `agentDir` (prevent path traversal/directory escape).
+- Write comprehensive unit tests for this translation helper, testing valid paths, undefined `baseDir`, and malicious escape attempts.
+
+**Verification:**
+- Run the new unit tests and ensure they pass.
+- Run `npm run validate` to ensure all checks pass.
+
+## Ticket 4: Context-Aware Execution Integration
+**Status**: Complete
+
+**Tasks:**
+- Write an E2E test using the `debug` agent template where the agent navigates to a subdirectory (e.g., `cd foo`) and invokes a `pwd` policy.
+- Ensure the E2E test fails (Red phase), as it will currently return the workspace root.
+- Update `src/daemon/routers/slash-policies.ts` and the auto-approve logic to look up the active chat/agent's environment configuration.
+- Use the path translation helper from Ticket 3 to determine the correct host `cwd` for the policy execution.
+- Pass the translated host `cwd` into `executeRequest` instead of `getWorkspaceRoot()`.
+- Ensure the E2E test passes (Green phase).
+
+**Verification:**
+- The new Context-Aware Execution E2E test passes.
+- Run `npm run validate` to ensure all system checks pass.
+
+## Ticket 5: DRY Violation for host cwd resolution
+**Status**: Complete
+
+**Tasks:**
+- The logic to resolve the host working directory using `getActiveEnvironmentInfo`, `readEnvironment`, and `translateSandboxPath` is duplicated identically in `src/daemon/api/agent-policy-endpoints.ts` and `src/daemon/routers/slash-policies.ts`. Extract this into a reusable function in `src/daemon/policy-utils.ts`.
+
+**Verification:**
+- Run `npm run validate` to ensure all checks pass.
+
+## Ticket 6: Leftover Debug Logs
+**Status**: Complete
+
+**Tasks:**
+- `src/daemon/policy-utils.ts` contains `console.log` statements in `translateSandboxPath` that were likely meant for debugging and should be removed.
+
+**Verification:**
+- Run `npm run validate` to ensure all checks pass.

package/docs/CLI_REFERENCE.md

@@ -3,7 +3,9 @@
 ### Initialization & Daemon
 - `clawmini init`: Initialize a new `.clawmini` configuration folder.
 - `clawmini up`: Start the local daemon server in the background.
-- `clawmini down`: Stop the local daemon server.
+- `clawmini serve [--detach] [--only <services>] [--exclude <services>]`: Run the daemon, web UI, and any configured adapters under a single supervisor with interleaved prefixed logs. Use `--detach` to run in the background. Adapters (`discord`, `google-chat`) are auto-detected by the presence of their config files.
+- `clawmini logs [-f] [-s <service>] [-n <lines>]`: View logs from `clawmini serve` services.
+- `clawmini down`: Stop the local supervisor (if running) or daemon.
 - `clawmini export-lite [--out <path>] [--stdout]`: Export the standalone `clawmini-lite` client script.
 
 ### Chat Management

package/docs/PHILOSOPHY.md

@@ -0,0 +1,35 @@
+Clawmini evolves agent CLIs (currently Gemini CLI and OpenCode, and in future Claude Code and Codex) into secure & proactive assistants.
+
+- Secure: can only access the network through allowlisted commands and human approval
+- Proactive: always available, always working
+- Assistant: one consistent personality across a single long-running chat
+
+The basics
+
+- When users message an agent, Clawmini converts it into a shell command to run and replies with the output.
+- Users most often message an agent through a chat app like Discord or Google Chat, though there is a built in web app and CLI for debugging.
+- Agents are defined by (1) a command to run when messages are received, usually for an agent CLI; (2) a folder to use as cwd; (3) env vars to set.
+- Most agent CLIs allow guiding their behavior via custom system prompts, per-folder AGENTS.md files, and Skills
+- Most agent CLIs expose hooks to monitor and adjust their behavior as they run (ex log a tool call before it is run, inject notifications when a tool call finishes, or prevent a model from stopping by sending a next prompt)
+
+Security model:
+
+- The Clawmini daemon exposes separate APIs for users (trusted) and agents (untrusted)
+- The Clawmini daemon runs agents inside a sandbox with no network access (except for LLM APIs), so they cannot exfiltrate private data by default; and limited file access so they cannot modify sensitive configuration data
+- The Clawmini daemon stores its configuration inside a .clawmini folder within the workspace root, including sensitive files that the agent should not be able to edit like commands to execute; and potentially sensitive files that the agent should not be allowed to read like chats with other agents
+- Agents are given a `clawmini-lite.js` script on their $PATH that allows them to interact with the daemon outside the sandbox through the untrusted agent API. The daemon distinguishes trusted (user) from untrusted (agent) callers via a per-workspace `CLAW_API_TOKEN` injected into the agent's environment.
+- Agents can request the daemon run user-allowlisted commands outside the sandbox and receive the output. Users decide whether commands run automatically or require human review depending on the sensitivity (ex always ok to read emails or create drafts, but sending an email requires approval). An agent can even request to allowlist new commands!
+
+Proactivity model:
+
+- Agents can schedule messages to send themselves in the future (one-off or recurring), waking up to perform work. Users do not see these scheduled messages, only the agent’s output.
+- Agents cannot do any blocking work so they always remain available for the user. For long-running tasks they delegate to a subagent and get notified when it finishes; subagents run to completion and may block on their own async work.
+- To avoid huge costs, there is a limit to how many subagents can run in parallel.
+- Agents receive any pending messages after each tool call, allowing for steering while the model is running
+- If no message should be shared with the user, the agent can respond with NO_REPLY_NECESSARY
+
+Memory model
+
+- Users interact with an agent through a single ongoing chat. However, agent context is limited and quality degrades as it gets longer.
+- The agent’s personality and memory are persisted via files; it is instructed to read the personality and recent memory files at the start, and search the memory when appropriate.
+- We regularly clear the session after timeout and tell it to save anything important to memory files