@aiwg/cli 2026.10.5 → 2026.10.7

package/dist/src/packages/adapters/git.js

@@ -11,11 +11,40 @@
  */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { mkdir, mkdtemp, readFile, rename, rm } from 'fs/promises';
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'fs/promises';
 import { join } from 'path';
-import { homedir } from 'os';
+import { homedir, tmpdir } from 'os';
 import { existsSync } from 'fs';
+import { resolveSensitiveInput } from '../../auth/sensitive-input.js';
+import { helperEnvironment, HELPER_ENV_ALLOWLIST } from '../../process/cli-command.mjs';
 const execFileAsync = promisify(execFile);
+// Deliberately separate from serializable sources, locks and provenance.
+const credentials = new WeakMap();
+function hasTokenSource(input) {
+    return Boolean(input.interactive || input.stdin || input.file !== undefined || input.store !== undefined || input.env !== undefined);
+}
+/** Explicit sources precede the established env/file lookup; no token means SSH. */
+export async function resolvePackageToken(input = {}, envName, paths = []) {
+    if (hasTokenSource(input))
+        return resolveSensitiveInput({ ...input, prefix: 'token' });
+    if (envName && process.env[envName])
+        return resolveSensitiveInput({ prefix: 'token', env: envName });
+    for (const file of paths) {
+        if (existsSync(file))
+            return resolveSensitiveInput({ prefix: 'token', file });
+    }
+    return undefined;
+}
+// GitHub rejects Bearer on git smart HTTP; Basic with x-access-token works on GitHub and Gitea.
+function basicCredential(token) {
+    return Buffer.from(`x-access-token:${token}`).toString('base64');
+}
+function redact(value, token) {
+    if (!token)
+        return value;
+    return [token, encodeURIComponent(token), basicCredential(token)]
+        .reduce((result, secret) => result.split(secret).join('[REDACTED]'), value);
+}
 /**
  * Default cache root
  */
