@a5c-ai/krate 5.0.1-staging.660d2b90f → 5.0.1-staging.69cb593ea

package/src/controller-ui.js

@@ -1,3 +1,4 @@
+import { giteaIssueSyncPlan, githubProjectIssueSyncPlan } from './gitea-backend.js';
 import { resourceToYaml } from './resource-model.js';
 import { KRATE_ORG_LABEL, KRATE_ORG_NAMESPACE_LABEL, KRATE_RESOURCES, apiResourceName, createKrateKubernetesReconciler, orgNamespaceName } from './kubernetes-controller.js';
 
@@ -31,18 +32,25 @@ const controllerEndpoints = [
   { method: 'GET', path: '/api/orgs/:org/agents/projects', purpose: 'list agent projects with board config' },
   { method: 'POST', path: '/api/orgs/:org/agents/dispatch', purpose: 'create manual agent dispatch run' },
   { method: 'POST', path: '/api/orgs/:org/agents/approvals/:name/decide', purpose: 'approve or deny a pending agent approval request' },
-  { method: 'POST', path: '/api/orgs/:org/agents/triggers/process', purpose: 'evaluate an event against trigger rules and dispatch matching agents' }
+  { method: 'POST', path: '/api/orgs/:org/agents/triggers/process', purpose: 'evaluate an event against trigger rules and dispatch matching agents' },
+  { method: 'POST', path: '/api/orgs/:org/agents/workspaces', purpose: 'provision a new agent workspace with worktree and runtime' },
+  { method: 'POST', path: '/api/orgs/:org/agents/workspaces/:name/archive', purpose: 'archive an agent workspace and mark it for cleanup' },
+  { method: 'POST', path: '/api/orgs/:org/agents/workspaces/:name/link', purpose: 'link a work item to an agent workspace' },
+  { method: 'POST', path: '/api/orgs/:org/agents/memory/query', purpose: 'query Company Brain memory with graph and grep search' },
+  { method: 'POST', path: '/api/orgs/:org/agents/memory/imports', purpose: 'create a memory import from a babysitter run' },
+  { method: 'GET', path: '/api/orgs/:org/agents/memory/snapshots', purpose: 'list memory snapshots for an organization' },
+  { method: 'GET', path: '/api/orgs/:org/agents/memory/repositories', purpose: 'list memory repositories for an organization' }
 ];
 
 const runtimeComponents = [
   { id: 'identity-access', title: 'Identity and access', area: 'identity', resources: ['User', 'Team', 'Invite', 'IdentityMapping', 'AuthProvider'], docs: 'src/auth.js' },
-  { id: 'api-controller', title: 'Krate API controller', area: 'api', resources: ['Repository', 'PullRequest', 'Pipeline'], docs: 'src/api-controller.js' },
+  { id: 'api-controller', title: 'Krate API controller', area: 'api', resources: ['Repository', 'KrateProject', 'PullRequest', 'Issue', 'Pipeline'], docs: 'src/api-controller.js' },
   { id: 'krate-resource-client', title: 'Krate resource client', area: 'control-plane', resources: ['Repository', 'BranchProtection', 'RefPolicy'], docs: 'src/kubernetes-controller.js' },
   { id: 'repository-service', title: 'Repository service', area: 'data-plane', resources: ['Repository', 'BranchProtection', 'RefPolicy'], docs: 'src/data-plane.js' },
   { id: 'runners-ci', title: 'Runner scheduler', area: 'ci', resources: ['RunnerPool', 'Pipeline', 'Job'], docs: 'src/kubernetes-controller.js' },
   { id: 'hooks-events', title: 'Webhook bus', area: 'events', resources: ['WebhookSubscription', 'WebhookDelivery'], docs: 'src/kubernetes-controller.js' },
   { id: 'policy-engine', title: 'Kyverno policy engine', area: 'policy', resources: ['PolicyProfile', 'PolicyTemplate', 'PolicyBinding', 'PolicyExceptionRequest'], docs: 'docs/todo-kyverno' },
-  { id: 'agent-orchestration', title: 'Agent orchestration', area: 'agents', resources: ['AgentStack', 'AgentDispatchRun', 'AgentTriggerRule', 'AgentSession', 'AgentWorkspace', 'AgentApproval', 'AgentAdapter', 'AgentProviderConfig', 'AgentProject'], docs: 'docs/agents/' }
+  { id: 'agent-orchestration', title: 'Agent orchestration', area: 'agents', resources: ['AgentStack', 'AgentDispatchRun', 'AgentTriggerRule', 'AgentSession', 'KrateWorkspace', 'AgentApproval', 'AgentAdapter', 'AgentProviderConfig', 'KrateProject'], docs: 'docs/agents/' }
 ];
 
 export function createControllerUiModel(source, options = {}) {
@@ -83,6 +91,7 @@ export function createControllerUiModel(source, options = {}) {
   identityView.org = activeOrg?.slug;
   const repositories = filterByOrg(snapshot.resources.Repository || [], activeOrg?.slug);
   const pullRequests = filterByOrg(snapshot.resources.PullRequest || [], activeOrg?.slug);
+  const issues = filterByOrg(snapshot.resources.Issue || [], activeOrg?.slug);
   const pipelines = filterByOrg(snapshot.resources.Pipeline || [], activeOrg?.slug);
   const jobs = filterByOrg(snapshot.resources.Job || [], activeOrg?.slug);
   const runnerPools = filterByOrg(snapshot.resources.RunnerPool || [], activeOrg?.slug);
@@ -97,13 +106,16 @@ export function createControllerUiModel(source, options = {}) {
   const agentDispatchRuns = filterByOrg(snapshot.resources.AgentDispatchRun || [], activeOrg?.slug);
   const agentTriggerRules = filterByOrg(snapshot.resources.AgentTriggerRule || [], activeOrg?.slug);
   const agentSessions = filterByOrg(snapshot.resources.AgentSession || [], activeOrg?.slug);
-  const agentWorkspaces = filterByOrg(snapshot.resources.AgentWorkspace || [], activeOrg?.slug);
+  const agentWorkspaces = filterByOrg(snapshot.resources.KrateWorkspace || [], activeOrg?.slug);
   const agentApprovals = filterByOrg(snapshot.resources.AgentApproval || [], activeOrg?.slug);
   const agentAdapters = filterByOrg(snapshot.resources.AgentAdapter || [], activeOrg?.slug);
   const agentProviders = filterByOrg(snapshot.resources.AgentProviderConfig || [], activeOrg?.slug);
-  const agentProjects = filterByOrg(snapshot.resources.AgentProject || [], activeOrg?.slug);
+  const agentProjects = filterByOrg(snapshot.resources.KrateProject || [], activeOrg?.slug);
   const agentGateway = filterByOrg(snapshot.resources.AgentGatewayConfig || [], activeOrg?.slug);
   const agentTranscripts = filterByOrg(snapshot.resources.AgentSessionTranscript || [], activeOrg?.slug);
+  const memoryRepositories = filterByOrg(snapshot.resources.AgentMemoryRepository || [], activeOrg?.slug);
+  const memorySnapshots = filterByOrg(snapshot.resources.AgentMemorySnapshot || [], activeOrg?.slug);
+  const memoryImports = filterByOrg(snapshot.resources.AgentRunMemoryImport || [], activeOrg?.slug);
 
   const agentView = {
     org: activeOrg?.slug,
@@ -118,6 +130,9 @@ export function createControllerUiModel(source, options = {}) {
     projects: { count: agentProjects.length, items: agentProjects },
     gateway: agentGateway[0] || null,
     transcripts: { count: agentTranscripts.length, items: agentTranscripts },
+    memoryRepositories: { count: memoryRepositories.length, items: memoryRepositories },
+    memorySnapshots: { count: memorySnapshots.length, items: memorySnapshots },
+    memoryImports: { count: memoryImports.length, items: memoryImports, pending: memoryImports.filter(i => !i.status?.phase || i.status.phase === 'Pending' || i.status.phase === 'AwaitingReview') },
   };
   const deploymentApplications = filterByOrg(snapshot.resources.KubeVelaApplication || [], activeOrg?.slug);
   const deploymentReleases = filterByOrg(snapshot.resources.KubeVelaApplicationRevision || [], activeOrg?.slug);
@@ -170,6 +185,8 @@ export function createControllerUiModel(source, options = {}) {
       invites: invites.length,
       repositories: repositories.length,
       pullRequests: pullRequests.length,
+      issues: issues.length,
+      projects: agentProjects.length,
       pipelines: pipelines.length,
       jobs: jobs.length,
       runnerPools: runnerPools.length,
@@ -204,8 +221,11 @@ export function createControllerUiModel(source, options = {}) {
     views: {
       dashboard: {
         repositories,
+        projects: agentProjects,
+        issues,
+        issueSync: issueSyncView({ org: activeOrg?.slug, projects: agentProjects, repositories, issues }),
       excellentFlows: ['Create or import a repository', 'Browse code and copy clone commands', 'Review and merge a pull request', 'Debug a failing pipeline run', 'Edit runner pool capacity', 'Inspect and replay webhook deliveries', 'Save a triage View'],
-        cards: dashboardCards({ repositories, pullRequests, pipelines, runnerPools, webhookDeliveries })
+        cards: dashboardCards({ repositories, projects: agentProjects, pullRequests, issues, pipelines, runnerPools, webhookDeliveries })
       },
       pullRequestReview: pullRequests[0] ? pullRequestReview(pullRequests[0], pipelines, jobs) : null,
       failingRun: pipelines.find((pipeline) => pipeline.status?.phase === 'Failed') ? failingRun(pipelines.find((pipeline) => pipeline.status?.phase === 'Failed'), jobs) : null,
@@ -244,13 +264,14 @@ function filterResourceItemsForOrg(definition, items = [], org) {
   return filterByOrg(items, org);
 }
 
-function filterByOrg(items = [], org) {
-  if (!org) return items;
-  return items.filter((item) => {
-    const itemOrg = item.spec?.organizationRef || item.metadata?.labels?.[KRATE_ORG_LABEL];
-    return itemOrg === org;
-  });
-}
+function filterByOrg(items = [], org) {
+  if (!org) return items;
+  const orgNamespace = orgNamespaceName(org);
+  return items.filter((item) => {
+    const itemOrg = item.spec?.organizationRef || item.metadata?.labels?.[KRATE_ORG_LABEL];
+    return itemOrg === org || item.metadata?.namespace === orgNamespace;
+  });
+}
 
 function normalizeSnapshot(source = {}) {
   const raw = typeof source.snapshot === 'function' ? source.snapshot() : source;
@@ -281,9 +302,11 @@ function summarizePhases(items) {
   }, {});
 }
 
-function dashboardCards({ repositories, pullRequests, pipelines, runnerPools, webhookDeliveries }) {
+function dashboardCards({ repositories, projects = [], pullRequests, issues = [], pipelines, runnerPools, webhookDeliveries }) {
   return [
     { label: 'Repositories', value: repositories.length, href: '/repositories' },
+    { label: 'Projects', value: projects.length, href: '/agents/projects' },
+    { label: 'Issues', value: issues.length, href: '/inbox' },
     { label: 'Pull requests', value: pullRequests.length, href: '/inbox' },
     { label: 'Runs', value: pipelines.length, href: '/runs' },
     { label: 'Runner pools', value: runnerPools.length, href: '/runners-ci' },
@@ -299,8 +322,65 @@ function defaultArchitecture(namespace) {
     deliveryReconciler: { role: 'krate-delivery-reconciler', scope: 'Repository status projection, repository hosting intent, policy projection, and data-plane sync intent; never owns HTTP routes or browser flows', namespace, delegatesTo: ['krate-resource-gateway', 'repository-service'] },
     repositoryService: { role: 'repository-service', scope: 'repository streaming and SSH hosting, object storage, and search indexing', boundary: process.env.KRATE_GITEA_HTTP_URL || 'repository service not configured' }
   };
-}
-
+}
+
+export function issueRepositoryRefs(issue = {}) {
+  return uniqueStrings([
+    issue.spec?.repository,
+    issue.spec?.repoRef,
+    issue.spec?.repositoryRef,
+    issue.metadata?.labels?.repository,
+    issue.metadata?.labels?.['krate.a5c.ai/repository'],
+    issue.metadata?.annotations?.['krate.a5c.ai/repository'],
+    issue.metadata?.annotations?.['krate.a5c.ai/repositories'],
+    issue.status?.repository,
+    issue.status?.repositoryRef,
+    ...(issue.spec?.repositories || []),
+    ...(issue.spec?.repositoryRefs || []),
+    ...(issue.status?.repositories || []),
+    ...(issue.status?.repositoryRefs || [])
+  ]);
+}
+
+export function issueProjectRefs(issue = {}) {
+  return uniqueStrings([
+    issue.spec?.project,
+    issue.spec?.projectRef,
+    issue.spec?.krateProject,
+    issue.spec?.krateProjectRef,
+    issue.metadata?.labels?.project,
+    issue.metadata?.labels?.['krate.a5c.ai/project'],
+    issue.metadata?.labels?.['krate.a5c.ai/krate-project'],
+    issue.metadata?.annotations?.['krate.a5c.ai/project'],
+    issue.metadata?.annotations?.['krate.a5c.ai/projects'],
+    issue.status?.project,
+    issue.status?.projectRef,
+    ...(issue.spec?.projects || []),
+    ...(issue.spec?.projectRefs || []),
+    ...(issue.status?.projects || []),
+    ...(issue.status?.projectRefs || [])
+  ]);
+}
+
+function uniqueStrings(values = []) {
+  return [...new Set(values.flatMap(refNames).filter(Boolean).map(String))];
+}
+
+function refNames(value) {
+  if (value === undefined || value === null || value === '') return [];
+  if (Array.isArray(value)) return value.flatMap(refNames);
+  if (typeof value === 'string') return value.split(',').map((part) => part.trim()).filter(Boolean);
+  if (typeof value === 'object') return refNames(value.name || value.repository || value.repo || value.project || value.krateProject || value.metadata?.name || value.ref || value.slug);
+  return [String(value)];
+}
+
+function issueSyncView({ org = 'default', projects = [], repositories = [], issues = [] }) {
+  return {
+    gitea: giteaIssueSyncPlan({ org, project: projects[0]?.metadata?.name || null, issue: issues[0] || null, repositories: repositories.map((repo) => repo.metadata?.name).filter(Boolean) }),
+    github: githubProjectIssueSyncPlan({ org, project: projects[0]?.metadata?.name || null, issue: issues[0] || null, repositories: repositories.map((repo) => repo.metadata?.name).filter(Boolean) })
+  };
+}
+
 function pullRequestReview(pullRequest, pipelines, jobs) {
   const pipelineRuns = pipelines.filter((pipeline) => pipeline.spec?.pullRequest === pullRequest.metadata?.name || pipeline.metadata?.labels?.pullrequest === pullRequest.metadata?.name);
   return {

package/src/data-plane.js

@@ -1,4 +1,4 @@
-import { giteaRepositoryIntegrationPlan } from './gitea-backend.js';
+import { giteaIssueSyncPlan, giteaRepositoryIntegrationPlan, orgMemoryRepositoryName } from './gitea-backend.js';
 import { clone, createResource } from './resource-model.js';
 
 
@@ -22,7 +22,8 @@ export function createGiteaRepositoryHosting({ backend = createDefaultGiteaGitBa
     organization: { kind: 'Organization', name: owner, delegatedTo: 'Gitea /api/v1/orgs' },
     sshKeys: { kind: 'SSHKey', scopes: ['user', 'deploy', 'argocd'], delegatedTo: 'Gitea /api/v1/user/keys and /repos/{owner}/{repo}/keys' },
     permissions: { kind: 'RepositoryPermission', defaultCollaborator: 'write', adminTeam: 'maintainers', delegatedTo: 'Gitea collaborators and team repository APIs' },
-    forgeRecords: { issues: 'Gitea /repos/{owner}/{repo}/issues', pullRequests: 'Gitea /repos/{owner}/{repo}/pulls' },
+    forgeRecords: { issues: `Gitea /repos/${owner}/${orgMemoryRepositoryName(namespace)}/issues`, pullRequests: 'Gitea /repos/{owner}/{repo}/pulls' },
+    issueSync: giteaIssueSyncPlan({ org: namespace, repositories: [repository] }),
     webhookUrl,
     integrationPlan: giteaRepositoryIntegrationPlan({ owner, repo: repository, deployKeyTitle: 'krate-argocd', permission: 'write', branch, webhookUrl })
   };

package/src/event-bus.js

@@ -0,0 +1,61 @@
+/**
+ * Module-level event bus for SSE real-event streaming.
+ * Provides a pub/sub mechanism for resource change events.
+ */
+
+/**
+ * Creates a new event bus with subscribe, unsubscribe, and emit methods.
+ * @returns {{ subscribe: Function, unsubscribe: Function, emit: Function, emitResourceChange: Function }}
+ */
+export function createEventBus() {
+  const listeners = new Set();
+
+  return {
+    /**
+     * Subscribe a listener function to receive emitted events.
+     * @param {Function} fn - listener receiving the event object
+     */
+    subscribe(fn) {
+      listeners.add(fn);
+    },
+
+    /**
+     * Remove a previously subscribed listener.
+     * @param {Function} fn - the listener to remove
+     */
+    unsubscribe(fn) {
+      listeners.delete(fn);
+    },
+
+    /**
+     * Emit an event to all current subscribers.
+     * @param {object} event - the event payload to broadcast
+     */
+    emit(event) {
+      for (const fn of listeners) {
+        fn(event);
+      }
+    },
+
+    /**
+     * Emit a resource-change event with kind, name, operation, and timestamp.
+     * @param {string} kind - resource kind (e.g. 'Repository')
+     * @param {string} name - resource name
+     * @param {string} operation - operation performed (e.g. 'apply', 'delete')
+     */
+    emitResourceChange(kind, name, operation) {
+      this.emit({
+        type: 'resource-change',
+        kind,
+        name,
+        operation,
+        timestamp: new Date().toISOString()
+      });
+    }
+  };
+}
+
+/**
+ * Module-level singleton event bus shared across the HTTP server and API controller.
+ */
+export const globalEventBus = createEventBus();

package/src/external/conflict-controller.js

@@ -0,0 +1,225 @@
+// External Conflict Controller — Slice 3.5
+// Detects field divergence between local Krate state and external provider state,
+// manages resolution workflows, and handles superseded conflict cleanup.
+
+import { createResource, clone } from '../resource-model.js';
+
+export const CONFLICT_CONTROLLER_BOUNDARY = {
+  role: 'external-conflict-controller',
+  scope: 'Field-level conflict detection and resolution for ExternalSyncConflict resources',
+  owns: ['conflict detection', 'resolution workflow', 'superseded cleanup', 'open conflict listing'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['write intent lifecycle', 'sync scheduling', 'external API client']
+};
+
+const VALID_STRATEGIES = ['prefer-external', 'prefer-krate', 'manual', 'ignore'];
+const OPEN_PHASES = new Set(['Open']);
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a conflict detection input object.
+ *
+ * @param {object} input
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateConflict(input) {
+  const errors = [];
+  if (!input) {
+    return { valid: false, errors: ['input must not be null or undefined'] };
+  }
+  if (!input.resourceRef || typeof input.resourceRef !== 'string') {
+    errors.push('resourceRef is required and must be a non-empty string');
+  }
+  if (!input.fieldPath || typeof input.fieldPath !== 'string') {
+    errors.push('fieldPath is required and must be a non-empty string');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Controller factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a ConflictController that manages ExternalSyncConflict resources.
+ *
+ * @param {{ persistFn?: (resource: object) => Promise<any> }} [opts]
+ *   Optional persistFn is called (fire-and-forget) after conflict state changes.
+ * @returns {object}
+ */
+export function createConflictController({ persistFn } = {}) {
+  /**
+   * Fire-and-forget persistence helper.
+   * @param {object} resource
+   */
+  function persist(resource) {
+    if (typeof persistFn === 'function') {
+      Promise.resolve(persistFn(resource)).catch(() => {});
+    }
+  }
+
+  return {
+    role: 'conflict-controller',
+
+    /**
+     * Detect a conflict between local and external field values.
+     * Returns { conflict: null } when values match (no conflict).
+     * Returns { conflict: ExternalSyncConflict } when values differ.
+     *
+     * @param {{ resourceRef, fieldPath, localValue, externalValue, namespace?, organizationRef? }} input
+     * @returns {{ conflict: object|null }}
+     */
+    detectConflict({
+      resourceRef,
+      fieldPath,
+      localValue,
+      externalValue,
+      namespace = 'default',
+      organizationRef = 'default'
+    }) {
+      const validation = validateConflict({ resourceRef, fieldPath });
+      if (!validation.valid) {
+        return { conflict: null, error: true, message: validation.errors.join('; ') };
+      }
+
+      // Values match — no conflict
+      if (localValue === externalValue) {
+        return { conflict: null };
+      }
+
+      const now = new Date().toISOString();
+      const conflictName = `conflict-${resourceRef.replace(/[^a-zA-Z0-9]/g, '-')}-${fieldPath.replace(/[^a-zA-Z0-9]/g, '-')}-${Date.now()}`;
+
+      const conflict = createResource('ExternalSyncConflict', { name: conflictName, namespace }, {
+        organizationRef,
+        resourceRef,
+        fieldPath,
+        localValue,
+        externalValue,
+        detectedAt: now
+      });
+      conflict.status = {
+        phase: 'Open',
+        detectedAt: now
+      };
+
+      persist(conflict);
+      return { conflict };
+    },
+
+    /**
+     * Resolve an Open conflict using the specified strategy.
+     *
+     * Strategies:
+     *   - prefer-external: choose externalValue, phase → Resolved
+     *   - prefer-krate:    choose localValue, phase → Resolved
+     *   - manual:          choose resolvedValue, phase → Resolved (requires resolvedValue)
+     *   - ignore:          phase → Ignored (no value chosen)
+     *
+     * @param {{ conflictName, strategy, resolvedValue?, resources }} opts
+     * @returns {{ conflict: object, resolution: object } | { error: true, message: string }}
+     */
+    resolveConflict({ conflictName, strategy, resolvedValue, resources = {} }) {
+      if (!conflictName) {
+        return { error: true, reason: 'missing-name', message: 'conflictName is required' };
+      }
+      if (!strategy || !VALID_STRATEGIES.includes(strategy)) {
+        return {
+          error: true,
+          reason: 'invalid-strategy',
+          message: `strategy must be one of: ${VALID_STRATEGIES.join(', ')}`
+        };
+      }
+
+      const conflicts = resources.ExternalSyncConflict || [];
+      const found = conflicts.find((c) => c.metadata?.name === conflictName);
+      if (!found) {
+        return { error: true, reason: 'not-found', message: `ExternalSyncConflict not found: ${conflictName}` };
+      }
+      if (found.status?.phase !== 'Open') {
+        return { error: true, reason: 'invalid-phase', message: `Conflict is not Open: ${found.status?.phase}` };
+      }
+
+      const updated = clone(found);
+      const now = new Date().toISOString();
+      let chosenValue;
+      let newPhase;
+
+      if (strategy === 'ignore') {
+        newPhase = 'Ignored';
+        chosenValue = undefined;
+      } else {
+        newPhase = 'Resolved';
+        if (strategy === 'prefer-external') {
+          chosenValue = found.spec.externalValue;
+        } else if (strategy === 'prefer-krate') {
+          chosenValue = found.spec.localValue;
+        } else if (strategy === 'manual') {
+          if (resolvedValue === undefined) {
+            return { error: true, reason: 'missing-resolved-value', message: 'resolvedValue is required for manual strategy' };
+          }
+          chosenValue = resolvedValue;
+        }
+      }
+
+      updated.status = {
+        ...updated.status,
+        phase: newPhase,
+        resolvedAt: now,
+        strategy,
+        chosenValue
+      };
+
+      const resolution = { strategy, chosenValue };
+
+      persist(updated);
+      return { conflict: updated, resolution };
+    },
+
+    /**
+     * Mark all Open conflicts for a given (resourceRef, fieldPath) pair as Superseded.
+     * Used when a new sync event arrives that makes old conflicts irrelevant.
+     *
+     * @param {{ resourceRef, fieldPath, resources }} opts
+     * @returns {{ superseded: object[] }}
+     */
+    supersededCheck({ resourceRef, fieldPath, resources = {} }) {
+      const conflicts = resources.ExternalSyncConflict || [];
+      const now = new Date().toISOString();
+
+      const superseded = [];
+      for (const c of conflicts) {
+        if (
+          c.spec?.resourceRef === resourceRef &&
+          c.spec?.fieldPath === fieldPath &&
+          c.status?.phase === 'Open'
+        ) {
+          const updated = clone(c);
+          updated.status = {
+            ...updated.status,
+            phase: 'Superseded',
+            supersededAt: now
+          };
+          superseded.push(updated);
+        }
+      }
+
+      return { superseded };
+    },
+
+    /**
+     * Return all Open (non-resolved, non-ignored, non-superseded) conflicts.
+     *
+     * @param {{ resources }} opts
+     * @returns {{ conflicts: object[] }}
+     */
+    getOpenConflicts({ resources = {} } = {}) {
+      const conflicts = resources.ExternalSyncConflict || [];
+      const open = conflicts.filter((c) => OPEN_PHASES.has(c.status?.phase));
+      return { conflicts: open };
+    }
+  };
+}

package/src/external/github/auth.js

@@ -0,0 +1,96 @@
+// GitHub App authentication helpers — Slice 3.3a
+// Provides JWT signing (HMAC-SHA256 for test, RSA-SHA256 for production)
+// and installation token exchange. No external dependencies; uses node:crypto.
+
+import { createHmac, createSign } from 'node:crypto';
+
+const GITHUB_API = 'https://api.github.com';
+
+/**
+ * Encode a value as Base64url (RFC 4648 §5, no padding).
+ * @param {string|Buffer} data
+ * @returns {string}
+ */
+function b64url(data) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+  return buf.toString('base64url');
+}
+
+/**
+ * Create a GitHub App JWT.
+ *
+ * In production, pass a PEM-encoded RSA private key and the function will
+ * use RS256. For unit tests, pass any string key; if it does not look like
+ * a PEM file the function falls back to HS256 (HMAC-SHA256) so tests can
+ * run without real RSA keys.
+ *
+ * @param {{ appId: string, privateKey: string, expiresInSeconds?: number }} opts
+ * @returns {Promise<string>} A signed JWT string.
+ */
+export async function createGitHubJwt({ appId, privateKey, expiresInSeconds = 600 } = {}) {
+  if (!appId) throw new Error('createGitHubJwt: appId is required');
+  if (!privateKey) throw new Error('createGitHubJwt: privateKey is required');
+
+  const now = Math.floor(Date.now() / 1000);
+  const isRsa = privateKey.includes('-----BEGIN');
+
+  const alg = isRsa ? 'RS256' : 'HS256';
+
+  const header = b64url(JSON.stringify({ alg, typ: 'JWT' }));
+  const payload = b64url(JSON.stringify({
+    iat: now,
+    exp: now + expiresInSeconds,
+    iss: appId
+  }));
+
+  const signingInput = `${header}.${payload}`;
+
+  let signature;
+  if (isRsa) {
+    const sign = createSign('RSA-SHA256');
+    sign.update(signingInput);
+    sign.end();
+    signature = sign.sign(privateKey, 'base64url');
+  } else {
+    // HMAC-SHA256 fallback (test mode only)
+    const hmac = createHmac('sha256', privateKey);
+    hmac.update(signingInput);
+    signature = hmac.digest('base64url');
+  }
+
+  return `${signingInput}.${signature}`;
+}
+
+/**
+ * Exchange a GitHub App JWT for an installation access token.
+ *
+ * @param {{ appJwt: string, installationId: string|number, fetchImpl?: Function }} opts
+ * @returns {Promise<{ token: string, expiresAt: string }>}
+ */
+export async function exchangeInstallationToken({ appJwt, installationId, fetchImpl = globalThis.fetch } = {}) {
+  if (!appJwt) throw new Error('exchangeInstallationToken: appJwt is required');
+  if (!installationId) throw new Error('exchangeInstallationToken: installationId is required');
+  if (!fetchImpl) throw new Error('exchangeInstallationToken: a fetch implementation is required');
+
+  const url = `${GITHUB_API}/app/installations/${installationId}/access_tokens`;
+
+  const response = await fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${appJwt}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      'Content-Type': 'application/json'
+    }
+  });
+
+  if (!response.ok) {
+    throw new Error(`exchangeInstallationToken: GitHub API returned ${response.status} — authentication or token exchange failed`);
+  }
+
+  const data = await response.json();
+  return {
+    token: data.token,
+    expiresAt: data.expires_at
+  };
+}