@mrc2204/agent-smart-memo 5.0.0 → 5.0.2

package/dist/core/usecases/default-memory-usecase-port.js

@@ -1,3 +1,7 @@
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -28,6 +32,13 @@ function allScopeIdentities(ctx) {
         { userId: "__public__", agentId: "__public__", scope: "public" },
     ];
 }
+function randomJobId() {
+    return `idxjob_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function shellEscape(value) {
+    const input = String(value || "");
+    return `'${input.replace(/'/g, `'"'"'`)}'`;
+}
 export class DefaultMemoryUseCasePort {
     slotDb;
     semanticUseCase;
@@ -46,6 +57,36 @@ export class DefaultMemoryUseCasePort {
                 return this.handleSlotList(payload, req);
             case "slot.delete":
                 return this.handleSlotDelete(payload, req);
+            case "project.register":
+                return this.handleProjectRegister(payload, req);
+            case "project.get":
+                return this.handleProjectGet(payload, req);
+            case "project.list":
+                return this.handleProjectList(req);
+            case "project.set_registration_state":
+                return this.handleProjectSetRegistrationState(payload, req);
+            case "project.set_tracker_mapping":
+                return this.handleProjectSetTrackerMapping(payload, req);
+            case "project.register_command":
+                return this.handleProjectRegisterCommand(payload, req);
+            case "project.link_tracker":
+                return this.handleProjectLinkTracker(payload, req);
+            case "project.trigger_index":
+                return this.handleProjectTriggerIndex(payload, req);
+            case "project.reindex_diff":
+                return this.handleProjectReindexDiff(payload, req);
+            case "project.index_watch_get":
+                return this.handleProjectIndexWatchGet(payload, req);
+            case "project.task_registry_upsert":
+                return this.handleProjectTaskRegistryUpsert(payload, req);
+            case "project.task_lineage_context":
+                return this.handleProjectTaskLineageContext(payload, req);
+            case "project.hybrid_search":
+                return this.handleProjectHybridSearch(payload, req);
+            case "project.legacy_backfill":
+                return this.handleProjectLegacyBackfill(payload, req);
+            case "project.telegram_onboarding":
+                return this.handleProjectTelegramOnboarding(payload, req);
             case "graph.entity.get":
                 return this.handleGraphEntityGet(payload, req);
             case "graph.entity.set":
@@ -166,6 +207,838 @@ export class DefaultMemoryUseCasePort {
             scope: identity.scope,
         };
     }
+    handleProjectRegister(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.project_alias || typeof payload.project_alias !== "string") {
+            throw new Error("project.register requires payload.project_alias");
+        }
+        return this.slotDb.registerProject(identity.userId, identity.agentId, {
+            project_id: payload.project_id,
+            project_name: payload.project_name,
+            project_alias: payload.project_alias,
+            repo_root: payload.repo_root,
+            repo_remote: payload.repo_remote,
+            active_version: payload.active_version,
+            allow_alias_update: payload.allow_alias_update,
+        });
+    }
+    handleProjectGet(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.project_id && !payload.project_alias) {
+            throw new Error("project.get requires payload.project_id or payload.project_alias");
+        }
+        if (payload.project_id) {
+            const project = this.slotDb.getProjectById(identity.userId, identity.agentId, payload.project_id);
+            if (!project)
+                return null;
+            return {
+                project,
+                registration: this.slotDb.getProjectRegistrationState(identity.userId, identity.agentId, payload.project_id),
+            };
+        }
+        const byAlias = this.slotDb.getProjectByAlias(identity.userId, identity.agentId, payload.project_alias);
+        if (!byAlias)
+            return null;
+        return {
+            project: byAlias.project,
+            alias: byAlias.alias,
+            registration: this.slotDb.getProjectRegistrationState(identity.userId, identity.agentId, byAlias.project.project_id),
+        };
+    }
+    handleProjectList(req) {
+        const identity = normalizePrivateIdentity(req.context);
+        return this.slotDb.listProjects(identity.userId, identity.agentId);
+    }
+    handleProjectSetRegistrationState(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.project_id) {
+            throw new Error("project.set_registration_state requires payload.project_id");
+        }
+        return this.slotDb.updateProjectRegistrationState(identity.userId, identity.agentId, {
+            project_id: payload.project_id,
+            registration_status: payload.registration_status,
+            validation_status: payload.validation_status,
+            validation_notes: payload.validation_notes ?? null,
+            completeness_score: payload.completeness_score,
+            missing_required_fields: payload.missing_required_fields || [],
+            last_validated_at: payload.last_validated_at,
+        });
+    }
+    handleProjectSetTrackerMapping(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.project_id || !payload.tracker_type) {
+            throw new Error("project.set_tracker_mapping requires payload.project_id and payload.tracker_type");
+        }
+        if (payload.tracker_type === "jira") {
+            this.validateJiraTrackerFields(payload.tracker_space_key, payload.default_epic_key);
+        }
+        return this.slotDb.setProjectTrackerMapping(identity.userId, identity.agentId, {
+            project_id: payload.project_id,
+            tracker_type: payload.tracker_type,
+            tracker_space_key: payload.tracker_space_key,
+            tracker_project_id: payload.tracker_project_id,
+            default_epic_key: payload.default_epic_key,
+            board_key: payload.board_key,
+            active_version: payload.active_version,
+            external_project_url: payload.external_project_url,
+        });
+    }
+    handleProjectRegisterCommand(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        const alias = String(payload.project_alias || "").trim();
+        if (!alias) {
+            throw new Error("project.register_command requires payload.project_alias");
+        }
+        const repoUrl = String(payload.repo_url || payload.repo_remote || "").trim() || undefined;
+        const workspaceRoot = this.resolveWorkspaceRoot(req);
+        const selection = this.resolveRepoForRegistration(identity.userId, identity.agentId, {
+            explicitRepoRoot: payload.repo_root,
+            repoUrl,
+            workspaceRoot,
+        });
+        const resolvedRepoRoot = selection.repo_root;
+        const resolvedRepoRemote = payload.repo_remote || selection.repo_remote || repoUrl;
+        const registered = this.slotDb.registerProject(identity.userId, identity.agentId, {
+            project_id: payload.project_id,
+            project_name: payload.project_name,
+            project_alias: alias,
+            repo_root: resolvedRepoRoot,
+            repo_remote: resolvedRepoRemote,
+            active_version: payload.active_version,
+            allow_alias_update: payload.options?.allow_alias_update,
+            reuse_existing_repo_root: selection.resolution === "registered_remote_match",
+        });
+        let trackerMapping = null;
+        if (payload.tracker?.tracker_type) {
+            if (payload.tracker.tracker_type === "jira") {
+                this.validateJiraTrackerFields(payload.tracker.tracker_space_key, payload.tracker.default_epic_key);
+            }
+            trackerMapping = this.slotDb.setProjectTrackerMapping(identity.userId, identity.agentId, {
+                project_id: registered.project.project_id,
+                tracker_type: payload.tracker.tracker_type,
+                tracker_space_key: payload.tracker.tracker_space_key,
+                tracker_project_id: payload.tracker.tracker_project_id,
+                default_epic_key: payload.tracker.default_epic_key,
+                board_key: payload.tracker.board_key,
+                active_version: payload.tracker.active_version || payload.active_version,
+                external_project_url: payload.tracker.external_project_url,
+            });
+        }
+        const triggerRequested = payload.options?.trigger_index === true;
+        let indexTrigger = {
+            requested: triggerRequested,
+            accepted: false,
+            enqueued: false,
+            run_id: null,
+            job_id: null,
+            note: triggerRequested ? "index requested but not enqueued" : null,
+        };
+        if (triggerRequested) {
+            const triggerResult = this.handleProjectTriggerIndex({
+                project_ref: { project_id: registered.project.project_id },
+                mode: "bootstrap",
+                reason: "post_registration",
+                paths: [],
+            }, req);
+            indexTrigger = {
+                requested: true,
+                accepted: Boolean(triggerResult?.accepted),
+                enqueued: Boolean(triggerResult?.enqueued),
+                run_id: triggerResult?.run_id || null,
+                job_id: triggerResult?.job_id || null,
+                note: triggerResult?.note || null,
+            };
+        }
+        return {
+            project_id: registered.project.project_id,
+            project_alias: registered.alias.project_alias,
+            registration_status: registered.registration.registration_status,
+            validation_status: registered.registration.validation_status,
+            completeness_score: Number((registered.registration.completeness_score / 100).toFixed(2)),
+            warnings: [],
+            repo_resolution: {
+                resolution: selection.resolution,
+                clone_policy: selection.clone_policy || "not_applicable",
+                workspace_root: selection.workspace_root || null,
+                clone_target: selection.clone_target || null,
+                notes: selection.notes,
+            },
+            tracker_mapping: trackerMapping
+                ? {
+                    tracker_type: trackerMapping.tracker_type,
+                    tracker_space_key: trackerMapping.tracker_space_key,
+                    default_epic_key: trackerMapping.default_epic_key,
+                    mapping_status: "linked",
+                }
+                : null,
+            index_trigger: indexTrigger,
+            project: registered.project,
+            registration: registered.registration,
+        };
+    }
+    handleProjectLinkTracker(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        const mode = payload.mode || "attach_or_update";
+        if (mode !== "attach_or_update") {
+            throw new Error("project.link_tracker only supports mode=attach_or_update");
+        }
+        const project = this.resolveProjectRef(identity.userId, identity.agentId, payload.project_ref);
+        if (!payload.tracker?.tracker_type) {
+            throw new Error("project.link_tracker requires tracker.tracker_type");
+        }
+        if (payload.tracker.tracker_type === "jira") {
+            this.validateJiraTrackerFields(payload.tracker.tracker_space_key, payload.tracker.default_epic_key);
+        }
+        const mapped = this.slotDb.setProjectTrackerMapping(identity.userId, identity.agentId, {
+            project_id: project.project_id,
+            tracker_type: payload.tracker.tracker_type,
+            tracker_space_key: payload.tracker.tracker_space_key,
+            tracker_project_id: payload.tracker.tracker_project_id,
+            default_epic_key: payload.tracker.default_epic_key,
+            board_key: payload.tracker.board_key,
+            active_version: payload.tracker.active_version,
+            external_project_url: payload.tracker.external_project_url,
+        });
+        return {
+            project_id: project.project_id,
+            tracker_mapping: {
+                tracker_type: mapped.tracker_type,
+                tracker_space_key: mapped.tracker_space_key,
+                default_epic_key: mapped.default_epic_key,
+                mapping_status: "linked",
+                updated: true,
+            },
+            validation_status: "ok",
+            warnings: [],
+        };
+    }
+    handleProjectTriggerIndex(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        const project = this.resolveProjectRef(identity.userId, identity.agentId, payload.project_ref);
+        const queuedAt = new Date().toISOString();
+        const jobId = randomJobId();
+        const normalizedPaths = (payload.paths || []).filter((item) => String(item.relative_path || "").trim().length > 0);
+        this.scheduleProjectReindexJob({
+            scopeUserId: identity.userId,
+            scopeAgentId: identity.agentId,
+            projectId: project.project_id,
+            sourceRev: payload.source_rev || null,
+            triggerType: payload.mode || "bootstrap",
+            indexProfile: payload.index_profile || "default",
+            paths: normalizedPaths,
+            jobId,
+        });
+        return {
+            project_id: project.project_id,
+            accepted: true,
+            enqueued: true,
+            detached: true,
+            run_id: null,
+            job_id: jobId,
+            queued_at: queuedAt,
+            reason: payload.reason || "manual_trigger",
+            path_count: normalizedPaths.length,
+            note: normalizedPaths.length > 0
+                ? "index request accepted/enqueued in background mode"
+                : "index request accepted/enqueued in background mode; no concrete paths provided yet",
+        };
+    }
+    scheduleProjectReindexJob(input) {
+        setTimeout(() => {
+            try {
+                let paths = input.paths;
+                if (paths.length === 0) {
+                    const project = this.slotDb.getProjectById(input.scopeUserId, input.scopeAgentId, input.projectId);
+                    if (project?.repo_root) {
+                        paths = this.collectGitTrackedPaths(project.repo_root);
+                    }
+                }
+                if (paths.length === 0)
+                    return;
+                this.slotDb.reindexProjectByDiff(input.scopeUserId, input.scopeAgentId, {
+                    project_id: input.projectId,
+                    source_rev: input.sourceRev,
+                    trigger_type: input.triggerType,
+                    index_profile: input.indexProfile,
+                    paths,
+                });
+            }
+            catch {
+                // Background-friendly fire-and-forget path: do not block foreground tool response.
+            }
+        }, 0);
+    }
+    resolveProjectRef(scopeUserId, scopeAgentId, projectRef) {
+        if (projectRef?.project_id) {
+            const project = this.slotDb.getProjectById(scopeUserId, scopeAgentId, projectRef.project_id);
+            if (!project)
+                throw new Error(`project_id '${projectRef.project_id}' is not registered`);
+            return project;
+        }
+        if (projectRef?.project_alias) {
+            const byAlias = this.slotDb.getProjectByAlias(scopeUserId, scopeAgentId, projectRef.project_alias);
+            if (!byAlias)
+                throw new Error(`project_alias '${projectRef.project_alias}' is not registered`);
+            return byAlias.project;
+        }
+        throw new Error("project reference requires project_id or project_alias");
+    }
+    validateJiraTrackerFields(trackerSpaceKey, defaultEpicKey) {
+        const space = String(trackerSpaceKey || "").trim();
+        if (!space) {
+            throw new Error("jira tracker requires tracker_space_key");
+        }
+        if (!/^[A-Z][A-Z0-9_]*$/.test(space)) {
+            throw new Error("jira tracker_space_key format is invalid");
+        }
+        const epic = String(defaultEpicKey || "").trim();
+        if (epic) {
+            const expectedPrefix = `${space}-`;
+            if (!epic.toUpperCase().startsWith(expectedPrefix)) {
+                throw new Error(`default_epic_key must match tracker_space_key prefix '${space}-*'`);
+            }
+        }
+    }
+    tryResolveRepoRootFromCwd() {
+        try {
+            const output = execSync("git rev-parse --show-toplevel", {
+                stdio: ["ignore", "pipe", "ignore"],
+                encoding: "utf8",
+            });
+            const value = String(output || "").trim();
+            return value || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    resolveWorkspaceRoot(req) {
+        const candidates = [
+            process.env.AGENT_MEMO_PROJECT_WORKSPACE_ROOT,
+            process.env.AGENT_MEMO_REPO_CLONE_ROOT,
+            process.env.PROJECT_WORKSPACE_ROOT,
+            process.env.REPO_CLONE_ROOT,
+            req?.meta?.projectWorkspaceRoot,
+            req?.meta?.repoCloneRoot,
+            req?.context?.metadata?.projectWorkspaceRoot,
+            req?.context?.metadata?.repoCloneRoot,
+            req?.context?.metadata?.workspaceRoot,
+        ];
+        for (const raw of candidates) {
+            const value = String(raw || "").trim();
+            if (!value)
+                continue;
+            const resolved = isAbsolute(value) ? resolve(value) : resolve(process.cwd(), value);
+            try {
+                mkdirSync(resolved, { recursive: true });
+            }
+            catch {
+                // ignore and fallback
+            }
+            if (existsSync(resolved))
+                return resolved;
+        }
+        const fallback = resolve(process.env.HOME || process.cwd(), ".openclaw", "workspace", "projects");
+        mkdirSync(fallback, { recursive: true });
+        return fallback;
+    }
+    resolveRepoForRegistration(scopeUserId, scopeAgentId, input) {
+        const notes = [];
+        const explicitRepoRoot = this.normalizeRepoRootInput(input.explicitRepoRoot);
+        if (explicitRepoRoot) {
+            notes.push("repo_root provided explicitly by operator/request payload");
+            return {
+                repo_root: explicitRepoRoot,
+                repo_remote: this.tryReadGitRemote(explicitRepoRoot) || input.repoUrl,
+                resolution: "explicit_repo_root",
+                clone_policy: "not_applicable",
+                workspace_root: input.workspaceRoot,
+                notes,
+            };
+        }
+        const cwdRoot = this.tryResolveRepoRootFromCwd();
+        const normalizedRepoUrl = this.normalizeRepoUrl(input.repoUrl);
+        if (cwdRoot) {
+            const cwdRemote = this.tryReadGitRemote(cwdRoot);
+            const cwdMatchesRepoUrl = !normalizedRepoUrl || !cwdRemote || this.canonicalizeRemote(cwdRemote) === this.canonicalizeRemote(normalizedRepoUrl);
+            if (cwdMatchesRepoUrl) {
+                notes.push("resolved repo_root from current git working directory");
+                return {
+                    repo_root: cwdRoot,
+                    repo_remote: cwdRemote || normalizedRepoUrl,
+                    resolution: "cwd_git_root",
+                    clone_policy: "not_applicable",
+                    workspace_root: input.workspaceRoot,
+                    notes,
+                };
+            }
+            notes.push("current git root exists but remote does not match repo_url; skipped cwd reuse");
+        }
+        if (normalizedRepoUrl) {
+            const registered = this.findRegisteredProjectByRemote(scopeUserId, scopeAgentId, normalizedRepoUrl);
+            if (registered?.repo_root) {
+                notes.push("matched existing registered project by repo remote; reusing repo_root");
+                return {
+                    repo_root: registered.repo_root,
+                    repo_remote: registered.repo_remote_primary || normalizedRepoUrl,
+                    resolution: "registered_remote_match",
+                    clone_policy: "reuse_existing_clone",
+                    workspace_root: input.workspaceRoot,
+                    clone_target: registered.repo_root,
+                    notes,
+                };
+            }
+            const imported = this.tryResolveLocalPathImport(normalizedRepoUrl, input.workspaceRoot);
+            if (imported) {
+                notes.push("repo_url points to a local path; imported without git clone");
+                return {
+                    repo_root: imported,
+                    repo_remote: this.tryReadGitRemote(imported) || normalizedRepoUrl,
+                    resolution: "imported_local_path",
+                    clone_policy: "not_applicable",
+                    workspace_root: input.workspaceRoot,
+                    clone_target: imported,
+                    notes,
+                };
+            }
+            const cloneAttempt = this.cloneOrReuseRepo(normalizedRepoUrl, input.workspaceRoot);
+            notes.push(...cloneAttempt.notes);
+            return {
+                repo_root: cloneAttempt.repo_root,
+                repo_remote: cloneAttempt.repo_remote,
+                resolution: "cloned_from_repo_url",
+                clone_policy: cloneAttempt.clone_policy,
+                workspace_root: input.workspaceRoot,
+                clone_target: cloneAttempt.clone_target,
+                notes,
+            };
+        }
+        notes.push("repo root unresolved: no explicit repo_root, not inside git repo, and no repo_url provided");
+        return {
+            repo_root: undefined,
+            repo_remote: undefined,
+            resolution: "repo_root_missing",
+            clone_policy: "not_applicable",
+            workspace_root: input.workspaceRoot,
+            notes,
+        };
+    }
+    normalizeRepoRootInput(repoRoot) {
+        const raw = String(repoRoot || "").trim();
+        if (!raw)
+            return undefined;
+        const resolved = isAbsolute(raw) ? resolve(raw) : resolve(process.cwd(), raw);
+        if (!existsSync(resolved))
+            return resolved;
+        try {
+            if (statSync(resolved).isDirectory())
+                return resolved;
+        }
+        catch {
+            // ignore
+        }
+        return resolved;
+    }
+    normalizeRepoUrl(repoUrl) {
+        const value = String(repoUrl || "").trim();
+        return value || undefined;
+    }
+    canonicalizeRemote(remote) {
+        const value = String(remote || "").trim();
+        if (!value)
+            return undefined;
+        if (value.startsWith("git@")) {
+            const stripped = value.replace(/^git@/, "").replace(":", "/");
+            return stripped.toLowerCase().replace(/\.git$/i, "");
+        }
+        return value
+            .replace(/^https?:\/\//i, "")
+            .replace(/^ssh:\/\//i, "")
+            .toLowerCase()
+            .replace(/\.git$/i, "");
+    }
+    findRegisteredProjectByRemote(scopeUserId, scopeAgentId, repoUrl) {
+        const canonical = this.canonicalizeRemote(repoUrl);
+        if (!canonical)
+            return null;
+        const projects = this.slotDb.listProjects(scopeUserId, scopeAgentId);
+        for (const row of projects) {
+            const remote = row.project.repo_remote_primary;
+            if (!remote)
+                continue;
+            if (this.canonicalizeRemote(remote) === canonical) {
+                return {
+                    repo_root: row.project.repo_root,
+                    repo_remote_primary: row.project.repo_remote_primary,
+                };
+            }
+        }
+        return null;
+    }
+    deriveRepoFolderName(repoUrl) {
+        const cleaned = repoUrl.replace(/[#?].*$/, "").replace(/\/+$/, "");
+        const base = cleaned.split(/[/:]/).pop() || "repo";
+        const name = base.replace(/\.git$/i, "").trim() || "repo";
+        return name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "repo";
+    }
+    tryResolveLocalPathImport(repoUrl, workspaceRoot) {
+        const looksLocal = repoUrl.startsWith("/") || repoUrl.startsWith("./") || repoUrl.startsWith("../") || repoUrl.startsWith("file://");
+        if (!looksLocal)
+            return undefined;
+        const rawPath = repoUrl.startsWith("file://") ? repoUrl.slice("file://".length) : repoUrl;
+        const candidate = isAbsolute(rawPath) ? resolve(rawPath) : resolve(workspaceRoot, rawPath);
+        if (!existsSync(candidate))
+            return undefined;
+        try {
+            if (statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            return undefined;
+        }
+        return undefined;
+    }
+    cloneOrReuseRepo(repoUrl, workspaceRoot) {
+        const notes = [];
+        mkdirSync(workspaceRoot, { recursive: true });
+        const folderName = this.deriveRepoFolderName(repoUrl);
+        const preferredTarget = resolve(workspaceRoot, folderName);
+        if (this.isMatchingExistingClone(preferredTarget, repoUrl)) {
+            notes.push(`existing clone already present at ${preferredTarget}; reused`);
+            return {
+                repo_root: preferredTarget,
+                repo_remote: this.tryReadGitRemote(preferredTarget) || repoUrl,
+                clone_policy: "reuse_existing_clone",
+                clone_target: preferredTarget,
+                notes,
+            };
+        }
+        if (!existsSync(preferredTarget)) {
+            this.gitClone(repoUrl, preferredTarget);
+            notes.push(`cloned repo_url into workspace root at ${preferredTarget}`);
+            return {
+                repo_root: preferredTarget,
+                repo_remote: this.tryReadGitRemote(preferredTarget) || repoUrl,
+                clone_policy: "cloned_new",
+                clone_target: preferredTarget,
+                notes,
+            };
+        }
+        const conflictTarget = this.computeConflictCloneTarget(preferredTarget, repoUrl);
+        this.gitClone(repoUrl, conflictTarget);
+        notes.push(`preferred clone target occupied; cloned with suffix at ${conflictTarget}`);
+        return {
+            repo_root: conflictTarget,
+            repo_remote: this.tryReadGitRemote(conflictTarget) || repoUrl,
+            clone_policy: "cloned_to_conflict_suffix",
+            clone_target: conflictTarget,
+            notes,
+        };
+    }
+    computeConflictCloneTarget(preferredTarget, repoUrl) {
+        const canonical = this.canonicalizeRemote(repoUrl) || repoUrl;
+        const digest = createHash("sha1").update(canonical).digest("hex").slice(0, 8);
+        const parent = dirname(preferredTarget);
+        const base = basename(preferredTarget);
+        let candidate = resolve(parent, `${base}--${digest}`);
+        let index = 1;
+        while (existsSync(candidate)) {
+            if (this.isMatchingExistingClone(candidate, repoUrl)) {
+                return candidate;
+            }
+            candidate = resolve(parent, `${base}--${digest}-${index}`);
+            index += 1;
+        }
+        return candidate;
+    }
+    isMatchingExistingClone(targetDir, repoUrl) {
+        if (!existsSync(targetDir))
+            return false;
+        try {
+            if (!statSync(targetDir).isDirectory())
+                return false;
+        }
+        catch {
+            return false;
+        }
+        if (!existsSync(resolve(targetDir, ".git")))
+            return false;
+        const existingRemote = this.tryReadGitRemote(targetDir);
+        if (!existingRemote)
+            return false;
+        return this.canonicalizeRemote(existingRemote) === this.canonicalizeRemote(repoUrl);
+    }
+    gitClone(repoUrl, targetDir) {
+        execSync(`git clone ${shellEscape(repoUrl)} ${shellEscape(targetDir)}`, {
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf8",
+        });
+    }
+    tryReadGitRemote(repoRoot) {
+        try {
+            const output = execSync("git remote get-url origin", {
+                cwd: repoRoot,
+                stdio: ["ignore", "pipe", "ignore"],
+                encoding: "utf8",
+            });
+            const value = String(output || "").trim();
+            return value || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    collectGitTrackedPaths(repoRoot) {
+        try {
+            const output = execSync("git ls-files", {
+                cwd: repoRoot,
+                stdio: ["ignore", "pipe", "ignore"],
+                encoding: "utf8",
+            });
+            const paths = String(output || "")
+                .split("\n")
+                .map((line) => line.trim())
+                .filter(Boolean);
+            return paths
+                .filter((p) => !p.startsWith(".git/"))
+                .map((relativePath) => {
+                const ext = relativePath.includes(".") ? relativePath.split(".").pop() || "" : "";
+                return {
+                    relative_path: relativePath,
+                    checksum: `git:${relativePath}`,
+                    module: relativePath.split("/")[0] || undefined,
+                    language: ext || undefined,
+                };
+            });
+        }
+        catch {
+            // fallback for non-git local import
+            const files = [];
+            const walk = (dir, prefix = "") => {
+                const entries = readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.name === ".git" || entry.name === "node_modules")
+                        continue;
+                    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+                    const abs = resolve(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        walk(abs, rel);
+                        continue;
+                    }
+                    files.push(rel);
+                }
+            };
+            try {
+                walk(repoRoot);
+            }
+            catch {
+                return [];
+            }
+            return files.map((relativePath) => ({
+                relative_path: relativePath,
+                checksum: `fs:${relativePath}`,
+                module: relativePath.split("/")[0] || undefined,
+                language: relativePath.includes(".") ? relativePath.split(".").pop() || undefined : undefined,
+            }));
+        }
+    }
+    handleProjectReindexDiff(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.project_id) {
+            throw new Error("project.reindex_diff requires payload.project_id");
+        }
+        return this.slotDb.reindexProjectByDiff(identity.userId, identity.agentId, {
+            project_id: payload.project_id,
+            source_rev: payload.source_rev,
+            trigger_type: payload.trigger_type,
+            index_profile: payload.index_profile,
+            paths: payload.paths || [],
+        });
+    }
+    handleProjectIndexWatchGet(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.project_id) {
+            throw new Error("project.index_watch_get requires payload.project_id");
+        }
+        return this.slotDb.getProjectIndexWatchState(identity.userId, identity.agentId, payload.project_id);
+    }
+    handleProjectTaskRegistryUpsert(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.task_id || !payload.project_id || !payload.task_title) {
+            throw new Error("project.task_registry_upsert requires payload.task_id, payload.project_id, payload.task_title");
+        }
+        return this.slotDb.upsertTaskRegistryRecord(identity.userId, identity.agentId, {
+            task_id: payload.task_id,
+            project_id: payload.project_id,
+            task_title: payload.task_title,
+            task_type: payload.task_type,
+            task_status: payload.task_status,
+            parent_task_id: payload.parent_task_id,
+            related_task_ids: payload.related_task_ids || [],
+            files_touched: payload.files_touched || [],
+            symbols_touched: payload.symbols_touched || [],
+            commit_refs: payload.commit_refs || [],
+            diff_refs: payload.diff_refs || [],
+            decision_notes: payload.decision_notes ?? null,
+            tracker_issue_key: payload.tracker_issue_key ?? null,
+        });
+    }
+    handleProjectTaskLineageContext(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.project_id) {
+            throw new Error("project.task_lineage_context requires payload.project_id");
+        }
+        if (!payload.task_id && !payload.tracker_issue_key && !payload.task_title) {
+            throw new Error("project.task_lineage_context requires one selector: task_id|tracker_issue_key|task_title");
+        }
+        return this.slotDb.getTaskLineageContext(identity.userId, identity.agentId, {
+            project_id: payload.project_id,
+            task_id: payload.task_id,
+            tracker_issue_key: payload.tracker_issue_key,
+            task_title: payload.task_title,
+            include_related: payload.include_related,
+            include_parent_chain: payload.include_parent_chain,
+        });
+    }
+    handleProjectHybridSearch(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        if (!payload.project_id || !payload.query) {
+            throw new Error("project.hybrid_search requires payload.project_id and payload.query");
+        }
+        return this.slotDb.hybridSearchProjectContext(identity.userId, identity.agentId, {
+            project_id: payload.project_id,
+            query: payload.query,
+            limit: payload.limit,
+            path_prefix: payload.path_prefix || [],
+            module: payload.module || [],
+            language: payload.language || [],
+            task_id: payload.task_id || [],
+            tracker_issue_key: payload.tracker_issue_key || [],
+            task_context: payload.task_context,
+        });
+    }
+    handleProjectLegacyBackfill(payload, req) {
+        const identity = normalizePrivateIdentity(req.context);
+        return this.slotDb.runLegacyCompatibilityBackfill(identity.userId, identity.agentId, {
+            mode: payload.mode || "dry_run",
+            only_project_ids: payload.only_project_ids || [],
+            only_aliases: payload.only_aliases || [],
+            force_registration_state: payload.force_registration_state === true,
+            source: payload.source || "mixed",
+        });
+    }
+    handleProjectTelegramOnboarding(payload, req) {
+        const mode = payload.mode || "preview";
+        const workspaceRoot = this.normalizeRepoRootInput(payload.project_workspace_root) || this.resolveWorkspaceRoot(req);
+        const draft = {
+            command: String(payload.command || "").trim() || "/project",
+            repo_url: String(payload.repo_url || "").trim(),
+            project_alias: String(payload.project_alias || "").trim(),
+            jira_space_key: String(payload.jira_space_key || "").trim().toUpperCase(),
+            default_epic_key: String(payload.default_epic_key || "").trim().toUpperCase(),
+            index_now: payload.index_now === true,
+            project_name: String(payload.project_name || "").trim() || undefined,
+            repo_root: String(payload.repo_root || "").trim() || undefined,
+            active_version: String(payload.active_version || "").trim() || undefined,
+            project_workspace_root: workspaceRoot,
+        };
+        const errors = [];
+        const warnings = [];
+        if (!draft.repo_url && !draft.repo_root) {
+            errors.push("repo_url or repo_root is required");
+        }
+        if (!draft.project_alias) {
+            warnings.push("project_alias is empty; alias should be confirmed before final commit");
+        }
+        if (draft.jira_space_key) {
+            if (!/^[A-Z][A-Z0-9_]*$/.test(draft.jira_space_key)) {
+                errors.push("jira_space_key format is invalid");
+            }
+            if (draft.default_epic_key) {
+                const expectedPrefix = `${draft.jira_space_key}-`;
+                if (!draft.default_epic_key.startsWith(expectedPrefix)) {
+                    errors.push(`default_epic_key must match jira_space_key prefix '${draft.jira_space_key}-*'`);
+                }
+            }
+        }
+        else if (draft.default_epic_key) {
+            errors.push("jira_space_key is required when default_epic_key is provided");
+        }
+        const selectionPreview = this.resolveRepoForRegistration(normalizePrivateIdentity(req.context).userId, normalizePrivateIdentity(req.context).agentId, {
+            explicitRepoRoot: draft.repo_root,
+            repoUrl: draft.repo_url || undefined,
+            workspaceRoot,
+        });
+        const summaryCard = {
+            title: "Project onboarding preview",
+            fields: {
+                command: draft.command,
+                repo_url: draft.repo_url || null,
+                repo_root: selectionPreview.repo_root || null,
+                project_alias: draft.project_alias || null,
+                jira_space_key: draft.jira_space_key || null,
+                default_epic_key: draft.default_epic_key || null,
+                index_now: draft.index_now,
+                project_workspace_root: workspaceRoot,
+                repo_resolution: selectionPreview.resolution,
+                clone_policy: selectionPreview.clone_policy || "not_applicable",
+            },
+            actions: ["confirm", "edit_alias", "edit_jira", "index_now", "cancel"],
+            notes: selectionPreview.notes,
+        };
+        if (mode !== "confirm") {
+            return {
+                status: errors.length > 0 ? "validation_error" : "preview_ready",
+                errors,
+                warnings,
+                summary_card: summaryCard,
+                bridge_commands: {
+                    register: "project.register_command",
+                    link_tracker: "project.link_tracker",
+                    trigger_index: "project.trigger_index",
+                },
+            };
+        }
+        if (errors.length > 0) {
+            return {
+                status: "validation_error",
+                errors,
+                warnings,
+                summary_card: summaryCard,
+            };
+        }
+        const registerPayload = {
+            project_alias: draft.project_alias,
+            project_name: draft.project_name,
+            repo_root: draft.repo_root,
+            repo_remote: draft.repo_url || undefined,
+            repo_url: draft.repo_url || undefined,
+            active_version: draft.active_version,
+            options: {
+                trigger_index: draft.index_now,
+            },
+            tracker: draft.jira_space_key
+                ? {
+                    tracker_type: "jira",
+                    tracker_space_key: draft.jira_space_key,
+                    default_epic_key: draft.default_epic_key || undefined,
+                    active_version: draft.active_version,
+                }
+                : undefined,
+        };
+        const registered = this.handleProjectRegisterCommand(registerPayload, req);
+        return {
+            status: "committed",
+            project_id: registered.project_id,
+            project_alias: registered.project_alias,
+            tracker_mapping: registered.tracker_mapping,
+            repo_resolution: registered.repo_resolution,
+            index_trigger: registered.index_trigger,
+            warnings,
+            used_commands: ["project.register_command", "project.link_tracker", "project.trigger_index"],
+        };
+    }
     handleGraphEntityGet(payload, req) {
         const identity = normalizePrivateIdentity(req.context);
         if (payload.id) {