@aiwg/cli 2026.7.20 → 2026.7.23

package/README.md

@@ -10,10 +10,15 @@ AIWG skills and agents use this CLI to perform common operations with
 predictable, structured calls instead of spending context on shell discovery,
 filesystem traversal, command reconstruction, and repeated tool output.
 
-```bash
-npm install --global @aiwg/cli
+New to AIWG? Install the full `aiwg` package and let the agentic installer
+connect the complete system. `@aiwg/cli` is the smaller execution layer for
+agents, CI, and web-backed installations.
 
-aiwg doctor
+```text
+Install or repair AIWG for this project by following
+https://raw.githubusercontent.com/jmagly/aiwg/main/setup.aiwg.yaml
+Explain the plan before changing anything, preserve my existing work, and ask
+me only for choices you cannot safely determine.
 ```
 
 [![npm version](https://img.shields.io/npm/v/%40aiwg%2Fcli/latest?label=%40aiwg%2Fcli&color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/@aiwg/cli)
@@ -209,6 +214,12 @@ execution layer and can obtain resources from the signed web release. Choose
 `aiwg` when local authoring, the full bundled corpus, or completely cold
 offline operation is required.
 
+For a first installation, an uncertain environment, or a machine with an old
+or broken AIWG setup, use the full `aiwg` package and the
+[agentic installer manifest](https://raw.githubusercontent.com/jmagly/aiwg/main/setup.aiwg.yaml).
+The flow detects development checkouts and preserves development mode unless
+the user explicitly approves switching to the published package.
+
 Both CLI packages expose the same `aiwg` executable name. Install one globally
 at a time unless you deliberately manage separate npm prefixes.
 
@@ -247,7 +258,7 @@ rather than merely printed.
 Agents do not need to memorize the remaining command surface. AIWG discovery
 finds the relevant skill, and the skill supplies the right CLI step. Operators
 who need the complete syntax and examples can use the
-[AIWG CLI reference](https://docs.aiwg.io/pages/cli-reference.html).
+[AIWG CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/agents/cli-reference.md).
 
 ## How It Works
 
@@ -438,7 +449,7 @@ This README therefore documents the operating model, package boundary, trust
 model, and troubleshooting path instead of duplicating every command and flag.
 The complete operator reference is maintained at:
 
-**[AIWG CLI Reference — every command and example](https://docs.aiwg.io/pages/cli-reference.html)**
+**[AIWG CLI Reference — every command and example](https://github.com/jmagly/aiwg/blob/main/docs/agents/cli-reference.md)**
 
 Keeping the command catalog in one canonical location prevents package
 documentation from drifting as the runtime grows.
@@ -492,7 +503,7 @@ security guidance.
 Do not routinely call `aiwg help` and place the full output in the model
 context. If a skill exists, use it. If a maintainer or operator needs an
 unfamiliar command, link to the canonical
-[CLI reference](https://docs.aiwg.io/pages/cli-reference.html) or retrieve only
+[CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/agents/cli-reference.md) or retrieve only
 the relevant section.
 
 ## Using AIWG from a Web-Connected Chat
@@ -1020,7 +1031,7 @@ Package invariants include:
 
 ## Documentation
 
-- [Complete AIWG CLI reference](https://docs.aiwg.io/pages/cli-reference.html)
+- [Complete AIWG CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/agents/cli-reference.md)
 - [AIWG documentation](https://docs.aiwg.io/)
 - [AIWG project README](https://github.com/jmagly/aiwg#readme)
 - [Web-backed resources guide](https://github.com/jmagly/aiwg/blob/main/docs/install/web-backed-resources.md)

package/dist/src/api/index.d.ts

@@ -7,4 +7,6 @@
  */
 export { run } from '../cli/router.js';
 export * from '../resources/index.js';
+export * from '../sessions/index.js';
+export * from '../security/threat-assessment-config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/api/index.js

@@ -7,4 +7,6 @@
  */
 export { run } from '../cli/router.js';
 export * from '../resources/index.js';
+export * from '../sessions/index.js';
+export * from '../security/threat-assessment-config.js';
 //# sourceMappingURL=index.js.map

package/dist/src/artifacts/browser-export.js

@@ -508,6 +508,13 @@ function recordForEntry(cwd, entry, graphName, dependencyGraph, privacy, schemaV
                 ...(entry.operationalState
                     ? { operational_state: entry.operationalState }
                     : {}),
+                ...(entry.stateTransfer
+                    ? {
+                        state_transfer: {
+                            deleted_at: entry.stateTransfer.deletedAt,
+                        },
+                    }
+                    : {}),
             }
             : {}),
         updated_at: entry.updated,

package/dist/src/artifacts/citation-parser.js

@@ -8,7 +8,7 @@
  * - **Incoming**: corpus papers that cite this work (column: "REF") → `cited-by` edges
  *
  * Supported node-id forms (#105):
- * - `REF-\d+`                      research-paper IDs (REF-001, REF-029, ...)
+ * - `REF-\d+[a-z]?`                research-paper IDs (REF-001, REF-434a, ...)
  * - `PROF-[POFG]-[a-z0-9-]+`       entity-profile IDs:
  *     - `PROF-P-*` people, `PROF-O-*` orgs, `PROF-F-*` funders, `PROF-G-*` groups
  *
@@ -26,17 +26,43 @@ import { parseFrontmatter } from './index-builder.js';
  * Match a single node identifier (REF-* or PROF-*) anywhere in a string.
  * Used by `extractRefsFromTable` to pull every ID out of a table cell.
  */
-const NODE_ID_PATTERN = /(?:REF-\d+|PROF-[POFG]-[a-z0-9-]+)/g;
+const NODE_ID_PATTERN = /(?:REF-\d+[a-z]?|PROF-[POFG]-[a-z0-9-]+)/g;
 /**
  * Validate that a string is a complete node identifier.
  * Used by `parseCitationSidecar` and `buildRefToPathMap` to gate
  * frontmatter `ref` values.
  */
-const NODE_ID_FULL = /^(?:REF-\d+|PROF-[POFG]-[a-z0-9-]+)$/;
+const NODE_ID_FULL = /^(?:REF-\d+[a-z]?|PROF-[POFG]-[a-z0-9-]+)$/;
+/** Explicit column aliases used by historical citation-sidecar variants. */
+const CITATION_REF_COLUMNS = [
+    'Inducted REF',
+    'REF',
+    'Corpus REF',
+    'In-corpus REF',
+];
+/**
+ * Preserve the corpus snapshot's legacy edge semantics: every node ID on a
+ * pipe-delimited line inside an outgoing/incoming section is a declaration.
+ * Explicit column parsing remains the primary path, while this compatibility
+ * scan covers malformed rows and prose continuations that historical corpus
+ * snapshots already count.
+ */
+function extractSectionNodeIds(section) {
+    const refs = [];
+    for (const line of section.split('\n')) {
+        if (!line.includes('|'))
+            continue;
+        NODE_ID_PATTERN.lastIndex = 0;
+        const matches = line.match(NODE_ID_PATTERN);
+        if (matches)
+            refs.push(...matches);
+    }
+    return [...new Set(refs)];
+}
 /**
  * Test whether a string is a valid sidecar node identifier.
  *
- * Accepts `REF-\d+` and `PROF-[POFG]-[a-z0-9-]+`. Returns false for any
+ * Accepts `REF-\d+[a-z]?` and `PROF-[POFG]-[a-z0-9-]+`. Returns false for any
  * other input (including unrelated `PROF-` prefixed strings that don't
  * match the four-letter type code form).
  */
@@ -54,34 +80,71 @@ export function isNodeId(value) {
  * @returns Array of node identifiers found
  */
 export function extractRefsFromTable(tableText, columnName) {
-    const lines = tableText.split('\n').filter(l => l.trim().startsWith('|'));
-    if (lines.length < 3)
-        return []; // Need header + separator + at least one row
-    // Parse header to find column index
-    const headerCells = lines[0].split('|').map(c => c.trim()).filter(Boolean);
-    const colIndex = headerCells.findIndex(h => h.toLowerCase() === columnName.toLowerCase());
-    if (colIndex === -1)
-        return [];
-    // Skip header (line 0) and separator (line 1), parse data rows
+    const aliases = (Array.isArray(columnName) ? columnName : [columnName])
+        .map(name => name.trim().toLowerCase());
+    const tableBlocks = [];
+    let currentBlock = [];
+    for (const line of tableText.split('\n')) {
+        if (line.trim().startsWith('|')) {
+            currentBlock.push(line);
+        }
+        else if (currentBlock.length > 0) {
+            tableBlocks.push(currentBlock);
+            currentBlock = [];
+        }
+    }
+    if (currentBlock.length > 0)
+        tableBlocks.push(currentBlock);
+    const parseRow = (line) => {
+        let row = line.trim();
+        if (row.startsWith('|'))
+            row = row.slice(1);
+        if (row.endsWith('|'))
+            row = row.slice(0, -1);
+        return row.split('|').map(cell => cell.trim());
+    };
     const refs = [];
-    for (let i = 2; i < lines.length; i++) {
-        const cells = lines[i].split('|').map(c => c.trim()).filter(Boolean);
-        if (colIndex >= cells.length)
+    for (const lines of tableBlocks) {
+        const headerCells = parseRow(lines[0]);
+        const colIndex = headerCells.findIndex(header => {
+            const normalized = header.toLowerCase().replace(/[`*_]/g, '').trim();
+            return aliases.some(alias => normalized === alias ||
+                normalized.startsWith(`${alias} /`) ||
+                normalized.startsWith(`${alias} (`));
+        });
+        if (lines.length < 3 || colIndex === -1) {
+            // Legacy sidecars sometimes have headerless continuation rows or a
+            // generic table whose rows were extended with a final REF cell. The
+            // corpus snapshot has always treated every in-section table REF as an
+            // outgoing/incoming declaration, so retain that compatibility fallback.
+            const dataLines = lines.length >= 3 ? lines.slice(2) : lines;
+            for (const line of dataLines) {
+                NODE_ID_PATTERN.lastIndex = 0;
+                const refMatches = line.match(NODE_ID_PATTERN);
+                if (refMatches)
+                    refs.push(...refMatches);
+            }
             continue;
-        const value = cells[colIndex].trim();
-        // Skip empty, dash, or em-dash values
-        if (!value || value === '—' || value === '-' || value === '–')
-            continue;
-        // Extract node-id pattern(s) (REF-* or PROF-*) from the cell.
-        // Reset the lastIndex defensively — NODE_ID_PATTERN is a module-level
-        // /g RegExp shared across calls.
-        NODE_ID_PATTERN.lastIndex = 0;
-        const refMatches = value.match(NODE_ID_PATTERN);
-        if (refMatches) {
-            refs.push(...refMatches);
+        }
+        // Skip this table's header and separator, preserving all interior cells.
+        for (let i = 2; i < lines.length; i++) {
+            const cells = parseRow(lines[i]);
+            if (colIndex >= cells.length)
+                continue;
+            // Historical rows may expand the named REF cell into an issue/REF pair
+            // or append placeholder cells without extending the header. Scan from
+            // the named column through the remainder of the row; columns before the
+            // alias (title/authors/year) remain excluded.
+            const value = cells.slice(colIndex).join(' | ');
+            if (!value || value === '—' || value === '-' || value === '–')
+                continue;
+            NODE_ID_PATTERN.lastIndex = 0;
+            const refMatches = value.match(NODE_ID_PATTERN);
+            if (refMatches)
+                refs.push(...refMatches);
         }
     }
