memorix 1.2.0 → 1.2.2

package/src/cli/update-checker.ts

@@ -9,85 +9,85 @@
  * Set MEMORIX_AUTO_UPDATE=install to opt into silent background install.
  * Disable via MEMORIX_AUTO_UPDATE=off.
  */
-
-import { execFile } from 'node:child_process';
-import type { ExecFileException } from 'node:child_process';
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { getCliVersion } from './version.js';
-
-const PACKAGE_NAME = 'memorix';
-const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const DEFAULT_AUTO_UPDATE_TIMEOUT_MS = 5 * 60 * 1000;
-const MIN_AUTO_UPDATE_TIMEOUT_MS = 5_000;
-const MAX_AUTO_UPDATE_TIMEOUT_MS = 30 * 60 * 1000;
-const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
-const CACHE_DIR = join(homedir(), '.memorix');
-const CACHE_FILE = join(CACHE_DIR, 'update-check.json');
-
+
+import { execFile } from 'node:child_process';
+import type { ExecFileException } from 'node:child_process';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { getCliVersion } from './version.js';
+
+const PACKAGE_NAME = 'memorix';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_AUTO_UPDATE_TIMEOUT_MS = 5 * 60 * 1000;
+const MIN_AUTO_UPDATE_TIMEOUT_MS = 5_000;
+const MAX_AUTO_UPDATE_TIMEOUT_MS = 30 * 60 * 1000;
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const CACHE_DIR = join(homedir(), '.memorix');
+const CACHE_FILE = join(CACHE_DIR, 'update-check.json');
+
 export interface UpdateCache {
-  lastCheck: number;
-  latestVersion: string;
-  lastAutoUpdate?: number;
-  lastAutoUpdateStatus?: 'success' | 'failed';
-  lastAutoUpdateError?: string;
-  lastAutoUpdateTimedOut?: boolean;
-  lastAutoUpdateExitCode?: number | null;
-  lastAutoUpdateSignal?: string | null;
-  lastAutoUpdateTimeoutMs?: number;
-  updatedFrom?: string;
-  updatedTo?: string;
+  lastCheck: number;
+  latestVersion: string;
+  lastAutoUpdate?: number;
+  lastAutoUpdateStatus?: 'success' | 'failed';
+  lastAutoUpdateError?: string;
+  lastAutoUpdateTimedOut?: boolean;
+  lastAutoUpdateExitCode?: number | null;
+  lastAutoUpdateSignal?: string | null;
+  lastAutoUpdateTimeoutMs?: number;
+  updatedFrom?: string;
+  updatedTo?: string;
 }
 
 export type AutoUpdateMode = 'off' | 'notify' | 'install';
