salmon-loop 0.2.3 → 0.2.16

package/dist/core/skills/runtime/SkillRunner.js

@@ -1,8 +1,103 @@
 import * as crypto from 'crypto';
 import { MicroTaskRunner } from '../../grizzco/dsl/MicroTaskRunner.js';
+import { tryGetLogger } from '../../observability/logger.js';
 import { Phase } from '../../types/index.js';
+import { emitSkillAuditEvent, generateSkillTraceId, hashSkillArgs } from '../audit.js';
 import { SkillParser } from '../parser.js';
 import { SkillStrategyDSL } from '../strategy.js';
+/**
+ * Resolve the effective allowed-tools set for a skill.
+ *
+ * Uses only the AgentSkills spec field (`allowed-tools`, space-delimited string)
+ * and returns a single `Set<string>`. Returns `null` when the field is not
+ * declared, meaning the skill places no tool restrictions.
+ *
+ * Distinguishes three states:
+ * - Field not declared → `null` (no restriction)
+ * - Field declared but empty (`""`) → empty `Set` (deny all tools)
+ * - Field declared with values → `Set` containing those tool names
+ *
+ * @see https://agentskills.io/specification — allowed-tools field
+ */
+function resolveAllowedTools(skill) {
+    const specField = skill.metadata?.['allowed-tools'];
+    if (specField === undefined)
+        return null;
+    if (!specField.trim())
+        return new Set();
+    return new Set(specField.split(/\s+/).filter(Boolean));
+}
+/**
+ * Match a tool name against an allowed-tools pattern.
+ *
+ * Supports two modes:
+ * - Exact match: pattern contains no `*` → strict string equality
+ * - Glob match: pattern contains `*` → each `*` matches zero or more characters
+ *
+ * Case-sensitive. Only `*` is treated as special; no `?` or `[...]` ranges.
+ *
+ * Uses an iterative segment-matching algorithm (no regex) to avoid ReDoS risk.
+ *
+ * @param pattern - An allowed-tools entry (e.g. "shell.*", "code.search")
+ * @param toolName - The tool name to check (e.g. "shell.exec")
+ * @returns true if toolName matches the pattern
+ */
+export function matchAllowedTool(pattern, toolName) {
+    // Split pattern on '*' into literal segments
+    const segments = pattern.split('*');
+    // No wildcard → exact match
+    if (segments.length === 1) {
+        return pattern === toolName;
+    }
+    const first = segments[0];
+    const last = segments[segments.length - 1];
+    // toolName must start with the first segment
+    if (!toolName.startsWith(first)) {
+        return false;
+    }
+    // toolName must end with the last segment
+    if (!toolName.endsWith(last)) {
+        return false;
+    }
+    // Guard: the tool name must be long enough to contain all literal segments
+    // without overlap between the first/last anchors
+    let pos = first.length;
+    const endBound = toolName.length - last.length;
+    // Match each middle segment in order (greedy left-to-right scan)
+    for (let i = 1; i < segments.length - 1; i++) {
+        const seg = segments[i];
+        if (seg === '') {
+            // Consecutive '*' — matches any amount of characters, skip
+            continue;
+        }
+        const idx = toolName.indexOf(seg, pos);
+        if (idx === -1 || idx + seg.length > endBound) {
+            return false;
+        }
+        pos = idx + seg.length;
+    }
+    return pos <= endBound;
+}
+/**
+ * Check whether a tool name is permitted by the allowed-tools set.
+ *
+ * @param toolName - The tool name to check
+ * @param allowedTools - The resolved allowed-tools set, or null for no restriction
+ * @returns true if the tool is permitted
+ */
+export function isToolPermitted(toolName, allowedTools) {
+    // null means no restriction — all tools permitted
+    if (allowedTools === null) {
+        return true;
+    }
+    // Iterate entries; return true if any pattern matches
+    for (const pattern of allowedTools) {
+        if (matchAllowedTool(pattern, toolName)) {
+            return true;
+        }
+    }
+    return false;
+}
 function buildStableId(parts) {
     return crypto.createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 16);
 }
