@aiwg/cli 2026.7.25 → 2026.8.1

package/dist/src/sessions/promotion.js

@@ -12,7 +12,7 @@ export class MemoryPromotionGateway {
             throw new SessionContractError('MALFORMED_SOURCE', 'candidate version does not exist');
         }
         const existing = this.store.getPromotionReceipt(input.candidateId, input.version, input.destination.consumer);
-        if (candidate.reviewState !== 'accepted' && !(candidate.reviewState === 'promoted' && existing)) {
+        if (candidate.reviewState !== 'accepted' && candidate.reviewState !== 'promoted') {
             throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'promotion requires an accepted exact candidate version');
         }
         const security = candidateSecurity(candidate);
@@ -165,7 +165,7 @@ export class FilesystemPromotionDispositionCoordinator {
             if (!decision) {
                 throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'every promoted artifact requires an explicit disposition');
             }
-            this.authorizedPath(dependent.destinationRef);
+            this.authorizedDispositionRef(dependent.destinationRef);
             return {
                 dependentId: dependent.dependentId,
                 destinationRef: dependent.destinationRef,
@@ -194,6 +194,12 @@ export class FilesystemPromotionDispositionCoordinator {
         for (const effect of journal.effects) {
             if (effect.outcome !== 'pending')
                 continue;
+            const lineMemory = this.lineMemoryRef(effect.destinationRef);
+            if (lineMemory) {
+                effect.outcome = this.applyLineMemoryDisposition(lineMemory.metadataPath, lineMemory.handle, purge.operationId, effect);
+                this.writeJournal(journalPath, journal);
+                continue;
+            }
             const target = this.authorizedPath(effect.destinationRef);
             const marker = dispositionMarker(purge.operationId, effect);
             if (effect.action === 'delete') {
@@ -252,6 +258,65 @@ export class FilesystemPromotionDispositionCoordinator {
         }
         return target;
     }
+    authorizedDispositionRef(destinationRef) {
+        if (this.lineMemoryRef(destinationRef))
+            return;
+        this.authorizedPath(destinationRef);
+    }
+    lineMemoryRef(destinationRef) {
+        const separator = destinationRef.lastIndexOf('#');
+        if (separator < 1)
+            return null;
+        const metadataRef = destinationRef.slice(0, separator);
+        const handle = destinationRef.slice(separator + 1);
+        if (!/^lm_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(handle)) {
+            return null;
+        }
+        return { metadataPath: this.authorizedPath(metadataRef), handle };
+    }
+    applyLineMemoryDisposition(metadataPath, handle, operationId, effect) {
+        if (!existsSync(metadataPath))
+            return 'already-applied';
+        const metadata = JSON.parse(readFileSync(metadataPath, 'utf8'));
+        if (metadata.schemaVersion !== 'aiwg.line-memory.v1' || !metadata.entries) {
+            throw new SessionContractError('IMPORT_CONFLICT', 'line-memory metadata schema is invalid');
+        }
+        const entry = metadata.entries[handle];
+        if (!entry)
+            return 'already-applied';
+        const priorOperation = entry.disposition?.operationId;
+        if (priorOperation === operationId)
+            return 'already-applied';
+        const memoryRef = metadata.store?.memoryPath ?? '.aiwg/memory/line-memory.txt';
+        const memoryPath = this.authorizedPath(memoryRef);
+        const lines = existsSync(memoryPath)
+            ? readFileSync(memoryPath, 'utf8').split(/\r?\n/).filter(Boolean)
+            : [];
+        const removesActiveFact = ['delete', 'revoke', 'supersede'].includes(effect.action);
+        const nextLines = removesActiveFact
+            ? removeFirstExact(lines, entry.value)
+            : lines;
+        if (effect.action === 'delete')
+            delete metadata.entries[handle];
+        else {
+            entry.status = effect.action === 'revoke' ? 'revoked'
+                : effect.action === 'supersede' ? 'superseded'
+                    : effect.action === 'origin_unavailable' ? 'origin-unavailable'
+                        : 'active';
+            entry.updatedAt = new Date().toISOString();
+            entry.disposition = {
+                operationId,
+                action: effect.action,
+                effect: effect.effect,
+                originAvailable: effect.action !== 'origin_unavailable',
+            };
+        }
+        if (removesActiveFact) {
+            this.atomicWrite(memoryPath, nextLines.length ? `${nextLines.join('\n')}\n` : '');
+        }
+        this.atomicWrite(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
+        return 'applied';
+    }
     journalPath(operationId) {
         return resolve(this.journalRoot, `${operationId.replace(':', '-')}.json`);
     }
@@ -290,6 +355,12 @@ function requireJournalFiles(root) {
         .sort()
         .map((name) => resolve(root, name));
 }
+function removeFirstExact(lines, value) {
+    const index = lines.indexOf(value);
+    return index < 0
+        ? [...lines]
+        : lines.filter((_, candidate) => candidate !== index);
+}
 export function resolveMemoryConsumerManifest(projectRoot, consumer) {
     const safeConsumer = assertConsumerId(consumer);
     const candidates = [

package/dist/src/sessions/repository.js

@@ -2,6 +2,7 @@ import { createRequire } from 'node:module';
 import { CandidateReviewReceiptSchema, DeletionReceiptSchema, IntelligenceCandidateSchema, PromotionDependencyDecisionSchema, PromotionReceiptSchema, SessionContractError, sha256, } from './contracts.js';
 import { coverageFromBatchRun, } from './batch-contracts.js';
 import { redactSessionText, sanitizeNativeExtensions } from './policy.js';
+import { deriveSessionAnalytics, } from './analytics.js';
 const require = createRequire(import.meta.url);
 const POLICY_PROVIDER_MIGRATION = 'policy-provider-identity:v2';
 const EVENT_ORIGIN_INTENT_MIGRATION = 'event-origin-intent:v1';
@@ -103,10 +104,23 @@ export class SessionRepository {
       CREATE TABLE IF NOT EXISTS session_catalog_meta (
         key TEXT PRIMARY KEY, value TEXT NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS session_analytics_facts (
+        fact_id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL,
+        session_id TEXT NOT NULL, event_id TEXT NOT NULL,
+        category TEXT NOT NULL, status TEXT NOT NULL,
+        provider TEXT NOT NULL, tool_name TEXT, occurred_at TEXT,
+        data TEXT NOT NULL,
+        FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE,
+        FOREIGN KEY(event_id) REFERENCES session_events(event_id) ON DELETE CASCADE
+      );
       CREATE INDEX IF NOT EXISTS idx_session_workspace_provider
         ON sessions(workspace_id, source_id, lifecycle);
       CREATE INDEX IF NOT EXISTS idx_event_session_sequence
         ON session_events(session_id, sequence_no);
+      CREATE INDEX IF NOT EXISTS idx_session_analytics_scope
+        ON session_analytics_facts(
+          workspace_id, category, provider, status, occurred_at, fact_id
+        );
       CREATE VIRTUAL TABLE IF NOT EXISTS session_event_fts USING fts5(
         event_id UNINDEXED, searchable_text, tokenize='unicode61'
       );
@@ -139,6 +153,23 @@ export class SessionRepository {
         this.alignSessionFtsRowids();
         this.migrateSessionPolicyAndProviderIdentity();
         this.migrateEventOriginAndIntent();
+        this.alignSessionAnalytics();
+    }
+    alignSessionAnalytics() {
+        const eventCount = Number(this.db.prepare(`SELECT COUNT(*) AS count
+       FROM session_events e
+       JOIN import_runs r ON r.import_run_id=e.import_run_id
+       JOIN sessions s ON s.session_id=e.session_id
+       WHERE r.status='committed' AND s.lifecycle!='tombstoned'`).get()?.count ?? 0);
+        const factSessions = Number(this.db.prepare('SELECT COUNT(DISTINCT session_id) AS count FROM session_analytics_facts').get()?.count ?? 0);
+        const sourceSessions = Number(this.db.prepare(`SELECT COUNT(DISTINCT e.session_id) AS count
+       FROM session_events e
+       JOIN import_runs r ON r.import_run_id=e.import_run_id
+       JOIN sessions s ON s.session_id=e.session_id
+       WHERE r.status='committed' AND s.lifecycle!='tombstoned'`).get()?.count ?? 0);
+        if (eventCount === 0 || factSessions === sourceSessions)
+            return;
+        this.rebuildAnalytics();
     }
     alignSessionFtsRowids() {
         const eventCount = Number(this.db.prepare('SELECT COUNT(*) AS count FROM session_events').get()?.count ?? 0);
@@ -470,6 +501,11 @@ export class SessionRepository {
             }
             const outcome = publish ? 'committed' : 'staged';
             this.db.prepare(`UPDATE import_runs SET status=?, checkpoint=? WHERE import_run_id=?`).run(outcome, JSON.stringify(checkpoint), batch.run.importRunId);
+            if (publish) {
+                for (const session of batch.sessions) {
+                    this.rebuildAnalytics(session.workspaceId, session.sessionId);
+                }
+            }
             const counts = { sessions: sessionsInserted, events: eventsInserted };
             this.db.prepare(`INSERT INTO import_receipts(operation_id, import_run_id, outcome, counts, checkpoint)
          VALUES (?, ?, ?, ?, ?)`).run(batch.run.importRunId, batch.run.importRunId, outcome, JSON.stringify(counts), JSON.stringify(checkpoint));
@@ -525,6 +561,8 @@ export class SessionRepository {
                 this.db.prepare(`UPDATE mutation_audit SET outcome='committed', occurred_at=?, data=?
            WHERE operation_id=?`).run(updated.observedAt, JSON.stringify(updated), operationId);
             }
+            if (result.changes > 0)
+                this.rebuildAnalytics();
             return result.changes;
         });
         return commit();
@@ -561,6 +599,8 @@ export class SessionRepository {
                 this.db.prepare(`UPDATE mutation_audit SET outcome='committed', occurred_at=?, data=?
            WHERE operation_id=?`).run(updated.observedAt, JSON.stringify(updated), operationId);
             }
+            if (result.changes > 0)
+                this.rebuildAnalytics();
             return result.changes;
         });
         return commit();
@@ -876,6 +916,163 @@ export class SessionRepository {
             snapshotRowid,
         };
     }
+    rebuildAnalytics(workspaceId, sessionId) {
+        const where = [
+            `r.status='committed'`,
+            `s.lifecycle!='tombstoned'`,
+        ];
+        const params = [];
+        if (workspaceId) {
+            where.push('s.workspace_id=?');
+            params.push(workspaceId);
+        }
+        if (sessionId) {
+            where.push('s.session_id=?');
+            params.push(sessionId);
+        }
+        const sessions = this.db.prepare(`SELECT s.session_id, s.data
+       FROM sessions s
+       WHERE s.lifecycle!='tombstoned'
+       ${workspaceId ? 'AND s.workspace_id=?' : ''}
+       ${sessionId ? 'AND s.session_id=?' : ''}
+       AND EXISTS (
+         SELECT 1 FROM session_events e
+         JOIN import_runs r ON r.import_run_id=e.import_run_id
+         WHERE e.session_id=s.session_id AND r.status='committed'
+       )
+       ORDER BY s.session_id`).all(...[
+            ...(workspaceId ? [workspaceId] : []),
+            ...(sessionId ? [sessionId] : []),
+        ]);
+        if (!workspaceId && !sessionId) {
+            this.db.exec('DELETE FROM session_analytics_facts');
+        }
+        else if (sessionId) {
+            this.db.prepare('DELETE FROM session_analytics_facts WHERE session_id=?').run(sessionId);
+        }
+        else {
+            this.db.prepare('DELETE FROM session_analytics_facts WHERE workspace_id=?').run(workspaceId);
+        }
+        const eventQuery = this.db.prepare(`SELECT e.data
+       FROM session_events e
+       JOIN import_runs r ON r.import_run_id=e.import_run_id
+       JOIN sessions s ON s.session_id=e.session_id
+       WHERE e.session_id=? AND ${where.join(' AND ')}
+       ORDER BY e.sequence_no, e.event_id`);
+        const insert = this.db.prepare(`INSERT OR REPLACE INTO session_analytics_facts(
+         fact_id, workspace_id, session_id, event_id, category, status,
+         provider, tool_name, occurred_at, data
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        let inserted = 0;
+        for (const row of sessions) {
+            const session = JSON.parse(String(row.data));
+            const events = eventQuery.all(session.sessionId, ...params)
+                .map((eventRow) => JSON.parse(String(eventRow.data)));
+            for (const fact of deriveSessionAnalytics(session, events)) {
+                inserted += insert.run(fact.factId, fact.workspaceId, fact.sessionId, fact.eventId, fact.category, fact.status, fact.provider, fact.toolName, fact.occurredAt, JSON.stringify(fact)).changes;
+            }
+        }
+        return inserted;
+    }
+    listAnalyticsFacts(options) {
+        const where = [
+            'f.workspace_id=?',
+            `s.lifecycle!='tombstoned'`,
+            `r.status='committed'`,
+        ];
+        const params = [options.workspaceId];
+        if (options.categories?.length) {
+            where.push(`f.category IN (${options.categories.map(() => '?').join(', ')})`);
+            params.push(...options.categories);
+        }
+        const scalar = [
+            ['f.provider', options.provider],
+            ['f.session_id', options.sessionId],
+            ['f.tool_name', options.tool],
+            ['f.status', options.status],
+            [`json_extract(f.data, '$.actor')`, options.actor],
+            [`json_extract(f.data, '$.sensitivity')`, options.sensitivity],
+            [`json_extract(f.data, '$.extractionState')`, options.extractionState],
+        ];
+        for (const [column, value] of scalar) {
+            if (value === undefined)
+                continue;
+            where.push(`${column}=?`);
+            params.push(value);
+        }
+        if (options.dateFrom) {
+            where.push('f.occurred_at>=?');
+            params.push(options.dateFrom);
+        }
+        if (options.dateTo) {
+            where.push('f.occurred_at<=?');
+            params.push(options.dateTo);
+        }
+        if (options.tag) {
+            where.push(`EXISTS (
+        SELECT 1 FROM session_tags t
+        WHERE t.session_id=f.session_id AND t.tag=?
+      )`);
+            params.push(options.tag);
+        }
+        const limit = options.limit ?? 500;
+        if (limit < 1 || limit > 5_000) {
+            throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'analytics limit must be between 1 and 5000');
+        }
+        return this.db.prepare(`SELECT f.data
+       FROM session_analytics_facts f
+       JOIN sessions s ON s.session_id=f.session_id
+       JOIN session_events e ON e.event_id=f.event_id
+       JOIN import_runs r ON r.import_run_id=e.import_run_id
+       WHERE ${where.join(' AND ')}
+       ORDER BY
+         CASE WHEN f.occurred_at IS NULL THEN 1 ELSE 0 END,
+         f.occurred_at, f.session_id,
+         json_extract(f.data, '$.sequence'), f.fact_id
+       LIMIT ?`).all(...params, limit)
+            .map((row) => JSON.parse(String(row.data)));
+    }
+    analyticsSummary(options) {
+        const facts = this.listAnalyticsFacts({ ...options, limit: options.limit ?? 5_000 });
+        const byCategory = countBy(facts, (fact) => fact.category);
+        const byStatus = countBy(facts, (fact) => fact.status);
+        const byProvider = countBy(facts, (fact) => fact.provider);
+        const byTool = countBy(facts.filter((fact) => fact.toolName), (fact) => fact.toolName);
+        return {
+            analyticsVersion: '1.0.0',
+            workspaceId: options.workspaceId,
+            totals: {
+                facts: facts.length,
+                sessions: new Set(facts.map((fact) => fact.sessionId)).size,
+                toolCalls: facts.filter((fact) => fact.category === 'tool-call').length,
+                toolFailures: facts.filter((fact) => fact.category === 'tool-result' && fact.status === 'failed').length,
+                escalations: facts.filter((fact) => fact.category === 'escalation').length,
+                hitlDecisions: facts.filter((fact) => fact.category === 'hitl').length,
+                indicators: facts.filter((fact) => fact.category === 'indicator').length,
+                retryGroups: new Set(facts.map((fact) => fact.retryGroupId).filter(Boolean)).size,
+            },
+            byCategory,
+            byStatus,
+            byProvider,
+            byTool,
+        };
+    }
+    getAnalyticsEvidence(id, workspaceId) {
+        const row = this.db.prepare(`SELECT f.data AS fact_data, e.data AS event_data
+       FROM session_analytics_facts f
+       JOIN sessions s ON s.session_id=f.session_id
+       JOIN session_events e ON e.event_id=f.event_id
+       JOIN import_runs r ON r.import_run_id=e.import_run_id
+       WHERE (f.fact_id=? OR f.event_id=?)
+       AND f.workspace_id=? AND s.lifecycle!='tombstoned' AND r.status='committed'
+       ORDER BY f.fact_id LIMIT 1`).get(id, id, workspaceId);
+        return row
+            ? {
+                fact: JSON.parse(String(row.fact_data)),
+                event: JSON.parse(String(row.event_data)),
+            }
+            : { fact: null, event: null };
+    }
     saveCandidates(candidates) {
         const save = this.db.transaction(() => {
             let inserted = 0;
@@ -1022,7 +1219,8 @@ export class SessionRepository {
             if (existing)
                 return { ...existing, duplicate: true };
             const candidate = this.getCandidate(receipt.candidateId, receipt.candidateVersion);
-            if (!candidate || candidate.reviewState !== 'accepted') {
+            if (!candidate
+                || (candidate.reviewState !== 'accepted' && candidate.reviewState !== 'promoted')) {
                 throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'promotion requires an accepted exact candidate version');
             }
             const evidenceIds = [...new Set(candidate.evidence.map((item) => item.eventId))].sort();
@@ -1161,6 +1359,9 @@ export class SessionRepository {
                     counts: { sessions: 1 },
                 });
             }
+            if (changed) {
+                this.db.prepare('DELETE FROM session_analytics_facts WHERE session_id=?').run(sessionId);
+            }
             return changed;
         });
         return tombstone();
@@ -1187,6 +1388,8 @@ export class SessionRepository {
                     counts: { sessions: 1 },
                 });
             }
+            if (changed)
+                this.rebuildAnalytics(workspaceId, sessionId);
             return changed;
         });
         return restore();
@@ -1385,6 +1588,7 @@ export class SessionRepository {
                     dependencyDispositions: validatedDecisions.length,
                 },
             });
+            this.db.prepare('DELETE FROM session_analytics_facts WHERE session_id=?').run(input.preview.sessionId);
             return receipt;
         });
         return apply();
@@ -1400,6 +1604,7 @@ export class SessionRepository {
           SELECT rowid, event_id, json_extract(data, '$.searchableText') FROM session_events
         `);
                 indexed = Number(this.db.prepare('SELECT COUNT(*) AS count FROM session_events').get()?.count ?? 0);
+                this.rebuildAnalytics();
             }
             else {
                 this.db.prepare(`DELETE FROM session_event_fts WHERE rowid IN (
@@ -1412,6 +1617,7 @@ export class SessionRepository {
            FROM session_events e
            JOIN sessions s ON s.session_id=e.session_id
            WHERE s.workspace_id=?`).run(workspaceId).changes;
+                this.rebuildAnalytics(workspaceId);
             }
             this.emitRepositoryMutation({
                 operationId: sha256([
@@ -1506,6 +1712,14 @@ function canonicalDevinLocator(value) {
         ? `devin-desktop-${value.slice('windsurf-'.length)}`
         : value;
 }
+function countBy(items, key) {
+    const counts = {};
+    for (const item of items) {
+        const value = key(item);
+        counts[value] = (counts[value] ?? 0) + 1;
+    }
+    return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
 function encodeMutationCursor(rowid, workspaceId) {
     const unsigned = { rowid, workspaceId };
     return Buffer.from(JSON.stringify({

package/dist/src/update/notifier.mjs

@@ -157,6 +157,16 @@ function readCurrentVersion(packageRoot) {
   }
 }
 
+/**
+ * Return true when a cached check belongs to the package currently handling
+ * the command. A global launcher can dispatch into a newer development
+ * checkout, so cache age alone is not sufficient.
+ */
+export function cacheMatchesPackage(cache, packageRoot) {
+  const currentVersion = readCurrentVersion(packageRoot);
+  return !!(currentVersion && cache?.current === currentVersion);
+}
+
 /**
  * Run the actual update check and write the cache file. Invoked by the
  * spawned background child via `node src/update/notifier.mjs --check`.
@@ -183,7 +193,7 @@ export function scheduleBackgroundCheck(packageRoot) {
   if (isDisabled()) return;
 
   const cache = readCache();
-  if (cache?.lastCheckAt) {
+  if (cacheMatchesPackage(cache, packageRoot) && cache?.lastCheckAt) {
     const age = Date.now() - new Date(cache.lastCheckAt).getTime();
     if (age < CHECK_INTERVAL_MS) return; // recent enough — skip
   }
@@ -213,9 +223,10 @@ export function scheduleBackgroundCheck(packageRoot) {
  * is interactive, print a single-line notice to stderr. Never prompts.
  * Safe to call unconditionally from `bin/aiwg.mjs` — gated by isDisabled().
  */
-export function maybePrintNotice() {
+export function maybePrintNotice(packageRoot) {
   if (isDisabled()) return;
   const cache = readCache();
+  if (!cacheMatchesPackage(cache, packageRoot)) return;
   if (!cache?.hasUpdate || !cache.current || !cache.latest) return;
   // One-line, non-intrusive. Users who want to update run `aiwg update`.
   const msg = `aiwg: update available ${cache.current} → ${cache.latest} (run: aiwg update)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.7.25",
+  "version": "2026.8.1",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -25,12 +25,19 @@
   "files": [
     "LICENSE",
     "bin/",
+    "agentic/code/providers/",
     "dist/src/",
     "!dist/**/*.d.ts",
     "!dist/**/*.map",
     "dist/src/api/index.d.ts",
     "dist/src/resources/index.d.ts",
     "dist/src/resources/web-release.d.ts",
+    "tools/_resolve-impl.mjs",
+    "tools/agents/deploy-agents.mjs",
+    "tools/agents/providers/",
+    "tools/commands/deploy-prompts-codex.mjs",
+    "tools/plugin/package-plugins.mjs",
+    "tools/skills/deploy-skills-codex.mjs",
     "README.md"
   ],
   "repository": {
@@ -56,23 +63,23 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@fortemi/core": "2026.7.14",
-    "@modelcontextprotocol/sdk": "^1.24.0",
+    "@fortemi/core": "2026.7.15",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^4.1.2",
-    "chokidar": "^3.6.0",
+    "chokidar": "^4.0.3",
     "commander": "^12.1.0",
-    "glob": "^13.0.1",
+    "glob": "^13.0.6",
     "graceful-fs": "^4.2.11",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.3.0",
     "listr2": "^8.2.5",
     "ora": "^5.4.1",
     "semver": "^7.8.5",
-    "yaml": "^2.8.1",
+    "yaml": "^2.9.0",
     "zod": "^3.25.0"
   },
   "optionalDependencies": {
-    "@hono/node-server": "^1.19.14",
-    "hono": "^4.12.18",
-    "ws": "^8.20.0"
+    "@hono/node-server": "2.0.11",
+    "hono": "^4.12.31",
+    "ws": "^8.21.1"
   }
 }

package/tools/_resolve-impl.mjs

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function findPackageRoot(callerUrl) {
+  let dir = dirname(fileURLToPath(callerUrl));
+  for (let i = 0; i < 12; i += 1) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (pkg.name === 'aiwg' || pkg.name === '@aiwg/cli') return dir;
+      } catch {
+        // Keep walking.
+      }
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  throw new Error(`Could not locate AIWG package root from ${callerUrl}`);
+}
+
+function candidatesFor(root, relativeFromSrc, base) {
+  const primary = resolve(root, base, relativeFromSrc);
+  const candidates = [primary];
+
+  if (base === 'src' && extname(primary) === '.js') {
+    candidates.push(primary.slice(0, -3) + '.ts');
+  }
+
+  return candidates;
+}
+
+function resolveCandidate(root, relativeFromSrc, base) {
+  for (const candidate of candidatesFor(root, relativeFromSrc, base)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Resolve a module that may live under compiled dist/src/ or source src/.
+ *
+ * Prefers dist/src/ when present. Set AIWG_RESOLVE_IMPL_FROM=dist or src to
+ * force a side during CI/package-layout checks.
+ */
+export function resolveImpl(callerUrl, relativeFromSrc) {
+  const root = findPackageRoot(callerUrl);
+  const forced = process.env.AIWG_RESOLVE_IMPL_FROM;
+
+  const order = forced === 'src'
+    ? ['src']
+    : forced === 'dist'
+      ? ['dist/src']
+      : ['dist/src', 'src'];
+
+  for (const base of order) {
+    const candidate = resolveCandidate(root, relativeFromSrc, base);
+    if (candidate) return candidate;
+  }
+
+  const attempted = order
+    .flatMap((base) => candidatesFor(root, relativeFromSrc, base))
+    .join(', ');
+  throw new Error(`Could not resolve ${relativeFromSrc}; attempted: ${attempted}`);
+}
+
+export async function importImpl(callerUrl, relativeFromSrc) {
+  const modulePath = resolveImpl(callerUrl, relativeFromSrc);
+  return import(pathToFileURL(modulePath).href);
+}