@futdevpro/fdp-agent-memory 1.1.30 → 1.1.113

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@futdevpro/fdp-agent-memory",
-    "version": "1.1.30",
+    "version": "1.1.113",
     "description": "Local-first, vector-backed multi-table agent memory exposed as an MCP server (read/write/capabilities). Public, FDP-Templates-free, no auth.",
     "private": false,
     "publishConfig": {

package/build/src/_cli/_commands/find-duplicates.command.js

@@ -10,6 +10,9 @@ const fam_cli_const_1 = require("../_collections/fam-cli.const");
  * 2026-06-21). Egy tár vektor-pool-jában megkeresi a NAGYON HASONLÓ (koszinusz ≥ `--threshold`) entry-ket és
  * cluster-ekbe vonja — **NEM töröl**, csak megmutatja az ismétlődéseket (a user dönt). A `GET /api/duplicates/:table`
  * REST-tükre. `--threshold` (0..1, default 0.95), `--neighbors`, `--max-entries` (O(n²)-cap), `--max-clusters`.
+ * CROSS-PROJECT mód (user-FR 2026-07-15): a `--path-regex`/`--exclude-path-regex`/`--exclude-root-regex`/
+ * `--projects`/`--exclude-projects` Mongo-prefilterrel szűkíti a jelölt-halmazt (célzott scan a nagy táron),
+ * a `--min-projects` csak a legalább ennyi KÜLÖNBÖZŐ projektet átfedő clustereket adja.
  */
 class FAM_FindDuplicates_Util {
     /** A `find-duplicates` parancs-deszkriptor. */
@@ -22,6 +25,12 @@ class FAM_FindDuplicates_Util {
             .option('--neighbors <n>', 'szomszéd-szám/entry (default 10)')
             .option('--max-entries <n>', 'entry-cap az O(n²) ellen (default 3000; a capped jelzi, ha több)')
             .option('--max-clusters <n>', 'a visszaadott cluster-ek max száma (default 100)')
+            .option('--path-regex <regex>', 'a sourceFilePath include-regexe (case-insensitive; célzott scan)')
+            .option('--exclude-path-regex <regex>', 'a sourceFilePath exclude-regexe (pl. spec/vendor zaj)')
+            .option('--exclude-root-regex <regex>', 'a source.root exclude-regexe (pl. STALE-projects)')
+            .option('--projects <list>', 'csak ezek a projektek (vessző-szeparált canonicalName lista)')
+            .option('--exclude-projects <list>', 'kizárt projektek (vessző-szeparált; fork-zaj elnyomása)')
+            .option('--min-projects <n>', 'csak a legalább ennyi KÜLÖNBÖZŐ projektet átfedő clusterek')
             .action(async () => {
             fam_output_util_1.FAM_Output_Util.exit(await FAM_FindDuplicates_Util.run(command));
         });
@@ -37,6 +46,12 @@ class FAM_FindDuplicates_Util {
             neighbors: local.neighbors,
             maxEntries: local.maxEntries,
             maxClusters: local.maxClusters,
+            pathRegex: local.pathRegex,
+            excludePathRegex: local.excludePathRegex,
+            excludeRootRegex: local.excludeRootRegex,
+            projects: local.projects,
+            excludeProjects: local.excludeProjects,
+            minProjects: local.minProjects,
         });
         const path = `/api/duplicates/${encodeURIComponent(local.table)}${query}`;
         const result = await client.get(path);
@@ -57,19 +72,22 @@ class FAM_FindDuplicates_Util {
     }
     /** A query-string összeállítása a megadott (definiált) opciókból. */
     static buildQuery(options) {
-        const parts = [];
-        if (options.threshold !== undefined) {
-            parts.push(`threshold=${encodeURIComponent(options.threshold)}`);
-        }
-        if (options.neighbors !== undefined) {
-            parts.push(`neighbors=${encodeURIComponent(options.neighbors)}`);
-        }
-        if (options.maxEntries !== undefined) {
-            parts.push(`maxEntries=${encodeURIComponent(options.maxEntries)}`);
-        }
-        if (options.maxClusters !== undefined) {
-            parts.push(`maxClusters=${encodeURIComponent(options.maxClusters)}`);
-        }
+        // A CLI kebab-opciók → REST camelCase query-kulcsok leképezése (a definiáltakból).
+        const mapping = [
+            ['threshold', options.threshold],
+            ['neighbors', options.neighbors],
+            ['maxEntries', options.maxEntries],
+            ['maxClusters', options.maxClusters],
+            ['pathRegex', options.pathRegex],
+            ['excludePathRegex', options.excludePathRegex],
+            ['excludeRootRegex', options.excludeRootRegex],
+            ['projects', options.projects],
+            ['excludeProjects', options.excludeProjects],
+            ['minProjects', options.minProjects],
+        ];
+        const parts = mapping
+            .filter(([, value]) => value !== undefined)
+            .map(([key, value]) => `${key}=${encodeURIComponent(value)}`);
         return parts.length ? `?${parts.join('&')}` : '';
     }
     /** Ember-olvasható összegzés: scan-fejléc (+ capped-figyelmeztetés) + a top cluster-ek tagokkal. */
@@ -77,7 +95,8 @@ class FAM_FindDuplicates_Util {
         const lines = [];
         lines.push(`Near-duplikátum scan — '${report.table}' (küszöb ${report.threshold}):`);
         lines.push(`  vizsgált ${report.scanned} / ${report.totalInPool} entry`
-            + `${report.capped ? '  ⚠ CAPPED (a tár nagyobb — emeld a --max-entries-t a teljes scan-hez)' : ''}`);
+            + `${report.filtered ? '  (szűrt jelölt-halmaz)' : ''}`
+            + `${report.capped ? '  ⚠ CAPPED (a jelölt-halmaz nagyobb — emeld a --max-entries-t vagy szűkíts tovább)' : ''}`);
         lines.push(`  ${report.clusterCount} duplikátum-cluster, összesen ${report.duplicateEntryCount} érintett entry`);
         if (!report.clusterCount) {
             lines.push('  ✓ nincs a küszöb feletti near-duplikátum.');
@@ -85,10 +104,16 @@ class FAM_FindDuplicates_Util {
         }
         for (const [index, cluster] of report.clusters.entries()) {
             lines.push('');
-            lines.push(`  #${index + 1} — ${cluster.size} elem (score ${cluster.minScore.toFixed(3)}…${cluster.maxScore.toFixed(3)}):`);
+            const projectInfo = cluster.projects?.length
+                ? ` — ${cluster.projectCount} projekt: ${cluster.projects.join(', ')}`
+                : '';
+            lines.push(`  #${index + 1} — ${cluster.size} elem (score ${cluster.minScore.toFixed(3)}…${cluster.maxScore.toFixed(3)})${projectInfo}:`);
             for (const member of cluster.members) {
+                const location = member.sourceFilePath
+                    ? ` ${member.project ? `[${member.project}] ` : ''}${member.sourceFilePath}`
+                    : '';
                 const snippet = member.snippet ? `: ${member.snippet}` : '';
-                lines.push(`     • [${member.id}]${member.kind ? ` (${member.kind})` : ''}${snippet}`);
+                lines.push(`     • [${member.id}]${member.kind ? ` (${member.kind})` : ''}${location}${snippet}`);
             }
         }
         return lines.join('\n');

package/build/src/_cli/_commands/scan-projects.command.js

@@ -1,159 +1,159 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_ScanProjects_Util = void 0;
-const fs_1 = require("fs");
+const path_1 = require("path");
 const commander_1 = require("commander");
 const fam_cooldown_util_1 = require("../../_collections/fam-cooldown.util");
 const fam_output_util_1 = require("../_collections/fam-output.util");
 const fam_client_service_1 = require("../_services/fam-client.service");
-const fam_cli_const_1 = require("../_collections/fam-cli.const");
-const fam_project_discovery_util_1 = require("../_collections/fam-project-discovery.util");
 /**
- * `fam scan-projects` — több projekt **SOROS** scan-orchestrátora (robusztus, NINCS konkurrens embed-thrash).
- * A projekt-listát `--config` (explicit JSON) VAGY `--root` (auto-felderítés: `package.json`/`.git` markerek,
- * a scope-név a package.json `name`-jéből) adja. Projektenként: előbb `dryRun` (idő-becslés), majd a VALÓS scan,
- * és VÁRJA a teljes választ, mielőtt a következőre lép. Ez a megfelelő minta a Packages / teljes CURSOR scanhez.
+ * `fam scan-projects` (FEAT-008, THIN-CLI) — több projekt scan-je **SZERVER-OLDALI vezényléssel**. A CLI itt már
+ * CSAK egy vékony eszköz: elindítja a job-ot (`POST /api/scan/start`) és poll-ozza az állapotát
+ * (`GET /api/scan/status/:jobId`), kiírva a haladást. A tényleges terhet (felderítés + soros feldolgozás + queue +
+ * cooldown + progress) a SZERVER viszi — nála van minden (adat, hidratáció). A `--config` fájlt is a SZERVER olvassa.
  */
 class FAM_ScanProjects_Util {
     /** A `scan-projects` parancs-deszkriptor. */
     static command() {
         const command = new commander_1.Command('scan-projects');
         command
-            .description('Több projekt SOROS scan-je (auto-felderítés --root-tal vagy explicit --config-gal; nincs '
-            + 'konkurrens thrash). ⚠️ MINDEN projekt-gyökérbe előbb `.fdpfamignore` + `--dry-run` (lásd lent).')
-            .option('--root <dir>', 'projekt-gyökerek auto-felderítése e mappa alatt (package.json/.git markerek)')
-            .option('--config <file.json>', 'explicit projekt-lista JSON — elemenként `path` + `project` (+ opcionális `org`, `table`)')
+            .description('Több projekt SZERVER-OLDALI scan-je (a szerver vezényel: felderítés + soros feldolgozás + '
+            + 'queue + cooldown). A CLI csak elindítja a job-ot és poll-ozza az állapotát.')
+            .option('--root <dir>', 'projekt-gyökerek auto-felderítése e mappa alatt (a SZERVEREN, package.json/.git markerek)')
+            .option('--config <file.json>', 'explicit projekt-lista JSON — a SZERVER olvassa (elemenként `path` + `project`)')
             .option('--depth <n>', 'auto-felderítés max mélysége (default 3)', '3')
             .option('--org <name>', 'default organization az auto-felderítéshez', 'FutDevPro')
             .option('--table <documents|codebase>', 'default cél-tár', 'codebase')
-            .option('--dry-run', 'csak becslés MINDEN projektre, NEM ír', false)
-            .option('--cooldown <ms>', 'cooldown a projektek KÖZÉ (ms) — gép-tehermentesítő szünet nagy multi-scanhez; '
-            + 'felülírja a `scan.projectCooldownMs` configot (default: a config, ami 0 = ki)')
-            .option('--stop-on-error', 'az első hibánál leáll (default: folytatja a többivel)', false)
-            .addHelpText('before', '\n⚠️  TISZTA MULTI-SCAN — ELŐBB minden projektbe IGNORE-FÁJL:\n'
-            + '   Mivel ez TÖBB projektet szkennel egyszerre, a junk gyorsan elszaporodik. MINDEN érintett\n'
-            + '   projekt-gyökérbe tegyél `.fdpfamignore`-t (a default fedi a node_modules/Library/__pycache__/\n'
-            + '   site-packages/dist/build/Logs-féle junkot; a projekt-specifikusat ott add hozzá), és FUTTASD\n'
-            + '   ELŐSZÖR `--dry-run`-nal (per-projekt fájl/chunk-becslés). Utólag kitakarítani (törlés +\n'
-            + '   re-embed minden projekten) sokkal drágább, mint eleve tisztán szkennelni.\n')
+            .option('--cooldown <ms>', 'projekt-cooldown override (ms) — felülírja a szerver `scan.projectCooldownMs` configot')
+            .option('--cooldown-min-chunks <n>', 'a feltételes cooldown küszöbe (≥ ennyi embed-chunk → vár)')
+            .option('--poll <ms>', 'a status-poll periódusa (ms)', '2000')
+            .option('--memory-path <dir>', '„SCAN-ALL": EXTRA cél a workspace mellé — az agent-memória mappa ADDITÍV '
+            + 'szkenje (preserveHistory: a kompaktáláskor kieső *.md-k MEGMARADNAK) a `memory` tárba, '
+            + '`project=agent-memory` scope-ra. Önállóan is futtatható (csak a memória).')
+            .option('--memory-scope <name>', 'a memória-cél projekt-scope neve (default `agent-memory`)', 'agent-memory')
             .action(async () => {
             fam_output_util_1.FAM_Output_Util.exit(await FAM_ScanProjects_Util.run(command));
         });
         return command;
     }
-    /** A `scan-projects` futtatása: projekt-lista feloldás → SOROS dryRun+scan → összesítő. */
+    /** Indít egy szerver-oldali scan-job-ot, majd poll-ozza az állapotát a befejezésig (progress a stderr-re). */
     static async run(command) {
         const globals = command.optsWithGlobals();
         const local = command.opts();
-        let specs;
-        try {
-            if (local.config) {
-                specs = fam_project_discovery_util_1.FAM_ProjectDiscovery_Util.parseConfig((0, fs_1.readFileSync)(local.config, 'utf-8'));
-            }
-            else if (local.root) {
-                specs = fam_project_discovery_util_1.FAM_ProjectDiscovery_Util.discover(local.root, Number(local.depth) || 3, { org: local.org, table: local.table });
-            }
-            else {
-                return fam_output_util_1.FAM_Output_Util.failure({
-                    options: globals, command: 'scan-projects',
-                    error: {
-                        errorCode: 'FAM-CLI-SCANP-001',
-                        message: '`--root <dir>` (auto-felderítés) VAGY `--config <file.json>` (explicit lista) kötelező.',
-                        fixHint: 'Pl.: fam scan-projects --root E:/.../NPM-packages   vagy   --config projects.json',
-                    },
-                });
-            }
-        }
-        catch (error) {
+        if (!local.root && !local.config && !local.memoryPath) {
             return fam_output_util_1.FAM_Output_Util.failure({
                 options: globals, command: 'scan-projects',
-                error: { errorCode: 'FAM-CLI-SCANP-002', message: `A projekt-lista feloldása sikertelen: ${error?.message}` },
+                error: {
+                    errorCode: 'FAM-CLI-SCANP-001',
+                    message: '`--root <dir>` (auto-felderítés) VAGY `--config <file.json>` (explicit lista) VAGY `--memory-path <dir>` kötelező.',
+                    fixHint: 'Pl.: fam scan-projects --root E:/.../NPM-packages   vagy   --config projects.json   vagy SCAN-ALL: --root <workspace> --memory-path <mem-dir>',
+                },
             });
         }
-        if (!specs.length) {
+        // A start-body — a felderítést/olvasást a SZERVER végzi (thin-CLI). A `sourceLocation` (a CLI cwd-je) MINDIG
+        // megy, hogy a szerver a relatív útvonalakat a HÍVÓ helyéhez oldja fel (a szerver cwd-je eltér). A `--root`/
+        // `--config` abszolútként is átmegy (belt-and-suspenders).
+        const body = { sourceLocation: process.cwd() };
+        if (local.config) {
+            body.configPath = (0, path_1.resolve)(local.config);
+        }
+        else if (local.root) {
+            body.root = (0, path_1.resolve)(local.root);
+            body.depth = Number(local.depth) || 3;
+            body.org = local.org;
+            body.table = local.table;
+        }
+        // „SCAN-ALL": a memória-mappa ADDITÍV cél a fő lista UTÁN appendelve (root-szintű `project=<scope>` scope, `memory`
+        // tár, preserveHistory → a kompaktáláskor kieső *.md-k megmaradnak). Önállóan is mehet (csak ez, root/config nélkül).
+        if (local.memoryPath) {
+            body.extraTargets = [{
+                    path: (0, path_1.resolve)(local.memoryPath),
+                    project: local.memoryScope ?? 'agent-memory',
+                    table: 'memory',
+                    preserveHistory: true,
+                    scopePath: [{ layer: 'project', rawName: local.memoryScope ?? 'agent-memory' }],
+                }];
+        }
+        if (local.cooldown !== undefined) {
+            body.cooldownMs = Number(local.cooldown);
+        }
+        if (local.cooldownMinChunks !== undefined) {
+            body.cooldownMinChunks = Number(local.cooldownMinChunks);
+        }
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        // A `start` a szerver FAST-PATH-ja miatt MÁR a (rész)job-ot adja vissza: ha a job ≤ a szerver wait-ablakán
+        // belül végzett → kész eredmény poll NÉLKÜL; különben futó job → poll-ozunk.
+        const start = await client.post('/api/scan/start', body);
+        if (!start.ok || !start.data) {
             return fam_output_util_1.FAM_Output_Util.failure({
                 options: globals, command: 'scan-projects',
-                error: { errorCode: 'FAM-CLI-SCANP-003', message: 'Nincs felderített/megadott projekt.' },
-                exitCode: fam_cli_const_1.FAM_CliExitCode.operationError,
+                error: start.error ?? { errorCode: 'FAM-CLI-SCANP-002', message: 'A scan-job indítása sikertelen.' },
             });
         }
-        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
-        const projects = [];
-        let okCount = 0;
-        // Projekt-cooldown (user-FR): a `--cooldown <ms>` felülírja a szerver `scan.projectCooldownMs` configját
-        // (default 0 = ki). dryRun-on nincs cooldown (nincs valódi embed-munka). A projektek KÖZÉ vár, nem az utolsó után.
-        const projectCooldownMs = local.dryRun ? 0 : await FAM_ScanProjects_Util.resolveCooldownMs(client, local.cooldown);
-        FAM_ScanProjects_Util.progress(globals, `=== ${specs.length} projekt SOROS scan-je${local.dryRun ? ' (dryRun)' : ''}`
-            + `${projectCooldownMs > 0 ? `, cooldown ${projectCooldownMs}ms/projekt` : ''} ===`);
-        for (let i = 0; i < specs.length; i++) {
-            const spec = specs[i];
-            FAM_ScanProjects_Util.progress(globals, `[${i + 1}/${specs.length}] ${spec.project} (${spec.path})`);
-            // 1) dryRun — idő-becslés
-            const dry = await client.post('/api/write', FAM_ScanProjects_Util.body(spec, true, local));
-            const dryScan = dry.ok ? dry.data?.scan : undefined;
-            if (dryScan) {
-                FAM_ScanProjects_Util.progress(globals, `  becslés: ${dryScan.filesProcessed} fájl, ${dryScan.chunks} chunk, ~${dryScan.estimate?.estimatedSeconds ?? '?'}s embed`);
-            }
-            if (local.dryRun) {
-                projects.push({ project: spec.project, dryRun: dryScan });
-                okCount += dry.ok ? 1 : 0;
-                continue;
-            }
-            // 2) VALÓS scan — VÁRJUK a teljes választ (soros, nincs konkurrencia)
-            const startedAt = Date.now();
-            const real = await client.post('/api/write', FAM_ScanProjects_Util.body(spec, false, local));
-            const seconds = Math.round((Date.now() - startedAt) / 1000);
-            const realScan = real.ok ? real.data?.scan : undefined;
-            if (real.ok && realScan) {
-                okCount++;
-                FAM_ScanProjects_Util.progress(globals, `  kész: ${realScan.filesProcessed} fájl, ${realScan.chunks} chunk, ${JSON.stringify(realScan.verdicts)}, ${realScan.status} (${seconds}s)`);
-                projects.push({ project: spec.project, scan: realScan, seconds: seconds });
-            }
-            else {
-                FAM_ScanProjects_Util.progress(globals, `  HIBA: ${real.error?.message ?? 'ismeretlen scan-hiba'}`);
-                projects.push({ project: spec.project, error: real.error });
-                if (local.stopOnError) {
+        const jobId = start.data.jobId;
+        const printed = new Set();
+        FAM_ScanProjects_Util.progress(globals, `=== scan-job a SZERVEREN: ${jobId} (${start.data.total} projekt) ===`);
+        let last = start.data;
+        FAM_ScanProjects_Util.printNew(globals, last, printed);
+        if (!FAM_ScanProjects_Util.isTerminal(last.status)) {
+            // Nem fért a fast-path-ba → poll a befejezésig (a frissen kész projekteket egyszer írjuk ki). ETA-jelzés.
+            const eta = last.etaSeconds !== undefined ? `, ETA ~${last.etaSeconds}s` : '';
+            FAM_ScanProjects_Util.progress(globals, `  …fut (${last.currentIndex}/${last.total}${eta}) — poll-ozok`);
+            const pollMs = Number(local.poll) || 2000;
+            let lastSubProgress = '';
+            for (;;) {
+                await fam_cooldown_util_1.FAM_Cooldown_Util.sleep(pollMs);
+                const status = await client.get(`/api/scan/status/${jobId}`);
+                if (!status.ok || !status.data) {
+                    return fam_output_util_1.FAM_Output_Util.failure({
+                        options: globals, command: 'scan-projects',
+                        error: status.error ?? { errorCode: 'FAM-CLI-SCANP-003', message: 'A scan-job állapota nem lekérdezhető.' },
+                    });
+                }
+                last = status.data;
+                FAM_ScanProjects_Util.printNew(globals, last, printed);
+                // Within-project sub-progress (user-FR): egy HOSSZÚ projekt KÖZBEN is lássunk haladást (nem csak a
+                // per-projekt befejezést). Dedup: csak változásnál írunk.
+                const sub = last.currentProgress;
+                if (sub && last.status === 'running') {
+                    const line = `    ↳ ${sub.scopeLabel}: ${sub.processed}/${sub.total} fájl (${sub.pct}%)`;
+                    if (line !== lastSubProgress) {
+                        lastSubProgress = line;
+                        FAM_ScanProjects_Util.progress(globals, line);
+                    }
+                }
+                if (FAM_ScanProjects_Util.isTerminal(last.status)) {
                     break;
                 }
             }
-            // Projekt-cooldown: a projektek KÖZÉ (NEM az utolsó után) — gép-tehermentesítő szünet nagy multi-scanhez.
-            if (projectCooldownMs > 0 && i < specs.length - 1) {
-                FAM_ScanProjects_Util.progress(globals, `  cooldown ${projectCooldownMs}ms…`);
-                await fam_cooldown_util_1.FAM_Cooldown_Util.sleep(projectCooldownMs);
-            }
         }
-        FAM_ScanProjects_Util.progress(globals, `=== KÉSZ: ${okCount}/${specs.length} ok ===`);
+        FAM_ScanProjects_Util.progress(globals, `=== ${last.status.toUpperCase()}: ${last.okCount}/${last.total} ok ===`);
         return fam_output_util_1.FAM_Output_Util.success({
             options: globals, command: 'scan-projects',
-            data: { total: specs.length, ok: okCount, projects: projects },
+            data: { jobId: jobId, status: last.status, total: last.total, ok: last.okCount, projects: last.projects },
         });
     }
-    /**
-     * A projekt-cooldown ms feloldása: a CLI `--cooldown` felülírja a szerver `scan.projectCooldownMs` configját.
-     * Nincs CLI-érték → a szerver effektív configját kérdezi (`GET /api/config`); a config-lekérés hibája → 0 (a
-     * cooldown sosem buktatja a scant). Minden út a `FAM_Cooldown_Util.resolveMs`-en megy át (clamp + biztonság).
-     */
-    static async resolveCooldownMs(client, cliValue) {
-        if (cliValue !== undefined) {
-            return fam_cooldown_util_1.FAM_Cooldown_Util.resolveMs(cliValue);
-        }
-        const result = await client.get('/api/config');
-        const value = result.ok ? result.data?.effective?.['scan.projectCooldownMs'] : 0;
-        return fam_cooldown_util_1.FAM_Cooldown_Util.resolveMs(value);
+    /** Terminál-e a job-státusz (kész/bukott/megszakítva). */
+    static isTerminal(status) {
+        return status === 'completed' || status === 'failed' || status === 'cancelled';
     }
-    /** A scan-request body egy projekt-spec-hez (dryRun vagy valós). */
-    static body(spec, dryRun, defaults) {
-        return {
-            table: spec.table ?? defaults.table ?? 'codebase',
-            operation: 'scan-project',
-            scopePath: [
-                { layer: 'organization', rawName: spec.org ?? defaults.org ?? 'FutDevPro' },
-                { layer: 'project', rawName: spec.project },
-            ],
-            scan: { path: spec.path, dryRun: dryRun },
-        };
+    /** A frissen (ok/error) befejezett projekteket EGYSZER írja ki (a `printed` halmaz dedupol). */
+    static printNew(globals, job, printed) {
+        for (const project of job.projects) {
+            if ((project.status === 'ok' || project.status === 'error') && !printed.has(project.project)) {
+                printed.add(project.project);
+                if (project.status === 'ok') {
+                    FAM_ScanProjects_Util.progress(globals, `  [${printed.size}/${job.total}] ${project.project}: `
+                        + `${project.filesProcessed ?? '?'} fájl, ${project.chunks ?? '?'} chunk, `
+                        + `${JSON.stringify(project.verdicts ?? {})} (${project.seconds ?? '?'}s)`);
+                }
+                else {
+                    FAM_ScanProjects_Util.progress(globals, `  [${printed.size}/${job.total}] ${project.project}: HIBA — ${project.error?.message ?? 'ismeretlen'}`);
+                }
+            }
+        }
     }
-    /** Ember-olvasható haladás-sor a stderr-re (a `--json` stdout-ot nem szennyezi; `--quiet` esetén néma). */
+    /** Ember-olvasható haladás-sor a stderr-re (`--json` stdout-ot nem szennyezi; `--quiet` esetén néma). */
     static progress(globals, line) {
         if (!globals.quiet) {
             process.stderr.write(`${line}\n`);

package/build/src/_cli/_commands/scan.command.js

@@ -26,6 +26,7 @@ class FAM_Scan_Util {
             .option('--exclude <glob,...>', 'exclude glob-szűrők (a secret-guard mellé)')
             .option('--scope <layer=name,...>', 'scope-lánc (KÖTELEZŐ)')
             .option('--dry-run', 'nem ír; tervezett fájl/chunk/verdikt-szám', false)
+            .option('--preserve-history', 'ADDITÍV: a forrásból eltűnt fájlok bejegyzéseit NEM törli (superset; pl. kompaktálódó memória)', false)
             .addHelpText('before', '\n⚠️  TISZTA SCAN — ELŐBB az IGNORE-FÁJL:\n'
             + '   1) Hozz létre `.fdpfamignore`-t a scan-gyökérben (a `.gitignore` mintájára) a projekt-\n'
             + '      specifikus junk-mappákra (a default már fedi: node_modules/Library/__pycache__/\n'
@@ -80,6 +81,7 @@ class FAM_Scan_Util {
                 include: fam_arg_util_1.FAM_Arg_Util.parseList(local.include),
                 exclude: exclude,
                 dryRun: local.dryRun === true,
+                preserveHistory: local.preserveHistory === true,
             },
         };
         const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);

package/build/src/_cli/_commands/serve.command.js

@@ -23,9 +23,8 @@ const fam_client_service_1 = require("../_services/fam-client.service");
  *   - **FEAT-002** („egy szerver, sok bridge"): ha már fut egy egészséges primary a porton → NEM indítunk
  *     másodikat (idempotens reuse). Az MCP-kliensek külön `fam start`-ja úgyis ehhez a REST-primary-hoz
  *     bridge-el.
- *   - **FEAT-001** (activity-konzol): a detach-olt szerver a saját, látható activity-ablakát nyitja (a
- *     `fam-activity-<port>.log` tail-je) → ez a „fixen megnyíló ablak, ami mindig fut". A tee `fs`-sel a
- *     fájlba ír, így `stdio:'ignore'` mellett is működik.
+ *   - **Saját látható ablak:** a detach-olt szerver a SAJÁT, látható konzol-ablakában fut (`spawnServerWindow`) —
+ *     az ablak KÖZVETLENÜL a node-ot futtatja, a szerver élő stdout/stderr-jét mutatja, és túléli a CLI/agent kilépését.
  *
  * A boot **REST-only** (a belépő argumentum-nélküli ága): tiszta HTTP-primary, MCP-stdio nélkül (a detach-olt
  * processnek nincs stdin-kliense). A heap-plafon a nagy korpusz boot-hidratálásához emelt (`--max-old-space-size`,
@@ -43,6 +42,109 @@ class FAM_Serve_Util {
     static HEALTH_POLL_MS = 1000;
     /** Az utolsó `fam serve` indítás állapot-fájlja (port + db + heap) — a `--restart`/auto-restart innen tudja, mit. */
     static STATE_FILE = (0, path_1.join)((0, os_1.tmpdir)(), 'fam-serve-state.json');
+    /**
+     * Az `ensureRunning()` egyidejű-spawn védő in-flight promise-e: ha több párhuzamos hívó (pl. több MCP-tool-hívás
+     * vagy bridge + CLI) EGYSZERRE találja le-állva a szervert, NE indítson mindenki külön példányt — az első spawn
+     * promise-ét osztjuk (process-en belül). A cross-process verseny benign (a port-preflight a 2. spawnt elejti).
+     */
+    static ensureInFlight = null;
+    /** Az utolsó (process-en belüli) ensure-spawn epoch-ms-e — a sorozatos tool-hívások ne nyissanak több ablakot, amíg az előző primary bootol. */
+    static lastEnsureSpawnAt = 0;
+    /** Az ensure-spawn cooldown-ja ms-ban: ennyin belül egy újabb le-állt-észlelés NEM spawn-ol újra (a bootoló primary-t várjuk). */
+    static ENSURE_SPAWN_COOLDOWN_MS = 15000;
+    /**
+     * `ensureRunning()` — **ÚJRAHASZNÁLHATÓ ensure-szemantika MINDEN FAM-funkcióhoz** (user-FR 2026-06-22: „minden
+     * fam funkciónak automatikusan gondoskodnia kell róla, hogy a fam el legyen indítva, ha nincs"). Health-check a
+     * (FAM_SERVER_URL/default `127.0.0.1:39265`) primary-n; ha fut → no-op (`already-running`). Ha NEM fut ÉS a cél
+     * **loopback** → leválasztott (detached) REST-primary spawn (a `fam serve` magjával: saját ablak, túléli a hívót)
+     * + health-bevárás. Remote cél → `remote-unreachable` (nem indíthatunk távoli szervert). Egyidejűség-védett.
+     *
+     * A hívók: az **MCP bridge** (unreachable → ensure + retry, önheal), a **`fam start` no-primary ág** (detached
+     * primary + bridge), és a **CLI data-parancsok** (pre-action). Best-effort, nem dob — a `reason` viszi a kimenetet.
+     */
+    static async ensureRunning(options) {
+        const client = new fam_client_service_1.FAM_CliClient_Service();
+        const baseUrl = client.getBaseUrl();
+        const port = FAM_Serve_Util.resolvePortFromUrl(baseUrl) ?? FAM_Serve_Util.resolvePort();
+        if (await client.isReachable()) {
+            return { running: true, spawned: false, url: baseUrl, port: port, reason: 'already-running' };
+        }
+        if (!FAM_Serve_Util.isLoopbackUrl(baseUrl)) {
+            // Távoli (nem-loopback) primary-t nem tudunk lokálisan felhúzni — csak jelezzük.
+            return { running: false, spawned: false, url: baseUrl, port: port, reason: 'remote-unreachable' };
+        }
+        if (FAM_Serve_Util.ensureInFlight) {
+            return FAM_Serve_Util.ensureInFlight;
+        }
+        // Spawn-spam védelem: ha az imént (cooldown-on belül) MÁR spawn-oltunk egy primary-t, az még BOOTOL-hat
+        // (pool-hidratálás) — ne nyissunk újabb ablakot minden tool-hívásra; jelezzük, hogy „indul" (a hívó retry-zik).
+        if (Date.now() - FAM_Serve_Util.lastEnsureSpawnAt < FAM_Serve_Util.ENSURE_SPAWN_COOLDOWN_MS) {
+            return { running: false, spawned: false, url: baseUrl, port: port, reason: 'boot-timeout' };
+        }
+        FAM_Serve_Util.lastEnsureSpawnAt = Date.now();
+        FAM_Serve_Util.ensureInFlight = FAM_Serve_Util.spawnDetachedForEnsure({
+            port: port, baseUrl: baseUrl, client: client, waitMs: options?.waitMs,
+        });
+        try {
+            return await FAM_Serve_Util.ensureInFlight;
+        }
+        finally {
+            FAM_Serve_Util.ensureInFlight = null;
+        }
+    }
+    /**
+     * Az `ensureRunning` spawn-magja (NEM CLI — nincs `FAM_Output`): a `serve` detached-spawn + health-wait logikájának
+     * újrahasznált, riport-mentes változata. Felhúzza a REST-only primary-t a saját ablakában, és bevárja a `/api/health`-et.
+     */
+    static async spawnDetachedForEnsure(set) {
+        const entry = FAM_Serve_Util.resolveServerEntry();
+        if (!entry) {
+            return { running: false, spawned: false, url: set.baseUrl, port: set.port, reason: 'no-entry' };
+        }
+        const envOverrides = {
+            FAM_SERVER_PORT: String(set.port),
+            FAM_LOG_FILE: (0, path_1.join)((0, os_1.tmpdir)(), `fam-server-${set.port}.log`),
+        };
+        const heapMb = FAM_Serve_Util.resolveHeapMb();
+        const nodeArgs = heapMb > 0 ? [`--max-old-space-size=${heapMb}`] : [];
+        try {
+            fam_console_util_1.FAM_Console_Util.spawnServerWindow({
+                command: process.execPath, args: [...nodeArgs, entry], envOverrides: envOverrides, port: set.port,
+            });
+        }
+        catch {
+            return { running: false, spawned: false, url: set.baseUrl, port: set.port, reason: 'spawn-failed' };
+        }
+        const waitMs = set.waitMs ?? FAM_Serve_Util.DEFAULT_WAIT_SEC * 1000;
+        const healthy = await FAM_Serve_Util.waitForHealthy(set.client, waitMs);
+        if (healthy) {
+            FAM_Serve_Util.writeServeState({ port: set.port, heapMb: heapMb });
+        }
+        return {
+            running: healthy, spawned: true, url: set.baseUrl, port: set.port,
+            reason: healthy ? 'spawned-healthy' : 'boot-timeout',
+        };
+    }
+    /** A port kinyerése egy base-URL-ből (`http://host:port`); nincs explicit port / hiba → `undefined` (a hívó default-ol). */
+    static resolvePortFromUrl(url) {
+        try {
+            const parsedPort = Number(new URL(url).port);
+            return Number.isInteger(parsedPort) && parsedPort > 0 ? parsedPort : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Loopback-cél-e az URL (`127.0.0.1`/`localhost`/`::1`/`0.0.0.0`)? Csak ilyet húzhatunk fel lokálisan. */
+    static isLoopbackUrl(url) {
+        try {
+            const host = new URL(url).hostname.toLowerCase().replace(/^\[|\]$/g, '');
+            return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '0.0.0.0';
+        }
+        catch {
+            return false;
+        }
+    }
     /** A `serve` parancs-deszkriptor. */
     static command() {
         const command = new commander_1.Command('serve');
@@ -173,13 +275,11 @@ class FAM_Serve_Util {
                 },
             });
         }
-        // A window-/foreground-szerver env-override-jai (a többit a szerver a saját `.env`-jéből olvassa):
-        // FAM_SHOW_CONSOLE=false → NINCS külön FEAT-001 tail-ablak (a serve-ablak MAGA a látható konzol → nincs
-        // dupla ablak; a user-direktíva szerint az Activity Monitor így redundáns).
+        // A detached-szerver env-override-jai (a többit a szerver a saját `.env`-jéből olvassa). A szerver a SAJÁT
+        // látható ablakában fut (`spawnServerWindow`) → az ablak a szerver konzolja (nincs külön monitor-ablak).
         const envOverrides = {
             FAM_SERVER_PORT: String(set.port),
-            FAM_SHOW_CONSOLE: 'false',
-            // File-log → a detached szerver logjai (import-progress is) FÁJLBÓL OLVASHATÓK (tail), ablak nélkül.
+            // File-log → a detached szerver logjai (import-progress is) FÁJLBÓL is OLVASHATÓK (tail) a látható ablak MELLETT.
             FAM_LOG_FILE: (0, path_1.join)((0, os_1.tmpdir)(), `fam-server-${set.port}.log`),
         };
         if (set.local.mongodbUri) {
@@ -198,8 +298,8 @@ class FAM_Serve_Util {
             return FAM_Serve_Util.runForeground([...nodeArgs, entry], { ...process.env, ...envOverrides });
         }
         // DETACHED: a szervert egy KÜLÖN, LÁTHATÓ konzol-ablakban indítjuk (a `start`/terminál teljesen leválasztja
-        // a CLI-ről → túléli; az ablak a szerver élő stdout/stderr-jét mutatja). REST-only primary (a belépő
-        // argumentum-nélküli ága). A FEAT-001 tail-monitort kikapcsoljuk (FAM_SHOW_CONSOLE=false) — nincs dupla ablak.
+        // a CLI-ről → túléli a hívót; az ablak a szerver élő stdout/stderr-jét mutatja). REST-only primary (a belépő
+        // argumentum-nélküli ága). Egy szerver = egy látható ablak (nincs külön activity-monitor).
         try {
             fam_console_util_1.FAM_Console_Util.spawnServerWindow({
                 command: process.execPath,

package/build/src/_cli/_services/fam-client.service.js

@@ -64,6 +64,23 @@ class FAM_CliClient_Service {
     async put(path, body) {
         return this.request('PUT', path, body);
     }
+    /**
+     * EVENT-SIGNING aláírás-headerek (user-FR 2026-06-25): a CLI minden REST-hívása `fam-cli`-ként alá van írva; ha az
+     * agent beállítja a `FAM_SESSION_ID` env-et, az a hívó session-azonosítója (több egyidejű workspace-session
+     * elkülönítéséhez). A `FAM_WORKSPACE` env vagy a CLI `cwd` adja a workspace-kontextust.
+     */
+    signingHeaders() {
+        const headers = { 'x-fam-agent': 'fam-cli' };
+        const sessionId = process.env.FAM_SESSION_ID;
+        if (sessionId && sessionId.trim()) {
+            headers['x-fam-session'] = sessionId.trim();
+        }
+        const workspace = process.env.FAM_WORKSPACE || process.cwd();
+        if (workspace) {
+            headers['x-fam-workspace'] = workspace;
+        }
+        return headers;
+    }
     /**
      * A közös HTTP-réteg: a server-választ `FAM_ClientResult`-tá fordítja. Elérhetetlen szerver →
      * `unreachable:true`; a `{ ok:false, error }` test → `error` átvitel; egyéb non-2xx → szintetikus
@@ -71,11 +88,18 @@ class FAM_CliClient_Service {
      */
     async request(method, path, body) {
         const url = `${this.baseUrl}${path}`;
+        // EVENT-SIGNING (user-FR 2026-06-25): a CLI MINDEN hívását aláírjuk → a `fam scan-projects` (és minden más)
+        // beazonosíthatóan `fam-cli`-ként szerepel a job-okon. A `FAM_SESSION_ID` env (ha az agent beállítja) a hívó
+        // session-azonosítója. Egy helyen, a közös request-rétegben → minden CLI-parancs aláírt.
+        const headers = this.signingHeaders();
+        if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
         let response;
         try {
             response = await fetch(url, {
                 method: method,
-                headers: body === undefined ? {} : { 'content-type': 'application/json' },
+                headers: headers,
                 body: body === undefined ? undefined : JSON.stringify(body),
             });
         }