@imdeadpool/guardex 7.0.16 → 7.0.19

package/templates/scripts/codex-agent.sh

@@ -6,6 +6,8 @@ AGENT_NAME="${GUARDEX_AGENT_NAME:-agent}"
 BASE_BRANCH="${GUARDEX_BASE_BRANCH:-}"
 BASE_BRANCH_EXPLICIT=0
 CODEX_BIN="${GUARDEX_CODEX_BIN:-codex}"
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 AUTO_FINISH_RAW="${GUARDEX_CODEX_AUTO_FINISH:-true}"
 AUTO_REVIEW_ON_CONFLICT_RAW="${GUARDEX_CODEX_AUTO_REVIEW_ON_CONFLICT:-true}"
 AUTO_CLEANUP_RAW="${GUARDEX_CODEX_AUTO_CLEANUP:-true}"
@@ -16,6 +18,23 @@ OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
 OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 
+run_guardex_cli() {
+  if [[ -n "$CLI_ENTRY" ]]; then
+    "$NODE_BIN" "$CLI_ENTRY" "$@"
+    return $?
+  fi
+  if command -v gx >/dev/null 2>&1; then
+    gx "$@"
+    return $?
+  fi
+  if command -v gitguardex >/dev/null 2>&1; then
+    gitguardex "$@"
+    return $?
+  fi
+  echo "[codex-agent] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 normalize_bool() {
   local raw="${1:-}"
   local fallback="${2:-0}"
@@ -143,6 +162,7 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   exit 1
 fi
 repo_root="$(git rev-parse --show-toplevel)"
+active_session_state_script="${repo_root}/scripts/agent-session-state.js"
 
 guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
 if [[ -f "$guardex_env_helper" ]]; then
@@ -373,11 +393,6 @@ start_sandbox_fallback() {
   printf '[agent-branch-start] Worktree: %s\n' "$worktree_path"
 }
 
-if [[ ! -x "${repo_root}/scripts/agent-branch-start.sh" ]]; then
-  echo "[codex-agent] Missing scripts/agent-branch-start.sh. Run: gx setup" >&2
-  exit 1
-fi
-
 start_args=("$TASK_NAME" "$AGENT_NAME")
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
   start_args+=("$BASE_BRANCH")
@@ -390,7 +405,7 @@ set +e
 start_output="$(
   GUARDEX_OPENSPEC_AUTO_INIT="$OPENSPEC_AUTO_INIT" \
   GUARDEX_OPENSPEC_MASTERPLAN_LABEL="$OPENSPEC_MASTERPLAN_LABEL_RAW" \
-  bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1
+  run_guardex_cli branch start "${start_args[@]}" 2>&1
 )"
 start_status=$?
 set -e
@@ -446,6 +461,40 @@ has_origin_remote() {
   git -C "$repo_root" remote get-url origin >/dev/null 2>&1
 }
 
