@aiwg/cli 2026.10.6 → 2026.10.7

package/dist/src/models/worker-installation.mjs

@@ -824,6 +824,40 @@ export async function prepareWorkerInstallationStore({ workerWritableRoots, appl
   return assertTrustedStore(installationStorePath(), workerWritableRoots, true, apply);
 }
 
+// Use the existing delivery ledger's host-selected keyring, never public keys
+// supplied by a registration. PAE separates this authority from effect records.
+const qualificationPayloadType = 'application/vnd.aiwg.worker-installation-qualification+json';
+const requalifyMessage = 'Re-run aiwg doctor --probe-workers --qualify. Existing unsigned approvals require deliberate one-time requalification.';
+const keyRecoveryMessage = 'Worker qualification signing trust is unavailable. Check effects.keyProvider in aiwg.config, unlock or restore the existing effect-ledger key, and run aiwg effect keys init if its keyring is not initialized; then re-run aiwg doctor --probe-workers --qualify.';
+
+async function qualificationTrust(cwd, scope) {
+  const { effectSession, openLedger } = await import('../effects/host.js');
+  const { openEffectLedger, readLedgerKeyring } = await import('../effects/ledger.js');
+  const ledger = scope ? openEffectLedger({ projectDir: cwd, scope, writer: 'cli' }) : openLedger(await effectSession(cwd));
+  const keyring = await readLedgerKeyring(ledger);
+  if (!keyring) throw new Error(keyRecoveryMessage);
+  return { ledger, keyring };
+}
+
+async function qualificationPayload(record, signedAt, projectDir, scope) {
+  const { canonicalJson } = await import('../security/artifact-trust.js');
+  const { signature: _signature, ...body } = record;
+  return Buffer.from(canonicalJson({ record: JSON.parse(JSON.stringify(body)), signedAt, projectDir, scope }), 'utf8');
+}
+
+async function qualificationSignatureFailure(record, trust) {
+  if (!record.signature) return 'signature-missing';
+  const { keyid, sig, signedAt, projectDir, scope } = record.signature;
+  if (typeof keyid !== 'string' || typeof sig !== 'string' || typeof signedAt !== 'string'
+    || typeof projectDir !== 'string' || !path.isAbsolute(projectDir) || !scope) return 'signature-invalid';
+  let keyring;
+  try { ({ keyring } = await trust(projectDir, scope)); } catch { return 'signature-trust-unavailable'; }
+  const { checkSignature } = await import('../effects/keyring.js');
+  const result = checkSignature(keyring, keyid, sig, qualificationPayloadType,
+    await qualificationPayload(record, signedAt, projectDir, scope), signedAt);
+  return result === 'ok' ? null : result === 'signature-invalid' ? result : `signature-${result}`;
+}
+
 async function readInstallationStore(filename, expectedDigest) {
   try {
     const bytes = await readInstalledFile(filename);
@@ -864,6 +898,7 @@ export async function inspectRecordedWorkerQualifications({ cwd, policy, paralle
         || (configured.executable && await realpath(configured.executable) !== await realpath(installation.executable))) continue;
       const proof = adapter.invocationProfiles?.[binding.profile]?.installationQualification;
       if (!proof || ['scopeDigest', 'fixtureDigest', 'verifiedAt', 'evidenceRef'].some(key => proof[key] !== installation.evidence?.[key])) continue;
+      if (await qualificationSignatureFailure(record, () => qualificationTrust(cwd))) continue;
       await assertWorkerInstallationEvidence({ ...installation, adapter, now: Date.now(), policy }, proof.scopeDigest);
       results.push({ cli, provider: adapter.provider });
     } catch { /* Malformed, expired or unbound evidence is not qualification. */ }
@@ -879,6 +914,15 @@ export async function recordWorkerInstallation(instance, options) {
   const installation = structuredClone(options.installation);
   const result = await qualifyWorkerInstallation(instance, { ...installation, now: Date.now() });
   if (result.status !== 'ENABLED') return result;
+  let signingKey, keyring, signingProjectDir;
+  try {
+    signingProjectDir = await realpath(options.projectDir ?? installation.cwd);
+    const trust = await qualificationTrust(signingProjectDir);
+    keyring = trust.keyring;
+    signingKey = await trust.ledger.signingKey();
+    const { activeKey } = await import('../effects/keyring.js');
+    if (activeKey(keyring).keyid !== signingKey.keyid) throw new Error('inactive key');
+  } catch { return { status: 'DISABLED', reason: keyRecoveryMessage }; }
   const adapter = structuredClone(installation.adapter);
   adapter.invocationProfiles[installation.profile].installationQualification = {
     scopeDigest: result.scopeDigest, fixtureDigest: result.fixtureDigest,
@@ -913,6 +957,14 @@ export async function recordWorkerInstallation(instance, options) {
       installation: { ...installation, environmentNames, versionProbe: { rawBanner: result.rawVersionBanner, version: result.cliVersion } },
       ...(options.mcpSchemas ? { mcpSchemas: structuredClone(options.mcpSchemas) } : {}),
       ...(options.mcpProfile ? { mcpProfile: structuredClone(options.mcpProfile) } : {}) };
+    const signedAt = new Date().toISOString();
+    try {
+      const payload = await qualificationPayload(record, signedAt, signingProjectDir, keyring.scope);
+      const sig = signingKey.signPae(qualificationPayloadType, payload);
+      const { checkSignature } = await import('../effects/keyring.js');
+      if (checkSignature(keyring, signingKey.keyid, sig, qualificationPayloadType, payload, signedAt) !== 'ok') throw new Error('invalid signature');
+      record.signature = { keyid: signingKey.keyid, sig, signedAt, projectDir: signingProjectDir, scope: keyring.scope };
+    } catch { return { status: 'DISABLED', reason: keyRecoveryMessage }; }
     const retained = [];
     for (const entry of stored.registrations) {
       const workspace = typeof entry.installation?.cwd === 'string'
@@ -944,7 +996,8 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, p
   // Underlying errors can contain probe output, environment values or paths.
   const rejections = [];
   const fail = () => new WorkerPolicyError('OG_ADAPTER_UNQUALIFIED',
-    `Trusted installation qualification is required (${[...new Set(rejections.map(row => row.reason))].join(', ')})`,
+    `Trusted installation qualification is required (${[...new Set(rejections.map(row => row.reason))].join(', ')})${rejections.some(row => row.reason.startsWith('signature-'))
+      ? `. ${rejections.some(row => row.reason === 'signature-trust-unavailable') ? keyRecoveryMessage : requalifyMessage}` : ''}`,
     { rejections });
   let reason = 'store-binding';
   let filename;
@@ -968,6 +1021,7 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, p
   const installations = {};
   const drivers = {};
   const observations = {};
+  const qualificationFailures = Object.create(null);
   const resolvedRegistry = structuredClone(registry);
   const requestedWorkspace = await realpath(cwd);
   const workspaces = await Promise.all(stored.registrations.map(async record => {
@@ -990,6 +1044,11 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, p
       if (!/^[a-z][a-z0-9-]{0,62}$/.test(cli)) throw fail();
       if (counts.get(JSON.stringify([cli, workspaces[registration]])) !== 1) throw fail();
       if (selected.get(cli) !== registration) continue;
+      // A conductor-pinned store digest also binds the original config source.
+      // Framing from a worker cwd must never read that cwd's configuration.
+      reason = await qualificationSignatureFailure(record, (projectDir, scope) => storePath === undefined
+        ? qualificationTrust(cwd) : qualificationTrust(projectDir, scope));
+      if (reason) throw fail();
       const installation = { ...record.installation, adapter, now: Date.now(), environment: {} };
       reason = 'environment-name';
       if (record.installation.environment && Object.keys(record.installation.environment).length) throw fail();
@@ -1106,13 +1165,15 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, p
       Object.assign(resolvedRegistry, candidateRegistry);
     } catch (error) {
       // One rejected installation cannot grant authority or hide qualified peers.
-      rejections.push({ registration, reason: reason === 'module-registration' && error?.code === 'WORKER_ADAPTER_CONFLICT'
-        ? 'adapter-conflict' : reason });
+      const failureReason = reason === 'module-registration' && error?.code === 'WORKER_ADAPTER_CONFLICT'
+        ? 'adapter-conflict' : reason;
+      rejections.push({ registration, reason: failureReason });
+      if (typeof record?.cli === 'string' && /^[a-z][a-z0-9-]{0,62}$/.test(record.cli)) qualificationFailures[record.cli] = failureReason;
     }
   }
   if (!Object.keys(installations).length) {
     if (!rejections.length) rejections.push({ registration: null, reason: 'no-records' });
     throw fail();
   }
-  return { registry: resolvedRegistry, installations, drivers, observations };
+  return { registry: resolvedRegistry, installations, drivers, observations, qualificationFailures };
 }

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/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/serve/worker-invocation.js

@@ -640,6 +640,16 @@ export function workerInvocationDiagnostic(error, pointer, fallback = 'OG_CONFIG
     if (error instanceof WorkerInvocationCheckError)
         return { code: error.code, reason: error.reason, ...invocationChecks[error.reason] };
     const code = error instanceof WorkerPolicyError ? error.code : fallback;
+    const signatureReason = error instanceof WorkerPolicyError
+        ? error.details?.rejections.find(row => row.reason.startsWith('signature-'))?.reason : undefined;
+    if (code === 'OG_ADAPTER_UNQUALIFIED' && signatureReason) {
+        const messages = {
+            'signature-missing': 'Unsigned worker installation approval is unqualified. This requires deliberate one-time requalification: re-run aiwg doctor --probe-workers --qualify.',
+            'signature-trust-unavailable': 'Worker qualification signing trust is unavailable. Check effects.keyProvider in aiwg.config and the existing delivery effect-ledger keyring (aiwg effect keys list); restore trust, then re-run aiwg doctor --probe-workers --qualify.',
+        };
+        return { code, pointer, message: messages[signatureReason]
+                ?? 'Worker installation signature is invalid or its keyid is untrusted. Re-run aiwg doctor --probe-workers --qualify.' };
+    }
     const messages = {
         OG_SANDBOX_EXTERNAL: "The CLI's own sandbox is disabled by explicit external policy; isolation relies on the per-task worktree and launcher resource scope.",
         OG_NATIVE_SANDBOX_UNAVAILABLE: 'Native sandbox unavailable inside systemd user units; select policy launchMode native-sandbox or allow unprivileged user namespaces through host AppArmor policy.',

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -23,7 +23,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, dedupeProviderBootstrap, } from './workspace-context.js';
 import { dominantLineEnding, withLineEnding } from './line-endings.js';
-import { assertSafeContextFile } from './context-file-safety.js';
+import { assertSafeContextFile, writeContextFileSync } from './context-file-safety.js';
 export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
 export const CLAUDE_HOOK_END = '<!-- AIWG:claude-md-hook:end -->';
 export function buildClaudeHookBlock(_policy = {}) {
@@ -92,7 +92,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     catch (err) {
         if (err.code === 'ENOENT') {
             const minimal = `${block}\n`;
-            await fs.writeFile(claudeMdPath, minimal, 'utf8');
+            writeContextFileSync(claudeMdPath, minimal, 'utf8');
             result.action = 'created';
             return result;
         }
@@ -121,7 +121,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
             const updated = existing.substring(0, bootstrapStartIdx)
                 + block
                 + existing.substring(bootstrapEndIdx);
-            await fs.writeFile(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
+            writeContextFileSync(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
             result.action = 'updated';
             return result;
         }
@@ -132,7 +132,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         // Ensure the file ends with a single newline before appending.
         const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
         const updated = `${trimmed}${lineEnding}${block}${lineEnding}`;
-        await fs.writeFile(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
+        writeContextFileSync(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
         result.action = 'inserted';
         return result;
     }
@@ -145,12 +145,12 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         // With --force, back up and append a fresh block.
         if (opts.detectExistingFiles !== false) {
             const backupPath = `${claudeMdPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
-            await fs.writeFile(backupPath, existing, 'utf8');
+            writeContextFileSync(backupPath, existing, 'utf8');
             result.backupPath = backupPath;
         }
         const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
         const updated = `${trimmed}${lineEnding}${block}${lineEnding}`;
-        await fs.writeFile(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
+        writeContextFileSync(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
         result.action = 'inserted';
         return result;
     }
@@ -159,7 +159,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     const currentBlock = existing.substring(startIdx, blockEndOffset);
     if (currentBlock === block) {
         if (repaired) {
-            await fs.writeFile(claudeMdPath, existing, 'utf8');
+            writeContextFileSync(claudeMdPath, existing, 'utf8');
             result.action = 'updated';
             return result;
         }
@@ -171,14 +171,14 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     // the case where an operator made deliberate edits inside the block).
     if (opts.force) {
         const backupPath = `${claudeMdPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
-        await fs.writeFile(backupPath, existing, 'utf8');
+        writeContextFileSync(backupPath, existing, 'utf8');
         result.backupPath = backupPath;
     }
     else {
         result.warnings.push(`CLAUDE.md AIWG hook block has been modified inside the markers; updating to canonical content. Operator content outside the block is preserved.`);
     }
     const updated = existing.substring(0, startIdx) + block + existing.substring(blockEndOffset);
-    await fs.writeFile(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
+    writeContextFileSync(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
     result.action = 'updated';
     return result;
 }