@josstei/maestro 1.6.4-nightly.20260430

package/src/skills/shared/session-management/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: session-management
+description: Manages orchestration session state, tracking, and resumption
+---
+
+# Session Management Skill
+
+Activate this skill for all session state operations during Maestro orchestration. This skill defines the protocols for creating, updating, resuming, and archiving orchestration sessions.
+
+## State Access Protocol
+
+When MCP state tools are available, prefer them for state operations:
+- **Preferred**: MCP tools (`initialize_workspace`, `create_session`, `update_session`, `transition_phase`, `get_session_status`, `archive_session`) — structured I/O, atomic operations.
+- **Fallback**: `write_file`/`replace` directly on state files — when MCP tools are not in the available tool list.
+- **Legacy**: Shell scripts (`write-state.js`, `read-state.js`) — remain available but are not the recommended path.
+
+Detection: check whether MCP state tools appear in your available tools. If they do, use them. If they do not, use `write_file`/`replace`.
+
+## Hook-Level Session State
+
+Maestro hooks maintain a separate, transient state directory under `${MAESTRO_HOOKS_DIR:-<os.tmpdir()>/maestro-hooks-<uid>}/<session-id>/` that is distinct from orchestration state in `<MAESTRO_STATE_DIR>`:
+
+| Concern | Orchestration State | Hook State |
+| --- | --- | --- |
+| Location | `<MAESTRO_STATE_DIR>/state/` | `${MAESTRO_HOOKS_DIR:-<os.tmpdir()>/maestro-hooks-<uid>}/<session-id>/` |
+| Lifecycle | Created at execution setup, archived in Phase 4 | Directory created by the session-start hook when an active session exists; active-agent file written by the pre-delegation hook and cleared by the post-delegation hook; stale directories pruned by both session-start and pre-delegation hooks |
+| Contents | Session metadata, phase tracking, token usage, file manifests | Active agent tracking file (`active-agent`) |
+| Persistence | Survives session restarts (supports `/maestro:resume`) | Ephemeral — lost on session end or system reboot |
+| Managed by | Orchestrator via session-management skill | The runtime's pre-delegation and post-delegation hooks |
+
+The pre-delegation hook prunes stale hook state directories older than 2 hours to prevent accumulation from abnormal session terminations.
+
+The orchestrator does not read or write hook-level state directly. It interacts only with `<MAESTRO_STATE_DIR>` paths. The two state systems are independent and serve different concerns.
+
+## Session Creation Protocol
+
+### When to Create
+For Standard workflow, create a new session at execution setup after the design document and implementation plan are approved and the execution mode gate has resolved. For Express workflow, create a session after the structured brief is approved (see Express Workflow section in the orchestrator template).
+
+### Session ID Format
+`YYYY-MM-DD-<topic-slug>`
+
+Where:
+- `YYYY-MM-DD` is the orchestration start date
+- `<topic-slug>` is a lowercase, hyphenated summary matching the design document topic
+
+### File Location
+`<MAESTRO_STATE_DIR>/state/active-session.md`
+
+All state paths in this skill use `<MAESTRO_STATE_DIR>` as their base directory (default: `docs/maestro`). In procedural steps, `<state_dir>` represents the resolved value of this variable.
+
+### State File Access
+
+Both `read_file` and `write_file` work on state paths inside `<MAESTRO_STATE_DIR>`. The runtime's file-access configuration makes state paths accessible.
+
+Use the runtime's bundled `scripts/` directory for these helper commands so they still work when the extension is installed outside the workspace root.
+
+**Reading state files:**
+Use `read_file` directly. The `read-state.js` script remains available as an alternative for TOML shell blocks that inject state before the model's first turn:
+
+`run_shell_command`: `node <runtime-script-root>/read-state.js <relative-path>`
+
+**Writing state files:**
+Use `write_file` directly. When content must be piped from a shell command, use the atomic write script:
+
+`run_shell_command`: `echo '...' | node <runtime-script-root>/write-state.js <relative-path>`
+
+**Rules:**
+- The `write-state.js` script writes atomically (temp file + rename) to prevent partial writes
+- Both scripts validate against absolute paths and path traversal
+
+### Initialization Steps
+1. Resolve state directory from `MAESTRO_STATE_DIR`
+2. Create `<state_dir>/state/` directory if it does not exist (defense-in-depth fallback — workspace readiness startup check is the primary mechanism)
+3. Verify no existing `active-session.md` — if one exists, alert the user and offer to archive or resume
+4. Generate session state using the `session-state` template loaded via `get_skill_content`
+5. Initialize all phases as `pending`
+6. Set overall status to `in_progress`
+7. Set `current_phase` to 1
+8. Record design document and implementation plan paths
+9. Initialize empty token_usage, file manifests, downstream_context, and errors sections
+
+### Initial State Template
+
+```yaml
+---
+session_id: "<YYYY-MM-DD-topic-slug>"
+task: "<user's original task description>"
+created: "<ISO 8601 timestamp>"
+updated: "<ISO 8601 timestamp>"
+status: "in_progress"
+workflow_mode: "<standard|express>"
+design_document: "<state_dir>/plans/<design-doc-filename>"
+implementation_plan: "<state_dir>/plans/<impl-plan-filename>"
+current_phase: 1
+total_phases: <integer from impl plan>
+execution_mode: null
+execution_backend: null
+task_complexity: null
+
+token_usage:
+  total_input: 0
+  total_output: 0
+  total_cached: 0
+  by_agent: {}
+
+phases:
+  - id: 1
+    name: "<phase name from impl plan>"
+    status: "pending"
+    agents: []
+    parallel: false
+    started: null
+    completed: null
+    blocked_by: []
+    files_created: []
+    files_modified: []
+    files_deleted: []
+    downstream_context:
+      key_interfaces_introduced: []
+      patterns_established: []
+      integration_points: []
+      assumptions: []
+      warnings: []
+    errors: []
+    retry_count: 0
+---
+
+# <Topic> Orchestration Log
+```
+
+Include `task_complexity` (from design document frontmatter) in the session state. Place after `execution_backend`, before `token_usage`. Default: `null`.
+
+## State Update Protocol
+
+### Update Triggers
+Update session state on every meaningful state change:
+- Phase status transitions
+- File manifest changes
+- Downstream context extraction from completed phases
+- Error occurrences
+- Token usage increments
+- Phase completion or failure
+
+### Update Rules
+
+1. **Timestamp**: Update `updated` field on every state change
+2. **Phase Status**: Transition phase status following valid transitions:
+   - `pending` -> `in_progress`
+   - `in_progress` -> `completed`
+   - `in_progress` -> `failed`
+   - `failed` -> `in_progress` (retry)
+   - `pending` -> `skipped` (user decision only)
+3. **Current Phase**: Update `current_phase` to the ID of the currently executing phase
+4. **File Manifest**: Append to `files_created`, `files_modified`, or `files_deleted` as subagents report changes
+5. **Downstream Context**: Persist parsed Handoff Report Part 2 fields into phase `downstream_context`
+6. **Token Usage**: Aggregate token counts from subagent responses into both `total_*` and `by_agent` sections
+7. **Error Recording**: Append to phase `errors` array with complete metadata
+
+### Error Recording Format
+
+```yaml
+errors:
+  - agent: "<agent-name>"
+    timestamp: "<ISO 8601>"
+    type: "<validation|timeout|file_conflict|runtime|dependency>"
+    message: "<full error description>"
+    resolution: "<what was done to resolve, or 'pending'>"
+    resolved: false
+```
+
+### Retry Tracking
+- Increment `retry_count` on each retry attempt
+- Maximum 2 retries per phase before escalating to user
+- Record each retry as a separate error entry with resolution details
+
+### Markdown Body Updates
+After updating YAML frontmatter, append to the Markdown body:
+
+```markdown
+## Phase N: <Phase Name> <status indicator>
+
+### <Agent Name> Output
+[Summary of agent output or full content]
+
+### Files Changed
+- Created: [list]
+- Modified: [list]
+
+### Downstream Context
+- Key Interfaces Introduced: [list]
+- Patterns Established: [list]
+- Integration Points: [list]
+- Assumptions: [list]
+- Warnings: [list]
+
+### Validation Result
+[Pass/Fail with details]
+```
+
+Status indicators:
+- Completed: checkmark
+- In Progress: circle
+- Failed: cross
+- Pending: square
+- Skipped: dash
+
+## Archive Protocol
+
+### When to Archive
+Archive session state when:
+- All phases are completed successfully AND `MAESTRO_AUTO_ARCHIVE` is `true` (default)
+- User explicitly requests archival (regardless of `MAESTRO_AUTO_ARCHIVE` setting)
+- User starts a new orchestration (previous session must be archived first, regardless of setting)
+
+When `MAESTRO_AUTO_ARCHIVE` is `false`, prompt the user after successful completion: "Session complete. Auto-archive is disabled. Would you like to archive this session?"
+
+### Archive Steps
+If `archive_session` appears in your available tools, use it — a single call handles all archival:
+
+1. Call `archive_session` with the session ID. The MCP tool atomically:
+   - Updates session status to `completed`
+   - Moves `active-session.md` to `<state_dir>/state/archive/<session-id>.md`
+   - Moves design document to `<state_dir>/plans/archive/` (if it exists and is non-null)
+   - Moves implementation plan to `<state_dir>/plans/archive/` (if it exists and is non-null)
+2. Confirm archival to user with summary of what was archived (use the `archived_files` array in the response)
+
+If `archive_session` is not available, fall back to manual file operations:
+1. Create `<state_dir>/plans/archive/` directory if it does not exist
+2. Create `<state_dir>/state/archive/` directory if it does not exist
+3. **MOVE** (not copy) design document from `<state_dir>/plans/` to `<state_dir>/plans/archive/` — the original MUST be deleted. Use the shell-command tool from runtime context with `mv` or read+write+delete. Do NOT leave the file in both locations. **Skip this step if `design_document` is `null` (Express sessions).**
+4. **MOVE** (not copy) implementation plan from `<state_dir>/plans/` to `<state_dir>/plans/archive/` — same: delete the original. **Skip this step if `implementation_plan` is `null` (Express sessions).**
+5. Update session state `status` to `completed`
+6. Update `updated` timestamp
+7. **MOVE** (not copy) `active-session.md` from `<state_dir>/state/` to `<state_dir>/state/archive/<session-id>.md` — delete the original.
+8. Confirm archival to user with summary of what was archived
+
+### Archive Verification
+After archival, verify ALL of the following (archive is incomplete if any check fails):
+- No `active-session.md` exists in `<state_dir>/state/`
+- No plan files remain in `<state_dir>/plans/` (only the `archive/` subdirectory should be present)
+- Archived files are readable at their new locations in `archive/`
+- If files still exist in the original locations, delete them now — the archive step used copy instead of move
+
+## Resume Protocol
+
+### When to Resume
+Resume is triggered by the `/maestro:resume` command or when `/maestro:orchestrate` detects an existing active session.
+
+### Resume Steps
+
+1. **Read State**: If session state was already injected into the prompt (e.g., via `/maestro:resume`), use that injected content instead of calling `get_session_status`. Otherwise, if `get_session_status` appears in your available tools, call it to read the active session. Otherwise, read state via `run_shell_command`: `node <runtime-script-root>/read-active-session.js` (resolves `MAESTRO_STATE_DIR` internally)
+2. **Parse Frontmatter**: Extract YAML frontmatter for session metadata
+3. **Identify Position**: Determine:
+   - Last completed phase (highest ID with `status: completed`)
+   - Current active phase (first phase with `status: in_progress` or `pending`)
+   - Any failed phases with unresolved errors
+4. **Check Errors**: Identify unresolved errors from previous execution
+5. **Present Summary**: Display status summary to user using the resume format defined in the orchestrator instructions
+6. **Handle Errors**: If unresolved errors exist:
+   - Present each error with context
+   - Offer options: retry, skip, abort, or adjust parameters
+   - Wait for user guidance before proceeding
+7. **Continue Execution**: Resume from the first pending or failed phase
+8. **Update State**: Mark resumed phase as `in_progress` and update timestamps
+
+### Express Resume Branch
+
+When resuming a session with `workflow_mode: "express"` (read from session state via `get_session_status`), follow the Express workflow's resume protocol instead of the standard resume steps above:
+
+- If phase status is `pending`: re-generate and present the structured brief for approval. On approval, proceed to delegation.
+- If phase status is `in_progress`: the implementing agent was interrupted. Re-delegate with the same scope. Use the `agents` array to identify which agent was running.
+- If phase status is `completed` but session status is `in_progress`: code review or archival was interrupted. Run the code review step, then archive.
+
+Express sessions have a single phase. The phase status combined with the `agents` array contents determines the resume position.
+
+### Conflict Detection
+When resuming, check for potential conflicts:
+- Files that were partially modified (phase started but not completed)
+- External modifications to files in the manifest since last session
+- Changes to the implementation plan since last execution
+
+Report any detected conflicts to the user before proceeding.
+
+## Token Usage Tracking
+
+### Collection
+After each subagent invocation, record:
+- Input tokens consumed
+- Output tokens generated
+- Cached tokens used (if available)
+
+### Aggregation
+Maintain two levels of aggregation:
+1. **Total**: Sum across all agents and phases
+2. **By Agent**: Per-agent totals across all their invocations
+
+### Format
+
+```yaml
+token_usage:
+  total_input: 15000
+  total_output: 8000
+  total_cached: 3000
+  by_agent:
+    coder:
+      input: 8000
+      output: 4000
+      cached: 2000
+    tester:
+      input: 7000
+      output: 4000
+      cached: 1000
+```

