@moretea-labs/forge 1.5.0-rc.1

package/src/cli/editing/executable-modes.ts

@@ -0,0 +1,70 @@
+import { chmodSync, lstatSync, openSync, closeSync, readSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+
+const EXCLUDED_DIRECTORIES = new Set([
+  '.git',
+  '.ai',
+  '.forge',
+  '_ops',
+  'node_modules',
+  'dist',
+  'coverage',
+]);
+
+export interface ExecutableModeRepairResult {
+  root: string;
+  scannedFiles: number;
+  shebangFiles: number;
+  repaired: string[];
+  missingExecutable: string[];
+}
+
+function hasShebang(path: string): boolean {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, 'r');
+    const buffer = Buffer.alloc(2);
+    return readSync(fd, buffer, 0, 2, 0) === 2 && buffer.toString('utf8') === '#!';
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function repairExecutableModes(repoRoot: string, checkOnly = false): ExecutableModeRepairResult {
+  const root = resolve(repoRoot);
+  const result: ExecutableModeRepairResult = {
+    root,
+    scannedFiles: 0,
+    shebangFiles: 0,
+    repaired: [],
+    missingExecutable: [],
+  };
+
+  const visit = (directory: string, relativeDirectory = ''): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isDirectory() && EXCLUDED_DIRECTORIES.has(entry.name)) continue;
+      const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+      const absolutePath = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        visit(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      result.scannedFiles += 1;
+      if (!hasShebang(absolutePath)) continue;
+      result.shebangFiles += 1;
+      const mode = lstatSync(absolutePath).mode & 0o777;
+      if ((mode & 0o111) !== 0) continue;
+      result.missingExecutable.push(relativePath);
+      if (!checkOnly) {
+        chmodSync(absolutePath, mode | 0o111);
+        result.repaired.push(relativePath);
+      }
+    }
+  };
+
+  visit(root);
+  return result;
+}

package/src/cli/github/github.ts

