agentic-qe 3.15.8 → 3.15.10

package/dist/coordination/task-dag/types.d.ts

@@ -37,6 +37,8 @@ export interface DAGTask {
     result?: unknown;
     /** Error message from failed execution */
     error?: string;
+    /** Caller-supplied completion evidence reference (set by complete()) */
+    evidenceRef?: string;
 }
 /** Input for adding a task to the DAG */
 export interface AddTaskInput {
@@ -76,8 +78,21 @@ export interface DAGStats {
     /** Whether the graph contains cycles (should always be false for a valid DAG) */
     readonly hasCycles: boolean;
 }
+/** Serialized view of a TaskDAG returned by toJSON() */
+export interface DAGSnapshot {
+    readonly graphId: string;
+    readonly graphRevision: number;
+    readonly tasks: DAGTask[];
+    readonly edges: Array<{
+        from: string;
+        to: string;
+    }>;
+    readonly receipts: PrerequisiteReceiptV1[];
+    readonly removedTasks: RemovedTaskRecord[];
+    readonly stats: DAGStats;
+}
 /** Event types emitted by the DAG */
-export type DAGEventType = 'task-ready' | 'task-completed' | 'task-failed' | 'tasks-unblocked' | 'cycle-detected';
+export type DAGEventType = 'task-ready' | 'task-completed' | 'task-failed' | 'task-cancelled' | 'task-removed' | 'prerequisite-waived' | 'tasks-unblocked' | 'cycle-detected';
 /** Event emitted by the DAG when state changes occur */
 export interface DAGEvent {
     /** Type of event that occurred */
@@ -88,6 +103,12 @@ export interface DAGEvent {
     readonly unblockedTaskIds?: string[];
     /** Node IDs involved in detected cycles (for 'cycle-detected' events) */
     readonly cycleNodes?: string[];
+    /** Prerequisite ID (for 'prerequisite-waived' events) */
+    readonly prerequisiteId?: string;
+    /** Dependents whose edge was tombstoned (for 'task-removed' events) */
+    readonly affectedTaskIds?: string[];
+    /** Graph revision at which the change was committed */
+    readonly graphRevision?: number;
     /** Timestamp when the event occurred (epoch ms) */
     readonly timestamp: number;
 }
@@ -100,4 +121,142 @@ export interface DAGSchedulerConfig {
 }
 /** Event handler callback for DAG events */
 export type DAGEventHandler = (event: DAGEvent) => void;
+/**
+ * Typed state of one prerequisite edge (dependent -> prerequisite).
+ * Only SATISFIED and WAIVED allow a dependent to become ready.
+ */
+export type PrerequisiteDisposition = 'UNRESOLVED' | 'SATISFIED' | 'FAILED' | 'CANCELLED' | 'WAIVED' | 'MISSING' | 'REMOVED';
+/** Schema identifier for PrerequisiteReceiptV1 */
+export declare const PREREQUISITE_RECEIPT_SCHEMA: "aqe.task-prerequisite@1";
+/** Waiver attached to a WAIVED receipt */
+export interface PrerequisiteWaiver {
+    /** Who issued the waiver */
+    readonly actor: string;
+    /** Why the prerequisite is waived */
+    readonly reason: string;
+    /** Reference to the authority (ticket, policy, approval) backing the waiver */
+    readonly authorityRef?: string;
+    /** ISO-8601 time the waiver was issued */
+    readonly issuedAt: string;
+}
+/** Immutable record of a prerequisite edge changing disposition */
+export interface PrerequisiteReceiptV1 {
+    readonly schema: typeof PREREQUISITE_RECEIPT_SCHEMA;
+    readonly graphId: string;
+    /** Graph revision at which this disposition was committed */
+    readonly graphRevision: number;
+    /** Dependent task */
+    readonly taskId: string;
+    /** Prerequisite task */
+    readonly prerequisiteId: string;
+    readonly disposition: PrerequisiteDisposition;
+    /** Evidence bound to a SATISFIED disposition (from complete()) */
+    readonly completionEvidenceRef?: string;
+    /** Present only on WAIVED receipts */
+    readonly waiver?: PrerequisiteWaiver;
+    /** ISO-8601 time the disposition was observed */
+    readonly observedAt: string;
+}
+/** Current disposition of one prerequisite edge, with its latest receipt */
+export interface PrerequisiteEdgeState {
+    readonly prerequisiteId: string;
+    readonly disposition: PrerequisiteDisposition;
+    readonly receipt: PrerequisiteReceiptV1;
+}
+/** Input for TaskDAG.waivePrerequisite() */
+export interface WaivePrerequisiteInput {
+    /** Dependent task whose prerequisite is waived */
+    readonly taskId: string;
+    /** Prerequisite being waived */
+    readonly prerequisiteId: string;
+    /** Who is waiving (required, non-empty) */
+    readonly actor: string;
+    /** Why it is waived (required, non-empty) */
+    readonly reason: string;
+    /** Optional reference to the authority backing the waiver */
+    readonly authorityRef?: string;
+    /** Compare-and-swap guard: reject if the graph revision has moved */
+    readonly expectedRevision?: number;
+}
+/** Context passed to a waiver policy */
+export interface WaiverRequest {
+    readonly graphId: string;
+    readonly graphRevision: number;
+    readonly taskId: string;
+    readonly prerequisiteId: string;
+    readonly actor: string;
+    readonly reason: string;
+    readonly authorityRef?: string;
+    readonly currentDisposition: PrerequisiteDisposition;
+}
+/** Policy deciding whether a waiver is authorized; return false to reject */
+export type WaiverPolicy = (request: WaiverRequest) => boolean;
+/** Options for constructing a TaskDAG */
+export interface TaskDAGOptions {
+    /** Stable graph identity (defaults to a random UUID-based ID) */
+    readonly graphId?: string;
+    /** Optional authorization policy applied to every waiver */
+    readonly waiverPolicy?: WaiverPolicy;
+}
+/** Options for TaskDAG.complete() */
+export interface CompleteTaskOptions {
+    /** Evidence reference bound to the SATISFIED receipts this completion emits */
+    readonly evidenceRef?: string;
+    /** Compare-and-swap guard: reject if the graph revision has moved */
+    readonly expectedRevision?: number;
+}
+/** Options for TaskDAG.removeTask() */
+export interface RemoveTaskOptions {
+    /** Compare-and-swap guard: reject if the graph revision has moved */
+    readonly expectedRevision?: number;
+}
+/** A task that was removed from the graph, kept as a tombstone */
+export interface RemovedTaskRecord {
+    readonly taskId: string;
+    /** Status the task had when it was removed */
+    readonly statusAtRemoval: DAGTaskStatus;
+    readonly graphRevision: number;
+}
+/**
+ * Obligation accounting over the original graph. Removed tasks stay in
+ * the denominator; completed-then-removed tasks still count as completed.
+ */
+export interface ObligationSummary {
+    readonly graphId: string;
+    readonly graphRevision: number;
+    /** Every task ever added since construction or clear() */
+    readonly originalTotal: number;
+    /** Tasks currently present in the graph */
+    readonly currentTotal: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly cancelled: number;
+    /** Tasks removed before completing */
+    readonly removed: number;
+    /** Live tasks not yet terminal (pending, blocked, ready, in_progress) */
+    readonly notRun: number;
+    /** Live edges whose current disposition is WAIVED */
+    readonly waivedEdges: number;
+    /** Live edges whose current disposition is MISSING */
+    readonly missingEdges: number;
+    /** Live edges whose current disposition is REMOVED */
+    readonly removedEdges: number;
+}
+/** Progress report from DAGScheduler.getProgress() */
+export interface DAGProgress {
+    /** Completed obligations (including completed tasks later removed) */
+    readonly completed: number;
+    /** Original obligation denominator; does not shrink when tasks are removed */
+    readonly total: number;
+    /** completed / total, rounded */
+    readonly percentage: number;
+    /** Tasks currently present in the graph */
+    readonly currentTotal: number;
+    readonly failed: number;
+    readonly cancelled: number;
+    readonly removed: number;
+    readonly notRun: number;
+    readonly waivedEdges: number;
+    readonly graphRevision: number;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/coordination/task-dag/types.js

@@ -5,5 +5,6 @@
  * Defines the core types for representing tasks as nodes in a directed
  * acyclic graph, with dependency edges controlling execution order.
  */
-export {};
+/** Schema identifier for PrerequisiteReceiptV1 */
+export const PREREQUISITE_RECEIPT_SCHEMA = 'aqe.task-prerequisite@1';
 //# sourceMappingURL=types.js.map

package/dist/coordination/task-executability.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Agentic QE v3 - Task executability check (#1075, #1081)
+ *
+ * A Queen-owned task runs only if the domain plugin it is assigned to has an
+ * `executeTask` handler for its type. Anything else used to fall through to
+ * the `TaskAssigned` event fallback, which nothing answers, so the task stayed
+ * `running` and held a concurrency slot for good.
+ */
+import type { DomainName } from '../shared/types';
+import type { DomainPlugin } from '../kernel/interfaces';
+/**
+ * List the domains among `domains` that cannot execute `type`, each with the
+ * reason and, where known, the types it does support. An empty list means
+ * every domain can run the task.
+ */
+export declare function findDomainsWithoutHandler(domainPlugins: ReadonlyMap<DomainName, DomainPlugin>, type: string, domains: readonly DomainName[]): string[];
+export declare function describeMissingHandler(type: string, gaps: readonly string[]): string;
+//# sourceMappingURL=task-executability.d.ts.map

package/dist/coordination/task-executability.js

@@ -0,0 +1,31 @@
+/**
+ * Agentic QE v3 - Task executability check (#1075, #1081)
+ *
+ * A Queen-owned task runs only if the domain plugin it is assigned to has an
+ * `executeTask` handler for its type. Anything else used to fall through to
+ * the `TaskAssigned` event fallback, which nothing answers, so the task stayed
+ * `running` and held a concurrency slot for good.
+ */
+/**
+ * List the domains among `domains` that cannot execute `type`, each with the
+ * reason and, where known, the types it does support. An empty list means
+ * every domain can run the task.
+ */
+export function findDomainsWithoutHandler(domainPlugins, type, domains) {
+    const gaps = [];
+    for (const domain of domains) {
+        const plugin = domainPlugins.get(domain);
+        if (!plugin) {
+            gaps.push(`${domain} (domain not loaded)`);
+        }
+        else if (!plugin.executeTask || !plugin.canHandleTask?.(type)) {
+            const supported = plugin.getSupportedTaskTypes?.() ?? [];
+            gaps.push(supported.length > 0 ? `${domain} (supported: ${supported.join(', ')})` : domain);
+        }
+    }
+    return gaps;
+}
+export function describeMissingHandler(type, gaps) {
+    return `No handler for task type '${type}' in domain ${gaps.join('; ')}`;
+}
+//# sourceMappingURL=task-executability.js.map

package/dist/coordination/task-executor.d.ts

@@ -114,6 +114,7 @@ export declare class DomainTaskExecutor implements TaskHandlerContext {
      */
     getCodeIntelligenceCoordinator(): Promise<ProjectMetricsCollector | undefined>;
     getQualityAnalyzer(): QualityAnalyzerService;
+    getTestExecutionAPI(): Promise<import('../domains/test-execution/interfaces').ITestExecutionAPI | undefined>;
     private registerHandlers;
     /**
      * Get or create Agent Booster adapter (instance-level)

package/dist/coordination/task-executor.js

@@ -273,6 +273,11 @@ export class DomainTaskExecutor {
         }
         return this.qualityAnalyzer;
     }
+    async getTestExecutionAPI() {
+        return this.kernel.getDomainAPIAsync
+            ? this.kernel.getDomainAPIAsync('test-execution')
+            : this.kernel.getDomainAPI('test-execution');
+    }
     // ============================================================================
     // Handler Registration (delegates to extracted handler modules)
     // ============================================================================

package/dist/coordination/yaml-pipeline-loader.js

@@ -8,6 +8,7 @@
 import * as fs from 'node:fs/promises';
 import { parse as parseYaml } from 'yaml';
 import { ok, err, ALL_DOMAINS } from '../shared/types/index.js';
+import { getOwn } from '../shared/utils/safe-record.js';
 const VALID_OPERATORS = [
     'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'exists',
 ];
@@ -380,8 +381,10 @@ export class YamlPipelineLoader {
     }
     /** Resolve a dot-path variable (e.g. "foo.bar") from a variables map. */
     resolveVarPath(vars, path) {
+        // #1136: own properties only, so ${constructor} or ${x.toString} does
+        // not expand to an inherited Object.prototype member.
         // Try direct key first (covers flat keys like "coverageGoal")
-        if (path in vars)
+        if (Object.hasOwn(vars, path))
             return vars[path];
         // Try dot-path traversal
         const parts = path.split('.');
@@ -390,7 +393,7 @@ export class YamlPipelineLoader {
             if (current === null || current === undefined || typeof current !== 'object') {
                 return undefined;
             }
-            current = current[part];
+            current = getOwn(current, part);
         }
         return current;
     }

package/dist/domains/code-intelligence/coordinator.js

@@ -7,6 +7,8 @@
  * - QESONA: Learns and adapts code patterns for improved intelligence
  */
 import { resolveProjectRootFromPaths } from './project-root-resolver.js';
+import { nothingIndexedError, validateIndexPaths } from './index-path-guard.js';
+import { findProjectRoot } from '../../kernel/project-root.js';
 import { LoggerFactory } from '../../logging/index.js';
 import { v4 as uuidv4 } from 'uuid';
 import { err } from '../../shared/types/index.js';
@@ -86,7 +88,9 @@ export class CodeIntelligenceCoordinator extends BaseDomainCoordinator {
         this.knowledgeGraph = new KnowledgeGraphService({ memory, llmRouter });
         this.semanticAnalyzer = new SemanticAnalyzerService(memory);
         this.impactAnalyzer = new ImpactAnalyzerService(memory, this.knowledgeGraph);
-        this.fileReader = new FileReader();
+        // #1096: confine reads (semantic index, GNN) to the project root by
+        // realpath, as the knowledge graph does.
+        this.fileReader = new FileReader({ projectRoot: findProjectRoot() });
         // Initialize Product Factors Bridge.
         // ADR-112 C2: inject a KG-backed relationship resolver so C4 component
         // diagrams use REAL import/call edges (not the naming heuristic).
@@ -265,6 +269,13 @@ export class CodeIntelligenceCoordinator extends BaseDomainCoordinator {
      * Index codebase into Knowledge Graph
      */
     async index(request) {
+        // #1096: reject a malformed path list before any work starts. The size
+        // cap is enforced where callers hand in lists (task_submit, task_orchestrate,
+        // `aqe task submit`); `aqe code index` passes the files it discovered.
+        const validPaths = validateIndexPaths(request.paths, 'paths', 'Invalid index payload', Number.POSITIVE_INFINITY);
+        if (!validPaths.success) {
+            return validPaths;
+        }
         const workflowId = uuidv4();
         try {
             this.startWorkflow(workflowId, 'index');
@@ -291,17 +302,32 @@ export class CodeIntelligenceCoordinator extends BaseDomainCoordinator {
             this.updateWorkflowProgress(workflowId, 10);
             // Perform indexing
             const result = await this.knowledgeGraph.index(request);
+            // #1096: paths were requested but none was indexed - fail rather than
+            // report success, naming what was skipped and why.
+            if (result.success && result.value.filesIndexed === 0 && request.paths.length > 0) {
+                const failure = nothingIndexedError(request.paths.length, result.value.skipped ?? [], result.value.errors);
+                this.failWorkflow(workflowId, failure.message);
+                await this.agentCoordinator.stop(agentResult.value);
+                return err(failure);
+            }
             if (result.success) {
                 this.updateWorkflowProgress(workflowId, 40);
+                // #1096: the follow-up steps read file content too, so they only see
+                // the files the knowledge graph actually indexed.
+                const notIndexed = new Set([
+                    ...(result.value.skipped ?? []).map((s) => s.path),
+                    ...result.value.errors.map((e) => e.file),
+                ]);
+                const indexedPaths = request.paths.filter((p) => !notIndexed.has(p));
                 // V3: Index code embeddings in GNN
-                if (this.config.enableGNN && this.gnnIndex && request.paths.length > 0) {
-                    await this.indexCodeEmbeddings(request.paths);
+                if (this.config.enableGNN && this.gnnIndex && indexedPaths.length > 0) {
+                    await this.indexCodeEmbeddings(indexedPaths);
                 }
                 this.updateWorkflowProgress(workflowId, 60);
                 // V3: Collect real project metrics using actual tooling (Phase 5)
-                if (this.config.enableMetricCollector && this.metricCollector && request.paths.length > 0) {
+                if (this.config.enableMetricCollector && this.metricCollector && indexedPaths.length > 0) {
                     // Determine project root from the caller's target (or the indexed paths)
-                    const projectPath = this.getProjectRootFromPaths(request.paths, request.target);
+                    const projectPath = this.getProjectRootFromPaths(indexedPaths, request.target);
                     if (projectPath) {
                         await this.collectProjectMetrics(projectPath);
                     }
@@ -311,14 +337,14 @@ export class CodeIntelligenceCoordinator extends BaseDomainCoordinator {
                 }
                 this.updateWorkflowProgress(workflowId, 70);
                 // Index content for semantic search
-                if (request.paths.length > 0) {
-                    await this.indexForSemanticSearch(request.paths);
+                if (indexedPaths.length > 0) {
+                    await this.indexForSemanticSearch(indexedPaths);
                 }
                 this.updateWorkflowProgress(workflowId, 85);
                 // V3: Rebuild hypergraph from indexed files (keeps hypergraph in sync with KG)
-                if (this.config.enableHypergraph && this.hypergraph && request.paths.length > 0) {
+                if (this.config.enableHypergraph && this.hypergraph && indexedPaths.length > 0) {
                     try {
-                        const codeIndexResult = await this.buildCodeIndexResultFromPaths(request.paths);
+                        const codeIndexResult = await this.buildCodeIndexResultFromPaths(indexedPaths);
                         if (codeIndexResult.files.length > 0) {
                             await this.hypergraph.buildFromIndexResult(codeIndexResult);
                             logger.info(`Hypergraph rebuilt from ${codeIndexResult.files.length} indexed files`);

package/dist/domains/code-intelligence/index-path-guard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * #1096: decide which requested paths code indexing may read.
+ *
+ * Every index entry point (the `index`/`index-code` tasks, `code_index`,
+ * `aqe code index`) ends in KnowledgeGraphService.index, which runs these
+ * checks before reading anything. A path is indexed only when its realpath is
+ * a regular file inside the project root's realpath, so a symlink pointing out
+ * of the project is skipped and reported instead of followed. Callers get the
+ * skipped paths back with a reason; nothing skipped counts as indexed.
+ */
+import { Result } from '../../shared/types';
+import type { SkippedIndexPath } from './interfaces';
+export interface ConfinedIndexPaths {
+    /** Requested paths (as given) that are regular files inside the project root. */
+    accepted: string[];
+    skipped: SkippedIndexPath[];
+}
+/**
+ * Most paths a caller may hand an index request at a boundary (MCP
+ * task_submit / task_orchestrate, `aqe task submit`). Lists the tools discover
+ * themselves (`aqe code index`, init) are not capped here.
+ */
+export declare const MAX_INDEX_PATHS = 10000;
+/**
+ * Validate the shape of a caller-supplied path list at a boundary, so a
+ * non-array value fails with a clear message rather than deep inside indexing.
+ */
+export declare function validateIndexPaths(value: unknown, field?: string, context?: string, maxPaths?: number): Result<string[], Error>;
+/**
+ * Boundary check shared by `task_submit` and `aqe task submit`: an `index` or
+ * `index-code` task must carry a non-empty, well-formed `paths` list. The task
+ * handler indexes exactly those files; it does not expand a directory
+ * `target` (#1134), so a request without `paths` is refused here instead of
+ * failing after it was accepted. Returns undefined when the task is acceptable.
+ */
+export declare function validateIndexTaskPayload(type: string, payload: unknown): Error | undefined;
+/**
+ * Split `paths` into those that may be indexed and those that must be skipped.
+ * Relative paths resolve against `basePath` (default: cwd), as FileReader does.
+ * The rule is the shared payload-path guard (#1126) without a size limit.
+ */
+export declare function confineIndexPaths(paths: readonly string[], projectRoot: string, basePath?: string): Promise<ConfinedIndexPaths>;
+/**
+ * The error an index entry point returns when paths were requested but none
+ * was indexed, so a task fails (and the CLI exits non-zero) instead of
+ * reporting success for work that did not happen.
+ */
+export declare function nothingIndexedError(requested: number, skipped: readonly SkippedIndexPath[], errors?: ReadonlyArray<{
+    file: string;
+    error: string;
+}>): Error;
+//# sourceMappingURL=index-path-guard.d.ts.map

package/dist/domains/code-intelligence/index-path-guard.js

@@ -0,0 +1,95 @@
+/**
+ * #1096: decide which requested paths code indexing may read.
+ *
+ * Every index entry point (the `index`/`index-code` tasks, `code_index`,
+ * `aqe code index`) ends in KnowledgeGraphService.index, which runs these
+ * checks before reading anything. A path is indexed only when its realpath is
+ * a regular file inside the project root's realpath, so a symlink pointing out
+ * of the project is skipped and reported instead of followed. Callers get the
+ * skipped paths back with a reason; nothing skipped counts as indexed.
+ */
+import { ok, err } from '../../shared/types/index.js';
+import { confinePayloadPaths } from '../../shared/io/payload-path-guard.js';
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Most paths a caller may hand an index request at a boundary (MCP
+ * task_submit / task_orchestrate, `aqe task submit`). Lists the tools discover
+ * themselves (`aqe code index`, init) are not capped here.
+ */
+export const MAX_INDEX_PATHS = 10_000;
+/**
+ * Validate the shape of a caller-supplied path list at a boundary, so a
+ * non-array value fails with a clear message rather than deep inside indexing.
+ */
+export function validateIndexPaths(value, field = 'paths', context = 'Invalid index payload', maxPaths = MAX_INDEX_PATHS) {
+    if (!Array.isArray(value)) {
+        return err(new Error(`${context}: '${field}' must be an array of file paths, got ${describe(value)}`));
+    }
+    if (value.length > maxPaths) {
+        return err(new Error(`${context}: '${field}' has ${value.length} entries; at most ${maxPaths} paths are accepted per request - index a directory target or split the list`));
+    }
+    for (let i = 0; i < value.length; i++) {
+        const entry = value[i];
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            return err(new Error(`${context}: '${field}[${i}]' must be a non-empty string, got ${describe(entry)}`));
+        }
+        if (entry.includes('\0')) {
+            return err(new Error(`${context}: '${field}[${i}]' contains a null byte`));
+        }
+    }
+    return ok(value);
+}
+/**
+ * Boundary check shared by `task_submit` and `aqe task submit`: an `index` or
+ * `index-code` task must carry a non-empty, well-formed `paths` list. The task
+ * handler indexes exactly those files; it does not expand a directory
+ * `target` (#1134), so a request without `paths` is refused here instead of
+ * failing after it was accepted. Returns undefined when the task is acceptable.
+ */
+export function validateIndexTaskPayload(type, payload) {
+    if (type !== 'index' && type !== 'index-code')
+        return undefined;
+    if (payload === null || typeof payload !== 'object' || !Object.hasOwn(payload, 'paths')) {
+        return new Error(`Invalid index payload: '${type}' needs 'paths', the list of files to index. ` +
+            "It does not expand a directory 'target'; use code_index (or `aqe code index`) with a target, " +
+            'or list the files in paths.');
+    }
+    const result = validateIndexPaths(payload.paths);
+    if (!result.success)
+        return result.error;
+    if (result.value.length === 0) {
+        return new Error("Invalid index payload: 'paths' is empty; list at least one file to index");
+    }
+    return undefined;
+}
+/**
+ * Split `paths` into those that may be indexed and those that must be skipped.
+ * Relative paths resolve against `basePath` (default: cwd), as FileReader does.
+ * The rule is the shared payload-path guard (#1126) without a size limit.
+ */
+export async function confineIndexPaths(paths, projectRoot, basePath = process.cwd()) {
+    const { accepted, skipped } = await confinePayloadPaths(paths, { projectRoot, basePath });
+    // Without maxBytes the guard never reports 'too-large'.
+    return { accepted, skipped: skipped };
+}
+/**
+ * The error an index entry point returns when paths were requested but none
+ * was indexed, so a task fails (and the CLI exits non-zero) instead of
+ * reporting success for work that did not happen.
+ */
+export function nothingIndexedError(requested, skipped, errors = []) {
+    const details = [
+        ...skipped.map((s) => `${s.path} (${s.reason})`),
+        ...errors.map((e) => `${e.file} (${e.error})`),
+    ];
+    const shown = details.slice(0, 5).join(', ');
+    const more = details.length > 5 ? `, and ${details.length - 5} more` : '';
+    return new Error(`Nothing was indexed: 0 of ${requested} requested path(s) indexed` + (shown ? ` - ${shown}${more}` : ''));
+}
+//# sourceMappingURL=index-path-guard.js.map

package/dist/domains/code-intelligence/interfaces.d.ts

@@ -37,6 +37,18 @@ export interface IndexResult {
      * no dependency extractor, so `deps`/`impact` will show 0 edges for them (#511).
      */
     warnings?: string[];
+    /**
+     * Requested paths that were not indexed, with the reason (#1096): missing,
+     * not a regular file, resolving outside the project root (e.g. through a
+     * symlink), or excluded by the language/test filters. None of them counts
+     * toward `filesIndexed`.
+     */
+    skipped?: SkippedIndexPath[];
+}
+export type IndexSkipReason = 'not-found' | 'not-a-file' | 'outside-project-root' | 'unreadable' | 'excluded-by-language' | 'excluded-test-file';
+export interface SkippedIndexPath {
+    path: string;
+    reason: IndexSkipReason;
 }
 export interface IndexError {
     file: string;

package/dist/domains/code-intelligence/plugin.js

@@ -66,7 +66,7 @@ export class CodeIntelligencePlugin extends BaseDomainPlugin {
     // Task Handlers (Queen-Domain Integration)
     // ============================================================================
     getTaskHandlers() {
-        return new Map([
+        const handlers = new Map([
             ['index', async (payload) => {
                     if (!this.coordinator) {
                         return err(new Error('Coordinator not initialized'));
@@ -127,6 +127,10 @@ export class CodeIntelligencePlugin extends BaseDomainPlugin {
                     });
                 }],
         ]);
+        // `index-code` is the public Queen TaskType inferred by task_orchestrate.
+        // Both names share one execution handler and the same result lifecycle.
+        handlers.set('index-code', handlers.get('index'));
+        return handlers;
     }
     // ============================================================================
     // Lifecycle Methods

package/dist/domains/code-intelligence/services/knowledge-graph.d.ts

@@ -46,6 +46,11 @@ export interface KnowledgeGraphConfig {
      * doesn't trip the FileReader path-traversal guard.
      */
     basePath?: string;
+    /**
+     * #1096: directory that indexing is confined to (by realpath). Defaults to
+     * `basePath` when set, otherwise the detected project root.
+     */
+    projectRoot?: string;
 }
 /**
  * Dependencies for KnowledgeGraphService
@@ -70,6 +75,7 @@ export declare class KnowledgeGraphService implements IKnowledgeGraphService {
     private allEdgesCache?;
     private readonly tsParser;
     private readonly fileReader;
+    private readonly projectRoot;
     private readonly embedder;
     /** ADR-051: Optional LLM router for AI-enhanced extraction */
     private readonly llmRouter?;