From e4390181b7dd64318ef0c8a1e9e013bad252081d Mon Sep 17 00:00:00 2001
From: NagyVikt <nagy.viktordp@gmail.com>
Date: Sun, 12 Apr 2026 02:33:01 +0200
Subject: [PATCH] Keep agent branch names readable by dropping timestamp
 prefixes

User-facing branch names now use snapshot/task slugs instead of datetime prefixes. To preserve uniqueness when the same task runs again, branch creation now appends an incrementing numeric suffix only when needed. Updated setup template, tests, and README examples to match the new naming behavior.

Constraint: Branch names must stay deterministic and human-readable for VS Code/source-control workflows

Rejected: Keep timestamps and only hide them in docs | does not satisfy explicit remove-timestamp request

Confidence: high

Scope-risk: narrow

Reversibility: clean

Directive: Keep script and template branch-name logic in sync whenever branch naming changes

Tested: npm test; node --check bin/multiagent-safety.js; npm pack --dry-run
---
 README.md                               |  6 +++---
 scripts/agent-branch-start.sh           | 14 ++++++++------
 templates/scripts/agent-branch-start.sh | 14 ++++++++------
 test/install.test.js                    |  4 ++--
 4 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index f169fe0..d66e16e 100644
--- a/README.md
+++ b/README.md
@@ -121,9 +121,9 @@ and a few `agent-branch-start` runs:
 
 ```text
 GuardeX (your preferred local branch: main/dev)
-agent_codex_<timestamp>-<snapshot>-<task>
-agent_bot_<timestamp>-<snapshot>-<task>
-agent_bot_<timestamp>-<snapshot>-<task>
+agent_codex_<snapshot>-<task>
+agent_bot_<snapshot>-<task>
+agent_bot_<snapshot>-<task>-2
 ```
 
 That gives you one stable main repo view plus parallel agent worktrees in the
diff --git a/scripts/agent-branch-start.sh b/scripts/agent-branch-start.sh
index 6510157..56e80fd 100755
--- a/scripts/agent-branch-start.sh
+++ b/scripts/agent-branch-start.sh
@@ -195,15 +195,17 @@ snapshot_name="$(resolve_active_codex_snapshot_name)"
 snapshot_slug="$(sanitize_slug "$snapshot_name" "")"
 timestamp="$(date +%Y%m%d-%H%M%S)"
 if [[ -n "$snapshot_slug" ]]; then
-  branch_name="agent/${agent_slug}/${timestamp}-${snapshot_slug}-${task_slug}"
+  branch_name_base="agent/${agent_slug}/${snapshot_slug}-${task_slug}"
 else
-  branch_name="agent/${agent_slug}/${timestamp}-${task_slug}"
+  branch_name_base="agent/${agent_slug}/${task_slug}"
 fi
 
-if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
-  echo "[agent-branch-start] Branch already exists: ${branch_name}" >&2
-  exit 1
-fi
+branch_name="$branch_name_base"
+branch_suffix=2
+while git show-ref --verify --quiet "refs/heads/${branch_name}"; do
+  branch_name="${branch_name_base}-${branch_suffix}"
+  branch_suffix=$((branch_suffix + 1))
+done
 
 if [[ "$WORKTREE_MODE" -eq 0 ]]; then
   if [[ "$ALLOW_IN_PLACE" -ne 1 ]]; then
diff --git a/templates/scripts/agent-branch-start.sh b/templates/scripts/agent-branch-start.sh
index 6510157..56e80fd 100755
--- a/templates/scripts/agent-branch-start.sh
+++ b/templates/scripts/agent-branch-start.sh
@@ -195,15 +195,17 @@ snapshot_name="$(resolve_active_codex_snapshot_name)"
 snapshot_slug="$(sanitize_slug "$snapshot_name" "")"
 timestamp="$(date +%Y%m%d-%H%M%S)"
 if [[ -n "$snapshot_slug" ]]; then
-  branch_name="agent/${agent_slug}/${timestamp}-${snapshot_slug}-${task_slug}"
+  branch_name_base="agent/${agent_slug}/${snapshot_slug}-${task_slug}"
 else
-  branch_name="agent/${agent_slug}/${timestamp}-${task_slug}"
+  branch_name_base="agent/${agent_slug}/${task_slug}"
 fi
 
-if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
-  echo "[agent-branch-start] Branch already exists: ${branch_name}" >&2
-  exit 1
-fi
+branch_name="$branch_name_base"
+branch_suffix=2
+while git show-ref --verify --quiet "refs/heads/${branch_name}"; do
+  branch_name="${branch_name_base}-${branch_suffix}"
+  branch_suffix=$((branch_suffix + 1))
+done
 
 if [[ "$WORKTREE_MODE" -eq 0 ]]; then
   if [[ "$ALLOW_IN_PLACE" -ne 1 ]]; then
diff --git a/test/install.test.js b/test/install.test.js
index 759918d..7cfa94c 100644
--- a/test/install.test.js
+++ b/test/install.test.js
@@ -474,7 +474,7 @@ OUT
     { env: { PATH: `${fakeBin}:${process.env.PATH || ''}` } },
   );
   assert.equal(result.status, 0, result.stderr || result.stdout);
-  assert.match(result.stdout, /Created branch: agent\/planner\/\d{8}-\d{6}-zeus-edix-hu-restore-snapshot/);
+  assert.match(result.stdout, /Created branch: agent\/planner\/zeus-edix-hu-restore-snapshot(?:-\d+)?/);
 });
 
 test('setup agent-branch-start supports explicit snapshot override without codex-auth', () => {
@@ -491,7 +491,7 @@ test('setup agent-branch-start supports explicit snapshot override without codex
     { env: { MUSAFETY_CODEX_AUTH_SNAPSHOT: 'Prod Snapshot One' } },
   );
   assert.equal(result.status, 0, result.stderr || result.stdout);
-  assert.match(result.stdout, /Created branch: agent\/bot\/\d{8}-\d{6}-prod-snapshot-one-ship-fix/);
+  assert.match(result.stdout, /Created branch: agent\/bot\/prod-snapshot-one-ship-fix(?:-\d+)?/);
 });
 
 test('setup agent-branch-start defaults base to current branch and stores per-branch base metadata', () => {