@@ -29,8 +124,24 @@ function formatShellTranscript(shellOutputs) {
  */
 export async function executeSkill(options) {
     const { skill, argsText, toolRouter, toolCtx, signal } = options;
+    const route = options.route ?? 'slash-governed';
     const inputs = { args: argsText ?? '' };
     const rawCommands = SkillParser.extractCommands(skill.instructions || '');
+    const traceId = generateSkillTraceId(skill.id);
+    const argsHash = hashSkillArgs(argsText);
+    const startedAt = Date.now();
+    const allowedTools = resolveAllowedTools(skill);
+    // Emit SKILL_EXECUTION_START before execution
+    emitSkillAuditEvent({
+        type: 'SKILL_EXECUTION_START',
+        skillId: skill.id,
+        route,
+        runnerClass: 'MicroTaskRunner',
+        commandCount: rawCommands.length,
+        authorizationMode: 'blocking',
+        argsHash,
+        traceId,
+    });
     const requiredShKeys = rawCommands.map((cmd) => `sh:${SkillParser.substituteVariables(cmd, inputs)}`);
     const data = {
         skill,
@@ -43,66 +154,134 @@ export async function executeSkill(options) {
         skillId: skill.id,
         path: skill.path,
     };
-    const runner = new MicroTaskRunner({
-        debugLabel: `SkillRunner:${skill.id}`,
-        maxRounds: 10,
-        strategy: (engine) => {
-            // Computation phase: assemble a prompt without any "!..." lines.
-            const promptLines = (skill.instructions || '')
-                .split('\n')
-                .filter((line) => !line.trim().startsWith('!'));
-            const basePrompt = SkillParser.substituteVariables(promptLines.join('\n').trim(), inputs);
-            const transcript = formatShellTranscript(data.shell_outputs);
-            data.prompt = `${basePrompt}${transcript}`.trim();
-            SkillStrategyDSL(engine);
-            return engine;
-        },
-        resolveData: async (_ctx, key) => {
-            if (!key.startsWith('sh:')) {
-                return undefined;
-            }
-            const command = key.slice(3);
-            const callId = `slash-sh-${buildStableId([skill.id, command])}`;
-            const envelope = {
-                id: callId,
-                phase: Phase.SLASH,
-                toolName: 'shell.exec',
-                args: { command },
-                ctx: {
-                    ...toolCtx,
-                    // Ensure ToolPolicy sees worktree isolation for process execution.
-                    worktreeRoot: toolCtx.worktreeRoot ?? toolCtx.repoRoot,
-                },
-            };
-            let result = await toolRouter.call(envelope);
-            if (result.status === 'denied' && result.error?.code === 'AUTH_REQUIRED') {
-                await toolRouter.waitForAuthorization(callId, signal);
-                result = await toolRouter.call(envelope);
-            }
-            if (result.status !== 'ok') {
-                const msg = result.error?.message || 'shell.exec failed';
-                throw new Error(msg);
-            }
-            const output = result.output;
-            const combined = [output.stdout, output.stderr].filter(Boolean).join('\n').trim();
-            data.shell_outputs[command] = combined;
-            data[key] = combined;
-            return combined;
-        },
-    });
-    const decided = await runner.decide(ctx);
-    const plan = decided.plan;
-    const inject = plan.actions.find((a) => a.type === 'INJECT_PROMPT');
-    return {
-        traceId: `skill-${skill.id}-${Date.now()}`,
-        skillId: skill.id,
-        inputs,
-        dynamicCommands: Object.entries(data.shell_outputs).map(([cmd, output]) => ({
-            cmd,
-            output: String(output),
-        })),
-        injectedPrompt: String(inject?.params?.prompt ?? ''),
-        status: plan.shouldAbort ? 'FAILURE' : 'SUCCESS',
-    };
+    try {
+        const runner = new MicroTaskRunner({
+            debugLabel: `SkillRunner:${skill.id}`,
+            maxRounds: 10,
+            strategy: (engine) => {
+                // Computation phase: assemble a prompt without any "!..." lines.
+                const promptLines = (skill.instructions || '')
+                    .split('\n')
+                    .filter((line) => !line.trim().startsWith('!'));
+                const basePrompt = SkillParser.substituteVariables(promptLines.join('\n').trim(), inputs);
+                const transcript = formatShellTranscript(data.shell_outputs);
+                data.prompt = `${basePrompt}${transcript}`.trim();
+                SkillStrategyDSL(engine);
+                return engine;
+            },
+            resolveData: async (_ctx, key) => {
+                if (!key.startsWith('sh:')) {
+                    return undefined;
+                }
+                const command = key.slice(3);
+                const toolName = 'shell.exec';
+                // Enforce allowed-tools constraint from skill frontmatter.
+                // When declared, only pre-approved tools may be invoked.
+                // Uses isToolPermitted for glob pattern matching support.
+                if (!isToolPermitted(toolName, allowedTools)) {
+                    const logger = tryGetLogger();
+                    logger?.warn(`Skill "${skill.id}" attempted to use tool "${toolName}" which is not in allowed-tools: [${[...(allowedTools ?? [])].join(', ')}]`);
+                    emitSkillAuditEvent({
+                        type: 'SKILL_EXECUTION_DENIED',
+                        skillId: skill.id,
+                        route,
+                        runnerClass: 'MicroTaskRunner',
+                        commandCount: rawCommands.length,
+                        authorizationMode: 'blocking',
+                        argsHash,
+                        traceId,
+                        denyReason: 'ALLOWED_TOOLS_VIOLATION',
+                        denySource: `skill-frontmatter:allowed-tools`,
+                        durationMs: Date.now() - startedAt,
+                    });
+                    throw new Error(`Tool "${toolName}" is not permitted by skill "${skill.id}" allowed-tools policy`);
+                }
+                const callId = `slash-sh-${buildStableId([skill.id, command])}`;
+                const envelope = {
+                    id: callId,
+                    phase: Phase.SLASH,
+                    toolName: 'shell.exec',
+                    args: { command },
+                    ctx: {
+                        ...toolCtx,
+                        // Ensure ToolPolicy sees worktree isolation for process execution.
+                        worktreeRoot: toolCtx.worktreeRoot ?? toolCtx.repoRoot,
+                    },
+                };
+                let result = await toolRouter.call(envelope);
+                if (result.status === 'denied' && result.error?.code === 'AUTH_REQUIRED') {
+                    await toolRouter.waitForAuthorization(callId, signal);
+                    result = await toolRouter.call(envelope);
+                }
+                if (result.status !== 'ok') {
+                    const msg = result.error?.message || 'shell.exec failed';
+                    // Emit SKILL_EXECUTION_DENIED for command-level denial
+                    if (result.status === 'denied') {
+                        emitSkillAuditEvent({
+                            type: 'SKILL_EXECUTION_DENIED',
+                            skillId: skill.id,
+                            route,
+                            runnerClass: 'MicroTaskRunner',
+                            commandCount: rawCommands.length,
+                            authorizationMode: 'blocking',
+                            argsHash,
+                            traceId,
+                            denyReason: result.error?.code || 'unknown',
+                            denySource: result.meta?.authorization?.source || 'policy',
+                            durationMs: Date.now() - startedAt,
+                        });
+                    }
+                    throw new Error(msg);
+                }
+                const output = result.output;
+                const combined = [output.stdout, output.stderr].filter(Boolean).join('\n').trim();
+                data.shell_outputs[command] = combined;
+                data[key] = combined;
+                return combined;
+            },
+        });
+        const decided = await runner.decide(ctx);
+        const plan = decided.plan;
+        const inject = plan.actions.find((a) => a.type === 'INJECT_PROMPT');
+        const status = plan.shouldAbort ? 'FAILURE' : 'SUCCESS';
+        // Emit SKILL_EXECUTION_END after successful execution
+        emitSkillAuditEvent({
+            type: 'SKILL_EXECUTION_END',
+            skillId: skill.id,
+            route,
+            runnerClass: 'MicroTaskRunner',
+            commandCount: rawCommands.length,
+            authorizationMode: 'blocking',
+            argsHash,
+            traceId,
+            durationMs: Date.now() - startedAt,
+        });
+        return {
+            traceId,
+            skillId: skill.id,
+            inputs,
+            dynamicCommands: Object.entries(data.shell_outputs).map(([cmd, output]) => ({
+                cmd,
+                output: String(output),
+            })),
+            injectedPrompt: String(inject?.params?.prompt ?? ''),
+            status,
+        };
+    }
+    catch (error) {
+        // Emit SKILL_EXECUTION_END on failure (non-denial errors)
+        emitSkillAuditEvent({
+            type: 'SKILL_EXECUTION_END',
+            skillId: skill.id,
+            route,
+            runnerClass: 'MicroTaskRunner',
+            commandCount: rawCommands.length,
+            authorizationMode: 'blocking',
+            argsHash,
+            traceId,
+            durationMs: Date.now() - startedAt,
+        });
+        throw error;
+    }
 }
 //# sourceMappingURL=SkillRunner.js.map

package/dist/core/strata/layers/shadow-driver/shadow-driver.js

@@ -5,16 +5,41 @@
  */
 import { join } from 'path';
 import { existsSync } from '../../../adapters/fs/node-fs.js';
-import { rm, mkdir, symlink } from '../../../adapters/fs/node-fs.js';
+import { lstat, mkdir, realpath, rm, symlink } from '../../../adapters/fs/node-fs.js';
 import { getLogger } from '../../../observability/logger.js';
 import { spawnCommand } from '../../../runtime/process-runner.js';
-import { normalizePath } from '../../../utils/path.js';
+import { arePathsEquivalent, normalizePath } from '../../../utils/path.js';
 import { getPlatformShellInvocation } from '../../../utils/platform-shell.js';
 import { copyDir, linkDirLinux } from './copy-backend.js';
 import { getEnvInjection } from './env.js';
 import { isEnvironmentError } from './error-classifier.js';
 import { enforceReadOnly, restoreWrite, acquireLock, releaseLock } from './readonly-lock.js';
 import { determineStrategy, planDependencyPaths, detectDependencyPaths } from './strategy.js';
+const DEPENDENCY_LINK_CONFLICT_CODES = new Set([
+    'EEXIST',
+    'EISDIR',
+    'ENOTEMPTY',
+    'ENOTDIR',
+    'EPERM',
+]);
+function getErrorCode(error) {
+    return error && typeof error === 'object' && 'code' in error
+        ? error.code
+        : undefined;
+}
+async function pointsToExpectedDependency(sourcePath, targetPath) {
+    try {
+        await lstat(targetPath);
+        const [resolvedSourcePath, resolvedTargetPath] = await Promise.all([
+            realpath(sourcePath),
+            realpath(targetPath),
+        ]);
+        return arePathsEquivalent(resolvedSourcePath, resolvedTargetPath);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * ShadowDriver Class
  */
@@ -49,13 +74,18 @@ export class ShadowDriver {
                 getLogger().debug(`Linked dependency: ${depPath}`);
             }
             catch (err) {
-                if ((err && typeof err === 'object' && 'code' in err
-                    ? err.code
-                    : undefined) !== 'EEXIST') {
-                    getLogger().warn(`Failed to link ${depPath}: ${err instanceof Error ? err.message : String(err)}`);
+                const errorCode = getErrorCode(err);
+                if (errorCode && DEPENDENCY_LINK_CONFLICT_CODES.has(errorCode)) {
+                    const alreadyProjected = await pointsToExpectedDependency(sourcePath, targetDepPath);
+                    if (alreadyProjected) {
+                        getLogger().debug(`Dependency projection already matches source: ${depPath}`);
+                        continue;
+                    }
+                    throw new Error(`Dependency projection path conflict for ${depPath}: ${err instanceof Error ? err.message : String(err)}`);
                 }
                 else {
-                    getLogger().debug(`Dependency link already exists: ${depPath}`);
+                    getLogger().warn(`Failed to link ${depPath}: ${err instanceof Error ? err.message : String(err)}`);
+                    throw err instanceof Error ? err : new Error(String(err));
                 }
             }
         }

package/dist/core/strata/layers/worktree.js

@@ -2,10 +2,11 @@ import { randomBytes } from 'crypto';
 import { tmpdir } from 'os';
 import path from 'path';
 import { text } from '../../../locales/index.js';
-import { access, realpath, rm } from '../../adapters/fs/node-fs.js';
+import { access, readdir, realpath, rm } from '../../adapters/fs/node-fs.js';
 import { GitAdapter } from '../../adapters/git/git-adapter.js';
 import { getLogger } from '../../observability/logger.js';
 import { isPathWithinDirectory, normalizePath } from '../../utils/path.js';
+import { detectDependencyPaths } from './shadow-driver/strategy.js';
 function resolveEnvironmentMode(options) {
     return options.environmentMode === 'parity' ? 'parity' : 'strict';
 }
@@ -28,12 +29,11 @@ function resolveParityWorktreeRoot(repoPath) {
     return normalizePath(impl.join(impl.dirname(impl.resolve(normalizedRepoPath)), '.salmonloop', 'worktrees'));
 }
 function isManagedWorktreePath(baseRepoPath, workPath) {
-    if (isPathWithinDirectory(tmpdir(), workPath, { allowEqual: false }))
-        return true;
-    const parityRoot = resolveParityWorktreeRoot(baseRepoPath);
-    if (isPathWithinDirectory(parityRoot, workPath, { allowEqual: false }))
-        return true;
-    return false;
+    const comparableWorkPath = normalizePathForCompare(workPath);
+    const managedRoots = [tmpdir(), resolveParityWorktreeRoot(baseRepoPath)];
+    return managedRoots.some((root) => isPathWithinDirectory(normalizePathForCompare(root), comparableWorkPath, {
+        allowEqual: false,
+    }));
 }
 function normalizePathForCompare(value) {
     const normalized = path.normalize(value).replace(/\\/g, '/');
@@ -67,6 +67,59 @@ async function resolveWorktreeMatchPath(worktreePaths, targetPath) {
     }
     return null;
 }
+async function removeProjectedWorktreeEntries(workPath) {
+    let worktreeRealPath;
+    try {
+        worktreeRealPath = await realpath(workPath);
+    }
+    catch (error) {
+        throw new Error(`Failed to resolve worktree path before git cleanup (${workPath}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let entries = [];
+    try {
+        entries = (await readdir(workPath, { withFileTypes: true }));
+    }
+    catch (error) {
+        throw new Error(`Failed to enumerate worktree entries before git cleanup (${workPath}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const entry of entries) {
+        const name = entry?.name;
+        if (!name || name === '.git')
+            continue;
+        const entryPath = path.join(workPath, name);
+        const entryRealPath = await tryRealpath(entryPath);
+        if (!entryRealPath)
+            continue;
+        if (isPathWithinDirectory(worktreeRealPath, entryRealPath, { allowEqual: false })) {
+            continue;
+        }
+        await rm(entryPath, {
+            recursive: true,
+            force: true,
+            maxRetries: 3,
+            retryDelay: 100,
+        });
+        getLogger().debug(`Removed projected worktree entry before git cleanup: ${entryPath}`);
+    }
+}
+async function pruneWorktreeDependencyRoots(baseRepoPath, worktreePath) {
+    const dependencyPaths = await detectDependencyPaths(baseRepoPath);
+    for (const dependencyPath of dependencyPaths) {
+        const dependencyRoot = path.join(worktreePath, dependencyPath);
+        try {
+            await rm(dependencyRoot, {
+                recursive: true,
+                force: true,
+                maxRetries: 3,
+                retryDelay: 100,
+            });
+            getLogger().debug(`Pruned disposable dependency root before worktree cleanup: ${dependencyRoot}`);
+        }
+        catch (error) {
+            getLogger().debug(`Failed to prune dependency root before worktree cleanup (${dependencyRoot}): ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
 /**
  * WorkspaceManager - Manages execution workspace for different checkpoint strategies
  *
@@ -101,17 +154,17 @@ export class WorkspaceManager {
             if (environmentMode === 'parity') {
                 const parityRoot = worktreeRootImpl.normalize(resolveParityWorktreeRoot(options.repoPath));
                 if (!isPathWithinDirectory(parityRoot, normalizedWorktreePath, { allowEqual: false })) {
-                    throw new Error('Worktree path must be under parity worktree root');
+                    throw new Error(text.errors.worktreePathMustBeUnderParityRoot);
                 }
             }
             else {
                 const tmpDir = worktreeRootImpl.normalize(tmpdir());
                 if (!isPathWithinDirectory(tmpDir, normalizedWorktreePath, { allowEqual: false })) {
-                    throw new Error('Worktree path must be in system temp directory');
+                    throw new Error(text.errors.worktreePathMustBeInTempDir);
                 }
             }
             if (isPathWithinDirectory(options.repoPath, worktreePath, { allowEqual: true })) {
-                throw new Error('Worktree path must not be inside repo path');
+                throw new Error(text.errors.worktreePathMustNotBeInsideRepo);
             }
             // Use GitAdapter for worktree creation
             await git.query(['worktree', 'add', '--quiet', '--detach', worktreePath, baseRef.trim()]);
@@ -163,9 +216,14 @@ export class WorkspaceManager {
             });
             return;
         }
+        // CRITICAL SAFETY: refuse any destructive cleanup outside managed worktree roots.
+        if (!isManagedWorktreePath(workspace.baseRepoPath, workspace.workPath)) {
+            throw new Error(text.errors.worktreePathNotInManagedRoots);
+        }
         const git = new GitAdapter(workspace.baseRepoPath);
         let removed = false;
         try {
+            await pruneWorktreeDependencyRoots(workspace.baseRepoPath, workspace.workPath);
             const list = await git.query(['worktree', 'list', '--porcelain']);
             const worktreePaths = list
                 .split('\n')
@@ -175,6 +233,8 @@ export class WorkspaceManager {
                 .filter(Boolean);
             const matchPath = await resolveWorktreeMatchPath(worktreePaths, workspace.workPath);
             if (matchPath) {
+                // CRITICAL SAFETY: if projection inspection fails, do not risk git traversing external roots.
+                await removeProjectedWorktreeEntries(workspace.workPath);
                 await git.query(['worktree', 'remove', '--force', matchPath]);
                 removed = true;
                 const directoryStillExists = await (async () => {
@@ -224,9 +284,6 @@ export class WorkspaceManager {
             getLogger().debug(`git worktree remove failed, falling back to filesystem removal: ${msg}`);
         }
         if (!removed) {
-            if (!isManagedWorktreePath(workspace.baseRepoPath, workspace.workPath)) {
-                throw new Error('Worktree path not in managed roots, refusing to delete');
-            }
             await rm(workspace.workPath, {
                 recursive: true,
                 force: true,

package/dist/core/strata/runtime/synchronizer.js

@@ -3,11 +3,12 @@ import { tmpdir } from 'os';
 import path from 'path';
 import { text } from '../../../locales/index.js';
 import { TextNormalizer } from '../../../utils/eol.js';
-import { copyFile, lstat, mkdir, readFile, readdir, rm, stat, unlink, writeFile, } from '../../adapters/fs/node-fs.js';
+import { copyFile, lstat, mkdir, readFile, readdir, realpath, rm, stat, unlink, writeFile, } from '../../adapters/fs/node-fs.js';
 import { GitAdapter } from '../../adapters/git/git-adapter.js';
 import { logIgnoredError } from '../../observability/ignored-error.js';
 import { getLogger } from '../../observability/logger.js';
 import { getMonitor } from '../../observability/monitor.js';
+import { isCanonicalPathWithinDirectory } from '../../utils/path.js';
 import { detectDependencyPaths } from '../layers/shadow-driver/strategy.js';
 const SECURITY_BLOCKLIST = [
     /^\.git(\/|\\)/i,
@@ -51,6 +52,27 @@ export class WorkspaceSynchronizer {
     normalizePath(value) {
         return value.replace(/\\/g, '/');
     }
+    async tryRealPath(value) {
+        try {
+            return await realpath(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    async isProjectedDependencyRoot(repoRealPath, candidatePath, entryStat) {
+        if (entryStat?.isSymbolicLink()) {
+            return true;
+        }
+        if (!repoRealPath) {
+            return false;
+        }
+        const candidateRealPath = await this.tryRealPath(candidatePath);
+        if (!candidateRealPath) {
+            return false;
+        }
+        return !isCanonicalPathWithinDirectory(repoRealPath, candidateRealPath, { allowEqual: true });
+    }
     isRenameOrCopyStatus(xy) {
         const x = xy.charAt(0);
         const y = xy.charAt(1);
@@ -120,6 +142,7 @@ export class WorkspaceSynchronizer {
             ...detectedDependencyPaths,
         ]);
         const symlinkedRoots = new Set();
+        const repoRealPath = await this.tryRealPath(repoPath);
         for (const candidate of candidates) {
             const normalizedCandidate = this.sanitizeRelativePath(candidate);
             if (!normalizedCandidate || normalizedCandidate.includes('/')) {
@@ -128,7 +151,11 @@ export class WorkspaceSynchronizer {
             const candidatePath = path.join(repoPath, ...normalizedCandidate.split('/'));
             try {
                 const entryStat = await lstat(candidatePath);
-                if (entryStat.isSymbolicLink()) {
+                const isProjectedRoot = await this.isProjectedDependencyRoot(repoRealPath, candidatePath, entryStat);
+                if (isProjectedRoot) {
+                    if (!entryStat.isSymbolicLink()) {
+                        getLogger().debug(`[checkpoint] Treating dependency root as projected via realpath escape: ${normalizedCandidate}`);
+                    }
                     symlinkedRoots.add(normalizedCandidate);
                 }
             }