memorix 1.1.13 → 1.2.0

package/src/codegraph/auto-context.ts

@@ -1,10 +1,17 @@
 import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { getResolvedConfig } from '../config/resolved-config.js';
+import { buildTaskWorkset, type TaskWorkset, type WorksetCaution } from '../knowledge/workset.js';
 import type { ProjectInfo } from '../types.js';
 import { backfillMissingObservationCodeRefs, type CodeRefBackfillResult } from './binder.js';
 import { collectCurrentProjectFacts, type CurrentProjectFacts } from './current-facts.js';
 import { refreshProjectLite } from './lite-provider.js';
+import {
+  getExternalCodeGraphContext,
+  inspectExternalCodeGraph,
+  type ExternalCodeGraphRunner,
+} from './external-provider.js';
+import type { CodeGraphProviderQuality, ExternalCodeGraphOutline } from './types.js';
 import {
   buildProjectContextExplain,
   type ProjectContextExplain,
@@ -40,6 +47,8 @@ export interface AutoProjectContext {
   overview: ProjectContextOverview;
   explain: ProjectContextExplain;
   refresh: AutoContextRefreshResult;
+  providerQuality: CodeGraphProviderQuality;
+  workset: TaskWorkset;
 }
 
 export interface AutoProjectBrief {
@@ -102,6 +111,8 @@ export async function buildAutoProjectContext(input: {
   now?: Date;
   exclude?: string[];
   maxFileBytes?: number;
+  /** Test-only injection point; production uses the bounded local runner. */
+  externalRunner?: ExternalCodeGraphRunner;
   /**
    * When supplied, a needed refresh is queued instead of running in this
    * request. MCP and hook callers use this to keep their response path fast.
@@ -161,6 +172,17 @@ export async function buildAutoProjectContext(input: {
           store,
           activeProjectObservations(input.observations, input.project.id) as any,
         );
+        try {
+          const { enqueueClaimRequalification } = await import('../runtime/lifecycle.js');
+          enqueueClaimRequalification({
+            dataDir: input.dataDir,
+            projectId: input.project.id,
+            source: 'foreground-refresh',
+            snapshotId: store.latestSnapshot(input.project.id)?.id,
+          });
+        } catch {
+          // The completed scan remains useful even if its later maintenance cannot queue.
+        }
         refresh = { ...refresh, backfill };
       } catch (error) {
         refresh = {
@@ -180,15 +202,116 @@ export async function buildAutoProjectContext(input: {
     exclude,
   });
   const overview = explain.overview;
+  const currentFacts = collectCurrentProjectFacts({ project: input.project, now });
+  const latestSnapshot = overview.code.latestSnapshot;
+  const sourceSets = lensSourceSets({ task, lens, explain });
+  let externalOutline: ExternalCodeGraphOutline | undefined;
+  let externalCaution: string | undefined;
+  let providerQuality: CodeGraphProviderQuality;
+  if (task) {
+    const external = await getExternalCodeGraphContext({
+      projectRoot: input.project.rootPath,
+      task,
+      exclude,
+      mode: codegraphConfig.externalContext,
+      command: codegraphConfig.externalCommand,
+      timeoutMs: codegraphConfig.externalTimeoutMs,
+      ...(input.externalRunner ? { runner: input.externalRunner } : {}),
+    });
+    externalOutline = external.outline;
+    externalCaution = external.caution;
+    providerQuality = external.quality;
+  } else {
+    const external = await inspectExternalCodeGraph({
+      projectRoot: input.project.rootPath,
+      mode: codegraphConfig.externalContext,
+      command: codegraphConfig.externalCommand,
+      timeoutMs: codegraphConfig.externalTimeoutMs,
+      ...(input.externalRunner ? { runner: input.externalRunner } : {}),
+    });
+    providerQuality = external.quality;
+  }
+  const externalStartHere = externalOutline
+    ? [...externalOutline.relatedFiles, ...externalOutline.entryPoints.map(entry => entry.path)]
+    : [];
+  const startHere = [...new Set([
+    ...externalStartHere,
+    ...rankLensPaths([
+      ...existingLensCandidates(input.project.rootPath, lens),
+      ...overview.suggestedReads,
+    ], lens, task),
+  ])].slice(0, 5);
+  const runtimeCautions: WorksetCaution[] = [];
+  if (refresh.reason === 'queued') {
+    runtimeCautions.push({ kind: 'codegraph-refresh-queued', message: refresh.message });
+  } else if (refresh.reason === 'failed') {
+    runtimeCautions.push({ kind: 'codegraph-refresh-failed', message: refresh.message });
+  }
+  if (externalCaution) {
+    runtimeCautions.push({ kind: 'external-codegraph-fallback', message: externalCaution });
+  }
+  const workset = await buildTaskWorkset({
+    projectId: input.project.id,
+    dataDir: input.dataDir,
+    ...(task ? { task } : {}),
+    lens: lens.id,
+    startHere,
+    ...(externalOutline ? { semanticCode: externalOutline } : {}),
+    providerQuality,
+    currentFacts: worksetFactLines(currentFacts),
+    codeState: codeStateLine(overview),
+    reliableMemory: sourceSets.reliableSources
+      .slice(0, lens.sourceLimit)
+      .map(source => ({
+        id: source.observationId,
+        title: source.title,
+        type: source.type,
+        status: source.status,
+        ...(source.path ? { path: source.path } : {}),
+        ...(source.symbol ? { symbol: source.symbol } : {}),
+      })),
+    cautionMemory: sourceSets.cautionSources
+      .slice(0, lens.cautionLimit)
+      .map(source => ({
+        id: source.observationId,
+        title: source.title,
+        type: source.type,
+        status: source.status,
+        ...(source.path ? { path: source.path } : {}),
+        ...(source.symbol ? { symbol: source.symbol } : {}),
+      })),
+    hiddenCautionMemoryCount: sourceSets.hiddenCautionCount,
+    verificationHints: lensVerificationHints(lens),
+    worktreeDirty: currentFacts.git.dirty,
+    ...(latestSnapshot
+      ? {
+        snapshot: {
+          id: latestSnapshot.id,
+          sourceEpoch: latestSnapshot.sourceEpoch,
+          worktreeState: latestSnapshot.worktreeState,
+          incomplete: latestSnapshot.completeness.skippedOversizedFiles > 0
+            || (latestSnapshot.completeness.unreadableFiles ?? 0) > 0
+            || latestSnapshot.completeness.removalScanDeferred,
+        },
+      }
+      : {}),
+    freshness: {
+      suspect: overview.freshness.suspect,
+      stale: overview.freshness.stale,
+    },
+    runtimeCautions,
+  });
 
   return {
     project: input.project,
     ...(task ? { task } : {}),
     lens,
-    currentFacts: collectCurrentProjectFacts({ project: input.project, now }),
+    currentFacts,
     overview,
     explain,
     refresh,
+    providerQuality,
+    workset,
   };
 }
 
@@ -198,6 +321,22 @@ function formatLanguages(overview: ProjectContextOverview): string {
     : 'none indexed yet';
 }
 
+function codeStateLine(overview: ProjectContextOverview): string {
+  const snapshot = overview.code.latestSnapshot;
+  if (!snapshot) return '- Code state: no completed snapshot yet';
+  const revision = snapshot.baseRevision ? snapshot.baseRevision.slice(0, 12) : 'Git unavailable';
+  const scanState = snapshot.completeness.skippedOversizedFiles > 0
+    || (snapshot.completeness.unreadableFiles ?? 0) > 0
+    || snapshot.completeness.removalScanDeferred
+    ? 'incomplete scan'
+    : 'complete scan';
+  return '- Code state: ' + revision
+    + ', ' + snapshot.worktreeState + ' worktree'
+    + ', ' + snapshot.changedPathCount + ' changed path(s)'
+    + ', epoch ' + snapshot.sourceEpoch
+    + ', ' + scanState;
+}
+
 function dedupeSourcesByObservation(
   sources: ProjectContextExplain['sources'],
 ): ProjectContextExplain['sources'] {
@@ -228,18 +367,14 @@ function existingLensCandidates(rootPath: string, lens: TaskLens): string[] {
 }
 
 function rankedStartHere(context: AutoProjectContext, limit = 8): string[] {
-  const candidates = [
-    ...existingLensCandidates(context.project.rootPath, context.lens),
-    ...context.overview.suggestedReads,
-  ];
-  return rankLensPaths(candidates, context.lens, context.task).slice(0, limit);
+  return context.workset.startHere.slice(0, limit);
 }
 
 function lensLine(context: AutoProjectContext): string {
   return `Task lens: ${context.lens.id} - ${context.lens.description}`;
 }
 
-function lensSourceSets(context: AutoProjectContext): {
+function lensSourceSets(context: Pick<AutoProjectContext, 'task' | 'lens' | 'explain'>): {
   reliableSources: ProjectContextExplain['sources'];
   cautionSources: ProjectContextExplain['sources'];
   hiddenReliableCount: number;
@@ -275,7 +410,7 @@ export function buildAutoProjectBrief(context: AutoProjectContext): AutoProjectB
   return {
     lens: context.lens.id,
     lensDescription: context.lens.description,
-    startHere: rankedStartHere(context),
+    startHere: context.workset.startHere,
     reliableMemoryIds: reliableSources
       .slice(0, context.lens.sourceLimit)
       .map(source => source.observationId),
@@ -284,7 +419,7 @@ export function buildAutoProjectBrief(context: AutoProjectContext): AutoProjectB
       .map(source => source.observationId),
     hiddenReliableCount,
     hiddenCautionCount,
-    suggestedVerification: lensVerificationHints(context.lens),
+    suggestedVerification: context.workset.verification,
   };
 }
 
@@ -322,6 +457,27 @@ function formatCurrentFactsLines(facts: CurrentProjectFacts): string[] {
   return lines;
 }
 
+function worksetFactLines(facts: CurrentProjectFacts): string[] {
+  const lines: string[] = [];
+  if (facts.packageVersion) lines.push('Package version: ' + facts.packageVersion);
+  if (facts.latestChangelog) {
+    lines.push('Latest changelog: ' + facts.latestChangelog.version
+      + (facts.latestChangelog.date ? ' (' + facts.latestChangelog.date + ')' : ''));
+  }
+  const gitParts: string[] = [];
+  if (facts.git.branch) gitParts.push('branch ' + facts.git.branch);
+  if (facts.git.commit) gitParts.push('commit ' + facts.git.commit);
+  gitParts.push(facts.git.dirty ? 'dirty worktree' : 'clean worktree');
+  lines.push('Git: ' + gitParts.join(', '));
+  for (const note of facts.staleNotes.slice(0, 1)) {
+    lines.push(
+      'Historical note: ' + note.path
+      + (note.branchHint ? ' (branch hint ' + note.branchHint + '; ' + note.reason + ')' : ' (' + note.reason + ')'),
+    );
+  }
+  return lines;
+}
+
 export function formatAutoProjectContextSummary(context: AutoProjectContext): string {
   const reliableSources = rankLensSources(
     dedupeSourcesByObservation(context.explain.sources.filter(source => source.status === 'current')),
@@ -337,6 +493,7 @@ export function formatAutoProjectContextSummary(context: AutoProjectContext): st
     ...formatCurrentFactsLines(context.currentFacts),
     '',
     `- Code memory: ${context.overview.code.files} files / ${context.overview.code.symbols} symbols / ${context.overview.code.refs} memory links`,
+    `- Code provider: ${context.providerQuality.selected} (${context.providerQuality.selectedQuality})`,
     `- Languages: ${formatLanguages(context.overview)}`,
     `- Memories: ${context.overview.memory.active} active / ${context.overview.memory.total} total`,
     `- Freshness: ${context.overview.freshness.current} current, ${context.overview.freshness.suspect} suspect, ${context.overview.freshness.stale} stale`,
@@ -363,6 +520,10 @@ export function formatAutoProjectContextSummary(context: AutoProjectContext): st
 }
 
 export function formatAutoProjectContextPrompt(context: AutoProjectContext): string {
+  return context.workset.prompt;
+}
+
+export function formatLegacyAutoProjectContextPrompt(context: AutoProjectContext): string {
   const lines = [
     `Memorix Autopilot Brief for ${context.project.name}`,
     context.task ? `Task: ${context.task}` : '',
@@ -371,6 +532,7 @@ export function formatAutoProjectContextPrompt(context: AutoProjectContext): str
     ...formatCurrentFactsLines(context.currentFacts),
     '',
     'Project state',
+    codeStateLine(context.overview),
     `- Code memory: ${context.overview.code.files} files, ${context.overview.code.symbols} symbols, ${context.overview.code.refs} memory links`,
     `- Languages: ${formatLanguages(context.overview)}`,
     `- Memories: ${context.overview.memory.active} active / ${context.overview.memory.total} total`,

package/src/codegraph/code-state.ts

@@ -0,0 +1,95 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promisify } from 'node:util';
+import type {
+  CodeGraphProviderKind,
+  CodeStateScanCompleteness,
+  CodeStateSnapshotInput,
+  CodeStateWorktreeState,
+} from './types.js';
+
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT_MS = 3_000;
+const GIT_MAX_BUFFER_BYTES = 256 * 1024;
+
+interface GitResult {
+  ok: boolean;
+  output: Buffer;
+}
+
+async function runGit(rootPath: string, args: string[]): Promise<GitResult> {
+  try {
+    const result = await execFileAsync('git', ['-C', rootPath, ...args], {
+      encoding: 'buffer',
+      windowsHide: true,
+      timeout: GIT_TIMEOUT_MS,
+      maxBuffer: GIT_MAX_BUFFER_BYTES,
+    });
+    const output = Buffer.isBuffer(result.stdout)
+      ? result.stdout
+      : Buffer.from(result.stdout ?? '');
+    return { ok: true, output };
+  } catch {
+    return { ok: false, output: Buffer.alloc(0) };
+  }
+}
+
+function changedPathCount(status: Buffer): number {
+  const entries = status.toString('utf8').split('\0');
+  let count = 0;
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index];
+    if (!entry) continue;
+    count++;
+    const code = entry.slice(0, 2);
+    if (code.includes('R') || code.includes('C')) index++;
+  }
+  return count;
+}
+
+function fingerprint(baseRevision: string | undefined, status: Buffer): string {
+  return createHash('sha256')
+    .update(baseRevision ?? '')
+    .update('\0')
+    .update(status)
+    .digest('hex');
+}
+
+export interface CollectCodeStateInput {
+  projectId: string;
+  projectRoot: string;
+  provider: CodeGraphProviderKind;
+  indexedAt: string;
+  completeness: CodeStateScanCompleteness;
+}
+
+/**
+ * Capture bounded Git metadata for a completed scan. No source file contents
+ * are copied into the snapshot, and an unavailable Git executable is explicit
+ * instead of being treated as a clean worktree.
+ */
+export async function collectCodeStateSnapshot(
+  input: CollectCodeStateInput,
+): Promise<CodeStateSnapshotInput> {
+  const [revision, status] = await Promise.all([
+    runGit(input.projectRoot, ['rev-parse', 'HEAD']),
+    runGit(input.projectRoot, ['status', '--porcelain=v1', '-z', '--untracked-files=normal']),
+  ]);
+  const baseRevision = revision.ok
+    ? revision.output.toString('utf8').trim() || undefined
+    : undefined;
+  const worktreeState: CodeStateWorktreeState = status.ok
+    ? (status.output.length > 0 ? 'dirty' : 'clean')
+    : 'unavailable';
+
+  return {
+    projectId: input.projectId,
+    provider: input.provider,
+    ...(baseRevision ? { baseRevision } : {}),
+    worktreeFingerprint: fingerprint(baseRevision, status.ok ? status.output : Buffer.alloc(0)),
+    worktreeState,
+    changedPathCount: status.ok ? changedPathCount(status.output) : 0,
+    indexedAt: input.indexedAt,
+    completeness: input.completeness,
+  };
+}

package/src/codegraph/context-pack.ts

@@ -1,5 +1,13 @@
 import { evaluateCodeRefFreshness } from './freshness.js';
-import type { CodeFile, CodeRefStatus, CodeSymbol, ObservationCodeRef } from './types.js';
+import { buildTaskWorkset, type TaskWorkset, type WorksetCaution } from '../knowledge/workset.js';
+import type {
+  CodeFile,
+  CodeGraphProviderQuality,
+  CodeRefStatus,
+  CodeSymbol,
+  ExternalCodeGraphOutline,
+  ObservationCodeRef,
+} from './types.js';
 import type { CodeGraphStore } from './store.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
 
@@ -9,6 +17,8 @@ export interface ContextPackMemory {
   type: string;
   status: CodeRefStatus | 'unbound';
   reason: string;
+  path?: string;
+  symbol?: string;
 }
 
 export interface ContextPackCodeFact {
@@ -32,6 +42,8 @@ export interface ContextPack {
   warnings: ContextPackWarning[];
   suggestedReads: string[];
   suggestedVerification: string[];
+  /** 1.2 bounded task selection, added without removing legacy pack fields. */
+  workset?: TaskWorkset;
 }
 
 export interface ContextPackObservation {
@@ -181,6 +193,8 @@ export function assembleContextPack(input: AssembleContextPackInput): ContextPac
           type: observation.type,
           status: freshness.status,
           reason: freshness.reason,
+          ...(file ? { path: file.path } : {}),
+          ...(symbol ? { symbol: symbol.name } : {}),
         });
       }
       if (file) suggestedReads.push(file.path);
@@ -240,7 +254,74 @@ export function assembleContextPack(input: AssembleContextPackInput): ContextPac
   };
 }
 
+/**
+ * Context Pack remains compatible with its detailed legacy fields, but the
+ * agent-facing prompt now uses the same bounded Workset selector as Project
+ * Context. No repository scan or page compilation happens here.
+ */
+export async function attachTaskWorkset(input: {
+  pack: ContextPack;
+  projectId: string;
+  dataDir: string;
+  lens: string;
+  worktreeDirty: boolean;
+  currentFacts?: string[];
+  codeState?: string;
+  snapshot?: {
+    id?: string;
+    sourceEpoch?: number;
+    worktreeState?: 'clean' | 'dirty' | 'unavailable';
+    incomplete?: boolean;
+  };
+  semanticCode?: ExternalCodeGraphOutline;
+  providerQuality?: CodeGraphProviderQuality;
+  runtimeCautions?: WorksetCaution[];
+}): Promise<ContextPack> {
+  const semanticStartHere = input.semanticCode
+    ? [...input.semanticCode.relatedFiles, ...input.semanticCode.entryPoints.map(entry => entry.path)]
+    : [];
+  const workset = await buildTaskWorkset({
+    projectId: input.projectId,
+    dataDir: input.dataDir,
+    task: input.pack.task,
+    lens: input.lens,
+    currentFacts: input.currentFacts ?? [],
+    ...(input.codeState ? { codeState: input.codeState } : {}),
+    startHere: uniq([...semanticStartHere, ...input.pack.suggestedReads]),
+    ...(input.semanticCode ? { semanticCode: input.semanticCode } : {}),
+    ...(input.providerQuality ? { providerQuality: input.providerQuality } : {}),
+    reliableMemory: input.pack.memories
+      .filter(memory => memory.status === 'current')
+      .map(memory => ({
+        id: memory.id,
+        title: memory.title,
+        type: memory.type,
+        status: memory.status,
+        ...(memory.path ? { path: memory.path } : {}),
+        ...(memory.symbol ? { symbol: memory.symbol } : {}),
+        ...(memory.reason ? { reason: memory.reason } : {}),
+      })),
+    cautionMemory: input.pack.warnings.map(warning => ({
+      id: warning.id,
+      title: warning.title,
+      type: 'memory',
+      status: warning.status,
+      reason: warning.reason,
+    })),
+    verificationHints: input.pack.suggestedVerification,
+    worktreeDirty: input.worktreeDirty,
+    ...(input.snapshot ? { snapshot: input.snapshot } : {}),
+    freshness: {
+      suspect: input.pack.warnings.filter(warning => warning.status === 'suspect').length,
+      stale: input.pack.warnings.filter(warning => warning.status === 'stale').length,
+    },
+    runtimeCautions: input.runtimeCautions,
+  });
+  return { ...input.pack, workset };
+}
+
 export function buildContextPackPrompt(pack: ContextPack): string {
+  if (pack.workset) return pack.workset.prompt;
   const reliableMemories = pack.memories.filter(memory => memory.status === 'current');
   const unboundMemories = pack.memories.filter(memory => memory.status === 'unbound');
   const lines: string[] = ['## Task', pack.task, '', '## Reliable Memories'];