-
-/**
- * Get the current installed version from package.json.
- */
-export function getCurrentVersion(): string {
-  try {
-    return getCliVersion();
-  } catch {
-    return '0.0.0';
-  }
-}
-
-/**
- * Compare two semver strings. Returns true if remote > local.
- */
-export function isNewer(remote: string, local: string): boolean {
-  const r = remote.split('.').map(Number);
-  const l = local.split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((r[i] ?? 0) > (l[i] ?? 0)) return true;
-    if ((r[i] ?? 0) < (l[i] ?? 0)) return false;
-  }
-  return false;
-}
-
-/**
- * Read the update check cache. Exported for doctor/status display.
- */
-export async function readCache(): Promise<UpdateCache | null> {
-  try {
-    const data = await readFile(CACHE_FILE, 'utf-8');
-    return JSON.parse(data);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Write the update check cache.
- */
-async function writeCache(cache: UpdateCache): Promise<void> {
-  try {
-    await mkdir(CACHE_DIR, { recursive: true });
-    await writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), 'utf-8');
-  } catch { /* silent */ }
-}
-
+
+/**
+ * Get the current installed version from package.json.
+ */
+export function getCurrentVersion(): string {
+  try {
+    return getCliVersion();
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Compare two semver strings. Returns true if remote > local.
+ */
+export function isNewer(remote: string, local: string): boolean {
+  const r = remote.split('.').map(Number);
+  const l = local.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((r[i] ?? 0) > (l[i] ?? 0)) return true;
+    if ((r[i] ?? 0) < (l[i] ?? 0)) return false;
+  }
+  return false;
+}
+
+/**
+ * Read the update check cache. Exported for doctor/status display.
+ */
+export async function readCache(): Promise<UpdateCache | null> {
+  try {
+    const data = await readFile(CACHE_FILE, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the update check cache.
+ */
+async function writeCache(cache: UpdateCache): Promise<void> {
+  try {
+    await mkdir(CACHE_DIR, { recursive: true });
+    await writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), 'utf-8');
+  } catch { /* silent */ }
+}
+
 /**
  * Parse MEMORIX_AUTO_UPDATE into an explicit mode.
  * Default: notify-only.
@@ -99,105 +99,105 @@ function parseAutoUpdateMode(raw: string | undefined): AutoUpdateMode {
   if (env === 'install' || env === 'true' || env === '1') return 'install';
   return 'notify';
 }
-
-function parseAutoUpdateTimeoutMs(raw: string | undefined): number {
-  const value = raw?.trim();
-  if (!value) return DEFAULT_AUTO_UPDATE_TIMEOUT_MS;
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed)) return DEFAULT_AUTO_UPDATE_TIMEOUT_MS;
-  return Math.max(MIN_AUTO_UPDATE_TIMEOUT_MS, Math.min(MAX_AUTO_UPDATE_TIMEOUT_MS, Math.floor(parsed)));
-}
-
-function describeAutoUpdateFailure(error: ExecFileException, timeoutMs: number): {
-  message: string;
-  timedOut: boolean;
-  exitCode: number | null;
-  signal: string | null;
-} {
-  const timedOut = /timed out/i.test(error.message);
-  const exitCode = typeof error.code === 'number' ? error.code : null;
-  const signal = typeof error.signal === 'string' ? error.signal : null;
-  const details: string[] = [];
-  if (timedOut) details.push(`timeout ${timeoutMs}ms`);
-  if (exitCode !== null) details.push(`exit code ${exitCode}`);
-  if (signal) details.push(`signal ${signal}`);
-  return {
-    message: details.length > 0 ? `${error.message} (${details.join(', ')})` : error.message,
-    timedOut,
-    exitCode,
-    signal,
-  };
-}
-
-/**
- * Fetch the latest version from npm registry.
- * Uses native https to avoid dependencies. Timeout: 5s.
- */
-async function fetchLatestVersion(): Promise<string | null> {
-  try {
-    const { default: https } = await import('node:https');
-    return new Promise((resolve) => {
-      const req = https.get(REGISTRY_URL, { timeout: 5000 }, (res) => {
-        if (res.statusCode !== 200) { resolve(null); return; }
-        let body = '';
-        res.on('data', (chunk: Buffer) => { body += chunk.toString(); });
-        res.on('end', () => {
-          try {
-            const data = JSON.parse(body);
-            resolve(data.version ?? null);
-          } catch { resolve(null); }
-        });
-      });
-      req.on('error', () => resolve(null));
-      req.on('timeout', () => { req.destroy(); resolve(null); });
-    });
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Silently install the latest version in the background.
- * Writes result to the cache file so doctor/status can report it.
- */
-function installUpdateInBackground(targetVersion: string, currentVersion: string, cache: UpdateCache): void {
-  try {
-    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const timeoutMs = parseAutoUpdateTimeoutMs(process.env.MEMORIX_AUTO_UPDATE_TIMEOUT_MS);
-    const child = execFile(
-      npmCmd,
-      ['install', '-g', `${PACKAGE_NAME}@${targetVersion}`],
-      { timeout: timeoutMs },
-      async (error) => {
-        const failure = error ? describeAutoUpdateFailure(error, timeoutMs) : null;
-        const updatedCache: UpdateCache = {
-          ...cache,
-          lastAutoUpdate: Date.now(),
-          updatedFrom: currentVersion,
-          updatedTo: targetVersion,
-          lastAutoUpdateStatus: error ? 'failed' : 'success',
-          lastAutoUpdateError: failure?.message,
-          lastAutoUpdateTimedOut: failure?.timedOut,
-          lastAutoUpdateExitCode: failure?.exitCode,
-          lastAutoUpdateSignal: failure?.signal,
-          lastAutoUpdateTimeoutMs: timeoutMs,
-        };
-        await writeCache(updatedCache);
-        if (error) {
-          console.error(`[memorix] Auto-update failed: ${failure?.message ?? error.message}`);
-        } else {
-          console.error(`[memorix] Auto-updated to v${targetVersion} — restart to apply`);
-        }
-      },
-    );
-    // Unref so the child process doesn't prevent the main process from exiting
-    child.unref();
-  } catch (err) {
-    console.error(`[memorix] Auto-update spawn failed:`, (err as Error)?.message ?? err);
-  }
-}
-
-/**
+
+function parseAutoUpdateTimeoutMs(raw: string | undefined): number {
+  const value = raw?.trim();
+  if (!value) return DEFAULT_AUTO_UPDATE_TIMEOUT_MS;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return DEFAULT_AUTO_UPDATE_TIMEOUT_MS;
+  return Math.max(MIN_AUTO_UPDATE_TIMEOUT_MS, Math.min(MAX_AUTO_UPDATE_TIMEOUT_MS, Math.floor(parsed)));
+}
+
+function describeAutoUpdateFailure(error: ExecFileException, timeoutMs: number): {
+  message: string;
+  timedOut: boolean;
+  exitCode: number | null;
+  signal: string | null;
+} {
+  const timedOut = /timed out/i.test(error.message);
+  const exitCode = typeof error.code === 'number' ? error.code : null;
+  const signal = typeof error.signal === 'string' ? error.signal : null;
+  const details: string[] = [];
+  if (timedOut) details.push(`timeout ${timeoutMs}ms`);
+  if (exitCode !== null) details.push(`exit code ${exitCode}`);
+  if (signal) details.push(`signal ${signal}`);
+  return {
+    message: details.length > 0 ? `${error.message} (${details.join(', ')})` : error.message,
+    timedOut,
+    exitCode,
+    signal,
+  };
+}
+
+/**
+ * Fetch the latest version from npm registry.
+ * Uses native https to avoid dependencies. Timeout: 5s.
+ */
+async function fetchLatestVersion(): Promise<string | null> {
+  try {
+    const { default: https } = await import('node:https');
+    return new Promise((resolve) => {
+      const req = https.get(REGISTRY_URL, { timeout: 5000 }, (res) => {
+        if (res.statusCode !== 200) { resolve(null); return; }
+        let body = '';
+        res.on('data', (chunk: Buffer) => { body += chunk.toString(); });
+        res.on('end', () => {
+          try {
+            const data = JSON.parse(body);
+            resolve(data.version ?? null);
+          } catch { resolve(null); }
+        });
+      });
+      req.on('error', () => resolve(null));
+      req.on('timeout', () => { req.destroy(); resolve(null); });
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Silently install the latest version in the background.
+ * Writes result to the cache file so doctor/status can report it.
+ */
+function installUpdateInBackground(targetVersion: string, currentVersion: string, cache: UpdateCache): void {
+  try {
+    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const timeoutMs = parseAutoUpdateTimeoutMs(process.env.MEMORIX_AUTO_UPDATE_TIMEOUT_MS);
+    const child = execFile(
+      npmCmd,
+      ['install', '-g', `${PACKAGE_NAME}@${targetVersion}`],
+      { timeout: timeoutMs },
+      async (error) => {
+        const failure = error ? describeAutoUpdateFailure(error, timeoutMs) : null;
+        const updatedCache: UpdateCache = {
+          ...cache,
+          lastAutoUpdate: Date.now(),
+          updatedFrom: currentVersion,
+          updatedTo: targetVersion,
+          lastAutoUpdateStatus: error ? 'failed' : 'success',
+          lastAutoUpdateError: failure?.message,
+          lastAutoUpdateTimedOut: failure?.timedOut,
+          lastAutoUpdateExitCode: failure?.exitCode,
+          lastAutoUpdateSignal: failure?.signal,
+          lastAutoUpdateTimeoutMs: timeoutMs,
+        };
+        await writeCache(updatedCache);
+        if (error) {
+          console.error(`[memorix] Auto-update failed: ${failure?.message ?? error.message}`);
+        } else {
+          console.error(`[memorix] Auto-updated to v${targetVersion} — restart to apply`);
+        }
+      },
+    );
+    // Unref so the child process doesn't prevent the main process from exiting
+    child.unref();
+  } catch (err) {
+    console.error(`[memorix] Auto-update spawn failed:`, (err as Error)?.message ?? err);
+  }
+}
+
+/**
  * Run the background update check.
  *
  * Call this fire-and-forget from entry points (serve-http, TUI).
@@ -215,32 +215,32 @@ export async function checkForUpdates(): Promise<void> {
 
     const cache = await readCache();
     const now = Date.now();
-
-    // Rate limit: skip if checked within the last 24 hours
-    if (cache && (now - cache.lastCheck) < CHECK_INTERVAL_MS) {
-      return;
-    }
-
-    const latestVersion = await fetchLatestVersion();
-    if (!latestVersion) return;
-
-    const currentVersion = getCurrentVersion();
-
-    // Update cache with check timestamp
-    const updatedCache: UpdateCache = {
-      lastCheck: now,
-      latestVersion,
-      lastAutoUpdate: cache?.lastAutoUpdate,
-      lastAutoUpdateStatus: cache?.lastAutoUpdateStatus,
-      lastAutoUpdateError: cache?.lastAutoUpdateError,
-      lastAutoUpdateTimedOut: cache?.lastAutoUpdateTimedOut,
-      lastAutoUpdateExitCode: cache?.lastAutoUpdateExitCode,
-      lastAutoUpdateSignal: cache?.lastAutoUpdateSignal,
-      lastAutoUpdateTimeoutMs: cache?.lastAutoUpdateTimeoutMs,
-      updatedFrom: cache?.updatedFrom,
-      updatedTo: cache?.updatedTo,
-    };
-    await writeCache(updatedCache);
+
+    // Rate limit: skip if checked within the last 24 hours
+    if (cache && (now - cache.lastCheck) < CHECK_INTERVAL_MS) {
+      return;
+    }
+
+    const latestVersion = await fetchLatestVersion();
+    if (!latestVersion) return;
+
+    const currentVersion = getCurrentVersion();
+
+    // Update cache with check timestamp
+    const updatedCache: UpdateCache = {
+      lastCheck: now,
+      latestVersion,
+      lastAutoUpdate: cache?.lastAutoUpdate,
+      lastAutoUpdateStatus: cache?.lastAutoUpdateStatus,
+      lastAutoUpdateError: cache?.lastAutoUpdateError,
+      lastAutoUpdateTimedOut: cache?.lastAutoUpdateTimedOut,
+      lastAutoUpdateExitCode: cache?.lastAutoUpdateExitCode,
+      lastAutoUpdateSignal: cache?.lastAutoUpdateSignal,
+      lastAutoUpdateTimeoutMs: cache?.lastAutoUpdateTimeoutMs,
+      updatedFrom: cache?.updatedFrom,
+      updatedTo: cache?.updatedTo,
+    };
+    await writeCache(updatedCache);
 
     if (isNewer(latestVersion, currentVersion)) {
       if (mode === 'install') {
@@ -254,12 +254,12 @@ export async function checkForUpdates(): Promise<void> {
     }
   } catch {
     // Entire update check is best-effort — never crash the caller
-  }
-}
-
-// ── Test helpers (exported for testing only) ──────────────────
-
-/** @internal */
+  }
+}
+
+// ── Test helpers (exported for testing only) ──────────────────
+
+/** @internal */
 export const _testing = {
   CACHE_FILE,
   CHECK_INTERVAL_MS,
@@ -268,8 +268,8 @@ export const _testing = {
   parseAutoUpdateTimeoutMs,
   describeAutoUpdateFailure,
   fetchLatestVersion,
-  installUpdateInBackground,
-  writeCache,
-  isNewer,
-  getCurrentVersion,
-};
+  installUpdateInBackground,
+  writeCache,
+  isNewer,
+  getCurrentVersion,
+};

package/src/cli/version.ts

@@ -1,7 +1,7 @@
-import pkg from '../../package.json';
-
-export function getCliVersion(): string {
-  return typeof __MEMORIX_VERSION__ !== 'undefined'
-    ? __MEMORIX_VERSION__
-    : pkg.version;
-}
+import pkg from '../../package.json';
+
+export function getCliVersion(): string {
+  return typeof __MEMORIX_VERSION__ !== 'undefined'
+    ? __MEMORIX_VERSION__
+    : pkg.version;
+}

package/src/cli/workbench.ts

@@ -5,4 +5,4 @@
  * Kept for backward-compat: `import { startWorkbench } from './workbench.js'`
  */
 
-export { startWorkbench } from './tui/index.js';
+export { startWorkbench } from './tui/index.js';

package/src/codegraph/auto-context.ts

@@ -2,9 +2,10 @@ 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 { ContextDeliveryTarget } from '../knowledge/context-assembly.js';
 import type { ProjectInfo } from '../types.js';
 import { backfillMissingObservationCodeRefs, type CodeRefBackfillResult } from './binder.js';
-import { collectCurrentProjectFacts, type CurrentProjectFacts } from './current-facts.js';
+import { collectCurrentProjectFacts, formatGitFact, type CurrentProjectFacts } from './current-facts.js';
 import { refreshProjectLite } from './lite-provider.js';
 import {
   getExternalCodeGraphContext,
@@ -19,6 +20,7 @@ import {
   type ProjectContextOverview,
 } from './project-context.js';
 import { CodeGraphStore } from './store.js';
+import { isEligibleForAutomaticDelivery } from '../memory/admission.js';
 import {
   lensPathCandidates,
   lensVerificationHints,
@@ -71,6 +73,14 @@ function activeProjectObservations(
   return observations.filter(obs => obs.projectId === projectId && (obs.status ?? 'active') === 'active');
 }
 
+function deliveryEligibleProjectObservations(
+  observations: ProjectContextObservation[],
+  projectId: string,
+): ProjectContextObservation[] {
+  return activeProjectObservations(observations, projectId)
+    .filter((observation) => isEligibleForAutomaticDelivery(observation));
+}
+
 function decideRefresh(input: {
   mode: AutoContextRefreshMode;
   status: ReturnType<CodeGraphStore['status']>;
@@ -118,6 +128,8 @@ export async function buildAutoProjectContext(input: {
    * request. MCP and hook callers use this to keep their response path fast.
    */
   enqueueRefresh?: () => void | Promise<void>;
+  /** The caller surface is recorded in the Workset receipt, not its prompt. */
+  deliveryTarget?: ContextDeliveryTarget;
 }): Promise<AutoProjectContext> {
   const refreshMode = input.refresh ?? 'auto';
   const now = input.now ?? new Date();
@@ -173,13 +185,27 @@ export async function buildAutoProjectContext(input: {
           activeProjectObservations(input.observations, input.project.id) as any,
         );
         try {
-          const { enqueueClaimRequalification } = await import('../runtime/lifecycle.js');
+          const { MaintenanceTargetStore } = await import('../runtime/maintenance-targets.js');
+          new MaintenanceTargetStore(input.dataDir).register({
+            projectId: input.project.id,
+            projectRoot: input.project.rootPath,
+            dataDir: input.dataDir,
+          });
+          const {
+            enqueueClaimRequalification,
+            enqueueObservationQualification,
+          } = await import('../runtime/lifecycle.js');
           enqueueClaimRequalification({
             dataDir: input.dataDir,
             projectId: input.project.id,
             source: 'foreground-refresh',
             snapshotId: store.latestSnapshot(input.project.id)?.id,
           });
+          enqueueObservationQualification({
+            dataDir: input.dataDir,
+            projectId: input.project.id,
+            source: 'foreground-refresh',
+          });
         } catch {
           // The completed scan remains useful even if its later maintenance cannot queue.
         }
@@ -198,7 +224,9 @@ export async function buildAutoProjectContext(input: {
   const explain = buildProjectContextExplain({
     project: input.project,
     store,
-    observations: input.observations,
+    // Binding sees all active evidence, but automatic delivery sees only
+    // evidence that has passed the control-plane admission gate.
+    observations: deliveryEligibleProjectObservations(input.observations, input.project.id),
     exclude,
   });
   const overview = explain.overview;
@@ -300,6 +328,7 @@ export async function buildAutoProjectContext(input: {
       stale: overview.freshness.stale,
     },
     runtimeCautions,
+    ...(input.deliveryTarget ? { deliveryTarget: input.deliveryTarget } : {}),
   });
 
   return {
@@ -430,15 +459,7 @@ function formatCurrentFactsLines(facts: CurrentProjectFacts): string[] {
     lines.push(`- Latest changelog: ${facts.latestChangelog.version}${facts.latestChangelog.date ? ` (${facts.latestChangelog.date})` : ''}`);
   }
 
-  const gitParts: string[] = [];
-  if (facts.git.detached) {
-    gitParts.push('detached HEAD');
-  } else 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(', ')}`);
+  lines.push('- ' + formatGitFact(facts.git));
   if (facts.git.latestCommit) lines.push(`- Latest commit: ${facts.git.latestCommit}`);
   lines.push('- Current facts above outrank progress/dev-log files when they conflict.');
 
@@ -464,11 +485,7 @@ function worksetFactLines(facts: CurrentProjectFacts): string[] {
     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(', '));
+  lines.push(formatGitFact(facts.git));
   for (const note of facts.staleNotes.slice(0, 1)) {
     lines.push(
       'Historical note: ' + note.path

package/src/codegraph/context-pack.ts

@@ -316,6 +316,7 @@ export async function attachTaskWorkset(input: {
       stale: input.pack.warnings.filter(warning => warning.status === 'stale').length,
     },
     runtimeCautions: input.runtimeCautions,
+    deliveryTarget: 'context-pack',
   });
   return { ...input.pack, workset };
 }

package/src/codegraph/current-facts.ts

@@ -10,6 +10,7 @@ export interface CurrentProjectFacts {
     date?: string;
   };
   git: {
+    available: boolean;
     branch?: string;
     commit?: string;
     latestCommit?: string;
@@ -72,11 +73,18 @@ function runGit(rootPath: string, args: string[]): string | undefined {
 }
 
 function readGitFacts(rootPath: string): CurrentProjectFacts['git'] {
-  const branch = runGit(rootPath, ['branch', '--show-current']);
+  const available = runGit(rootPath, ['rev-parse', '--is-inside-work-tree']) === 'true';
+  if (!available) {
+    return { available: false, dirty: false, detached: false };
+  }
+
+  const branch = runGit(rootPath, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+    ?? runGit(rootPath, ['branch', '--show-current']);
   const commit = runGit(rootPath, ['rev-parse', '--short', 'HEAD']);
   const latestCommit = runGit(rootPath, ['log', '-1', '--pretty=%s']);
   const dirty = Boolean(runGit(rootPath, ['status', '--porcelain']));
   return {
+    available: true,
     ...(branch ? { branch } : {}),
     ...(commit ? { commit } : {}),
     ...(latestCommit ? { latestCommit } : {}),
@@ -85,6 +93,16 @@ function readGitFacts(rootPath: string): CurrentProjectFacts['git'] {
   };
 }
 
+export function formatGitFact(git: CurrentProjectFacts['git']): string {
+  if (!git.available) return 'Git: unavailable';
+  const parts: string[] = [];
+  if (git.detached) parts.push('detached HEAD');
+  else if (git.branch) parts.push('branch ' + git.branch);
+  if (git.commit) parts.push('commit ' + git.commit);
+  parts.push(git.dirty ? 'dirty worktree' : 'clean worktree');
+  return 'Git: ' + parts.join(', ');
+}
+
 function parseProgressNote(content: string): Pick<ProjectStaleNote, 'lastUpdated' | 'branchHint'> {
   const lastUpdated = content.match(/Last updated\*\*:\s*(\d{4}-\d{2}-\d{2})/i)
     ?? content.match(/Last updated:\s*(\d{4}-\d{2}-\d{2})/i);

package/src/codegraph/project-context.ts

@@ -16,6 +16,8 @@ export interface ProjectContextObservation {
   title: string;
   type: string;
   status?: string;
+  /** Automatic capture must be qualified before it can source a project brief. */
+  admissionState?: 'ephemeral' | 'candidate' | 'qualified';
   createdAt?: string;
   updatedAt?: string;
   /** Explicit file paths recorded with a memory, used only before Code Memory exists. */