@imdeadpool/guardex 7.0.22 → 7.0.23

package/templates/vscode/guardex-active-agents/package.json

@@ -3,7 +3,7 @@
   "displayName": "GitGuardex Active Agents",
   "description": "Shows live Guardex sandbox sessions and repo changes inside VS Code Source Control.",
   "publisher": "recodeee",
-  "version": "0.0.3",
+  "version": "0.0.7",
   "license": "MIT",
   "icon": "icon.png",
   "engines": {
@@ -36,6 +36,11 @@
         "title": "Commit Selected Session",
         "icon": "$(check)"
       },
+      {
+        "command": "gitguardex.activeAgents.inspect",
+        "title": "Inspect Session",
+        "icon": "$(info)"
+      },
       {
         "command": "gitguardex.activeAgents.openWorktree",
         "title": "Open Agent Worktree"
@@ -73,14 +78,14 @@
     "viewsWelcome": [
       {
         "view": "gitguardex.activeAgents",
-        "contents": "No active Guardex agents are visible in this workspace yet.\n\n[Start agent](command:gitguardex.activeAgents.startAgent)\n[Open guide](https://github.com/recodeee/gitguardex/blob/main/vscode/guardex-active-agents/README.md#quick-start)\n[Refresh](command:gitguardex.activeAgents.refresh)"
+        "contents": "No live Guardex agents are visible in this workspace yet.\n\nThis view tracks Guardex session files and managed worktree telemetry, not every repo visible in Source Control.\n\n[Start agent](command:gitguardex.activeAgents.startAgent)\n[Open guide](https://github.com/recodeee/gitguardex/blob/main/vscode/guardex-active-agents/README.md#quick-start)\n[Refresh](command:gitguardex.activeAgents.refresh)"
       }
     ],
     "menus": {
       "view/title": [
         {
           "command": "gitguardex.activeAgents.commitSelectedSession",
-          "when": "view == gitguardex.activeAgents",
+          "when": "view == gitguardex.activeAgents && guardex.hasAgents",
           "group": "navigation@1"
         },
         {
@@ -95,6 +100,11 @@
           "when": "view == gitguardex.activeAgents && viewItem == gitguardex.session",
           "group": "inline"
         },
+        {
+          "command": "gitguardex.activeAgents.inspect",
+          "when": "view == gitguardex.activeAgents && viewItem == gitguardex.session",
+          "group": "inline"
+        },
         {
           "command": "gitguardex.activeAgents.finishSession",
           "when": "view == gitguardex.activeAgents && viewItem == gitguardex.session",

package/templates/vscode/guardex-active-agents/session-schema.js

@@ -5,6 +5,7 @@ const cp = require('node:child_process');
 const ACTIVE_SESSIONS_RELATIVE_DIR = path.join('.omx', 'state', 'active-sessions');
 const SESSION_SCHEMA_VERSION = 1;
 const LOCK_FILE_RELATIVE = path.join('.omx', 'state', 'agent-file-locks.json');
+const LOGS_RELATIVE_DIR = path.join('.omx', 'logs');
 const AGENT_WORKTREE_LOCK_FILE = 'AGENT.lock';
 const MANAGED_WORKTREE_ROOTS = [
   path.join('.omx', 'agent-worktrees'),
@@ -13,8 +14,42 @@ const MANAGED_WORKTREE_ROOTS = [
 const MAX_CHANGED_PATH_PREVIEW = 3;
 const ACTIVE_SESSIONS_FILTER_PREFIX = ACTIVE_SESSIONS_RELATIVE_DIR.split(path.sep).join('/');
 const LOCK_FILE_FILTER_PATH = LOCK_FILE_RELATIVE.split(path.sep).join('/');
+const MANAGED_WORKTREE_FILTER_PREFIXES = MANAGED_WORKTREE_ROOTS
+  .map((relativeRoot) => relativeRoot.split(path.sep).join('/').replace(/\/+$/, ''));
 const IDLE_ACTIVITY_WINDOW_MS = 2 * 60 * 1000;
 const STALLED_ACTIVITY_WINDOW_MS = 15 * 60 * 1000;
+const HEARTBEAT_STALE_MS = 5 * 60 * 1000;
+const DEFAULT_BASE_BRANCH = 'dev';
+const DEFAULT_LOG_TAIL_LINE_COUNT = 200;
+const ADVISORY_SESSION_STATES = new Set(['working', 'thinking', 'idle']);
+const WORKTREE_ACTIVITY_CACHE_TTL_MS = 3_000;
+const MAX_WORKTREE_ACTIVITY_STAT_PATHS = 200;
+const WORKTREE_ACTIVITY_SKIP_PREFIXES = [
+  '.git/',
+  '.omx/',
+  '.omc/',
+  'node_modules/',
+  'dist/',
+  'build/',
+  'coverage/',
+  '.next/',
+  'out/',
+  'vendor/',
+];
+const WORKTREE_ACTIVITY_PRIORITY_PREFIXES = [
+  'src/',
+  'app/',
+  'apps/',
+  'lib/',
+  'packages/',
+  'scripts/',
+  'test/',
+  'tests/',
+  'vscode/',
+  'templates/',
+  'openspec/',
+  'docs/',
+];
 const BLOCKING_GIT_STATES = [
   {
     label: 'Rebase in progress.',
@@ -29,6 +64,7 @@ const BLOCKING_GIT_STATES = [
     markers: ['CHERRY_PICK_HEAD'],
   },
 ];
+const worktreeActivityCache = new Map();
 
 function toNonEmptyString(value, fallback = '') {
   const normalized = typeof value === 'string' ? value.trim() : String(value || '').trim();
@@ -50,6 +86,11 @@ function normalizeOpenSpecTier(value) {
   return ['T0', 'T1', 'T2', 'T3'].includes(normalized) ? normalized : '';
 }
 
+function normalizeAdvisoryState(value, fallback = 'working') {
+  const normalized = toNonEmptyString(value).toLowerCase();
+  return ADVISORY_SESSION_STATES.has(normalized) ? normalized : fallback;
+}
+
 function sanitizeBranchForFile(branch) {
   const normalized = toNonEmptyString(branch, 'session');
   return normalized.replace(/[^a-zA-Z0-9._-]+/g, '__').replace(/^_+|_+$/g, '') || 'session';
@@ -93,6 +134,138 @@ function readJsonFile(filePath) {
   }
 }
 
+function readConfiguredBaseBranch(repoRoot) {
+  const lines = runGitLines(path.resolve(repoRoot), ['config', '--get', 'multiagent.baseBranch']);
+  if (Array.isArray(lines) && typeof lines[0] === 'string' && lines[0].trim()) {
+    return lines[0].trim();
+  }
+  return DEFAULT_BASE_BRANCH;
+}
+
+function readAheadBehindCounts(worktreePath, branch, baseBranch) {
+  const normalizedWorktreePath = toNonEmptyString(worktreePath);
+  const normalizedBranch = toNonEmptyString(branch);
+  const normalizedBaseBranch = toNonEmptyString(baseBranch, DEFAULT_BASE_BRANCH);
+  const compareRef = `origin/${normalizedBaseBranch}`;
+
+  if (!normalizedWorktreePath || !normalizedBranch) {
+    return {
+      compareRef,
+      aheadCount: null,
+      behindCount: null,
+    };
+  }
+
+  const lines = runGitLines(normalizedWorktreePath, [
+    'rev-list',
+    '--left-right',
+    '--count',
+    `${normalizedBranch}...${compareRef}`,
+  ]);
+  const match = Array.isArray(lines) && typeof lines[0] === 'string'
+    ? lines[0].trim().match(/^(\d+)\s+(\d+)$/)
+    : null;
+  if (!match) {
+    return {
+      compareRef,
+      aheadCount: null,
+      behindCount: null,
+    };
+  }
+
+  return {
+    compareRef,
+    aheadCount: Number.parseInt(match[1], 10),
+    behindCount: Number.parseInt(match[2], 10),
+  };
+}
+
+function sessionLogPath(repoRoot, branch) {
+  const normalizedRepoRoot = toNonEmptyString(repoRoot);
+  const normalizedBranch = toNonEmptyString(branch);
+  if (!normalizedRepoRoot || !normalizedBranch) {
+    return '';
+  }
+
+  return path.join(
+    path.resolve(normalizedRepoRoot),
+    LOGS_RELATIVE_DIR,
+    `agent-${sanitizeBranchForFile(normalizedBranch)}.log`,
+  );
+}
+
+function readLogTail(filePath, maxLines = DEFAULT_LOG_TAIL_LINE_COUNT) {
+  const normalizedFilePath = toNonEmptyString(filePath);
+  const normalizedMaxLines = toPositiveInteger(maxLines) || DEFAULT_LOG_TAIL_LINE_COUNT;
+  if (!normalizedFilePath || !fs.existsSync(normalizedFilePath)) {
+    return [];
+  }
+
+  try {
+    const lines = fs.readFileSync(normalizedFilePath, 'utf8').split(/\r?\n/);
+    while (lines.length > 0 && lines[lines.length - 1] === '') {
+      lines.pop();
+    }
+    return lines.slice(-normalizedMaxLines);
+  } catch (_error) {
+    return [];
+  }
+}
+
+function readSessionHeldLocks(repoRoot, branch) {
+  const normalizedRepoRoot = toNonEmptyString(repoRoot);
+  const normalizedBranch = toNonEmptyString(branch);
+  if (!normalizedRepoRoot || !normalizedBranch) {
+    return [];
+  }
+
+  const parsed = readJsonFile(path.join(path.resolve(normalizedRepoRoot), LOCK_FILE_RELATIVE));
+  const locks = parsed?.locks;
+  if (!locks || typeof locks !== 'object' || Array.isArray(locks)) {
+    return [];
+  }
+
+  return Object.entries(locks)
+    .map(([rawRelativePath, entry]) => {
+      if (!entry || typeof entry !== 'object') {
+        return null;
+      }
+
+      const relativePath = normalizeRelativePath(rawRelativePath);
+      const ownerBranch = toNonEmptyString(entry.branch);
+      if (!relativePath || ownerBranch !== normalizedBranch) {
+        return null;
+      }
+
+      return {
+        relativePath,
+        claimedAt: toNonEmptyString(entry.claimed_at),
+        allowDelete: Boolean(entry.allow_delete),
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+
+function readSessionInspectData(session, options = {}) {
+  const repoRoot = toNonEmptyString(session?.repoRoot);
+  const branch = toNonEmptyString(session?.branch);
+  const worktreePath = toNonEmptyString(session?.worktreePath);
+  const baseBranch = readConfiguredBaseBranch(repoRoot);
+  const logPath = sessionLogPath(repoRoot, branch);
+  const logTailLines = readLogTail(logPath, options.logLines);
+
+  return {
+    baseBranch,
+    logPath,
+    logExists: Boolean(logPath) && fs.existsSync(logPath),
+    logTailLines,
+    logTailText: logTailLines.join('\n'),
+    heldLocks: readSessionHeldLocks(repoRoot, branch),
+    ...readAheadBehindCounts(worktreePath, branch, baseBranch),
+  };
+}
+
 function normalizeIsoString(value, fallback = '') {
   const normalized = toNonEmptyString(value);
   if (!normalized) {
@@ -212,6 +385,9 @@ function parseRepoChangeLine(repoRoot, line) {
     || normalizedRelativePath.startsWith(`${LOCK_FILE_FILTER_PATH}/`)
     || normalizedRelativePath === ACTIVE_SESSIONS_FILTER_PREFIX
     || normalizedRelativePath.startsWith(`${ACTIVE_SESSIONS_FILTER_PREFIX}/`)
+    || MANAGED_WORKTREE_FILTER_PREFIXES.some((prefix) => (
+      normalizedRelativePath === prefix || normalizedRelativePath.startsWith(`${prefix}/`)
+    ))
   ) {
     return null;
   }
@@ -294,14 +470,80 @@ function collectWorktreeTrackedPaths(worktreePath) {
     .sort((left, right) => left.localeCompare(right));
 }
 
-function deriveLatestWorktreeFileActivity(worktreePath) {
+function shouldSkipWorktreeActivityPath(relativePath) {
+  const normalized = normalizeRelativePath(relativePath);
+  if (!normalized || normalized === LOCK_FILE_RELATIVE || normalized === AGENT_WORKTREE_LOCK_FILE) {
+    return true;
+  }
+
+  return WORKTREE_ACTIVITY_SKIP_PREFIXES.some((prefix) => (
+    normalized === prefix.slice(0, -1) || normalized.startsWith(prefix)
+  ));
+}
+
+function worktreeActivityPathPriority(relativePath, recentPathsSet) {
+  if (recentPathsSet.has(relativePath)) {
+    return 0;
+  }
+  if (!relativePath.includes('/')) {
+    return 1;
+  }
+  if (WORKTREE_ACTIVITY_PRIORITY_PREFIXES.some((prefix) => relativePath.startsWith(prefix))) {
+    return 2;
+  }
+  return 3;
+}
+
+function collectWorktreeActivityCandidatePaths(worktreePath, trackedPaths) {
+  const recentPaths = runGitLines(worktreePath, ['log', '-1', '--name-only', '--pretty=format:', '--', '.']) || [];
+  const filteredRecentPaths = [...new Set(recentPaths.map(normalizeRelativePath).filter(Boolean))]
+    .filter((relativePath) => !shouldSkipWorktreeActivityPath(relativePath));
+  const recentPathSet = new Set(filteredRecentPaths);
+  const prioritizedTrackedPaths = trackedPaths
+    .map(normalizeRelativePath)
+    .filter(Boolean)
+    .filter((relativePath) => !shouldSkipWorktreeActivityPath(relativePath))
+    .sort((left, right) => {
+      const priorityDelta = worktreeActivityPathPriority(left, recentPathSet)
+        - worktreeActivityPathPriority(right, recentPathSet);
+      if (priorityDelta !== 0) {
+        return priorityDelta;
+      }
+      return left.localeCompare(right);
+    });
+
+  return [...new Set([...filteredRecentPaths, ...prioritizedTrackedPaths])]
+    .slice(0, MAX_WORKTREE_ACTIVITY_STAT_PATHS);
+}
+
+function clearWorktreeActivityCache(worktreePath = '') {
+  const normalizedWorktreePath = toNonEmptyString(worktreePath);
+  if (!normalizedWorktreePath) {
+    worktreeActivityCache.clear();
+    return;
+  }
+  worktreeActivityCache.delete(path.resolve(normalizedWorktreePath));
+}
+
+function deriveLatestWorktreeFileActivity(worktreePath, options = {}) {
+  const now = Number.isFinite(options.now) ? options.now : Date.now();
+  const useCache = options.useCache !== false;
+  const cacheKey = path.resolve(worktreePath);
+  if (useCache) {
+    const cached = worktreeActivityCache.get(cacheKey);
+    if (cached && (now - cached.checkedAtMs) < WORKTREE_ACTIVITY_CACHE_TTL_MS) {
+      return cached.latestMtimeMs;
+    }
+  }
+
   const trackedPaths = collectWorktreeTrackedPaths(worktreePath);
   if (!trackedPaths) {
     return null;
   }
 
+  const candidatePaths = collectWorktreeActivityCandidatePaths(worktreePath, trackedPaths);
   let latestMtimeMs = null;
-  for (const relativePath of trackedPaths) {
+  for (const relativePath of candidatePaths) {
     const absolutePath = path.join(worktreePath, relativePath);
     try {
       const stats = fs.statSync(absolutePath);
@@ -316,6 +558,13 @@ function deriveLatestWorktreeFileActivity(worktreePath) {
     }
   }
 
+  if (useCache) {
+    worktreeActivityCache.set(cacheKey, {
+      checkedAtMs: now,
+      latestMtimeMs,
+    });
+  }
+
   return latestMtimeMs;
 }
 
@@ -323,6 +572,23 @@ function deriveSessionActivity(session, options = {}) {
   const now = Number.isFinite(options.now) ? options.now : Date.now();
   const pid = toPositiveInteger(session?.pid);
   const pidAlive = pid ? isPidAlive(pid) : null;
+  const heartbeatAt = normalizeIsoString(session?.lastHeartbeatAt);
+  const heartbeatMs = Date.parse(heartbeatAt);
+  if (heartbeatAt && Number.isFinite(heartbeatMs) && now - heartbeatMs > HEARTBEAT_STALE_MS) {
+    return {
+      activityKind: 'dead',
+      activityLabel: 'dead',
+      activityCountLabel: '',
+      activitySummary: `Heartbeat stale for ${formatElapsedFrom(heartbeatAt, now)}.`,
+      changeCount: 0,
+      changedPaths: [],
+      worktreeChangedPaths: [],
+      pidAlive,
+      lastFileActivityAt: '',
+      lastFileActivityLabel: '',
+    };
+  }
+
   const blockingLabel = deriveBlockingGitLabel(session.worktreePath);
   if (blockingLabel) {
     return {
@@ -332,6 +598,7 @@ function deriveSessionActivity(session, options = {}) {
       activitySummary: blockingLabel,
       changeCount: 0,
       changedPaths: [],
+      worktreeChangedPaths: [],
       pidAlive,
       lastFileActivityAt: '',
       lastFileActivityLabel: '',
@@ -346,6 +613,7 @@ function deriveSessionActivity(session, options = {}) {
       activitySummary: 'Recorded PID is not alive.',
       changeCount: 0,
       changedPaths: [],
+      worktreeChangedPaths: [],
       pidAlive,
       lastFileActivityAt: '',
       lastFileActivityLabel: '',
@@ -361,6 +629,7 @@ function deriveSessionActivity(session, options = {}) {
       activitySummary: 'Worktree activity unavailable.',
       changeCount: 0,
       changedPaths: [],
+      worktreeChangedPaths: [],
       pidAlive,
       lastFileActivityAt: '',
       lastFileActivityLabel: '',
@@ -368,6 +637,11 @@ function deriveSessionActivity(session, options = {}) {
   }
 
   if (worktreeChangedPaths.length > 0) {
+    const worktreeRelativePaths = [...new Set(worktreeChangedPaths
+      .map((relativePath) => normalizeRelativePath(relativePath))
+      .filter(Boolean))]
+      .sort((left, right) => left.localeCompare(right));
+    clearWorktreeActivityCache(session.worktreePath);
     const changedPaths = [...new Set(worktreeChangedPaths
       .map((relativePath) => normalizeRelativePath(
         path.relative(session.repoRoot, path.resolve(session.worktreePath, relativePath)),
@@ -382,13 +656,17 @@ function deriveSessionActivity(session, options = {}) {
       activitySummary: previewChangedPaths(worktreeChangedPaths),
       changeCount: worktreeChangedPaths.length,
       changedPaths,
+      worktreeChangedPaths: worktreeRelativePaths,
       pidAlive,
       lastFileActivityAt: '',
       lastFileActivityLabel: '',
     };
   }
 
-  const latestFileActivityMs = deriveLatestWorktreeFileActivity(session.worktreePath);
+  const latestFileActivityMs = deriveLatestWorktreeFileActivity(session.worktreePath, {
+    now,
+    useCache: options.useCache,
+  });
   const lastFileActivityAt = Number.isFinite(latestFileActivityMs)
     ? new Date(latestFileActivityMs).toISOString()
     : '';
@@ -407,6 +685,7 @@ function deriveSessionActivity(session, options = {}) {
       activitySummary: `Worktree clean. No file activity for ${lastFileActivityLabel}.`,
       changeCount: 0,
       changedPaths: [],
+      worktreeChangedPaths: [],
       pidAlive,
       lastFileActivityAt,
       lastFileActivityLabel,
@@ -424,6 +703,7 @@ function deriveSessionActivity(session, options = {}) {
         : 'Worktree clean.',
     changeCount: 0,
     changedPaths: [],
+    worktreeChangedPaths: [],
     pidAlive,
     lastFileActivityAt,
     lastFileActivityLabel,
@@ -436,6 +716,7 @@ function buildSessionRecord(input) {
   const branch = toNonEmptyString(input.branch);
   const pid = toPositiveInteger(input.pid);
   const startedAt = input.startedAt ? new Date(input.startedAt) : new Date();
+  const lastHeartbeatAt = input.lastHeartbeatAt ? new Date(input.lastHeartbeatAt) : new Date();
 
   if (!branch) {
     throw new Error('branch is required');
@@ -452,6 +733,9 @@ function buildSessionRecord(input) {
   if (Number.isNaN(startedAt.getTime())) {
     throw new Error('startedAt must be a valid date');
   }
+  if (Number.isNaN(lastHeartbeatAt.getTime())) {
+    throw new Error('lastHeartbeatAt must be a valid date');
+  }
 
   return {
     schemaVersion: SESSION_SCHEMA_VERSION,
@@ -467,6 +751,8 @@ function buildSessionRecord(input) {
     openspecTier: normalizeOpenSpecTier(input.openspecTier),
     taskRoutingReason: toNonEmptyString(input.taskRoutingReason),
     startedAt: startedAt.toISOString(),
+    lastHeartbeatAt: lastHeartbeatAt.toISOString(),
+    state: normalizeAdvisoryState(input.state),
   };
 }
 
@@ -487,9 +773,17 @@ function normalizeSessionRecord(input, options = {}) {
   const branch = toNonEmptyString(input.branch);
   const worktreePath = toNonEmptyString(input.worktreePath);
   const startedAt = new Date(input.startedAt);
+  const lastHeartbeatAt = new Date(input.lastHeartbeatAt || input.startedAt);
   const pid = toPositiveInteger(input.pid);
 
-  if (!repoRoot || !branch || !worktreePath || !pid || Number.isNaN(startedAt.getTime())) {
+  if (
+    !repoRoot
+    || !branch
+    || !worktreePath
+    || !pid
+    || Number.isNaN(startedAt.getTime())
+    || Number.isNaN(lastHeartbeatAt.getTime())
+  ) {
     return null;
   }
 
@@ -507,9 +801,12 @@ function normalizeSessionRecord(input, options = {}) {
     openspecTier: normalizeOpenSpecTier(input.openspecTier),
     taskRoutingReason: toNonEmptyString(input.taskRoutingReason),
     startedAt: startedAt.toISOString(),
+    lastHeartbeatAt: lastHeartbeatAt.toISOString(),
+    state: normalizeAdvisoryState(input.state, 'idle'),
     filePath: toNonEmptyString(options.filePath),
     label: deriveSessionLabel(branch, worktreePath),
     changedPaths: [],
+    worktreeChangedPaths: [],
     sourceKind: 'active-session',
     telemetryUpdatedAt: '',
     telemetrySource: '',
@@ -646,9 +943,12 @@ function buildWorktreeLockSession(repoRoot, worktreePath, lockPayload, options =
     openspecTier: '',
     taskRoutingReason: '',
     startedAt,
+    lastHeartbeatAt: '',
+    state: '',
     filePath: path.join(worktreePath, AGENT_WORKTREE_LOCK_FILE),
     label,
     changedPaths: [],
+    worktreeChangedPaths: [],
     sourceKind: 'worktree-lock',
     telemetryUpdatedAt: telemetryUpdatedAt || startedAt,
     telemetrySource: toNonEmptyString(lockPayload?.source, 'worktree-lock'),
@@ -782,6 +1082,7 @@ module.exports = {
   SESSION_SCHEMA_VERSION,
   activeSessionsDirForRepo,
   buildSessionRecord,
+  clearWorktreeActivityCache,
   collectWorktreeChangedPaths,
   collectWorktreeTrackedPaths,
   deriveBlockingGitLabel,
@@ -798,7 +1099,13 @@ module.exports = {
   readWorktreeLockSessions,
   readRepoChanges,
   deriveRepoChangeStatus,
+  readAheadBehindCounts,
+  readConfiguredBaseBranch,
+  readLogTail,
   resolveWorktreeGitDir,
+  readSessionHeldLocks,
+  readSessionInspectData,
+  sessionLogPath,
   sanitizeBranchForFile,
   sessionFileNameForBranch,
   sessionFilePathForBranch,