@@ -34,16 +63,24 @@ export function buildCachePath(owner, name, version) {
 /**
  * Run a git command, returning stdout
  */
-async function git(args, cwd) {
-    const env = { ...process.env };
+async function git(args, cwd, authentication) {
+    const env = helperEnvironment(process.env, [...HELPER_ENV_ALLOWLIST, 'SSH_AUTH_SOCK', 'SSH_AGENT_PID',
+        'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_SSH_VARIANT', 'XDG_CONFIG_HOME']);
     // Suppress interactive prompts
     env.GIT_TERMINAL_PROMPT = '0';
-    const { stdout } = await execFileAsync('git', args, {
-        cwd,
-        env,
-        timeout: 120_000,
-    });
-    return stdout.trim();
+    if (authentication) {
+        env.GIT_CONFIG_COUNT = '1';
+        env.GIT_CONFIG_KEY_0 = 'include.path';
+        env.GIT_CONFIG_VALUE_0 = authentication.config;
+    }
+    try {
+        const { stdout } = await execFileAsync('git', args, { cwd, env, timeout: 120_000 });
+        return redact(stdout.trim(), authentication?.token);
+    }
+    catch (error) {
+        // Never rethrow execFile's object: it carries raw stdout/stderr properties.
+        throw new Error(redact(error instanceof Error ? error.message : 'Git command failed.', authentication?.token));
+    }
 }
 /**
  * Detect the manifest type from a cloned package directory
@@ -69,9 +106,9 @@ async function detectManifestType(cachePath) {
 /**
  * Resolve the latest tag from a remote git repo
  */
-async function resolveLatestTag(gitUrl) {
+async function resolveLatestTag(gitUrl, authentication) {
     try {
-        const output = await git(['ls-remote', '--tags', '--sort=-v:refname', gitUrl]);
+        const output = await git(['ls-remote', '--tags', '--sort=-v:refname', gitUrl], undefined, authentication);
         const firstLine = output.split('\n')[0] ?? '';
         const match = firstLine.match(/refs\/tags\/(.+)/);
         if (match && match[1])
@@ -82,14 +119,14 @@ async function resolveLatestTag(gitUrl) {
     }
     return 'latest';
 }
-async function resolveRemoteCommit(gitUrl, requestedRef) {
+async function resolveRemoteCommit(gitUrl, requestedRef, authentication) {
     if (/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(requestedRef))
         return requestedRef;
     const patterns = requestedRef === 'HEAD'
         ? ['HEAD']
         : [`refs/tags/${requestedRef}^{}`, `refs/tags/${requestedRef}`, `refs/heads/${requestedRef}`, requestedRef];
     try {
-        const output = await git(['ls-remote', gitUrl, ...patterns]);
+        const output = await git(['ls-remote', gitUrl, ...patterns], undefined, authentication);
         const rows = output.split('\n').filter(Boolean).map((line) => {
             const [oid = '', ref = ''] = line.split(/\s+/, 2);
             return { oid, ref };
@@ -136,30 +173,69 @@ export class GitAdapter {
             ref.startsWith('ssh://') ||
             ref.startsWith('git+https://'));
     }
-    async resolve(ref) {
+    async resolve(ref, options = {}) {
         if (!ref.rawUrl)
             return null;
-        return {
+        const source = {
             gitUrl: ref.rawUrl,
             ref: ref.version,
             label: ref.rawUrl,
         };
+        const token = await resolvePackageToken(options.tokenInput);
+        return this.withToken(source, token);
+    }
+    withToken(source, token) {
+        if (/^https?:\/\//.test(source.gitUrl)) {
+            const url = new URL(source.gitUrl);
+            if (url.username || url.password)
+                throw new Error('Credentials in Git URLs are refused; use --token-stdin, --token-file, --token-store or --token-env.');
+        }
+        if (token)
+            credentials.set(source, token);
+        return source;
     }
     async fetch(source, options = {}) {
+        this.withToken(source);
+        const token = credentials.get(source) ?? (hasTokenSource(options.tokenInput ?? {})
+            ? await resolvePackageToken(options.tokenInput) : undefined);
+        let privateDir;
+        try {
+            let authentication;
+            if (token) {
+                if (process.platform === 'win32')
+                    throw new Error('Git token authentication requires private temporary-file ACL validation on Windows; use SSH-agent authentication.');
+                const url = new URL(source.gitUrl);
+                if (url.protocol !== 'https:')
+                    throw new Error('Git token authentication requires HTTPS.');
+                privateDir = await mkdtemp(join(tmpdir(), 'aiwg-git-credentials-'));
+                const config = join(privateDir, 'config');
+                // A path-only include survives NODE_DEBUG=child_process safely. The
+                // origin-scoped header is transient and never saved in .git/config.
+                await writeFile(config, `[http ${JSON.stringify(`${url.origin}/`)}]\n\textraHeader = ${JSON.stringify(`Authorization: Basic ${basicCredential(token)}`)}\n`, { mode: 0o600 });
+                authentication = { config, token };
+            }
+            return await this.fetchAuthenticated(source, options, authentication);
+        }
+        finally {
+            if (privateDir)
+                await rm(privateDir, { recursive: true, force: true });
+        }
+    }
+    async fetchAuthenticated(source, options, authentication) {
         // Resolve discovery inputs before any deployment and cache by immutable
         // commit rather than by a movable tag/branch name (#2009).
         let requestedRef = source.ref;
         if (!requestedRef) {
-            const latest = await resolveLatestTag(source.gitUrl);
+            const latest = await resolveLatestTag(source.gitUrl, authentication);
             requestedRef = latest === 'latest' ? 'HEAD' : latest;
             source.ref = requestedRef;
         }
-        const advertisedCommit = await resolveRemoteCommit(source.gitUrl, requestedRef);
+        const advertisedCommit = await resolveRemoteCommit(source.gitUrl, requestedRef, authentication);
         const { owner, name } = urlCacheIdentity(source.gitUrl);
         if (advertisedCommit) {
             const existing = buildCachePath(owner, name, advertisedCommit);
             if (!options.refresh && existsSync(join(existing, '.git'))) {
-                const existingCommit = await git(['rev-parse', 'HEAD^{commit}'], existing);
+                const existingCommit = await git(['rev-parse', 'HEAD^{commit}'], existing, authentication);
                 if (existingCommit !== advertisedCommit)
                     throw new Error(`Immutable package cache mismatch at ${existing}`);
                 return existing;
@@ -169,9 +245,9 @@ export class GitAdapter {
         await mkdir(ownerDir, { recursive: true });
         const stage = await mkdtemp(join(ownerDir, `.${name}.resolve-`));
         try {
-            await git(['clone', '--no-checkout', source.gitUrl, stage]);
-            await git(['checkout', '--detach', requestedRef], stage);
-            const resolvedCommit = await git(['rev-parse', 'HEAD^{commit}'], stage);
+            await git(['clone', '--no-checkout', source.gitUrl, stage], undefined, authentication);
+            await git(['checkout', '--detach', requestedRef], stage, authentication);
+            const resolvedCommit = await git(['rev-parse', 'HEAD^{commit}'], stage, authentication);
             if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(resolvedCommit)) {
                 throw new Error(`Git resolved '${requestedRef}' to invalid commit '${resolvedCommit}'`);
             }
@@ -180,7 +256,7 @@ export class GitAdapter {
             }
             const cachePath = buildCachePath(owner, name, resolvedCommit);
             if (existsSync(join(cachePath, '.git'))) {
-                const cachedCommit = await git(['rev-parse', 'HEAD^{commit}'], cachePath);
+                const cachedCommit = await git(['rev-parse', 'HEAD^{commit}'], cachePath, authentication);
                 if (cachedCommit !== resolvedCommit)
                     throw new Error(`Immutable package cache mismatch at ${cachePath}`);
                 await rm(stage, { recursive: true, force: true });

package/dist/src/packages/adapters/gitea.js

@@ -11,36 +11,17 @@
  *
  * Authentication:
  *   - SSH clone: uses default SSH agent (recommended for teams)
- *   - HTTPS clone: reads token from GITEA_TOKEN env or ~/.config/gitea/token
+ *   - HTTPS clone: resolves explicit sources, otherwise reads token from GITEA_TOKEN env or ~/.config/gitea/token
  *
  * @implements #557
  */
-import { existsSync } from 'fs';
-import { readFile } from 'fs/promises';
 import { join } from 'path';
 import { homedir } from 'os';
-import { GitAdapter } from './git.js';
+import { GitAdapter, resolvePackageToken } from './git.js';
 /**
  * Regex for "owner/name" or "owner/name@version" (no scheme prefix)
  */
 const GITEA_SHORTHAND = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(@[a-zA-Z0-9._/-]+)?$/;
-/**
- * Read Gitea token from standard file path (same as global CLAUDE.md convention)
- */
-async function readGiteaToken() {
-    if (process.env.GITEA_TOKEN)
-        return process.env.GITEA_TOKEN;
-    const tokenPaths = [
-        join(homedir(), '.config', 'gitea', 'token'),
-        join(homedir(), '.aiwg', 'credentials', 'gitea'),
-    ];
-    for (const p of tokenPaths) {
-        if (existsSync(p)) {
-            return (await readFile(p, 'utf-8')).trim();
-        }
-    }
-    return undefined;
-}
 /**
  * Resolve the Gitea host
  */
@@ -66,25 +47,25 @@ export class GiteaAdapter extends GitAdapter {
             return false; // has scheme prefix → not gitea shorthand
         return GITEA_SHORTHAND.test(ref);
     }
-    async resolve(ref) {
+    async resolve(ref, options = {}) {
         if (!ref.owner || !ref.name)
             return null;
         const host = resolveGiteaHost();
-        const token = await readGiteaToken();
+        const token = await resolvePackageToken(options.tokenInput, 'GITEA_TOKEN', [join(homedir(), '.config', 'gitea', 'token'), join(homedir(), '.aiwg', 'credentials', 'gitea')]);
         let gitUrl;
         if (token) {
-            // HTTPS with token
-            gitUrl = `https://${token}@${host}/${ref.owner}/${ref.name}.git`;
+            // HTTPS; credential is held outside the serializable source
+            gitUrl = `https://${host}/${ref.owner}/${ref.name}.git`;
         }
         else {
             // SSH (relies on SSH agent)
             gitUrl = `git@${host}:${ref.owner}/${ref.name}.git`;
         }
-        return {
+        return this.withToken({
             gitUrl,
             ref: ref.version,
             label: `${host}/${ref.owner}/${ref.name}${ref.version ? `@${ref.version}` : ''}`,
-        };
+        }, token);
     }
     async fetch(source, options = {}) {
         return super.fetch(source, options);

package/dist/src/packages/adapters/github.js

@@ -5,32 +5,14 @@
  *
  * Authentication:
  *   - SSH clone: uses default SSH agent
- *   - HTTPS clone: reads token from GITHUB_TOKEN env or ~/.aiwg/credentials/github
+ *   - HTTPS clone: resolves explicit sources, otherwise reads token from GITHUB_TOKEN env or ~/.aiwg/credentials/github
  *
  * @implements #557
  */
-import { existsSync } from 'fs';
-import { readFile } from 'fs/promises';
 import { join } from 'path';
 import { homedir } from 'os';
-import { GitAdapter } from './git.js';
+import { GitAdapter, resolvePackageToken } from './git.js';
 const GITHUB_HOST = 'github.com';
-/**
- * Read GitHub token from standard locations
- */
-async function readGitHubToken() {
-    if (process.env.GITHUB_TOKEN)
-        return process.env.GITHUB_TOKEN;
-    const tokenPaths = [
-        join(homedir(), '.aiwg', 'credentials', 'github'),
-    ];
-    for (const p of tokenPaths) {
-        if (existsSync(p)) {
-            return (await readFile(p, 'utf-8')).trim();
-        }
-    }
-    return undefined;
-}
 /**
  * GitHubAdapter
  *
@@ -45,22 +27,22 @@ export class GitHubAdapter extends GitAdapter {
     canResolve(ref) {
         return ref.startsWith('github:');
     }
-    async resolve(ref) {
+    async resolve(ref, options = {}) {
         if (!ref.owner || !ref.name)
             return null;
-        const token = await readGitHubToken();
+        const token = await resolvePackageToken(options.tokenInput, 'GITHUB_TOKEN', [join(homedir(), '.aiwg', 'credentials', 'github')]);
         let gitUrl;
         if (token) {
-            gitUrl = `https://${token}@${GITHUB_HOST}/${ref.owner}/${ref.name}.git`;
+            gitUrl = `https://${GITHUB_HOST}/${ref.owner}/${ref.name}.git`;
         }
         else {
             gitUrl = `git@${GITHUB_HOST}:${ref.owner}/${ref.name}.git`;
         }
-        return {
+        return this.withToken({
             gitUrl,
             ref: ref.version,
             label: `github.com/${ref.owner}/${ref.name}${ref.version ? `@${ref.version}` : ''}`,
-        };
+        }, token);
     }
     async fetch(source, options = {}) {
         return super.fetch(source, options);

package/dist/src/packages/registry.js

@@ -99,11 +99,11 @@ export function parseRef(raw) {
 /**
  * Resolve a ref to a PackageSource using the appropriate adapter
  */
-export async function resolveRef(ref) {
+export async function resolveRef(ref, options = {}) {
     for (const adapter of ALL_ADAPTERS) {
         if (!adapter.canResolve(ref.raw))
             continue;
-        const source = await adapter.resolve(ref);
+        const source = await adapter.resolve(ref, options);
         if (source)
             return { source, adapter };
     }
@@ -171,7 +171,7 @@ export async function readPackageNamespace(cachePath, registryKey) {
  */
 export async function installPackage(rawRef, options = {}) {
     const ref = parseRef(rawRef);
-    const resolved = await resolveRef(ref);
+    const resolved = await resolveRef(ref, options);
     if (!resolved) {
         throw new Error(`Cannot resolve package reference: '${rawRef}'\n` +
             `Supported formats:\n` +
@@ -185,7 +185,7 @@ export async function installPackage(rawRef, options = {}) {
     const { source, adapter } = resolved;
     if (options.ref)
         source.ref = options.ref;
-    const cachePath = await adapter.fetch(source, { refresh: options.refresh });
+    const cachePath = await adapter.fetch(source, { refresh: options.refresh, tokenInput: options.tokenInput });
     const discovered = await discoverInstallablePackage(cachePath, options.packageSelector);
     const standardEnvelopePaths = [
         join(cachePath, '.aiwg', 'marketplace', 'envelope.json'),

package/dist/src/plugin/metadata-validator.js

@@ -177,7 +177,7 @@ export class MetadataValidator {
             result.manifest = manifest;
         }
         else {
-            for (const issue of skillResult.errors.errors) {
+            for (const issue of skillResult.errors.issues) {
                 result.errors.push({
                     path: filename,
                     field: issue.path.join('.'),

package/dist/src/process/cli-command.d.mts

@@ -14,3 +14,8 @@ export function cliCommand(
   pathExt?: string,
   cwd?: string,
 ): [string, string[]];
+
+export const HELPER_ENV_ALLOWLIST: readonly string[];
+export const DESKTOP_HELPER_ENV_ALLOWLIST: readonly string[];
+export const DEPLOYMENT_HELPER_ENV_ALLOWLIST: readonly string[];
+export function helperEnvironment(source?: NodeJS.ProcessEnv, names?: readonly string[]): Record<string, string>;

package/dist/src/process/cli-command.mjs

@@ -1,6 +1,48 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
+// Like worker dispatch, helper processes receive only explicitly named state.
+// Keep provider credentials, NODE_OPTIONS and unrelated shell variables out of
+// process launch diagnostics as well as the child's own environment.
+export const HELPER_ENV_ALLOWLIST = Object.freeze([
+  'PATH', 'PATHEXT', 'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'COMSPEC',
+  'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH',
+  'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM',
+  // Platform and network plumbing a child may need to reach anything at all
+  // (corporate proxies and CA bundles, Windows per-user data, git global config).
+  'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy',
+  'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
+  'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_NOSYSTEM',
+]);
+
+export const DESKTOP_HELPER_ENV_ALLOWLIST = Object.freeze([
+  'DISPLAY', 'WAYLAND_DISPLAY', 'XAUTHORITY', 'XDG_RUNTIME_DIR',
+  'DBUS_SESSION_BUS_ADDRESS', 'XDG_CURRENT_DESKTOP',
+]);
+
+// Deployment helpers read project/configuration locations and policy switches;
+// none consumes provider authentication or the caller's complete shell state.
+export const DEPLOYMENT_HELPER_ENV_ALLOWLIST = Object.freeze([
+  ...HELPER_ENV_ALLOWLIST, 'AIWG_ROOT', 'AIWG_HOME', 'AIWG_CONFIG', 'AIWG_PROJECT_DIR',
+  'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'XDG_STATE_HOME', 'LOCALAPPDATA',
+  'AIWG_ARTIFACTS_PATH', 'AIWG_PROJECT_ARTIFACTS_PATH', 'AIWG_PROJECT_AIWG_DIR',
+  'AIWG_PROJECT_MEMORY_HOME', 'AIWG_USER_REGISTRY_PATH', 'AIWG_RULE_BINDING_INDEX_CACHE',
+  'AIWG_DEPLOY_SUBPROCESS', 'AIWG_REPORT_DEPLOY_COLLISIONS', 'CODEX_HOME', 'HERMES_HOME',
+  'OPENCLAW_PROFILE', 'OMP_PROFILE', 'PI_PROFILE', 'PI_CONFIG_DIR', 'PI_CODING_AGENT_DIR',
+  'AIWG_RESOLVE_IMPL_FROM', 'NODE_ENV', 'VITEST', 'NO_UPDATE_NOTIFIER', 'NO_COLOR', 'CI',
+]);
+
+/** Copy only the helper's declared variable names; never merge the parent. */
+export function helperEnvironment(source = process.env, names = HELPER_ENV_ALLOWLIST) {
+  const environment = {};
+  for (const name of names) {
+    const value = source?.[name];
+    if (typeof value === 'string' && !value.includes('\0')) environment[name] = value;
+  }
+  return environment;
+}
+
 // Share PATH/PATHEXT lookup with callers that can launch arbitrary batch files.
 function* executableCandidates(command, searchPath, pathExt, preferNative = false, cwd = process.cwd()) {
   const candidates = path.isAbsolute(command)

package/dist/src/providers/deploy-version.d.mts

@@ -0,0 +1 @@
+export function resolveDeployVersion(root: string, explicitVersion?: string | null, warn?: (message: string) => void): string;

package/dist/src/providers/deploy-version.mjs

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Resolve the selected corpus version before provider inputs are staged. */
+export function resolveDeployVersion(root, explicitVersion, warn = console.warn) {
+  const valid = value => typeof value === 'string' && value.trim() &&
+    !/unknown|\s/i.test(value);
+  if (valid(explicitVersion)) return explicitVersion;
+  if (!explicitVersion) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+      if (valid(pkg.version)) return pkg.version;
+    } catch { /* Report missing, unreadable and invalid versions consistently. */ }
+  }
+  warn(`Unable to resolve AIWG deploy version from ${path.join(root, 'package.json')}; managed markers will use vunknown. Restore the package version or pass --deploy-version to the deployer.`);
+  return 'unknown';
+}

package/dist/src/providers/provider-definitions.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
+import { integer, url } from '../schema/zod-validation.mjs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { isAbsolute, join } from 'path';
 import { resolveHermesHomePath } from './hermes-home.js';
 import { resolveGrokbotSkillsDir } from './grokbot-paths.js';
 import { getProviderCapabilities, } from './capability-matrix.js';
@@ -38,9 +39,9 @@ const ProviderDefinitionSchema = z.object({
     status: z.enum(['stable', 'experimental', 'deprecated']),
     builtIn: z.boolean(),
     upstream: z.object({
-        source: z.string().url(),
+        source: url(),
         version: z.string().min(1),
-        revision: z.string().regex(/^[0-9a-f]{40}$/).refine((value) => value !== '0'.repeat(40), { message: 'upstream.revision must be a real reviewed SHA, not all-zero' }),
+        revision: z.string().regex(/^[0-9a-f]{40}$/).refine((value) => value !== '0'.repeat(40), { error: 'upstream.revision must be a real reviewed SHA, not all-zero' }),
         runtime: z.string().min(1),
         lastVerified: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
     }).optional(),
@@ -67,7 +68,7 @@ const ProviderDefinitionSchema = z.object({
         env: z.array(z.string().min(1)),
         process: z.array(z.string().min(1)),
         capabilityId: z.string().min(1),
-        runtimeEnvPriority: z.number().int().positive().optional(),
+        runtimeEnvPriority: integer().positive().optional(),
     }),
     paths: z.object({
         deployTarget: z.enum(['project', 'home', 'mixed']),
@@ -95,8 +96,8 @@ const ProviderDefinitionSchema = z.object({
         includeSyntax: z.string().nullable(),
         configRegistration: z.object({ file: z.string().min(1), key: z.string().min(1) }).nullable(),
         bootstrapTargets: z.array(z.string().min(1)),
-        maxContextBytes: z.number().int().positive().nullable(),
-        recommendedMaxLines: z.number().int().positive().nullable(),
+        maxContextBytes: integer().positive().nullable(),
+        recommendedMaxLines: integer().positive().nullable(),
         nestedContext: z.boolean(),
         support: z.enum(['supported', 'degraded', 'unsupported']),
         verification: z.object({
@@ -119,8 +120,8 @@ const ProviderDefinitionSchema = z.object({
         pathType: z.enum(['project', 'home-dir']),
         skillsBaseDir: z.string().min(1),
         subdirLayout: z.boolean(),
-        maxNameLength: z.number().int().positive().optional(),
-        maxDescriptionLength: z.number().int().positive().optional(),
+        maxNameLength: integer().positive().optional(),
+        maxDescriptionLength: integer().positive().optional(),
         appendToDescription: z.string().min(1).optional(),
     }),
     adapters: z.object({
@@ -132,8 +133,8 @@ const ProviderDefinitionSchema = z.object({
     }),
     capabilities: z.object({
         matrixRef: z.string().nullable(),
-        nativeFeatures: z.record(z.boolean()),
-        emulation: z.record(z.string().nullable()),
+        nativeFeatures: z.record(z.string(), z.boolean()),
+        emulation: z.record(z.string(), z.string().nullable()),
     }),
 });
 export const PROVIDER_IDS = [
@@ -755,10 +756,11 @@ const BUILT_IN_SEEDS = [
                 agents: null,
                 commands: null,
                 skills: resolveHermesHomePath('skills', '.aiwg'),
-                rules: null,
+                rules: '.hermes/rules',
                 behaviors: null,
             },
             kernelSkills: resolveHermesHomePath('skills'),
+            contextDiscovery: { agents: null, skills: resolveHermesHomePath('skills', '.aiwg'), rules: null, behaviors: null },
             configFile: 'AGENTS.md',
             contextFiles: { aiwgMd: true, agentsMd: true, claudeMdHook: false, hookFile: '.hermes.md', contextFile: 'AGENTS.md' },
         },
@@ -1080,7 +1082,7 @@ const BUILT_IN_SEEDS = [
                 agents: '.agents/skills',
                 commands: '.pi/prompts',
                 skills: '.pi/.aiwg/skills',
-                rules: null,
+                rules: '.pi/rules',
                 behaviors: '.pi/extensions',
             },
             kernelSkills: '.agents/skills',
@@ -1425,13 +1427,14 @@ export function getProviderKernelSkillPath(provider) {
     const definition = getProviderDefinition(provider);
     return expandProviderHomePath(definition?.paths.kernelSkills ?? null);
 }
-export function resolveProviderPathValue(providerPath, projectPath) {
-    const expandedPath = expandProviderHomePath(providerPath);
+export function resolveProviderPathValue(providerPath, projectPath, paths = { join, isAbsolute }, homeDirectory = homedir()) {
+    const expandedPath = !providerPath ? '' : providerPath === '~' ? homeDirectory
+        : providerPath.startsWith('~/') ? paths.join(homeDirectory, providerPath.slice(2)) : providerPath;
     if (!expandedPath)
         return '';
-    if (expandedPath.startsWith('/'))
+    if (paths.isAbsolute(expandedPath))
         return expandedPath;
-    return join(projectPath, expandedPath);
+    return paths.join(projectPath, expandedPath);
 }
 export function normalizeProviderDefinitionId(provider) {
     const normalized = provider?.trim().toLowerCase();

package/dist/src/providers/skill-ownership.d.mts

@@ -2,8 +2,17 @@ export interface SkillReceipt {
   skillSource?: string;
   managed?: Record<string, { hash: string; frameworkSlug?: string; source?: string; version?: string }>;
 }
+export interface SkillRemovalPlanEntry {
+  path: string;
+  action: 'remove' | 'preserve';
+  reason: string;
+}
+export interface SkillRemovalOptions {
+  dryRun?: boolean;
+  plan?: SkillRemovalPlanEntry[];
+}
 export function extractFrameworkSlug(source: string): string | null;
 export function sameSkillOwner(receipt: SkillReceipt | null, skillSource: string, frameworkSlug?: string | null): boolean;
 export function canDeploySkill(receipt: SkillReceipt | null, skillSource: string, opts?: { force?: boolean }): boolean;
-export function pruneRecordedSkillFiles(skillDir: string, managed: SkillReceipt['managed'], desired: Set<string>, opts?: { dryRun?: boolean }): void;
-export function releaseSkillOwnership(skillDir: string, owner: { frameworkSlug?: string; skillSource?: string; sourceRoot?: string }, opts?: { dryRun?: boolean }): boolean | null;
+export function pruneRecordedSkillFiles(skillDir: string, managed: SkillReceipt['managed'], desired: Set<string>, opts?: SkillRemovalOptions): void;
+export function releaseSkillOwnership(skillDir: string, owner: { frameworkSlug?: string; skillSource?: string; sourceRoot?: string }, opts?: SkillRemovalOptions): boolean | null;

package/dist/src/providers/skill-ownership.mjs

@@ -40,28 +40,40 @@ export function canDeploySkill(receipt, skillSource, { force = false } = {}) {
 
 /** Remove unchanged recorded files, allowing symlinks above (but never inside) the skill root. */
 export function pruneRecordedSkillFiles(skillDir, managed, desired, opts = {}) {
-  if (opts.dryRun) return;
+  const root = path.resolve(skillDir);
   for (const [relative, record] of Object.entries(managed || {})) {
-    if (desired.has(relative)) continue;
     const target = path.resolve(skillDir, relative);
-    if (!target.startsWith(`${path.resolve(skillDir)}${path.sep}`)) continue;
+    let action = 'preserve';
+    let reason = 'modified or unverifiable managed file';
+    if (desired.has(relative)) reason = 'retained managed file';
+    else if (!target.startsWith(`${root}${path.sep}`)) reason = 'path outside skill directory';
+    else {
+      try {
+        const expected = path.resolve(fs.realpathSync(skillDir), relative);
+        let current = target;
+        let symlink = false;
+        while (current !== root) {
+          if (fs.lstatSync(current).isSymbolicLink()) { symlink = true; break; }
+          current = path.dirname(current);
+        }
+        if (symlink) reason = 'symlink preserved';
+        else if (fs.realpathSync(target) === expected && fs.lstatSync(target).isFile()
+          && `sha256:${createHash('sha256').update(fs.readFileSync(target)).digest('hex')}` === record?.hash) {
+          action = 'remove';
+          reason = 'unchanged managed file';
+        }
+      } catch { reason = 'missing or unreadable path; cannot verify'; }
+    }
+    opts.plan?.push({ path: target, action, reason });
+    if (opts.dryRun || action !== 'remove') continue;
     try {
-      const expected = path.resolve(fs.realpathSync(skillDir), relative);
-      let current = target;
-      let symlink = false;
-      while (current !== path.resolve(skillDir)) {
-        if (fs.lstatSync(current).isSymbolicLink()) { symlink = true; break; }
-        current = path.dirname(current);
-      }
-      if (symlink || fs.realpathSync(target) !== expected || !fs.lstatSync(target).isFile()) continue;
-      if (`sha256:${createHash('sha256').update(fs.readFileSync(target)).digest('hex')}` !== record.hash) continue;
       fs.unlinkSync(target);
       let parent = path.dirname(target);
-      while (parent !== path.resolve(skillDir)) {
+      while (parent !== root) {
         try { fs.rmdirSync(parent); } catch { break; }
         parent = path.dirname(parent);
       }
-    } catch { /* missing, modified, or unreadable files are left alone */ }
+    } catch { /* Files that cannot be removed are left alone. */ }
   }
 }
 
@@ -80,9 +92,15 @@ export function releaseSkillOwnership(skillDir, owner, opts = {}) {
     && !path.isAbsolute(path.relative(path.resolve(owner.sourceRoot), path.resolve(receipt.skillSource)));
   if (!insideRoot && (slug ? slug !== owner.frameworkSlug
     : !owner.skillSource || !sameSkillOwner(receipt, owner.skillSource, null))) return null;
-  if (opts.dryRun) return false;
   pruneRecordedSkillFiles(skillDir, receipt.managed, new Set(), opts);
-  fs.rmSync(manifestPath, { force: true });
-  fs.rmSync(path.join(skillDir, '.aiwg-managed'), { force: true });
+  for (const target of [manifestPath, path.join(skillDir, '.aiwg-managed')]) {
+    // Metadata is released even when operator files keep the directory alive.
+    try {
+      fs.lstatSync(target);
+      opts.plan?.push({ path: path.resolve(target), action: 'remove', reason: 'ownership metadata released' });
+    } catch { /* Missing metadata has nothing to remove. */ }
+    if (!opts.dryRun) fs.rmSync(target, { force: true });
+  }
+  if (opts.dryRun) return false;
   try { fs.rmdirSync(skillDir); return true; } catch { return false; }
 }