@aiwg/cli 2026.10.7 → 2026.10.9

package/dist/src/resources/web-release.js

@@ -433,6 +433,9 @@ async function fetchBytes(fetcher, url, label, maxBytes, bearerToken) {
     catch (error) {
         if (timedOut)
             throw new Error(`${label} request timed out after ${RESOURCE_FETCH_TIMEOUT_MS}ms`);
+        const message = error instanceof Error ? error.message : String(error);
+        if (bearerToken && message.includes(bearerToken))
+            throw new Error(message.split(bearerToken).join('[REDACTED]'));
         throw error;
     }
     finally {
@@ -1072,80 +1075,88 @@ export async function resolveWebRelease(options = {}) {
         const headers = { ...(init.headers || {}), ...(bearerToken ? { authorization: `Bearer ${bearerToken}` } : {}) };
         return (options.fetcher ?? globalThis.fetch)(input, { ...init, headers });
     };
-    if (selector.kind === "exact") {
-        if (options.offline)
-            return resolveOfflineExact(cacheRoot, selector, selector.value, publicKeyPem, base);
-        const fetcher = authorize;
-        if (!fetcher)
-            throw new Error("No fetch implementation is available for AIWG web resources");
-        return fetchAndCacheRelease(base, fetcher, cacheRoot, selector, selector.value, publicKeyPem);
-    }
-    if (selector.kind === "range" || selector.kind === "digest") {
-        if (!options.offline && selector.kind === "digest") {
-            for (const version of cachedReleaseVersions(cacheRoot)) {
-                if (!cachedDigests(cacheRoot, version).includes(selector.digest))
-                    continue;
-                try {
-                    return verifyCachedGeneration(cacheRoot, version, selector.digest, selector, publicKeyPem, base, selector.digest);
-                }
-                catch {
-                    // A corrupt immutable generation cannot bypass signed index resolution.
+    try {
+        if (selector.kind === "exact") {
+            if (options.offline)
+                return resolveOfflineExact(cacheRoot, selector, selector.value, publicKeyPem, base);
+            const fetcher = authorize;
+            if (!fetcher)
+                throw new Error("No fetch implementation is available for AIWG web resources");
+            return await fetchAndCacheRelease(base, fetcher, cacheRoot, selector, selector.value, publicKeyPem);
+        }
+        if (selector.kind === "range" || selector.kind === "digest") {
+            if (!options.offline && selector.kind === "digest") {
+                for (const version of cachedReleaseVersions(cacheRoot)) {
+                    if (!cachedDigests(cacheRoot, version).includes(selector.digest))
+                        continue;
+                    try {
+                        return verifyCachedGeneration(cacheRoot, version, selector.digest, selector, publicKeyPem, base, selector.digest);
+                    }
+                    catch {
+                        // A corrupt immutable generation cannot bypass signed index resolution.
+                    }
                 }
             }
+            const fetcher = authorize;
+            const index = await resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, options.offline, options.onDiagnostic);
+            const selected = selectVersionFromIndex(index, selector);
+            if (options.offline) {
+                return resolveOfflineExact(cacheRoot, selector, selected.version, publicKeyPem, base, selected.releaseManifestSha256);
+            }
+            if (!fetcher)
+                throw new Error("No fetch implementation is available for AIWG web resources");
+            return await fetchAndCacheRelease(base, fetcher, cacheRoot, selector, selected.version, publicKeyPem, selected.releaseManifestSha256);
         }
-        const fetcher = authorize;
-        const index = await resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, options.offline, options.onDiagnostic);
-        const selected = selectVersionFromIndex(index, selector);
         if (options.offline) {
-            return resolveOfflineExact(cacheRoot, selector, selected.version, publicKeyPem, base, selected.releaseManifestSha256);
+            const cached = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
+            if (!cached)
+                throw new Error(`AIWG resource channel ${selector.value} is not cached; offline mode cannot fetch it`);
+            const release = resolveOfflineExact(cacheRoot, selector, cached.manifest.version, publicKeyPem, base, cached.manifest.releaseManifestSha256, cached.manifest.sequence);
+            return cached.manifest.expiresAt ? { ...release, channelExpiresAt: cached.manifest.expiresAt } : release;
         }
+        const fetcher = authorize;
         if (!fetcher)
             throw new Error("No fetch implementation is available for AIWG web resources");
-        return fetchAndCacheRelease(base, fetcher, cacheRoot, selector, selected.version, publicKeyPem, selected.releaseManifestSha256);
-    }
-    if (options.offline) {
-        const cached = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
-        if (!cached)
-            throw new Error(`AIWG resource channel ${selector.value} is not cached; offline mode cannot fetch it`);
-        const release = resolveOfflineExact(cacheRoot, selector, cached.manifest.version, publicKeyPem, base, cached.manifest.releaseManifestSha256, cached.manifest.sequence);
-        return cached.manifest.expiresAt ? { ...release, channelExpiresAt: cached.manifest.expiresAt } : release;
-    }
-    const fetcher = authorize;
-    if (!fetcher)
-        throw new Error("No fetch implementation is available for AIWG web resources");
-    const channelPrefix = `resources/channels/${selector.value}`;
-    let prior = null;
-    try {
-        prior = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
+        const channelPrefix = `resources/channels/${selector.value}`;
+        let prior = null;
+        try {
+            prior = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
+        }
+        catch {
+            prior = null;
+        }
+        const fetched = await fetchMetadata(fetcher, resourceUrl(base, `${channelPrefix}.json`), `channel ${selector.value}`, MAX_SIGNED_METADATA_BYTES, prior?.validator);
+        if (fetched.notModified) {
+            cacheChannel(cacheRoot, prior.manifest, prior.bytes, prior.signatureBytes, prior.digest, fetched.validator);
+            options.onDiagnostic?.({ resource: "channel", outcome: "conditional-hit", validator: prior.validator.etag ? "etag" : "last-modified" });
+            const release = await fetchAndCacheRelease(base, fetcher, cacheRoot, selector, prior.manifest.version, publicKeyPem, prior.manifest.releaseManifestSha256, prior.manifest.sequence);
+            return prior.manifest.expiresAt ? { ...release, channelExpiresAt: prior.manifest.expiresAt } : release;
+        }
+        const channelBytes = fetched.bytes;
+        const channelSignatureBytes = await fetchBytes(fetcher, resourceUrl(base, `${channelPrefix}.sig`), `channel ${selector.value} signature`, MAX_SIGNATURE_BYTES);
+        const channelDigest = verifySignedResourceBytes(channelBytes, channelSignatureBytes, publicKeyPem, `channel ${selector.value}`);
+        const channel = validateChannelManifest(parseJson(channelBytes, `channel ${selector.value}`), selector.value);
+        if (prior && channel.sequence < prior.manifest.sequence) {
+            throw new Error(`channel ${selector.value} sequence rollback detected (${channel.sequence} < ${prior.manifest.sequence})`);
+        }
+        if (prior &&
+            channel.sequence === prior.manifest.sequence &&
+            (channelDigest !== prior.digest ||
+                channel.version !== prior.manifest.version ||
+                channel.releaseManifestSha256 !== prior.manifest.releaseManifestSha256)) {
+            throw new Error(`channel ${selector.value} sequence ${channel.sequence} has conflicting signed metadata`);
+        }
+        const release = await fetchAndCacheRelease(base, fetcher, cacheRoot, selector, channel.version, publicKeyPem, channel.releaseManifestSha256, channel.sequence);
+        cacheChannel(cacheRoot, channel, channelBytes, channelSignatureBytes, channelDigest, fetched.validator);
+        options.onDiagnostic?.({ resource: "channel", outcome: prior?.validator ? "revalidated" : "unconditional", validator: fetched.validator?.etag ? "etag" : fetched.validator?.lastModified ? "last-modified" : "none" });
+        return channel.expiresAt ? { ...release, channelExpiresAt: channel.expiresAt } : release;
     }
-    catch {
-        prior = null;
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (bearerToken && message.includes(bearerToken))
+            throw new Error(message.split(bearerToken).join('[REDACTED]'));
+        throw error;
     }
-    const fetched = await fetchMetadata(fetcher, resourceUrl(base, `${channelPrefix}.json`), `channel ${selector.value}`, MAX_SIGNED_METADATA_BYTES, prior?.validator);
-    if (fetched.notModified) {
-        cacheChannel(cacheRoot, prior.manifest, prior.bytes, prior.signatureBytes, prior.digest, fetched.validator);
-        options.onDiagnostic?.({ resource: "channel", outcome: "conditional-hit", validator: prior.validator.etag ? "etag" : "last-modified" });
-        const release = await fetchAndCacheRelease(base, fetcher, cacheRoot, selector, prior.manifest.version, publicKeyPem, prior.manifest.releaseManifestSha256, prior.manifest.sequence);
-        return prior.manifest.expiresAt ? { ...release, channelExpiresAt: prior.manifest.expiresAt } : release;
-    }
-    const channelBytes = fetched.bytes;
-    const channelSignatureBytes = await fetchBytes(fetcher, resourceUrl(base, `${channelPrefix}.sig`), `channel ${selector.value} signature`, MAX_SIGNATURE_BYTES);
-    const channelDigest = verifySignedResourceBytes(channelBytes, channelSignatureBytes, publicKeyPem, `channel ${selector.value}`);
-    const channel = validateChannelManifest(parseJson(channelBytes, `channel ${selector.value}`), selector.value);
-    if (prior && channel.sequence < prior.manifest.sequence) {
-        throw new Error(`channel ${selector.value} sequence rollback detected (${channel.sequence} < ${prior.manifest.sequence})`);
-    }
-    if (prior &&
-        channel.sequence === prior.manifest.sequence &&
-        (channelDigest !== prior.digest ||
-            channel.version !== prior.manifest.version ||
-            channel.releaseManifestSha256 !== prior.manifest.releaseManifestSha256)) {
-        throw new Error(`channel ${selector.value} sequence ${channel.sequence} has conflicting signed metadata`);
-    }
-    const release = await fetchAndCacheRelease(base, fetcher, cacheRoot, selector, channel.version, publicKeyPem, channel.releaseManifestSha256, channel.sequence);
-    cacheChannel(cacheRoot, channel, channelBytes, channelSignatureBytes, channelDigest, fetched.validator);
-    options.onDiagnostic?.({ resource: "channel", outcome: prior?.validator ? "revalidated" : "unconditional", validator: fetched.validator?.etag ? "etag" : fetched.validator?.lastModified ? "last-modified" : "none" });
-    return channel.expiresAt ? { ...release, channelExpiresAt: channel.expiresAt } : release;
 }
 export async function fetchVerifiedRawResource(release, resourcePath, options = {}) {
     assertSafeRelativePath(resourcePath, "raw resource path");

package/dist/src/serve/shared-host-scheduler.js

@@ -233,7 +233,10 @@ export class FileAdmissionStore {
             const file = openSync(this.path, constants.O_RDONLY | constants.O_NOFOLLOW);
             try {
                 const stat = fstatSync(file);
-                if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.() || stat.size > 16 * 1024 * 1024)
+                // nlink is 0 when a writer atomically renamed a new snapshot over the
+                // file after this reader opened it; the open descriptor is still a
+                // complete earlier snapshot. Only extra hard links are refused.
+                if (!stat.isFile() || stat.nlink > 1 || (stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.() || stat.size > 16 * 1024 * 1024)
                     throw new Error('host authority must be a private bounded regular file');
                 return JSON.parse(readFileSync(file, 'utf8'));
             }

package/dist/src/storage/backends/fortemi.js

@@ -37,6 +37,8 @@
  * @issue #972
  */
 import { createHash } from 'node:crypto';
+import { debuglog } from 'node:util';
+import { hasSecretLookingLiterals } from '../../mcp/credentials.mjs';
 const FORTEMI_QUERY_LIMIT = 50;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function schemaProperties(tool) {
@@ -81,7 +83,7 @@ export function resolveMcpRequestHeaders(server, environment = process.env) {
     const headers = { ...(server.headers ?? {}) };
     for (const [header, envName] of Object.entries(server.headerEnv ?? {})) {
         if (!ENV_NAME.test(envName)) {
-            throw new Error(`storage(fortemi): invalid environment variable reference "${envName}"`);
+            throw new Error('storage(fortemi): invalid environment variable reference; use ENV_NAME, file:ABSOLUTE_PATH or store:NAME.');
         }
         const value = environment[envName];
         if (!value) {
@@ -371,8 +373,8 @@ export class FortemiAdapter {
  * Implemented as a lazy import so tests that inject a stub never load
  * the SDK or touch the registry.
  */
-export const createDefaultMcpClient = async (serverName, registryOverride, environment = process.env) => {
-    const { McpServerRegistry } = await import('../../mcp/registry.js');
+export const createDefaultMcpClient = async (serverName, registryOverride, environment = process.env, sensitiveInput = {}) => {
+    const { McpServerRegistry, resolveMcpCredentialMaps } = await import('../../mcp/registry.js');
     const registry = registryOverride ?? new McpServerRegistry();
     const server = await registry.get(serverName);
     if (!server) {
@@ -381,60 +383,120 @@ export const createDefaultMcpClient = async (serverName, registryOverride, envir
     }
     // Lazy imports keep unit tests that inject a stub isolated from transports.
     const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
-    let transport;
-    if (server.type === 'stdio') {
-        const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
-        transport = new StdioClientTransport({
-            command: server.command ?? '',
-            args: server.args ?? [],
-            env: server.env,
-        });
+    const hasCredentials = [server.env, server.headers, server.envFrom, server.headerEnv]
+        .some(map => Object.keys(map ?? {}).length > 0);
+    if (hasCredentials && server.type === 'stdio' && debuglog('child_process').enabled) {
+        throw new Error('MCP stdio credentials require NODE_DEBUG child_process logging to be disabled.');
     }
-    else {
-        if (!server.url) {
-            throw new Error(`storage(fortemi): MCP server "${serverName}" has no URL`);
+    // Reuse the registry resolver for file/store references. Preserve legacy env
+    // bytes and Authorization's existing Bearer prefix at the transport boundary.
+    const hasNewReferences = [...Object.values(server.headerEnv ?? {}), ...Object.values(server.envFrom ?? {})]
+        .some(reference => /^(?:file|store):/.test(reference));
+    const resolved = hasNewReferences
+        ? await resolveMcpCredentialMaps(server, { ...sensitiveInput, environment })
+        : { env: server.env ? { ...server.env } : undefined, headers: resolveMcpRequestHeaders(server, environment) };
+    if (!hasNewReferences) {
+        for (const [key, name] of Object.entries(server.envFrom ?? {})) {
+            if (!ENV_NAME.test(name) || !environment[name]) {
+                throw new Error('storage(fortemi): envFrom requires a set ENV_NAME, file:ABSOLUTE_PATH or store:NAME.');
+            }
+            resolved.env = { ...resolved.env, [key]: environment[name] };
         }
-        const url = validateRemoteMcpUrl(server.url);
-        const headers = resolveMcpRequestHeaders(server, environment);
-        if (server.type === 'http') {
-            const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
-            transport = new StreamableHTTPClientTransport(url, {
-                requestInit: { headers },
-            });
+    }
+    const secrets = [
+        ...Object.entries(resolved.env ?? {}).filter(([key, value]) => key in (server.envFrom ?? {}) || hasSecretLookingLiterals({ name: server.name, env: { [key]: value } })).map(([, value]) => value),
+        ...Object.values(resolved.headers ?? {}),
+        ...Object.values(resolved.headers ?? {}).map(value => value.replace(/^Bearer /i, '')),
+    ].filter(Boolean).sort((a, b) => b.length - a.length);
+    const redact = (text) => secrets.reduce((text, secret) => text.split(secret).join('[REDACTED]'), text);
+    const protect = async (operation) => {
+        try {
+            return await operation();
         }
-        else if (server.type === 'sse') {
-            const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
-            transport = new SSEClientTransport(url, {
-                requestInit: { headers },
-                eventSourceInit: {
-                    fetch: async (input, init) => {
-                        const merged = new Headers(init?.headers);
-                        for (const [name, value] of Object.entries(headers))
-                            merged.set(name, value);
-                        return fetch(input, { ...init, headers: merged });
-                    },
-                },
+        catch (error) {
+            throw new Error(redact(error instanceof Error ? error.message : 'MCP transport failed'));
+        }
+    };
+    const protectResult = (value) => {
+        if (typeof value === 'string')
+            return redact(value);
+        if (Array.isArray(value))
+            return value.map(protectResult);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value).map(([key, value]) => [redact(key), protectResult(value)]));
+        return value;
+    };
+    try {
+        let transport;
+        if (server.type === 'stdio') {
+            const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
+            transport = new StdioClientTransport({
+                command: server.command ?? '',
+                args: server.args ?? [],
+                env: resolved.env,
+                ...(hasCredentials ? { stderr: 'pipe' } : {}),
             });
         }
         else {
-            throw new Error(`storage(fortemi): unsupported MCP transport "${String(server.type)}"`);
+            if (!server.url) {
+                throw new Error(`storage(fortemi): MCP server "${serverName}" has no URL`);
+            }
+            const url = validateRemoteMcpUrl(server.url);
+            const headers = resolved.headers ?? {};
+            if (hasNewReferences) {
+                for (const header of Object.keys(server.headerEnv ?? {})) {
+                    if (header.toLowerCase() === 'authorization')
+                        headers[header] = `Bearer ${headers[header]}`;
+                }
+            }
+            if (server.type === 'http') {
+                const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
+                transport = new StreamableHTTPClientTransport(url, {
+                    requestInit: { headers },
+                });
+            }
+            else if (server.type === 'sse') {
+                const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
+                transport = new SSEClientTransport(url, {
+                    requestInit: { headers },
+                    eventSourceInit: {
+                        fetch: async (input, init) => {
+                            const merged = new Headers(init?.headers);
+                            for (const [name, value] of Object.entries(headers))
+                                merged.set(name, value);
+                            return fetch(input, { ...init, headers: merged });
+                        },
+                    },
+                });
+            }
+            else {
+                throw new Error(`storage(fortemi): unsupported MCP transport "${String(server.type)}"`);
+            }
+        }
+        const client = new Client({ name: 'aiwg-storage-fortemi-adapter', version: '1.0.0' }, { capabilities: {} });
+        if (hasCredentials && server.type === 'stdio') {
+            // The recipient's stderr can contain credentials. Drain without forwarding.
+            transport.stderr?.on('data', () => { });
         }
+        await protect(() => client.connect(transport));
+        return {
+            async callTool(name, args) {
+                const call = async () => unwrapMcpToolResult(await client.callTool({ name, arguments: args }));
+                return protectResult(await protect(call));
+            },
+            async listTools() {
+                return protectResult(await protect(() => client.listTools()));
+            },
+            serverVersion() {
+                return protectResult(client.getServerVersion());
+            },
+            async close() {
+                await protect(() => client.close());
+            },
+        };
+    }
+    catch (error) {
+        throw new Error(redact(error instanceof Error ? error.message : 'MCP transport failed'));
     }
-    const client = new Client({ name: 'aiwg-storage-fortemi-adapter', version: '1.0.0' }, { capabilities: {} });
-    await client.connect(transport);
-    return {
-        async callTool(name, args) {
-            return unwrapMcpToolResult(await client.callTool({ name, arguments: args }));
-        },
-        async listTools() {
-            return client.listTools();
-        },
-        serverVersion() {
-            return client.getServerVersion();
-        },
-        async close() {
-            await client.close();
-        },
-    };
 };
 //# sourceMappingURL=fortemi.js.map

package/dist/src/storage/backends/logseq.js

@@ -32,20 +32,26 @@
  * @issue #958
  */
 import { existsSync } from 'fs';
+import { resolveSensitiveInput } from '../../auth/sensitive-input.js';
+import { credentialReferenceInput } from '../../mcp/credentials.mjs';
 import { mkdir, readFile, readdir, rm, stat, writeFile } from 'fs/promises';
 import { dirname, join, relative, resolve, sep } from 'path';
 const LOGSEQ_CONFIG_DIR = 'logseq';
 const DEFAULT_API_URL = 'http://127.0.0.1:12315/api';
 export class LogseqAdapter {
+    sensitiveInput;
     /** Absolute path to the Logseq graph root. */
     graph;
     apiUrl;
     useApi;
+    apiTokenEnv;
     apiWarned = false;
-    constructor(config) {
+    constructor(config, sensitiveInput = {}) {
+        this.sensitiveInput = sensitiveInput;
         this.graph = resolve(expandHome(config.graph));
         this.apiUrl = config.apiUrl ?? DEFAULT_API_URL;
         this.useApi = config.useApi ?? true;
+        this.apiTokenEnv = config.apiTokenEnv;
     }
     async init() {
         if (!existsSync(this.graph)) {
@@ -61,7 +67,14 @@ export class LogseqAdapter {
     async probeApi() {
         if (this.apiWarned)
             return;
-        const token = process.env['LOGSEQ_API_TOKEN'];
+        const input = credentialReferenceInput(this.apiTokenEnv ?? 'LOGSEQ_API_TOKEN', 'Logseq apiTokenEnv');
+        // Keep the optional legacy environment path, including its missing-token warning.
+        const token = input.env
+            ? (this.sensitiveInput.environment ?? process.env)[input.env]
+            : await resolveSensitiveInput(input, this.sensitiveInput);
+        if (!token && this.apiTokenEnv !== undefined) {
+            throw new Error('storage(logseq): apiTokenEnv is not set; use ENV_NAME, file:ABSOLUTE_PATH or store:NAME.');
+        }
         if (!token) {
             this.apiWarned = true;
             process.stderr.write(`storage(logseq): API requested (useApi: true) but LOGSEQ_API_TOKEN is not set.\n` +
@@ -89,7 +102,7 @@ export class LogseqAdapter {
         }
         catch {
             this.apiWarned = true;
-            process.stderr.write(`storage(logseq): API server at ${this.apiUrl} is not reachable.\n` +
+            process.stderr.write(`storage(logseq): API server is not reachable.\n` +
                 `  AIWG will continue with direct file writes against the graph.\n` +
                 `  Start Logseq with the API server enabled, or set "useApi": false to suppress.\n`);
         }

package/dist/src/storage/backends/postgres.js

@@ -1,3 +1,5 @@
+import { resolveSensitiveInput } from '../../auth/sensitive-input.js';
+import { credentialReferenceInput } from '../../mcp/credentials.mjs';
 import { createHash } from 'node:crypto';
 import { loadFeaturePackage } from '../../features/runtime.js';
 import { STORAGE_BACKEND_CONTRACT, } from '../backend-contract.js';
@@ -27,6 +29,7 @@ export class PostgresBackendError extends Error {
  */
 export class PostgresStorageBackend {
     options;
+    sensitiveInput;
     descriptor = {
         contract: STORAGE_BACKEND_CONTRACT,
         backend: 'postgres-direct',
@@ -50,8 +53,9 @@ export class PostgresStorageBackend {
     statementTimeoutMs;
     lockTimeoutMs;
     idleTransactionTimeoutMs;
-    constructor(options) {
+    constructor(options, sensitiveInput = {}) {
         this.options = options;
+        this.sensitiveInput = sensitiveInput;
         validateIdentity(options.tenant, 'tenant');
         validateIdentity(options.subsystem, 'subsystem');
         this.pool = options.pool;
@@ -69,7 +73,7 @@ export class PostgresStorageBackend {
     }
     async init() {
         if (!this.pool)
-            this.pool = await createPool(this.options);
+            this.pool = await createPool(this.options, this.sensitiveInput);
         if (this.options.schemaMode !== 'migrate') {
             const schema = await this.runQuery('SELECT schema_version FROM aiwg_storage_schema WHERE singleton = true');
             if (Number(schema.rows[0]?.schema_version) !== 1) {
@@ -187,7 +191,7 @@ export class PostgresStorageBackend {
     }
     /** Hold an exported PostgreSQL snapshot open while parallel consumers page it. */
     async openSnapshotLease() {
-        const exporter = await this.requiredPool().connect();
+        const exporter = await this.connect();
         let closed = false;
         try {
             await exporter.query('BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY');
@@ -208,8 +212,11 @@ export class PostgresStorageBackend {
                     try {
                         await exporter.query('COMMIT');
                     }
+                    catch (error) {
+                        throw classifyPostgresError(error);
+                    }
                     finally {
-                        exporter.release(false);
+                        releaseClient(exporter, false);
                     }
                 },
             };
@@ -219,7 +226,7 @@ export class PostgresStorageBackend {
                 await exporter.query('ROLLBACK');
             }
             catch { /* preserve original error */ }
-            exporter.release(true);
+            releaseClient(exporter, true);
             throw classifyPostgresError(error);
         }
     }
@@ -228,7 +235,7 @@ export class PostgresStorageBackend {
             throw new PostgresBackendError('AIWG_POSTGRES_SNAPSHOT_INVALID', 'exported snapshot identifier is malformed');
         }
         const boundedLimit = bounded(limit, 1000, 1, 10_000, 'limit');
-        const client = await this.requiredPool().connect();
+        const client = await this.connect();
         let failed = false;
         try {
             await client.query('BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY');
@@ -252,7 +259,7 @@ export class PostgresStorageBackend {
             throw classifyPostgresError(error);
         }
         finally {
-            client.release(failed);
+            releaseClient(client, failed);
         }
     }
     async changes(cursor) {
@@ -322,12 +329,17 @@ export class PostgresStorageBackend {
         });
     }
     async close() {
-        if (this.ownsPool && this.pool)
-            await this.pool.end();
+        try {
+            if (this.ownsPool && this.pool)
+                await this.pool.end();
+        }
+        catch (error) {
+            throw classifyPostgresError(error);
+        }
         this.pool = undefined;
     }
     async withTransaction(operation, isolation = 'SERIALIZABLE') {
-        const client = await this.requiredPool().connect();
+        const client = await this.connect();
         let failed = false;
         try {
             await client.query(`BEGIN ISOLATION LEVEL ${isolation}`);
@@ -347,7 +359,7 @@ export class PostgresStorageBackend {
             throw classifyPostgresError(error);
         }
         finally {
-            client.release(failed);
+            releaseClient(client, failed);
         }
     }
     assertMutationIdentity(mutation) {
@@ -356,6 +368,14 @@ export class PostgresStorageBackend {
             throw new PostgresBackendError('AIWG_POSTGRES_IDENTITY_MISMATCH', 'mutation identity is outside this backend tenant/subsystem');
         }
     }
+    async connect() {
+        try {
+            return await this.requiredPool().connect();
+        }
+        catch (error) {
+            throw classifyPostgresError(error);
+        }
+    }
     requiredPool() {
         if (!this.pool)
             throw new PostgresBackendError('AIWG_POSTGRES_NOT_INITIALIZED', 'call init() before using the PostgreSQL backend');
@@ -370,11 +390,18 @@ export class PostgresStorageBackend {
         }
     }
 }
-async function createPool(options) {
+async function createPool(options, sensitiveInput) {
     const envName = options.connectionStringEnv ?? 'AIWG_POSTGRES_URL';
-    const connectionString = process.env[envName];
+    const input = credentialReferenceInput(envName, 'PostgreSQL connectionStringEnv');
+    let connectionString;
+    try {
+        connectionString = input.env ? (sensitiveInput.environment ?? process.env)[input.env] : await resolveSensitiveInput(input, sensitiveInput);
+    }
+    catch (error) {
+        throw new PostgresBackendError('AIWG_POSTGRES_CREDENTIAL_UNAVAILABLE', error.message);
+    }
     if (!connectionString) {
-        throw new PostgresBackendError('AIWG_POSTGRES_CREDENTIAL_UNAVAILABLE', `PostgreSQL connection locator ${envName} is not set`);
+        throw new PostgresBackendError('AIWG_POSTGRES_CREDENTIAL_UNAVAILABLE', 'PostgreSQL connectionStringEnv is not set; use ENV_NAME (default AIWG_POSTGRES_URL), file:ABSOLUTE_PATH or store:NAME.');
     }
     if (options.ssl === undefined) {
         throw new PostgresBackendError('AIWG_POSTGRES_TLS_REQUIRED', 'PostgreSQL remote connections require explicit ssl=require or ssl=verify-full');
@@ -382,24 +409,29 @@ async function createPool(options) {
     if (options.ssl === 'disable' && !isLoopbackPostgresUrl(connectionString)) {
         throw new PostgresBackendError('AIWG_POSTGRES_TLS_REQUIRED', 'ssl=disable is limited to explicit loopback development endpoints');
     }
-    const pg = await loadFeaturePackage('pg');
-    const defaultExport = pg.default;
-    const Pool = (pg.Pool ?? defaultExport?.Pool);
-    if (!Pool)
-        throw new PostgresBackendError('AIWG_POSTGRES_DRIVER_INVALID', 'optional pg package does not export Pool');
-    const pool = new Pool({
-        connectionString,
-        max: bounded(options.maxConnections, DEFAULT_POOL_MAX, 1, 100, 'maxConnections'),
-        connectionTimeoutMillis: bounded(options.connectionTimeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'connectionTimeoutMs'),
-        statement_timeout: bounded(options.statementTimeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'statementTimeoutMs'),
-        application_name: options.applicationName ?? 'aiwg',
-        ssl: options.ssl === 'disable' ? false : { rejectUnauthorized: options.ssl === 'verify-full' },
-    });
-    // pg emits idle-client failures at pool scope. Registering a listener keeps
-    // server restarts from becoming uncaught process exceptions; failed clients
-    // are evicted by pg and the next backend operation reconnects normally.
-    pool.on?.('error', () => undefined);
-    return pool;
+    try {
+        const pg = await loadFeaturePackage('pg');
+        const defaultExport = pg.default;
+        const Pool = (pg.Pool ?? defaultExport?.Pool);
+        if (!Pool)
+            throw new PostgresBackendError('AIWG_POSTGRES_DRIVER_INVALID', 'optional pg package does not export Pool');
+        const pool = new Pool({
+            connectionString,
+            max: bounded(options.maxConnections, DEFAULT_POOL_MAX, 1, 100, 'maxConnections'),
+            connectionTimeoutMillis: bounded(options.connectionTimeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'connectionTimeoutMs'),
+            statement_timeout: bounded(options.statementTimeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'statementTimeoutMs'),
+            application_name: options.applicationName ?? 'aiwg',
+            ssl: options.ssl === 'disable' ? false : { rejectUnauthorized: options.ssl === 'verify-full' },
+        });
+        // pg emits idle-client failures at pool scope. Registering a listener keeps
+        // server restarts from becoming uncaught process exceptions; failed clients
+        // are evicted by pg and the next backend operation reconnects normally.
+        pool.on?.('error', () => undefined);
+        return pool;
+    }
+    catch (error) {
+        throw classifyPostgresError(error);
+    }
 }
 function isLoopbackPostgresUrl(connectionString) {
     try {
@@ -468,6 +500,15 @@ function classifyPostgresError(error) {
     if (['40001', '40P01', '55P03', '57014', '57P01', '57P02', '57P03', '08000', '08003', '08006', '08001'].includes(code)) {
         return new PostgresBackendError('AIWG_POSTGRES_RETRYABLE', `retryable PostgreSQL failure (${code})`, true);
     }
-    return error instanceof Error ? error : new Error(String(error));
+    // Drivers may echo the entire connection string, passwords or server detail.
+    return new PostgresBackendError('AIWG_POSTGRES_OPERATION_FAILED', 'PostgreSQL operation failed; check connectivity, credentials and server configuration.');
+}
+function releaseClient(client, failed) {
+    try {
+        client.release(failed);
+    }
+    catch (error) {
+        throw classifyPostgresError(error);
+    }
 }
 //# sourceMappingURL=postgres.js.map