From 6ed364ffe281d926b7a794f2f5bcde6cab411acd Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 12 Aug 2026 12:20:08 +0200
Subject: [PATCH] Document per-execution Hub worktree branch names (#3267)

* docs(hub): document per-execution worktree branch names

Hub now materializes `${{ paseo.execution.id }}` inside a daemon
environment's `worktree.newBranch` before it persists or dispatches the
launch, so a reusable branch-off environment can get a stable branch per
execution instead of every trigger contending for one literal name.

The reference states the constraint precisely because it is the part the
YAML cannot show: `newBranch` accepts that one execution-scoped path and
nothing else, and any other expression fails bundle activation with the
authored file and field in the error. Literal branch names stay valid.

* docs(hub): reshape the per-execution worktree branch docs

Split the two pages by the job each reader is doing. The daemon page is a
task guide, so it now carries the worktree YAML and only the two facts
that reader needs to choose a branch name, then links out. The reference
owns the exhaustive contract at the `newBranch` field: a table contrasting
a literal with the template, then the accepted expression scope and what
activation rejects.

Dropped the render-before-dispatch ordering. Readers cannot act on where
Hub materializes the value; the reachable behavior is that a retried or
recovered execution keeps its branch, which is what the table says.

* docs(hub): make the per-execution worktree branch the only guidance

A branch-off Hub environment that aims every execution at one branch name
is not a configuration worth teaching, so the docs no longer present it as
an alternative. Both pages now show `newBranch: trigger-${{ paseo.execution.id }}`
and say what it does, with no literal-branch example and no comparison.

The reference keeps the field's type as a bare syntax fact, along with the
accepted expression, what activation rejects, and the authored field the
failure names.
---
 public-docs/hub/configuration/hub-yml.md | 10 +++++++++-
 public-docs/hub/daemons.md               |  6 ++++--
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/public-docs/hub/configuration/hub-yml.md b/public-docs/hub/configuration/hub-yml.md
index 9d8a44247..a478dcf1e 100644
--- a/public-docs/hub/configuration/hub-yml.md
+++ b/public-docs/hub/configuration/hub-yml.md
@@ -72,10 +72,18 @@ environments:
     cwd: /workspace/project
     worktree:
       mode: branch-off
-      newBranch: paseo/review
+      newBranch: trigger-${{ paseo.execution.id }}
       base: origin/main
 ```
 
+`newBranch` is a branch-name string. Embed `${{ paseo.execution.id }}`, which renders the execution's UUID, so every execution branches off `base` on its own branch and keeps it when Hub retries or recovers that execution.
+
+One execution is one step run, so two steps selecting the same environment get separate branches.
+
+`${{ paseo.execution.id }}` is the only expression `newBranch` accepts. `paseo.prompt`, `paseo.context`, `paseo.inputs.*`, `values.*`, `steps.<id>.outputs.*`, and provider event fields are unavailable here, and each one fails bundle activation at the authored field, such as `.paseo/hub.yml.environments.review.worktree.newBranch`.
+
+`${{ paseo.execution.id }}` fails activation the same way anywhere else in a bundle. `branch` and `prNumber` take literal values.
+
 An environment is a complete named object. A step selects its name; objects are not inherited, merged, or partially overridden.
 
 ### Named agents
diff --git a/public-docs/hub/daemons.md b/public-docs/hub/daemons.md
index 2e0dce859..24ba7b5c6 100644
--- a/public-docs/hub/daemons.md
+++ b/public-docs/hub/daemons.md
@@ -80,11 +80,13 @@ To keep executions off your working tree, add a worktree:
 ```yaml
 worktree:
   mode: branch-off
-  newBranch: hub/investigation
+  newBranch: trigger-${{ paseo.execution.id }}
   base: origin/main
 ```
 
-See [Git worktrees](/docs/worktrees) for setup hooks and scripts.
+`${{ paseo.execution.id }}` renders the execution's UUID, so every execution gets its own branch off `origin/main`.
+
+[Environment fields](/docs/hub/configuration/hub-yml#environments) lists what `newBranch` accepts. See [Git worktrees](/docs/worktrees) for setup hooks and scripts.
 
 ## What Hub owns