@yemi33/minions 0.1.1810 → 0.1.1812

package/engine/cli.js

@@ -1157,11 +1157,14 @@ const commands = {
     }
 
     const config = getConfig();
-    const { getProjects, projectWorkItemsPath } = require('./shared');
+    const { getProjects, projectWorkItemsPath, resolveProjectSource } = require('./shared');
     const projects = getProjects(config);
-    const targetProject = opts.project
-      ? projects.find(p => p.name?.toLowerCase() === opts.project?.toLowerCase()) || projects[0]
-      : projects[0];
+    const target = opts.project ? resolveProjectSource(opts.project, projects, { allowCentral: false }) : null;
+    if (target?.error) {
+      console.log(target.error);
+      return;
+    }
+    const targetProject = target?.project || projects[0];
     const wiPath = projectWorkItemsPath(targetProject);
     let item;
     mutateWorkItems(wiPath, items => {
@@ -1202,11 +1205,14 @@ const commands = {
     }
 
     const config = getConfig();
-    const { getProjects } = require('./shared');
+    const { getProjects, resolveProjectSource } = require('./shared');
     const projects = getProjects(config);
-    const targetProject = projectName
-      ? projects.find(p => p.name?.toLowerCase() === projectName.toLowerCase()) || projects[0]
-      : projects[0];
+    const target = projectName ? resolveProjectSource(projectName, projects, { allowCentral: false }) : null;
+    if (target?.error) {
+      console.log(target.error);
+      return;
+    }
+    const targetProject = target?.project || projects[0];
 
     if (!targetProject) {
       console.log('No projects configured. Run: minions add <dir>');
@@ -1395,7 +1401,7 @@ const commands = {
           const wiPath = (item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout')
             ? path.join(MINIONS_DIR, 'work-items.json')
             : item.meta.project?.localPath
-              ? shared.projectWorkItemsPath({ localPath: item.meta.project.localPath, name: item.meta.project.name, workSources: config.projects?.find(p => p.name === item.meta.project.name)?.workSources })
+              ? shared.projectWorkItemsPath(shared.resolveProjectSource(item.meta.project, config.projects || [], { allowCentral: false }).project || item.meta.project)
               : null;
           if (wiPath) {
             mutateWorkItems(wiPath, items => {

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-09T01:00:53.065Z"
+  "cachedAt": "2026-05-09T08:52:32.908Z"
 }

package/engine/dispatch.js

@@ -79,7 +79,8 @@ function mutateDispatch(mutator) {
 
 function getDispatchProjectKey(project) {
   if (!project) return '';
-  return project.name || (project.localPath ? path.resolve(project.localPath).toLowerCase() : '');
+  if (project.name) return String(project.name).toLowerCase();
+  return project.localPath ? path.resolve(project.localPath).toLowerCase() : '';
 }
 
 function getPrDispatchTargetKey(entry) {
@@ -176,15 +177,8 @@ function addToDispatch(item) {
 function _resolveDispatchProject(projectRef, config) {
   if (!projectRef) return null;
   const projects = getProjects(config);
-  if (projectRef.name) {
-    const byName = projects.find(p => p.name === projectRef.name);
-    if (byName) return byName;
-  }
-  if (projectRef.localPath) {
-    const refPath = path.resolve(projectRef.localPath);
-    const byPath = projects.find(p => p.localPath && path.resolve(p.localPath) === refPath);
-    if (byPath) return byPath;
-  }
+  const resolved = shared.resolveProjectSource(projectRef, projects, { allowCentral: false });
+  if (resolved.project) return resolved.project;
   return projectRef;
 }
 

package/engine/issues.js

@@ -9,6 +9,7 @@ const shared = require('./shared');
 
 const DEFAULT_REPO = 'yemi33/minions';
 const DEFAULT_LABELS = ['bug'];
+const WRITABLE_REPO_PERMISSIONS = new Set(['WRITE', 'MAINTAIN', 'ADMIN']);
 
 class GitHubIssueError extends Error {
   constructor(message, statusCode = 500) {
@@ -67,16 +68,105 @@ function extractIssueUrl(output) {
   return match ? match[0] : null;
 }
 
-function runGh(execFileSync, args, timeout) {
-  return execFileSync('gh', args, {
+function runGh(execFileSync, args, timeout, { env } = {}) {
+  const opts = {
     encoding: 'utf8',
     timeout,
     windowsHide: true,
-  });
+  };
+  if (env) opts.env = { ...process.env, ...env };
+  return execFileSync('gh', args, opts);
+}
+
+function isWritableRepoPermission(permission) {
+  return WRITABLE_REPO_PERMISSIONS.has(String(permission || '').trim().toUpperCase());
+}
+
+function repoViewerPermission({ repo, execFileSync, ghEnv }) {
+  const output = runGh(execFileSync, ['repo', 'view', repo, '--json', 'viewerPermission'], 10000, { env: ghEnv });
+  const parsed = JSON.parse(output || '{}');
+  return String(parsed.viewerPermission || '').trim().toUpperCase();
+}
+
+function parseGhAuthUsers(output) {
+  const users = [];
+  const seen = new Set();
+  for (const line of String(output || '').split(/\r?\n/)) {
+    const match = line.match(/\baccount\s+([^\s()]+)/i) || line.match(/\bas\s+([^\s()]+)/i);
+    if (!match) continue;
+    const user = match[1].trim();
+    const key = user.toLowerCase();
+    if (!user || seen.has(key)) continue;
+    seen.add(key);
+    users.push(user);
+  }
+  return users;
+}
+
+function listAuthenticatedGhUsers({ execFileSync }) {
+  const output = runGh(execFileSync, ['auth', 'status', '--hostname', 'github.com'], 10000);
+  return parseGhAuthUsers(output);
+}
+
+function ghTokenForUser({ user, execFileSync }) {
+  return String(runGh(execFileSync, ['auth', 'token', '--hostname', 'github.com', '--user', user], 10000) || '').trim();
+}
+
+function resolveWritableGitHubEnv({ repo, execFileSync }) {
+  let activePermission = '';
+  let activeError = null;
+  try {
+    activePermission = repoViewerPermission({ repo, execFileSync });
+    if (isWritableRepoPermission(activePermission)) return undefined;
+  } catch (e) {
+    activeError = e;
+  }
+
+  let users = [];
+  let accountListError = null;
+  try {
+    users = listAuthenticatedGhUsers({ execFileSync });
+  } catch (e) {
+    if (activeError && isAuthError(activeError) && isAuthError(e)) {
+      throw new GitHubIssueError('GitHub auth required. Run: gh auth login', 401);
+    }
+    accountListError = e;
+  }
+
+  const candidateErrors = [];
+  for (const user of users) {
+    try {
+      const token = ghTokenForUser({ user, execFileSync });
+      if (!token) continue;
+      const ghEnv = { GH_TOKEN: token };
+      const permission = repoViewerPermission({ repo, execFileSync, ghEnv });
+      if (isWritableRepoPermission(permission)) return ghEnv;
+    } catch (e) {
+      candidateErrors.push(`${user}: ${conciseGhMessage(e)}`);
+    }
+  }
+
+  const activeDetail = activePermission
+    ? ` Active account permission is ${activePermission}.`
+    : activeError
+      ? ` Active account permission could not be checked: ${conciseGhMessage(activeError)}.`
+      : '';
+  const authStatusDetail = accountListError
+    ? ` Authenticated accounts could not be listed: ${conciseGhMessage(accountListError)}.`
+    : '';
+  const candidateDetail = candidateErrors.length
+    ? ` Checked ${candidateErrors.length} authenticated account(s) without finding write access.`
+    : '';
+  throw new GitHubIssueError(
+    `No authenticated GitHub account with write access to ${repo}.${activeDetail} ` +
+      `${authStatusDetail}${candidateDetail} ` +
+      `Run: gh auth login --hostname github.com with a profile that can write to ${repo}, or set GH_TOKEN for that account.`,
+    403
+  );
 }
 
-function listRepoLabels({ repo, execFileSync }) {
-  const output = runGh(execFileSync, ['label', 'list', '--repo', repo, '--json', 'name', '--limit', '1000'], 15000);
+function listRepoLabels({ repo, execFileSync, ghEnv }) {
+  const output = runGh(execFileSync, ['label', 'list', '--repo', repo, '--json', 'name', '--limit', '1000'], 15000, { env: ghEnv });
   const parsed = JSON.parse(output || '[]');
   if (!Array.isArray(parsed)) {
     throw new GitHubIssueError('GitHub label list returned an unexpected response shape');
@@ -89,14 +179,14 @@ function listRepoLabels({ repo, execFileSync }) {
   return labelsByLower;
 }
 
-function resolveLabels({ labels, repo, execFileSync }) {
+function resolveLabels({ labels, repo, execFileSync, ghEnv }) {
   const requested = normalizeLabels(labels);
   if (requested.length === 0) {
     return { requested, labelsToApply: [], labelsSkipped: [], validationUnavailable: false };
   }
 
   try {
-    const available = listRepoLabels({ repo, execFileSync });
+    const available = listRepoLabels({ repo, execFileSync, ghEnv });
     const labelsToApply = [];
     const labelsSkipped = [];
     for (const label of requested) {
@@ -175,10 +265,10 @@ function _redactIssueContent(value, { repo, projects } = {}) {
   });
 }
 
-function createIssueWithLabels({ title, bodyFile, repo, labels, execFileSync }) {
+function createIssueWithLabels({ title, bodyFile, repo, labels, execFileSync, ghEnv }) {
   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 output = runGh(execFileSync, args, 30000, { env: ghEnv });
   const url = extractIssueUrl(output);
   if (!url) {
     throw new GitHubIssueError(`Issue may not have been created: ${conciseGhMessage(output)}`);
@@ -202,6 +292,7 @@ function createGitHubIssue({
   } catch (e) {
     throw new GitHubIssueError('gh CLI not found. Install from https://cli.github.com/');
   }
+  const ghEnv = resolveWritableGitHubEnv({ repo, execFileSync });
 
   const redactionProjects = projects || shared.getProjects();
   const safeTitle = _redactIssueContent(title, { repo, projects: redactionProjects });
@@ -214,13 +305,14 @@ function createGitHubIssue({
 
   let resolved;
   try {
-    resolved = resolveLabels({ labels, repo, execFileSync });
+    resolved = resolveLabels({ labels, repo, execFileSync, ghEnv });
     const created = createIssueWithLabels({
       title: safeTitle,
       bodyFile,
       repo,
       labels: resolved.labelsToApply,
       execFileSync,
+      ghEnv,
     });
     const filedWithoutLabels = resolved.requested.length > 0 && resolved.labelsToApply.length === 0;
     return {
@@ -237,7 +329,7 @@ function createGitHubIssue({
     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: safeTitle, bodyFile, repo, labels: [], execFileSync });
+        const created = createIssueWithLabels({ title: safeTitle, bodyFile, repo, labels: [], execFileSync, ghEnv });
         const skipped = normalizeLabels([...resolved.labelsSkipped, ...resolved.labelsToApply], []);
         return {
           ok: true,

package/engine/lifecycle.js

@@ -160,7 +160,8 @@ function checkPlanCompletion(meta, config) {
   // Resolve the primary project for writing new work items (PR, verify)
   const projectName = plan.project;
   const primaryProject = projectName
-    ? projects.find(p => p.name?.toLowerCase() === projectName?.toLowerCase()) : projects[0];
+    ? shared.resolveProjectSource(projectName, projects, { allowCentral: false }).project
+    : (projects.length === 1 ? projects[0] : null);
   if (!primaryProject) {
     log('warn', `Plan ${planFile}: no primary project found — skipping PR/verify creation`);
     return;
@@ -196,9 +197,8 @@ function checkPlanCompletion(meta, config) {
     log('info', `Plan ${planFile}: verify WI ${existingVerify.id} already ${existingVerify.status} — skipping`);
   } else if (isReopenableVerify(existingVerify) && doneItems.length > 0) {
     const verifyProject = existingVerify.project || projectName;
-    const vWiPath = shared.projectWorkItemsPath(
-      projects.find(p => p.name?.toLowerCase() === verifyProject?.toLowerCase()) || primaryProject
-    );
+    const vProject = shared.resolveProjectSource(verifyProject, projects, { allowCentral: false }).project || primaryProject;
+    const vWiPath = shared.projectWorkItemsPath(vProject);
     let reopenedVerify = false;
     mutateWorkItems(vWiPath, items => {
       const v = items.find(w => w.id === existingVerify.id);
@@ -777,7 +777,8 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
 
   const projects = shared.getProjects(config);
   if (projects.length === 0 && !meta?.project?.name) return 0;
-  const defaultProject = (meta?.project?.name && projects.find(p => p.name === meta.project.name)) || projects[0];
+  const defaultProject = (meta?.project?.name && shared.resolveProjectSource(meta.project.name, projects, { allowCentral: false }).project) ||
+    (projects.length === 1 ? projects[0] : null);
   const useCentral = !defaultProject;
 
   // Match each PR to its correct project by finding which repo URL appears near the PR number in output
@@ -950,16 +951,15 @@ function hasCanonicalPrAttachment(itemId, config) {
 function resolvePrFallbackProject(meta, config) {
   const projects = shared.getProjects(config);
   if (meta?.project?.name) {
-    const match = projects.find(p => p.name === meta.project.name);
+    const match = shared.resolveProjectSource(meta.project.name, projects, { allowCentral: false }).project;
     if (match) return match;
   }
   if (meta?.project?.localPath) {
-    const metaPath = path.resolve(meta.project.localPath);
-    const match = projects.find(p => p.localPath && path.resolve(p.localPath) === metaPath);
+    const match = shared.resolveProjectSource(meta.project.localPath, projects, { allowCentral: false }).project;
     if (match) return match;
   }
   if (meta?.item?.project) {
-    const match = projects.find(p => p.name === meta.item.project);
+    const match = shared.resolveProjectSource(meta.item.project, projects, { allowCentral: false }).project;
     if (match) return match;
   }
   return projects.length === 1 ? projects[0] : null;
@@ -1813,7 +1813,7 @@ async function processPendingRebases(config) {
   for (const entry of snapshot) {
     if (isBranchActive(entry.branch)) { remaining.push(entry); continue; }
 
-    const project = shared.getProjects(config).find(p => p.name === entry.projectName);
+    const project = shared.resolveProjectSource(entry.projectName, shared.getProjects(config), { allowCentral: false }).project;
     if (!project) continue;
 
     const prs = getPrs(project);
@@ -2037,7 +2037,7 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeN
     if (!m('created')) enrichedBlock = enrichedBlock.replace('---\n', `---\ncreated: ${dateStamp()}\n`);
     const skillDirName = name.replace(/[^a-z0-9-]/g, '-');
     if (scope === 'project' && project) {
-      const proj = shared.getProjects(config).find(p => p.name === project);
+      const proj = shared.resolveProjectSource(project, shared.getProjects(config), { allowCentral: false }).project;
       if (proj) {
         const projectSkillRoot = skillWriteTargets(effectiveRuntime, proj).project
           || path.resolve(proj.localPath, '.claude', 'skills');

package/engine/pipeline.js

@@ -205,19 +205,26 @@ function _pipelineProjectValues(...values) {
   for (const value of values) {
     if (value === undefined) continue;
     if (Array.isArray(value)) out.push(...value);
+    else if (value && typeof value === 'object' && value.project !== undefined) out.push(value.project);
+    else if (value && typeof value === 'object' && value._project !== undefined) out.push(value._project);
     else out.push(value);
   }
   return out;
 }
 
-function _resolvePipelineProjects(values, config) {
+function _pipelineProjectValuePresent(value) {
+  if (value === undefined) return false;
+  if (value === null) return true;
+  if (typeof value === 'string') return value.trim() !== '';
+  return true;
+}
+
+function _resolvePipelineProjectValues(rawValues, config) {
   const projects = shared.getProjects(config);
-  const rawValues = _pipelineProjectValues(...values);
-  if (rawValues.length === 0) return { projects: [null] };
   const resolved = [];
   const seen = new Set();
   for (const raw of rawValues) {
-    if (raw === undefined) continue;
+    if (!_pipelineProjectValuePresent(raw)) continue;
     if (raw === null || String(raw).trim().toLowerCase() === 'central') {
       if (!seen.has('central')) { seen.add('central'); resolved.push(null); }
       continue;
@@ -230,6 +237,16 @@ function _resolvePipelineProjects(values, config) {
   return { projects: resolved.length ? resolved : [null] };
 }
 
+function _resolvePipelineProjects(scopes, config) {
+  for (const scope of (Array.isArray(scopes) ? scopes : [scopes])) {
+    const values = _pipelineProjectValues(...(Array.isArray(scope) ? scope : [scope]))
+      .filter(_pipelineProjectValuePresent);
+    if (values.length === 0) continue;
+    return _resolvePipelineProjectValues(values, config);
+  }
+  return { projects: [null] };
+}
+
 function _pipelineProjectSlug(project) {
   return project ? shared.safeSlugComponent(project.name || 'project', 32).toLowerCase() : 'central';
 }
@@ -339,12 +356,9 @@ function executeTaskStage(stage, stageState, run, config, pipeline = {}) {
   for (let i = 0; i < count; i++) {
     const item = items[i % items.length];
     const projectResolution = _resolvePipelineProjects([
-      item.projects,
-      item.project,
-      stage.projects,
-      stage.project,
-      pipeline.projects,
-      pipeline.project,
+      [item.projects, item.project],
+      [stage.projects, stage.project],
+      [pipeline.projects, pipeline.project],
     ], config);
     if (projectResolution.error) return { status: PIPELINE_STATUS.FAILED, error: projectResolution.error };
     for (const project of projectResolution.projects) {
@@ -376,7 +390,10 @@ function executeTaskStage(stage, stageState, run, config, pipeline = {}) {
       touchedProjects.push(project?.name || null);
     }
   }
-  return { status: PIPELINE_STATUS.RUNNING, artifacts: { workItems: [...new Set(createdIds)], projects: [...new Set(touchedProjects)] } };
+  const projects = [...new Set(touchedProjects)];
+  const artifacts = { workItems: [...new Set(createdIds)] };
+  if (projects.some(Boolean)) artifacts.projects = projects;
+  return { status: PIPELINE_STATUS.RUNNING, artifacts };
 }
 
 function executeTaskStageLegacy(stage, stageState, run, config) {
@@ -488,7 +505,10 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
   if (!fs.existsSync(plansDir)) fs.mkdirSync(plansDir, { recursive: true });
 
   const slug = slugify(stage.title || 'pipeline-plan');
-  const projectResolution = _resolvePipelineProjects([stage.projects, stage.project, pipeline.projects, pipeline.project], config);
+  const projectResolution = _resolvePipelineProjects([
+    [stage.projects, stage.project],
+    [pipeline.projects, pipeline.project],
+  ], config);
   if (projectResolution.error) return { status: PIPELINE_STATUS.FAILED, error: projectResolution.error };
   const targetProjects = projectResolution.projects;
   const wiIdForProject = (project) => `PL-${run.runId.slice(4, 12)}-${stage.id}-prd${targetProjects.length > 1 || project ? '-' + _pipelineProjectSlug(project) : ''}`;
@@ -1093,6 +1113,7 @@ module.exports = {
   getPipelineRuns, getActiveRun, startRun, updateRunStage, completeRun,
   discoverPipelineWork,
   evaluateCondition, // exported for testing
-  executeTaskStage, isStageComplete, resolveTemplate, // exported for testing
+  executeTaskStage, executePlanStage, isStageComplete, resolveTemplate, // exported for testing
+  _resolvePipelineProjects, // exported for testing
   _findMeetingsInRun, _findExistingPlanForMeeting, _findExistingPrdForPlan, // exported for testing
 };

package/engine/projects.js

@@ -66,7 +66,7 @@ function removeProject(target, options = {}) {
   // 1. Cancel pending/queued work items linked to this project (project-local
   //    file + central). Done items are preserved as history.
   summary.cancelledItems += dispatch.cancelPendingWorkItems(
-    path.join(MINIONS_DIR, 'projects', project.name, 'work-items.json'),
+    shared.projectWorkItemsPath(project),
     () => true,
     'project-removed',
   );
@@ -103,7 +103,7 @@ function removeProject(target, options = {}) {
   //    specifically. Don't touch schedules with project='any' or unset.
   if (Array.isArray(config.schedules)) {
     for (const s of config.schedules) {
-      if (s.project === project.name && s.enabled !== false) {
+      if (shared.resolveProjectSource(s.project, [project], { allowCentral: false }).project && s.enabled !== false) {
         s.enabled = false;
         summary.disabledSchedules++;
       }
@@ -164,20 +164,20 @@ function removeProject(target, options = {}) {
         ...(p.monitoredResources || []),
         ...((p.stages || []).flatMap(s => s.monitoredResources || [])),
       ];
-      if (refs.some(r => r && (r.project === project.name || r._project === project.name))) {
+      if (refs.some(r => r && shared.resolveProjectSource(r.project || r._project, [project], { allowCentral: false }).project)) {
         summary.pipelineRefs.push(p.id);
       }
     }
   } catch { /* pipelines optional */ }
 
   // 7. Remove from config.json (and persist any schedule disables)
-  config.projects = (config.projects || []).filter(p => p.name !== project.name);
+  config.projects = (config.projects || []).filter(p => !shared.resolveProjectSource(p, [project], { allowCentral: false }).project);
   try { fs.writeFileSync(configPath, JSON.stringify(config, null, 2)); }
   catch (e) { return { ...summary, error: 'Failed to write config: ' + e.message }; }
 
   // 8. Move (or purge) projects/<name>/ — preserves PR/work-item history by
   //    default so a re-add can pick up where it left off.
-  const dataDir = path.join(MINIONS_DIR, 'projects', project.name);
+  const dataDir = shared.projectStateDir(project);
   if (fs.existsSync(dataDir)) {
     if (dataMode === 'purge') {
       try { fs.rmSync(dataDir, { recursive: true, force: true }); summary.purgedDataDir = true; }

package/engine/queries.js

@@ -703,7 +703,7 @@ function buildPrUrlFromId(prId, pr, projects) {
       }
     }
   }
-  const project = pr?._project ? projects.find(p => p.name === pr._project) : null;
+  const project = pr?._project ? shared.resolveProjectSource(pr._project, projects, { allowCentral: false }).project : null;
   const prNumber = shared.getPrNumber(pr || prId);
   if (project?.prUrlBase && prNumber != null) return project.prUrlBase + prNumber;
   return '';
@@ -1179,7 +1179,7 @@ function getWorkItems(config) {
   const allPrs = getPullRequests(config);
   for (const item of allItems) {
     if (item._pr && !item._prUrl) {
-      const project = projects.find(p => p.name === item.project || p.name === item._source) || null;
+      const project = shared.resolveProjectSource(item.project || item._source, projects, { allowCentral: false }).project || null;
       const canonicalPrId = shared.getCanonicalPrId(project, item._pr);
       const displayPrId = shared.getPrDisplayId(item._pr);
       const exactPr = allPrs.find(p => p.id === canonicalPrId);
@@ -1418,7 +1418,7 @@ function getPrdInfo(config) {
   // Fallback: work item _pr field for anything still missing
   for (const wi of Object.values(wiById)) {
     if (!wi._pr || prdToPr[wi.id]?.length) continue;
-    const project = projects.find(p => p.name === wi.project || p.name === wi._source) || null;
+    const project = shared.resolveProjectSource(wi.project || wi._source, projects, { allowCentral: false }).project || null;
     const canonicalPrId = shared.getCanonicalPrId(project, wi._pr);
     const exactPr = prById[canonicalPrId] || null;
     const displayMatches = exactPr ? [] : Object.values(prById).filter(candidate => shared.getPrDisplayId(candidate) === shared.getPrDisplayId(wi._pr));

package/engine/shared.js

@@ -1725,7 +1725,7 @@ function findProjectByName(projects, projectName) {
 function findProjectByNameOrPath(projects, target) {
   const value = String(target || '').trim();
   if (!value) return null;
-  return findProjectByName(projects, value) || (projects || []).find(p => p?.localPath && sameResolvedPath(p.localPath, value)) || null;
+  return resolveProjectSource(value, projects, { allowCentral: false }).project || null;
 }
 
 function resolveConfiguredProject(projectName, projectsOrConfig, options = {}) {
@@ -1746,6 +1746,117 @@ function resolveConfiguredProject(projectName, projectsOrConfig, options = {}) {
   return { project: null, explicit: false, value: '' };
 }
 
+function centralWorkItemsPath(minionsDir = MINIONS_DIR) {
+  return path.join(minionsDir, 'work-items.json');
+}
+
+function centralPullRequestsPath(minionsDir = MINIONS_DIR) {
+  return path.join(minionsDir, 'pull-requests.json');
+}
+
+function _projectSourceRawValue(source) {
+  if (source && typeof source === 'object') {
+    return source.name ?? source.project ?? source._project ?? source.source ?? source._source ??
+      source.wiPath ?? source.workItemsPath ?? source.prPath ?? source.pullRequestsPath ??
+      source.stateDir ?? source.path ?? source.localPath ?? '';
+  }
+  return source;
+}
+
+function _sameSourcePath(value, targetPath, minionsDir = MINIONS_DIR) {
+  if (!value || !targetPath) return false;
+  if (sameResolvedPath(value, targetPath)) return true;
+  if (!path.isAbsolute(value) && sameResolvedPath(path.resolve(minionsDir, value), targetPath)) return true;
+  return false;
+}
+
+function _projectSourceDescriptor(project, value, explicit, minionsDir = MINIONS_DIR) {
+  const wiPath = project ? projectWorkItemsPath(project) : centralWorkItemsPath(minionsDir);
+  const prPath = project ? projectPrPath(project) : centralPullRequestsPath(minionsDir);
+  const stateDir = project ? projectStateDir(project) : minionsDir;
+  return {
+    project: project || null,
+    explicit: !!explicit,
+    value: value || '',
+    sourceName: project?.name || 'central',
+    isCentral: !project,
+    stateDir,
+    wiPath,
+    prPath,
+  };
+}
+
+function resolveProjectSource(source, projectsOrConfig, options = {}) {
+  const projects = Array.isArray(projectsOrConfig) ? projectsOrConfig : getProjects(projectsOrConfig);
+  const minionsDir = options.minionsDir ? path.resolve(options.minionsDir) : MINIONS_DIR;
+  const allowCentral = options.allowCentral !== false;
+  const raw = _projectSourceRawValue(source);
+  const value = String(raw || '').trim();
+  const explicit = !!value;
+
+  if (!value) {
+    if (options.defaultWhenSingle && projects.length === 1) {
+      return _projectSourceDescriptor(projects[0], '', false, minionsDir);
+    }
+    if (allowCentral) return _projectSourceDescriptor(null, '', false, minionsDir);
+    return { project: null, explicit: false, value: '', sourceName: '', isCentral: false, wiPath: null, prPath: null, stateDir: null };
+  }
+
+  const centralWorkPath = centralWorkItemsPath(minionsDir);
+  const centralPrPath = centralPullRequestsPath(minionsDir);
+  const centralNames = new Set(['central', 'root']);
+  const lowerValue = value.toLowerCase();
+  const isCentral = centralNames.has(lowerValue) ||
+    _sameSourcePath(value, minionsDir, minionsDir) ||
+    _sameSourcePath(value, centralWorkPath, minionsDir) ||
+    _sameSourcePath(value, centralPrPath, minionsDir);
+  if (isCentral) {
+    if (allowCentral) return _projectSourceDescriptor(null, value, true, minionsDir);
+    return {
+      project: null,
+      explicit: true,
+      value,
+      sourceName: '',
+      isCentral: false,
+      wiPath: null,
+      prPath: null,
+      stateDir: null,
+      error: 'central source is not allowed here',
+    };
+  }
+
+  for (const project of projects || []) {
+    if (!project) continue;
+    if (String(project.name || '').toLowerCase() === lowerValue) {
+      return _projectSourceDescriptor(project, value, explicit, minionsDir);
+    }
+    const candidates = [
+      project.localPath,
+      projectStateDir(project),
+      projectWorkItemsPath(project),
+      projectPrPath(project),
+      legacyProjectStateDir(project),
+      legacyProjectStatePath(project, 'work-items.json'),
+      legacyProjectStatePath(project, 'pull-requests.json'),
+    ].filter(Boolean);
+    if (candidates.some(candidate => _sameSourcePath(value, candidate, minionsDir))) {
+      return _projectSourceDescriptor(project, value, explicit, minionsDir);
+    }
+  }
+
+  return {
+    project: null,
+    explicit: true,
+    value,
+    sourceName: '',
+    isCentral: false,
+    wiPath: null,
+    prPath: null,
+    stateDir: null,
+    error: formatUnknownProjectError(value, projects),
+  };
+}
+
 function projectRoot(project) {
   return path.resolve(project.localPath);
 }
@@ -1812,9 +1923,13 @@ function mergeProjectStateArrays(current, legacy) {
 
 function sameResolvedPath(a, b) {
   if (!a || !b) return false;
-  const left = path.resolve(a);
-  const right = path.resolve(b);
-  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+  try {
+    const left = path.resolve(a);
+    const right = path.resolve(b);
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+  } catch {
+    return false;
+  }
 }
 
 function removeLegacyProjectStateDir(project) {
@@ -3323,7 +3438,10 @@ module.exports = {
   findProjectByName,
   findProjectByNameOrPath,
   resolveConfiguredProject,
+  resolveProjectSource,
   projectRoot,
+  centralWorkItemsPath,
+  centralPullRequestsPath,
   projectStateDir,
   projectStateDirEnsure,
   projectWorkItemsPath,
@@ -3331,6 +3449,7 @@ module.exports = {
   legacyProjectStateDir,
   legacyProjectStatePath,
   ensureProjectStateFiles,
+  sameResolvedPath,
   resolveProjectForPrPath, // exported for testing
   getPrLinks,
   addPrLink,