@@ -0,0 +1,274 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { runProcess } from '../../effects/process-runner';
+import { repositoryChildProcessEnvironment } from '../../runtime/shared/process-environment';
+import { getIssue, updateIssue, updateTask } from '../controller/issue-store';
+import type { ControllerIssue, ControllerTask, GitHubIssueLink } from '../controller/types';
+import { readTaskRunEvidence } from '../controller/run-evidence';
+import { resolveEffectiveTaskState, resolveIssueLifecycleStatus } from '../controller/task-status-resolver';
+
+export interface GitHubRepositoryInfo {
+  nameWithOwner: string;
+  owner: string;
+  repo: string;
+  url: string;
+  defaultBranch: string;
+}
+
+export interface GitHubStatus {
+  available: boolean;
+  authenticated: boolean;
+  version?: string;
+  repository?: GitHubRepositoryInfo;
+  agentTaskSupported: boolean;
+  errors: string[];
+}
+
+export interface PublishIssueOptions {
+  repo?: string;
+  labels?: string[];
+  includeTasks?: boolean;
+  projectOwner?: string;
+  projectNumber?: number;
+}
+
+function parseJson<T>(value: string, label: string): T {
+  try { return JSON.parse(value) as T; } catch (error) { throw new Error(`${label} returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+function parseRepo(value: string): { owner: string; repo: string } {
+  const normalized = value.trim().replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '').replace(/^git@github\.com:/, '');
+  const [owner, repo, ...rest] = normalized.split('/');
+  if (!owner || !repo || rest.length) throw new Error(`invalid GitHub repository: ${value}`);
+  return { owner, repo };
+}
+
+function gh(repoRoot: string, args: string[], input?: string, maxOutputBytes = 512 * 1024) {
+  return runProcess('gh', args, {
+    cwd: repoRoot,
+    timeoutMs: 120_000,
+    maxOutputBytes,
+    input,
+    env: repositoryChildProcessEnvironment(),
+  });
+}
+
+export function resolveGitHubRepository(repoRoot: string, explicitRepo?: string): GitHubRepositoryInfo {
+  const args = ['repo', 'view'];
+  if (explicitRepo?.trim()) args.push(explicitRepo.trim());
+  args.push('--json', 'nameWithOwner,url,defaultBranchRef');
+  const result = gh(repoRoot, args);
+  if (!result.ok) throw new Error(`failed to resolve GitHub repository: ${result.error || result.stderr}`);
+  const payload = parseJson<{ nameWithOwner: string; url: string; defaultBranchRef?: { name?: string } }>(result.stdout, 'gh repo view');
+  const { owner, repo } = parseRepo(payload.nameWithOwner);
+  return {
+    nameWithOwner: `${owner}/${repo}`,
+    owner,
+    repo,
+    url: payload.url,
+    defaultBranch: payload.defaultBranchRef?.name || 'main',
+  };
+}
+
+function versionAtLeast(version: string, minimum: [number, number, number]): boolean {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (!match) return false;
+  const actual = [Number(match[1]), Number(match[2]), Number(match[3])] as const;
+  for (let index = 0; index < 3; index += 1) {
+    if (actual[index] > minimum[index]) return true;
+    if (actual[index] < minimum[index]) return false;
+  }
+  return true;
+}
+
+export function getGitHubStatus(repoRoot: string, explicitRepo?: string): GitHubStatus {
+  const errors: string[] = [];
+  const versionResult = gh(repoRoot, ['--version'], undefined, 16 * 1024);
+  if (!versionResult.ok) return { available: false, authenticated: false, agentTaskSupported: false, errors: ['GitHub CLI (gh) is not installed or not on PATH.'] };
+  const version = versionResult.stdout.split(/\r?\n/)[0] || versionResult.stdout.trim();
+  const auth = gh(repoRoot, ['auth', 'status'], undefined, 64 * 1024);
+  if (!auth.ok) errors.push(auth.error || auth.stderr || 'GitHub CLI is not authenticated.');
+  let repository: GitHubRepositoryInfo | undefined;
+  try { repository = resolveGitHubRepository(repoRoot, explicitRepo); } catch (error) { errors.push(error instanceof Error ? error.message : String(error)); }
+  return {
+    available: true,
+    authenticated: auth.ok,
+    version,
+    repository,
+    agentTaskSupported: versionAtLeast(version, [2, 80, 0]),
+    errors,
+  };
+}
+
+function issueBody(repoRoot: string, issue: ControllerIssue): string {
+  return [
+    `<!-- forge:${issue.id} -->`,
+    issue.summary || 'No summary provided.',
+    '',
+    '## Goals',
+    ...(issue.goals.length ? issue.goals.map((item) => `- ${item}`) : ['- TBD']),
+    '',
+    '## Non-goals',
+    ...(issue.nonGoals.length ? issue.nonGoals.map((item) => `- ${item}`) : ['- None recorded.']),
+    '',
+    '## Acceptance criteria',
+    ...(issue.acceptanceCriteria.length ? issue.acceptanceCriteria.map((item) => `- [ ] ${item}`) : ['- [ ] Define acceptance criteria.']),
+    '',
+    '## Controller Tasks',
+    ...(issue.tasks.filter((task) => resolveEffectiveTaskState({ issue, task, runs: readTaskRunEvidence(repoRoot, task) }).effectiveStatus !== 'superseded').length
+      ? issue.tasks
+          .filter((task) => resolveEffectiveTaskState({ issue, task, runs: readTaskRunEvidence(repoRoot, task) }).effectiveStatus !== 'superseded')
+          .map((task) => {
+            const state = resolveEffectiveTaskState({ issue, task, runs: readTaskRunEvidence(repoRoot, task) });
+            return `- [ ] **${task.id}** — ${task.title} (declared: \`${state.declaredStatus}\`, effective: \`${state.effectiveStatus}\`, run: \`${state.latestRunStatus ?? 'none'}\`, \`${task.recommendedAgent ?? 'runtime-selected'}\`)`;
+          })
+      : ['- No tasks planned.']),
+    '',
+    `Local source: \`tasks/issues/${issue.id}-${issue.slug}.issue.md\``,
+  ].join('\n');
+}
+
+function taskBody(issue: ControllerIssue, task: ControllerTask, parentUrl: string): string {
+  return [
+    `<!-- forge:${issue.id}/${task.id} -->`,
+    `Parent controller issue: ${parentUrl}`,
+    '',
+    task.objective,
+    '',
+    '## Scope',
+    `- Allowed paths: ${task.allowedPaths.length ? task.allowedPaths.map((item) => `\`${item}\``).join(', ') : 'not defined'}`,
+    `- Forbidden paths: ${task.forbiddenPaths.length ? task.forbiddenPaths.map((item) => `\`${item}\``).join(', ') : 'default controller denies'}`,
+    `- Risk: \`${task.risk}\``,
+    `- Execution hint: \`${task.recommendedAgent ?? 'runtime-selected'}\``,
+    '',
+    '## Acceptance criteria',
+    ...(task.acceptanceCriteria.length ? task.acceptanceCriteria.map((item) => `- [ ] ${item}`) : ['- [ ] Define task acceptance criteria.']),
+    '',
+    '## Checks',
+    ...(task.checks.length ? task.checks.map((item) => `- [ ] \`${item}\``) : ['- [ ] Define a focused check or explicitly document manual verification.']),
+  ].join('\n');
+}
+
+function bodyFile(repoRoot: string, name: string, body: string): string {
+  const path = join(repoRoot, '.ai', 'harness', 'github', `${name}.md`);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, body, 'utf-8');
+  return path;
+}
+
+function parseIssueUrl(output: string): { url: string; number: number } {
+  const matches = output.match(/https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/issues\/(\d+)/g);
+  const url = matches?.at(-1);
+  if (!url) throw new Error(`GitHub CLI did not return an issue URL: ${output.trim()}`);
+  const number = Number(url.match(/\/(\d+)$/)?.[1]);
+  if (!Number.isFinite(number)) throw new Error(`could not parse issue number from ${url}`);
+  return { url, number };
+}
+
+function addProjectItem(repoRoot: string, link: GitHubIssueLink, projectOwner?: string, projectNumber?: number): GitHubIssueLink {
+  if (!projectOwner || !projectNumber) return link;
+  const result = gh(repoRoot, ['project', 'item-add', String(projectNumber), '--owner', projectOwner, '--url', link.url, '--format', 'json']);
+  if (!result.ok) throw new Error(`failed to add ${link.url} to GitHub Project: ${result.error || result.stderr}`);
+  const payload = result.stdout.trim() ? parseJson<Record<string, unknown>>(result.stdout, 'gh project item-add') : {};
+  return {
+    ...link,
+    projectOwner,
+    projectNumber,
+    projectItemId: typeof payload.id === 'string' ? payload.id : undefined,
+    syncedAt: new Date().toISOString(),
+  };
+}
+
+function withoutPairedOption(args: string[], option: string): string[] {
+  return args.filter((entry, index, all) => entry !== option && all[index - 1] !== option);
+}
+
+function createGitHubIssue(repoRoot: string, repo: GitHubRepositoryInfo, title: string, bodyPath: string, labels: string[], parentNumber?: number): GitHubIssueLink {
+  const args = ['issue', 'create', '--repo', repo.nameWithOwner, '--title', title, '--body-file', bodyPath];
+  for (const label of labels) args.push('--label', label);
+  if (parentNumber) args.push('--parent', String(parentNumber));
+  let attemptedArgs = args;
+  let result = gh(repoRoot, attemptedArgs);
+  if (!result.ok && parentNumber) {
+    // gh versions before sub-issue support reject --parent. Keep the parent URL in the body and retry.
+    attemptedArgs = withoutPairedOption(attemptedArgs, '--parent');
+    result = gh(repoRoot, attemptedArgs);
+  }
+  if (!result.ok && labels.length > 0) {
+    // Labels are optional metadata and may not exist in a newly linked repository. Publication must not fail only for that reason.
+    attemptedArgs = withoutPairedOption(attemptedArgs, '--label');
+    result = gh(repoRoot, attemptedArgs);
+  }
+  if (!result.ok) throw new Error(`failed to create GitHub issue: ${result.error || result.stderr}`);
+  const parsed = parseIssueUrl(result.stdout);
+  return { owner: repo.owner, repo: repo.repo, number: parsed.number, url: parsed.url, syncedAt: new Date().toISOString() };
+}
+
+function updateGitHubIssue(repoRoot: string, repo: GitHubRepositoryInfo, link: GitHubIssueLink, title: string, bodyPath: string): GitHubIssueLink {
+  const result = gh(repoRoot, ['issue', 'edit', String(link.number), '--repo', repo.nameWithOwner, '--title', title, '--body-file', bodyPath]);
+  if (!result.ok) throw new Error(`failed to update GitHub issue #${link.number}: ${result.error || result.stderr}`);
+  return { ...link, owner: repo.owner, repo: repo.repo, syncedAt: new Date().toISOString() };
+}
+
+export function publishIssueToGitHub(repoRoot: string, issueId: string, options: PublishIssueOptions = {}): ControllerIssue {
+  let issue = getIssue(repoRoot, issueId);
+  const repository = resolveGitHubRepository(repoRoot, options.repo ?? (issue.github ? `${issue.github.owner}/${issue.github.repo}` : undefined));
+  const labels = Array.from(new Set(['forge', issue.kind, ...(options.labels ?? [])].filter(Boolean)));
+  const parentBody = bodyFile(repoRoot, `${issue.id}-parent`, issueBody(repoRoot, issue));
+  try {
+    let parent = issue.github
+      ? updateGitHubIssue(repoRoot, repository, issue.github, issue.title, parentBody)
+      : createGitHubIssue(repoRoot, repository, issue.title, parentBody, labels);
+    parent = addProjectItem(repoRoot, parent, options.projectOwner, options.projectNumber);
+    issue = updateIssue(repoRoot, issue.id, { github: parent });
+
+    if (options.includeTasks) {
+      for (const task of issue.tasks.filter((entry) => resolveEffectiveTaskState({ issue, task: entry, runs: readTaskRunEvidence(repoRoot, entry) }).effectiveStatus !== 'superseded')) {
+        const taskFile = bodyFile(repoRoot, `${issue.id}-${task.id}`, taskBody(issue, task, parent.url));
+        try {
+          let taskLink = task.github
+            ? updateGitHubIssue(repoRoot, repository, task.github, `${task.id}: ${task.title}`, taskFile)
+            : createGitHubIssue(repoRoot, repository, `${task.id}: ${task.title}`, taskFile, ['forge-task'], parent.number);
+          taskLink = addProjectItem(repoRoot, taskLink, options.projectOwner, options.projectNumber);
+          issue = updateTask(repoRoot, issue.id, task.id, { github: taskLink, note: `Synced to GitHub: ${taskLink.url}` });
+        } finally {
+          rmSync(taskFile, { force: true });
+        }
+      }
+    }
+    return getIssue(repoRoot, issue.id);
+  } finally {
+    rmSync(parentBody, { force: true });
+  }
+}
+
+export function refreshGitHubIssue(repoRoot: string, issueId: string): { issue: ControllerIssue; remote: Record<string, unknown> } {
+  const issue = getIssue(repoRoot, issueId);
+  if (!issue.github) throw new Error('issue is not linked to GitHub');
+  const repository = `${issue.github.owner}/${issue.github.repo}`;
+  const result = gh(repoRoot, ['issue', 'view', String(issue.github.number), '--repo', repository, '--json', 'number,title,state,url,labels,assignees,projectItems,updatedAt']);
+  if (!result.ok) throw new Error(`failed to refresh GitHub issue: ${result.error || result.stderr}`);
+  const remote = parseJson<Record<string, unknown>>(result.stdout, 'gh issue view');
+  const state = String(remote.state ?? '').toUpperCase();
+  const lifecycle = resolveIssueLifecycleStatus(issue);
+  const nextStatus = state === 'CLOSED' && lifecycle === 'active' ? 'review' : issue.status;
+  const updated = updateIssue(repoRoot, issue.id, {
+    status: nextStatus,
+    github: { ...issue.github, url: String(remote.url ?? issue.github.url), syncedAt: new Date().toISOString() },
+  });
+  return { issue: updated, remote };
+}
+
+export function closeGitHubIssue(repoRoot: string, issueId: string): ControllerIssue {
+  const issue = getIssue(repoRoot, issueId);
+  if (!issue.github) throw new Error('issue is not linked to GitHub');
+  const result = gh(repoRoot, ['issue', 'close', String(issue.github.number), '--repo', `${issue.github.owner}/${issue.github.repo}`]);
+  if (!result.ok) throw new Error(`failed to close GitHub issue: ${result.error || result.stderr}`);
+  return updateIssue(repoRoot, issue.id, { github: { ...issue.github, syncedAt: new Date().toISOString() } });
+}
+
+export function githubIssueExists(repoRoot: string, link: GitHubIssueLink): boolean {
+  if (!existsSync(repoRoot)) return false;
+  const result = gh(repoRoot, ['issue', 'view', String(link.number), '--repo', `${link.owner}/${link.repo}`, '--json', 'number']);
+  return result.ok;
+}