-    return refs;
+    return [...new Set(refs)];
 }
 /**
  * Parse a citation sidecar markdown file into structured edges.
@@ -102,17 +165,15 @@ export function parseCitationSidecar(content) {
     for (const section of sections) {
         const sectionLower = section.toLowerCase();
         if (sectionLower.startsWith('outgoing')) {
-            // Outgoing table: extract from "Inducted REF" column
-            cites = extractRefsFromTable(section, 'Inducted REF');
+            cites.push(...extractRefsFromTable(section, CITATION_REF_COLUMNS));
+            cites.push(...extractSectionNodeIds(section));
         }
         else if (sectionLower.startsWith('incoming')) {
-            // Incoming table: extract from "REF" column
-            // The incoming section may have subsections (### Corpus Cross-References)
-            // Look for tables anywhere in this section
-            citedBy = extractRefsFromTable(section, 'REF');
+            citedBy.push(...extractRefsFromTable(section, CITATION_REF_COLUMNS));
+            citedBy.push(...extractSectionNodeIds(section));
         }
     }
-    return { ref, cites, citedBy };
+    return { ref, cites: [...new Set(cites)], citedBy: [...new Set(citedBy)] };
 }
 /**
  * Convert a CitationParseResult into TypedEdge arrays for the dependency graph.

package/dist/src/artifacts/index-builder.js

@@ -20,6 +20,7 @@ import { loadManifest, writeManifest, statMatches, makeEntry } from './checksum-
 import { workspaceLinkedFiles } from '../smiths/context-pipeline/workspace-context.js';
 import { normalizeOperationalState } from './operational-state.js';
 import { DEFAULT_PROJECT_AIWG_DIR, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
+import { normalizeStateTransferProjection } from './state-transfer.js';
 function pathContains(parent, child) {
     const relative = path.relative(parent, child);
     return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
@@ -322,10 +323,10 @@ export function parseRunbookDoc(data, body, filePath) {
 /**
  * Extract trigger phrases from a SKILL.md / agent body.
  *
- * Skills declare alternate activation phrases under a `## Triggers`
- * heading; the body typically lists them as bullet points. This
- * function pulls each bullet's leading phrase (the part before any
- * `→` arrow or em-dash explanation), lowercased and trimmed.
+ * Skills declare alternate activation phrases in `triggers`, `aliases`,
+ * `deprecated_names`, or under a `## Triggers` heading. This function pulls
+ * those names plus each bullet's leading phrase (the part before any `→`
+ * arrow or em-dash explanation), lowercased and trimmed.
  *
  * Returns an empty array when no `## Triggers` section is found —
  * non-skill artifacts get `triggers: undefined` after this is wired.
@@ -334,18 +335,20 @@ export function parseRunbookDoc(data, body, filePath) {
  */
 export function extractTriggers(body, frontmatter) {
     const phrases = [];
-    const declaredTriggers = Array.isArray(frontmatter?.triggers)
-        ? frontmatter.triggers
-        : [];
-    for (const trigger of declaredTriggers) {
-        if (typeof trigger !== 'string')
-            continue;
-        const phrase = trigger.trim().toLowerCase();
-        if (phrase.length === 0)
-            continue;
-        if (phrase.length > 200)
-            continue;
-        phrases.push(phrase);
+    for (const field of ['triggers', 'aliases', 'deprecated_names']) {
+        const declaredValues = Array.isArray(frontmatter?.[field])
+            ? frontmatter[field]
+            : [];
+        for (const value of declaredValues) {
+            if (typeof value !== 'string')
+                continue;
+            const phrase = value.trim().toLowerCase();
+            if (phrase.length === 0)
+                continue;
+            if (phrase.length > 200)
+                continue;
+            phrases.push(phrase);
+        }
     }
     // Find a triggers heading (case-insensitive). Accepted variants:
     //   ## Triggers
@@ -882,6 +885,7 @@ export async function buildIndex(cwd, options = {}) {
             // Script entrypoint metadata is meaningful for skills only (#1227).
             const script = type === 'skill' ? extractSkillScript(data) : undefined;
             const operationalState = normalizeOperationalState(data.operational_state);
+            const stateTransfer = normalizeStateTransferProjection(data.state_transfer);
             // Canonical short name (#1233) — used by the scorer to floor exact-name
             // queries to 1.0 so hyphenated kernel-skill names like `aiwg-doctor`
             // remain searchable even when the rendered title strips the hyphen.
@@ -907,6 +911,7 @@ export async function buildIndex(cwd, options = {}) {
                 ...(kernel ? { kernel } : {}),
                 ...(script ? { script } : {}),
                 ...(operationalState ? { operationalState } : {}),
+                ...(stateTransfer ? { stateTransfer } : {}),
             };
         }
         entries[relativePath] = entry;
@@ -957,6 +962,7 @@ export async function buildIndex(cwd, options = {}) {
         }
     }
     // Run citation sidecar edge extraction if configured
+    let citationMetrics = null;
     if (graphConfig?.edgeExtraction?.parser === 'citation-sidecar') {
         // Build REF-XXX → path map from all entries with ref frontmatter
         const entryFrontmatter = new Map();
@@ -971,6 +977,10 @@ export async function buildIndex(cwd, options = {}) {
         const refToPath = buildRefToPathMap(entryFrontmatter);
         // Parse each entry as a citation sidecar and extract edges
         let citationEdgeCount = 0;
+        let outgoingDeclarations = 0;
+        let incomingDeclarations = 0;
+        const canonicalOutgoing = new Set();
+        const declaredIncoming = new Set();
         for (const entryPath of Object.keys(entries)) {
             const fullPath = absoluteEntryPath(cwd, entryPath, graph);
             if (!fs.existsSync(fullPath))
@@ -979,6 +989,14 @@ export async function buildIndex(cwd, options = {}) {
             const result = parseCitationSidecar(content);
             if (!result)
                 continue;
+            outgoingDeclarations += result.cites.length;
+            incomingDeclarations += result.citedBy.length;
+            for (const targetRef of result.cites) {
+                canonicalOutgoing.add(`${result.ref}\0${targetRef}`);
+            }
+            for (const sourceRef of result.citedBy) {
+                declaredIncoming.add(`${sourceRef}\0${result.ref}`);
+            }
             const edges = citationResultToEdges(result, refToPath);
             if (!depGraph[entryPath]) {
                 depGraph[entryPath] = { upstream: [], downstream: [] };
@@ -1004,6 +1022,15 @@ export async function buildIndex(cwd, options = {}) {
                 citationEdgeCount++;
             }
         }
+        citationMetrics = {
+            canonicalEdges: canonicalOutgoing.size,
+            outgoingDeclarations,
+            incomingDeclarations,
+            unmirroredOutgoing: [...canonicalOutgoing]
+                .filter(edge => !declaredIncoming.has(edge)).length,
+            unmirroredIncoming: [...declaredIncoming]
+                .filter(edge => !canonicalOutgoing.has(edge)).length,
+        };
         if (verbose && citationEdgeCount > 0) {
             console.log(`  citation edges: ${citationEdgeCount}`);
         }
@@ -1038,7 +1065,9 @@ export async function buildIndex(cwd, options = {}) {
         manifestStats.pruned = 0;
     writeManifest(indexOutputDir, nextManifest);
     // Write stats
-    const totalEdges = Object.values(depGraph).reduce((sum, node) => sum + node.downstream.length, 0);
+    const downstreamEdges = Object.values(depGraph).reduce((sum, node) => sum + node.downstream.length, 0);
+    const adjacencyEntries = Object.values(depGraph).reduce((sum, node) => sum + node.upstream.length + node.downstream.length, 0);
+    const totalEdges = citationMetrics?.canonicalEdges ?? downstreamEdges;
     const orphaned = Object.entries(depGraph).filter(([, node]) => node.upstream.length === 0 && node.downstream.length === 0).length;
     const mostReferenced = Object.entries(depGraph)
         .map(([p, node]) => ({ path: p, count: node.downstream.length }))
@@ -1064,6 +1093,14 @@ export async function buildIndex(cwd, options = {}) {
         tagDistribution: tagDist,
         graphMetrics: {
             totalEdges,
+            ...(citationMetrics ? {
+                canonicalEdges: citationMetrics.canonicalEdges,
+                outgoingDeclarations: citationMetrics.outgoingDeclarations,
+                incomingDeclarations: citationMetrics.incomingDeclarations,
+                adjacencyEntries,
+                unmirroredOutgoing: citationMetrics.unmirroredOutgoing,
+                unmirroredIncoming: citationMetrics.unmirroredIncoming,
+            } : {}),
             orphanedArtifacts: orphaned,
             mostReferenced,
         },

package/dist/src/artifacts/state-transfer.js

@@ -0,0 +1,27 @@
+export function normalizeStateTransferProjection(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("state_transfer must be an object");
+    }
+    const record = value;
+    const unknown = Object.keys(record).filter((key) => key !== "deleted_at");
+    if (unknown.length > 0) {
+        throw new Error(`state_transfer has unsupported fields: ${unknown.join(", ")}`);
+    }
+    if (!Object.hasOwn(record, "deleted_at")) {
+        throw new Error("state_transfer.deleted_at is required");
+    }
+    const deletedAt = record.deleted_at;
+    if (deletedAt === null)
+        return { deletedAt: null };
+    if (deletedAt instanceof Date && !Number.isNaN(deletedAt.getTime())) {
+        return { deletedAt: deletedAt.toISOString() };
+    }
+    if (typeof deletedAt !== "string"
+        || Number.isNaN(Date.parse(deletedAt))) {
+        throw new Error("state_transfer.deleted_at must be null or an ISO date-time");
+    }
+    return { deletedAt: new Date(deletedAt).toISOString() };
+}
+//# sourceMappingURL=state-transfer.js.map

package/dist/src/artifacts/stats.js

@@ -153,6 +153,14 @@ async function renderStats(cwd, stats, options, graphType) {
     // Dependency graph
     console.log('Dependency Graph:');
     console.log(`  Total edges:        ${stats.graphMetrics.totalEdges}`);
+    if (stats.graphMetrics.canonicalEdges !== undefined) {
+        console.log(`  Canonical edges:    ${stats.graphMetrics.canonicalEdges}`);
+        console.log(`  Outgoing declares:  ${stats.graphMetrics.outgoingDeclarations}`);
+        console.log(`  Incoming declares:  ${stats.graphMetrics.incomingDeclarations}`);
+        console.log(`  Adjacency entries:  ${stats.graphMetrics.adjacencyEntries}`);
+        console.log(`  Unmirrored outgoing:${String(stats.graphMetrics.unmirroredOutgoing).padStart(3)}`);
+        console.log(`  Unmirrored incoming:${String(stats.graphMetrics.unmirroredIncoming).padStart(3)}`);
+    }
     console.log(`  Orphaned artifacts: ${stats.graphMetrics.orphanedArtifacts}`);
     if (stats.graphMetrics.mostReferenced) {
         console.log(`  Most referenced:    ${stats.graphMetrics.mostReferenced.path} (${stats.graphMetrics.mostReferenced.count} dependents)`);

package/dist/src/cli/cli-extension-loader.js

@@ -41,10 +41,83 @@ export async function writeRegistry(cwd, registry) {
  * Called by `aiwg use <addon>` after reading the addon manifest.
  */
 export async function registerCliCommands(cwd, namespace, description, source, subcommands) {
+    if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(namespace)) {
+        throw new Error(`Invalid CLI namespace: ${namespace}`);
+    }
+    if (!source || !path.isAbsolute(source)) {
+        throw new Error('CLI extension source must be an absolute path.');
+    }
+    if (Object.keys(subcommands).length === 0) {
+        throw new Error(`CLI namespace '${namespace}' declares no subcommands.`);
+    }
+    for (const [name, subcommand] of Object.entries(subcommands)) {
+        if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(name)) {
+            throw new Error(`Invalid CLI subcommand: ${namespace} ${name}`);
+        }
+        if (!subcommand
+            || typeof subcommand.file !== 'string'
+            || !/^[a-zA-Z0-9_-]+\.mjs$/.test(subcommand.file)) {
+            throw new Error(`CLI subcommand '${namespace} ${name}' must name a local .mjs file.`);
+        }
+        if (typeof subcommand.description !== 'string' || !subcommand.description.trim()) {
+            throw new Error(`CLI subcommand '${namespace} ${name}' requires a description.`);
+        }
+    }
     const existing = await readRegistry(cwd) ?? {};
     existing[namespace] = { source, description, subcommands };
     await writeRegistry(cwd, existing);
 }
+/**
+ * Read and validate an addon-shaped manifest's expandable CLI declaration.
+ *
+ * `sourceRoot` may be a bundled addon, a project-local addon, or the validated
+ * payload of a project-local plugin wrapper. Module files are constrained to
+ * the declared commands directory; registration never follows `..` paths.
+ */
+export async function loadCliCommandsContribution(sourceRoot) {
+    const manifestPath = path.join(sourceRoot, 'manifest.json');
+    let raw;
+    try {
+        raw = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new Error(`Unable to read CLI extension manifest at ${manifestPath}: ${error.message}`);
+    }
+    const candidate = raw.cli_commands;
+    if (candidate === undefined)
+        return null;
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+        throw new Error(`Invalid cli_commands block in ${manifestPath}`);
+    }
+    const commands = candidate;
+    if (typeof commands.namespace !== 'string'
+        || typeof commands.description !== 'string'
+        || !commands.subcommands
+        || typeof commands.subcommands !== 'object'
+        || Array.isArray(commands.subcommands)) {
+        throw new Error(`Incomplete cli_commands block in ${manifestPath}`);
+    }
+    const entry = commands.entry ?? 'commands/';
+    if (typeof entry !== 'string'
+        || path.isAbsolute(entry)
+        || entry.split(/[\\/]+/).includes('..')) {
+        throw new Error(`Unsafe cli_commands.entry in ${manifestPath}`);
+    }
+    const commandsSource = path.resolve(sourceRoot, entry);
+    const relative = path.relative(path.resolve(sourceRoot), commandsSource);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`cli_commands.entry escapes its addon root in ${manifestPath}`);
+    }
+    const manifest = {
+        namespace: commands.namespace,
+        description: commands.description,
+        entry,
+        subcommands: commands.subcommands,
+    };
+    return { manifest, commandsSource };
+}
 /**
  * Try to execute an addon-contributed CLI command
  *

package/dist/src/cli/handlers/index.js

@@ -44,6 +44,7 @@ import { serveHandler } from './serve.js';
 import { lintHandler } from './lint.js';
 import { feedbackHandler } from './feedback.js';
 import { sessionHandler } from './session.js';
+import { sessionsHandler } from './sessions.js';
 import { sandboxHandler, sandboxHandlers } from './sandbox.js';
 import { diagnoseHandler } from './diagnose.js';
 import { localExecutorHandler, localExecutorServeHandler } from './local-executor.js';
@@ -62,7 +63,7 @@ helpHandler, versionHandler, doctorHandler, updateHandler, refreshHandler, regen
 // Framework management
 useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, issueHandler, issueAuditHandler, runHandler, 
 // Project
-newBundleHandler, quickrefHandler, newProjectHandler, 
+newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
 statusHandler, wizardHandler, migrateWorkspaceHandler, rollbackWorkspaceHandler, 
 // Subcommands
@@ -224,6 +225,7 @@ export const allHandlers = [
     feedbackHandler,
     // Session (#884)
     sessionHandler,
+    sessionsHandler,
     // Repo access policy (#1376)
     ...repoAccessHandlers,
 ];