@yemi33/minions 0.1.1622 → 0.1.1624

package/CHANGELOG.md

@@ -1,12 +1,21 @@
 # Changelog
 
-## 0.1.1622 (2026-04-29)
+## 0.1.1624 (2026-04-29)
 
 ### Features
-- harden action block parsing (#1863)
+- harden ADO repository polling (#1872)
+- resilient file-bug label preflight (#1840) (#1867)
+
+### Fixes
+- use elapsed time for PR pollers (#1870)
 
 ### Other
-- refactor: move stream-event handling into runtime adapters
+- test(dispatch): add unit tests for cancelPendingWorkItems, writeInboxAlert, cleanDispatchEntries (#1874)
+
+## 0.1.1621 (2026-04-29)
+
+### Features
+- harden action block parsing (#1863)
 
 ## 0.1.1620 (2026-04-29)
 

package/dashboard/js/command-center.js

@@ -1126,10 +1126,11 @@ async function ccExecuteAction(action, targetTabId) {
       case 'file-bug': {
         var res10 = await _ccFetch('/api/issues/create', { title: action.title, description: action.description, labels: action.labels });
         var d10 = await res10.json();
+        var labelWarning = d10.warning ? ' <span style="color:var(--orange)">(' + escHtml(d10.warning) + ')</span>' : '';
         if (d10.url) {
-          status.innerHTML = '&#128027; Bug filed: <a href="' + escHtml(d10.url) + '" target="_blank" style="color:var(--blue)">' + escHtml(action.title) + '</a>';
+          status.innerHTML = '&#128027; Bug filed: <a href="' + escHtml(d10.url) + '" target="_blank" style="color:var(--blue)">' + escHtml(action.title) + '</a>' + labelWarning;
         } else {
-          status.innerHTML = '&#128027; Bug filed: <strong>' + escHtml(action.title) + '</strong> — <a href="https://github.com/yemi33/minions/issues" target="_blank" style="color:var(--blue)">view issues</a>';
+          status.innerHTML = '&#128027; Bug filed: <strong>' + escHtml(action.title) + '</strong> — <a href="https://github.com/yemi33/minions/issues" target="_blank" style="color:var(--blue)">view issues</a>' + labelWarning;
         }
         status.style.color = 'var(--green)';
         break;

package/dashboard.js

@@ -23,6 +23,7 @@ const queries = require('./engine/queries');
 const teams = require('./engine/teams');
 const ado = require('./engine/ado');
 const gh = require('./engine/github');
+const issues = require('./engine/issues');
 const watchesMod = require('./engine/watches');
 const os = require('os');
 
@@ -4467,40 +4468,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     try {
       const body = await readBody(req);
       if (!body.title) return jsonReply(res, 400, { error: 'title required' });
-
-      // Check gh CLI is available
-      try { shared.exec('gh --version', { encoding: 'utf-8', timeout: 5000, windowsHide: true }); }
-      catch { return jsonReply(res, 500, { error: 'gh CLI not installed. Run: npm install -g gh' }); }
-
-      const repo = 'yemi33/minions';
-      const labels = (body.labels || ['bug']).join(',');
-      const bugBody = (body.description || '') + '\n\n---\n_Filed via Minions dashboard_';
-
-      // Write body to temp file to avoid shell escaping issues with quotes, backticks, newlines
-      const tmpBody = path.join(ENGINE_DIR, 'tmp', `bug-body-${Date.now()}.md`);
-      safeWrite(tmpBody, bugBody);
-      const safeTitle = body.title.replace(/["`$\\]/g, '');
-      try {
-        const cmd = `gh issue create --repo "${repo}" --title "${safeTitle}" --body-file "${tmpBody}" --label "${labels}" 2>&1`;
-        const result = shared.exec(cmd, { encoding: 'utf-8', timeout: 30000, windowsHide: true });
-        shared.safeUnlink(tmpBody);
-        // Detect gh errors in output
-        if (result.includes('authentication') || result.includes('auth login')) {
-          return jsonReply(res, 401, { error: 'GitHub auth required. Run: gh auth login' });
-        }
-        const urlMatch = result.match(/https:\/\/github\.com\/\S+/);
-        if (!urlMatch) {
-          return jsonReply(res, 500, { error: 'Issue may not have been created: ' + result.trim().slice(0, 200) });
-        }
-        return jsonReply(res, 200, { ok: true, url: urlMatch[0], output: result.trim() });
-      } catch (e) {
-        shared.safeUnlink(tmpBody);
-        throw e;
-      }
+      const result = issues.createGitHubIssue({
+        title: body.title,
+        description: body.description || '',
+        labels: body.labels,
+        repo: 'yemi33/minions',
+        tmpDir: path.join(ENGINE_DIR, 'tmp'),
+      });
+      return jsonReply(res, 200, result);
     } catch (e) {
-      const msg = e.message || '';
-      if (msg.includes('ENOENT') || msg.includes('not found')) return jsonReply(res, 500, { error: 'gh CLI not found. Install from https://cli.github.com/' });
-      return jsonReply(res, 500, { error: msg });
+      return jsonReply(res, e.statusCode || 500, { error: e.message || 'Issue creation failed' });
     }
   }
 

package/docs/auto-discovery.md

@@ -11,8 +11,8 @@ tick()
   1. checkTimeouts()            Kill stale/hung agents (>heartbeatTimeout)
   2. consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
   2.5 runCleanup()              Periodic cleanup (every 10 ticks ≈ 10min)
-  2.6 pollPrStatus()            Poll ADO + GitHub for build, review, merge status (every prPollStatusEvery ticks, default 12 ≈ 12min)
-  2.7 pollPrHumanComments()     Poll PR threads for human @minions comments (every prPollCommentsEvery ticks, default 12 ≈ 12min)
+  2.6 pollPrStatus()            Poll ADO + GitHub for build, review, merge status (wall-clock cadence from prPollStatusEvery × tickInterval, default ≈ 12min)
+  2.7 pollPrHumanComments()     Poll PR threads for human @minions comments (wall-clock cadence from prPollCommentsEvery × tickInterval, default ≈ 12min)
   3. discoverWork()             Scan ALL linked projects for new tasks
   4. updateSnapshot()           Write identity/now.md
   5. dispatch                   Spawn agents for pending items (up to maxConcurrent)
@@ -124,7 +124,7 @@ Both write to `work-items.json` and are picked up by Source 3 on the same or nex
 
 ## PR Status Polling (`pollPrStatus`)
 
-**Runs:** Every `prPollStatusEvery` ticks (default 12, ≈ 12 minutes), independently of work discovery. ADO polling lives in `engine/ado.js`; GitHub polling lives in `engine/github.js` — both run in parallel each cycle (`Promise.allSettled`) and write to the same per-project `pull-requests.json` schema. Replaces the retired agent-based `pr-sync`.
+**Runs:** On a wall-clock cadence derived from `prPollStatusEvery × engine.tickInterval` (default 12 × 60s, ≈ 12 minutes), independently of work discovery or file-change wakeups. ADO polling lives in `engine/ado.js`; GitHub polling lives in `engine/github.js` — both run in parallel each cycle (`Promise.allSettled`) and write to the same per-project `pull-requests.json` schema. Replaces the retired agent-based `pr-sync`.
 
 The engine directly polls the host REST API for **all** PR metadata: build/CI status, human review votes, and completion state. Two API calls per PR — no agent dispatch needed.
 

package/docs/design-state-storage.md

@@ -22,7 +22,7 @@ Minions persists all runtime state as flat JSON files guarded by file-lock-based
 | `engine/metrics.json` | 5 KB | Per-agent stats | R/W on PR approval/merge | Low | Low |
 | `engine/control.json` | 169 B | Single object | R/W on start/stop/heartbeat | Low | Low |
 | `projects/*/work-items.json` | 370 KB | 180 items | R/W every 1-2 ticks; dashboard reads on-demand | **High** — engine + lifecycle + dashboard | High |
-| `projects/*/pull-requests.json` | 241 KB | 128 PRs | R/W every `prPollStatusEvery` ticks (default 12, polling); lifecycle writes | Medium | Medium |
+| `projects/*/pull-requests.json` | 241 KB | 128 PRs | R/W on the `prPollStatusEvery × tickInterval` wall-clock cadence (default ≈12min); lifecycle writes | Medium | Medium |
 | `engine/pipeline-runs.json` | 36 KB | Pipeline state | R/W on pipeline execution | Low | Low |
 | `engine/schedule-runs.json` | 115 B | Last-run times | R every 10 ticks; W on schedule execution | Low | Low |
 
@@ -56,7 +56,7 @@ Key properties:
 | Engine tick cycle | ~15 | ~3 | Heavy read, selective write |
 | Dashboard (per page load) | ~8 | 0 | Read-only display |
 | Dashboard (user action) | ~2 | ~2 | Read-modify-write |
-| PR polling (every `prPollStatusEvery` ticks, default 12) | ~4 | ~2 | Batch read-modify-write |
+| PR polling (every `prPollStatusEvery × tickInterval`, default ≈12min) | ~4 | ~2 | Batch read-modify-write |
 | Consolidation (every 10 ticks) | ~3 | ~2 | Read inbox files, write notes.md |
 
 **Read:write ratio is approximately 8:1.** This strongly favors a system that can serve reads without locking (e.g., WAL mode).

package/docs/pr-review-fix-loop.md

@@ -71,7 +71,7 @@ When multiple problems coexist, earlier triggers get the first chance to enqueue
 
 ## 6. Re-review cycle
 
-- Poller (every `prPollStatusEvery` ticks, default ~12min): detects new commit (`head.sha` changed) → sets `lastPushedAt`
+- Poller (wall-clock cadence from `prPollStatusEvery × tickInterval`, default ~12min): detects new commit (`head.sha` changed) → sets `lastPushedAt`
 - Platform review state drives next action:
   - Reviewer approves → `approved` → done
   - Reviewer re-requests changes → `changes-requested` → triggers another fix

package/engine/ado.js

@@ -27,6 +27,24 @@ const getAdoPrUrl = (project, prNumber) => {
   return `https://dev.azure.com/${project.adoOrg}/${project.adoProject}/_git/${repoPath}/pullrequest/${prNumber}`;
 };
 
+function isGitHubProject(project) {
+  return String(project?.repoHost || '').toLowerCase() === 'github';
+}
+
+function getAdoRepositoryId(project) {
+  const repositoryId = String(project?.repositoryId || '').trim();
+  if (repositoryId) return repositoryId;
+  return String(project?.repoName || '').trim();
+}
+
+function getAdoProjectLabel(project) {
+  return project?.name || project?.repoName || `${project?.adoOrg || 'unknown-org'}/${project?.adoProject || 'unknown-project'}`;
+}
+
+function logMissingAdoRepository(project, purpose) {
+  log('error', `${purpose} disabled for project ${getAdoProjectLabel(project)}: missing project.repositoryId and project.repoName; configure one so Azure DevOps repository API calls can target the repo`);
+}
+
 // ── Build/Review Status Helpers ───────────────────────────────────────────────
 
 /** Classify an array of ADO build records into a single status string. */
@@ -238,7 +256,7 @@ async function fetchAdoBuildErrorLog(orgBase, project, failedStatus, token, pr,
 // ─── Shared PR Polling Loop ──────────────────────────────────────────────────
 
 /**
- * Iterate active PRs across all projects. Calls `callback(project, pr, prNum, orgBase)`
+ * Iterate active PRs across all projects. Calls `callback(project, pr, prNum, orgBase, adoRepositoryId)`
  * for each active PR. If callback returns truthy, the PR file is saved after the project loop.
  */
 async function forEachActivePr(config, token, callback) {
@@ -246,12 +264,19 @@ async function forEachActivePr(config, token, callback) {
   let totalUpdated = 0;
 
   for (const project of projects) {
-    if (!project.adoOrg || !project.adoProject || !project.repositoryId) continue;
+    if (isGitHubProject(project)) continue;
+    if (!project.adoOrg || !project.adoProject) continue;
 
     const prs = getPrs(project);
     const activePrs = prs.filter(pr => shared.PR_POLLABLE_STATUSES.has(pr.status));
     if (activePrs.length === 0) continue;
 
+    const adoRepositoryId = getAdoRepositoryId(project);
+    if (!adoRepositoryId) {
+      logMissingAdoRepository(project, 'ADO PR polling');
+      continue;
+    }
+
     let projectUpdated = 0;
     const orgBase = getAdoOrgBase(project);
 
@@ -262,7 +287,7 @@ async function forEachActivePr(config, token, callback) {
       const results = await Promise.allSettled(batch.map(async (pr) => {
         const prNum = shared.getPrNumber(pr);
         if (!prNum) return false;
-        return callback(project, pr, prNum, orgBase);
+        return callback(project, pr, prNum, orgBase, adoRepositoryId);
       }));
       for (const r of results) {
         if (r.status === 'fulfilled' && r.value) projectUpdated++;
@@ -275,7 +300,11 @@ async function forEachActivePr(config, token, callback) {
         // Merge back updated PRs — preserve disk values that may have been changed
         // by other writers between poll start and this write
         for (const updatedPr of activePrs) {
-          const idx = currentPrs.findIndex(p => p.id === updatedPr.id);
+          const updatedPrNumber = shared.getPrNumber(updatedPr);
+          const idx = currentPrs.findIndex(p =>
+            p.id === updatedPr.id
+            || (updatedPrNumber != null && shared.getPrNumber(p) === updatedPrNumber)
+          );
           if (idx >= 0) {
             // Never downgrade reviewStatus from 'approved' — it's a permanent terminal state
             // The disk version may have been set to 'approved' by another writer after we read
@@ -317,9 +346,10 @@ async function pollPrStatus(config) {
     return;
   }
 
-  const totalUpdated = await forEachActivePr(config, token, async (project, pr, prNum, orgBase) => {
+  const totalUpdated = await forEachActivePr(config, token, async (project, pr, prNum, orgBase, adoRepositoryId) => {
     try {
-    const repoBase = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}/pullrequests/${prNum}`;
+    const encodedRepoId = encodeURIComponent(adoRepositoryId);
+    const repoBase = `${orgBase}/${project.adoProject}/_apis/git/repositories/${encodedRepoId}/pullrequests/${prNum}`;
     let updated = false;
 
     // Clear stale flag — we're attempting a fresh poll
@@ -453,7 +483,7 @@ async function pollPrStatus(config) {
     if (prNumber && mergeCommitId) {
       try {
         const mergeRef = encodeURIComponent(`refs/pull/${prNumber}/merge`);
-        const buildsUrl = `${orgBase}/${project.adoProject}/_apis/build/builds?branchName=${mergeRef}&repositoryId=${project.repositoryId}&repositoryType=TfsGit&$top=25&api-version=7.1`;
+        const buildsUrl = `${orgBase}/${project.adoProject}/_apis/build/builds?branchName=${mergeRef}&repositoryId=${encodedRepoId}&repositoryType=TfsGit&$top=25&api-version=7.1`;
         const buildsData = await adoFetch(buildsUrl, token);
         const allBuilds = buildsData?.value || [];
         const prBuilds = allBuilds.filter(b => b.sourceVersion === mergeCommitId);
@@ -544,7 +574,7 @@ async function pollPrStatus(config) {
           const mergeStrategy = config.engine?.prMergeMethod === 'merge' ? 1 : config.engine?.prMergeMethod === 'rebase' ? 2 : 3; // 3 = squash
           const identityUrl = `${orgBase}/_apis/connectionData?api-version=7.1`;
           const identity = await adoFetch(identityUrl, token).catch(() => null);
-          const autoCompleteUrl = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}/pullrequests/${prNum}?api-version=7.1`;
+          const autoCompleteUrl = `${orgBase}/${project.adoProject}/_apis/git/repositories/${encodedRepoId}/pullrequests/${prNum}?api-version=7.1`;
           await adoFetch(autoCompleteUrl, token, {
             method: 'PATCH',
             body: JSON.stringify({
@@ -599,8 +629,8 @@ async function pollPrHumanComments(config) {
   const token = await getAdoToken();
   if (!token) return;
 
-  const totalUpdated = await forEachActivePr(config, token, async (project, pr, prNum, orgBase) => {
-    const threadsUrl = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}/pullrequests/${prNum}/threads?api-version=7.1`;
+  const totalUpdated = await forEachActivePr(config, token, async (project, pr, prNum, orgBase, adoRepositoryId) => {
+    const threadsUrl = `${orgBase}/${project.adoProject}/_apis/git/repositories/${encodeURIComponent(adoRepositoryId)}/pullrequests/${prNum}/threads?api-version=7.1`;
     const threadsData = await adoFetch(threadsUrl, token);
     const threads = threadsData.value || [];
 
@@ -698,10 +728,16 @@ async function reconcilePrs(config) {
   let totalAdded = 0;
 
   for (const project of projects) {
-    if (!project.adoOrg || !project.adoProject || !project.repositoryId) continue;
+    if (isGitHubProject(project)) continue;
+    if (!project.adoOrg || !project.adoProject) continue;
+    const adoRepositoryId = getAdoRepositoryId(project);
+    if (!adoRepositoryId) {
+      logMissingAdoRepository(project, 'ADO PR reconciliation');
+      continue;
+    }
 
     const orgBase = shared.getAdoOrgBase(project);
-    const url = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}/pullrequests?searchCriteria.status=active&api-version=7.1`;
+    const url = `${orgBase}/${project.adoProject}/_apis/git/repositories/${encodeURIComponent(adoRepositoryId)}/pullrequests?searchCriteria.status=active&api-version=7.1`;
 
     let prData;
     try {
@@ -829,7 +865,12 @@ async function checkLiveReviewStatus(pr, project) {
     const orgBase = shared.getAdoOrgBase(project);
     const prNum = shared.getPrNumber(pr);
     if (!prNum) return null;
-    const url = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}/pullrequests/${prNum}?api-version=7.1`;
+    const adoRepositoryId = getAdoRepositoryId(project);
+    if (!adoRepositoryId) {
+      logMissingAdoRepository(project, 'ADO live review check');
+      return null;
+    }
+    const url = `${orgBase}/${project.adoProject}/_apis/git/repositories/${encodeURIComponent(adoRepositoryId)}/pullrequests/${prNum}?api-version=7.1`;
     // SEC-02: use in-process adoFetch rather than a shell-out — keeps the bearer
     // token out of the process argv list where any local process could read it.
     // 4s timeout preserves the original request-cancellation semantics via AbortSignal.
@@ -868,7 +909,13 @@ async function checkLiveBuildAndConflict(pr, project) {
     const orgBase = shared.getAdoOrgBase(project);
     const prNum = shared.getPrNumber(pr);
     if (!prNum) return null;
-    const repoBase = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}`;
+    const adoRepositoryId = getAdoRepositoryId(project);
+    if (!adoRepositoryId) {
+      logMissingAdoRepository(project, 'ADO live build/conflict check');
+      return null;
+    }
+    const encodedRepoId = encodeURIComponent(adoRepositoryId);
+    const repoBase = `${orgBase}/${project.adoProject}/_apis/git/repositories/${encodedRepoId}`;
     const prUrl = `${repoBase}/pullrequests/${prNum}?api-version=7.1`;
     // 4s timeout — same budget as checkLiveReviewStatus. This is a pre-dispatch
     // gate; we'd rather miss a freshness signal and fall back to cache than
@@ -889,7 +936,7 @@ async function checkLiveBuildAndConflict(pr, project) {
       if (mergeCommitId) {
         try {
           const mergeRef = encodeURIComponent(`refs/pull/${prNum}/merge`);
-          const buildsUrl = `${orgBase}/${project.adoProject}/_apis/build/builds?branchName=${mergeRef}&repositoryId=${project.repositoryId}&repositoryType=TfsGit&$top=25&api-version=7.1`;
+          const buildsUrl = `${orgBase}/${project.adoProject}/_apis/build/builds?branchName=${mergeRef}&repositoryId=${encodedRepoId}&repositoryType=TfsGit&$top=25&api-version=7.1`;
           const buildsData = await adoFetch(buildsUrl, token, { timeout: 4000 });
           const allBuilds = buildsData?.value || [];
           const prBuilds = allBuilds.filter(b => b.sourceVersion === mergeCommitId);
@@ -940,9 +987,15 @@ async function fetchSinglePrBuildStatus(project, prNumber) {
   if (!token) return null;
 
   const orgBase = getAdoOrgBase(project);
-  const repoBase = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}`;
+  const adoRepositoryId = getAdoRepositoryId(project);
+  if (!adoRepositoryId) {
+    logMissingAdoRepository(project, 'ADO single PR status fetch');
+    return null;
+  }
+  const encodedRepoId = encodeURIComponent(adoRepositoryId);
+  const repoBase = `${orgBase}/${project.adoProject}/_apis/git/repositories/${encodedRepoId}`;
   const mergeRef = encodeURIComponent(`refs/pull/${prNumber}/merge`);
-  const buildsUrl = `${orgBase}/${project.adoProject}/_apis/build/builds?branchName=${mergeRef}&repositoryId=${project.repositoryId}&repositoryType=TfsGit&$top=25&api-version=7.1`;
+  const buildsUrl = `${orgBase}/${project.adoProject}/_apis/build/builds?branchName=${mergeRef}&repositoryId=${encodedRepoId}&repositoryType=TfsGit&$top=25&api-version=7.1`;
 
   // Fetch PR metadata and builds in parallel
   const [prData, buildsData] = await Promise.all([
@@ -1011,7 +1064,12 @@ const getAdoThrottleState = () => _adoThrottle.getState();
  * @returns {{ prNumber: number, url: string }|null}
  */
 async function findOpenPrOnBranch(project, branch) {
-  if (!project.adoOrg || !project.adoProject || !project.repositoryId || !branch) return null;
+  if (!project.adoOrg || !project.adoProject || !branch) return null;
+  const adoRepositoryId = getAdoRepositoryId(project);
+  if (!adoRepositoryId) {
+    logMissingAdoRepository(project, 'ADO branch PR lookup');
+    return null;
+  }
   if (isAdoThrottled()) {
     log('debug', `[ado] Skipping branch PR lookup for ${project.name || project.repoName || 'unknown project'}:${branch} — throttled`);
     return null;
@@ -1020,7 +1078,7 @@ async function findOpenPrOnBranch(project, branch) {
   if (!token) return null;
   const orgBase = shared.getAdoOrgBase(project);
   const sourceRef = encodeURIComponent(`refs/heads/${branch}`);
-  const url = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}/pullrequests?searchCriteria.status=active&searchCriteria.sourceRefName=${sourceRef}&api-version=7.1`;
+  const url = `${orgBase}/${project.adoProject}/_apis/git/repositories/${encodeURIComponent(adoRepositoryId)}/pullrequests?searchCriteria.status=active&searchCriteria.sourceRefName=${sourceRef}&api-version=7.1`;
   const data = await adoFetch(url, token);
   const pr = (data.value || [])[0];
   if (!pr) return null;

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-04-29T11:02:21.813Z"
+  "cachedAt": "2026-04-29T15:04:42.719Z"
 }

package/engine/dispatch.js

@@ -111,6 +111,17 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
     'invalid file path',
     'missing required',
     'validation failed',
+    'auth failure',
+    'authentication failed',
+    'authentication failure',
+    'unauthorized',
+    'invalid api key',
+    'please log in',
+    'budget-exceeded',
+    'budget exceeded',
+    'budget cap exceeded',
+    'max-budget-usd',
+    'cost limit',
   ];
   return !nonRetryable.some(s => r.includes(s));
 }

package/engine/issues.js

@@ -0,0 +1,206 @@
+/**
+ * engine/issues.js — GitHub issue creation helpers.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync: _execFileSync } = require('child_process');
+
+const DEFAULT_REPO = 'yemi33/minions';
+const DEFAULT_LABELS = ['bug'];
+
+class GitHubIssueError extends Error {
+  constructor(message, statusCode = 500) {
+    super(message);
+    this.name = 'GitHubIssueError';
+    this.statusCode = statusCode;
+  }
+}
+
+function normalizeLabels(labels, defaultLabels = DEFAULT_LABELS) {
+  let raw;
+  if (labels == null) raw = defaultLabels;
+  else if (Array.isArray(labels)) raw = labels;
+  else if (typeof labels === 'string') raw = labels.split(',');
+  else raw = [];
+
+  const seen = new Set();
+  const out = [];
+  for (const label of raw) {
+    const value = String(label || '').trim();
+    if (!value) continue;
+    const key = value.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(value);
+  }
+  return out;
+}
+
+function ghMessage(err) {
+  if (!err) return '';
+  return [err.message, err.stdout, err.stderr]
+    .filter(Boolean)
+    .map(String)
+    .join('\n');
+}
+
+function conciseGhMessage(errOrText) {
+  const text = typeof errOrText === 'string' ? errOrText : ghMessage(errOrText);
+  return text.replace(/\s+/g, ' ').trim().slice(0, 240);
+}
+
+function isAuthError(errOrText) {
+  return /(authentication|auth login|not authenticated|bad credentials|http 401|requires authentication)/i.test(
+    typeof errOrText === 'string' ? errOrText : ghMessage(errOrText)
+  );
+}
+
+function isLabelUnavailableError(errOrText) {
+  const msg = typeof errOrText === 'string' ? errOrText : ghMessage(errOrText);
+  return /label/i.test(msg) && /(not found|not exist|unavailable|invalid|could not add|could not resolve|does not exist)/i.test(msg);
+}
+
+function extractIssueUrl(output) {
+  const match = String(output || '').match(/https:\/\/github\.com\/\S+\/issues\/\d+/);
+  return match ? match[0] : null;
+}
+
+function runGh(execFileSync, args, timeout) {
+  return execFileSync('gh', args, {
+    encoding: 'utf8',
+    timeout,
+    windowsHide: true,
+  });
+}
+
+function listRepoLabels({ repo, execFileSync }) {
+  const output = runGh(execFileSync, ['label', 'list', '--repo', repo, '--json', 'name', '--limit', '1000'], 15000);
+  const parsed = JSON.parse(output || '[]');
+  if (!Array.isArray(parsed)) {
+    throw new GitHubIssueError('GitHub label list returned an unexpected response shape');
+  }
+  const labelsByLower = new Map();
+  for (const item of parsed) {
+    if (!item || typeof item.name !== 'string') continue;
+    labelsByLower.set(item.name.toLowerCase(), item.name);
+  }
+  return labelsByLower;
+}
+
+function resolveLabels({ labels, repo, execFileSync }) {
+  const requested = normalizeLabels(labels);
+  if (requested.length === 0) {
+    return { requested, labelsToApply: [], labelsSkipped: [], validationUnavailable: false };
+  }
+
+  try {
+    const available = listRepoLabels({ repo, execFileSync });
+    const labelsToApply = [];
+    const labelsSkipped = [];
+    for (const label of requested) {
+      const matched = available.get(label.toLowerCase());
+      if (matched) labelsToApply.push(matched);
+      else labelsSkipped.push(label);
+    }
+    return { requested, labelsToApply, labelsSkipped, validationUnavailable: false };
+  } catch (e) {
+    if (e instanceof GitHubIssueError) throw e;
+    if (isAuthError(e)) throw new GitHubIssueError('GitHub auth required. Run: gh auth login', 401);
+    return { requested, labelsToApply: requested, labelsSkipped: [], validationUnavailable: true };
+  }
+}
+
+function buildWarning(labelsSkipped, filedWithoutLabels) {
+  if (!labelsSkipped.length) return undefined;
+  const base = `Skipped unavailable GitHub label(s): ${labelsSkipped.join(', ')}.`;
+  return filedWithoutLabels ? `${base} Filed without labels.` : base;
+}
+
+function createIssueWithLabels({ title, bodyFile, repo, labels, execFileSync }) {
+  const args = ['issue', 'create', '--repo', repo, '--title', title, '--body-file', bodyFile];
+  if (labels.length > 0) args.push('--label', labels.join(','));
+  const output = runGh(execFileSync, args, 30000);
+  const url = extractIssueUrl(output);
+  if (!url) {
+    throw new GitHubIssueError(`Issue may not have been created: ${conciseGhMessage(output)}`);
+  }
+  return { url, output: String(output || '').trim() };
+}
+
+function createGitHubIssue({
+  title,
+  description = '',
+  labels,
+  repo = DEFAULT_REPO,
+  tmpDir,
+  execFileSync = _execFileSync,
+} = {}) {
+  if (!title) throw new GitHubIssueError('title required', 400);
+
+  try {
+    runGh(execFileSync, ['--version'], 5000);
+  } catch (e) {
+    throw new GitHubIssueError('gh CLI not found. Install from https://cli.github.com/');
+  }
+
+  const issueBody = `${description || ''}\n\n---\n_Filed via Minions dashboard_`;
+  const dir = tmpDir || path.join(__dirname, 'tmp');
+  fs.mkdirSync(dir, { recursive: true });
+  const bodyFile = path.join(dir, `bug-body-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.md`);
+  fs.writeFileSync(bodyFile, issueBody);
+
+  let resolved;
+  try {
+    resolved = resolveLabels({ labels, repo, execFileSync });
+    const created = createIssueWithLabels({
+      title,
+      bodyFile,
+      repo,
+      labels: resolved.labelsToApply,
+      execFileSync,
+    });
+    const filedWithoutLabels = resolved.requested.length > 0 && resolved.labelsToApply.length === 0;
+    return {
+      ok: true,
+      url: created.url,
+      output: created.output,
+      labelsRequested: resolved.requested,
+      labelsApplied: resolved.labelsToApply,
+      labelsSkipped: resolved.labelsSkipped,
+      warning: buildWarning(resolved.labelsSkipped, filedWithoutLabels),
+    };
+  } catch (e) {
+    if (e instanceof GitHubIssueError) throw e;
+    if (isAuthError(e)) throw new GitHubIssueError('GitHub auth required. Run: gh auth login', 401);
+    if (resolved && resolved.labelsToApply.length > 0 && isLabelUnavailableError(e)) {
+      try {
+        const created = createIssueWithLabels({ title, bodyFile, repo, labels: [], execFileSync });
+        const skipped = normalizeLabels([...resolved.labelsSkipped, ...resolved.labelsToApply], []);
+        return {
+          ok: true,
+          url: created.url,
+          output: created.output,
+          labelsRequested: resolved.requested,
+          labelsApplied: [],
+          labelsSkipped: skipped,
+          warning: buildWarning(skipped, true),
+        };
+      } catch (retryErr) {
+        if (isAuthError(retryErr)) throw new GitHubIssueError('GitHub auth required. Run: gh auth login', 401);
+        throw new GitHubIssueError(`GitHub issue creation failed after retrying without labels: ${conciseGhMessage(retryErr)}`);
+      }
+    }
+    throw new GitHubIssueError(`GitHub issue creation failed: ${conciseGhMessage(e)}`);
+  } finally {
+    try { fs.unlinkSync(bodyFile); } catch {}
+  }
+}
+
+module.exports = {
+  DEFAULT_LABELS,
+  GitHubIssueError,
+  normalizeLabels,
+  isLabelUnavailableError,
+  createGitHubIssue,
+};

package/engine.js

@@ -3337,11 +3337,30 @@ let tickCount = 0;
 // In-memory cache of plan filenames confirmed completed — avoids redundant
 // checkPlanCompletion calls.  Cleared automatically on engine restart.
 const completedPlanCache = new Set();
+let lastWatchCheckAt = 0;
+let lastPrStatusPollAt = 0;
+let lastPrCommentsPollAt = 0;
 
 let tickRunning = false;
 let _tickStartedAt = 0;
 const TICK_TIMEOUT_MS = 300000; // 5 min — force-release tick lock if stuck
 
+function _pollIntervalMsFromTicks(ticks, tickIntervalMs) {
+  const normalizedTicks = Math.max(1, Number(ticks) || 1);
+  const normalizedTickInterval = Math.max(1, Number(tickIntervalMs) || ENGINE_DEFAULTS.tickInterval);
+  return normalizedTicks * normalizedTickInterval;
+}
+
+function _shouldRunPeriodicPhase(now, lastRunAt, intervalMs) {
+  const current = Number(now);
+  const previous = Number(lastRunAt) || 0;
+  const interval = Math.max(1, Number(intervalMs) || 1);
+  if (!Number.isFinite(current)) return false;
+  if (!previous || !Number.isFinite(previous)) return true;
+  if (current < previous) return true;
+  return current - previous >= interval;
+}
+
 async function tick() {
   if (tickRunning) {
     if (_tickStartedAt && Date.now() - _tickStartedAt > TICK_TIMEOUT_MS) {
@@ -3375,6 +3394,8 @@ async function tickInner() {
 
   const config = getConfig();
   tickCount++;
+  const now = Date.now();
+  const tickIntervalMs = Math.max(1, Number(config.engine?.tickInterval) || ENGINE_DEFAULTS.tickInterval);
   _failedRefCache.clear(); // Reset per-tick failed-ref cache
 
   // Helper: run a phase, log + continue on error
@@ -3402,8 +3423,10 @@ async function tickInner() {
     safe('runCleanup', () => runCleanup(config));
   }
 
-  // 2.55. Check persistent watches (every 3 ticks = ~3 minutes)
-  if (tickCount % 3 === 0) {
+  // 2.55. Check persistent watches (3 tick-equivalents, default ~3 minutes)
+  const watchPollIntervalMs = _pollIntervalMsFromTicks(3, tickIntervalMs);
+  if (_shouldRunPeriodicPhase(now, lastWatchCheckAt, watchPollIntervalMs)) {
+    lastWatchCheckAt = now;
     safe('checkWatches', () => {
       const { checkWatches } = require('./engine/watches');
       const projects = getProjects(config);
@@ -3432,10 +3455,14 @@ async function tickInner() {
     Number(config.engine?.prPollCommentsEvery ?? config.engine?.adoPollCommentsEvery) || ENGINE_DEFAULTS.prPollCommentsEvery
   );
 
-  // 2.6. Poll PR status: build, review, merge (every prPollStatusEvery ticks, default ~12 minutes)
+  // 2.6. Poll PR status: build, review, merge (every prPollStatusEvery tick-equivalents, default ~12 minutes)
   // Awaited so PR state is consistent before discoverWork reads it
   // Also re-polls early if previous tick had ADO auth failures (stale build status recovery)
-  if (tickCount % prPollStatusEvery === 0 || needsAdoPollRetry()) {
+  const prPollStatusIntervalMs = _pollIntervalMsFromTicks(prPollStatusEvery, tickIntervalMs);
+  const prStatusPollDue = _shouldRunPeriodicPhase(now, lastPrStatusPollAt, prPollStatusIntervalMs);
+  const adoPollRetryDue = needsAdoPollRetry();
+  if (prStatusPollDue || adoPollRetryDue) {
+    lastPrStatusPollAt = now;
     // Build promise array — enabled+unthrottled polls run concurrently via Promise.allSettled
     const statusPolls = [];
     if (adoPollEnabled && !isAdoThrottled()) {
@@ -3475,8 +3502,11 @@ async function tickInner() {
     } catch (err) { log('warn', `Plan completion check error: ${err?.message || err}`); }
   }
 
-  // 2.7. Poll PR threads for human comments (every prPollCommentsEvery ticks, default ~12 minutes)
-  if (tickCount % prPollCommentsEvery === 0) {
+  const prPollCommentsIntervalMs = _pollIntervalMsFromTicks(prPollCommentsEvery, tickIntervalMs);
+
+  // 2.7. Poll PR threads for human comments (every prPollCommentsEvery tick-equivalents, default ~12 minutes)
+  if (_shouldRunPeriodicPhase(now, lastPrCommentsPollAt, prPollCommentsIntervalMs)) {
+    lastPrCommentsPollAt = now;
     // Build promise array — enabled+unthrottled comment polls run concurrently via Promise.allSettled
     const commentPolls = [];
     if (adoPollEnabled && !isAdoThrottled()) {
@@ -3923,6 +3953,7 @@ module.exports = {
 
   // Tick
   tick,
+  _pollIntervalMsFromTicks, _shouldRunPeriodicPhase, // exported for testing
 };
 
 // ─── Entrypoint ─────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1622",
+  "version": "0.1.1624",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"