package/src/cli/github/plugin.ts

@@ -0,0 +1,345 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { getGitHubStatus, publishIssueToGitHub, refreshGitHubIssue, closeGitHubIssue } from "./github";
+import type { ControllerIssue } from "../controller/types";
+import { tryAppendControllerWorklogEvent } from "../controller/worklog";
+import { resolveRepoPreferredControllerHome } from "../repositories/controller-home";
+import { listRepositories, updateRepository } from "../repositories/registry";
+import type { RepositoryRecord } from "../repositories/types";
+
+const CONFIG_PATH = ".forge/plugins/github.json";
+const STATUS_CACHE_TTL_MS = 30_000;
+const CONFIG_STATUS_CACHE_TTL_MS = 5_000;
+const statusCache = new Map<string, { at: number; fingerprint: string; status: GitHubPluginStatus }>();
+
+export interface GitHubPluginConfig {
+  schemaVersion: 1;
+  enabled: boolean;
+  repository?: string;
+  labels?: string[];
+  syncMode: "manual" | "checkpoint";
+  includeTasks: boolean;
+  projectOwner?: string;
+  projectNumber?: number;
+  statusField?: string;
+}
+
+export interface GitHubPluginStatus {
+  config: GitHubPluginConfig;
+  probed: boolean;
+  available: boolean;
+  authenticated: boolean;
+  ready: boolean;
+  repository?: string;
+  errors: string[];
+  warnings: string[];
+  capabilities: {
+    issues: boolean;
+    projects: boolean;
+    copilotAgentSessions: boolean;
+  };
+}
+
+export function defaultGitHubPluginConfig(): GitHubPluginConfig {
+  return {
+    schemaVersion: 1,
+    enabled: false,
+    syncMode: "manual",
+    includeTasks: true,
+  };
+}
+
+function configuredGitHubPluginStatus(config: GitHubPluginConfig): GitHubPluginStatus {
+  return {
+    config,
+    probed: false,
+    available: false,
+    authenticated: false,
+    ready: false,
+    repository: config.repository,
+    errors: [],
+    warnings: !config.enabled
+      ? ['GitHub plugin is disabled. Enable it to probe GitHub CLI and repository readiness.']
+      : ['Live GitHub CLI readiness will refresh on the next explicit status read.'],
+    capabilities: { issues: false, projects: false, copilotAgentSessions: false },
+  };
+}
+
+function normalizeGitHubPluginConfig(raw: Partial<GitHubPluginConfig>): GitHubPluginConfig {
+  const repository = typeof raw.repository === "string" && raw.repository.trim()
+    ? raw.repository.trim()
+    : undefined;
+  const labels = Array.isArray(raw.labels)
+    ? Array.from(new Set(raw.labels.map((label) => String(label).trim()).filter(Boolean)))
+    : undefined;
+  const projectOwner = typeof raw.projectOwner === "string" && raw.projectOwner.trim()
+    ? raw.projectOwner.trim()
+    : undefined;
+  const statusField = typeof raw.statusField === "string" && raw.statusField.trim()
+    ? raw.statusField.trim()
+    : undefined;
+  const projectNumber = Number.isInteger(raw.projectNumber) && Number(raw.projectNumber) > 0
+    ? Number(raw.projectNumber)
+    : undefined;
+  return {
+    schemaVersion: 1,
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : defaultGitHubPluginConfig().enabled,
+    repository,
+    labels,
+    syncMode: raw.syncMode === "checkpoint" ? "checkpoint" : "manual",
+    includeTasks: raw.includeTasks !== false,
+    projectOwner,
+    projectNumber,
+    statusField,
+  };
+}
+
+function loadLegacyGitHubPluginConfig(repoRoot: string): GitHubPluginConfig | undefined {
+  const path = join(repoRoot, CONFIG_PATH);
+  if (!existsSync(path)) return undefined;
+  try {
+    return normalizeGitHubPluginConfig(JSON.parse(readFileSync(path, "utf-8")) as Partial<GitHubPluginConfig>);
+  } catch (_error) {
+    return undefined;
+  }
+}
+
+function findRepositoryRecord(repoRoot: string): RepositoryRecord | undefined {
+  const controllerHome = resolveRepoPreferredControllerHome(repoRoot);
+  return listRepositories(controllerHome).find((record) =>
+    record.canonicalRoot === repoRoot
+    || record.localRoot === repoRoot
+    || record.checkouts.some((checkout) => checkout.canonicalRoot === repoRoot || checkout.localRoot === repoRoot));
+}
+
+function configFromRepository(record: RepositoryRecord | undefined): GitHubPluginConfig | undefined {
+  const github = record?.github;
+  if (!github) return undefined;
+  return normalizeGitHubPluginConfig({
+    enabled: github.pluginEnabled ?? true,
+    repository: github.repository ?? (github.owner && github.repo ? `${github.owner}/${github.repo}` : undefined),
+    labels: github.labels,
+    syncMode: github.syncMode,
+    includeTasks: github.includeTasks,
+    projectOwner: github.projectOwner,
+    projectNumber: github.projectNumber,
+    statusField: github.statusField,
+  });
+}
+
+function syncRepositoryGitHubConfig(repoRoot: string, config: GitHubPluginConfig): void {
+  const record = findRepositoryRecord(repoRoot);
+  if (!record) return;
+  const controllerHome = resolveRepoPreferredControllerHome(repoRoot);
+  const current = record.github;
+  const repository = config.repository?.trim();
+  const effectiveRepository = repository
+    || current?.repository
+    || (current?.owner && current?.repo ? `${current.owner}/${current.repo}` : undefined);
+  if (!effectiveRepository) return;
+  const [owner, repo] = effectiveRepository.includes("/") ? effectiveRepository.split("/", 2) : [current?.owner, current?.repo];
+  if (!owner || !repo) return;
+  updateRepository(record.repoId, {
+    github: {
+      owner,
+      repo,
+      repository: effectiveRepository,
+      labels: config.labels ?? current?.labels,
+      projectOwner: config.projectOwner,
+      projectNumber: config.projectNumber,
+      statusField: config.statusField,
+      pluginEnabled: config.enabled,
+      syncMode: config.syncMode,
+      includeTasks: config.includeTasks,
+      issueSyncEnabled: current?.issueSyncEnabled,
+      cloudAgentSupported: current?.cloudAgentSupported,
+      authenticationCapability: current?.authenticationCapability ?? "unknown",
+    },
+  }, controllerHome);
+}
+
+export function loadGitHubPluginConfig(repoRoot: string): GitHubPluginConfig {
+  const registryConfig = configFromRepository(findRepositoryRecord(repoRoot));
+  const legacyConfig = loadLegacyGitHubPluginConfig(repoRoot);
+  if (registryConfig && legacyConfig) {
+    const merged = normalizeGitHubPluginConfig({
+      ...registryConfig,
+      enabled: legacyConfig.enabled,
+      repository: legacyConfig.repository ?? registryConfig.repository,
+      labels: legacyConfig.labels ?? registryConfig.labels,
+      syncMode: legacyConfig.syncMode,
+      includeTasks: legacyConfig.includeTasks,
+      projectOwner: legacyConfig.projectOwner ?? registryConfig.projectOwner,
+      projectNumber: legacyConfig.projectNumber ?? registryConfig.projectNumber,
+      statusField: legacyConfig.statusField ?? registryConfig.statusField,
+    });
+    syncRepositoryGitHubConfig(repoRoot, merged);
+    return merged;
+  }
+  if (registryConfig) return registryConfig;
+  if (legacyConfig) {
+    syncRepositoryGitHubConfig(repoRoot, legacyConfig);
+    return legacyConfig;
+  }
+  return defaultGitHubPluginConfig();
+}
+
+export type GitHubPluginConfigPatch = Partial<Omit<GitHubPluginConfig, "schemaVersion" | "projectNumber">> & {
+  projectNumber?: number | null;
+};
+
+export function saveGitHubPluginConfig(
+  repoRoot: string,
+  patch: GitHubPluginConfigPatch,
+): GitHubPluginConfig {
+  const current = loadGitHubPluginConfig(repoRoot);
+  const repository = patch.repository === undefined
+    ? current.repository
+    : patch.repository.trim() || undefined;
+  const labels = patch.labels === undefined
+    ? current.labels
+    : Array.from(new Set(patch.labels.map((label) => label.trim()).filter(Boolean)));
+  const projectOwner = patch.projectOwner === undefined
+    ? current.projectOwner
+    : patch.projectOwner.trim() || undefined;
+  const statusField = patch.statusField === undefined
+    ? current.statusField
+    : patch.statusField.trim() || undefined;
+  let projectNumber = patch.projectNumber === undefined ? current.projectNumber : patch.projectNumber ?? undefined;
+  if (projectNumber !== undefined) {
+    if (!Number.isInteger(projectNumber) || projectNumber < 1) {
+      throw new Error("GitHub project number must be a positive integer");
+    }
+  }
+  const config: GitHubPluginConfig = {
+    schemaVersion: 1,
+    enabled: typeof patch.enabled === "boolean" ? patch.enabled : current.enabled,
+    repository,
+    labels,
+    syncMode: patch.syncMode === "manual" || patch.syncMode === "checkpoint"
+      ? patch.syncMode
+      : current.syncMode,
+    includeTasks: typeof patch.includeTasks === "boolean" ? patch.includeTasks : current.includeTasks,
+    projectOwner,
+    projectNumber,
+    statusField,
+  };
+  syncRepositoryGitHubConfig(repoRoot, config);
+  const path = join(repoRoot, CONFIG_PATH);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+  statusCache.set(repoRoot, {
+    at: Date.now() - STATUS_CACHE_TTL_MS + CONFIG_STATUS_CACHE_TTL_MS,
+    fingerprint: JSON.stringify(config),
+    status: configuredGitHubPluginStatus(config),
+  });
+  tryAppendControllerWorklogEvent(repoRoot, {
+    category: "github",
+    action: "github_plugin_configured",
+    summary: `GitHub plugin ${config.enabled ? "enabled" : "disabled"}.`,
+    actor: "local-controller",
+    details: { config },
+  });
+  return config;
+}
+
+export function getGitHubPluginStatus(repoRoot: string, forceRefresh = false): GitHubPluginStatus {
+  const config = loadGitHubPluginConfig(repoRoot);
+  if (!config.enabled) {
+    return {
+      config,
+      probed: false,
+      available: false,
+      authenticated: false,
+      ready: false,
+      repository: config.repository,
+      errors: [],
+      warnings: ["GitHub plugin is disabled. Enable it to probe GitHub CLI and repository readiness."],
+      capabilities: { issues: false, projects: false, copilotAgentSessions: false },
+    };
+  }
+  const fingerprint = JSON.stringify(config);
+  const cached = statusCache.get(repoRoot);
+  if (!forceRefresh && cached && cached.fingerprint === fingerprint && Date.now() - cached.at < STATUS_CACHE_TTL_MS) {
+    return cached.status;
+  }
+  const status = getGitHubStatus(repoRoot, config.repository);
+  const result: GitHubPluginStatus = {
+    config,
+    probed: true,
+    available: status.available,
+    authenticated: status.authenticated,
+    ready: status.available && status.authenticated && Boolean(status.repository),
+    repository: status.repository?.nameWithOwner ?? config.repository,
+    errors: status.errors,
+    warnings: status.agentTaskSupported ? [] : ["GitHub CLI is too old for observable Copilot agent sessions; Issue synchronization remains available."],
+    capabilities: {
+      issues: status.available && status.authenticated,
+      projects: status.available && status.authenticated,
+      copilotAgentSessions: status.agentTaskSupported,
+    },
+  };
+  statusCache.set(repoRoot, { at: Date.now(), fingerprint, status: result });
+  return result;
+}
+
+function requireEnabled(repoRoot: string): GitHubPluginConfig {
+  const config = loadGitHubPluginConfig(repoRoot);
+  if (!config.enabled) throw new Error("GitHub plugin is disabled. Enable it before publishing or syncing Issues.");
+  return config;
+}
+
+export function publishIssueWithGitHubPlugin(repoRoot: string, issueId: string): ControllerIssue {
+  const config = requireEnabled(repoRoot);
+  const issue = publishIssueToGitHub(repoRoot, issueId, {
+    repo: config.repository,
+    labels: config.labels,
+    includeTasks: config.includeTasks,
+    projectOwner: config.projectOwner,
+    projectNumber: config.projectNumber,
+  });
+  statusCache.delete(repoRoot);
+  tryAppendControllerWorklogEvent(repoRoot, {
+    category: "github",
+    action: "github_issue_published",
+    summary: `Published ${issue.id} to GitHub.`,
+    actor: "github-plugin",
+    issueId: issue.id,
+    details: { url: issue.github?.url },
+  });
+  return issue;
+}
+
+export function refreshIssueWithGitHubPlugin(repoRoot: string, issueId: string) {
+  requireEnabled(repoRoot);
+  const result = refreshGitHubIssue(repoRoot, issueId);
+  statusCache.delete(repoRoot);
+  tryAppendControllerWorklogEvent(repoRoot, {
+    category: "github",
+    action: "github_issue_refreshed",
+    summary: `Refreshed ${issueId} from GitHub.`,
+    actor: "github-plugin",
+    issueId,
+    details: { url: result.issue.github?.url, remote: result.remote },
+  });
+  return result;
+}
+
+export function closeIssueWithGitHubPlugin(repoRoot: string, issueId: string): ControllerIssue {
+  requireEnabled(repoRoot);
+  const issue = closeGitHubIssue(repoRoot, issueId);
+  statusCache.delete(repoRoot);
+  tryAppendControllerWorklogEvent(repoRoot, {
+    category: "github",
+    action: "github_issue_closed",
+    summary: `Closed the linked GitHub Issue for ${issueId}.`,
+    actor: "github-plugin",
+    issueId,
+    details: { url: issue.github?.url },
+  });
+  return issue;
+}
+
+export function githubPluginConfigPath(): string {
+  return CONFIG_PATH;
+}