Compare commits

...

1 Commits

Author SHA1 Message Date
HAL9000 792d78d6ed docs(spec): describe git worktree sandbox path via temp dir placeholder
CI / push-validation (pull_request) Successful in 17s
CI / helm (pull_request) Successful in 23s
CI / lint (pull_request) Successful in 26s
CI / build (pull_request) Successful in 36s
CI / security (pull_request) Successful in 52s
CI / quality (pull_request) Successful in 3m41s
CI / typecheck (pull_request) Successful in 3m59s
CI / e2e_tests (pull_request) Successful in 4m18s
CI / integration_tests (pull_request) Successful in 4m23s
CI / unit_tests (pull_request) Successful in 6m29s
CI / docker (pull_request) Successful in 1m59s
CI / coverage (pull_request) Successful in 11m8s
CI / status-check (pull_request) Successful in 1s
CI / benchmark-publish (pull_request) Has been skipped
CI / benchmark-regression (pull_request) Successful in 57m7s
The GitWorktreeSandbox implementation (PR #5998) creates worktrees in the
system temp directory using tempfile.mkdtemp() with the prefix
ca-sandbox-<plan_id>-, producing OS-specific paths (e.g.,
&lt;SYSTEM_TEMP_DIR&gt;/ca-sandbox-<PLAN_ULID>-XXXXXX/).

The spec previously showed the worktree path as a .worktrees/ subdirectory
inside the repository (e.g., /repos/api/.worktrees/plan-01HXM8). This was
incorrect and inconsistent with the implementation.

Changes:
- Update all plan execute output examples (Rich/Plain/JSON/YAML) to use the
  <SYSTEM_TEMP_DIR> prefix placeholder instead of hard-coding /tmp
- Update the end-to-end workflow examples (strategize + execute panels)
- Add explicit documentation of the git worktree path format in the
  Sandbox Implementation Strategies section, including rationale
- Update the changelog to reference the cross-platform placeholder

Triggered by: merged PR #5998 (GitWorktreeSandbox implementation)
ISSUES CLOSED: #6343
2026-04-12 19:36:49 +00:00
3 changed files with 45 additions and 22 deletions
+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.
+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):
+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) │