Add project-scoped feature state stores by xai · Pull Request #37 · eclipse-enclave/enclave

xai · 2026-08-03T13:02:39Z

What it does

Adds an opt-in state store for features that need to keep project data across sessions and tools. A mixin can declare state: true; in persistent sessions Enclave creates ~/.local/state/enclave/projects/<hash>/features/<feature>/state/ and mounts it at ~/.enclave-feature-state/<feature>/.

While sourcing that feature's setup scripts, the entrypoint exposes the mount as ENCLAVE_FEATURE_STATE_DIR. It unsets the variable before sourcing the next feature and before starting the agent. Ephemeral sessions do not create or mount feature state.

Feature state is represented in both backend store layers, although current QEMU sessions disable mixins and do not mount it. It is independent of auth scope and remains separate from feature auth. enclave cleanup removes it with the rest of the project data unless --keep feature-state is set, including during cleanup --all.

Mixin validation rejects state on sandbox specs. The sandbox extension name features is now reserved because it would collide with the project feature-state namespace. The image build also makes kit-init.sh world-readable, so startup does not depend on the checkout's umask.

How to test

Current QEMU sessions disable mixins, so this manual test uses Docker. It creates a temporary state-probe extension that records which tools start with its state store mounted.

Run the setup commands from the repository root. enclave shell is interactive; run the checks below at the container prompt.

repo="$PWD"
make build
enclave_bin="$repo/bin/enclave"
test_root="$(mktemp -d)"
project_dir="$test_root/project"

export XDG_CONFIG_HOME="$test_root/config"
export XDG_STATE_HOME="$test_root/state"

probe_dir="$XDG_CONFIG_HOME/enclave/extensions/features/state-probe"
mkdir -p "$probe_dir/feature-entrypoint.d" "$project_dir"
cat >"$probe_dir/spec.yaml" <<'YAML'
schemaVersion: "1"
kind: mixin
name: state-probe
displayName: State Probe
description: Manual feature-state probe
defaultEnabled: false
state: true
YAML
cat >"$probe_dir/feature-entrypoint.d/setup.sh" <<'SH'
if [ -n "${ENCLAVE_FEATURE_STATE_DIR:-}" ]; then
    printf '%s\n' "${TOOL:-unknown}" >> "$ENCLAVE_FEATURE_STATE_DIR/runs"
fi
SH

cd "$project_dir"
"$enclave_bin" shell --tool claude --features state-probe --rebuild

Inside the Claude shell:

cat "$HOME/.enclave-feature-state/state-probe/runs"  # claude
printf '%s\n' "${ENCLAVE_FEATURE_STATE_DIR-unset}"   # unset
exit

Start the same extension with Codex:

"$enclave_bin" shell --tool codex --features state-probe --rebuild

Inside the Codex shell, the shared file should contain both tool names:

cat "$HOME/.enclave-feature-state/state-probe/runs"
# claude
# codex
exit

Back on the host, clean up and run the automated checks:

cd "$repo"
rm -rf "$test_root"
unset XDG_CONFIG_HOME XDG_STATE_HOME
make test
make lint

The unit tests cover stateless and ephemeral sessions, cleanup retention, and both backend store layers.

Follow-ups

None.

Breaking changes

The sandbox extension name features is now reserved.

This PR introduces breaking changes and has been coordinated with maintainers.

Review checklist

As an author, I have thoroughly tested my changes and carefully followed the contribution guidelines.

EclipseSourceAI

Note

Autonomous AI review.

This review was done by an AI agent and therefore may contain mistakes. Feel free to ignore any comment you disagree with. Noting why helps, since replies are read and taken into account in follow-up reviews.

Resolving all AI comments does not lead to an automatic approval. A maintainer still needs to review and sign off on the overall architecture and design.

To get an updated review after pushing changes, a maintainer may re-request a review from this account.

Running in Eclipse Enclave, submitted via review-guard-mcp

Adds an opt-in project-scoped state store for feature mixins (state: true), mounted at ~/.enclave-feature-state/<feature>/ and keyed by feature + project hash but not by tool, so tools in the same project share it.

The store integration is clean: a new StoreKind, one hoststore case, one path helper, and both backends pick it up through the generalized StorePrep.FeatureStores. Nice side effects are that hoststore.DirFor no longer silently falls through to the config layout for unknown kinds, and feature auth and feature state are no longer mutually exclusive. Owner and project hash both go through validateStoreSegment, and the docs (docs/runtime/stores.md) are accurate about the cross-tool trust channel and the --ephemeral / --auth-scope interactions.

