entropic::SandboxManager Class Reference

Create, finalize, and discard per-delegation filesystem sandboxes. More...

#include <entropic/core/sandbox.h>

Public Member Functions
	SandboxManager (const std::filesystem::path &project_dir)
	Construct with the user's project directory.
	~SandboxManager ()
	Remove this session's sandbox tree.
	SandboxManager (SandboxManager &&)=default
SandboxManager &	operator= (SandboxManager &&)=default
	SandboxManager (const SandboxManager &)=delete
SandboxManager &	operator= (const SandboxManager &)=delete
std::optional< SandboxInfo >	create_sandbox (const std::string &delegation_id, std::optional< SandboxInfo > chain_from=std::nullopt)
	Create a new delegation sandbox.
std::optional< SandboxResult >	finalize_sandbox (const SandboxInfo &info)
	Produce the final patch artifact for a sandbox.
void	discard_sandbox (const SandboxInfo &info)
	Remove a sandbox directory.
std::optional< std::filesystem::path >	write_pending_patch (const std::string &delegation_id, const std::string &patch)
	Write a patch to the session's pending/ directory.
const std::filesystem::path &	project_dir () const
	Get the project directory this manager snapshots from.
const std::filesystem::path &	session_base () const
	Get this session's sandbox base directory.

Detailed Description

Create, finalize, and discard per-delegation filesystem sandboxes.

One instance per engine session. Owns ~/.entropic/sandbox/<session-id>/ and removes it in the destructor. Creates an initial base/ snapshot of the project (filtered by .gitignore when the project is a git repo) on the first create_sandbox() call. Subsequent delegations either branch from base/ or chain from a prior delegation's output.

Threading

Not thread-safe. The caller (DelegationManager) serializes access.

Example

SandboxManager mgr(project_dir);
auto s1 = mgr.create_sandbox("d1", std::nullopt);
// ... agent edits files in s1->path ...
auto r1 = mgr.finalize_sandbox(*s1);  // emits patch, removes s1->path
 
auto s2 = mgr.create_sandbox("d2", s1);  // chains from d1 head
// ... agent edits in s2->path ...
auto r2 = mgr.finalize_sandbox(*s2);

Version

2.1.5

Definition at line 99 of file sandbox.h.

Constructor & Destructor Documentation

SandboxManager()

entropic::SandboxManager::SandboxManager ( const std::filesystem::path &  project_dir )

explicit

Construct with the user's project directory.

Generates <pid>-<hex8> session id and reserves ~/.entropic/sandbox/<session_id>/. The base snapshot is not created until the first create_sandbox() call — sessions that never delegate pay no snapshot cost.

Prunes at startup: session directories under ~/.entropic/sandbox/ whose owner pid is no longer alive.

Parameters

project_dir

Path to the user's project root (used as snapshot source; never written to by this class).

Version

2.1.5

Parameters

project_dir

Project root (read-only to this class).

Definition at line 170 of file sandbox.cpp.

~SandboxManager()

entropic::SandboxManager::~SandboxManager

(

)

Remove this session's sandbox tree.

Destructor — remove this session's sandbox tree.

Best-effort: errors are logged, not thrown. Path containment is enforced — refuses to remove anything outside session_base_.

Version

2.1.5

Definition at line 192 of file sandbox.cpp.

Member Function Documentation

create_sandbox()

std::optional< SandboxInfo > entropic::SandboxManager::create_sandbox	(	const std::string &	delegation_id,
		std::optional< SandboxInfo >	chain_from = std::nullopt
	)

Create a new delegation sandbox.

On the first call of a session, materializes the base/ snapshot from the project directory, honoring .gitignore (via git ls-files --cached --others --exclude-standard) when the project is a git repository. For non-git projects, the entire project tree is copied verbatim.

The new sandbox is a copy of either base/ (when chain_from is empty) or chain_from->path (for pipeline forward-carry).

Parameters

delegation_id	Short, filesystem-safe id (e.g. "d1", "d2", "pipeline"). Becomes the sandbox dir name.
chain_from	Optional prior sandbox to chain from. When set, the new sandbox starts from that sandbox's current state instead of base/.

Returns

SandboxInfo on success, std::nullopt if snapshot or copy failed (logged at ERROR).

Version

2.1.5

Parameters

delegation_id	Short id (becomes the sandbox dir name).
chain_from	Optional prior sandbox to chain from.

Returns

SandboxInfo on success.

Definition at line 390 of file sandbox.cpp.

discard_sandbox()

void entropic::SandboxManager::discard_sandbox

(

const SandboxInfo &

info

)

Remove a sandbox directory.

Path-containment guarded — refuses to remove anything outside session_base_. Safe to call multiple times.

Parameters

info	Sandbox to remove.

Version

2.1.5

Parameters

info	Sandbox to remove.

Definition at line 533 of file sandbox.cpp.

finalize_sandbox()

std::optional< SandboxResult > entropic::SandboxManager::finalize_sandbox

(

const SandboxInfo &

info

)

Produce the final patch artifact for a sandbox.

Runs git diff --no-index --binary <base_dir>/ <sandbox>/ to generate a portable unified diff, collects the list of changed files, and returns them in a SandboxResult. The sandbox directory is NOT removed by this call — the caller decides when to discard (see discard_sandbox()), allowing the patch consumer to inspect files before cleanup.

Parameters

info	Sandbox to finalize.

Returns

SandboxResult on success, std::nullopt on failure.

Version

2.1.5

Parameters

info	Sandbox to finalize.

Returns

SandboxResult on success.

Definition at line 506 of file sandbox.cpp.

project_dir()

const std::filesystem::path & entropic::SandboxManager::project_dir

(

)

const

Get the project directory this manager snapshots from.

Returns

Project root path.

Version

2.1.5

Returns

Project root path.

Definition at line 589 of file sandbox.cpp.

session_base()

const std::filesystem::path & entropic::SandboxManager::session_base

(

)

const

Get this session's sandbox base directory.

Returns

Path to ~/.entropic/sandbox/<session-id>/.

Version

2.1.5

Returns

Path to ~/.entropic/sandbox/<session-id>/.

Definition at line 599 of file sandbox.cpp.

write_pending_patch()

std::optional< std::filesystem::path > entropic::SandboxManager::write_pending_patch	(	const std::string &	delegation_id,
		const std::string &	patch
	)

Write a patch to the session's pending/ directory.

Persist a patch under the session's pending/ directory.

Default-deny fallback: invoked by DelegationManager when no complete callback is registered, or when the consumer's callback returned ENT_DECISION_REJECT. The pending dir is created on demand under session_base_/pending/. Path containment is enforced by path_in_session_base().

Parameters

delegation_id	Short id (becomes the basename).
patch	Unified-diff text to persist.

Returns

Path to the written file on success, std::nullopt on failure (logged at ERROR).

Version

2.1.5

Default-deny fallback path (gh#29, v2.1.5). Used when no delegation-complete callback is registered or the consumer returns REJECT. Refuses to write to anything outside session_base_.

Parameters

delegation_id	Short id (basename for the .patch file).
patch	Unified-diff text.

Returns

Path written, or std::nullopt on failure.

Definition at line 552 of file sandbox.cpp.

---

The documentation for this class was generated from the following files:

• entropic/core/sandbox.h
• core/sandbox.cpp