@omnitype-code/cli 0.1.0

package/src/core/FileProvenance.ts

@@ -0,0 +1,538 @@
+/**
+ * FileProvenance — character-level origin tracking for a single file.
+ *
+ * Every character belongs to one of four origins:
+ *   'ai'       — inserted by an AI tool
+ *   'user'     — typed manually
+ *   'paste'    — pasted from clipboard
+ *   'existing' — present before tracking began (unknown origin)
+ *
+ * Internally the file is an ordered array of contiguous Spans covering
+ * [start, end) character offsets. Adjacent spans with the same origin
+ * are coalesced automatically.
+ *
+ * For external disk writes we accept a LineHashBaseline (hashes + char lengths)
+ * instead of raw text — no source code is ever stored or reconstructed.
+ */
+
+export type Origin = 'ai' | 'user' | 'paste' | 'existing';
+
+interface Span {
+  start: number; // inclusive
+  end: number;   // exclusive
+  origin: Origin;
+  modelId?: number; // index into the file-local model dictionary; undefined = unknown
+  timestamp: number; // unix-ms when this origin was last set; 0 = unknown/existing
+}
+
+export interface Composition {
+  ai: number;
+  user: number;
+  paste: number;
+  existing: number;
+  total: number;
+  aiEditedByManual: number;   // Chars added by 'user' that replaced 'ai' content
+  manualEditedByAi: number;   // Chars added by 'ai' that replaced 'user' content
+}
+
+/** One entry per line in the baseline snapshot. No source text — only hashes. */
+export interface LineHashBaseline {
+  /** FNV-1a 32-bit hash of the line content (without trailing \n). */
+  hash: number;
+  /** Character length of the line including the trailing \n (except last line). */
+  charLen: number;
+}
+
+/** Compact origin encoding: 0=existing, 1=user, 2=ai, 3=paste */
+const ORIGIN_ENCODE: Record<Origin, number> = { existing: 0, user: 1, ai: 2, paste: 3 };
+const ORIGIN_DECODE: Origin[] = ['existing', 'user', 'ai', 'paste'];
+
+/** Serialized provenance for a single file — stored across sessions. No source text. */
+export interface StoredProvenance {
+  hashes: number[];
+  origins: number[];
+  charLens: number[];
+  timestamps?: number[]; // unix-ms when each line's origin was last set; 0 = unknown; optional for backwards compat
+  aiEditedByManual: number;
+  manualEditedByAi: number;
+  /** String-interned model dictionary. e.g. ['claude-3-5-sonnet', 'gpt-4o'] */
+  modelDictionary?: string[];
+  /** Per-line index into modelDictionary. -1 or undefined = unknown model. */
+  modelIds?: number[];
+}
+
+export interface ProvenanceDelta {
+  added: number;
+  deleted: Record<Origin, number>;
+  aiEditedByManual: number;
+  manualEditedByAi: number;
+}
+
+export class FileProvenance {
+  private spans: Span[];
+
+  private aiEditedByManual = 0;
+  private manualEditedByAi = 0;
+
+  /** File-local model dictionary for string interning. */
+  private _modelDict: string[] = [];
+
+  constructor(existingLength: number) {
+    this.spans = existingLength > 0
+      ? [{ start: 0, end: existingLength, origin: 'existing', timestamp: 0 }]
+      : [];
+  }
+
+  /**
+   * Intern a model name and return its numeric ID.
+   * Returns undefined for falsy/unknown model names.
+   */
+  internModel(model: string | undefined): number | undefined {
+    if (!model || model === 'unknown') return undefined;
+    let idx = this._modelDict.indexOf(model);
+    if (idx === -1) {
+      idx = this._modelDict.length;
+      this._modelDict.push(model);
+    }
+    return idx;
+  }
+
+  /** Resolve a modelId back to its string name. */
+  resolveModel(modelId: number | undefined): string | undefined {
+    if (modelId === undefined || modelId < 0 || modelId >= this._modelDict.length) return undefined;
+    return this._modelDict[modelId];
+  }
+
+  /** Get the full model dictionary (for serialization). */
+  getModelDictionary(): string[] {
+    return this._modelDict;
+  }
+
+  /**
+   * Adjust the length of the span(s) at `offset` without changing origin attribution.
+   * Used for "silent" updates like indentation/formatting where the line identity
+   * (hash) remains the same but the number of whitespace characters changed.
+   */
+  adjustLength(offset: number, oldLen: number, newLen: number): void {
+    if (oldLen === newLen) return;
+    const delta = newLen - oldLen;
+
+    const idx = this._spanAt(offset);
+    if (idx === -1) return;
+
+    // We extend/shrink the span that contains the offset.
+    // Usually this is the start of a line.
+    this.spans[idx].end += delta;
+    this._shiftFrom(idx + 1, delta);
+    this._coalesce();
+  }
+
+  // ── Core operations ──────────────────────────────────────────────────────────
+
+  /**
+   * Insert `length` characters at `offset` with the given origin.
+   * timestamp defaults to Date.now() for tracked origins, 0 for 'existing'.
+   */
+  insert(offset: number, length: number, origin: Origin, timestamp?: number, modelId?: number): void {
+    if (length <= 0) return;
+    const ts = timestamp ?? (origin === 'existing' ? 0 : Date.now());
+
+    const idx = this._spanAt(offset);
+
+    if (idx === -1) {
+      const last = this.spans[this.spans.length - 1];
+      const start = last ? last.end : 0;
+      this.spans.push({ start, end: start + length, origin, modelId, timestamp: ts });
+      this._coalesce();
+      return;
+    }
+
+    const span = this.spans[idx];
+
+    if (span.start === offset) {
+      this.spans.splice(idx, 0, { start: offset, end: offset + length, origin, modelId, timestamp: ts });
+      this._shiftFrom(idx + 1, length);
+    } else if (span.end === offset) {
+      this.spans.splice(idx + 1, 0, { start: offset, end: offset + length, origin, modelId, timestamp: ts });
+      this._shiftFrom(idx + 2, length);
+    } else {
+      // Split span — right half inherits the original span's timestamp and modelId
+      const right: Span = { start: offset + length, end: span.end + length, origin: span.origin, modelId: span.modelId, timestamp: span.timestamp };
+      span.end = offset;
+      this.spans.splice(idx + 1, 0, { start: offset, end: offset + length, origin, modelId, timestamp: ts }, right);
+      this._shiftFrom(idx + 3, length);
+    }
+
+    this._coalesce();
+  }
+
+  /**
+   * Delete `length` characters starting at `offset`.
+   * Returns the composition of the deleted segment.
+   */
+  delete(offset: number, length: number): Record<Origin, number> {
+    const deleted: Record<Origin, number> = { ai: 0, user: 0, paste: 0, existing: 0 };
+    if (length <= 0) return deleted;
+    const end = offset + length;
+
+    let i = 0;
+    while (i < this.spans.length) {
+      const s = this.spans[i];
+      if (s.end <= offset) { i++; continue; }
+      if (s.start >= end) break;
+
+      const overlapLen = Math.min(s.end, end) - Math.max(s.start, offset);
+      deleted[s.origin] += overlapLen;
+
+      s.end -= overlapLen;
+      if (s.start >= s.end) {
+        this.spans.splice(i, 1);
+      } else {
+        i++;
+      }
+    }
+
+    for (let j = i; j < this.spans.length; j++) {
+      this.spans[j].start -= length;
+      this.spans[j].end   -= length;
+    }
+
+    this._coalesce();
+    return deleted;
+  }
+
+  /**
+   * Replace [offset, offset+deleteLen) with insertLen chars of origin.
+   * Returns a delta indicating what was added and what was deleted.
+   */
+  replace(offset: number, deleteLen: number, insertLen: number, origin: Origin, modelId?: number): ProvenanceDelta {
+    const res: ProvenanceDelta = { 
+      added: insertLen, 
+      deleted: { ai: 0, user: 0, paste: 0, existing: 0 },
+      aiEditedByManual: 0,
+      manualEditedByAi: 0
+    };
+    
+    if (deleteLen > 0) {
+      const del = this.delete(offset, deleteLen);
+      Object.assign(res.deleted, del);
+      
+      // Attribution: if a user edit replaces AI work, track that "edit"
+      if (origin === 'user' && res.deleted.ai > 0) {
+        const amt = Math.min(res.deleted.ai, insertLen);
+        this.aiEditedByManual += amt;
+        res.aiEditedByManual  += amt;
+      }
+      if (origin === 'ai' && res.deleted.user > 0) {
+        const amt = Math.min(res.deleted.user, insertLen);
+        this.manualEditedByAi += amt;
+        res.manualEditedByAi  += amt;
+      }
+    }
+    if (insertLen > 0) this.insert(offset, insertLen, origin, undefined, modelId);
+    return res;
+  }
+
+  /**
+   * Apply a diff between an old baseline and a new baseline, attributing
+   * all added/changed lines to `origin`.
+   */
+  applyLineDiff(oldBaseline: LineHashBaseline[], newBaseline: LineHashBaseline[], origin: Origin, modelId?: number): ProvenanceDelta {
+    const res: ProvenanceDelta = { 
+      added: 0, 
+      deleted: { ai: 0, user: 0, paste: 0, existing: 0 },
+      aiEditedByManual: 0,
+      manualEditedByAi: 0
+    };
+    const m = oldBaseline.length;
+    const n = newBaseline.length;
+    const t = this._lcsTable(oldBaseline, newBaseline);
+
+    // 1. Backtrack to find the optimal edit path (from end to start)
+    type Op = { type: 'match' | 'add' | 'delete', oi: number, ni: number };
+    const ops: Op[] = [];
+    let i = m, j = n;
+    while (i > 0 || j > 0) {
+      if (i > 0 && j > 0 && oldBaseline[i - 1].hash === newBaseline[j - 1].hash && t[i][j] === t[i - 1][j - 1] + 1) {
+        ops.push({ type: 'match', oi: i - 1, ni: j - 1 });
+        i--; j--;
+      } else if (i > 0 && (j === 0 || t[i - 1][j] >= t[i][j - 1])) {
+        ops.push({ type: 'delete', oi: i - 1, ni: -1 });
+        i--;
+      } else {
+        ops.push({ type: 'add', oi: -1, ni: j - 1 });
+        j--;
+      }
+    }
+    ops.reverse();
+
+    // 2. Apply operations forward to maintain correct character offsets
+    let offset = 0;
+    let lastDeleted: ProvenanceDelta['deleted'] | null = null;
+
+    for (const op of ops) {
+      if (op.type === 'match') {
+        const olen = oldBaseline[op.oi].charLen;
+        const nlen = newBaseline[op.ni].charLen;
+        if (olen !== nlen) this.adjustLength(offset, olen, nlen);
+        offset += nlen;
+        lastDeleted = null;
+      } else if (op.type === 'add') {
+        const len = newBaseline[op.ni].charLen;
+        this.insert(offset, len, origin, undefined, modelId);
+        res.added += len;
+        
+        // Tracking transitions for consecutive replacements
+        if (lastDeleted) {
+          if (origin === 'user' && lastDeleted.ai > 0) {
+            const amt = Math.min(lastDeleted.ai, len);
+            this.aiEditedByManual += amt;
+            res.aiEditedByManual  += amt;
+          } else if (origin === 'ai' && lastDeleted.user > 0) {
+            const amt = Math.min(lastDeleted.user, len);
+            this.manualEditedByAi += amt;
+            res.manualEditedByAi  += amt;
+          }
+        }
+        offset += len;
+      } else {
+        const len = oldBaseline[op.oi].charLen;
+        const del = this.delete(offset, len);
+        for (const k in del) res.deleted[k as Origin] += (del as any)[k];
+        lastDeleted = del;
+      }
+    }
+    return res;
+  }
+
+
+  getComposition(): Composition {
+    const c: Composition = { 
+      ai: 0, user: 0, paste: 0, existing: 0, total: 0,
+      aiEditedByManual: this.aiEditedByManual,
+      manualEditedByAi: this.manualEditedByAi
+    };
+    for (const s of this.spans) {
+      const len = s.end - s.start;
+      c[s.origin] += len;
+      c.total     += len;
+    }
+    return c;
+  }
+
+  // ── Persistence ──────────────────────────────────────────────────────────────
+
+  /**
+   * Returns the dominant origin for each line.
+   * A line's origin is whichever origin covers the most characters in that line.
+   */
+  getLineOrigins(baseline: LineHashBaseline[]): Origin[] {
+    return this._getLineData(baseline).map(d => d.origin);
+  }
+
+  /** Get per-line model names (resolved from dictionary). */
+  getLineModels(baseline: LineHashBaseline[]): Array<string | undefined> {
+    return this._getLineData(baseline).map(d => this.resolveModel(d.modelId));
+  }
+
+  /** Returns per-model char counts for AI-attributed content in this file. */
+  getModelBreakdown(baseline: LineHashBaseline[]): Record<string, number> {
+    const result: Record<string, number> = {};
+    for (const span of this.spans) {
+      if (span.origin !== 'ai') continue;
+      const model = this.resolveModel(span.modelId);
+      if (!model || model === 'unknown') continue;
+      // Count chars covered by this span that overlap with the baseline
+      const totalChars = span.end - span.start;
+      result[model] = (result[model] ?? 0) + totalChars;
+    }
+    return result;
+  }
+
+  private _getLineData(baseline: LineHashBaseline[]): Array<{ origin: Origin; timestamp: number; modelId?: number }> {
+    const result: Array<{ origin: Origin; timestamp: number; modelId?: number }> = [];
+    let offset = 0;
+    for (const line of baseline) {
+      const lineEnd = offset + line.charLen;
+      const counts: Record<Origin, number> = { ai: 0, user: 0, paste: 0, existing: 0 };
+      const timestamps: Record<Origin, number> = { ai: 0, user: 0, paste: 0, existing: 0 };
+      const modelCounts = new Map<number | undefined, number>();
+      for (const span of this.spans) {
+        if (span.end <= offset || span.start >= lineEnd) continue;
+        const lo = Math.max(span.start, offset);
+        const hi = Math.min(span.end, lineEnd);
+        const covered = hi - lo;
+        counts[span.origin] += covered;
+        if (span.timestamp > timestamps[span.origin]) timestamps[span.origin] = span.timestamp;
+        modelCounts.set(span.modelId, (modelCounts.get(span.modelId) ?? 0) + covered);
+      }
+      let dominant: Origin = 'existing';
+      let max = 0;
+      for (const k of ['ai', 'user', 'paste', 'existing'] as Origin[]) {
+        if (counts[k] > max) { max = counts[k]; dominant = k; }
+      }
+      // Pick the model with the most coverage on this line
+      let dominantModel: number | undefined;
+      let maxModelCov = 0;
+      for (const [mid, cov] of modelCounts) {
+        if (mid !== undefined && cov > maxModelCov) { maxModelCov = cov; dominantModel = mid; }
+      }
+      result.push({ origin: dominant, timestamp: timestamps[dominant], modelId: dominantModel });
+      offset = lineEnd;
+    }
+    return result;
+  }
+
+  /** Serialize to a compact, storable format. */
+  toStored(baseline: LineHashBaseline[]): StoredProvenance {
+    const lineData = this._getLineData(baseline);
+    const hasModels = this._modelDict.length > 0;
+    const stored: StoredProvenance = {
+      hashes:           baseline.map(l => l.hash),
+      origins:          lineData.map(d => ORIGIN_ENCODE[d.origin]),
+      charLens:         baseline.map(l => l.charLen),
+      timestamps:       lineData.map(d => d.timestamp),
+      aiEditedByManual: this.aiEditedByManual,
+      manualEditedByAi: this.manualEditedByAi,
+    };
+    if (hasModels) {
+      stored.modelDictionary = [...this._modelDict];
+      stored.modelIds = lineData.map(d => d.modelId ?? -1);
+    }
+    return stored;
+  }
+
+  /**
+   * Reconstruct FileProvenance from a previous session's stored data,
+   * reconciling against the current file baseline via LCS on hashes.
+   *
+   * Lines that match (same hash) keep their stored origin.
+   * New or changed lines (no hash match) are marked 'existing'.
+   */
+  static fromStored(stored: StoredProvenance, currentBaseline: LineHashBaseline[]): FileProvenance {
+    const m = stored.hashes.length;
+    const n = currentBaseline.length;
+
+    // LCS table on line hashes
+    const t: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+      for (let j = 1; j <= n; j++) {
+        t[i][j] = stored.hashes[i - 1] === currentBaseline[j - 1].hash
+          ? t[i - 1][j - 1] + 1
+          : Math.max(t[i - 1][j], t[i][j - 1]);
+      }
+    }
+
+    // Backtrack to assign origins and timestamps to current lines
+    const lineOrigins: Origin[] = new Array(n).fill('existing' as Origin);
+    const lineTimestamps: number[] = new Array(n).fill(0);
+    let i = m, j = n;
+    while (i > 0 && j > 0) {
+      if (stored.hashes[i - 1] === currentBaseline[j - 1].hash && t[i][j] === t[i - 1][j - 1] + 1) {
+        lineOrigins[j - 1]    = ORIGIN_DECODE[stored.origins[i - 1]] ?? 'existing';
+        lineTimestamps[j - 1] = stored.timestamps?.[i - 1] ?? 0;
+        i--; j--;
+      } else if (t[i - 1][j] >= t[i][j - 1]) {
+        i--;
+      } else {
+        j--;
+      }
+    }
+
+    // Restore model dictionary
+    const fp = new FileProvenance(0);
+    if (stored.modelDictionary) {
+      fp._modelDict = [...stored.modelDictionary];
+    }
+    fp.aiEditedByManual = stored.aiEditedByManual || 0;
+    fp.manualEditedByAi = stored.manualEditedByAi || 0;
+
+    // Build per-line modelId array from stored data (reconciled via LCS)
+    const lineModelIds: Array<number | undefined> = new Array(n).fill(undefined);
+    // Re-walk the LCS backtrack to map stored modelIds to current lines
+    let ii = m, jj = n;
+    while (ii > 0 && jj > 0) {
+      if (stored.hashes[ii - 1] === currentBaseline[jj - 1].hash && t[ii][jj] === t[ii - 1][jj - 1] + 1) {
+        const mid = stored.modelIds?.[ii - 1];
+        lineModelIds[jj - 1] = (mid !== undefined && mid >= 0) ? mid : undefined;
+        ii--; jj--;
+      } else if (t[ii - 1][jj] >= t[ii][jj - 1]) {
+        ii--;
+      } else {
+        jj--;
+      }
+    }
+
+    let offset = 0;
+    for (let k = 0; k < n; k++) {
+      const len = currentBaseline[k].charLen;
+      if (len > 0) {
+        fp.insert(offset, len, lineOrigins[k], lineTimestamps[k], lineModelIds[k]);
+        offset += len;
+      }
+    }
+    return fp;
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────────────
+
+  /** Index of the span that contains `offset`, or -1 if past end. Binary search O(log n). */
+  private _spanAt(offset: number): number {
+    let lo = 0, hi = this.spans.length - 1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >>> 1;
+      const s = this.spans[mid];
+      if (offset < s.start)   { hi = mid - 1; }
+      else if (offset > s.end){ lo = mid + 1; }
+      else                    { return mid;   }
+    }
+    return -1;
+  }
+
+  private _shiftFrom(idx: number, delta: number): void {
+    for (let i = idx; i < this.spans.length; i++) {
+      this.spans[i].start += delta;
+      this.spans[i].end   += delta;
+    }
+  }
+
+  private _coalesce(): void {
+    this.spans = this.spans.filter(s => s.end > s.start);
+    let i = 0;
+    while (i < this.spans.length - 1) {
+      const a = this.spans[i], b = this.spans[i + 1];
+      if (a.origin === b.origin && a.modelId === b.modelId && a.end === b.start) {
+        a.end = b.end;
+        a.timestamp = Math.max(a.timestamp, b.timestamp);
+        this.spans.splice(i + 1, 1);
+      } else {
+        i++;
+      }
+    }
+  }
+
+  /**
+   * O(m×n) LCS table over hash values.
+   * Guard: if either side exceeds MAX_LCS_SIDE lines the table would exceed ~36 MB.
+   * In that case return an all-zeros table — the diff algorithm will treat every
+   * line as deleted+added, which is conservative (no lines get wrongly matched)
+   * but loses attribution for unchanged lines on those huge files.
+   */
+  private static readonly MAX_LCS_SIDE = 3000;
+
+  private _lcsTable(a: LineHashBaseline[], b: LineHashBaseline[]): number[][] {
+    const m = a.length, n = b.length;
+    if (m > FileProvenance.MAX_LCS_SIDE || n > FileProvenance.MAX_LCS_SIDE) {
+      return Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    }
+    const t: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+      for (let j = 1; j <= n; j++) {
+        t[i][j] = a[i - 1].hash === b[j - 1].hash
+          ? t[i - 1][j - 1] + 1
+          : Math.max(t[i - 1][j], t[i][j - 1]);
+      }
+    }
+    return t;
+  }
+}

