gitnexus 1.6.3-rc.30 → 1.6.3-rc.32

package/dist/cli/clean.js

@@ -5,7 +5,7 @@
  * Also unregisters it from the global registry.
  */
 import fs from 'fs/promises';
-import { findRepo, unregisterRepo, listRegisteredRepos } from '../storage/repo-manager.js';
+import { findRepo, unregisterRepo, listRegisteredRepos, assertSafeStoragePath, UnsafeStoragePathError, } from '../storage/repo-manager.js';
 export const cleanCommand = async (options) => {
     // --all flag: clean all indexed repos
     if (options?.all) {
@@ -24,6 +24,24 @@ export const cleanCommand = async (options) => {
         }
         const entries = await listRegisteredRepos();
         for (const entry of entries) {
+            // Safety guard (#1003 review — @magyargergo): same rationale as
+            // remove.ts. `~/.gitnexus/registry.json` is user-writable, so a
+            // corrupted or hand-edited entry could point storagePath at the
+            // repo root, an empty string, or anywhere else — and
+            // fs.rm(recursive: true) on any of those would be catastrophic.
+            // Skip poisoned entries without touching disk, but keep going
+            // through the rest of the registry (preserves the existing
+            // per-repo error-tolerance semantics of `clean --all`).
+            try {
+                assertSafeStoragePath(entry);
+            }
+            catch (err) {
+                if (err instanceof UnsafeStoragePathError) {
+                    console.error(`Refusing to clean ${entry.name}: ${err.message}`);
+                    continue;
+                }
+                throw err;
+            }
             try {
                 await fs.rm(entry.storagePath, { recursive: true, force: true });
                 await unregisterRepo(entry.path);

package/dist/cli/index.js

@@ -59,6 +59,12 @@ program
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
     .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
+program
+    .command('remove <target>')
+    .description('Delete the GitNexus index for a registered repo (by alias, name, or absolute path). ' +
+    'Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .action(createLazyAction(() => import('./remove.js'), 'removeCommand'));
 program
     .command('wiki [path]')
     .description('Generate repository wiki from knowledge graph')

package/dist/cli/remove.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.gitnexus/` index for a registered repo and unregister it
+ * from the global registry (~/.gitnexus/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .gitnexus/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+export declare const removeCommand: (target: string, options?: {
+    force?: boolean;
+}) => Promise<void>;

package/dist/cli/remove.js

@@ -0,0 +1,99 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.gitnexus/` index for a registered repo and unregister it
+ * from the global registry (~/.gitnexus/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .gitnexus/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+import fs from 'fs/promises';
+import { readRegistry, resolveRegistryEntry, assertSafeStoragePath, unregisterRepo, RegistryNotFoundError, RegistryAmbiguousTargetError, UnsafeStoragePathError, } from '../storage/repo-manager.js';
+export const removeCommand = async (target, options) => {
+    // Read the registry snapshot once and pass it to the resolver — this
+    // lets us render the "before" state in the dry-run path without a
+    // second disk read.
+    const entries = await readRegistry();
+    let entry;
+    try {
+        entry = resolveRegistryEntry(entries, target);
+    }
+    catch (err) {
+        if (err instanceof RegistryNotFoundError) {
+            // Idempotent: missing target is a no-op warning, not an error.
+            // The `availableNames` hint comes from the error itself so users
+            // can see what they might have meant.
+            console.warn(`Nothing to remove: ${err.message}`);
+            return;
+        }
+        if (err instanceof RegistryAmbiguousTargetError) {
+            // Duplicate aliases are allowed via --allow-duplicate-name (#829);
+            // refuse to guess which one the user meant — surface the full list
+            // and exit non-zero so scripts don't silently pick the wrong repo.
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Confirmation gate — same shape as `clean`. Default is a dry-run
+    // that describes what would be deleted; `--force` actually deletes.
+    if (!options?.force) {
+        console.log(`This will delete the GitNexus index for: ${entry.name}`);
+        console.log(`   Path:    ${entry.path}`);
+        console.log(`   Storage: ${entry.storagePath}`);
+        console.log('\nRun with --force to confirm deletion.');
+        return;
+    }
+    // Safety guard (#1003 review — @magyargergo): refuse to proceed if
+    // the registry entry's `storagePath` isn't the canonical
+    // `<entry.path>/.gitnexus` subfolder. `~/.gitnexus/registry.json` is
+    // user-writable, so a corrupted or hand-edited entry could point
+    // storagePath at the repo root, an empty string (→ cwd), a parent
+    // dir, or anywhere else; `fs.rm(recursive: true, force: true)` on
+    // any of those would be a runtime disaster. Bail before touching
+    // disk, with an actionable hint for recovering a broken registry.
+    try {
+        assertSafeStoragePath(entry);
+    }
+    catch (err) {
+        if (err instanceof UnsafeStoragePathError) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Deletion order: fs.rm first, then unregister. If fs.rm fails mid-way,
+    // the registry entry stays so the user can retry. If fs.rm succeeds but
+    // unregister throws (e.g. ENOSPC on registry write), the entry becomes
+    // orphaned — `listRegisteredRepos({ validate: true })` prunes those on
+    // next read, so the failure is self-healing.
+    try {
+        await fs.rm(entry.storagePath, { recursive: true, force: true });
+        await unregisterRepo(entry.path);
+        console.log(`Removed: ${entry.name}`);
+        console.log(`   Path:    ${entry.path}`);
+        console.log(`   Storage: ${entry.storagePath}`);
+    }
+    catch (err) {
+        console.error(`Failed to remove ${entry.name}:`, err);
+        process.exit(1);
+    }
+};

package/dist/core/graph/graph.js

@@ -1,28 +1,113 @@
+/** Fresh empty iterator per call — `[].values()` returns a new
+ *  exhausted iterator each invocation, so empty-type lookups don't
+ *  share a single already-exhausted iterator across callers. */
+function emptyRelIter() {
+    return [].values();
+}
 export const createKnowledgeGraph = () => {
     const nodeMap = new Map();
     const relationshipMap = new Map();
+    // Per-type index maintained alongside `relationshipMap`. Bucket
+    // values are `Map<id, Relationship>` so per-type iteration is cheap
+    // and per-edge removal is O(1). See plan
+    // docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 1).
+    const relationshipsByType = new Map();
+    // Reverse-adjacency index: nodeId → Set<relId> of every edge where
+    // this node appears as source OR target. Maintained on writeRel /
+    // deleteRel so `removeNode` can delete a node's edges in
+    // O(edges-touching-node) instead of O(total-edges).
+    const edgeIdsByNode = new Map();
+    // File index: filePath → Set<nodeId>. Maintained on addNode /
+    // removeNode so `removeNodesByFile` reaches its file's nodes
+    // directly instead of scanning the whole node map.
+    const nodeIdsByFile = new Map();
+    // Private helpers that encode the dual-index invariants in one
+    // place. All mutation paths go through these — adding a new
+    // mutation method only needs to call the helper, not remember to
+    // touch every index.
+    const addToBucket = (map, key, value) => {
+        let bucket = map.get(key);
+        if (bucket === undefined) {
+            bucket = new Set();
+            map.set(key, bucket);
+        }
+        bucket.add(value);
+    };
+    const removeFromBucket = (map, key, value) => {
+        const bucket = map.get(key);
+        if (bucket === undefined)
+            return;
+        bucket.delete(value);
+        if (bucket.size === 0)
+            map.delete(key);
+    };
+    const writeRel = (rel) => {
+        relationshipMap.set(rel.id, rel);
+        let typeBucket = relationshipsByType.get(rel.type);
+        if (typeBucket === undefined) {
+            typeBucket = new Map();
+            relationshipsByType.set(rel.type, typeBucket);
+        }
+        typeBucket.set(rel.id, rel);
+        addToBucket(edgeIdsByNode, rel.sourceId, rel.id);
+        // Guard against a self-edge writing the same rel.id into the
+        // same Set twice — Set dedup handles it, but we skip explicitly
+        // for clarity.
+        if (rel.targetId !== rel.sourceId) {
+            addToBucket(edgeIdsByNode, rel.targetId, rel.id);
+        }
+    };
+    const deleteRel = (rel) => {
+        relationshipMap.delete(rel.id);
+        const typeBucket = relationshipsByType.get(rel.type);
+        if (typeBucket !== undefined) {
+            typeBucket.delete(rel.id);
+            if (typeBucket.size === 0)
+                relationshipsByType.delete(rel.type);
+        }
+        removeFromBucket(edgeIdsByNode, rel.sourceId, rel.id);
+        if (rel.targetId !== rel.sourceId) {
+            removeFromBucket(edgeIdsByNode, rel.targetId, rel.id);
+        }
+    };
     const addNode = (node) => {
-        if (!nodeMap.has(node.id)) {
-            nodeMap.set(node.id, node);
+        if (nodeMap.has(node.id))
+            return;
+        nodeMap.set(node.id, node);
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePath.length > 0) {
+            addToBucket(nodeIdsByFile, filePath, node.id);
         }
     };
     const addRelationship = (relationship) => {
-        if (!relationshipMap.has(relationship.id)) {
-            relationshipMap.set(relationship.id, relationship);
-        }
+        if (relationshipMap.has(relationship.id))
+            return;
+        writeRel(relationship);
     };
     /**
-     * Remove a single node and all relationships involving it
+     * Remove a single node and all relationships involving it.
+     * O(edges-touching-node) via the reverse-adjacency index — no full
+     * relationshipMap scan.
      */
     const removeNode = (nodeId) => {
-        if (!nodeMap.has(nodeId))
+        const node = nodeMap.get(nodeId);
+        if (node === undefined)
             return false;
         nodeMap.delete(nodeId);
-        // Remove all relationships involving this node
-        for (const [relId, rel] of relationshipMap) {
-            if (rel.sourceId === nodeId || rel.targetId === nodeId) {
-                relationshipMap.delete(relId);
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePath.length > 0) {
+            removeFromBucket(nodeIdsByFile, filePath, nodeId);
+        }
+        const touchingEdgeIds = edgeIdsByNode.get(nodeId);
+        if (touchingEdgeIds !== undefined) {
+            // Snapshot the ids before iterating — deleteRel mutates the same
+            // Set via removeFromBucket, which would break mid-loop iteration.
+            for (const relId of [...touchingEdgeIds]) {
+                const rel = relationshipMap.get(relId);
+                if (rel !== undefined)
+                    deleteRel(rel);
             }
+            edgeIdsByNode.delete(nodeId);
         }
         return true;
     };
@@ -31,20 +116,26 @@ export const createKnowledgeGraph = () => {
      * Returns true if the relationship existed and was removed, false otherwise.
      */
     const removeRelationship = (relationshipId) => {
-        return relationshipMap.delete(relationshipId);
+        const rel = relationshipMap.get(relationshipId);
+        if (rel === undefined)
+            return false;
+        deleteRel(rel);
+        return true;
     };
     /**
      * Remove all nodes (and their relationships) belonging to a file.
+     * O(file-nodes × avg-edges-per-node) via the file index — no full
+     * node-map scan.
      */
     const removeNodesByFile = (filePath) => {
-        let removed = 0;
-        for (const [nodeId, node] of nodeMap) {
-            if (node.properties?.filePath === filePath) {
-                removeNode(nodeId);
-                removed++;
-            }
-        }
-        return removed;
+        const nodeIds = nodeIdsByFile.get(filePath);
+        if (nodeIds === undefined)
+            return 0;
+        // Snapshot before iterating — removeNode mutates nodeIdsByFile.
+        const snapshot = [...nodeIds];
+        for (const nodeId of snapshot)
+            removeNode(nodeId);
+        return snapshot.length;
     };
     return {
         get nodes() {
@@ -55,6 +146,10 @@ export const createKnowledgeGraph = () => {
         },
         iterNodes: () => nodeMap.values(),
         iterRelationships: () => relationshipMap.values(),
+        iterRelationshipsByType: (type) => {
+            const bucket = relationshipsByType.get(type);
+            return bucket === undefined ? emptyRelIter() : bucket.values();
+        },
         forEachNode(fn) {
             nodeMap.forEach(fn);
         },

package/dist/core/graph/types.d.ts

@@ -6,12 +6,23 @@
  *
  * This file only defines the CLI's KnowledgeGraph with mutation methods.
  */
-import type { GraphNode, GraphRelationship } from '../../_shared/index.js';
+import type { GraphNode, GraphRelationship, RelationshipType } from '../../_shared/index.js';
 export interface KnowledgeGraph {
     nodes: GraphNode[];
     relationships: GraphRelationship[];
     iterNodes: () => IterableIterator<GraphNode>;
     iterRelationships: () => IterableIterator<GraphRelationship>;
+    /**
+     * Iterate ONLY relationships of the given type, backed by a per-type
+     * index maintained in `addRelationship` / `removeRelationship` /
+     * `removeNode` / `removeNodesByFile`. Returns an empty iterator when
+     * the graph contains no relationships of that type.
+     *
+     * Prefer this over `iterRelationships()` + per-edge type filtering
+     * for hot paths (MRO setup, heritage walks). Backwards-compatible:
+     * existing `iterRelationships()` callers keep working.
+     */
+    iterRelationshipsByType: (type: RelationshipType) => IterableIterator<GraphRelationship>;
     forEachNode: (fn: (node: GraphNode) => void) => void;
     forEachRelationship: (fn: (rel: GraphRelationship) => void) => void;
     getNode: (id: string) => GraphNode | undefined;

package/dist/core/group/config-parser.d.ts

@@ -1,3 +1,7 @@
 import type { GroupConfig } from './types.js';
 export declare function parseGroupConfig(yamlContent: string): GroupConfig;
+export declare class GroupNotFoundError extends Error {
+    readonly groupName: string;
+    constructor(groupName: string);
+}
 export declare function loadGroupConfig(groupDir: string): Promise<GroupConfig>;

package/dist/core/group/config-parser.js

@@ -74,10 +74,27 @@ export function parseGroupConfig(yamlContent) {
         matching,
     };
 }
+export class GroupNotFoundError extends Error {
+    groupName;
+    constructor(groupName) {
+        super(`Group "${groupName}" not found`);
+        this.groupName = groupName;
+        this.name = 'GroupNotFoundError';
+    }
+}
 export async function loadGroupConfig(groupDir) {
     const fsp = await import('node:fs/promises');
     const path = await import('node:path');
     const yamlPath = path.join(groupDir, 'group.yaml');
-    const content = await fsp.readFile(yamlPath, 'utf-8');
+    let content;
+    try {
+        content = await fsp.readFile(yamlPath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new GroupNotFoundError(path.basename(groupDir));
+        }
+        throw err;
+    }
     return parseGroupConfig(content);
 }

package/dist/core/group/cross-impact.js

@@ -4,7 +4,7 @@
  */
 import fsp from 'node:fs/promises';
 import path from 'node:path';
-import { loadGroupConfig } from './config-parser.js';
+import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getGroupDir } from './storage.js';
 import { closeBridgeDb, openBridgeDbReadOnly, queryBridge, readBridgeMeta } from './bridge-db.js';
@@ -242,6 +242,8 @@ export async function runGroupImpact(deps, params) {
         config = await loadGroupConfig(groupDir);
     }
     catch (e) {
+        if (e instanceof GroupNotFoundError)
+            return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
         return { error: e instanceof Error ? e.message : String(e) };
     }
     const resolved = await resolveGroupRepo(deps.port, config, repoPath);
@@ -255,13 +257,10 @@ export async function runGroupImpact(deps, params) {
         includeTests,
         minConfidence,
     };
-    // Single shared deadline for Phase 1 (local walk) + Phase 2 (bridge fan-out).
-    // Phase 1 still gets the full budget; Phase 2 only uses whatever wall-clock
-    // time is left, so total work cannot exceed `timeoutMs`.
     const deadline = Date.now() + Math.max(0, timeoutMs);
     const { value: local, timedOut: localTimedOut } = await safeLocalImpact(deps.port, resolved, impactParams, timeoutMs);
     if (localTimedOut) {
-        const base = local;
+        const _base = local;
         return {
             local,
             group: name,
@@ -283,24 +282,13 @@ export async function runGroupImpact(deps, params) {
     }
     const localObj = local;
     if (localObj?.error && typeof localObj.error === 'string') {
-        const empty = {
-            local,
-            group: name,
-            cross: [],
-            outOfScope: [],
-            truncated: false,
-            truncatedRepos: [],
-            summary: {
-                direct: 0,
-                processes_affected: 0,
-                modules_affected: 0,
-                cross_repo_hits: 0,
-            },
-            risk: 'UNKNOWN',
-            timeoutMs,
-            crossDepthWarning,
-        };
-        return empty;
+        // Fail closed: the local-impact phase errored (missing symbol, graph-load
+        // failure, thrown exception wrapped by safeLocalImpact, or port-returned
+        // `{ error }`). Do NOT wrap it into a zero-hit success payload — callers
+        // branch on top-level `error`, and a blast-radius tool reporting "no
+        // impact" on the failure path is a false negative on a safety-critical
+        // signal. Bubble the error so consumers treat it as a failure.
+        return { error: `Local impact failed for ${repoPath}: ${localObj.error}` };
     }
     if (servicePrefix) {
         const tf = localObj?.target?.filePath;
@@ -372,7 +360,6 @@ export async function runGroupImpact(deps, params) {
                 continue;
             }
             if (!repoInSubgroup(n.neighborRepo, subgroup)) {
-                // CrossLink convention: consumer -> provider
                 outOfScope.push({
                     from: direction === 'upstream' ? n.neighborRepo : repoPath,
                     to: direction === 'upstream' ? repoPath : n.neighborRepo,

package/dist/core/group/service.js

@@ -5,7 +5,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { checkStaleness } from '../git-staleness.js';
-import { loadGroupConfig } from './config-parser.js';
+import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
 import { syncGroup } from './sync.js';
@@ -134,7 +134,15 @@ export class GroupService {
             return { groups };
         }
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         return {
             name: config.name,
             description: config.description,
@@ -147,7 +155,15 @@ export class GroupService {
         if (!name)
             return { error: 'name is required' };
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         const result = await syncGroup(config, {
             groupDir,
             exactOnly: Boolean(params.exactOnly),
@@ -222,6 +238,14 @@ export class GroupService {
             config = await loadGroupConfig(groupDir);
         }
         catch (e) {
+            if (e instanceof GroupNotFoundError)
+                return {
+                    group: name,
+                    target: target || uid,
+                    service: servicePrefix,
+                    error: `Group "${name}" not found. Run group_list to see configured groups.`,
+                    results: [],
+                };
             return {
                 group: name,
                 target: target || uid,
@@ -231,9 +255,6 @@ export class GroupService {
             };
         }
         const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
-        // Per-repo work is independent (each repo opens its own DB handle and the
-        // group-level result preserves repo iteration order via the indexed map).
-        // Errors are caught per repo so one slow/failed member does not block the rest.
         const results = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
             try {
                 const repoObj = await this.port.resolveRepo(registryName);
@@ -282,10 +303,16 @@ export class GroupService {
         const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
         const subgroupExact = params.subgroupExact === true;
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
-        // Per-repo query is independent; run them concurrently and isolate
-        // failures so one slow/failed member does not block the rest.
         const perRepo = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
             try {
                 const repoObj = await this.port.resolveRepo(registryName);
@@ -324,7 +351,15 @@ export class GroupService {
         if (!name)
             return { error: 'name is required' };
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         const registry = await readContractRegistry(groupDir);
         const repoStatuses = {};
         for (const [repoPath, registryName] of Object.entries(config.repos)) {

package/dist/core/ingestion/ast-cache.d.ts

@@ -1,5 +1,20 @@
 import Parser from 'tree-sitter';
-export interface ASTCache {
+/**
+ * Minimal structural shape consumers need when reading Trees back
+ * through a phase-dependency boundary. Declared here so phases that
+ * receive ASTCache via `getPhaseOutput<...>` don't hand-roll their
+ * own inline structural types that silently drift when ASTCache's
+ * contract changes.
+ *
+ * Typed as `unknown` at the Tree boundary because consumers on the
+ * other side of the phase-output map don't share tree-sitter's type
+ * graph (e.g. COBOL's standalone processor).
+ */
+export interface ASTCacheReader {
+    get(filePath: string): unknown;
+    clear(): void;
+}
+export interface ASTCache extends ASTCacheReader {
     get: (filePath: string) => Parser.Tree | undefined;
     set: (filePath: string, tree: Parser.Tree) => void;
     clear: () => void;

package/dist/core/ingestion/ast-cache.js

@@ -7,8 +7,20 @@ export const createASTCache = (maxSize = 50) => {
         max: effectiveMax,
         dispose: (tree) => {
             try {
-                // NOTE: web-tree-sitter has tree.delete(); native tree-sitter trees are GC-managed.
-                // Keep this try/catch so we don't crash on either runtime.
+                // NOTE: web-tree-sitter has tree.delete(); native tree-sitter
+                // trees are GC-managed and .delete is absent (no-op here).
+                //
+                // Single-owner invariant (load-bearing under WASM): a given
+                // Parser.Tree reference must live in AT MOST ONE ASTCache
+                // that disposes. The parse-phase chunk-local cache clears
+                // between chunks; the cross-phase `scopeTreeCache` (also an
+                // ASTCache today) holds the same Tree by reference. Under
+                // native tree-sitter this is benign (dispose is a no-op).
+                // If/when GitNexus adopts web-tree-sitter for sequential
+                // parsing, the cross-phase cache must either (a) skip
+                // writing Trees that are already owned by a disposing cache,
+                // or (b) use tree.copy() per entry. Failing to pick one
+                // will hand freed memory to scope-resolution.
                 tree.delete?.();
             }
             catch (e) {