@aiwg/cli 2026.9.0 → 2026.9.2

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

@@ -0,0 +1,221 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname, resolve } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { analyzeBackwardCompatibility, loadSchemaCatalog, SchemaResolver, SchemaValidator } from '../../schema/index.js';
+const ACTIONS = ['list', 'show', 'graph', 'policy', 'validate', 'lint', 'check-refs', 'diff', 'compatibility', 'generate', 'verify-projections'];
+function value(args, flag) {
+    const index = args.indexOf(flag);
+    return index < 0 ? undefined : args[index + 1];
+}
+function positional(args) {
+    const flagsWithValues = new Set(['--catalog', '--domain', '--lifecycle', '--format', '--direction', '--schema', '--against']);
+    const result = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (flagsWithValues.has(arg)) {
+            index += 1;
+            continue;
+        }
+        if (!arg.startsWith('-'))
+            result.push(arg);
+    }
+    return result;
+}
+function jsonResult(payload, exitCode = 0) {
+    return { exitCode, rawOutput: true, message: `${JSON.stringify(payload, null, 2)}\n` };
+}
+function digest(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+function readData(path) {
+    const source = readFileSync(path, 'utf8');
+    return ['.yaml', '.yml'].includes(extname(path).toLowerCase()) ? parseYaml(source) : JSON.parse(source);
+}
+function diagnostic(code, message, entry, path) {
+    return { code, severity: 'error', message, ...(entry ? { artifactId: entry.artifact.id } : {}), ...(path ? { path } : {}) };
+}
+function load(ctx) {
+    const catalogPath = value(ctx.args, '--catalog');
+    const result = loadSchemaCatalog({ rootDir: ctx.cwd, ...(catalogPath ? { catalogPath } : {}) });
+    return {
+        ...(result.catalog ? { resolver: new SchemaResolver(result.catalog, { rootDir: ctx.cwd }) } : {}),
+        diagnostics: result.diagnostics,
+    };
+}
+function authorityPath(ctx, entry) {
+    const path = entry.artifact.authority.path;
+    if (!path)
+        throw new Error(`${entry.artifact.id} has no local canonical authority`);
+    return resolve(ctx.cwd, path);
+}
+function schemaRefs(node, refs = []) {
+    if (Array.isArray(node))
+        for (const child of node)
+            schemaRefs(child, refs);
+    else if (typeof node === 'object' && node !== null) {
+        for (const [key, child] of Object.entries(node)) {
+            if (key === '$ref' && typeof child === 'string')
+                refs.push(child);
+            else
+                schemaRefs(child, refs);
+        }
+    }
+    return refs;
+}
+function resolveBaseline(ctx, resolver, query) {
+    const entry = resolver.resolve(query);
+    return readData(entry ? authorityPath(ctx, entry) : resolve(ctx.cwd, query));
+}
+async function execute(ctx) {
+    const [action = 'list', ...terms] = positional(ctx.args);
+    if (!ACTIONS.includes(action))
+        return { exitCode: 1, message: `Unknown schema action '${action}'.` };
+    const loaded = load(ctx);
+    if (!loaded.resolver)
+        return jsonResult({ schema: 'aiwg.schema.diagnostics.v1', valid: false, diagnostics: loaded.diagnostics }, 1);
+    const resolver = loaded.resolver;
+    const query = terms[0];
+    if (action === 'list') {
+        const entries = resolver.list({ domain: value(ctx.args, '--domain'), lifecycle: value(ctx.args, '--lifecycle'), format: value(ctx.args, '--format') });
+        return jsonResult({ schema: 'aiwg.schema.list.v1', entries: entries.map(({ artifact, domain, digest: hash }) => ({ id: artifact.id, logicalName: artifact.logicalName, version: artifact.version, domain, format: artifact.format, lifecycle: artifact.lifecycle, digest: hash })) });
+    }
+    if (action === 'show') {
+        if (!query)
+            return { exitCode: 1, message: 'Usage: aiwg schema show <id|name@version|path>' };
+        const entry = resolver.require(query);
+        return jsonResult({ schema: 'aiwg.schema.show.v1', ...entry });
+    }
+    if (action === 'graph') {
+        const direction = value(ctx.args, '--direction');
+        if (direction && !['dependencies', 'dependents', 'both'].includes(direction))
+            throw new Error(`Invalid graph direction '${direction}'`);
+        return jsonResult({ schema: 'aiwg.schema.graph.v1', ...resolver.graph(query, { direction: direction }) });
+    }
+    if (action === 'policy') {
+        const effective = ctx.args.includes('--effective');
+        if (!effective || !query)
+            return { exitCode: 1, message: 'Usage: aiwg schema policy --effective <id>' };
+        return jsonResult({ schema: 'aiwg.schema.policy.v1', id: resolver.require(query).artifact.id, effective: resolver.policy(query) });
+    }
+    if (action === 'validate') {
+        const schemaQuery = value(ctx.args, '--schema');
+        const instance = schemaQuery ? query : terms[1];
+        const selected = schemaQuery ?? query;
+        if (!selected || !instance)
+            return { exitCode: 1, message: 'Usage: aiwg schema validate --schema <id> <instance>' };
+        const entry = resolver.require(selected);
+        if (entry.artifact.format !== 'json-schema')
+            throw new Error(`Validation currently requires a JSON Schema artifact; got ${entry.artifact.format}`);
+        const data = readData(resolve(ctx.cwd, instance));
+        const result = new SchemaValidator(resolver, { rootDir: ctx.cwd }).validate(entry.artifact.id, data);
+        return jsonResult({ schema: 'aiwg.schema.validation.v1', ...result, instance }, result.valid ? 0 : 1);
+    }
+    if (action === 'lint') {
+        const diagnostics = [...loaded.diagnostics];
+        const entries = resolver.list();
+        for (const entry of entries) {
+            if (entry.artifact.format !== 'json-schema')
+                continue;
+            try {
+                new SchemaValidator(resolver, { rootDir: ctx.cwd }).compile(entry.artifact.id);
+            }
+            catch (error) {
+                diagnostics.push(diagnostic('SCHEMA_COMPILE_FAILED', error instanceof Error ? error.message : String(error), entry, entry.artifact.authority.path));
+            }
+        }
+        const valid = !diagnostics.some(item => item.severity === 'error');
+        return jsonResult({ schema: 'aiwg.schema.diagnostics.v1', valid, diagnostics }, valid ? 0 : 1);
+    }
+    if (action === 'check-refs') {
+        const diagnostics = [];
+        for (const entry of resolver.list()) {
+            for (const dependency of entry.artifact.dependencies ?? [])
+                if (!resolver.resolve(dependency.id) && !dependency.optional)
+                    diagnostics.push(diagnostic('SCHEMA_DEPENDENCY_UNRESOLVED', `Unresolved dependency ${dependency.id}`, entry));
+            if (entry.artifact.format !== 'json-schema' || !entry.artifact.authority.path)
+                continue;
+            for (const ref of schemaRefs(readData(authorityPath(ctx, entry)))) {
+                if (ref.startsWith('#'))
+                    continue;
+                const base = ref.split('#')[0];
+                if (!base)
+                    continue;
+                const local = resolve(dirname(authorityPath(ctx, entry)), base);
+                if (!resolver.resolve(base) && !resolver.resolve(ref) && !existsSync(local))
+                    diagnostics.push(diagnostic('SCHEMA_REFERENCE_UNRESOLVED', `Unresolved $ref ${ref}`, entry, entry.artifact.authority.path));
+            }
+        }
+        return jsonResult({ schema: 'aiwg.schema.references.v1', valid: diagnostics.length === 0, diagnostics }, diagnostics.length ? 1 : 0);
+    }
+    if (action === 'diff' || action === 'compatibility') {
+        const against = value(ctx.args, '--against');
+        if (!query || !against)
+            return { exitCode: 1, message: `Usage: aiwg schema ${action} <id|path> --against <id|path>` };
+        const current = resolveBaseline(ctx, resolver, query);
+        const baseline = resolveBaseline(ctx, resolver, against);
+        const result = analyzeBackwardCompatibility(baseline, current);
+        return jsonResult({ schema: action === 'diff' ? 'aiwg.schema.diff.v1' : 'aiwg.schema.compatibility.v1', current: query, baseline: against, ...result }, result.status === 'breaking' ? 1 : 0);
+    }
+    if (action === 'verify-projections') {
+        const entries = query ? [resolver.require(query)] : resolver.list();
+        const diagnostics = [];
+        for (const entry of entries)
+            for (const projection of entry.artifact.projections ?? []) {
+                const path = resolve(ctx.cwd, projection.path);
+                if (!existsSync(path)) {
+                    diagnostics.push(diagnostic('SCHEMA_PROJECTION_MISSING', `Projection does not exist: ${projection.path}`, entry, projection.path));
+                    continue;
+                }
+                const actual = digest(readFileSync(path));
+                if (projection.digest && projection.digest !== actual)
+                    diagnostics.push(diagnostic('SCHEMA_PROJECTION_DRIFT', `Projection digest does not match: ${projection.path}`, entry, projection.path));
+                if (projection.kind === 'mirror' && readFileSync(path).compare(readFileSync(authorityPath(ctx, entry))) !== 0)
+                    diagnostics.push(diagnostic('SCHEMA_PROJECTION_DRIFT', `Mirror differs from canonical authority: ${projection.path}`, entry, projection.path));
+            }
+        return jsonResult({ schema: 'aiwg.schema.projections.v1', valid: diagnostics.length === 0, diagnostics }, diagnostics.length ? 1 : 0);
+    }
+    const entries = query ? [resolver.require(query)] : resolver.list();
+    const projections = entries.flatMap(entry => (entry.artifact.projections ?? []).map(projection => ({ artifactId: entry.artifact.id, source: entry.artifact.authority.path, ...projection })));
+    if (ctx.args.includes('--write'))
+        for (const item of projections) {
+            if (item.kind !== 'mirror' || !item.source)
+                continue;
+            const target = resolve(ctx.cwd, item.path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, readFileSync(resolve(ctx.cwd, item.source)));
+        }
+    return jsonResult({ schema: 'aiwg.schema.generation-plan.v1', write: ctx.args.includes('--write'), projections });
+}
+export const schemaHandler = {
+    id: 'schema',
+    name: 'Schema Control Plane',
+    description: 'Discover, validate, compare, and verify governed schema artifacts',
+    category: 'utility',
+    aliases: ['schemas'],
+    async help() {
+        return { exitCode: 0, rawOutput: true, message: [
+                'Usage: aiwg schema <action> [options]',
+                '',
+                'Discovery: list, show <id>, graph [id], policy --effective <id>',
+                'Quality: lint, check-refs, validate --schema <id> <instance>',
+                'Evolution: diff <id|path> --against <id|path>, compatibility <id|path> --against <id|path>',
+                'Projections: generate [id] [--write], verify-projections [id]',
+                '',
+                'Common options: --catalog <path>, --domain <id>, --lifecycle <state>, --format <format>',
+                'All command results use stable versioned JSON envelopes.',
+            ].join('\n') };
+    },
+    async execute(ctx) {
+        try {
+            return await execute(ctx);
+        }
+        catch (error) {
+            return jsonResult({ schema: 'aiwg.schema.error.v1', error: error instanceof Error ? error.message : String(error) }, 1);
+        }
+    },
+};
+//# sourceMappingURL=schema.js.map

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

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, realpathSync, statSync, } from 'node:fs';
 import { dirname, isAbsolute, resolve, } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SESSION_PROVIDER_IDS, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, defaultDiscoveryManifestPath, discoverWorkspaceHistories, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, } from '../../sessions/index.js';
