feat: add project-scoped feature state stores

Author: xai

Dockerfile

@@ -335,7 +335,8 @@ COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 RUN chmod a+rx /usr/local/bin/entrypoint.sh \
         /usr/local/share/enclave/auth-reconcile.sh \
         /usr/local/share/enclave/net.sh && \
-    chmod a+r /usr/local/share/enclave/tmux-session.conf
+    chmod a+r /usr/local/share/enclave/tmux-session.conf \
+        /usr/local/share/enclave/kit-init.sh
 USER ${USERNAME}
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
 CMD ["/bin/bash"]

docs/ARCHITECTURE.md

@@ -38,6 +38,7 @@ flowchart LR
         EnvStore["projects/&lt;hash&gt;/&lt;tool&gt;/env<br/>persisted env secrets, not mounted into the tool container"]
         SharedAuthStore["tools/&lt;tool&gt;/auth<br/>shared tool auth store, only with --auth-scope=shared"]
         FeatureAuthStore["features/&lt;feature&gt;/auth<br/>shared feature auth store, only with --auth-scope=shared"]
+        FeatureStateStore["projects/&lt;hash&gt;/features/&lt;feature&gt;/state<br/>project-scoped state shared across tools"]
     end
 
     subgraph Docker
@@ -54,6 +55,7 @@ flowchart LR
     EnvStore -.->|"host-side read/write env file"| Tool
     SharedAuthStore -->|"bind mount (~/.enclave-auth)"| Tool
     FeatureAuthStore -->|"bind mount (~/.enclave-feature-auth/&lt;feature&gt;)"| Tool
+    FeatureStateStore -->|"bind mount (~/.enclave-feature-state/&lt;feature&gt;)"| Tool
     Gateway --> DnsNet
     Tool --> DnsNet
     Tool -.->|"resolver/proxy"| Gateway
