fix(skills): pull upstream skill runtime resolution to stop event-loop starvation

The fork's listRuntimeSkillEntries rematerialized every skill's files from
the DB on every heartbeat run dispatch — fs.rm + fs.mkdir + per-file
readFile/writeFile, sequentially per skill. With 24 configured skills and
5 concurrent agents, this saturated the Node event loop badly enough that
executeRun continuations couldn't reach activeRunExecutions.add() within
the orphan-reaper's 5-min threshold, causing reaper to false-positive runs
as "process_lost".

Upstream's listRuntimeSkillEntries calls resolveRuntimeSkillSource, which
checks if the materialized directory already exists on disk and short-
circuits when it does. Fixes the symptom at the root.

Replaces these files with upstream/master content:
  - server/src/services/company-skills.ts
  - server/src/services/heartbeat.ts
  - server/src/services/workspace-runtime.ts
  - server/src/services/company-portability.ts
  - server/src/routes/company-skills.ts
  - server/src/routes/agents.ts
  - packages/adapter-utils/src/server-utils.ts

Pulls in supporting upstream files:
  - server/src/services/catalog-provenance.ts
  - server/src/services/skills-catalog.ts
  - server/src/services/github-fetch.ts
  - server/src/services/portable-path.ts
  - packages/skills-catalog/ (new package)
  - packages/db document_annotation_* schema + migration 0091
  - packages/shared document-annotation types/validators

Drops fork features (to be re-evaluated later):
  - Gitea/Forgejo git skill sources (server/src/services/git-source.ts deleted)
  - PAT support for private skill repos
  - Fork-specific secret-export portability extensions

Adds agentId: null to acquireRunLease test-probe call in routes/agents.ts
to satisfy the fork's environment-runtime agentId requirement (kept).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/shared/src/constants.ts

@@ -281,6 +281,22 @@ export function isSystemIssueDocumentKey(key: string): key is SystemIssueDocumen
 export const ISSUE_REFERENCE_SOURCE_KINDS = ["title", "description", "comment", "document"] as const;
 export type IssueReferenceSourceKind = (typeof ISSUE_REFERENCE_SOURCE_KINDS)[number];
 
+export const DOCUMENT_ANNOTATION_THREAD_STATUSES = ["open", "resolved"] as const;
+export type DocumentAnnotationThreadStatus = (typeof DOCUMENT_ANNOTATION_THREAD_STATUSES)[number];
+
+export const DOCUMENT_ANNOTATION_ANCHOR_STATES = ["active", "stale", "orphaned"] as const;
+export type DocumentAnnotationAnchorState = (typeof DOCUMENT_ANNOTATION_ANCHOR_STATES)[number];
+
+export const DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES = [
+  "exact",
+  "duplicate",
+  "fuzzy",
+  "ambiguous",
+  "missing",
+] as const;
+export type DocumentAnnotationAnchorConfidence =
+  (typeof DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES)[number];
+
 export const ISSUE_EXECUTION_POLICY_MODES = ["normal", "auto"] as const;
 export type IssueExecutionPolicyMode = (typeof ISSUE_EXECUTION_POLICY_MODES)[number];
 

packages/shared/src/document-anchors.ts