package/src/skills/shared/validation/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: validation
+description: Cross-cutting validation methodology for verifying phase outputs and project integrity
+---
+
+# Validation Skill
+
+Activate this skill when validating phase outputs during orchestration execution or when running standalone validation checks. This skill provides the pipeline, heuristics, and interpretation rules for verifying that changes meet quality standards.
+
+## Validation Pipeline
+
+Execute validation steps in this order. Stop on the first blocking failure unless the user explicitly requests continuing.
+
+### Step 1: Build / Compile
+Verify the project compiles without errors.
+
+| Project Type | Command |
+|-------------|---------|
+| Node.js (TypeScript) | `npx tsc --noEmit` |
+| Node.js (JavaScript) | N/A (skip) |
+| Rust | `cargo build` |
+| Go | `go build ./...` |
+| Python | `python -m py_compile [files]` |
+| Java (Maven) | `mvn compile` |
+| Java (Gradle) | `./gradlew compileJava` |
+
+### Step 2: Lint / Format
+Verify code meets style and quality standards.
+
+| Project Type | Command |
+|-------------|---------|
+| Node.js | `npx eslint . && npx prettier --check .` |
+| Rust | `cargo clippy && cargo fmt --check` |
+| Go | `go vet ./... && gofmt -l .` |
+| Python | `ruff check . && ruff format --check .` |
+| Java | `mvn checkstyle:check` or `./gradlew checkstyleMain` |
+
+### Step 3: Unit Tests
+Run unit tests to verify behavior preservation.
+
+| Project Type | Command |
+|-------------|---------|
+| Node.js (Jest) | `npx jest` |
+| Node.js (Vitest) | `npx vitest run` |
+| Rust | `cargo test` |
+| Go | `go test ./...` |
+| Python (pytest) | `python -m pytest tests/` |
+| Java (Maven) | `mvn test` |
+| Java (Gradle) | `./gradlew test` |
+
+### Step 4: Integration Tests
+Run integration tests if available and applicable.
+
+Detect integration test presence by looking for:
+- `tests/integration/`, `test/integration/`, or `**/integration_test*` directories/files
+- Test files with `integration` in the name
+- Test scripts in package.json (e.g., `test:integration`)
+
+### Step 5: Manual Verification
+For changes that cannot be automatically validated, present a checklist to the user.
+
+## Project Type Detection
+
+Detect the project type by checking for the presence of these files in the project root:
+
+| Indicator File | Project Type |
+|---------------|-------------|
+| `package.json` | Node.js (check for `typescript` dep for TS) |
+| `Cargo.toml` | Rust |
+| `go.mod` | Go |
+| `pyproject.toml` or `setup.py` | Python |
+| `pom.xml` | Java (Maven) |
+| `build.gradle` or `build.gradle.kts` | Java (Gradle) |
+| `Gemfile` | Ruby |
+| `*.csproj` or `*.sln` | .NET |
+
+When multiple indicators are present, validate each project type independently.
+
+## Validation Result Interpretation
+
+### Pass
+All executed validation steps completed with exit code 0. No errors or warnings that indicate broken functionality.
+
+### Fail (Blocking)
+Any of the following constitute a blocking failure:
+- Build/compile errors
+- Lint errors (not warnings, unless the project treats warnings as errors)
+- Test failures
+- Type errors
+
+### Warn (Non-Blocking)
+The following are recorded but do not block progression:
+- Lint warnings (when not configured as errors)
+- Deprecation notices
+- Coverage decreases (unless coverage threshold is configured)
+- Format-only issues (can be auto-fixed)
+
+## Validation Modes
+
+The validation strictness is controlled by `MAESTRO_VALIDATION_STRICTNESS` (default: `normal`).
+
+| Mode | Behavior |
+|------|----------|
+| `strict` | Warnings are treated as blocking failures. All lint warnings, deprecation notices, and coverage decreases block phase progression. |
+| `normal` | Only errors block. Warnings are recorded but do not prevent phase completion. This is the default behavior described in the Pass/Fail/Warn sections above. |
+| `lenient` | Nothing blocks automatically. All failures and warnings are recorded in session state and reported to the user, but phase progression continues. The user reviews the accumulated report at completion. |
+
+### Strictness Application
+
+When evaluating each validation step:
+1. Run the validation command and capture the exit code and output
+2. Classify the result as Pass, Fail (Blocking), or Warn (Non-Blocking) using the standard criteria above
+3. Apply the strictness mode:
+   - `strict`: Fail (Blocking) AND Warn (Non-Blocking) both stop progression
+   - `normal`: Only Fail (Blocking) stops progression
+   - `lenient`: Record everything, stop nothing — append all results to session state and continue
+4. If strictness causes a result to be downgraded from blocking to non-blocking, note this in the validation output: "Warning recorded but not blocking (lenient mode)"
+
+## Post-Phase Validation
+
+### When to Validate
+Run validation after:
+- Every phase that creates or modifies source code
+- Every parallel batch completion (validate the combined result)
+- Before marking any phase as `completed`
+
+### When to Skip Validation
+Skip validation when:
+- The phase only modified documentation files
+- The phase only produced read-only analysis (`architect`, `code-reviewer` reports)
+- The user explicitly requests skipping validation
+
+Record `skipped` with rationale in the phase validation result.
+
+## Manual Verification Checklist
+
+For changes that cannot be automatically validated, present this checklist template:
+
+```
+### Manual Verification Required
+
+The following changes require manual verification:
+
+- [ ] [Description of what to verify]
+- [ ] [Visual/UI changes look correct]
+- [ ] [Integration with external service works]
+- [ ] [Environment-specific behavior confirmed]
+
+Please confirm these items are verified before I mark this phase as complete.
+```
+
+Use manual verification for:
+- UI/visual changes
+- External service integrations
+- Environment-specific configurations
+- Performance improvements (require load testing)
+- Security remediations (require penetration testing)
+
+## Incremental Validation Mode
+
+When full pipeline validation is unnecessary, use targeted validation based on the type of changes in the completed phase:
+
+### Validation Scope by Change Type
+- **Phase created new files only** (no existing files modified): Run lint + type check on the new files only. This provides fast feedback without running the full test suite against unchanged code.
+- **Phase modified existing files**: Run the full test suite. Existing tests serve as behavior-preservation checks — any failure indicates a potential regression.
+- **Phase touched configuration files** (build config, CI config, environment config, dependency manifests): Run the full pipeline (build + lint + type check + all tests). Configuration changes can have cascading effects across the entire project.
+- **Phase only produced documentation or analysis**: Skip validation (record as `skipped` with rationale).
+
+### Scope Detection
+Determine the change type automatically from the completing agent's Task Report:
+1. Parse Files Created and Files Modified lists
+2. Classify each file: source code, test code, configuration, documentation
+3. Apply the most comprehensive validation scope that matches any changed file type (e.g., if one config file and three source files changed, run the full pipeline because config was touched)
+
+## Validation Failure Diagnosis
+
+When validation fails, provide a structured diagnosis to help the orchestrator decide next steps.
+
+### Diagnosis Protocol
+1. **Categorize the failure**: type error, lint error, test failure, build error, runtime error
+2. **Identify involved files**: Which files from the current phase appear in the error output?
+3. **Determine causality**: Is the failure caused by the current phase's changes, or is it a pre-existing issue?
+   - Check: Does the failure reference files modified in this phase?
+   - Check: Run validation against a clean snapshot while always restoring local state:
+     - `git stash push --include-untracked -m "maestro-causality-check"`
+     - `[validation command]` (capture exit code as `validation_exit`)
+     - `git stash pop` (run regardless of `validation_exit`)
+   - If `validation_exit` is non-zero in the clean snapshot, classify the failure as pre-existing.
+   - If `git stash pop` fails, mark the diagnosis as inconclusive until restoration conflicts are resolved.
+4. **Classify resolution path**:
+   - **Fixable by same agent**: The error is in files the agent owns, the fix is straightforward (missing import, type mismatch, lint violation). Re-delegate to the same agent with the error context.
+   - **Requires different agent**: The error is caused by an interface mismatch between phases. Identify which phase introduced the incompatibility.
+   - **Requires human input**: The error reveals an ambiguity in the design or plan that cannot be resolved without user guidance. Escalate with full context.
+
+### Diagnosis Output Format
+```
+### Validation Diagnosis
+- **Failure Type**: [type error | lint error | test failure | build error]
+- **Failing Files**: [list of files from current phase involved in the failure]
+- **Root Cause**: [brief description of why validation failed]
+- **Pre-existing**: [yes | no — was this failure present before this phase's changes?]
+- **Resolution Path**: [re-delegate to same agent | escalate to user | requires cross-phase fix]
+- **Recommended Action**: [specific next step with context to include in re-delegation or escalation]
+```