Worth a human look at three spots: the kit-init.sh permission fix in the Dockerfile has no counterpart in runtime-assets/microvm/alpine/build-bundle.sh, where the same umask-dependent copy defeats the empty-manifest feature gate; entrypoint.sh unsets the state root before the initFiles/startup loops, so a stateful service mixin can't locate its store from a startup command; and the restructured --all path in internal/app/cleanup.go introduces a "project" cleanup kind that no --keep filter matches.

make build, make test, and make lint all pass.

EclipseSourceAI · 2026-08-03T17:29:11Z

        /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


The QEMU bundle needs the same fix. build-bundle.sh copies kit-init.sh with plain cp and its chmod line only covers entrypoint/auth-reconcile/net.sh (link), and the later chown -R agent doesn't touch /usr/local/share/enclave. Since the bundle bakes an empty .installed-features manifest specifically to gate mixins off and that gate lives in kit-init.sh, an unreadable copy fails open and runs every baked feature's hooks.

EclipseSourceAI · 2026-08-03T17:29:12Z

    fi
+    unset ENCLAVE_FEATURE_STATE_DIR
 done
+unset ENCLAVE_FEATURE_STATE_ROOT enclave_feature_state_root


Unsetting the root here means neither ENCLAVE_FEATURE_STATE_ROOT nor ENCLAVE_FEATURE_STATE_DIR is visible to the initFiles / workspace / startup loops that follow (link). A stateful service mixin declaring commands.startup can then only find its store if a feature-entrypoint.d script planted a symlink first, and initFiles can't reference it at all (envsubst whitelist is WORKDIR/HOME/USER). Either keep the root exported through those loops or say so in the extension docs.

EclipseSourceAI · 2026-08-03T17:29:12Z

+		logx.Infof("%s feature state mounted", util.TitleCase(feat.Name))
+	}
+	if mounted {
+		mounts.AddEnv(model.EnvFeatureStateRoot, mountRoot)


Exporting only the root and letting the entrypoint infer per-feature opt-in from [ -d "$root/$feature_name" ] diverges from how feature auth does it: that one ships a declared map, ENCLAVE_FEATURE_AUTH_MAP (link, consumed at entrypoint.sh#L170). With the directory probe a feature that declared state: true but whose mount got skipped looks identical to one that never opted in.

EclipseSourceAI · 2026-08-03T17:29:13Z

+			}
+		}
+		if !keepsChild {
+			dirs = append(dirs, cleanupDir{Kind: "project", Path: projectDir})


Kind: "project" matches none of the filters in cleanupDirsForRemoval, so this whole-project shortcut is unfilterable by any --keep. It happens to be safe because only history and feature-state gate the projects tree today, but it will silently ignore any future project-scoped keep kind. The keepsChild loop above also reduces to two checks: does the project have a features child, does it have any other child.

EclipseSourceAI · 2026-08-03T17:29:14Z

 )

+// FeatureStoreLabel returns the user-facing label for a feature-owned store.
+func (kind StoreKind) FeatureStoreLabel() string {


This is log-message formatting hanging off a shared domain type, and it returns "feature store" for config/auth/env, which aren't feature stores. It's only used by the two logx lines in the Docker and QEMU prepare paths; a local helper or a small map in each backend keeps the presentation string out of backend.

EclipseSourceAI · 2026-08-03T17:29:15Z

 	}
 }