+import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, PI_ADAPTER_VERSION, PiSessionAdapter, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SESSION_PROVIDER_IDS, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, defaultDiscoveryManifestPath, discoverWorkspaceHistories, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, } from '../../sessions/index.js';
 const JSON_CONTRACT_VERSION = '1.0.0';
 async function createLineMemoryPromotionDestination(projectRoot, manifestPath) {
     const modulePath = resolve(dirname(manifestPath), 'commands', 'line-memory.mjs');
@@ -622,7 +622,7 @@ async function importSource(ctx, args) {
     if (provider !== 'generic' && provider !== 'claude' && provider !== 'codex'
         && provider !== 'copilot' && provider !== 'cursor' && provider !== 'factory'
         && provider !== 'hermes' && provider !== 'opencode' && provider !== 'openclaw'
-        && provider !== 'openhuman' && provider !== 'warp' && provider !== 'devin-desktop') {
+        && provider !== 'openhuman' && provider !== 'pi' && provider !== 'warp' && provider !== 'devin-desktop') {
         throw new CliError('UNSUPPORTED_OPERATION', `session import is not implemented for ${provider}`, EXIT.unsupported);
     }
     const sourceId = requiredValue(args, '--source-id');
@@ -638,6 +638,7 @@ async function importSource(ctx, args) {
     const isOpenCode = provider === 'opencode';
     const isOpenClaw = provider === 'openclaw';
     const isOpenHuman = provider === 'openhuman';
+    const isPi = provider === 'pi';
     const isWarp = provider === 'warp';
     const isDevinDesktop = provider === 'devin-desktop';
     const adapter = isClaude
@@ -658,11 +659,13 @@ async function importSource(ctx, args) {
                                     ? new OpenClawSessionAdapter()
                                     : isOpenHuman
                                         ? new OpenHumanSessionAdapter()
-                                        : isWarp
-                                            ? new WarpSessionAdapter()
-                                            : isDevinDesktop
-                                                ? new DevinDesktopSessionAdapter()
-                                                : new GenericSessionInterchangeAdapter();
+                                        : isPi
+                                            ? new PiSessionAdapter()
+                                            : isWarp
+                                                ? new WarpSessionAdapter()
+                                                : isDevinDesktop
+                                                    ? new DevinDesktopSessionAdapter()
+                                                    : new GenericSessionInterchangeAdapter();
     const locatorClass = isClaude
         ? (input.endsWith('.hooks.jsonl') ? 'claude-hook-jsonl' : 'claude-transcript-jsonl')
         : isCodex
@@ -681,11 +684,13 @@ async function importSource(ctx, args) {
                                     ? 'openclaw-consistent-snapshot-jsonl'
                                     : isOpenHuman
                                         ? 'openhuman-enriched-jsonl'
-                                        : isWarp
-                                            ? 'warp-markdown-export'
-                                            : isDevinDesktop
-                                                ? 'devin-desktop-cascade-hook-jsonl'
-                                                : 'manual-export';
+                                        : isPi
+                                            ? 'pi-session-v3-jsonl'
+                                            : isWarp
+                                                ? 'warp-markdown-export'
+                                                : isDevinDesktop
+                                                    ? 'devin-desktop-cascade-hook-jsonl'
+                                                    : 'manual-export';
     const selectedSource = {
         provider, locator: input, locatorClass, sourceId,
         authorizedScope: { workspaceId, allowedRoots: [dirname(input)] },
@@ -1007,6 +1012,19 @@ function providerDisposition(provider) {
             },
         };
     }
+    if (provider === 'pi') {
+        return {
+            provider, disposition: 'implemented', operationalState: 'available',
+            supportedOperations: ['discover', 'inspect', 'stream'],
+            acquisitionModes: ['jsonl'], reasonCode: null,
+            remediation: 'Authorize PI_CODING_AGENT_SESSION_DIR, the default Pi sessions root, or an explicit v3 JSONL export.',
+            evidence: {
+                adapterVersion: PI_ADAPTER_VERSION,
+                verifiedAt: '2026-09-04',
+                documentation: 'https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/session-manager.ts',
+            },
+        };
+    }
     if (provider === 'warp') {
         return {
             provider, disposition: 'manual-only', operationalState: 'available',

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

@@ -29,6 +29,9 @@ import { buildWrapperRouteEnvelope } from '../../models/wrapper-route.js';
 import { loadProviderModelCatalog, } from '../../models/provider-policy.js';
 import { CapabilityResolutionError, resolveRoutableCapability, } from '../../artifacts/capability-resolver.js';
 const BASELINE_PROVIDER = 'claude-code';
+function isModelPolicyProvider(provider) {
+    return Object.hasOwn(loadProviderModelCatalog().providers, provider);
+}
 // ── Feature name normalization ────────────────────────────────────────────────
 /**
  * Accept both hyphenated (agent-teams) and underscored (agent_teams) feature
@@ -192,7 +195,7 @@ async function handleSteward(args, ctx) {
     aiwg steward permissions migrate --apply      Back up and atomically normalize config
 
   Providers:
-    claude-code, codex, copilot, cursor, factory, opencode, warp, windsurf, hermes, openclaw
+    claude-code, codex, copilot, cursor, factory, opencode, pi, warp, windsurf, hermes, openclaw
 
   Features:
     cron, agent_teams, tasks, mcp, behaviors, mission_control, daemon
@@ -455,6 +458,13 @@ async function handleSteward(args, ctx) {
                     hint: 'Pass --provider with a supported provider id.',
                     exitCode: EXIT_CODES.USAGE,
                 });
+            if (!isModelPolicyProvider(provider))
+                throw new AiwgError({
+                    code: 'ERR_USAGE_UNSUPPORTED_PROVIDER',
+                    message: `Model wrapper routing is not implemented for provider: ${provider}`,
+                    hint: 'Use `aiwg steward capabilities --provider pi` for current Pi capability routing; model routing is tracked separately.',
+                    exitCode: EXIT_CODES.USAGE,
+                });
             const capabilityType = flagValue('--capability-type');
             const capability = flagValue('--capability');
             const assignment = flagValue('--assignment');

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

@@ -2922,7 +2922,7 @@ export class UseHandler {
             catch {
                 // Profile selection is optional — don't fail deployment
             }
-            if (framework === 'aiwg-utils' && !remainingArgs.includes('--dry-run')) {
+            if (framework === 'aiwg-utils' && provider !== 'pi' && !remainingArgs.includes('--dry-run')) {
                 const wrapperValidation = await validateDeployedModelWrappers({
                     provider: normalizeProviderDefinitionId(provider) ?? provider,
                     target,
@@ -3025,6 +3025,7 @@ export class UseHandler {
             ? withProviderOverride(deployFilteredArgs, provider)
             : deployFilteredArgs;
         const bulkKernelOnly = framework === 'all'
+            && provider !== 'pi'
             && !remainingArgs.includes('--copy-all')
             && !remainingArgs.includes('--copy-standard-skills');
         if (bulkKernelOnly)
@@ -3230,7 +3231,10 @@ export class UseHandler {
         }
         await ensureProviderGeneratedDirsIgnored(target, provider, { dryRun, verbose });
         const paths = getProviderPaths(provider);
-        if (!dryRun && !skipUtils && !bulkKernelOnly) {
+        // Pi model selection/headless routing is delivered by #2151. Until that
+        // adapter exists, do not require model-wrapper artifacts that Pi cannot
+        // load; resource deployment remains independently valid.
+        if (!dryRun && !skipUtils && !bulkKernelOnly && provider !== 'pi') {
             const wrapperValidation = await validateDeployedModelWrappers({
                 provider,
                 target,

package/dist/src/cli/hooks/builtin/activity-log-hook.js

@@ -74,6 +74,12 @@ export const activityLogPostCommandHook = {
         commands: Object.keys(COMMAND_OPERATION_MAP),
     },
     async execute(ctx) {
+        // A dry-run is a strict no-write contract. The command handler may preview
+        // mutations, but the post-command hook must not create activity.log as a
+        // side effect of that preview.
+        if (ctx.args.includes('--dry-run')) {
+            return { action: 'continue' };
+        }
         // Skip on env-var opt-out
         if (isActivityLogSkipped()) {
             return { action: 'continue' };

package/dist/src/cli/router.js

@@ -316,7 +316,7 @@ async function logCommandInvocation(input) {
  * @returns Handler context
  */
 async function buildContext(args, rawArgs, options) {
-    const frameworkRoot = await getFrameworkRoot();
+    const frameworkRoot = await getFrameworkRoot({ createIfMissing: !args.includes('--dry-run') });
     const ctx = {
         args,
         rawArgs,

package/dist/src/cli/scope-resolver.js

@@ -13,6 +13,16 @@ import { homedir } from 'node:os';
 import * as path from 'node:path';
 import { resolveHermesHome, resolveHermesHomePath } from '../providers/hermes-home.js';
 export const hermesHome = resolveHermesHome;
+function piAgentDir() {
+    const configured = process.env.PI_CODING_AGENT_DIR;
+    if (!configured)
+        return path.join(homedir(), '.pi', 'agent');
+    if (configured === '~')
+        return homedir();
+    if (configured.startsWith('~/'))
+        return path.join(homedir(), configured.slice(2));
+    return configured;
+}
 /**
  * User-scope deploy paths per provider per ADR-4 §2. Each path is absolute
  * (rooted in os.homedir()) so the orchestrator's existing path-join logic
@@ -47,6 +57,18 @@ export const USER_SCOPE_PATHS = {
         rules: '',
         behaviors: '',
     },
+    pi: {
+        // Pi's global resource root is configurable. Unlike project deployment,
+        // user-scope resources belong under the effective agent directory. Keep
+        // skills on this single native path instead of also copying them to
+        // ~/.agents/skills, which would create duplicate Pi discovery entries.
+        // PI_CODING_AGENT_DIR is configuration only and is not runtime evidence.
+        agents: '',
+        skills: path.join(piAgentDir(), 'skills'),
+        commands: path.join(piAgentDir(), 'prompts'),
+        rules: '',
+        behaviors: path.join(piAgentDir(), 'extensions'),
+    },
     copilot: {
         // #1160 — Non-applicable for filesystem user-scope discovery.
         //

package/dist/src/dataset/adapter-sdk.d.ts

@@ -0,0 +1,41 @@
+import type { AdapterCheckpoint, AdapterConfigurationResult, AdapterDiagnostic, AdapterDiagnosticCode, AdapterLimits, AdapterManifest, AdapterOperation, AdapterQualificationCell, AdapterQualificationReport, AdapterRequest, AdapterSchemaDeclaration, CredentialLocator, DatasetSourceAdapter } from './adapter-types.js';
+export declare const DEFAULT_ADAPTER_LIMITS: AdapterLimits;
+export declare function sha256Digest(value: string | Uint8Array): {
+    algorithm: 'sha256';
+    value: string;
+};
+export declare function canonicalJson(value: unknown): string;
+export declare function diagnostic(operation: AdapterOperation, code: AdapterDiagnosticCode, message: string, options?: {
+    path?: string;
+    retryable?: boolean;
+    severity?: AdapterDiagnostic['severity'];
+}): AdapterDiagnostic;
+export declare class AdapterFailure extends Error {
+    readonly diagnostic: AdapterDiagnostic;
+    constructor(diagnostic: AdapterDiagnostic);
+}
+export declare function assertActive(signal: AbortSignal | undefined, operation: AdapterOperation): void;
+export declare function effectiveLimits(manifest: AdapterManifest, requested: AdapterLimits): AdapterLimits;
+export declare function isCredentialLocator(value: unknown): value is CredentialLocator;
+export declare function containsRawSecret(value: unknown, key?: string): boolean;
+export declare function redactAdapterValue(value: unknown, key?: string): unknown;
+export declare function schemaDeclaration(id: string, schema: Record<string, unknown>): AdapterSchemaDeclaration;
+export declare function configureObject<T extends Record<string, unknown>>(operation: AdapterOperation, value: unknown, validate: (candidate: Record<string, unknown>) => candidate is T): AdapterConfigurationResult<T>;
+export declare function validateCheckpoint(checkpoint: AdapterCheckpoint | undefined, manifest: AdapterManifest, sourceIdentity: string): AdapterDiagnostic[];
+export declare class AdapterRegistry {
+    #private;
+    private readonly trust;
+    constructor(trust: {
+        allowIds: Set<string>;
+        allowUntrusted?: boolean;
+    });
+    register(adapter: DatasetSourceAdapter): void;
+    require(id: string, version: string): DatasetSourceAdapter;
+}
+export declare function qualifyAdapter(adapter: DatasetSourceAdapter, options: {
+    fixtureRevision: string;
+    qualifiedAt: string;
+    cells: AdapterQualificationCell[];
+}): Promise<AdapterQualificationReport>;
+export declare function request<T extends Record<string, unknown>>(requestId: string, config: T, policy: AdapterRequest<T>['policy'], limits?: Partial<AdapterLimits>): AdapterRequest<T>;
+//# sourceMappingURL=adapter-sdk.d.ts.map

package/dist/src/dataset/adapter-sdk.js

@@ -0,0 +1,147 @@
+import { createHash } from 'node:crypto';
+import { DATASET_ADAPTER_CONTRACT_VERSION } from './adapter-types.js';
+export const DEFAULT_ADAPTER_LIMITS = Object.freeze({
+    maxRecords: 10_000,
+    maxBytes: 16 * 1024 * 1024,
+    maxRecordBytes: 1024 * 1024,
+    timeoutMs: 30_000,
+    maxRedirects: 3,
+    maxDepth: 16,
+});
+export function sha256Digest(value) {
+    return { algorithm: 'sha256', value: createHash('sha256').update(value).digest('hex') };
+}
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(',')}}`;
+}
+export function diagnostic(operation, code, message, options = {}) {
+    return { code, message, operation, retryable: options.retryable ?? false, severity: options.severity ?? 'error', ...(options.path ? { path: options.path } : {}) };
+}
+export class AdapterFailure extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(diagnostic.message);
+        this.diagnostic = diagnostic;
+        this.name = 'AdapterFailure';
+    }
+}
+export function assertActive(signal, operation) {
+    if (signal?.aborted)
+        throw new AdapterFailure(diagnostic(operation, 'ADAPTER_CANCELLED', 'The adapter operation was cancelled.'));
+}
+export function effectiveLimits(manifest, requested) {
+    const positive = (value, ceiling) => Math.max(1, Math.min(Number.isFinite(value) ? Math.trunc(value) : 1, ceiling));
+    return {
+        maxRecords: positive(requested.maxRecords, manifest.limits.maxRecords),
+        maxBytes: positive(requested.maxBytes, manifest.limits.maxBytes),
+        maxRecordBytes: positive(requested.maxRecordBytes, manifest.limits.maxRecordBytes),
+        timeoutMs: positive(requested.timeoutMs, manifest.limits.timeoutMs),
+        maxRedirects: Math.max(0, Math.min(Math.trunc(requested.maxRedirects), manifest.limits.maxRedirects)),
+        maxDepth: positive(requested.maxDepth, manifest.limits.maxDepth),
+    };
+}
+export function isCredentialLocator(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return ['opaque', 'environment', 'keychain', 'vault'].includes(String(candidate.kind))
+        && typeof candidate.locator === 'string' && candidate.locator.length > 0 && candidate.locator.length <= 512;
+}
+const SECRET_KEY = /(?:secret|password|passwd|token|api[-_]?key|credential)/iu;
+export function containsRawSecret(value, key = '') {
+    if (SECRET_KEY.test(key))
+        return !isCredentialLocator(value);
+    if (Array.isArray(value))
+        return value.some(item => containsRawSecret(item));
+    if (value && typeof value === 'object')
+        return Object.entries(value).some(([childKey, child]) => containsRawSecret(child, childKey));
+    return false;
+}
+export function redactAdapterValue(value, key = '') {
+    if (SECRET_KEY.test(key))
+        return '[credential-locator-redacted]';
+    if (Array.isArray(value))
+        return value.map(item => redactAdapterValue(item));
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [childKey, redactAdapterValue(child, childKey)]));
+    return value;
+}
+export function schemaDeclaration(id, schema) {
+    const version = '1.0.0';
+    return { id, version, digest: sha256Digest(canonicalJson(schema)), dialect: 'https://json-schema.org/draft/2020-12/schema', schema };
+}
+export function configureObject(operation, value, validate) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || containsRawSecret(value)) {
+        return { ok: false, diagnostics: [diagnostic(operation, containsRawSecret(value) ? 'ADAPTER_SECRET_REJECTED' : 'ADAPTER_INVALID_CONFIGURATION', containsRawSecret(value) ? 'Secret-like fields must contain an opaque credential locator, never credential material.' : 'Configuration must be an object accepted by the adapter schema.')] };
+    }
+    const candidate = structuredClone(value);
+    if (!validate(candidate))
+        return { ok: false, diagnostics: [diagnostic(operation, 'ADAPTER_INVALID_CONFIGURATION', 'Configuration does not satisfy the adapter contract.')] };
+    return { ok: true, config: candidate, configDigest: sha256Digest(canonicalJson(redactAdapterValue(candidate))), diagnostics: [] };
+}
+export function validateCheckpoint(checkpoint, manifest, sourceIdentity) {
+    if (!checkpoint)
+        return [];
+    const valid = checkpoint.contractVersion === DATASET_ADAPTER_CONTRACT_VERSION
+        && checkpoint.kind === 'AdapterCheckpoint'
+        && checkpoint.adapter.id === manifest.id
+        && checkpoint.adapter.version === manifest.version
+        && checkpoint.sourceIdentity === sourceIdentity
+        && /^-?\d+$/u.test(checkpoint.cursor)
+        && checkpoint.schema.id === manifest.schemas.checkpoint.id
+        && checkpoint.schema.version === manifest.schemas.checkpoint.version
+        && checkpoint.schema.digest?.value === manifest.schemas.checkpoint.digest.value;
+    return valid ? [] : [diagnostic('read', 'ADAPTER_CHECKPOINT_INCOMPATIBLE', 'Checkpoint identity, adapter version, or schema binding is incompatible; no records were read.')];
+}
+export class AdapterRegistry {
+    trust;
+    #adapters = new Map();
+    constructor(trust) {
+        this.trust = trust;
+    }
+    register(adapter) {
+        const manifest = adapter.describe();
+        if (!this.trust.allowIds.has(manifest.id))
+            throw new Error(`ADAPTER_NOT_ALLOWLISTED: ${manifest.id}`);
+        if (manifest.trust.state === 'untrusted' && !this.trust.allowUntrusted)
+            throw new Error(`ADAPTER_TRUST_REQUIRED: ${manifest.id}`);
+        if (manifest.permissions.credentials !== 'none' && manifest.permissions.credentials !== 'locator-only')
+            throw new Error(`ADAPTER_PERMISSION_INVALID: ${manifest.id}`);
+        this.#adapters.set(`${manifest.id}@${manifest.version}`, adapter);
+    }
+    require(id, version) {
+        const adapter = this.#adapters.get(`${id}@${version}`);
+        if (!adapter)
+            throw new Error(`ADAPTER_NOT_REGISTERED: ${id}@${version}`);
+        return adapter;
+    }
+}
+export async function qualifyAdapter(adapter, options) {
+    const manifest = adapter.describe();
+    const required = new Set(['configuration-schema', 'preview-purity', 'deterministic-read', 'stable-errors', 'cancellation', 'checkpoints', 'version-upgrade', 'secret-leakage']);
+    const passed = new Set(options.cells.filter(cell => cell.passed).map(cell => cell.name));
+    const qualified = [...required].every(name => passed.has(name));
+    const realSource = options.cells.some(cell => cell.source === 'real-source' && cell.passed);
+    return {
+        contractVersion: DATASET_ADAPTER_CONTRACT_VERSION,
+        kind: 'AdapterQualificationReport',
+        adapter: { id: manifest.id, version: manifest.version, packageDigest: manifest.packageDigest },
+        schemas: {
+            config: binding(manifest.schemas.config), record: binding(manifest.schemas.discoveredRecord), checkpoint: binding(manifest.schemas.checkpoint),
+        },
+        fixtureRevision: options.fixtureRevision,
+        cells: structuredClone(options.cells), qualifiedAt: options.qualifiedAt,
+        qualified, stableEligible: qualified && realSource,
+    };
+}
+function binding(schema) {
+    return { id: schema.id, version: schema.version, digest: schema.digest };
+}
+export function request(requestId, config, policy, limits = {}) {
+    return { contractVersion: DATASET_ADAPTER_CONTRACT_VERSION, requestId, config, policy, limits: { ...DEFAULT_ADAPTER_LIMITS, ...limits } };
+}
+//# sourceMappingURL=adapter-sdk.js.map