package/src/state/session-state.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync } = require('../lib/io');
+
+const DEFAULT_STATE_DIR = 'docs/maestro';
+
+function validateRelativePath(filePath) {
+  if (path.isAbsolute(filePath)) {
+    throw new Error('Path must be relative');
+  }
+  const segments = filePath.split(/[/\\]/);
+  if (segments.includes('..')) {
+    throw new Error('Path traversal not allowed');
+  }
+}
+
+function validateContainment(absolutePath, rootDir) {
+  let resolved = path.resolve(absolutePath);
+  let resolvedRoot = path.resolve(rootDir);
+  try { resolved = fs.realpathSync(resolved); } catch {}
+  try { resolvedRoot = fs.realpathSync(resolvedRoot); } catch {}
+  const rootPrefix = resolvedRoot + path.sep;
+  if (!resolved.startsWith(rootPrefix) && resolved !== resolvedRoot) {
+    throw new Error('state_dir must be within the project root');
+  }
+  return resolved;
+}
+
+function resolveStateDirPath(cwd, stateDirOverride) {
+  const stateDir = stateDirOverride || process.env.MAESTRO_STATE_DIR || DEFAULT_STATE_DIR;
+  const base = cwd || process.cwd();
+
+  if (path.isAbsolute(stateDir)) {
+    return validateContainment(stateDir, base);
+  }
+
+  validateRelativePath(stateDir);
+  return path.join(base, stateDir);
+}
+
+function resolveActiveSessionPath(cwd) {
+  return path.join(resolveStateDirPath(cwd), 'state', 'active-session.md');
+}
+
+function hasActiveSession(cwd) {
+  try {
+    const sessionPath = resolveActiveSessionPath(cwd);
+    return fs.existsSync(sessionPath);
+  } catch {
+    return false;
+  }
+}
+
+function readState(relativePath, basePath) {
+  validateRelativePath(relativePath);
+  const fullPath = path.join(basePath, relativePath);
+  return fs.readFileSync(fullPath, 'utf8');
+}
+
+function writeState(relativePath, content, basePath) {
+  validateRelativePath(relativePath);
+  const fullPath = path.join(basePath, relativePath);
+  atomicWriteSync(fullPath, content);
+}
+
+function ensureWorkspace(stateDir, basePath) {
+  const fullBase = path.isAbsolute(stateDir)
+    ? validateContainment(stateDir, basePath)
+    : (() => {
+        validateRelativePath(stateDir);
+        return path.join(basePath, stateDir);
+      })();
+  fs.mkdirSync(fullBase, { recursive: true, mode: 0o700 });
+  const stats = fs.lstatSync(fullBase);
+  if (stats.isSymbolicLink()) {
+    throw new Error('STATE_DIR must not be a symlink');
+  }
+  const dirs = [
+    path.join(fullBase, 'state'),
+    path.join(fullBase, 'state', 'archive'),
+    path.join(fullBase, 'plans'),
+    path.join(fullBase, 'plans', 'archive'),
+  ];
+  for (const dir of dirs) {
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    } catch {
+      throw new Error('Failed to create workspace directory');
+    }
+    try {
+      fs.accessSync(dir, fs.constants.W_OK);
+    } catch {
+      throw new Error('Workspace directory not writable');
+    }
+  }
+  const stateGitignore = path.join(fullBase, 'state', '.gitignore');
+  try {
+    fs.writeFileSync(stateGitignore, 'active-session.md\narchive/\n', { mode: 0o600, flag: 'wx' });
+  } catch {}
+}
+
+module.exports = {
+  DEFAULT_STATE_DIR,
+  validateContainment,
+  resolveStateDirPath,
+  resolveActiveSessionPath,
+  hasActiveSession,
+  readState,
+  writeState,
+  ensureWorkspace,
+};