+func TestResolveEphemeralStoreDirsSkipsFeatureStateNamespace(t *testing.T) {


This sets run.Tool = "features", which is the non---all branch, and a sandbox named features is now rejected at spec load so that can't happen in practice. The branch the guard actually protects is --all, where tools comes from listSubdirs(HostProjectDir(...)). Set CleanupAll: true and add a real tool dir alongside the feature-state tree.

EclipseSourceAI · 2026-08-03T17:29:16Z

 		features: []model.Extension{
-			{Name: "diffity", Ports: []model.PortConfig{
-				{Container: 5391, HostAllocation: model.HostAllocationAuto, Publish: true, Label: "Diffity"},
+			{Name: "preview", Ports: []model.PortConfig{


Renaming the diffity fixture to preview is unrelated to feature state. Separate commit.

i don't care, this will be done now :)

Signed-off-by: Olaf Lessenich <olessenich@eclipsesource.com>

EclipseSourceAI

Note

Autonomous AI review.

This review was done by an AI agent and therefore may contain mistakes. Feel free to ignore any comment you disagree with. Noting why helps, since replies are read and taken into account in follow-up reviews.

Resolving all AI comments does not lead to an automatic approval. A maintainer still needs to review and sign off on the overall architecture and design.

To get an updated review after pushing changes, a maintainer may re-request a review from this account.

Running in Eclipse Enclave, submitted via review-guard-mcp

Follow-up review of the project-scoped feature state store.

Two commits landed since the last pass: the QEMU bundle now chmods kit-init.sh readable, and the ephemeral-cleanup guard test was rewritten to actually hit the --all branch (it now trips on a feature named config-store, which is exactly the collision the guard exists for). Both look right.

The store integration itself stays small and well placed: one StoreKind, one hoststore case, two path helpers, and both backends pick it up via the generalized StorePrep.FeatureStores. Docs across stores.md, persistence.md, ARCHITECTURE.md, cli-reference.md and extensions/README.md match the code, including the concurrency and cross-tool caveats. make build, make test, make lint pass.

Where a maintainer should focus: the restructured --all path in internal/app/cleanup.go (the "project" kind is unfilterable by any --keep), the entrypoint env lifecycle around the initFiles/startup loops, and the blast radius of enclave cleanup --tool <x>, which now wipes the whole project's feature state including data other tools use. Also worth deciding whether the new cross-tool write channel deserves a mention in docs/security/ rather than only docs/runtime/stores.md. No shipped extension sets state: true yet, so the path is exercised only by tests.

Two new low-severity comments inline; the four earlier open threads still apply.

These previous comments can be resolved as they are now handled:

I can't resolve them myself as I would need write permission on this repository.

EclipseSourceAI · 2026-08-03T21:51:32Z

 	}
 	if prep.Auth != nil {
-		b.ensureStoreDir(backend.StoreKindAuth, prep.Auth.Key, util.TitleCase(prep.Auth.Key.Owner)+" shared auth store")
+		b.ensureStoreDir(prep.Auth.Kind, prep.Auth.Key, util.TitleCase(prep.Auth.Key.Owner)+" shared auth store")


Taking the kind from prep.Auth.Kind buys nothing here (prep.Auth is by definition the shared tool auth store) and adds a failure mode: with the new erroring default case in DirFor, a caller that forgets Kind now silently loses the shared auth store, since ensureStoreDir only logs the resolve failure at debug level (link). Same in qemu/prepare.go. Keeping backend.StoreKindAuth hardcoded for this one field would be safer.

EclipseSourceAI · 2026-08-03T21:51:33Z

 	if doc.Name != name {
 		return specDocument{}, fmt.Errorf("%s name must be %q", specPath, name)
 	}
+	if kind == KindSandbox && name == projectFeatureStateDirName {


The reservation only fires once the spec is actually loaded. ListTools just checks for a spec file (link), so a user tool dir named features still shows up in --help and completion and only errors when someone selects it. Filtering it there too would make the docs claim ("the sandbox name features is reserved") hold end to end.

xai added documentation Improvements or additions to documentation enhancement New feature or request labels Aug 3, 2026

xai force-pushed the feat/feature-state-store branch from 5c59385 to 1d2f384 Compare August 3, 2026 13:03

xai marked this pull request as ready for review August 3, 2026 17:21

EclipseSourceAI reviewed Aug 3, 2026

View reviewed changes

xai added 3 commits August 3, 2026 23:29

feat: add project-scoped feature state stores

8c22ece

Signed-off-by: Olaf Lessenich <olessenich@eclipsesource.com>

fix: make qemu kit init world-readable

dfa1df0

test: cover feature state in all-project cleanup

a22bc64

xai force-pushed the feat/feature-state-store branch from 1d2f384 to a22bc64 Compare August 3, 2026 21:30

xai requested a review from EclipseSourceAI August 3, 2026 21:43

EclipseSourceAI reviewed Aug 3, 2026

View reviewed changes

xai added 3 commits August 4, 2026 09:49

fix: pin shared auth store kind

20b47ea

fix: exclude reserved tool from discovery

20246ef

docs: document feature state trust boundary

111532b

Navigation Menu

Uh oh!

Add project-scoped feature state stores - #37

Add project-scoped feature state stores#37
xai wants to merge 6 commits into
mainfrom
feat/feature-state-store

xai commented Aug 3, 2026

Uh oh!

EclipseSourceAI left a comment

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

xai Aug 3, 2026

Uh oh!

EclipseSourceAI left a comment

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

EclipseSourceAI Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

xai commented Aug 3, 2026

What it does

How to test

Follow-ups

Breaking changes

Review checklist

Uh oh!

EclipseSourceAI left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EclipseSourceAI left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants