@imdeadpool/guardex 7.0.22 → 7.0.24

package/templates/AGENTS.multiagent-safety.md

@@ -10,6 +10,29 @@
 **Task-size routing.** Small tasks stay in direct caveman-only mode. For typos, single-file tweaks, one-liners, version bumps, or similarly bounded asks, solve directly and do not escalate into heavy OMX orchestration just because a keyword appears. Treat `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches.
 Promote to OMX orchestration only when the task is medium/large: multi-file behavior changes, API/schema work, refactors, migrations, architecture, cross-cutting scope, or long prompts. Heavy OMX modes (`ralph`, `autopilot`, `team`, `ultrawork`, `swarm`, `ralplan`) are for that larger scope. If the task grows while working, upgrade then.
 
+## Token / Context Budget
+
+Default: less word, same proof.
+
+- For prompts about `token inefficiency`, `reviewer mode`, `minimal token overhead`, or session waste patterns, switch into low-overhead mode: plan in at most 4 bullets, execute by phase, batch related reads/commands, avoid duplicate reads and interactive loops, keep outputs compact, and verify once per phase.
+- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine; low output spread across 20+ steps with rising per-turn input is fragmentation and should be treated as context growth first.
+- Startup / resume summaries stay tiny: `branch`, `task`, `blocker`, `next step`, and `evidence`.
+- Memory-driven starts stay ordered: read active `.omx/state` first, then one live `.omx/notepad.md` handoff, then external memory only when the task depends on prior repo decisions, a previous lane, or ambiguous continuity. Stop after the first 1-2 relevant hits.
+- Front-load scaffold/path discovery into one grouped inspection pass. Avoid serial `ls` / `find` / `rg` / `cat` retries that only rediscover the same path state.
+- Treat repeated `write_stdin`, repeated `sed` / `cat` peeks, and tiny diagnostic follow-up checks as strong negative signals. If they appear alongside climbing input cost, stop the probe loop and batch the next phase.
+- Tool / hook summaries stay tiny: command, status, last meaningful lines only. Drop routine hook boilerplate.
+- Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases. Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
+- When a session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
+- Keep `.omx/notepad.md` lean: live handoffs only. Use exactly `branch`, `task`, `blocker`, `next step`, and `evidence`; move narrative proof into OpenSpec artifacts, PRs, or command output.
+
+## OMX Caveman Style
+
+- Commentary and progress updates use smart-caveman `ultra` by default: drop articles, filler, pleasantries, and hedging. Fragments are fine when they stay clear.
+- Answer order stays fixed: answer first, cause next, fix or next step last. If yes/no fits, say yes/no first.
+- Keep literals exact: code, commands, file paths, flags, env vars, URLs, numbers, timestamps, and error text are never caveman-compressed.
+- Auto-clarity wins: switch back to `lite` or normal wording for security warnings, irreversible actions, privacy/compliance notes, ordered instructions where fragments may confuse, or when the user is confused and needs more detail.
+- Boundaries stay normal/exact for code, commits, PR text, specs, logs, and blocker evidence.
+
 **Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope.
 Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
@@ -25,6 +48,8 @@ OMX completion policy: when a task is done, the agent must commit the task chang
 
 **Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
 
+**Open questions.** If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan/<plan-slug>/open-questions.md` as an unchecked `- [ ]` item. Resolve it in-place when answered instead of burying it in chat-only notes.
+
 **OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.

package/templates/scripts/agent-branch-finish.sh

@@ -409,6 +409,33 @@ is_remote_branch_missing_error() {
   return 1
 }
 
