@imdeadpool/guardex 7.0.15 → 7.0.18

package/templates/scripts/agent-session-state.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function resolveSessionSchemaModule() {
+  const candidates = [
+    path.resolve(__dirname, '..', 'vscode', 'guardex-active-agents', 'session-schema.js'),
+    path.resolve(__dirname, '..', 'templates', 'vscode', 'guardex-active-agents', 'session-schema.js'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return require(candidate);
+    }
+  }
+
+  throw new Error('Could not resolve Guardex active-agent session schema module.');
+}
+
+const sessionSchema = resolveSessionSchemaModule();
+
+function usage() {
+  return (
+    'Usage:\n' +
+    '  node scripts/agent-session-state.js start --repo <path> --branch <name> --task <task> --agent <agent> --worktree <path> --pid <pid> --cli <name>\n' +
+    '  node scripts/agent-session-state.js stop --repo <path> --branch <name>\n'
+  );
+}
+
+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 requireOption(options, key) {
+  const value = options[key];
+  if (!value) {
+    throw new Error(`Missing required option --${key}`);
+  }
+  return value;
+}
+
+function writeSessionRecord(options) {
+  const repoRoot = requireOption(options, 'repo');
+  const branch = requireOption(options, 'branch');
+  const record = sessionSchema.buildSessionRecord({
+    repoRoot,
+    branch,
+    taskName: requireOption(options, 'task'),
+    agentName: requireOption(options, 'agent'),
+    worktreePath: requireOption(options, 'worktree'),
+    pid: requireOption(options, 'pid'),
+    cliName: requireOption(options, 'cli'),
+  });
+
+  const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+}
+
+function removeSessionRecord(options) {
+  const repoRoot = requireOption(options, 'repo');
+  const branch = requireOption(options, 'branch');
+  const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
+  if (fs.existsSync(targetPath)) {
+    fs.unlinkSync(targetPath);
+  }
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || ['-h', '--help', 'help'].includes(command)) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const options = parseOptions(rest);
+  if (command === 'start') {
+    writeSessionRecord(options);
+    return;
+  }
+  if (command === 'stop') {
+    removeSessionRecord(options);
+    return;
+  }
+
+  throw new Error(`Unknown subcommand: ${command}`);
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`[guardex-active-session] ${error.message}\n`);
+  process.stderr.write(usage());
+  process.exitCode = 1;
+}

package/templates/scripts/codex-agent.sh

@@ -6,6 +6,7 @@ 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}"
 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}"
@@ -14,6 +15,7 @@ OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-true}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 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}"
 
 normalize_bool() {
   local raw="${1:-}"
@@ -34,6 +36,19 @@ AUTO_CLEANUP="$(normalize_bool "$AUTO_CLEANUP_RAW" "1")"
 AUTO_WAIT_FOR_MERGE="$(normalize_bool "$AUTO_WAIT_FOR_MERGE_RAW" "1")"
 OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
 
+resolve_openspec_masterplan_label() {
+  local raw="${OPENSPEC_MASTERPLAN_LABEL_RAW:-}"
+  local label
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ -z "$raw" ]]; then
+    printf ''
+    return 0
+  fi
+
+  label="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  printf '%s' "$label"
+}
+
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
 fi
@@ -129,6 +144,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
@@ -161,11 +177,21 @@ sanitize_slug() {
 resolve_openspec_plan_slug() {
   local branch_name="$1"
   local task_slug
+  local masterplan_label=""
+  local branch_role=""
+  local branch_leaf=""
   task_slug="$(sanitize_slug "$TASK_NAME" "task")"
   if [[ -n "$OPENSPEC_PLAN_SLUG_OVERRIDE" ]]; then
     sanitize_slug "$OPENSPEC_PLAN_SLUG_OVERRIDE" "$task_slug"
     return 0
   fi
+  masterplan_label="$(resolve_openspec_masterplan_label)"
+  if [[ -n "$masterplan_label" ]] && [[ "$branch_name" =~ ^agent/([^/]+)/(.+)$ ]]; then
+    branch_role="${BASH_REMATCH[1]}"
+    branch_leaf="${BASH_REMATCH[2]}"
+    sanitize_slug "agent-${branch_role}-${masterplan_label}-${branch_leaf}" "$task_slug"
+    return 0
+  fi
   sanitize_slug "${branch_name//\//-}" "$task_slug"
 }
 
@@ -190,6 +216,23 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
+resolve_worktree_leaf() {
+  local branch_name="$1"
+  local masterplan_label=""
+  local branch_role=""
+  local branch_leaf=""
+
+  masterplan_label="$(resolve_openspec_masterplan_label)"
+  if [[ -n "$masterplan_label" ]] && [[ "$branch_name" =~ ^agent/([^/]+)/(.+)$ ]]; then
+    branch_role="${BASH_REMATCH[1]}"
+    branch_leaf="${BASH_REMATCH[2]}"
+    printf 'agent__%s__%s__%s' "$branch_role" "$masterplan_label" "$branch_leaf"
+    return 0
+  fi
+
+  printf '%s' "${branch_name//\//__}"
+}
+
 hydrate_local_helper_in_worktree() {
   local worktree="$1"
   local relative_path="$2"
@@ -314,7 +357,7 @@ start_sandbox_fallback() {
 
   worktree_root="${repo_root}/.omx/agent-worktrees"
   mkdir -p "$worktree_root"
-  worktree_path="${worktree_root}/${branch_name//\//__}"
+  worktree_path="${worktree_root}/$(resolve_worktree_leaf "$branch_name")"
   if [[ -e "$worktree_path" ]]; then
     echo "[codex-agent] Fallback worktree path already exists: $worktree_path" >&2
     return 1
@@ -346,7 +389,11 @@ initial_repo_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/nu
 start_output=""
 start_status=0
 set +e
-start_output="$(GUARDEX_OPENSPEC_AUTO_INIT=0 bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1)"
+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
+)"
 start_status=$?
 set -e
 
@@ -401,6 +448,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)"
@@ -429,6 +510,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="bash scripts/agent-branch-finish.sh --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
@@ -788,6 +894,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
@@ -796,6 +915,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
 
@@ -856,6 +977,7 @@ else
     if [[ "$auto_finish_completed" -eq 1 ]]; then
       echo "[codex-agent] Branch kept intentionally. Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     else
+      print_takeover_prompt "$worktree_path" "$worktree_branch"
       echo "[codex-agent] If finished, merge with: bash scripts/agent-branch-finish.sh --branch \"${worktree_branch}\" --base dev --via-pr --wait-for-merge"
       echo "[codex-agent] Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     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