aptly 0.1.0 → 0.1.2

package/dist/src/server.js

@@ -13,7 +13,7 @@ const constraintsSchema = z.object({ model_pinned: z.boolean().optional(), effor
 const hookSchema = { client: z.enum(['codex', 'claude']), event: z.record(z.string(), z.unknown()) };
 const content = (result) => ({ content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result });
 export function createServer({ env = process.env } = {}) {
-    const { router, mode, modelInfo, disabledClients } = runtime(env);
+    const { router, mode, modelInfo, credentialStatus, disabledClients } = runtime(env);
     let lastAutomaticHook = null;
     const server = new McpServer({ name: 'aptly', version: VERSION });
     const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: mode === 'decisions' };
@@ -28,6 +28,7 @@ export function createServer({ env = process.env } = {}) {
         precedence: 'per_call_effective_host_evidence_required', automatic_settings_discovery: false,
         recommendation: { application: 'advisory_only', host_evidence_required: false, constraints: 'caller_declared_pins' },
         model_information: { status: modelInfo.status, refresh: 'explicit_only', account_access_verified: false }, disabled_clients: disabledClients,
+        credential_status: credentialStatus,
         automatic_hook: { status: loadAutomaticHookPolicy(env.APTLY_HOOK_POLICY_PATH).reason, mode: loadAutomaticHookPolicy(env.APTLY_HOOK_POLICY_PATH).policy?.mode ?? 'disabled', host_settings_verified: false, last_result: lastAutomaticHook },
     }));
     server.registerTool('recommend_agent', {

package/dist/src/setup.d.ts

@@ -12,11 +12,25 @@ export interface SetupClientResult {
     status: 'configured' | 'unchanged' | 'removed' | 'skipped' | 'error';
     codes: string[];
     requires_hook_review?: boolean;
+    recovery?: string[];
 }
 export interface SetupResult {
     status: 'complete' | 'partial' | 'skipped';
     clients: SetupClientResult[];
 }
+export declare const configurableEnvironmentKeys: readonly string[];
 export declare function setupHosts(options?: SetupOptions): SetupResult;
 export declare function removeSetup(options?: SetupOptions): SetupResult;
+export declare function setDefaults(options?: SetupOptions): SetupResult;
+export declare function setEnvironment(key: string, value: string, options?: SetupOptions): SetupResult;
+/** Store only the nonsecret source reference; credential values never enter setup. */
+export declare function setCredentialReference(options?: SetupOptions): SetupResult;
+/** Snapshot-only plan. No file writes, credential access, paths or values in diagnostics. */
+export declare function prepareCredentialReference(options: SetupOptions, client: Client): {
+    result: SetupClientResult;
+    check: () => SetupClientResult;
+    commit: () => SetupClientResult;
+};
+/** Only an explicitly selected, receipt-matching standard registration is eligible. */
+export declare function migrateLauncher(options: SetupOptions, dryRun?: boolean): SetupResult;
 export {};

package/dist/src/setup.js

@@ -1,13 +1,28 @@
 import { lstatSync, readFileSync, mkdirSync, chmodSync, openSync, writeFileSync, closeSync, renameSync, unlinkSync, rmdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import { parse } from 'smol-toml';
+import { resolveCatalog } from './catalog.js';
+import { assertPrivateStatePath } from './files.js';
+import { assertWindowsPrivatePath, protectNewWindowsPrivateDirectory, copyWindowsFilePermissions } from './windows-private.js';
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
 const stringify = (value) => JSON.stringify(value, null, 2) + '\n';
 const fail = (code) => { throw new Error(code); };
+function privatePermissions(path, code) {
+    if (process.platform === 'win32') {
+        try {
+            assertWindowsPrivatePath(path);
+        }
+        catch {
+            fail(code);
+        }
+    }
+    else if ((lstatSync(path).mode & 0o077) !== 0)
+        fail(code);
+}
 const checkedDirectory = (path) => { const s = lstatSync(path); if (!s.isDirectory() || s.isSymbolicLink())
     fail('unsafe_directory'); };
 function noSymlinks(path) {
@@ -140,6 +155,85 @@ function removeTomlEnv(text, additions) {
         fail('managed_entry_changed');
     return text;
 }
+export const configurableEnvironmentKeys = Object.freeze(['ROUTER_PROVIDER', 'APTLY_CLAUDE_MODELS', 'APTLY_CODEX_MODELS', 'CLAUDE_MODELS', 'CODEX_MODELS', 'APTLY_MODEL_INFO_PATH']);
+const defaultEnvironment = { ROUTER_PROVIDER: 'decisions', APTLY_CLAUDE_MODELS: '["haiku","sonnet","opus"]', APTLY_CODEX_MODELS: '["gpt-6-luna","gpt-6.1-terra","gpt-6.1-sol"]' };
+function validateEnvironmentValue(key, value) {
+    if (!configurableEnvironmentKeys.includes(key))
+        fail(/KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i.test(key) ? 'environment_secret_key_unsupported' : 'environment_key_unsupported');
+    if (typeof value !== 'string' || !value || Buffer.byteLength(value) > 8192 || /[\x00-\x1f\x7f]/.test(value))
+        fail('environment_invalid_value');
+    if (/\bsk-[A-Za-z0-9_-]{8,}|\bBearer\s+\S+|https?:\/\/[^/\s]+:[^/\s]+@/i.test(value))
+        fail('environment_sensitive_value');
+    if (key === 'ROUTER_PROVIDER' && !['fixture', 'decisions'].includes(value))
+        fail('environment_invalid_value');
+    if (key === 'APTLY_MODEL_INFO_PATH') {
+        try {
+            assertPrivateStatePath(value);
+        }
+        catch {
+            fail('environment_invalid_value');
+        }
+    }
+}
+function editEnvironment(current, edit, client) {
+    const updates = {};
+    if ('defaults' in edit) {
+        for (const [key, value] of Object.entries(defaultEnvironment)) {
+            const alias = key === 'APTLY_CLAUDE_MODELS' ? 'CLAUDE_MODELS' : key === 'APTLY_CODEX_MODELS' ? 'CODEX_MODELS' : null;
+            if (current[key] === undefined && (!alias || current[alias] === undefined))
+                updates[key] = value;
+        }
+    }
+    else if ('credential' in edit) {
+        updates.APTLY_SECRET_BACKEND = 'os';
+        updates.APTLY_SECRET_CLIENT = client;
+    }
+    else if (!('migrate' in edit)) {
+        validateEnvironmentValue(edit.key, edit.value);
+        updates[edit.key] = edit.value;
+    }
+    const effective = { ...current, ...updates };
+    if (effective.ROUTER_PROVIDER !== undefined && !['fixture', 'decisions'].includes(effective.ROUTER_PROVIDER))
+        fail('environment_invalid_value');
+    try {
+        resolveCatalog(effective);
+    }
+    catch {
+        fail('environment_invalid_value');
+    }
+    return Object.fromEntries(Object.entries(updates).filter(([key, value]) => current[key] !== value));
+}
+/** Change only selected single-line scalar env assignments; refuse ambiguous TOML layouts. */
+function updateTomlEnv(text, updates) {
+    const parsed = toml(text), existing = parsed.mcp_servers?.aptly?.env ?? {};
+    const expected = structuredClone(parsed);
+    Object.assign(map(map(map(expected, 'mcp_servers'), 'aptly'), 'env'), updates);
+    const headers = [...text.matchAll(/^\s*\[([^\n]+)\][ \t]*(?:#[^\n]*)?\r?$/gm)];
+    const header = headers.find(h => { try {
+        return toml(h[0] + '\naptly_probe = true\n').mcp_servers?.aptly?.env?.aptly_probe === true;
+    }
+    catch {
+        return false;
+    } });
+    const present = Object.entries(updates).filter(([key]) => existing[key] !== undefined);
+    if (present.length) {
+        if (!header)
+            fail('unsupported_toml_layout');
+        const end = headers.find(h => h.index > header.index)?.index ?? text.length;
+        let body = text.slice(header.index + header[0].length, end);
+        for (const [key, value] of present) {
+            const line = new RegExp('^[ \t]*' + key + '[ \t]*=[^\n]*(?:\n|$)', 'gm');
+            if ([...body.matchAll(line)].length !== 1)
+                fail('unsupported_toml_layout');
+            body = body.replace(line, () => key + ' = ' + q(value) + '\n');
+        }
+        text = text.slice(0, header.index + header[0].length) + body + text.slice(end);
+    }
+    text = addTomlEnv(text, Object.fromEntries(Object.entries(updates).filter(([key]) => existing[key] === undefined)));
+    if (!isDeepStrictEqual(toml(text), expected))
+        fail('unsupported_toml_layout');
+    return text;
+}
 function resolved(options, client) {
     const home = resolve(options.home ?? homedir()), env = options.env ?? process.env;
     const override = client === 'codex' ? env.CODEX_HOME : env.CLAUDE_CONFIG_DIR;
@@ -154,16 +248,34 @@ function ownership(value, client) {
         fail('invalid_ownership');
     return value;
 }
-function prepare(options, client, removing) {
+/** Compatibility restriction only: this does not authenticate arbitrary launcher code. */
+function requireCredentialRuntime(entry, root) {
+    const allowed = [join(root, 'dist', 'src', 'server.js'), join(root, 'src', 'server.ts')];
+    const incompatible = (reason) => { throw Object.assign(new Error('credential_launcher_unverified'), { reason }); };
+    if (entry.command !== process.execPath)
+        incompatible('credential_node_mismatch');
+    if (!Array.isArray(entry.args) || entry.args.length !== 1 || !allowed.includes(entry.args[0]))
+        incompatible('credential_server_mismatch');
+    try {
+        const extension = entry.args[0].endsWith('.ts') ? 'ts' : 'js';
+        const server = read(entry.args[0]).text;
+        const runtime = read(join(dirname(entry.args[0]), 'runtime.' + extension)).text;
+        if (!server?.includes('./runtime.' + extension) || !runtime?.includes('APTLY_SECRET_BACKEND') || !runtime.includes('APTLY_SECRET_CLIENT'))
+            fail('credential_launcher_unverified');
+    }
+    catch {
+        incompatible('credential_runtime_unsupported');
+    }
+}
+function prepare(options, client, removing, edit) {
     const env = options.env ?? process.env, paths = resolved(options, client), { dir, mcpPath, hooksPath, privateDir } = paths;
-    const changes = [], dirs = [];
+    const changes = [], observations = [], dirs = [];
     noSymlinks(dir);
     noSymlinks(privateDir);
     for (const path of [privateDir, join(privateDir, 'state')]) {
         try {
             checkedDirectory(path);
-            if ((lstatSync(path).mode & 0o077) !== 0)
-                fail('private_directory_permissions');
+            privatePermissions(path, 'private_directory_permissions');
         }
         catch (e) {
             if (e.code !== 'ENOENT')
@@ -181,16 +293,17 @@ function prepare(options, client, removing) {
     } })();
     const result = { client, status: 'unchanged', codes: [] };
     if (!hasDir && (options.automatic || removing))
-        return { changes, dirs, result: { client, status: 'skipped', codes: ['host_not_configured'] } };
+        return { changes, observations, dirs, result: { client, status: 'skipped', codes: ['host_not_configured'] } };
     const policyPath = join(privateDir, 'auto-policy.json'), manifestPath = join(privateDir, 'setup-ownership.json'), stateDir = join(privateDir, 'state');
     const snap = (path) => { const source = read(path); return { path, before: source.text, after: source.text, mode: source.mode }; };
     const mcp = snap(mcpPath), hooks = snap(hooksPath), policy = snap(policyPath), manifest = snap(manifestPath);
     for (const privateFile of [policy, manifest])
-        if (privateFile.before !== null && (privateFile.mode & 0o077) !== 0)
-            fail('private_file_permissions');
+        if (privateFile.before !== null)
+            privatePermissions(privateFile.path, 'private_file_permissions');
+    observations.push(mcp, hooks, policy, manifest);
     const oldOwner = manifest.before === null ? undefined : ownership(json(manifest.before), client);
     if (removing && !oldOwner)
-        return { changes, dirs, result: { client, status: 'skipped', codes: ['no_owned_setup'] } };
+        return { changes, observations, dirs, result: { client, status: 'skipped', codes: ['no_owned_setup'] } };
     const hookValue = hook(client), hooksObject = json(hooks.before), entries = hooksArray(hooksObject);
     const config = client === 'codex' ? toml(mcp.before ?? '') : json(mcp.before), servers = map(config, client === 'codex' ? 'mcp_servers' : 'mcpServers');
     if (removing) {
@@ -245,19 +358,24 @@ function prepare(options, client, removing) {
         const root = resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..', ...(import.meta.url.includes('/dist/src/') ? ['..'] : [])));
         const additions = { APTLY_HOOK_POLICY_PATH: policyPath, ROUTER_LEDGER_PATH: join(stateDir, 'ledger.json') };
         let created = false, tomlBlock;
+        if (edit && 'migrate' in edit) {
+            if (!oldOwner?.mcp_created || !object(servers.aptly) || !isDeepStrictEqual(servers.aptly, oldOwner.mcp))
+                fail('launcher_migration_not_owned');
+            const entry = servers.aptly;
+            if (typeof entry.command !== 'string' || !isAbsolute(entry.command) || !['node', 'node.exe'].includes(basename(entry.command).toLowerCase()) || !Array.isArray(entry.args) || entry.args.length !== 1 || typeof entry.args[0] !== 'string' || !isAbsolute(entry.args[0]) || !/(?:^|[\\/])(?:dist[\\/]src[\\/]server\.js|src[\\/]server\.ts)$/.test(entry.args[0]))
+                fail('launcher_migration_not_standard');
+            if (!entries.some(entry => isDeepStrictEqual(entry, oldOwner.hook)) || !isDeepStrictEqual(json(policy.before), oldOwner.policy))
+                fail('managed_entry_changed');
+        }
         if (servers.aptly === undefined) {
             created = true;
-            servers.aptly = { ...(client === 'claude' ? { type: 'stdio' } : {}), command: process.execPath, args: [join(root, 'dist', 'src', 'server.js')], ...(client === 'codex' ? { env_vars: ['OPENAI_API_KEY'] } : {}), env: { ROUTER_PROVIDER: env.ROUTER_PROVIDER === 'fixture' ? 'fixture' : 'decisions', ...additions } };
-            if (client === 'codex') {
-                tomlBlock = newTomlBlock(servers.aptly);
-                mcp.after = (mcp.before ?? '') + ((mcp.before ?? '').endsWith('\n') || !mcp.before ? '\n' : '\n\n') + tomlBlock;
-            }
-            else
-                mcp.after = stringify(config);
+            servers.aptly = { ...(client === 'claude' ? { type: 'stdio' } : {}), command: process.execPath, args: [join(root, 'dist', 'src', 'server.js')], ...(client === 'codex' ? { env_vars: ['OPENAI_API_KEY'] } : {}), env: { ROUTER_PROVIDER: edit && 'defaults' in edit ? 'decisions' : env.ROUTER_PROVIDER === 'fixture' ? 'fixture' : 'decisions', ...additions } };
         }
         else {
             if (!object(servers.aptly))
                 fail('mcp_entry_conflict');
+            if (edit && oldOwner?.mcp_created && !isDeepStrictEqual(servers.aptly, oldOwner.mcp))
+                fail('managed_mcp_changed');
             const currentEnv = map(servers.aptly, 'env');
             if (currentEnv.APTLY_HOOK_POLICY_PATH !== undefined && currentEnv.APTLY_HOOK_POLICY_PATH !== policyPath)
                 fail('mcp_environment_conflict');
@@ -265,13 +383,33 @@ function prepare(options, client, removing) {
             Object.assign(currentEnv, missing);
             mcp.after = client === 'codex' ? addTomlEnv(mcp.before ?? '', missing) : stringify(config);
         }
+        if (edit && 'migrate' in edit) {
+            servers.aptly.command = process.execPath;
+            servers.aptly.args = [join(root, 'dist', 'src', 'server.js')];
+        }
+        if (edit && ('credential' in edit || 'migrate' in edit))
+            requireCredentialRuntime(servers.aptly, root);
+        const currentEnv = map(servers.aptly, 'env');
+        const updates = edit ? editEnvironment(currentEnv, edit, client) : {};
+        Object.assign(currentEnv, updates);
+        if (created) {
+            if (client === 'codex') {
+                tomlBlock = newTomlBlock(servers.aptly);
+                mcp.after = (mcp.before ?? '') + ((mcp.before ?? '').endsWith('\n') || !mcp.before ? '\n' : '\n\n') + tomlBlock;
+            }
+            else
+                mcp.after = stringify(config);
+        }
+        else if (edit)
+            mcp.after = client === 'codex' ? updateTomlEnv(mcp.after, updates) : stringify(config);
         const existingRoute = entries.filter(routeHook);
         if (existingRoute.some(entry => !isDeepStrictEqual(entry, hookValue)))
             fail('existing_routing_hook_conflict');
         if (existingRoute.length === 0)
             entries.push(hookValue);
-        hooks.after = stringify(hooksObject);
-        const policyValue = { schema_version: 1, kind: 'aptly-auto-hook', mode: options.mode ?? 'defaults', issuer: 'operator_installation', enabled: true, state_directory: stateDir };
+        hooks.after = edit && 'migrate' in edit ? hooks.before : stringify(hooksObject);
+        const preservedMode = edit && policy.before !== null ? json(policy.before).mode : undefined;
+        const policyValue = { schema_version: 1, kind: 'aptly-auto-hook', mode: options.mode ?? (['defaults', 'advisory'].includes(preservedMode) ? preservedMode : 'defaults'), issuer: 'operator_installation', enabled: true, state_directory: stateDir };
         if (policy.before !== null) {
             const p = json(policy.before);
             if (!isDeepStrictEqual(p, policyValue))
@@ -286,6 +424,36 @@ function prepare(options, client, removing) {
         if (existingRoute.length && !oldOwner)
             fail('existing_hook_not_owned');
         const owner = oldOwner ?? { schema_version: 1, kind: 'aptly-setup-ownership', client, hook: hookValue, policy: policyValue, policy_created: policy.before === null, mcp_created: created, ...(created ? { mcp: servers.aptly } : {}), env_added: envAdded, ...(tomlBlock ? { toml_block: tomlBlock } : {}) };
+        if (edit && oldOwner) {
+            if (oldOwner.mcp_created) {
+                owner.mcp = structuredClone(servers.aptly);
+                if (client === 'codex') {
+                    const oldBlock = oldOwner.toml_block;
+                    if (!oldBlock || !(mcp.before ?? '').includes(oldBlock))
+                        fail('managed_mcp_changed');
+                    const nextBlock = newTomlBlock(servers.aptly);
+                    const rendered = (mcp.before ?? '').replace(oldBlock, nextBlock);
+                    if (!isDeepStrictEqual(toml(rendered), config))
+                        fail('managed_mcp_changed');
+                    mcp.after = rendered;
+                    owner.toml_block = nextBlock;
+                }
+            }
+            else {
+                const prior = client === 'codex' ? toml(mcp.before ?? '') : json(mcp.before);
+                const priorEnv = prior[client === 'codex' ? 'mcp_servers' : 'mcpServers']?.aptly?.env ?? {};
+                for (const [key, value] of Object.entries(updates))
+                    if (Object.hasOwn(owner.env_added, key) || priorEnv[key] === undefined)
+                        owner.env_added[key] = value;
+            }
+        }
+        else if (edit && !created) {
+            const prior = client === 'codex' ? toml(mcp.before ?? '') : json(mcp.before);
+            const priorEnv = prior[client === 'codex' ? 'mcp_servers' : 'mcpServers']?.aptly?.env ?? {};
+            for (const [key, value] of Object.entries(updates))
+                if (priorEnv[key] === undefined)
+                    owner.env_added[key] = value;
+        }
         manifest.after = stringify(owner);
         if (client === 'codex')
             result.requires_hook_review = true;
@@ -300,7 +468,7 @@ function prepare(options, client, removing) {
             changes.push(snapshot);
     if (!removing && changes.length)
         result.status = 'configured';
-    return { changes, dirs, result };
+    return { changes, observations, dirs, result };
 }
 /** Secure sibling staging is short-lived and never a backup; original settings stay in memory. */
 function replace(snapshot, forward) {
@@ -316,13 +484,21 @@ function replace(snapshot, forward) {
     let fd;
     try {
         fd = openSync(stage, 'wx', 0o600);
+        if (process.platform === 'win32' && expected !== null) {
+            try {
+                copyWindowsFilePermissions(snapshot.path, stage);
+            }
+            catch {
+                fail('private_file_permissions');
+            }
+        }
         writeFileSync(fd, next);
         closeSync(fd);
         fd = undefined;
         if (read(snapshot.path).text !== expected)
             fail('concurrent_configuration_change');
         renameSync(stage, snapshot.path);
-        if (snapshot.mode !== 0o600)
+        if (process.platform !== 'win32' && snapshot.mode !== 0o600)
             chmodSync(snapshot.path, snapshot.mode);
     }
     finally {
@@ -337,28 +513,31 @@ function replace(snapshot, forward) {
         }
     }
 }
-function execute(options, removing) {
+function execute(options, removing, edit, captured) {
     const clients = [...new Set(options.clients ?? ['codex', 'claude'])];
     if (clients.some(client => client !== 'codex' && client !== 'claude'))
         return { status: 'partial', clients: [] };
     const env = options.env ?? process.env;
     if (!removing && options.automatic && (env.APTLY_SKIP_SETUP === '1' || !!env.CI))
         return { status: 'skipped', clients: clients.map(client => ({ client, status: 'skipped', codes: [env.APTLY_SKIP_SETUP === '1' ? 'setup_disabled' : 'ci_environment'] })) };
-    const prepared = clients.map(client => {
+    const prepared = captured ?? clients.map(client => {
         try {
-            return prepare(options, client, removing);
+            return prepare(options, client, removing, edit);
         }
         catch (e) {
-            return { changes: [], dirs: [], result: { client, status: 'error', codes: [safeCode(e)] } };
+            return { changes: [], observations: [], dirs: [], result: { client, status: 'error', codes: [safeCode(e)] } };
         }
     });
     const results = prepared.map(plan => plan.result);
+    if (edit && results.some(result => result.status === 'error'))
+        return { status: 'partial', clients: results.map(result => result.status === 'error' ? result : { ...result, status: 'skipped', codes: ['other_host_validation_failed'] }) };
     // Each host is independent; prepare every host before committing any host.
     for (const plan of prepared) {
         if (!plan.changes.length)
             continue;
         const written = [], madeDirs = [];
         try {
+            validateObservations(plan);
             for (const path of plan.dirs) {
                 noSymlinks(path);
                 try {
@@ -369,16 +548,24 @@ function execute(options, removing) {
                         throw e;
                     mkdirSync(path, { mode: 0o700 });
                     madeDirs.push(path);
+                    if (process.platform === 'win32') {
+                        try {
+                            protectNewWindowsPrivateDirectory(path);
+                        }
+                        catch {
+                            fail('private_directory_permissions');
+                        }
+                    }
                 }
-                if (path.endsWith('/aptly') || path.endsWith('/aptly/state')) {
-                    if ((lstatSync(path).mode & 0o077) !== 0)
-                        fail('private_directory_permissions');
-                }
+                if (basename(path) === 'aptly' || (basename(path) === 'state' && basename(dirname(path)) === 'aptly'))
+                    privatePermissions(path, 'private_directory_permissions');
             }
             for (const snapshot of plan.changes) {
+                validateObservations(plan, written);
                 replace(snapshot, true);
                 written.push(snapshot);
             }
+            validateObservations(plan, written);
         }
         catch (e) {
             let rollbackConflict = false;
@@ -402,7 +589,88 @@ function execute(options, removing) {
     }
     return { status: results.some(result => result.status === 'error') ? 'partial' : results.every(result => result.status === 'skipped') ? 'skipped' : 'complete', clients: results };
 }
-const codes = new Set(['unsafe_directory', 'unsafe_symlink', 'unsafe_configuration_file', 'invalid_json', 'invalid_json_object', 'configuration_shape_conflict', 'hook_shape_conflict', 'invalid_toml', 'unsupported_toml_layout', 'relative_configuration_directory', 'invalid_ownership', 'managed_hook_changed', 'managed_mcp_changed', 'managed_entry_changed', 'managed_policy_changed', 'mcp_entry_conflict', 'mcp_environment_conflict', 'existing_routing_hook_conflict', 'policy_conflict', 'existing_hook_not_owned', 'concurrent_configuration_change', 'private_directory_permissions', 'private_file_permissions']);
+const codes = new Set(['launcher_migration_not_owned', 'launcher_migration_not_standard', 'credential_launcher_unverified', 'environment_invalid_value', 'environment_sensitive_value', 'environment_key_unsupported', 'environment_secret_key_unsupported', 'unsafe_directory', 'unsafe_symlink', 'unsafe_configuration_file', 'invalid_json', 'invalid_json_object', 'configuration_shape_conflict', 'hook_shape_conflict', 'invalid_toml', 'unsupported_toml_layout', 'relative_configuration_directory', 'invalid_ownership', 'managed_hook_changed', 'managed_mcp_changed', 'managed_entry_changed', 'managed_policy_changed', 'mcp_entry_conflict', 'mcp_environment_conflict', 'existing_routing_hook_conflict', 'policy_conflict', 'existing_hook_not_owned', 'concurrent_configuration_change', 'private_directory_permissions', 'private_file_permissions']);
 function safeCode(error) { return error instanceof Error && codes.has(error.message) ? error.message : 'configuration_io_error'; }
 export function setupHosts(options = {}) { return execute(options, false); }
 export function removeSetup(options = {}) { return execute(options, true); }
+export function setDefaults(options = {}) { return execute(options, false, { defaults: true }); }
+export function setEnvironment(key, value, options = {}) {
+    try {
+        validateEnvironmentValue(key, value);
+    }
+    catch (error) {
+        return { status: 'partial', clients: (options.clients ?? ['codex', 'claude']).map(client => ({ client, status: 'error', codes: [safeCode(error)] })) };
+    }
+    return execute(options, false, { key, value });
+}
+/** Store only the nonsecret source reference; credential values never enter setup. */
+export function setCredentialReference(options = {}) { return execute(options, false, { credential: true }); }
+/** Include unchanged files: a no-op reference update must still detect prompt-time edits. */
+function validateObservations(plan, written = []) {
+    for (const snapshot of plan.observations) {
+        const current = read(snapshot.path);
+        const expected = written.includes(snapshot) ? snapshot.after : snapshot.before;
+        if (current.text !== expected || (process.platform !== 'win32' && expected !== null && current.mode !== snapshot.mode))
+            fail('concurrent_configuration_change');
+    }
+}
+function recovery(client) {
+    return [`aptly set env OPENAI_API_KEY --client ${client} --check`,
+        `aptly setup --client ${client} --migrate-launcher --dry-run`,
+        `aptly setup --client ${client} --migrate-launcher`,
+        `aptly set env OPENAI_API_KEY --client ${client}`];
+}
+/** Snapshot-only plan. No file writes, credential access, paths or values in diagnostics. */
+export function prepareCredentialReference(options, client) {
+    let plan;
+    let result;
+    try {
+        plan = prepare({ ...options, clients: [client] }, client, false, { credential: true });
+        result = { client, status: 'unchanged', codes: ['credential_preflight_ok'] };
+    }
+    catch (error) {
+        const reason = error?.reason;
+        const reasons = ['credential_node_mismatch', 'credential_server_mismatch', 'credential_runtime_unsupported'];
+        const migration = migrateLauncher({ ...options, clients: [client] }, true);
+        const canMigrate = migration.status === 'complete';
+        result = { client, status: 'error', codes: [safeCode(error), ...(reason && reasons.includes(reason) ? [reason] : []), ...(canMigrate ? ['launcher_migration_available'] : [])],
+            recovery: canMigrate ? recovery(client) : [`aptly set env OPENAI_API_KEY --client ${client} --check`, 'Keep custom or modified launchers unchanged. Review the host registration locally; use its secure credential environment or a separately reviewed standard registration.'] };
+    }
+    const check = () => {
+        if (!plan)
+            return result;
+        try {
+            validateObservations(plan);
+            // Recheck runtime support, symlinks, private permissions and policy before storage.
+            prepare({ ...options, clients: [client] }, client, false, { credential: true });
+            return result;
+        }
+        catch (error) {
+            return { client, status: 'error', codes: [safeCode(error)], recovery: recovery(client) };
+        }
+    };
+    return { result, check, commit: () => {
+            const checked = check();
+            if (checked.status === 'error' || !plan)
+                return checked;
+            return execute({ ...options, clients: [client] }, false, { credential: true }, [plan]).clients[0];
+        } };
+}
+/** Only an explicitly selected, receipt-matching standard registration is eligible. */
+export function migrateLauncher(options, dryRun = false) {
+    const client = options.clients?.[0];
+    if (options.clients?.length !== 1 || !client || !['codex', 'claude'].includes(client) || options.automatic || options.mode)
+        return { status: 'partial', clients: [] };
+    try {
+        const plan = prepare(options, client, false, { migrate: true });
+        if (dryRun)
+            return { status: 'complete', clients: [{ client, status: 'unchanged', codes: [plan.changes.length ? 'launcher_migration_available' : 'launcher_current'], requires_hook_review: client === 'codex' }] };
+        const result = execute(options, false, { migrate: true }, [plan]);
+        if (result.status === 'complete')
+            result.clients[0].codes.push('launcher_migrated', 'mcp_restart_required');
+        return result;
+    }
+    catch (error) {
+        return { status: 'partial', clients: [{ client, status: 'error', codes: [safeCode(error)] }] };
+    }
+}

package/dist/src/types.d.ts

@@ -71,6 +71,9 @@ export interface ProviderAnswer {
     confidence?: number;
     usage?: unknown;
 }
-export type RoutingProvider = (args: ProviderArguments) => Promise<ProviderAnswer>;
+export type RoutingProvider = ((args: ProviderArguments) => Promise<ProviderAnswer>) & {
+    /** Synchronous local readiness check only; must not initiate transport. */
+    preflight?: () => void;
+};
 export declare function isRecord(value: unknown): value is UnknownRecord;
 export declare function errorCode(error: unknown): string | undefined;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.2";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.2';

package/dist/src/windows-powershell.d.ts

@@ -0,0 +1,2 @@
+/** Use the operator's Windows system directory, never cwd or PATH lookup. */
+export declare function windowsPowerShellPath(env?: NodeJS.ProcessEnv): string;

package/dist/src/windows-powershell.js

@@ -0,0 +1,11 @@
+import { win32 } from 'node:path';
+/** Use the operator's Windows system directory, never cwd or PATH lookup. */
+export function windowsPowerShellPath(env = process.env) {
+    const root = env.SystemRoot ?? 'C:\\Windows';
+    // Reject drive-relative, UNC/device, traversal and control-character roots.
+    if (!/^[A-Za-z]:[\\/]/.test(root) || /[\x00-\x1f\x7f]/.test(root) ||
+        root.slice(2).includes(':') || root.split(/[\\/]/).some(part => part === '.' || part === '..')) {
+        throw new Error('windows_system_directory_invalid');
+    }
+    return win32.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+}

package/dist/src/windows-private.d.ts

@@ -0,0 +1,11 @@
+type Runner = (executable: string, args: readonly string[], input: string) => string;
+interface WindowsPrivateOptions {
+    execute?: Runner;
+}
+/** Preserve the existing file DACL, including inheritance protection, before writing stage content. */
+export declare function copyWindowsFilePermissions(source: string, target: string, options?: WindowsPrivateOptions): void;
+/** Existing paths are inspected, never repaired or granted new permissions. */
+export declare function assertWindowsPrivatePath(path: string, options?: WindowsPrivateOptions): void;
+/** Only call immediately after this process exclusively created the directory. */
+export declare function protectNewWindowsPrivateDirectory(path: string, options?: WindowsPrivateOptions): void;
+export {};