+local_branch_exists() {
+  local branch="$1"
+  git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}"
+}
+
+delete_local_branch_for_cleanup() {
+  local branch="$1"
+  local delete_output=""
+
+  if ! local_branch_exists "$branch"; then
+    echo "[agent-branch-finish] Local branch '${branch}' was already deleted; continuing cleanup." >&2
+    return 0
+  fi
+
+  if delete_output="$(git -C "$repo_root" branch -d "$branch" 2>&1)"; then
+    return 0
+  fi
+
+  if ! local_branch_exists "$branch"; then
+    echo "[agent-branch-finish] Local branch '${branch}' was already deleted; continuing cleanup." >&2
+    return 0
+  fi
+
+  echo "$delete_output" >&2
+  return 1
+}
+
 read_pr_state() {
   local state_line
   state_line="$("$GH_BIN" pr view "$SOURCE_BRANCH" --json state,mergedAt,url --jq '[.state, (.mergedAt // ""), (.url // "")] | join("\u001f")' 2>/dev/null || true)"
@@ -428,6 +455,44 @@ read_pr_state() {
   return 0
 }
 
+read_merged_pr_for_head() {
+  local head_sha="${1:-}"
+  local state_line=""
+  local parsed_state=""
+  local parsed_merged_at=""
+  local parsed_url=""
+
+  if [[ -z "$head_sha" ]]; then
+    return 1
+  fi
+
+  state_line="$("$GH_BIN" pr list \
+    --state merged \
+    --head "$SOURCE_BRANCH" \
+    --base "$BASE_BRANCH" \
+    --json state,mergedAt,url,headRefOid \
+    --jq "map(select(.headRefOid == \"$head_sha\")) | sort_by(.mergedAt // \"\") | reverse | (.[0] // {}) | [(.state // \"\"), (.mergedAt // \"\"), (.url // \"\")] | join(\"\u001f\")" \
+    2>/dev/null || true)"
+  if [[ -z "$state_line" ]]; then
+    return 1
+  fi
+
+  IFS=$'\x1f' read -r parsed_state parsed_merged_at parsed_url <<< "$state_line"
+  if [[ -z "$parsed_state" && -z "$parsed_merged_at" && -z "$parsed_url" ]]; then
+    return 1
+  fi
+  if [[ "$parsed_state" != "MERGED" && -z "$parsed_merged_at" ]]; then
+    return 1
+  fi
+
+  PR_STATE="$parsed_state"
+  PR_MERGED_AT="$parsed_merged_at"
+  if [[ -n "$parsed_url" ]]; then
+    pr_url="$parsed_url"
+  fi
+  return 0
+}
+
 wait_for_pr_merge() {
   local deadline
   deadline=$(( $(date +%s) + WAIT_TIMEOUT_SECONDS ))
@@ -482,11 +547,22 @@ wait_for_pr_merge() {
 }
 
 run_pr_flow() {
+  local source_head_sha=""
+
   if ! command -v "$GH_BIN" >/dev/null 2>&1; then
     echo "[agent-branch-finish] PR fallback requested but GitHub CLI not found: ${GH_BIN}" >&2
     return 1
   fi
 
+  source_head_sha="$(git -C "$repo_root" rev-parse "$SOURCE_BRANCH" 2>/dev/null || true)"
+  if read_merged_pr_for_head "$source_head_sha"; then
+    echo "[agent-branch-finish] Source branch head already landed in a merged PR; skipping new PR creation and continuing cleanup." >&2
+    if [[ -n "$pr_url" ]]; then
+      echo "[agent-branch-finish] Merged PR: ${pr_url}" >&2
+    fi
+    return 0
+  fi
+
   git -C "$source_worktree" push -u origin "$SOURCE_BRANCH"
 
   pr_title="$(git -C "$repo_root" log -1 --pretty=%s "$SOURCE_BRANCH" 2>/dev/null || true)"
@@ -607,7 +683,9 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
     git -C "$repo_root" worktree remove "$source_worktree" --force >/dev/null 2>&1 || true
   fi
 
-  git -C "$repo_root" branch -d "$SOURCE_BRANCH"
+  if ! delete_local_branch_for_cleanup "$SOURCE_BRANCH"; then
+    exit 1
+  fi
 
   if [[ "$PUSH_ENABLED" -eq 1 && "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
     if git -C "$repo_root" ls-remote --exit-code --heads origin "$SOURCE_BRANCH" >/dev/null 2>&1; then

package/templates/scripts/agent-branch-start.sh

@@ -155,6 +155,15 @@ env_flag_truthy() {
   esac
 }
 
+maybe_fail_after_auto_transfer_stash() {
+  if env_flag_truthy "${GUARDEX_TEST_FAIL_AFTER_AUTO_TRANSFER_STASH:-}"; then
+    echo "[agent-branch-start] Simulated failure after capturing auto-transfer stash." >&2
+    return 1
+  fi
+
+  return 0
+}
+
 default_worktree_root_rel() {
   local raw_agent="$1"
   local override="${GUARDEX_AGENT_TYPE:-}"
@@ -580,6 +589,27 @@ fi
 auto_transfer_stash_ref=""
 auto_transfer_message=""
 auto_transfer_source_branch=""
+auto_transfer_completed=0
+
+restore_auto_transfer_stash_on_failure() {
+  local exit_code="${1:-0}"
+  if [[ "$exit_code" -eq 0 ]] || [[ -z "$auto_transfer_stash_ref" ]] || [[ "$auto_transfer_completed" -eq 1 ]]; then
+    return 0
+  fi
+
+  local transfer_label="${auto_transfer_source_branch:-$BASE_BRANCH}"
+  if git -C "$repo_root" stash apply "$auto_transfer_stash_ref" >/dev/null 2>&1; then
+    git -C "$repo_root" stash drop "$auto_transfer_stash_ref" >/dev/null 2>&1 || true
+    auto_transfer_stash_ref=""
+    echo "[agent-branch-start] Restored moved changes back to '${transfer_label}' after startup failure." >&2
+  else
+    echo "[agent-branch-start] Startup failed and auto-restore also failed." >&2
+    echo "[agent-branch-start] Changes are preserved in ${auto_transfer_stash_ref} on ${transfer_label}." >&2
+  fi
+}
+
+trap 'restore_auto_transfer_stash_on_failure "$?"' EXIT
+
 current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
 protected_branches_raw="$(resolve_protected_branches "$repo_root")"
 if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_branch_name "$current_branch" "$protected_branches_raw"; then
@@ -593,6 +623,9 @@ if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_bra
       if [[ -n "$auto_transfer_stash_ref" ]]; then
         auto_transfer_source_branch="$current_branch"
         echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'. Moving them to '${branch_name}'..."
+        if ! maybe_fail_after_auto_transfer_stash; then
+          exit 1
+        fi
       fi
     fi
   fi
@@ -610,7 +643,9 @@ git -C "$worktree_path" branch --unset-upstream "$branch_name" >/dev/null 2>&1 |
 
 if [[ -n "$auto_transfer_stash_ref" ]]; then
   if git -C "$worktree_path" stash apply "$auto_transfer_stash_ref" >/dev/null 2>&1; then
+    auto_transfer_completed=1
     git -C "$repo_root" stash drop "$auto_transfer_stash_ref" >/dev/null 2>&1 || true
+    auto_transfer_stash_ref=""
     transfer_label="${auto_transfer_source_branch:-$BASE_BRANCH}"
     echo "[agent-branch-start] Moved local changes from '${transfer_label}' into '${branch_name}'."
   else

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

@@ -23,7 +23,9 @@ 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 start --repo <path> --branch <name> --task <task> --agent <agent> --worktree <path> --pid <pid> --cli <name> [--task-mode <caveman|omx>] [--openspec-tier <T0|T1|T2|T3>] [--routing-reason <text>] [--state <working|thinking|idle>]\n' +
+    '  node scripts/agent-session-state.js heartbeat --repo <path> --branch <name> [--state <working|thinking|idle>]\n' +
+    '  node scripts/agent-session-state.js terminate --repo <path> --branch <name>\n' +
     '  node scripts/agent-session-state.js stop --repo <path> --branch <name>\n'
   );
 }
@@ -65,6 +67,10 @@ function writeSessionRecord(options) {
     worktreePath: requireOption(options, 'worktree'),
     pid: requireOption(options, 'pid'),
     cliName: requireOption(options, 'cli'),
+    taskMode: options['task-mode'],
+    openspecTier: options['openspec-tier'],
+    taskRoutingReason: options['routing-reason'],
+    state: options.state,
   });
 
   const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
@@ -72,6 +78,53 @@ function writeSessionRecord(options) {
   fs.writeFileSync(targetPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
 }
 
+function refreshSessionRecord(options) {
+  const repoRoot = requireOption(options, 'repo');
+  const branch = requireOption(options, 'branch');
+  const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
+  if (!fs.existsSync(targetPath)) {
+    return;
+  }
+
+  const parsed = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  const nextRecord = {
+    ...parsed,
+    lastHeartbeatAt: new Date().toISOString(),
+  };
+  if (options.state) {
+    nextRecord.state = options.state;
+  }
+
+  fs.writeFileSync(targetPath, `${JSON.stringify(nextRecord, null, 2)}\n`, 'utf8');
+}
+
+function readSessionRecord(options) {
+  const repoRoot = requireOption(options, 'repo');
+  const branch = requireOption(options, 'branch');
+  const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
+  if (!fs.existsSync(targetPath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+}
+
+function terminateSessionProcess(options) {
+  const record = readSessionRecord(options);
+  const pid = Number(record?.pid);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error('No live pid recorded for branch.');
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch (error) {
+    if (error?.code === 'ESRCH') {
+      return;
+    }
+    throw error;
+  }
+}
+
 function removeSessionRecord(options) {
   const repoRoot = requireOption(options, 'repo');
   const branch = requireOption(options, 'branch');
@@ -93,6 +146,14 @@ function main() {
     writeSessionRecord(options);
     return;
   }
+  if (command === 'heartbeat') {
+    refreshSessionRecord(options);
+    return;
+  }
+  if (command === 'terminate') {
+    terminateSessionProcess(options);
+    return;
+  }
   if (command === 'stop') {
     removeSessionRecord(options);
     return;

package/templates/scripts/codex-agent.sh

@@ -636,6 +636,41 @@ clear_active_session_state() {
   run_active_session_state stop --repo "$repo_root" --branch "$branch"
 }
 
+heartbeat_active_session_state() {
+  local branch="$1"
+  run_active_session_state heartbeat --repo "$repo_root" --branch "$branch" --state working
+}
+
+normalize_heartbeat_interval_seconds() {
+  local raw="${GUARDEX_ACTIVE_SESSION_HEARTBEAT_INTERVAL_SECONDS:-15}"
+  if [[ "$raw" =~ ^[0-9]+$ ]] && [[ "$raw" -ge 1 ]]; then
+    printf '%s' "$raw"
+    return 0
+  fi
+  printf '15'
+}
+
+start_active_session_heartbeat() {
+  local branch="$1"
+  local interval
+  interval="$(normalize_heartbeat_interval_seconds)"
+  (
+    while true; do
+      sleep "$interval" || break
+      heartbeat_active_session_state "$branch"
+    done
+  ) &
+  active_session_heartbeat_pid="$!"
+}
+
+stop_active_session_heartbeat() {
+  if [[ -n "${active_session_heartbeat_pid:-}" ]]; then
+    kill "$active_session_heartbeat_pid" >/dev/null 2>&1 || true
+    wait "$active_session_heartbeat_pid" >/dev/null 2>&1 || true
+    active_session_heartbeat_pid=""
+  fi
+}
+
 origin_remote_supports_pr_finish() {
   local origin_url
   origin_url="$(git -C "$repo_root" remote get-url origin 2>/dev/null || true)"
@@ -1024,9 +1059,11 @@ fi
 echo "[codex-agent] Task routing: $(describe_task_routing) (${TASK_ROUTING_REASON})"
 
 active_session_recorded=0
+active_session_heartbeat_pid=""
 cleanup_active_session_state_on_exit() {
   set +e
   if [[ "${active_session_recorded:-0}" -eq 1 && -n "${worktree_branch:-}" && "${worktree_branch:-}" != "HEAD" ]]; then
+    stop_active_session_heartbeat
     clear_active_session_state "$worktree_branch"
     active_session_recorded=0
   fi
@@ -1034,6 +1071,7 @@ cleanup_active_session_state_on_exit() {
 
 record_active_session_state "$worktree_path" "$worktree_branch"
 active_session_recorded=1
+start_active_session_heartbeat "$worktree_branch"
 trap cleanup_active_session_state_on_exit EXIT INT TERM
 
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"

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

@@ -4,6 +4,8 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+const PATCH_COMPATIBILITY_WINDOW = 20;
+
 function parseOptions(argv) {
   const options = {};
   for (let index = 0; index < argv.length; index += 1) {
@@ -43,6 +45,26 @@ function removeIfExists(targetPath) {
   }
 }
 
+function parseSimpleSemver(version) {
+  const parts = String(version || '').trim().split('.').map((part) => Number.parseInt(part, 10));
+  if (parts.length !== 3 || parts.some((part) => Number.isNaN(part))) {
+    throw new Error(`Expected simple semver for the Active Agents companion, received "${version}".`);
+  }
+  return parts;
+}
+
+function buildInstallTargets(extensionId, version, extensionsDir) {
+  const [major, minor, patch] = parseSimpleSemver(version);
+  const firstCompatiblePatch = Math.max(0, patch - PATCH_COMPATIBILITY_WINDOW);
+  const targets = [path.join(extensionsDir, extensionId)];
+
+  for (let compatiblePatch = firstCompatiblePatch; compatiblePatch <= patch; compatiblePatch += 1) {
+    targets.push(path.join(extensionsDir, `${extensionId}-${major}.${minor}.${compatiblePatch}`));
+  }
+
+  return targets;
+}
+
 function main() {
   const repoRoot = path.resolve(__dirname, '..');
   const options = parseOptions(process.argv.slice(2));
@@ -57,30 +79,35 @@ function main() {
   );
 
   fs.mkdirSync(extensionsDir, { recursive: true });
-  const targetDir = path.join(extensionsDir, `${extensionId}-${manifest.version}`);
+  const targetDirs = buildInstallTargets(extensionId, manifest.version, extensionsDir);
+  const canonicalTargetDir = targetDirs[0];
+  const keepDirNames = new Set(targetDirs.map((targetDir) => path.basename(targetDir)));
 
   for (const entry of fs.readdirSync(extensionsDir, { withFileTypes: true })) {
     if (!entry.isDirectory()) {
       continue;
     }
-    if (entry.name === path.basename(targetDir)) {
+    if (keepDirNames.has(entry.name)) {
       continue;
     }
-    if (entry.name.startsWith(`${extensionId}-`)) {
+    if (entry.name === extensionId || entry.name.startsWith(`${extensionId}-`)) {
       removeIfExists(path.join(extensionsDir, entry.name));
     }
   }
 
-  removeIfExists(targetDir);
-  fs.cpSync(sourceDir, targetDir, {
-    recursive: true,
-    force: true,
-    preserveTimestamps: true,
-  });
+  for (const targetDir of targetDirs) {
+    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',
+    `[guardex-active-agents] Installed ${extensionId}@${manifest.version} to ${canonicalTargetDir}\n` +
+      `[guardex-active-agents] Refreshed ${targetDirs.length - 1} recent patch compatibility path(s) for already-open windows.\n` +
+      '[guardex-active-agents] Reload each already-open VS Code window to activate the newest Source Control companion.\n',
   );
 }
 

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

@@ -50,17 +50,38 @@ Chronological checkpoint log for all roles.
 CPTEOF
 fi
 
+if [[ ! -f "$PLAN_DIR/open-questions.md" ]]; then
+  cat > "$PLAN_DIR/open-questions.md" <<OPENQUESTIONSEOF
+# Open Questions: ${PLAN_SLUG}
+
+Capture unresolved plan questions here as unchecked checklist items.
+Keep each item concrete, decision-shaped, and easy to close with evidence.
+
+- [ ] Add the next unresolved question here.
+OPENQUESTIONSEOF
+fi
+
 if [[ ! -f "$PLAN_DIR/README.md" ]]; then
   {
     echo "# Plan Workspace: ${PLAN_SLUG}"
     echo
     echo "This folder stores durable planning artifacts before implementation changes."
     echo
+    echo "## Shared files"
+    echo "- \`summary.md\`"
+    echo "- \`checkpoints.md\`"
+    echo "- \`phases.md\`"
+    echo "- \`open-questions.md\`"
+    echo "- \`coordinator-prompt.md\`"
+    echo "- \`kickoff-prompts.md\`"
+    echo
     echo "## Role folders"
     for role in "${ROLES[@]}"; do
       echo "- \`${role}/\`"
     done
     echo
+    echo "When Codex or Claude hits an unresolved question that should survive chat, add it to \`open-questions.md\` as an unchecked \`- [ ]\` item."
+    echo
     echo "Each role folder contains OpenSpec-style artifacts:"
     echo "- \`.openspec.yaml\`"
     echo "- \`proposal.md\`"
@@ -85,15 +106,17 @@ Drive this plan from draft to execution-ready status with strict checkpoint disc
 
 - \`openspec/plan/${PLAN_SLUG}/summary.md\`
 - \`openspec/plan/${PLAN_SLUG}/checkpoints.md\`
+- \`openspec/plan/${PLAN_SLUG}/open-questions.md\`
 - \`openspec/plan/${PLAN_SLUG}/planner/plan.md\`
 - role \`tasks.md\` files for planner/architect/critic/executor/writer/verifier
 
 ## Coordinator responsibilities
 
 1. Keep checkpoints current in each role \`tasks.md\` and root \`checkpoints.md\`.
-2. Ensure each role has explicit acceptance criteria and verification evidence.
-3. Prevent implementation from starting before planning gates are complete.
-4. Keep handoffs concise: files changed, behavior touched, verification output, risks.
+2. Route unresolved questions and branching decisions into \`open-questions.md\`.
+3. Ensure each role has explicit acceptance criteria and verification evidence.
+4. Prevent implementation from starting before planning gates are complete.
+5. Keep handoffs concise: files changed, behavior touched, verification output, risks.
 
 ## Wave-splitting decision (optional)
 
@@ -109,6 +132,7 @@ If wave splitting is not needed, keep execution under a single owner with normal
 
 - All role checkpoints required for planning are done.
 - Execution lanes (if any) have clear ownership boundaries.
+- \`open-questions.md\` captures unresolved decisions that still need answers.
 - Verification plan and rollback expectations are explicit and testable.
 COORDPROMPTEOF
 fi
@@ -431,6 +455,7 @@ EXCCPTEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -467,6 +492,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -503,6 +529,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -539,6 +566,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -575,6 +603,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -611,6 +640,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -647,6 +677,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 

package/templates/vscode/guardex-active-agents/README.md

@@ -13,17 +13,18 @@ node scripts/install-vscode-active-agents-extension.js
 ```
 
 2. Reload the VS Code window.
-3. In Source Control -> `Active Agents`, use `Start agent` to enter a task + agent name and run `gx branch start`.
+3. In Source Control -> `Active Agents`, use `Start agent` to enter a task + agent name and launch the repo Guardex agent runner. The companion prefers `bash scripts/codex-agent.sh` when present, falls back to `npm run agent:codex --`, and only uses `gx branch start` as a last resort.
 
 What it does:
 
 - Bundles a local GitGuardex icon so repo installs show branded extension metadata inside VS Code.
 - Adds an `Active Agents` view to the Source Control container.
 - Renders one repo node per live Guardex workspace with grouped `ACTIVE AGENTS` and `CHANGES` sections.
-- Splits live sessions inside `ACTIVE AGENTS` into `BLOCKED`, `WORKING NOW`, `IDLE`, `STALLED`, and `DEAD` groups so stuck, active, and inactive lanes stand out immediately.
+- Splits live sessions inside `ACTIVE AGENTS` into `BLOCKED`, `WORKING NOW`, `THINKING`, `STALLED`, and `DEAD` groups so stuck, active, and inactive lanes stand out immediately.
 - Mirrors the same live state in the VS Code status bar so the selected session or active-agent count stays visible outside the tree.
-- Shows one row per live Guardex sandbox session inside those activity groups.
+- Shows one row per live Guardex sandbox session inside those activity groups, with changed-file rows nested under sessions that are touching files.
 - Shows repo-root git changes in a sibling `CHANGES` section when the guarded repo itself is dirty.
-- Derives session state from dirty worktree status, git conflict markers, PID liveness, and recent file mtimes, surfaces working/dead counts in the repo/header summary, and shows changed-file counts for active edits.
-- Uses distinct VS Code codicons for each session state: `warning`, `edit`, `loading~spin`, `clock`, and `error`.
-- Reads repo-local presence files from `.omx/state/active-sessions/` and falls back to managed worktree-root `AGENT.lock` telemetry when the launcher session file is absent.
+- Derives session state from dirty worktree status, git conflict markers, heartbeat freshness, PID liveness, and recent file mtimes, surfaces working/dead/conflict counts in the repo/header summary, and shows changed-file counts for active edits.
+- Uses distinct VS Code codicons for each session state, including animated `loading~spin` for `WORKING NOW`.
+- Reads repo-local presence files from `.omx/state/active-sessions/`, expects `lastHeartbeatAt` freshness, and falls back to managed worktree-root `AGENT.lock` telemetry when the launcher session file is absent.
+- Publishes `guardex.hasAgents` and `guardex.hasConflicts` context keys for other VS Code contributions.