cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(spec): correct git worktree sandbox path format to use system temp directory #6378

Closed
HAL9000 wants to merge 1 commits from spec/arch-sandbox-path-correction-cycle9 into master
pull from: spec/arch-sandbox-path-correction-cycle9
merge into: cleveragents:master
Conversation 14 Commits 1 Files Changed 3
+45 -22
3 changed files with 45 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+3
View File
@@ -48,6 +48,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Changed
- **Specification** (#6343): Documented that git worktree sandboxes are created in
the system temporary directory (rendered as `<SYSTEM_TEMP_DIR>/ca-sandbox-<PLAN_ULID>-XXXXXX/`)
so example `plan execute` outputs stay platform-accurate instead of hard-coding `/tmp`.
- **Automation Tracking Format**: All automation tracking issues now use a standardized
header format with mandatory `Reporting Interval: <interval> (Next report expected: <ts>)`
declarations, enabling precise staleness detection.
docs/reference/cleanup.md
+3 -1
View File
@@ -129,9 +129,11 @@ Cleanup Scan Results (dry-run)
Backups scanned=5 to remove=2 skipped=0
Stale items found:
[sandbox] /tmp/ca-sandbox-plan123-abcd (3 days old)
[sandbox] <SYSTEM_TEMP_DIR>/ca-sandbox-plan123-abcd (3 days old)
[checkpoint] .cleveragents/checkpoints/plan456/checkpoint_003.json (excess)
...
> ℹ️ Replace `<SYSTEM_TEMP_DIR>` with the temp directory for your OS. On Linux this is typically `/tmp`, on macOS it is the value returned by `getconf DARWIN_USER_TEMP_DIR`, and on Windows it resolves to `%LOCALAPPDATA%\Temp`.
```
Purge only sandboxes and checkpoints (default):
docs/specification.md
+39 -21
View File
@@ -12947,12 +12947,12 @@ Start or resume execution for a plan.
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰──────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> /repos/api/.worktrees/plan-01HXM8 │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXM8C2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> &lt;SYSTEM_TEMP_DIR&gt;/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXM8C2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────────────────────────────╯
╭─ Strategy Summary ─────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Decisions:</span> 8 │
@@ -12987,7 +12987,7 @@ Start or resume execution for a plan.
Sandbox
Strategy: git_worktree
Path: /repos/api/.worktrees/plan-01HXM8
Path: <SYSTEM_TEMP_DIR>/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX
Branch: cleveragents/plan-01HXM8C2
Status: active
@@ -13019,7 +13019,7 @@ Start or resume execution for a plan.
"phase": "execute",
"sandbox": {
"strategy": "git_worktree",
"path": "/repos/api/.worktrees/plan-01HXM8",
"path": "<SYSTEM_TEMP_DIR>/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX",
"branch": "cleveragents/plan-01HXM8C2",
"status": "active"
},
@@ -13056,7 +13056,7 @@ Start or resume execution for a plan.
phase: execute
sandbox:
strategy: git_worktree
path: "/repos/api/.worktrees/plan-01HXM8"
path: "<SYSTEM_TEMP_DIR>/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX"
branch: "cleveragents/plan-01HXM8C2"
status: active
worker: "local/executor"
@@ -19272,6 +19272,24 @@ Different resource types require different sandbox strategies:
Pros: natural rollback, diff support, efficient
Cons: requires git
**Git worktree path format**: The worktree is created in the **system temp directory** (whatever `tempfile.gettempdir()` returns on the host OS) using `tempfile.mkdtemp()` with the prefix `ca-sandbox-<plan_id>-`. This produces paths of the form `<SYSTEM_TEMP_DIR>/ca-sandbox-<PLAN_ULID>-<RANDOM>/`. The worktree is **not** created inside the repository directory (e.g., not in `.worktrees/`). This avoids polluting the repository, leverages OS-managed cleanup on reboot, and guarantees path uniqueness. The branch name follows the pattern `cleveragents/plan-<PLAN_ULID_PREFIX>`.
Example paths:
- Linux: `/tmp/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-a3f7b2/`
- macOS: `/var/folders/<hash>/T/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-a3f7b2/`
- Windows: `%TEMP%\\ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-a3f7b2`
!!! tip "Finding `<SYSTEM_TEMP_DIR>`"
The value depends on the host operating system:
- **Linux**: `echo "$TMPDIR"` if set, otherwise `/tmp`
- **macOS**: `getconf DARWIN_USER_TEMP_DIR` resolves to `/var/folders/<hash>/T/`
- **Windows**: `%LOCALAPPDATA%\\Temp` (also accessible via `echo %TEMP%`)
CleverAgents reads whatever `tempfile.gettempdir()` returns, so custom
deployments that override the process temp directory will automatically
inherit that location.
**2. Filesystem copy sandbox**
* Copy project directory to a sandbox directory
@@ -36645,12 +36663,12 @@ Because the automation profile is `manual`, the plan stops and waits after creat
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰─────────────────────────────────────────╯
╭─ Sandbox ───────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> /home/dev/projects/api-service/.worktrees/plan-01HXR1C1 │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXR1C1D2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰─────────────────────────────────────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> &lt;SYSTEM_TEMP_DIR&gt;/ca-sandbox-01HXR1C1D2E3F4G5H6I7J8K9L0-XXXXXX │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXR1C1D2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Strategy Summary ────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Decisions:</span> 4 │
@@ -36758,12 +36776,12 @@ The strategy actor has read the codebase, identified the relevant files, and pro
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰─────────────────────────────────────────╯
╭─ Sandbox ───────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> /home/dev/projects/api-service/.worktrees/plan-01HXR1C1 │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXR1C1D2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰─────────────────────────────────────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> &lt;SYSTEM_TEMP_DIR&gt;/ca-sandbox-01HXR1C1D2E3F4G5H6I7J8K9L0-XXXXXX │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXR1C1D2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Progress ────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Collect context (0.4s) │