+run_active_session_state() {
+  local action="$1"
+  shift
+
+  if [[ ! -f "$active_session_state_script" ]]; then
+    return 0
+  fi
+  if ! command -v "$NODE_BIN" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  "$NODE_BIN" "$active_session_state_script" "$action" "$@" >/dev/null 2>&1 || true
+}
+
+record_active_session_state() {
+  local wt="$1"
+  local branch="$2"
+
+  run_active_session_state \
+    start \
+    --repo "$repo_root" \
+    --branch "$branch" \
+    --task "$TASK_NAME" \
+    --agent "$AGENT_NAME" \
+    --worktree "$wt" \
+    --pid "$$" \
+    --cli "$CODEX_BIN"
+}
+
+clear_active_session_state() {
+  local branch="$1"
+  run_active_session_state stop --repo "$repo_root" --branch "$branch"
+}
+
 origin_remote_supports_pr_finish() {
   local origin_url
   origin_url="$(git -C "$repo_root" remote get-url origin 2>/dev/null || true)"
@@ -474,6 +523,31 @@ resolve_worktree_base_branch() {
   printf 'dev'
 }
 
+print_takeover_prompt() {
+  local wt="$1"
+  local branch="$2"
+  local base_branch change_slug change_artifact finish_cmd
+
+  base_branch="$(resolve_worktree_base_branch "$wt")"
+  if [[ -z "$base_branch" ]]; then
+    base_branch="dev"
+  fi
+
+  change_slug="$(resolve_openspec_change_slug "$branch")"
+  change_artifact="openspec/changes/${change_slug}/tasks.md"
+  if [[ ! -f "${wt}/${change_artifact}" ]]; then
+    change_artifact="openspec/changes/${change_slug}/notes.md"
+  fi
+  if [[ ! -f "${wt}/${change_artifact}" ]]; then
+    change_artifact="openspec/changes/${change_slug}/"
+  fi
+
+  finish_cmd="gx branch finish --branch \"${branch}\" --base ${base_branch} --via-pr --wait-for-merge --cleanup"
+
+  echo "[codex-agent] Takeover sandbox: ${wt}"
+  echo "[codex-agent] Takeover prompt: Continue \`${change_slug}\` on branch \`${branch}\`. Work inside \`${wt}\`, review \`${change_artifact}\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`${finish_cmd}\`."
+}
+
 sync_worktree_with_base() {
   local wt="$1"
   if ! has_origin_remote; then
@@ -524,24 +598,12 @@ ensure_openspec_plan_workspace() {
     return 0
   fi
 
-  hydrate_local_helper_in_worktree "$wt" "scripts/openspec/init-plan-workspace.sh"
-
-  local openspec_script="${wt}/scripts/openspec/init-plan-workspace.sh"
-  if [[ ! -f "$openspec_script" ]]; then
-    echo "[codex-agent] Missing OpenSpec init script in sandbox: ${openspec_script}" >&2
-    echo "[codex-agent] Run 'gx setup --target ${repo_root}' and retry." >&2
-    return 1
-  fi
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
   local plan_slug
   plan_slug="$(resolve_openspec_plan_slug "$branch")"
   local init_output=""
   if ! init_output="$(
     cd "$wt"
-    bash "scripts/openspec/init-plan-workspace.sh" "$plan_slug" 2>&1
+    run_guardex_cli internal run-shell planInit "$plan_slug" 2>&1
   )"; then
     printf '%s\n' "$init_output" >&2
     echo "[codex-agent] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2
@@ -561,24 +623,12 @@ ensure_openspec_change_workspace() {
     return 0
   fi
 
-  hydrate_local_helper_in_worktree "$wt" "scripts/openspec/init-change-workspace.sh"
-
-  local openspec_script="${wt}/scripts/openspec/init-change-workspace.sh"
-  if [[ ! -f "$openspec_script" ]]; then
-    echo "[codex-agent] Missing OpenSpec change init script in sandbox: ${openspec_script}" >&2
-    echo "[codex-agent] Run 'gx setup --target ${repo_root}' and retry." >&2
-    return 1
-  fi
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
   local change_slug capability_slug init_output=""
   change_slug="$(resolve_openspec_change_slug "$branch")"
   capability_slug="$(resolve_openspec_capability_slug)"
   if ! init_output="$(
     cd "$wt"
-    bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1
+    run_guardex_cli internal run-shell changeInit "$change_slug" "$capability_slug" 2>&1
   )"; then
     printf '%s\n' "$init_output" >&2
     echo "[codex-agent] OpenSpec workspace initialization failed for change '${change_slug}'." >&2
@@ -607,11 +657,6 @@ worktree_has_changes() {
 claim_changed_files() {
   local wt="$1"
   local branch="$2"
-  local lock_script="${repo_root}/scripts/agent-file-locks.py"
-
-  if [[ ! -x "$lock_script" ]]; then
-    return 0
-  fi
 
   local changed_raw deleted_raw
   changed_raw="$({
@@ -622,7 +667,7 @@ claim_changed_files() {
 
   if [[ -n "$changed_raw" ]]; then
     mapfile -t changed_files < <(printf '%s\n' "$changed_raw")
-    python3 "$lock_script" claim --branch "$branch" "${changed_files[@]}" >/dev/null 2>&1 || true
+    run_guardex_cli locks claim --branch "$branch" "${changed_files[@]}" >/dev/null 2>&1 || true
   fi
 
   deleted_raw="$({
@@ -632,7 +677,7 @@ claim_changed_files() {
 
   if [[ -n "$deleted_raw" ]]; then
     mapfile -t deleted_files < <(printf '%s\n' "$deleted_raw")
-    python3 "$lock_script" allow-delete --branch "$branch" "${deleted_files[@]}" >/dev/null 2>&1 || true
+    run_guardex_cli locks allow-delete --branch "$branch" "${deleted_files[@]}" >/dev/null 2>&1 || true
   fi
 }
 
@@ -781,7 +826,7 @@ run_finish_flow() {
     return 2
   fi
 
-  if finish_output="$(bash "${repo_root}/scripts/agent-branch-finish.sh" "${finish_args[@]}" 2>&1)"; then
+  if finish_output="$(run_guardex_cli branch finish "${finish_args[@]}" 2>&1)"; then
     printf '%s\n' "$finish_output"
     return 0
   fi
@@ -804,7 +849,7 @@ run_finish_flow() {
       fi
     )
 
-    if finish_output="$(bash "${repo_root}/scripts/agent-branch-finish.sh" "${finish_args[@]}" 2>&1)"; then
+    if finish_output="$(run_guardex_cli branch finish "${finish_args[@]}" 2>&1)"; then
       printf '%s\n' "$finish_output"
       return 0
     fi
@@ -833,6 +878,19 @@ if ! ensure_openspec_plan_workspace "$worktree_path" "$worktree_branch"; then
   exit 1
 fi
 
+active_session_recorded=0
+cleanup_active_session_state_on_exit() {
+  set +e
+  if [[ "${active_session_recorded:-0}" -eq 1 && -n "${worktree_branch:-}" && "${worktree_branch:-}" != "HEAD" ]]; then
+    clear_active_session_state "$worktree_branch"
+    active_session_recorded=0
+  fi
+}
+
+record_active_session_state "$worktree_path" "$worktree_branch"
+active_session_recorded=1
+trap cleanup_active_session_state_on_exit EXIT INT TERM
+
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"
 cd "$worktree_path"
 set +e
@@ -841,6 +899,8 @@ codex_exit="$?"
 set -e
 
 cd "$repo_root"
+cleanup_active_session_state_on_exit
+trap - EXIT INT TERM
 final_exit="$codex_exit"
 auto_finish_completed=0
 
@@ -878,18 +938,16 @@ if [[ "$AUTO_FINISH" -eq 1 && -n "$worktree_branch" && "$worktree_branch" != "HE
   fi
 fi
 
-if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-  echo "[codex-agent] Session ended (exit=${codex_exit}). Running worktree cleanup..."
-  prune_args=()
-  if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
-    prune_args+=(--base "$BASE_BRANCH")
-  fi
-  if [[ "$AUTO_CLEANUP" -eq 1 && "$auto_finish_completed" -eq 1 ]]; then
-    prune_args+=(--only-dirty-worktrees --delete-branches --delete-remote-branches)
-  fi
-  if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" "${prune_args[@]}"; then
-    echo "[codex-agent] Warning: automatic worktree cleanup failed." >&2
-  fi
+echo "[codex-agent] Session ended (exit=${codex_exit}). Running worktree cleanup..."
+prune_args=()
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
+  prune_args+=(--base "$BASE_BRANCH")
+fi
+if [[ "$AUTO_CLEANUP" -eq 1 && "$auto_finish_completed" -eq 1 ]]; then
+  prune_args+=(--only-dirty-worktrees --delete-branches --delete-remote-branches)
+fi
+if ! run_guardex_cli worktree prune "${prune_args[@]}"; then
+  echo "[codex-agent] Warning: automatic worktree cleanup failed." >&2
 fi
 
 if [[ ! -d "$worktree_path" ]]; then
@@ -901,7 +959,8 @@ else
     if [[ "$auto_finish_completed" -eq 1 ]]; then
       echo "[codex-agent] Branch kept intentionally. Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     else
-      echo "[codex-agent] If finished, merge with: bash scripts/agent-branch-finish.sh --branch \"${worktree_branch}\" --base dev --via-pr --wait-for-merge"
+      print_takeover_prompt "$worktree_path" "$worktree_branch"
+      echo "[codex-agent] If finished, merge with: gx branch finish --branch \"${worktree_branch}\" --base dev --via-pr --wait-for-merge"
       echo "[codex-agent] Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     fi
   fi

package/templates/scripts/install-vscode-active-agents-extension.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function parseOptions(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${token}`);
+    }
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new Error(`Missing value for --${key}`);
+    }
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function resolveExtensionSource(repoRoot) {
+  const candidates = [
+    path.join(repoRoot, 'vscode', 'guardex-active-agents'),
+    path.join(repoRoot, 'templates', 'vscode', 'guardex-active-agents'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, 'package.json'))) {
+      return candidate;
+    }
+  }
+
+  throw new Error('Could not find the Guardex VS Code companion sources.');
+}
+
+function removeIfExists(targetPath) {
+  if (fs.existsSync(targetPath)) {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  }
+}
+
+function main() {
+  const repoRoot = path.resolve(__dirname, '..');
+  const options = parseOptions(process.argv.slice(2));
+  const sourceDir = resolveExtensionSource(repoRoot);
+  const manifest = JSON.parse(fs.readFileSync(path.join(sourceDir, 'package.json'), 'utf8'));
+  const extensionId = `${manifest.publisher}.${manifest.name}`;
+  const extensionsDir = path.resolve(
+    options['extensions-dir'] ||
+      process.env.GUARDEX_VSCODE_EXTENSIONS_DIR ||
+      process.env.VSCODE_EXTENSIONS_DIR ||
+      path.join(os.homedir(), '.vscode', 'extensions'),
+  );
+
+  fs.mkdirSync(extensionsDir, { recursive: true });
+  const targetDir = path.join(extensionsDir, `${extensionId}-${manifest.version}`);
+
+  for (const entry of fs.readdirSync(extensionsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    if (entry.name === path.basename(targetDir)) {
+      continue;
+    }
+    if (entry.name.startsWith(`${extensionId}-`)) {
+      removeIfExists(path.join(extensionsDir, entry.name));
+    }
+  }
+
+  removeIfExists(targetDir);
+  fs.cpSync(sourceDir, targetDir, {
+    recursive: true,
+    force: true,
+    preserveTimestamps: true,
+  });
+
+  process.stdout.write(
+    `[guardex-active-agents] Installed ${extensionId}@${manifest.version} to ${targetDir}\n` +
+      '[guardex-active-agents] Reload the VS Code window to activate the Source Control companion.\n',
+  );
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`[guardex-active-agents] ${error.message}\n`);
+  process.exitCode = 1;
+}

package/templates/scripts/openspec/init-change-workspace.sh

@@ -1,14 +1,15 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-if [[ $# -lt 1 || $# -gt 2 ]]; then
-  echo "Usage: $0 <change-slug> [capability-slug]"
-  echo "Example: $0 add-dashboard-live-usage runtime-migration"
+if [[ $# -lt 1 || $# -gt 3 ]]; then
+  echo "Usage: $0 <change-slug> [capability-slug] [agent-branch]"
+  echo "Example: $0 add-dashboard-live-usage runtime-migration agent/claude-odin/add-dashboard-live-usage-123456"
   exit 1
 fi
 
 CHANGE_SLUG="$1"
 CAPABILITY_SLUG="${2:-$CHANGE_SLUG}"
+AGENT_BRANCH="${3:-agent/<your-name>/<branch-slug>}"
 
 if [[ "$CHANGE_SLUG" =~ [^a-z0-9-] ]]; then
   echo "Error: change slug must be kebab-case (lowercase letters, numbers, hyphens)."
@@ -20,11 +21,39 @@ if [[ "$CAPABILITY_SLUG" =~ [^a-z0-9-] ]]; then
   exit 1
 fi
 
+resolve_base_branch() {
+  local branch="$1"
+  local base_branch=""
+
+  if [[ -n "$branch" ]] && [[ "$branch" != "agent/<your-name>/<branch-slug>" ]]; then
+    base_branch="$(git config --get "branch.${branch}.guardexBase" || true)"
+  fi
+  if [[ -z "$base_branch" ]]; then
+    base_branch="$(git config --get multiagent.baseBranch || true)"
+  fi
+  if [[ -z "$base_branch" ]]; then
+    base_branch="dev"
+  fi
+
+  printf '%s' "$base_branch"
+}
+
 CHANGE_DIR="openspec/changes/${CHANGE_SLUG}"
 SPEC_DIR="${CHANGE_DIR}/specs/${CAPABILITY_SLUG}"
 TODAY="$(date -u +%Y-%m-%d)"
-
-mkdir -p "$SPEC_DIR"
+BASE_BRANCH="$(resolve_base_branch "$AGENT_BRANCH")"
+
+MINIMAL_RAW="${GUARDEX_OPENSPEC_MINIMAL:-0}"
+case "$(printf '%s' "$MINIMAL_RAW" | tr '[:upper:]' '[:lower:]')" in
+  1|true|yes|on) MINIMAL=1 ;;
+  *) MINIMAL=0 ;;
+esac
+
+if [[ "$MINIMAL" -eq 1 ]]; then
+  mkdir -p "$CHANGE_DIR"
+else
+  mkdir -p "$SPEC_DIR"
+fi
 
 if [[ ! -f "${CHANGE_DIR}/.openspec.yaml" ]]; then
   cat > "${CHANGE_DIR}/.openspec.yaml" <<YAMLEOF
@@ -33,6 +62,32 @@ created: ${TODAY}
 YAMLEOF
 fi
 
+if [[ "$MINIMAL" -eq 1 ]]; then
+  if [[ ! -f "${CHANGE_DIR}/notes.md" ]]; then
+    cat > "${CHANGE_DIR}/notes.md" <<NOTESEOF
+# ${CHANGE_SLUG} (minimal / T1)
+
+Branch: \`${AGENT_BRANCH}\`
+
+Describe the change in a sentence or two. Commit message is the spec of record.
+
+## Handoff
+
+- Handoff: change=\`${CHANGE_SLUG}\`; branch=\`${AGENT_BRANCH}\`; scope=\`TODO\`; action=\`continue this sandbox or finish cleanup after a usage-limit/manual takeover\`.
+- Copy prompt: Continue \`${CHANGE_SLUG}\` on branch \`${AGENT_BRANCH}\`. Work inside the existing sandbox, review \`openspec/changes/${CHANGE_SLUG}/notes.md\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`.
+
+## Cleanup
+
+- [ ] Run: \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`
+- [ ] Record PR URL + \`MERGED\` state in the completion handoff.
+- [ ] Confirm sandbox worktree is gone (\`git worktree list\`, \`git branch -a\`).
+NOTESEOF
+  fi
+  echo "[gitguardex] OpenSpec change workspace (minimal) ready: ${CHANGE_DIR}"
+  echo "[gitguardex] Notes-only scaffold: ${CHANGE_DIR}/notes.md"
+  exit 0
+fi
+
 if [[ ! -f "${CHANGE_DIR}/proposal.md" ]]; then
   cat > "${CHANGE_DIR}/proposal.md" <<PROPOSALEOF
 ## Why
@@ -51,6 +106,19 @@ fi
 
 if [[ ! -f "${CHANGE_DIR}/tasks.md" ]]; then
   cat > "${CHANGE_DIR}/tasks.md" <<TASKSEOF
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches \`MERGED\` state on \`origin\` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a \`BLOCKED:\` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=\`${CHANGE_SLUG}\`; branch=\`${AGENT_BRANCH}\`; scope=\`TODO\`; action=\`continue this sandbox or finish cleanup after a usage-limit/manual takeover\`.
+- Copy prompt: Continue \`${CHANGE_SLUG}\` on branch \`${AGENT_BRANCH}\`. Work inside the existing sandbox, review \`openspec/changes/${CHANGE_SLUG}/tasks.md\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`.
+
 ## 1. Specification
 
 - [ ] 1.1 Finalize proposal scope and acceptance criteria for \`${CHANGE_SLUG}\`.
@@ -67,11 +135,11 @@ if [[ ! -f "${CHANGE_DIR}/tasks.md" ]]; then
 - [ ] 3.2 Run \`openspec validate ${CHANGE_SLUG} --type change --strict\`.
 - [ ] 3.3 Run \`openspec validate --specs\`.
 
-## 4. Completion
+## 4. Cleanup (mandatory; run before claiming completion)
 
-- [ ] 4.1 Finish the agent branch via PR merge + cleanup (\`gx finish --via-pr --wait-for-merge --cleanup\` or \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base <base-branch> --via-pr --wait-for-merge --cleanup\`).
-- [ ] 4.2 Record PR URL + final \`MERGED\` state in the completion handoff.
-- [ ] 4.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or capture a \`BLOCKED:\` handoff if merge/cleanup is pending.
+- [ ] 4.1 Run the cleanup pipeline: \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (\`MERGED\`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (\`git worktree list\` no longer shows the agent path; \`git branch -a\` shows no surviving local/remote refs for the branch).
 TASKSEOF
 fi