@imdeadpool/guardex 7.0.22 → 7.0.23

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.