memorix 1.1.13 → 1.2.1

package/src/orchestrate/verify-gate.ts

@@ -9,7 +9,7 @@
  * is skipped and the task completes as before (backward compatible).
  */
 
-import { spawn, execSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 
 // ── Types ──────────────────────────────────────────────────────────
 
@@ -63,6 +63,15 @@ export function runGate(
   return new Promise<GateResult>((resolve) => {
     const chunks: Buffer[] = [];
     let totalBytes = 0;
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    const finish = (result: GateResult) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
 
     const proc = spawn(command, {
       cwd,
@@ -86,9 +95,14 @@ export function runGate(
     let killed = false;
     const killTree = () => {
       try {
-        if (process.platform === 'win32') {
-          // Windows: kill entire process tree via taskkill
-          execSync(`taskkill /F /T /PID ${proc.pid}`, { stdio: 'ignore' });
+        if (process.platform === 'win32' && proc.pid) {
+          // `shell: true` gives Windows a cmd.exe parent. Kill its whole tree
+          // without making the timeout path wait for a stubborn descendant.
+          const killer = spawn('taskkill.exe', ['/F', '/T', '/PID', String(proc.pid)], {
+            stdio: 'ignore',
+            windowsHide: true,
+          });
+          killer.unref();
         } else {
           // Unix: kill process group
           process.kill(-proc.pid!, 'SIGKILL');
@@ -97,20 +111,30 @@ export function runGate(
         // Fallback: kill the process directly
         try { proc.kill('SIGKILL'); } catch { /* already dead */ }
       }
+      try { proc.stdout?.destroy(); } catch { /* already closed */ }
+      try { proc.stderr?.destroy(); } catch { /* already closed */ }
+      proc.unref();
     };
 
-    const timer = setTimeout(() => {
+    timer = setTimeout(() => {
       killed = true;
       killTree();
+      const output = Buffer.concat(chunks).toString('utf-8');
+      finish({
+        gate,
+        passed: false,
+        output: output + `\n[TIMEOUT] Gate "${gate}" killed after ${timeoutMs}ms`,
+        durationMs: Date.now() - start,
+        command,
+      });
     }, timeoutMs);
 
     proc.on('close', (code) => {
-      clearTimeout(timer);
       const output = Buffer.concat(chunks).toString('utf-8');
       const durationMs = Date.now() - start;
 
       if (killed) {
-        resolve({
+        finish({
           gate,
           passed: false,
           output: output + `\n[TIMEOUT] Gate "${gate}" killed after ${timeoutMs}ms`,
@@ -120,7 +144,7 @@ export function runGate(
         return;
       }
 
-      resolve({
+      finish({
         gate,
         passed: code === 0,
         output,
@@ -130,8 +154,7 @@ export function runGate(
     });
 
     proc.on('error', (err) => {
-      clearTimeout(timer);
-      resolve({
+      finish({
         gate,
         passed: false,
         output: `[ERROR] Failed to spawn gate command: ${err.message}`,

package/src/runtime/control-plane-maintenance.ts

@@ -11,6 +11,11 @@ export const CONTROL_PLANE_MAINTENANCE_KINDS: readonly MaintenanceJobKind[] = [
   'retention-archive',
   'consolidation',
   'codegraph-refresh',
+  'claim-derive',
+  'claim-requalification',
+  'knowledge-compile',
+  'knowledge-lint',
+  'workflow-index',
 ];
 
 const TARGET_WAIT_RETRY_MS = 30_000;

package/src/runtime/isolated-maintenance.ts

@@ -12,6 +12,11 @@ export const ISOLATED_MAINTENANCE_JOB_KINDS: readonly MaintenanceJobKind[] = [
   'retention-archive',
   'consolidation',
   'codegraph-refresh',
+  'claim-derive',
+  'claim-requalification',
+  'knowledge-compile',
+  'knowledge-lint',
+  'workflow-index',
 ];
 const DEFAULT_TIMEOUT_MS = 5 * 60_000;
 const MAX_CHILD_OUTPUT_BYTES = 1_000_000;

package/src/runtime/lifecycle-status.ts

@@ -0,0 +1,102 @@
+import { ClaimStore } from '../knowledge/claim-store.js';
+import { KnowledgeWorkspaceStore } from '../knowledge/workspace-store.js';
+import { WorkflowStore } from '../knowledge/workflow-store.js';
+import { MaintenanceJobStore, type MaintenanceJobSummary } from './maintenance-jobs.js';
+
+export interface LifecycleDiagnostics {
+  maintenance: {
+    summary: MaintenanceJobSummary;
+    failedJobs: Array<{
+      id: string;
+      kind: string;
+      attempts: number;
+      updatedAt: number;
+      lastError?: string;
+    }>;
+  };
+  claims: {
+    total: number;
+    active: number;
+    unknown: number;
+    needsReview: number;
+    conflicts: number;
+  };
+  workspaces: Array<{
+    id: string;
+    mode: 'local' | 'versioned';
+    status: string;
+    pages: number;
+    pendingProposals: number;
+    lastCompiledAt?: string;
+    lastLintedAt?: string;
+  }>;
+  workflows: {
+    total: number;
+    active: number;
+    failedRuns: number;
+  };
+}
+
+/**
+ * Read-only operational summary for Doctor and dashboard surfaces. It exposes
+ * lifecycle state, never maintenance payloads or workspace file contents.
+ */
+export async function collectLifecycleDiagnostics(input: {
+  dataDir: string;
+  projectId: string;
+}): Promise<LifecycleDiagnostics> {
+  const queue = new MaintenanceJobStore(input.dataDir);
+  const maintenance = {
+    summary: queue.summary(input.projectId),
+    failedJobs: queue.list({ projectId: input.projectId, status: 'failed', limit: 5 }).map(job => ({
+      id: job.id,
+      kind: job.kind,
+      attempts: job.attempts,
+      updatedAt: job.updatedAt,
+      ...(job.lastError ? { lastError: job.lastError } : {}),
+    })),
+  };
+
+  const claims = new ClaimStore();
+  const workspaces = new KnowledgeWorkspaceStore();
+  const workflows = new WorkflowStore();
+  await Promise.all([
+    claims.init(input.dataDir),
+    workspaces.init(input.dataDir),
+    workflows.init(input.dataDir),
+  ]);
+
+  const projectClaims = claims.listClaims(input.projectId);
+  const workspaceRecords = [
+    workspaces.findWorkspace(input.projectId, 'versioned'),
+    workspaces.findWorkspace(input.projectId, 'local'),
+  ].filter((workspace): workspace is NonNullable<typeof workspace> => !!workspace);
+  const workspaceDiagnostics = workspaceRecords.map(workspace => ({
+    id: workspace.id,
+    mode: workspace.mode,
+    status: workspace.status,
+    pages: workspaces.listPages(workspace.id).length,
+    pendingProposals: workspaces.listProposals(workspace.id, 'pending').length,
+    ...(workspace.lastCompiledAt ? { lastCompiledAt: workspace.lastCompiledAt } : {}),
+    ...(workspace.lastLintedAt ? { lastLintedAt: workspace.lastLintedAt } : {}),
+  }));
+  const projectWorkflows = workspaceRecords.flatMap(workspace => workflows.listWorkflows(workspace.id));
+  const runs = workflows.listRuns(input.projectId, undefined, 100);
+
+  return {
+    maintenance,
+    claims: {
+      total: projectClaims.length,
+      active: projectClaims.filter(claim => claim.status === 'active').length,
+      unknown: projectClaims.filter(claim => claim.status === 'unknown').length,
+      needsReview: projectClaims.filter(claim => claim.reviewState === 'needs-review').length,
+      conflicts: claims.listConflicts(input.projectId).length,
+    },
+    workspaces: workspaceDiagnostics,
+    workflows: {
+      total: projectWorkflows.length,
+      active: projectWorkflows.filter(workflow => workflow.status === 'active').length,
+      failedRuns: runs.filter(run => run.outcome === 'failed' || run.verificationVerdict === 'failed').length,
+    },
+  };
+}

package/src/runtime/lifecycle.ts

@@ -0,0 +1,107 @@
+import { MaintenanceJobStore } from './maintenance-jobs.js';
+
+export type MaintenanceQueue = Pick<MaintenanceJobStore, 'enqueue'>;
+
+function queueFor(input: { dataDir: string; queue?: MaintenanceQueue }): MaintenanceQueue {
+  return input.queue ?? new MaintenanceJobStore(input.dataDir);
+}
+
+/**
+ * Coalesce every trigger for a project's next Code Memory scan. The newest
+ * event replaces the payload while one durable job remains pending.
+ */
+export function enqueueCodegraphRefresh(input: {
+  dataDir: string;
+  projectId: string;
+  source: string;
+  maxFiles?: number;
+  queue?: MaintenanceQueue;
+}): void {
+  queueFor(input).enqueue({
+    projectId: input.projectId,
+    kind: 'codegraph-refresh',
+    dedupeKey: 'codegraph-refresh',
+    payload: {
+      source: input.source,
+      ...(input.maxFiles ? { maxFiles: input.maxFiles } : {}),
+    },
+  });
+}
+
+/**
+ * Requalification is owned by one job per project, never by an individual
+ * snapshot. A newer refresh replaces the snapshot metadata before it runs.
+ */
+export function enqueueClaimRequalification(input: {
+  dataDir: string;
+  projectId: string;
+  source: string;
+  snapshotId?: string;
+  queue?: MaintenanceQueue;
+}): void {
+  queueFor(input).enqueue({
+    projectId: input.projectId,
+    kind: 'claim-requalification',
+    dedupeKey: 'claim-requalification',
+    payload: {
+      source: input.source,
+      ...(input.snapshotId ? { snapshotId: input.snapshotId } : {}),
+    },
+  });
+}
+
+/** A stored explicit/Git observation earns a recoverable claim derivation. */
+export function enqueueClaimDerivation(input: {
+  dataDir: string;
+  projectId: string;
+  observationId: number;
+  queue?: MaintenanceQueue;
+}): void {
+  queueFor(input).enqueue({
+    projectId: input.projectId,
+    kind: 'claim-derive',
+    dedupeKey: 'claim-derive:' + input.observationId,
+    payload: { observationId: input.observationId },
+  });
+}
+
+/**
+ * The follow-up jobs operate on the same workspace the Workset reads: a
+ * versioned workspace when present, otherwise the local workspace.
+ */
+export function enqueueKnowledgeFollowups(input: {
+  dataDir: string;
+  projectId: string;
+  source: string;
+  includeCompile?: boolean;
+  workspaceMode?: 'local' | 'versioned';
+  allowVersionedWrite?: boolean;
+  queue?: MaintenanceQueue;
+}): void {
+  const queue = queueFor(input);
+  const payload = {
+    source: input.source,
+    ...(input.workspaceMode ? { workspaceMode: input.workspaceMode } : {}),
+    ...(input.allowVersionedWrite ? { allowVersionedWrite: true } : {}),
+  };
+  if (input.includeCompile) {
+    queue.enqueue({
+      projectId: input.projectId,
+      kind: 'knowledge-compile',
+      dedupeKey: 'knowledge-compile',
+      payload,
+    });
+  }
+  queue.enqueue({
+    projectId: input.projectId,
+    kind: 'knowledge-lint',
+    dedupeKey: 'knowledge-lint',
+    payload,
+  });
+  queue.enqueue({
+    projectId: input.projectId,
+    kind: 'workflow-index',
+    dedupeKey: 'workflow-index',
+    payload,
+  });
+}

package/src/runtime/maintenance-jobs.ts

@@ -8,6 +8,11 @@ export const MAINTENANCE_JOB_KINDS = [
   'retention-archive',
   'consolidation',
   'codegraph-refresh',
+  'claim-derive',
+  'claim-requalification',
+  'knowledge-compile',
+  'knowledge-lint',
+  'workflow-index',
 ] as const;
 
 export type MaintenanceJobKind = typeof MAINTENANCE_JOB_KINDS[number];

package/src/runtime/project-maintenance.ts

@@ -3,11 +3,17 @@ import type {
   MaintenanceJobRunResult,
 } from './maintenance-jobs.js';
 import { runMaintenanceInChildProcess } from './isolated-maintenance.js';
+import {
+  enqueueClaimRequalification,
+  enqueueKnowledgeFollowups,
+  type MaintenanceQueue,
+} from './lifecycle.js';
 
 const DEFAULT_VECTOR_BATCH_SIZE = 12;
 const DEFAULT_RETENTION_BATCH_SIZE = 100;
 const DEFAULT_CONSOLIDATION_BATCH_SIZE = 200;
 const DEFAULT_CODEGRAPH_MAX_FILES = 5_000;
+const DEFAULT_CLAIM_DERIVATION_BATCH_SIZE = 100;
 const VECTOR_RETRY_DELAY_MS = 5_000;
 const DEDUP_PER_PAIR_TIMEOUT_MS = 5_000;
 
@@ -49,6 +55,46 @@ function codeGraphMaxFiles(payload: Record<string, unknown>): number {
   return Math.min(20_000, Math.max(1, Math.floor(value)));
 }
 
+function claimDerivationBatchSize(payload: Record<string, unknown>): number {
+  const value = payload.limit;
+  if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_CLAIM_DERIVATION_BATCH_SIZE;
+  return Math.min(500, Math.max(1, Math.floor(value)));
+}
+
+function claimDerivationCursor(payload: Record<string, unknown>): number {
+  const value = payload.cursor;
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, Math.floor(value))
+    : 0;
+}
+
+function observationId(payload: Record<string, unknown>): number | undefined {
+  const value = payload.observationId;
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+    ? value
+    : undefined;
+}
+
+function workspaceMode(payload: Record<string, unknown>): 'local' | 'versioned' | undefined {
+  return payload.workspaceMode === 'local' || payload.workspaceMode === 'versioned'
+    ? payload.workspaceMode
+    : undefined;
+}
+
+async function loadWorkspaceForMaintenance(
+  projectId: string,
+  projectDir: string,
+  mode?: 'local' | 'versioned',
+) {
+  const { loadKnowledgeWorkspace } = await import('../knowledge/workspace.js');
+  if (mode) return loadKnowledgeWorkspace({ projectId, dataDir: projectDir, mode });
+  const [versioned, local] = await Promise.all([
+    loadKnowledgeWorkspace({ projectId, dataDir: projectDir, mode: 'versioned' }),
+    loadKnowledgeWorkspace({ projectId, dataDir: projectDir, mode: 'local' }),
+  ]);
+  return versioned ?? local;
+}
+
 /**
  * Creates handlers for one initialized project runtime. The worker itself is
  * project-scoped so it never claims a different project's queued work.
@@ -149,6 +195,7 @@ export function createProjectMaintenanceHandler(
   projectId: string,
   projectDir: string,
   projectRoot?: string,
+  options: { maintenanceQueue?: MaintenanceQueue } = {},
 ): MaintenanceJobHandler {
   return async (job): Promise<MaintenanceJobRunResult> => {
     if (job.projectId !== projectId) {
@@ -220,6 +267,149 @@ export function createProjectMaintenanceHandler(
       });
       const activeObservations = await getObservationStore().loadByProject(projectId, { status: 'active' });
       await backfillMissingObservationCodeRefs(store, activeObservations);
+      const snapshot = store.latestSnapshot(projectId);
+      enqueueClaimRequalification({
+        projectId,
+        dataDir: projectDir,
+        source: 'codegraph-refresh',
+        ...(snapshot?.id ? { snapshotId: snapshot.id } : {}),
+        ...(options.maintenanceQueue ? { queue: options.maintenanceQueue } : {}),
+      });
+      return { action: 'complete' };
+    }
+
+    if (job.kind === 'claim-derive') {
+      const id = observationId(job.payload);
+      if (!id) throw new Error('Claim derivation requires a positive observationId');
+      const [
+        { CodeGraphStore },
+        { ClaimStore },
+        { bindObservationToCode },
+        { deriveLowRiskClaimsFromObservation },
+        { getObservationStore },
+      ] = await Promise.all([
+        import('../codegraph/store.js'),
+        import('../knowledge/claim-store.js'),
+        import('../codegraph/binder.js'),
+        import('../knowledge/claims.js'),
+        import('../store/obs-store.js'),
+      ]);
+      const observation = await getObservationStore().getById(id);
+      if (!observation || observation.projectId !== projectId) return { action: 'complete' };
+      const codeStore = new CodeGraphStore();
+      const claimStore = new ClaimStore();
+      await Promise.all([codeStore.init(projectDir), claimStore.init(projectDir)]);
+      await bindObservationToCode(codeStore, observation);
+      const derived = deriveLowRiskClaimsFromObservation(claimStore, observation, codeStore);
+      if (derived.length > 0) {
+        enqueueKnowledgeFollowups({
+          projectId,
+          dataDir: projectDir,
+          source: 'claim-derive:' + id,
+          includeCompile: true,
+          ...(options.maintenanceQueue ? { queue: options.maintenanceQueue } : {}),
+        });
+      }
+      return { action: 'complete' };
+    }
+
+    if (job.kind === 'claim-requalification') {
+      const [
+        { CodeGraphStore },
+        { ClaimStore },
+        { bindObservationToCode },
+        { deriveLowRiskClaimsFromObservation, requalifyClaimsForCodeState },
+        { getObservationStore },
+      ] = await Promise.all([
+        import('../codegraph/store.js'),
+        import('../knowledge/claim-store.js'),
+        import('../codegraph/binder.js'),
+        import('../knowledge/claims.js'),
+        import('../store/obs-store.js'),
+      ]);
+      const codeStore = new CodeGraphStore();
+      const claimStore = new ClaimStore();
+      await Promise.all([codeStore.init(projectDir), claimStore.init(projectDir)]);
+      const limit = claimDerivationBatchSize(job.payload);
+      const observations = await getObservationStore().loadByProject(projectId, {
+        status: 'active',
+        afterId: claimDerivationCursor(job.payload),
+        limit,
+      });
+      let derivedCount = 0;
+      for (const observation of observations) {
+        await bindObservationToCode(codeStore, observation);
+        derivedCount += deriveLowRiskClaimsFromObservation(claimStore, observation, codeStore).length;
+      }
+      requalifyClaimsForCodeState(claimStore, codeStore, projectId);
+      if (observations.length === limit) {
+        return {
+          action: 'reschedule',
+          delayMs: 0,
+          resetAttempts: true,
+          payload: {
+            ...job.payload,
+            cursor: observations[observations.length - 1].id,
+            limit,
+          },
+        };
+      }
+      enqueueKnowledgeFollowups({
+        projectId,
+        dataDir: projectDir,
+        source: 'claim-requalification',
+        includeCompile: derivedCount > 0,
+        ...(options.maintenanceQueue ? { queue: options.maintenanceQueue } : {}),
+      });
+      return { action: 'complete' };
+    }
+
+    if (job.kind === 'knowledge-compile') {
+      const workspace = await loadWorkspaceForMaintenance(projectId, projectDir, workspaceMode(job.payload));
+      if (!workspace) return { action: 'complete' };
+      if (workspace.mode === 'versioned' && job.payload.allowVersionedWrite !== true) {
+        return { action: 'complete' };
+      }
+      const [{ ClaimStore }, { compileKnowledgeWorkspace }] = await Promise.all([
+        import('../knowledge/claim-store.js'),
+        import('../knowledge/wiki.js'),
+      ]);
+      const claims = new ClaimStore();
+      await claims.init(projectDir);
+      await compileKnowledgeWorkspace({ workspace, claims });
+      enqueueKnowledgeFollowups({
+        projectId,
+        dataDir: projectDir,
+        source: 'knowledge-compile',
+        ...(options.maintenanceQueue ? { queue: options.maintenanceQueue } : {}),
+      });
+      return { action: 'complete' };
+    }
+
+    if (job.kind === 'workflow-index') {
+      const workspace = await loadWorkspaceForMaintenance(projectId, projectDir, workspaceMode(job.payload));
+      if (!workspace) return { action: 'complete' };
+      const { syncCanonicalWorkflows } = await import('../knowledge/workflows.js');
+      await syncCanonicalWorkflows(workspace);
+      return { action: 'complete' };
+    }
+
+    if (job.kind === 'knowledge-lint') {
+      const workspace = await loadWorkspaceForMaintenance(projectId, projectDir, workspaceMode(job.payload));
+      if (!workspace) return { action: 'complete' };
+      const [
+        { ClaimStore },
+        { CodeGraphStore },
+        { lintKnowledgeWorkspace },
+      ] = await Promise.all([
+        import('../knowledge/claim-store.js'),
+        import('../codegraph/store.js'),
+        import('../knowledge/wiki.js'),
+      ]);
+      const claims = new ClaimStore();
+      const codeStore = new CodeGraphStore();
+      await Promise.all([claims.init(projectDir), codeStore.init(projectDir)]);
+      await lintKnowledgeWorkspace({ workspace, claims, codeStore });
       return { action: 'complete' };
     }
 

package/src/server/tool-profile.ts

@@ -10,7 +10,7 @@
  *     Suitable for normal MCP clients where every tool schema costs context tokens.
  *   - "lite": Core memory CRUD, sessions, reasoning, retention, backup — 17 tools.
  *     Suitable for solo users who want the full memory surface without team tools.
- *   - "team" (HTTP default): lite + orchestration coordination tools + dashboard — 24 tools.
+ *   - "team" (HTTP default): lite + orchestration coordination tools, dashboard, and Knowledge Workspace — 25 tools.
  *     Suitable when an operator explicitly wants task/message/lock surfaces.
  *   - "full": Everything, including niche / advanced tools (consolidate, dedup,
  *     formation metrics, skills, rules/workspace sync, KG-official, image ingest).
@@ -50,6 +50,7 @@ export const TOOL_PROFILES: Record<string, ReadonlyArray<ToolProfile>> = Object.
 
   // ── team: orchestration coordination surfaces — HTTP default ──────
   memorix_dashboard:          ['team', 'full'],
+  memorix_knowledge:          ['team', 'full'],
   memorix_handoff:            ['team', 'full'],
   memorix_poll:               ['team', 'full'],
   team_manage:                ['team', 'full'],
@@ -135,7 +136,7 @@ export function describeProfile(profile: ToolProfile): string {
   switch (profile) {
     case 'micro': return 'micro (agent-ready context + basic memory, ~7 tools)';
     case 'lite': return 'lite (core memory + sessions, ~17 tools)';
-    case 'team': return 'team (lite + coordination tools + dashboard, ~24 tools)';
+    case 'team': return 'team (lite + coordination tools + dashboard + knowledge workspace, ~25 tools)';
     case 'full': return 'full (all tools including advanced / KG-compat)';
   }
 }