@@ -0,0 +1,464 @@
+import type {
+  DocumentAnnotationAnchorConfidence,
+  DocumentAnnotationAnchorState,
+} from "./constants.js";
+import type {
+  DocumentAnnotationAnchorSelector,
+  DocumentAnnotationAnchorSnapshot,
+  DocumentTextPosition,
+  DocumentTextProjection,
+  DocumentTextRange,
+} from "./types/document-annotation.js";
+
+export interface CreateDocumentAnchorSelectorOptions {
+  contextLength?: number;
+}
+
+export interface VerifyDocumentAnchorSelectorInput {
+  markdown: string;
+  selector: DocumentAnnotationAnchorSelector;
+  contextLength?: number;
+}
+
+export interface VerifyDocumentAnchorSelectorResult {
+  ok: boolean;
+  anchor: DocumentAnnotationAnchorSnapshot | null;
+  projection: DocumentTextProjection;
+  reason: "verified" | "quote_mismatch" | "position_mismatch" | "invalid_range";
+}
+
+export interface RemapDocumentAnchorInput {
+  previousAnchor: DocumentAnnotationAnchorSnapshot;
+  nextMarkdown: string;
+  contextLength?: number;
+}
+
+export interface RemapDocumentAnchorResult {
+  anchorState: DocumentAnnotationAnchorState;
+  confidence: DocumentAnnotationAnchorConfidence;
+  anchor: DocumentAnnotationAnchorSnapshot | null;
+  projection: DocumentTextProjection;
+  reason: "exact" | "duplicate" | "fuzzy" | "ambiguous" | "missing";
+}
+
+interface Candidate {
+  start: number;
+  end: number;
+  score: number;
+  reason: RemapDocumentAnchorResult["reason"];
+}
+
+const DEFAULT_CONTEXT_LENGTH = 48;
+
+export function normalizeAnchorText(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+export function projectMarkdownToText(markdown: string): DocumentTextProjection {
+  const builder = new ProjectionBuilder(markdown);
+  const lines = markdown.match(/[^\n]*(?:\n|$)/g) ?? [markdown];
+  let offset = 0;
+  let inFence = false;
+
+  for (const rawLine of lines) {
+    if (rawLine === "") continue;
+    const hasNewline = rawLine.endsWith("\n");
+    const line = hasNewline ? rawLine.slice(0, -1) : rawLine;
+    const fenceMatch = line.match(/^\s*(```+|~~~+)/);
+
+    if (fenceMatch) {
+      inFence = !inFence;
+      offset += rawLine.length;
+      builder.addSeparator(offset - (hasNewline ? 1 : 0));
+      continue;
+    }
+
+    if (inFence) {
+      builder.addText(line, offset);
+      builder.addSeparator(offset + line.length);
+      offset += rawLine.length;
+      continue;
+    }
+
+    const { text, sourceOffset } = stripBlockSyntax(line, offset);
+    addInlineMarkdownText(builder, text, sourceOffset);
+    builder.addSeparator(offset + line.length);
+    offset += rawLine.length;
+  }
+
+  return builder.toProjection();
+}
+
+export function resolveProjectionRange(
+  projection: DocumentTextProjection,
+  normalizedStart: number,
+  normalizedEnd: number,
+): DocumentTextRange | null {
+  if (
+    normalizedStart < 0
+    || normalizedEnd <= normalizedStart
+    || normalizedEnd > projection.text.length
+    || normalizedStart >= projection.positions.length
+    || normalizedEnd - 1 >= projection.positions.length
+  ) {
+    return null;
+  }
+
+  return {
+    text: projection.text.slice(normalizedStart, normalizedEnd),
+    normalizedStart,
+    normalizedEnd,
+    markdownStart: projection.positions[normalizedStart]?.sourceStart ?? 0,
+    markdownEnd: projection.positions[normalizedEnd - 1]?.sourceEnd ?? 0,
+  };
+}
+
+export function createDocumentAnchorSelector(
+  projection: DocumentTextProjection,
+  range: DocumentTextRange,
+  options: CreateDocumentAnchorSelectorOptions = {},
+): DocumentAnnotationAnchorSelector {
+  const contextLength = options.contextLength ?? DEFAULT_CONTEXT_LENGTH;
+  return {
+    quote: {
+      exact: range.text,
+      prefix: projection.text.slice(Math.max(0, range.normalizedStart - contextLength), range.normalizedStart),
+      suffix: projection.text.slice(range.normalizedEnd, range.normalizedEnd + contextLength),
+    },
+    position: {
+      normalizedStart: range.normalizedStart,
+      normalizedEnd: range.normalizedEnd,
+      markdownStart: range.markdownStart,
+      markdownEnd: range.markdownEnd,
+    },
+  };
+}
+
+export function selectorToAnchorSnapshot(selector: DocumentAnnotationAnchorSelector): DocumentAnnotationAnchorSnapshot {
+  return {
+    selectedText: selector.quote.exact,
+    prefixText: selector.quote.prefix,
+    suffixText: selector.quote.suffix,
+    normalizedStart: selector.position.normalizedStart,
+    normalizedEnd: selector.position.normalizedEnd,
+    markdownStart: selector.position.markdownStart,
+    markdownEnd: selector.position.markdownEnd,
+  };
+}
+
+export function anchorSnapshotToSelector(anchor: DocumentAnnotationAnchorSnapshot): DocumentAnnotationAnchorSelector {
+  return {
+    quote: {
+      exact: anchor.selectedText,
+      prefix: anchor.prefixText,
+      suffix: anchor.suffixText,
+    },
+    position: {
+      normalizedStart: anchor.normalizedStart,
+      normalizedEnd: anchor.normalizedEnd,
+      markdownStart: anchor.markdownStart,
+      markdownEnd: anchor.markdownEnd,
+    },
+  };
+}
+
+export function verifyDocumentAnchorSelector(
+  input: VerifyDocumentAnchorSelectorInput,
+): VerifyDocumentAnchorSelectorResult {
+  const projection = projectMarkdownToText(input.markdown);
+  const range = resolveProjectionRange(
+    projection,
+    input.selector.position.normalizedStart,
+    input.selector.position.normalizedEnd,
+  );
+  if (!range) {
+    return { ok: false, anchor: null, projection, reason: "invalid_range" };
+  }
+
+  if (normalizeAnchorText(range.text) !== normalizeAnchorText(input.selector.quote.exact)) {
+    return { ok: false, anchor: null, projection, reason: "quote_mismatch" };
+  }
+
+  if (
+    range.markdownStart !== input.selector.position.markdownStart
+    || range.markdownEnd !== input.selector.position.markdownEnd
+  ) {
+    return { ok: false, anchor: null, projection, reason: "position_mismatch" };
+  }
+
+  const selector = createDocumentAnchorSelector(projection, range, {
+    contextLength: input.contextLength ?? DEFAULT_CONTEXT_LENGTH,
+  });
+  return { ok: true, anchor: selectorToAnchorSnapshot(selector), projection, reason: "verified" };
+}
+
+export function remapDocumentAnchor(input: RemapDocumentAnchorInput): RemapDocumentAnchorResult {
+  const projection = projectMarkdownToText(input.nextMarkdown);
+  const contextLength = input.contextLength ?? DEFAULT_CONTEXT_LENGTH;
+  const quote = normalizeAnchorText(input.previousAnchor.selectedText);
+  if (!quote) {
+    return { anchorState: "orphaned", confidence: "missing", anchor: null, projection, reason: "missing" };
+  }
+
+  const exactCandidates = findOccurrences(projection.text, quote).map((start) => scoreCandidate({
+    projection,
+    start,
+    end: start + quote.length,
+    previousAnchor: input.previousAnchor,
+    reason: "exact",
+    contextLength,
+  }));
+
+  if (exactCandidates.length > 0) {
+    exactCandidates.sort((a, b) => b.score - a.score);
+    const [best, second] = exactCandidates;
+    if (exactCandidates.length > 1 && (!second || Math.abs(best.score - second.score) < 0.05)) {
+      return {
+        anchorState: "stale",
+        confidence: "ambiguous",
+        anchor: buildAnchorSnapshot(projection, best.start, best.end, contextLength),
+        projection,
+        reason: "ambiguous",
+      };
+    }
+    return {
+      anchorState: "active",
+      confidence: exactCandidates.length === 1 ? "exact" : "duplicate",
+      anchor: buildAnchorSnapshot(projection, best.start, best.end, contextLength),
+      projection,
+      reason: exactCandidates.length === 1 ? "exact" : "duplicate",
+    };
+  }
+
+  const fuzzy = findFuzzyCandidate(projection, input.previousAnchor, contextLength);
+  if (fuzzy && fuzzy.score >= 0.58) {
+    return {
+      anchorState: "stale",
+      confidence: "fuzzy",
+      anchor: buildAnchorSnapshot(projection, fuzzy.start, fuzzy.end, contextLength),
+      projection,
+      reason: "fuzzy",
+    };
+  }
+
+  return { anchorState: "orphaned", confidence: "missing", anchor: null, projection, reason: "missing" };
+}
+
+function stripBlockSyntax(line: string, absoluteOffset: number): { text: string; sourceOffset: number } {
+  const blockMatch = line.match(/^\s{0,3}(?:(#{1,6})\s+|(?:[-+*]|\d+[.)])\s+|>\s?)/);
+  if (!blockMatch) return { text: line, sourceOffset: absoluteOffset };
+  return { text: line.slice(blockMatch[0].length), sourceOffset: absoluteOffset + blockMatch[0].length };
+}
+
+function addInlineMarkdownText(builder: ProjectionBuilder, text: string, sourceOffset: number): void {
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index] ?? "";
+    const absolute = sourceOffset + index;
+    const rest = text.slice(index);
+
+    const image = rest.match(/^!\[([^\]]*)\]\(([^)]*)\)/);
+    if (image) {
+      const altStart = absolute + 2;
+      builder.addText(image[1] ?? "", altStart);
+      index += image[0].length - 1;
+      continue;
+    }
+
+    const link = rest.match(/^\[([^\]]+)\]\(([^)]*)\)/);
+    if (link) {
+      const labelStart = absolute + 1;
+      builder.addText(link[1] ?? "", labelStart);
+      index += link[0].length - 1;
+      continue;
+    }
+
+    if (char === "`") {
+      const closing = text.indexOf("`", index + 1);
+      if (closing > index + 1) {
+        builder.addText(text.slice(index + 1, closing), absolute + 1);
+        index = closing;
+        continue;
+      }
+    }
+
+    if (char === "|" || char === "\t") {
+      builder.addSeparator(absolute);
+      continue;
+    }
+
+    if (isMarkdownFormattingChar(char, text, index)) continue;
+
+    builder.addChar(char, absolute, absolute + 1);
+  }
+}
+
+function isMarkdownFormattingChar(char: string, text: string, index: number): boolean {
+  if (char === "*" || char === "_" || char === "~") return true;
+  if (char === "\\" && index + 1 < text.length) return true;
+  return false;
+}
+
+function findOccurrences(text: string, quote: string): number[] {
+  const starts: number[] = [];
+  let start = text.indexOf(quote);
+  while (start !== -1) {
+    starts.push(start);
+    start = text.indexOf(quote, start + 1);
+  }
+  return starts;
+}
+
+function scoreCandidate(args: {
+  projection: DocumentTextProjection;
+  start: number;
+  end: number;
+  previousAnchor: DocumentAnnotationAnchorSnapshot;
+  reason: Candidate["reason"];
+  contextLength: number;
+}): Candidate {
+  const before = args.projection.text.slice(Math.max(0, args.start - args.contextLength), args.start);
+  const after = args.projection.text.slice(args.end, args.end + args.contextLength);
+  const prefixScore = suffixOverlapScore(args.previousAnchor.prefixText, before);
+  const suffixScore = prefixOverlapScore(args.previousAnchor.suffixText, after);
+  const distance = Math.abs(args.start - args.previousAnchor.normalizedStart);
+  const proximity = 1 / (1 + distance / 200);
+  return {
+    start: args.start,
+    end: args.end,
+    score: prefixScore * 0.35 + suffixScore * 0.35 + proximity * 0.3,
+    reason: args.reason,
+  };
+}
+
+function findFuzzyCandidate(
+  projection: DocumentTextProjection,
+  previousAnchor: DocumentAnnotationAnchorSnapshot,
+  contextLength: number,
+): Candidate | null {
+  const words = normalizeAnchorText(previousAnchor.selectedText).split(" ").filter(Boolean);
+  if (words.length === 0) return null;
+  const textWords = [...projection.text.matchAll(/\S+/g)].map((match) => ({
+    text: match[0],
+    start: match.index ?? 0,
+    end: (match.index ?? 0) + match[0].length,
+  }));
+  const windowSizes = new Set([words.length - 1, words.length, words.length + 1, words.length + 2].filter((n) => n > 0));
+  let best: Candidate | null = null;
+
+  for (const size of windowSizes) {
+    for (let index = 0; index + size <= textWords.length; index += 1) {
+      const window = textWords.slice(index, index + size);
+      const candidateText = window.map((word) => word.text).join(" ");
+      const similarity = similarityScore(normalizeAnchorText(previousAnchor.selectedText), candidateText);
+      if (similarity < 0.45) continue;
+      const scored = scoreCandidate({
+        projection,
+        start: window[0]?.start ?? 0,
+        end: window[window.length - 1]?.end ?? 0,
+        previousAnchor,
+        reason: "fuzzy",
+        contextLength,
+      });
+      scored.score = scored.score * 0.35 + similarity * 0.65;
+      if (!best || scored.score > best.score) best = scored;
+    }
+  }
+
+  return best;
+}
+
+function buildAnchorSnapshot(
+  projection: DocumentTextProjection,
+  normalizedStart: number,
+  normalizedEnd: number,
+  contextLength: number,
+): DocumentAnnotationAnchorSnapshot {
+  const range = resolveProjectionRange(projection, normalizedStart, normalizedEnd);
+  if (!range) {
+    return {
+      selectedText: "",
+      prefixText: "",
+      suffixText: "",
+      normalizedStart,
+      normalizedEnd,
+      markdownStart: 0,
+      markdownEnd: 0,
+    };
+  }
+  const selector = createDocumentAnchorSelector(projection, range, { contextLength });
+  return selectorToAnchorSnapshot(selector);
+}
+
+function prefixOverlapScore(expectedPrefix: string, actualPrefix: string): number {
+  const expected = normalizeAnchorText(expectedPrefix);
+  const actual = normalizeAnchorText(actualPrefix);
+  if (!expected) return 0.5;
+  for (let size = Math.min(expected.length, actual.length); size > 0; size -= 1) {
+    if (expected.slice(0, size) === actual.slice(0, size)) return size / expected.length;
+  }
+  return 0;
+}
+
+function suffixOverlapScore(expectedPrefix: string, actualPrefix: string): number {
+  const expected = normalizeAnchorText(expectedPrefix);
+  const actual = normalizeAnchorText(actualPrefix);
+  if (!expected) return 0.5;
+  for (let size = Math.min(expected.length, actual.length); size > 0; size -= 1) {
+    if (expected.slice(-size) === actual.slice(-size)) return size / expected.length;
+  }
+  return 0;
+}
+
+function similarityScore(left: string, right: string): number {
+  if (left === right) return 1;
+  const leftWords = new Set(left.toLowerCase().split(/\s+/).filter(Boolean));
+  const rightWords = new Set(right.toLowerCase().split(/\s+/).filter(Boolean));
+  const intersection = [...leftWords].filter((word) => rightWords.has(word)).length;
+  const union = new Set([...leftWords, ...rightWords]).size || 1;
+  const jaccard = intersection / union;
+  const lengthRatio = Math.min(left.length, right.length) / Math.max(left.length, right.length, 1);
+  return jaccard * 0.75 + lengthRatio * 0.25;
+}
+
+class ProjectionBuilder {
+  private text = "";
+  private positions: DocumentTextPosition[] = [];
+  private pendingSpace: DocumentTextPosition | null = null;
+
+  constructor(private readonly source: string) {}
+
+  addText(text: string, sourceOffset: number): void {
+    for (let index = 0; index < text.length; index += 1) {
+      this.addChar(text[index] ?? "", sourceOffset + index, sourceOffset + index + 1);
+    }
+  }
+
+  addSeparator(sourceOffset: number): void {
+    this.addChar(" ", sourceOffset, sourceOffset + 1);
+  }
+
+  addChar(char: string, sourceStart: number, sourceEnd: number): void {
+    if (/\s/.test(char)) {
+      if (this.text.length > 0 && !this.pendingSpace) {
+        this.pendingSpace = { sourceStart, sourceEnd };
+      }
+      return;
+    }
+
+    if (this.pendingSpace && this.text.length > 0) {
+      this.text += " ";
+      this.positions.push(this.pendingSpace);
+    }
+    this.pendingSpace = null;
+    this.text += char;
+    this.positions.push({ sourceStart, sourceEnd });
+  }
+
+  toProjection(): DocumentTextProjection {
+    return {
+      source: this.source,
+      text: this.text,
+      positions: this.positions,
+    };
+  }
+}

packages/shared/src/index.ts

@@ -45,6 +45,9 @@ export {
   SYSTEM_ISSUE_DOCUMENT_KEYS,
   isSystemIssueDocumentKey,
   ISSUE_REFERENCE_SOURCE_KINDS,
+  DOCUMENT_ANNOTATION_THREAD_STATUSES,
+  DOCUMENT_ANNOTATION_ANCHOR_STATES,
+  DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES,
   ISSUE_EXECUTION_POLICY_MODES,
   ISSUE_EXECUTION_STAGE_TYPES,
   ISSUE_MONITOR_SCHEDULED_BY,
@@ -164,6 +167,9 @@ export {
   type IssueTreeHoldStatus,
   type SystemIssueDocumentKey,
   type IssueReferenceSourceKind,
+  type DocumentAnnotationThreadStatus,
+  type DocumentAnnotationAnchorState,
+  type DocumentAnnotationAnchorConfidence,
   type IssueExecutionPolicyMode,
   type IssueExecutionStageType,
   type IssueMonitorScheduledBy,
@@ -290,6 +296,13 @@ export type {
   CompanySkillUsageAgent,
   CompanySkillDetail,
   CompanySkillUpdateStatus,
+  CompanySkillAuditSeverity,
+  CompanySkillAuditVerdict,
+  CompanySkillUpdateHoldReason,
+  CompanySkillAuditFinding,
+  CompanySkillAuditResult,
+  CompanySkillInstallUpdateRequest,
+  CompanySkillResetRequest,
   CompanySkillImportRequest,
   CompanySkillImportResult,
   CompanySkillProjectScanRequest,
@@ -299,6 +312,14 @@ export type {
   CompanySkillCreateRequest,
   CompanySkillFileDetail,
   CompanySkillFileUpdateRequest,
+  CatalogSkillKind,
+  CatalogSkillFileKind,
+  CatalogSkillFile,
+  CatalogSkill,
+  CatalogSkillListQuery,
+  CatalogSkillFileDetail,
+  CompanySkillInstallCatalogRequest,
+  CompanySkillInstallCatalogResult,
   AgentSkillSyncMode,
   AgentSkillState,
   AgentSkillOrigin,
@@ -376,6 +397,20 @@ export type {
   IssueWorkProductProvider,
   IssueWorkProductStatus,
   IssueWorkProductReviewState,
+  CreateDocumentAnnotationCommentRequest,
+  CreateDocumentAnnotationThreadRequest,
+  DocumentAnnotationAnchorRemapSnapshot,
+  DocumentAnnotationAnchorSelector,
+  DocumentAnnotationAnchorSnapshot,
+  DocumentAnnotationComment,
+  DocumentAnnotationTextPositionSelector,
+  DocumentAnnotationTextQuoteSelector,
+  DocumentAnnotationThread,
+  DocumentAnnotationThreadWithComments,
+  DocumentTextPosition,
+  DocumentTextProjection,
+  DocumentTextRange,
+  UpdateDocumentAnnotationThreadRequest,
   Issue,
   IssueAssigneeAdapterOverrides,
   IssueBlockerAttention,
@@ -551,7 +586,6 @@ export type {
   CompanyPortabilityImportRequest,
   CompanyPortabilityImportResult,
   CompanyPortabilityExportRequest,
-  CompanyPortabilitySecretEntry,
   EnvBinding,
   EnvPlainBinding,
   EnvSecretRefBinding,
@@ -655,6 +689,22 @@ export {
   type IssueReferenceMatch,
 } from "./issue-references.js";
 
+export {
+  anchorSnapshotToSelector,
+  createDocumentAnchorSelector,
+  normalizeAnchorText,
+  projectMarkdownToText,
+  remapDocumentAnchor,
+  resolveProjectionRange,
+  selectorToAnchorSnapshot,
+  verifyDocumentAnchorSelector,
+  type CreateDocumentAnchorSelectorOptions,
+  type RemapDocumentAnchorInput,
+  type RemapDocumentAnchorResult,
+  type VerifyDocumentAnchorSelectorInput,
+  type VerifyDocumentAnchorSelectorResult,
+} from "./document-anchors.js";
+
 export {
   sidebarOrderPreferenceSchema,
   upsertSidebarOrderPreferenceSchema,
@@ -796,6 +846,18 @@ export {
   type CreateProjectWorkspace,
   type UpdateProjectWorkspace,
   projectExecutionWorkspacePolicySchema,
+  createDocumentAnnotationCommentSchema,
+  createDocumentAnnotationThreadSchema,
+  documentAnnotationAnchorConfidenceSchema,
+  documentAnnotationAnchorSelectorSchema,
+  documentAnnotationAnchorStateSchema,
+  documentAnnotationTextPositionSelectorSchema,
+  documentAnnotationTextQuoteSelectorSchema,
+  documentAnnotationThreadStatusSchema,
+  updateDocumentAnnotationThreadSchema,
+  type CreateDocumentAnnotationComment,
+  type CreateDocumentAnnotationThread,
+  type UpdateDocumentAnnotationThread,
   companySearchQuerySchema,
   COMPANY_SEARCH_DEFAULT_LIMIT,
   COMPANY_SEARCH_MAX_LIMIT,
@@ -1013,8 +1075,9 @@ export {
   companySkillUsageAgentSchema,
   companySkillDetailSchema,
   companySkillUpdateStatusSchema,
+  companySkillAuditFindingSchema,
+  companySkillAuditResultSchema,
   companySkillImportSchema,
-  companySkillUpdateAuthSchema,
   companySkillProjectScanRequestSchema,
   companySkillProjectScanSkippedSchema,
   companySkillProjectScanConflictSchema,
@@ -1022,6 +1085,15 @@ export {
   companySkillCreateSchema,
   companySkillFileDetailSchema,
   companySkillFileUpdateSchema,
+  catalogSkillKindSchema,
+  catalogSkillFileSchema,
+  catalogSkillSchema,
+  catalogSkillListQuerySchema,
+  catalogSkillFileDetailSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
   portabilityIncludeSchema,
   portabilityEnvInputSchema,
   portabilityCompanyManifestEntrySchema,

packages/shared/src/types/company-skill.ts

@@ -51,6 +51,10 @@ export interface CompanySkillListItem {
   sourceLabel: string | null;
   sourceBadge: CompanySkillSourceBadge;
   sourcePath: string | null;
+  catalogKind: "bundled" | "optional" | null;
+  originHash: string | null;
+  packageName: string | null;
+  packageVersion: string | null;
 }
 
 export interface CompanySkillUsageAgent {
@@ -84,6 +88,49 @@ export interface CompanySkillUpdateStatus {
   currentRef: string | null;
   latestRef: string | null;
   hasUpdate: boolean;
+  installedHash: string | null;
+  originHash: string | null;
+  userModifiedAt: string | null;
+  updateHoldReason: CompanySkillUpdateHoldReason | null;
+  auditVerdict: CompanySkillAuditVerdict | null;
+  auditCodes: string[];
+}
+
+export type CompanySkillAuditSeverity = "warning" | "error";
+
+export type CompanySkillAuditVerdict = "pass" | "warning" | "fail";
+
+export type CompanySkillUpdateHoldReason =
+  | "local_modifications"
+  | "audit_hard_stop"
+  | "origin_unavailable"
+  | "compatibility_invalid"
+  | "operator_hold";
+
+export interface CompanySkillAuditFinding {
+  code: string;
+  severity: CompanySkillAuditSeverity;
+  message: string;
+  path: string | null;
+}
+
+export interface CompanySkillAuditResult {
+  skillId: string;
+  installedHash: string | null;
+  originHash: string | null;
+  verdict: CompanySkillAuditVerdict;
+  codes: string[];
+  findings: CompanySkillAuditFinding[];
+  scannedAt: string;
+  scanVersion: string;
+}
+
+export interface CompanySkillInstallUpdateRequest {
+  force?: boolean;
+}
+
+export interface CompanySkillResetRequest {
+  force?: boolean;
 }
 
 export interface CompanySkillImportRequest {
@@ -155,3 +202,64 @@ export interface CompanySkillFileUpdateRequest {
   path: string;
   content: string;
 }
+
+export type CatalogSkillKind = "bundled" | "optional";
+
+export type CatalogSkillFileKind = CompanySkillFileInventoryEntry["kind"];
+
+export interface CatalogSkillFile {
+  path: string;
+  kind: CatalogSkillFileKind;
+  sizeBytes: number;
+  sha256: string;
+}
+
+export interface CatalogSkill {
+  id: string;
+  key: string;
+  kind: CatalogSkillKind;
+  category: string;
+  slug: string;
+  name: string;
+  description: string;
+  path: string;
+  entrypoint: "SKILL.md";
+  trustLevel: CompanySkillTrustLevel;
+  compatibility: CompanySkillCompatibility;
+  defaultInstall: boolean;
+  recommendedForRoles: string[];
+  requires: string[];
+  tags: string[];
+  files: CatalogSkillFile[];
+  contentHash: string;
+  packageName?: string;
+  packageVersion?: string;
+}
+
+export interface CatalogSkillListQuery {
+  kind?: CatalogSkillKind;
+  category?: string;
+  q?: string;
+}
+
+export interface CatalogSkillFileDetail {
+  catalogSkillId: string;
+  path: string;
+  kind: CatalogSkillFileKind;
+  content: string;
+  language: string | null;
+  markdown: boolean;
+}
+
+export interface CompanySkillInstallCatalogRequest {
+  catalogSkillId: string;
+  slug?: string | null;
+  force?: boolean;
+}
+
+export interface CompanySkillInstallCatalogResult {
+  action: "created" | "updated" | "unchanged";
+  skill: CompanySkill;
+  catalogSkill: CatalogSkill;
+  warnings: string[];
+}

packages/shared/src/types/document-annotation.ts

@@ -0,0 +1,134 @@
+import type {
+  DocumentAnnotationAnchorConfidence,
+  DocumentAnnotationAnchorState,
+  DocumentAnnotationThreadStatus,
+  IssueCommentAuthorType,
+} from "../constants.js";
+
+export interface DocumentTextPosition {
+  sourceStart: number;
+  sourceEnd: number;
+}
+
+export interface DocumentTextProjection {
+  source: string;
+  text: string;
+  positions: DocumentTextPosition[];
+}
+
+export interface DocumentTextRange {
+  text: string;
+  normalizedStart: number;
+  normalizedEnd: number;
+  markdownStart: number;
+  markdownEnd: number;
+}
+
+export interface DocumentAnnotationTextQuoteSelector {
+  exact: string;
+  prefix: string;
+  suffix: string;
+}
+
+export interface DocumentAnnotationTextPositionSelector {
+  normalizedStart: number;
+  normalizedEnd: number;
+  markdownStart: number;
+  markdownEnd: number;
+}
+
+export interface DocumentAnnotationAnchorSelector {
+  quote: DocumentAnnotationTextQuoteSelector;
+  position: DocumentAnnotationTextPositionSelector;
+}
+
+export interface DocumentAnnotationAnchorSnapshot {
+  selectedText: string;
+  prefixText: string;
+  suffixText: string;
+  normalizedStart: number;
+  normalizedEnd: number;
+  markdownStart: number;
+  markdownEnd: number;
+}
+
+export interface DocumentAnnotationThread {
+  id: string;
+  companyId: string;
+  issueId: string;
+  documentId: string;
+  documentKey: string;
+  status: DocumentAnnotationThreadStatus;
+  anchorState: DocumentAnnotationAnchorState;
+  anchorConfidence: DocumentAnnotationAnchorConfidence;
+  originalRevisionId: string | null;
+  originalRevisionNumber: number;
+  currentRevisionId: string | null;
+  currentRevisionNumber: number;
+  selectedText: string;
+  prefixText: string;
+  suffixText: string;
+  normalizedStart: number;
+  normalizedEnd: number;
+  markdownStart: number;
+  markdownEnd: number;
+  anchorSelector: DocumentAnnotationAnchorSelector;
+  createdByAgentId: string | null;
+  createdByUserId: string | null;
+  resolvedByAgentId: string | null;
+  resolvedByUserId: string | null;
+  resolvedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface DocumentAnnotationComment {
+  id: string;
+  companyId: string;
+  threadId: string;
+  issueId: string;
+  documentId: string;
+  body: string;
+  authorType: IssueCommentAuthorType;
+  authorAgentId: string | null;
+  authorUserId: string | null;
+  createdByRunId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface DocumentAnnotationAnchorRemapSnapshot {
+  id: string;
+  companyId: string;
+  threadId: string;
+  documentId: string;
+  fromRevisionId: string | null;
+  fromRevisionNumber: number | null;
+  toRevisionId: string | null;
+  toRevisionNumber: number;
+  previousAnchor: DocumentAnnotationAnchorSnapshot;
+  nextAnchor: DocumentAnnotationAnchorSnapshot | null;
+  anchorState: DocumentAnnotationAnchorState;
+  anchorConfidence: DocumentAnnotationAnchorConfidence;
+  failureReason: string | null;
+  createdAt: Date;
+}
+
+export interface DocumentAnnotationThreadWithComments extends DocumentAnnotationThread {
+  comments: DocumentAnnotationComment[];
+}
+
+export interface CreateDocumentAnnotationThreadRequest {
+  baseRevisionId: string;
+  baseRevisionNumber: number;
+  selector: DocumentAnnotationAnchorSelector;
+  body: string;
+}
+
+export interface CreateDocumentAnnotationCommentRequest {
+  body: string;
+}
+
+export interface UpdateDocumentAnnotationThreadRequest {
+  status?: DocumentAnnotationThreadStatus;
+}

packages/shared/src/types/index.ts

@@ -51,6 +51,13 @@ export type {
   CompanySkillUsageAgent,
   CompanySkillDetail,
   CompanySkillUpdateStatus,
+  CompanySkillAuditSeverity,
+  CompanySkillAuditVerdict,
+  CompanySkillUpdateHoldReason,
+  CompanySkillAuditFinding,
+  CompanySkillAuditResult,
+  CompanySkillInstallUpdateRequest,
+  CompanySkillResetRequest,
   CompanySkillImportRequest,
   CompanySkillImportResult,
   CompanySkillProjectScanRequest,
@@ -60,6 +67,14 @@ export type {
   CompanySkillCreateRequest,
   CompanySkillFileDetail,
   CompanySkillFileUpdateRequest,
+  CatalogSkillKind,
+  CatalogSkillFileKind,
+  CatalogSkillFile,
+  CatalogSkill,
+  CatalogSkillListQuery,
+  CatalogSkillFileDetail,
+  CompanySkillInstallCatalogRequest,
+  CompanySkillInstallCatalogResult,
 } from "./company-skill.js";
 export type {
   AgentSkillSyncMode,
@@ -89,6 +104,22 @@ export type {
   AdapterEnvironmentTestResult,
 } from "./agent.js";
 export type { AssetImage } from "./asset.js";
+export type {
+  CreateDocumentAnnotationCommentRequest,
+  CreateDocumentAnnotationThreadRequest,
+  DocumentAnnotationAnchorRemapSnapshot,
+  DocumentAnnotationAnchorSelector,
+  DocumentAnnotationAnchorSnapshot,
+  DocumentAnnotationComment,
+  DocumentAnnotationTextPositionSelector,
+  DocumentAnnotationTextQuoteSelector,
+  DocumentAnnotationThread,
+  DocumentAnnotationThreadWithComments,
+  DocumentTextPosition,
+  DocumentTextProjection,
+  DocumentTextRange,
+  UpdateDocumentAnnotationThreadRequest,
+} from "./document-annotation.js";
 export type { Project, ProjectCodebase, ProjectCodebaseOrigin, ProjectGoalRef, ProjectManagedByPlugin, ProjectWorkspace } from "./project.js";
 export type {
   CompanySearchHighlight,
@@ -386,7 +417,6 @@ export type {
   CompanyPortabilityImportRequest,
   CompanyPortabilityImportResult,
   CompanyPortabilityExportRequest,
-  CompanyPortabilitySecretEntry,
 } from "./company-portability.js";
 export type {
   JsonSchema,

packages/shared/src/validators/company-skill.ts

@@ -35,6 +35,10 @@ export const companySkillListItemSchema = companySkillSchema.extend({
   editableReason: z.string().nullable(),
   sourceLabel: z.string().nullable(),
   sourceBadge: companySkillSourceBadgeSchema,
+  catalogKind: z.enum(["bundled", "optional"]).nullable(),
+  originHash: z.string().nullable(),
+  packageName: z.string().nullable(),
+  packageVersion: z.string().nullable(),
 });
 
 export const companySkillUsageAgentSchema = z.object({
@@ -64,15 +68,48 @@ export const companySkillUpdateStatusSchema = z.object({
   currentRef: z.string().nullable(),
   latestRef: z.string().nullable(),
   hasUpdate: z.boolean(),
+  installedHash: z.string().nullable(),
+  originHash: z.string().nullable(),
+  userModifiedAt: z.string().nullable(),
+  updateHoldReason: z.enum([
+    "local_modifications",
+    "audit_hard_stop",
+    "origin_unavailable",
+    "compatibility_invalid",
+    "operator_hold",
+  ]).nullable(),
+  auditVerdict: z.enum(["pass", "warning", "fail"]).nullable(),
+  auditCodes: z.array(z.string()),
 });
 
+export const companySkillAuditFindingSchema = z.object({
+  code: z.string().min(1),
+  severity: z.enum(["warning", "error"]),
+  message: z.string().min(1),
+  path: z.string().nullable(),
+});
+
+export const companySkillAuditResultSchema = z.object({
+  skillId: z.string().uuid(),
+  installedHash: z.string().nullable(),
+  originHash: z.string().nullable(),
+  verdict: z.enum(["pass", "warning", "fail"]),
+  codes: z.array(z.string()),
+  findings: z.array(companySkillAuditFindingSchema),
+  scannedAt: z.string().min(1),
+  scanVersion: z.string().min(1),
+});
+
+export const companySkillInstallUpdateSchema = z.object({
+  force: z.boolean().optional(),
+}).default({});
+
+export const companySkillResetSchema = z.object({
+  force: z.boolean().optional(),
+}).default({});
+
 export const companySkillImportSchema = z.object({
   source: z.string().min(1),
-  authToken: z.string().min(1).optional(),
-});
-
-export const companySkillUpdateAuthSchema = z.object({
-  authToken: z.string().min(1).nullable(),
 });
 
 export const companySkillProjectScanRequestSchema = z.object({
@@ -136,8 +173,70 @@ export const companySkillFileUpdateSchema = z.object({
   content: z.string(),
 });
 
+export const catalogSkillKindSchema = z.enum(["bundled", "optional"]);
+
+export const catalogSkillFileSchema = z.object({
+  path: z.string().min(1),
+  kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
+  sizeBytes: z.number().int().nonnegative(),
+  sha256: z.string().min(1),
+});
+
+export const catalogSkillSchema = z.object({
+  id: z.string().min(1),
+  key: z.string().min(1),
+  kind: catalogSkillKindSchema,
+  category: z.string().min(1),
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string(),
+  path: z.string().min(1),
+  entrypoint: z.literal("SKILL.md"),
+  trustLevel: companySkillTrustLevelSchema,
+  compatibility: companySkillCompatibilitySchema,
+  defaultInstall: z.boolean(),
+  recommendedForRoles: z.array(z.string()),
+  requires: z.array(z.string()),
+  tags: z.array(z.string()),
+  files: z.array(catalogSkillFileSchema),
+  contentHash: z.string().min(1),
+  packageName: z.string().min(1).optional(),
+  packageVersion: z.string().min(1).optional(),
+});
+
+export const catalogSkillListQuerySchema = z.object({
+  kind: catalogSkillKindSchema.optional(),
+  category: z.string().min(1).optional(),
+  q: z.string().min(1).optional(),
+});
+
+export const catalogSkillFileDetailSchema = z.object({
+  catalogSkillId: z.string().min(1),
+  path: z.string().min(1),
+  kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
+  content: z.string(),
+  language: z.string().nullable(),
+  markdown: z.boolean(),
+});
+
+export const companySkillInstallCatalogSchema = z.object({
+  catalogSkillId: z.string().min(1),
+  slug: z.string().min(1).nullable().optional(),
+  force: z.boolean().optional(),
+});
+
+export const companySkillInstallCatalogResultSchema = z.object({
+  action: z.enum(["created", "updated", "unchanged"]),
+  skill: companySkillSchema,
+  catalogSkill: catalogSkillSchema,
+  warnings: z.array(z.string()),
+});
+
 export type CompanySkillImport = z.infer<typeof companySkillImportSchema>;
 export type CompanySkillProjectScan = z.infer<typeof companySkillProjectScanRequestSchema>;
 export type CompanySkillCreate = z.infer<typeof companySkillCreateSchema>;
 export type CompanySkillFileUpdate = z.infer<typeof companySkillFileUpdateSchema>;
-export type CompanySkillUpdateAuth = z.infer<typeof companySkillUpdateAuthSchema>;
+export type CatalogSkillListQuery = z.infer<typeof catalogSkillListQuerySchema>;
+export type CompanySkillInstallCatalog = z.infer<typeof companySkillInstallCatalogSchema>;
+export type CompanySkillInstallUpdate = z.infer<typeof companySkillInstallUpdateSchema>;
+export type CompanySkillReset = z.infer<typeof companySkillResetSchema>;

packages/shared/src/validators/document-annotation.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import {
+  DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES,
+  DOCUMENT_ANNOTATION_ANCHOR_STATES,
+  DOCUMENT_ANNOTATION_THREAD_STATUSES,
+} from "../constants.js";
+import { multilineTextSchema } from "./text.js";
+
+export const documentAnnotationThreadStatusSchema = z.enum(DOCUMENT_ANNOTATION_THREAD_STATUSES);
+export const documentAnnotationAnchorStateSchema = z.enum(DOCUMENT_ANNOTATION_ANCHOR_STATES);
+export const documentAnnotationAnchorConfidenceSchema = z.enum(DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES);
+
+export const documentAnnotationTextQuoteSelectorSchema = z.object({
+  exact: z.string().min(1).max(10_000),
+  prefix: z.string().max(1_000).default(""),
+  suffix: z.string().max(1_000).default(""),
+}).strict();
+
+export const documentAnnotationTextPositionSelectorSchema = z.object({
+  normalizedStart: z.number().int().nonnegative(),
+  normalizedEnd: z.number().int().nonnegative(),
+  markdownStart: z.number().int().nonnegative(),
+  markdownEnd: z.number().int().nonnegative(),
+}).strict().superRefine((value, ctx) => {
+  if (value.normalizedEnd <= value.normalizedStart) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "normalizedEnd must be greater than normalizedStart",
+      path: ["normalizedEnd"],
+    });
+  }
+  if (value.markdownEnd <= value.markdownStart) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "markdownEnd must be greater than markdownStart",
+      path: ["markdownEnd"],
+    });
+  }
+});
+
+export const documentAnnotationAnchorSelectorSchema = z.object({
+  quote: documentAnnotationTextQuoteSelectorSchema,
+  position: documentAnnotationTextPositionSelectorSchema,
+}).strict();
+
+export const createDocumentAnnotationThreadSchema = z.object({
+  baseRevisionId: z.string().uuid(),
+  baseRevisionNumber: z.number().int().positive(),
+  selector: documentAnnotationAnchorSelectorSchema,
+  body: multilineTextSchema.pipe(z.string().min(1).max(20_000)),
+}).strict();
+
+export const createDocumentAnnotationCommentSchema = z.object({
+  body: multilineTextSchema.pipe(z.string().min(1).max(20_000)),
+}).strict();
+
+export const updateDocumentAnnotationThreadSchema = z.object({
+  status: documentAnnotationThreadStatusSchema.optional(),
+}).strict().refine((value) => value.status != null, {
+  message: "At least one field must be provided",
+});
+
+export type CreateDocumentAnnotationThread = z.infer<typeof createDocumentAnnotationThreadSchema>;
+export type CreateDocumentAnnotationComment = z.infer<typeof createDocumentAnnotationCommentSchema>;
+export type UpdateDocumentAnnotationThread = z.infer<typeof updateDocumentAnnotationThreadSchema>;

packages/shared/src/validators/index.ts

@@ -67,8 +67,9 @@ export {
   companySkillUsageAgentSchema,
   companySkillDetailSchema,
   companySkillUpdateStatusSchema,
+  companySkillAuditFindingSchema,
+  companySkillAuditResultSchema,
   companySkillImportSchema,
-  companySkillUpdateAuthSchema,
   companySkillProjectScanRequestSchema,
   companySkillProjectScanSkippedSchema,
   companySkillProjectScanConflictSchema,
@@ -76,11 +77,23 @@ export {
   companySkillCreateSchema,
   companySkillFileDetailSchema,
   companySkillFileUpdateSchema,
+  catalogSkillKindSchema,
+  catalogSkillFileSchema,
+  catalogSkillSchema,
+  catalogSkillListQuerySchema,
+  catalogSkillFileDetailSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
   type CompanySkillImport,
   type CompanySkillProjectScan,
   type CompanySkillCreate,
   type CompanySkillFileUpdate,
-  type CompanySkillUpdateAuth,
+  type CatalogSkillListQuery,
+  type CompanySkillInstallCatalog,
+  type CompanySkillInstallUpdate,
+  type CompanySkillReset,
 } from "./company-skill.js";
 export {
   agentSkillStateSchema,
@@ -154,6 +167,21 @@ export {
   type ProjectExecutionWorkspacePolicy,
 } from "./project.js";
 
+export {
+  createDocumentAnnotationCommentSchema,
+  createDocumentAnnotationThreadSchema,
+  documentAnnotationAnchorConfidenceSchema,
+  documentAnnotationAnchorSelectorSchema,
+  documentAnnotationAnchorStateSchema,
+  documentAnnotationTextPositionSelectorSchema,
+  documentAnnotationTextQuoteSelectorSchema,
+  documentAnnotationThreadStatusSchema,
+  updateDocumentAnnotationThreadSchema,
+  type CreateDocumentAnnotationComment,
+  type CreateDocumentAnnotationThread,
+  type UpdateDocumentAnnotationThread,
+} from "./document-annotation.js";
+
 export {
   createIssueSchema,
   createIssueInputSchema,