@imdeadpool/guardex 7.0.21 → 7.0.23

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

@@ -218,18 +218,48 @@ fi
 
 get_worktree_for_branch() {
   local branch="$1"
-  git -C "$repo_root" worktree list --porcelain | awk -v target="refs/heads/${branch}" '
+  git -C "$repo_root" worktree list --porcelain | awk -v target="refs/heads/${branch}" -v probe_prefix="${agent_worktree_root}/__source-probe-" '
     $1 == "worktree" { wt = $2 }
-    $1 == "branch" && $2 == target { print wt; exit }
+    $1 == "branch" && $2 == target {
+      if (index(wt, probe_prefix) != 1) {
+        print wt
+        exit
+      }
+    }
   '
 }
 
+remove_stale_source_probe_worktrees() {
+  local branch="$1"
+  local stale_probe=""
+
+  while IFS= read -r stale_probe; do
+    [[ -z "$stale_probe" ]] && continue
+    [[ "$stale_probe" == "$current_worktree" ]] && continue
+
+    echo "[agent-branch-finish] Removing stale source-probe worktree for '${branch}': ${stale_probe}" >&2
+    git -C "$stale_probe" rebase --abort >/dev/null 2>&1 || true
+    git -C "$stale_probe" merge --abort >/dev/null 2>&1 || true
+    git -C "$repo_root" worktree remove "$stale_probe" --force >/dev/null 2>&1 || true
+  done < <(
+    git -C "$repo_root" worktree list --porcelain | awk -v target="refs/heads/${branch}" -v probe_prefix="${agent_worktree_root}/__source-probe-" '
+      $1 == "worktree" { wt = $2 }
+      $1 == "branch" && $2 == target {
+        if (index(wt, probe_prefix) == 1) {
+          print wt
+        }
+      }
+    '
+  )
+}
+
 is_clean_worktree() {
   local wt="$1"
   git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
     && git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json"
 }
 
+remove_stale_source_probe_worktrees "$SOURCE_BRANCH"
 source_worktree="$(get_worktree_for_branch "$SOURCE_BRANCH")"
 created_source_probe=0
 source_probe_path=""
@@ -295,8 +325,13 @@ if [[ "$should_require_sync" -eq 1 ]] && git -C "$repo_root" show-ref --verify -
 
       echo "[agent-sync-guard] Auto-sync failed while rebasing '${SOURCE_BRANCH}' onto origin/${BASE_BRANCH}." >&2
       if [[ "$rebase_active" -eq 1 ]]; then
-        echo "[agent-sync-guard] Resolve conflicts, then run: git -C \"$source_worktree\" rebase --continue" >&2
-        echo "[agent-sync-guard] Or abort: git -C \"$source_worktree\" rebase --abort" >&2
+        if [[ "$created_source_probe" -eq 1 ]]; then
+          echo "[agent-sync-guard] Temporary source-probe worktree will be cleaned up on exit." >&2
+          echo "[agent-sync-guard] Reattach '${SOURCE_BRANCH}' in a regular worktree, then rebase it onto origin/${BASE_BRANCH} manually." >&2
+        else
+          echo "[agent-sync-guard] Resolve conflicts, then run: git -C \"$source_worktree\" rebase --continue" >&2
+          echo "[agent-sync-guard] Or abort: git -C \"$source_worktree\" rebase --abort" >&2
+        fi
       fi
       exit 1
     fi
@@ -366,6 +401,41 @@ is_local_branch_delete_error() {
   return 1
 }
 
+is_remote_branch_missing_error() {
+  local output="$1"
+  if [[ "$output" == *"remote ref does not exist"* ]] || [[ "$output" == *"failed to push some refs"* ]]; then
+    return 0
+  fi
+  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)"
@@ -564,11 +634,21 @@ 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
-      git -C "$repo_root" push origin --delete "$SOURCE_BRANCH"
+      remote_delete_output=""
+      if ! remote_delete_output="$(git -C "$repo_root" push origin --delete "$SOURCE_BRANCH" 2>&1)"; then
+        if is_remote_branch_missing_error "$remote_delete_output"; then
+          echo "[agent-branch-finish] Remote branch '${SOURCE_BRANCH}' was already deleted; continuing cleanup." >&2
+        else
+          echo "$remote_delete_output" >&2
+          exit 1
+        fi
+      fi
     fi
   fi
 

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/agent-worktree-prune.sh

@@ -111,6 +111,13 @@ is_managed_worktree_path() {
   return 1
 }
 
+is_temporary_worktree_path() {
+  local entry="$1"
+  local name
+  name="$(basename "$entry")"
+  [[ "$name" == __agent_integrate-* || "$name" == __source-probe-* ]]
+}
+
 resolve_base_branch() {
   local configured=""
   local current=""
@@ -425,7 +432,9 @@ process_entry() {
   local remove_reason=""
   local branch_delete_mode="safe"
 
-  if [[ -z "$branch_ref" ]]; then
+  if is_temporary_worktree_path "$wt"; then
+    remove_reason="temporary-worktree"
+  elif [[ -z "$branch_ref" ]]; then
     remove_reason="detached-worktree"
   elif ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}"; then
     remove_reason="missing-branch"
@@ -452,6 +461,11 @@ process_entry() {
     return
   fi
 
+  if [[ "$remove_reason" == "temporary-worktree" ]]; then
+    git -C "$wt" rebase --abort >/dev/null 2>&1 || true
+    git -C "$wt" merge --abort >/dev/null 2>&1 || true
+  fi
+
   if [[ "$FORCE_DIRTY" -ne 1 ]] && ! is_clean_worktree "$wt"; then
     skipped_dirty=$((skipped_dirty + 1))
     echo "[agent-worktree-prune] Skipping dirty worktree (${remove_reason}): ${wt}"

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,15 +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.
-- Shows one row per live Guardex sandbox session inside those activity groups.
+- 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, 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.