@@ -166,7 +168,7 @@ The restricted network request flow has a separate
 - **User-defined subcommands**: executables under `~/.config/enclave/commands/{host,session}/` become `enclave <name>` verbs. `cli.Parse` discovers them, registers name-only stub commands (Cobra group "User Commands") so they list in `--help` and shell completion, and intercepts a matching first positional *before* `normalizeArgs`/Cobra so the trailing line reaches the script verbatim (preserving the unknown-command rejection for everything else). enclave flags must precede the name: host commands accept only the global group, session commands accept the full session flag set. `host/` commands exec directly on the host (`os/exec`, exit code/stdin/stdout passthrough, `ENCLAVE_BIN`/`ENCLAVE_PROJECT_ROOT`/`ENCLAVE_CONFIG_DIR` injected). `session/` commands run through the normal run pipeline as a shell-style execution (`opts.Shell=true`, argv `bash -c 'exec "$@"' <name> <container-path> <args>` so the script's shebang is honored via execve).
 - **Session command isolation boundary**: session commands mount only the `session/` tree, read-only, at the fixed neutral container path `/opt/enclave/commands` (`model.UserCommandsContainerDir`) via a dedicated `model.UserCommandMount` — never through `mounts.AddAdditional` (which mirrors host paths and would leak the home layout). No mount/backend code path ever references the `host/` tree, and no enclave host-data directory is otherwise mounted, so host commands stay invisible in-container by construction. Session commands receive no `ENCLAVE_*` env injection.
 - **Detached sessions**: `--background` runs detached tool containers that can be reattached. There is no separate daemon run mode.
-- **Persistent stores**: per-tool/project stores hold tool configs; an optional env store persists env auth and `--pass-env` values when persistence is enabled (default unless `--ephemeral`). Stores are host directories under `~/.local/state/enclave/` bind-mounted into the container (no Docker volumes). See [`docs/runtime/stores.md`](runtime/stores.md) for detailed store lifecycle, auth symlinks, and scoping documentation.
+- **Persistent stores**: per-tool/project stores hold tool configs; an optional env store persists env auth and `--pass-env` values; opted-in mixins receive per-feature/project state shared across tools. Persistence is enabled by default unless `--ephemeral`. Stores are host directories under `~/.local/state/enclave/` bind-mounted into the container (no Docker volumes). See [`docs/runtime/stores.md`](runtime/stores.md) for detailed store lifecycle, auth symlinks, and scoping documentation.
 - **Caches/history**: host-side caches are stored under `~/.cache/enclave/` and shell history under `~/.local/state/enclave/projects/`.
 - **Network isolation**: by default, a gateway sidecar (dnsmasq + transparent proxy) restricts outbound domains. DNS blocks unknown domains, and the proxy is passthrough-by-default with MITM only for hosts that need secret release rewriting unless `network_log=requests` forces MITM for all allowlisted HTTPS.
 - **Declared secrets and HTTP release**: tool profiles and enabled feature manifests can declare `secrets`. Each secret lists env-var aliases and can optionally define `release.http` target hosts/header formatting. Declared secrets are resolved from host env, layered secrets files, or persisted env; when gateway release is enabled, matching secrets are replaced with `ENCLAVE_SECRET_*` placeholders inside the container. The flow is: extension `secrets` config → `PlaceholderResolver` generates placeholders → `SecretMapping` entries written to a JSON file → gateway proxy loads secret release rules and performs header rewriting on HTTPS requests. Plaintext HTTP requests carrying placeholders are denied. This protection is limited to env-var injection: credential files written by auth hooks can still contain the real secret in the config/auth store.
@@ -189,11 +191,12 @@ Persistent stores are host directories under `~/.local/state/enclave/` (honoring
 - **Env store**: `~/.local/state/enclave/projects/<hash>/<tool>/env/` stores persisted env auth data and additional `--pass-env` values when persistence is enabled (default unless `--ephemeral`).
 - **Shared auth store** (when `--auth-scope=shared`): `~/.local/state/enclave/tools/<tool>/auth/<identity>/` stores OAuth files shared across projects for the tool; `<identity>` is `default` or the `--auth-name` slug.
 - **Feature auth store** (when `--auth-scope=shared` and feature defines `authFiles`): `~/.local/state/enclave/features/<feature>/auth/` stores feature auth files shared across tools/projects (for example `github-cli`).
+- **Feature state store** (when an enabled mixin declares `state: true`): `~/.local/state/enclave/projects/<hash>/features/<feature>/state/` stores feature-owned project data shared across tools. It is not created for ephemeral sessions and is independent of auth scope.
 
 Other host-side data:
 
 - **Embedded asset cache**: standalone binaries extract into `${XDG_CACHE_HOME:-~/.cache}/enclave/assets/<hash>/` on Linux or `~/Library/Caches/org.eclipse.enclave/assets/<hash>/` on macOS. Extraction uses a per-content lock, temporary sibling directory, and atomic rename so concurrent first runs share one complete entry. Missing or invalid entries are recreated from the binary.
-- **QEMU stores**: the experimental QEMU backend mounts the same host-directory stores as the Docker backend (resolved via `internal/backend/hoststore`) into the guest over 9p, so auth, config, and env state are shared across backends.
+- **QEMU stores**: the experimental QEMU backend mounts the same host-directory stores as the Docker backend (resolved via `internal/backend/hoststore`) into the guest over 9p. The store layer supports feature state, but current QEMU bundles disable all mixins, so normal QEMU runs do not request it.
 - **QEMU bundles**: generated microVM bundles live under `${XDG_CACHE_HOME:-~/.cache}/enclave/microvm/<tool>/<hash>/` unless `--image-name` points at an explicit bundle directory.
 - **Caches**: `~/.cache/enclave/<tool>/<hash>/` for package managers and build tools:
   - `npm/` - npm package cache

docs/cli-reference.md

@@ -115,7 +115,7 @@ Mutation commands (`add-domain`, `remove-domain`, `set-mode`) apply the new poli
 | `enclave cleanup --all` | All projects and tools |
 | `enclave cleanup --ephemeral` | Remove stopped containers and ephemeral session stores |
 | `enclave cleanup --dry-run` | Preview what would be removed |
-| `enclave cleanup --keep cache,history,auth,memory` | Preserve the listed stores (comma-separated or repeated `--keep`): `cache` (package caches), `history` (shell history), `auth` (auth stores, with `--all`), `memory` (per-project agent memory, no selective effect with `--all`) |
+| `enclave cleanup --keep cache,history,auth,memory,feature-state` | Preserve the listed stores (comma-separated or repeated `--keep`): `cache` (package caches), `history` (shell history), `auth` (auth stores, with `--all`), `memory` (per-project agent memory, no selective effect with `--all`), `feature-state` (project-scoped feature state) |
 | `enclave cleanup --build-cache` | Prune Docker build cache (requires confirmation) |
 
 ---

docs/extensions/README.md

@@ -112,13 +112,15 @@ aptPackages: [<packages>]
 needsRoot: <bool>
 failOnInstallError: <bool>
 defaultEnabled: <bool>
+state: <bool, default false> # project-scoped persistent state shared across tools
 
 # tool-only field (kind: sandbox)
 defaultIncluded: <bool>
 ```
 
 `name` and `kind` are validated against the file's location and directory
-name at load time.
+name at load time. The sandbox name `features` is reserved for the
+project-scoped feature-state namespace.
 
 ### Reserved and deferred fields
 
@@ -524,6 +526,31 @@ every host the proxy injects credentials for is unioned into the session
 allow set so it resolves. A service mixin thus declares its own reachability
 without help from the tool spec.
 
+Set `state: true` only when a feature owns persistent project data that must be
+shared across tools. Enclave mounts the store at
+`~/.enclave-feature-state/<feature>/` and exports
+`ENCLAVE_FEATURE_STATE_DIR` while sourcing that feature's
+`feature-entrypoint.d/*.sh`. The variable is unset afterward. State is not
+created under `--ephemeral` and is independent of `--auth-scope`.
+
+```yaml
+schemaVersion: "1"
+kind: mixin
+name: state-probe
+state: true
+```
+
+A setup script can link the feature's native path to the neutral store:
+
+```sh
+if [ -n "${ENCLAVE_FEATURE_STATE_DIR:-}" ] && [ ! -e "$HOME/.state-probe" ] && [ ! -L "$HOME/.state-probe" ]; then
+    ln -s "$ENCLAVE_FEATURE_STATE_DIR" "$HOME/.state-probe"
+fi
+```
+
+The store may be mounted into multiple sessions concurrently. Stateful
+features must provide their own process-safe locking or database concurrency.
+
 ### Optional Files
 
 | File | Purpose |
@@ -618,6 +645,7 @@ resolved port appears in the printed `openUrl` and in `enclave ps`.
 | `needsRoot` | N/A | Controls install user |
 | `aptPackages` | N/A | Auto-installed apt packages |
 | Declared `ports` | Published for every session of the tool | Published when the feature is enabled |
+| `state: true` | Invalid | Opts into project-scoped state shared across tools |
 
 ## How It Works
 
@@ -665,7 +693,7 @@ CLI sets it to the single selected tool):
 
 1. Determines current tool from `$TOOL` env var
 2. Sources scripts from `extensions/tools/{tool}/entrypoint.d/*.sh` (tool-specific)
-3. Sources scripts from `extensions/*/feature-entrypoint.d/*.sh` (all features)
+3. Sources scripts from `extensions/*/feature-entrypoint.d/*.sh` (all enabled features), setting `ENCLAVE_FEATURE_STATE_DIR` only for a feature that declares `state: true`
 
 ### Go Registration (Tools Only)
 
@@ -725,6 +753,7 @@ Hooks run in a fixed order during runtime auth preparation:
 3. Optionally add:
    - `install.sh` for custom installation (set `needsRoot: true` if it needs root)
    - `feature-entrypoint.d/setup.sh` for runtime initialization
+   - `state: true` when the feature needs persistent project data shared across tools
 
 ### Feature Guidelines
 

docs/persistence.md

@@ -44,6 +44,7 @@ Per-project data is stored on the host and reused across sessions:
 | Shell history | `~/.local/state/enclave/projects/<project-hash>/<tool>/history/` |
 | Agent memory | `~/.local/state/enclave/projects/<project-hash>/<tool>/memory/` (Claude) |
 | Config/env/auth stores | Host directories under `~/.local/state/enclave/` (bind-mounted; no Docker volumes) |
+| Feature state | `~/.local/state/enclave/projects/<project-hash>/features/<feature>/state/` for enabled mixins that opt in with `state: true`; shared across tools |
 | Embedded runtime assets | `~/.cache/enclave/assets/<content-hash>/` |
 
 Extracted runtime asset entries are reproducible cache data. Deleting them is
@@ -55,8 +56,9 @@ the standard Apple locations, in a reverse-DNS application directory: config
 and state under `~/Library/Application Support/org.eclipse.enclave/`
 (`config/`, `state/`) and caches under `~/Library/Caches/org.eclipse.enclave/`.
 
-Agent memory is skipped for `--ephemeral` sessions: memory written during them
-is discarded with the session's config store.
+Agent memory and feature state are skipped for `--ephemeral` sessions. Feature
+state is independent of auth scope and is shared by all tools running the same
+enabled feature in a project.
 
 Disable specific persistence:
 
@@ -81,7 +83,7 @@ Options:
 |------|--------|
 | `--all` | Remove stores and caches for all projects and tools |
 | `--ephemeral` | Remove stopped containers and ephemeral session stores |
-| `--keep <kinds>` | Preserve the listed stores (comma-separated or repeated): `cache` (package caches), `history` (shell history), `memory` (per-project agent memory, removed by default; no selective effect with `--all`), `auth` (auth stores, with `--all`) |
+| `--keep <kinds>` | Preserve the listed stores (comma-separated or repeated): `cache` (package caches), `history` (shell history), `memory` (per-project agent memory, removed by default; no selective effect with `--all`), `auth` (auth stores, with `--all`), `feature-state` (project-scoped feature state) |
 | `--build-cache` | Prune Docker build cache (requires confirmation) |
 | `--dry-run` | Preview what would be removed |
 
@@ -91,6 +93,7 @@ Examples:
 enclave cleanup --dry-run
 enclave cleanup --keep cache
 enclave cleanup --keep cache,history
+enclave cleanup --keep feature-state
 enclave cleanup --ephemeral
 enclave cleanup --all
 ```