package/src/core/GitNotes.ts

@@ -0,0 +1,141 @@
+/**
+ * GitNotes — read/write omnitype attribution data as Git Notes.
+ *
+ * Notes live at refs/notes/ai. Each note on a commit is a JSON blob:
+ *
+ *   {
+ *     "v": 1,
+ *     "tool": "omnitype",
+ *     "ts": <unix-ms>,
+ *     "files": {
+ *       "src/foo.ts": [
+ *         { "start": 1, "end": 45, "origin": "ai",   "model": "claude-sonnet-4-5" },
+ *         { "start": 46, "end": 60, "origin": "user" }
+ *       ]
+ *     }
+ *   }
+ *
+ * Line numbers are 1-indexed, inclusive — matching git blame output.
+ */
+
+import { execFileSync, execFile } from 'child_process';
+import { promisify } from 'util';
+
+const _execFile = promisify(execFile);
+const NOTES_REF = 'refs/notes/ai';
+
+export interface NoteRange {
+  start: number;   // 1-indexed
+  end: number;     // inclusive
+  origin: 'ai' | 'user' | 'paste' | 'existing';
+  model?: string;
+  tool?: string;
+}
+
+export interface NoteFile {
+  [relPath: string]: NoteRange[];
+}
+
+export interface CommitNote {
+  v: 1;
+  tool: 'omnitype';
+  ts: number;
+  files: NoteFile;
+}
+
+export function buildNote(files: NoteFile): CommitNote {
+  return { v: 1, tool: 'omnitype', ts: Date.now(), files };
+}
+
+/** Write (or overwrite) a Git Note for the given commit in the repo at repoPath. */
+export async function writeNote(repoPath: string, commitish: string, note: CommitNote): Promise<void> {
+  const json = JSON.stringify(note);
+  await _execFile('git', ['-C', repoPath, 'notes', '--ref', NOTES_REF, 'add', '-f', '-m', json, commitish]);
+}
+
+/** Read the omnitype Git Note for a commit. Returns null if none exists. */
+export function readNote(repoPath: string, commitish: string): CommitNote | null {
+  try {
+    const out = execFileSync(
+      'git', ['-C', repoPath, 'notes', '--ref', NOTES_REF, 'show', commitish],
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    const parsed = JSON.parse(out);
+    if (parsed?.v === 1 && parsed?.tool === 'omnitype') return parsed as CommitNote;
+    return null;
+  } catch { return null; }
+}
+
+/** Merge two notes — second note's ranges overwrite first for conflicting files. */
+export function mergeNotes(base: CommitNote, overlay: CommitNote): CommitNote {
+  return {
+    ...base,
+    ts: Math.max(base.ts, overlay.ts),
+    files: { ...base.files, ...overlay.files },
+  };
+}
+
+/**
+ * Build a NoteFile from a StoredProvenance map (as returned by FileProvenance.toStored).
+ * Converts span-level data into 1-indexed line ranges for the note.
+ */
+export function provenanceToNoteFile(
+  files: Record<string, { origins: number[]; modelIds?: number[]; modelDictionary?: string[]; toolIds?: number[]; toolDictionary?: string[] }>,
+): NoteFile {
+  const DECODE: Record<number, NoteRange['origin']> = { 0: 'existing', 1: 'user', 2: 'ai', 3: 'paste' };
+  const result: NoteFile = {};
+
+  for (const [relPath, sp] of Object.entries(files)) {
+    const ranges: NoteRange[] = [];
+    let lineNum = 1;
+    let runStart = lineNum;
+    let runOrigin: NoteRange['origin'] = DECODE[sp.origins[0]] ?? 'existing';
+    let runModel: string | undefined;
+    let runTool:  string | undefined;
+
+    const flush = (end: number) => {
+      if (end < runStart) return;
+      const r: NoteRange = { start: runStart, end, origin: runOrigin };
+      if (runModel) r.model = runModel;
+      if (runTool)  r.tool  = runTool;
+      ranges.push(r);
+    };
+
+    for (let i = 0; i < sp.origins.length; i++) {
+      const origin = DECODE[sp.origins[i]] ?? 'existing';
+      const model  = (sp.modelIds && sp.modelDictionary && sp.modelIds[i] >= 0)
+        ? sp.modelDictionary[sp.modelIds[i]] : undefined;
+      const tool   = (sp.toolIds && sp.toolDictionary && sp.toolIds[i] >= 0)
+        ? sp.toolDictionary[sp.toolIds[i]] : undefined;
+
+      if (origin !== runOrigin || model !== runModel || tool !== runTool) {
+        flush(lineNum - 1);
+        runStart  = lineNum;
+        runOrigin = origin;
+        runModel  = model;
+        runTool   = tool;
+      }
+      lineNum++;
+    }
+    flush(lineNum - 1);
+
+    if (ranges.length > 0) result[relPath] = ranges;
+  }
+
+  return result;
+}
+
+/** Fetch git notes from remote so teammates' attributions are visible locally. */
+export async function fetchNotes(repoPath: string, remote = 'origin'): Promise<void> {
+  try {
+    await _execFile('git', [
+      '-C', repoPath, 'fetch', remote,
+      `${NOTES_REF}:${NOTES_REF}`,
+    ]);
+  } catch { /* remote may not have notes yet */ }
+}
+
+/** Push git notes to remote. */
+export async function pushNotes(repoPath: string, remote = 'origin'): Promise<void> {
+  await _execFile('git', ['-C', repoPath, 'push', remote, NOTES_REF]);
+}