aptly 0.1.1 → 0.1.3

package/dist/src/ledger-lock.js

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, linkSync, lstatSync, openSync, unlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { assertNoRedirectedAncestors, assertPrivateStatePath } from './files.js';
+const require = createRequire(import.meta.url);
+const applicationId = 0x4150544c;
+const userVersion = 1;
+function fail(code) { throw Object.assign(new Error(code), { code }); }
+const codeOf = (error) => error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+const sqliteCode = (error) => {
+    if (!error || typeof error !== 'object' || !('errcode' in error) || typeof error.errcode !== 'number')
+        return;
+    return error.errcode & 0xff;
+};
+function identity(path, directory = false) {
+    const stat = lstatSync(path, { bigint: true });
+    if ((directory ? !stat.isDirectory() : !stat.isFile()) || stat.isSymbolicLink() || stat.ino === 0n)
+        fail('ledger_error');
+    if (process.platform !== 'win32' && ((stat.mode & 63n) !== 0n || (process.getuid && stat.uid !== BigInt(process.getuid()))))
+        fail('ledger_error');
+    return { dev: stat.dev, ino: stat.ino, uid: stat.uid, mode: stat.mode };
+}
+function same(actual, expected) {
+    return actual.dev === expected.dev && actual.ino === expected.ino && actual.uid === expected.uid && actual.mode === expected.mode;
+}
+function close(connection, transaction) {
+    if (!connection)
+        return true;
+    let success = true;
+    if (transaction) {
+        try {
+            connection.exec('ROLLBACK');
+        }
+        catch {
+            success = false;
+        }
+    }
+    try {
+        connection.close();
+    }
+    catch {
+        success = false;
+    }
+    return success;
+}
+/**
+ * Publish a completely initialized gate with an atomic no-replace hard link.
+ * Existing empty/unknown locks belong to the legacy protocol and are untouched.
+ * Never open an old stage alias: a crash after link may leave it sharing the gate
+ * inode, and an ordinary fs close could cancel this process's SQLite POSIX lock.
+ */
+function initialize(path, Database) {
+    const stage = join(dirname(path), `.aptly-lock-init-${randomUUID()}`);
+    let created = false, connection, transaction = false;
+    try {
+        const fd = openSync(stage, 'wx', 0o600);
+        created = true;
+        closeSync(fd);
+        assertPrivateStatePath(stage);
+        identity(stage);
+        connection = new Database(stage);
+        connection.exec('PRAGMA journal_mode=DELETE; PRAGMA busy_timeout=0; BEGIN IMMEDIATE');
+        transaction = true;
+        connection.exec(`PRAGMA application_id=${applicationId}; PRAGMA user_version=${userVersion}; COMMIT`);
+        transaction = false;
+        connection.close();
+        connection = undefined;
+        try {
+            linkSync(stage, path);
+        }
+        catch (error) {
+            if (codeOf(error) !== 'EEXIST')
+                throw error;
+        }
+    }
+    finally {
+        close(connection, transaction);
+        // Only our exclusive, unique stage is removed; the canonical gate persists.
+        if (created)
+            unlinkSync(stage);
+    }
+}
+/** Local, hard-link-capable filesystems only; no PID or stale-age recovery. */
+export function acquireLedgerLock(ledgerPath) {
+    let connection, transaction = false;
+    try {
+        const path = `${ledgerPath}.lock`;
+        assertPrivateStatePath(ledgerPath);
+        assertPrivateStatePath(path);
+        const parent = identity(dirname(path), true);
+        // Load only for persistent ledgers. Fixture-only callers need no SQLite.
+        const { DatabaseSync } = require('node:sqlite');
+        try {
+            lstatSync(path);
+        }
+        catch (error) {
+            if (codeOf(error) !== 'ENOENT')
+                throw error;
+            initialize(path, DatabaseSync);
+        }
+        assertPrivateStatePath(path);
+        const before = identity(path);
+        // Do not let SQLite initialize an existing empty legacy ownership marker.
+        if (lstatSync(path).size < 512)
+            fail('ledger_locked');
+        connection = new DatabaseSync(path);
+        const assertIdentity = () => {
+            // ACLs are checked before opening; while held use only path metadata.
+            assertNoRedirectedAncestors(dirname(path));
+            if (!same(identity(dirname(path), true), parent) || !same(identity(path), before))
+                fail('ledger_error');
+        };
+        assertIdentity();
+        connection.exec('PRAGMA busy_timeout=0; BEGIN IMMEDIATE');
+        transaction = true;
+        assertIdentity();
+        const app = connection.prepare('PRAGMA application_id').get();
+        const version = connection.prepare('PRAGMA user_version').get();
+        const journal = connection.prepare('PRAGMA journal_mode').get();
+        if (app?.application_id !== applicationId || version?.user_version !== userVersion || journal?.journal_mode !== 'delete')
+            fail('ledger_locked');
+        assertIdentity();
+        const owned = connection;
+        let released = false;
+        return {
+            assertHeld() {
+                if (released)
+                    fail('ledger_error');
+                try {
+                    assertIdentity();
+                }
+                catch {
+                    fail('ledger_error');
+                }
+            },
+            release() {
+                if (released)
+                    return;
+                released = true;
+                if (!close(owned, true))
+                    fail('ledger_error');
+            },
+        };
+    }
+    catch (error) {
+        close(connection, transaction);
+        const code = codeOf(error), sqlite = sqliteCode(error);
+        if (code === 'ledger_locked' || sqlite === 5 || sqlite === 6 || sqlite === 11 || sqlite === 26)
+            fail('ledger_locked');
+        fail('ledger_error');
+    }
+}

package/dist/src/provider.js

@@ -9,7 +9,13 @@ export function decisionsProvider({ key, fetchImpl = fetch, descriptions = {} }
         preflight();
         const payload = {
             model: 'gpt-6-luna',
-            input: JSON.stringify({ task: input.task, client: input.client }),
+            // Keep the wire boundary explicit even for internal callers that bypass
+            // Router validation. Unrelated task/native metadata is never serialized.
+            input: JSON.stringify({ task: {
+                    summary: input.task.summary,
+                    operation: input.task.operation,
+                    context_sufficient: input.task.context_sufficient,
+                }, client: input.client }),
             questions: [{ type: 'choice', name: 'profile', instructions, choices: [
                         ...profiles.map(p => ({ value: p.id, description: descriptions[p.id] ?? `${p.model}${p.reasoning_effort ? ' / effort ' + p.reasoning_effort : ''}. Select only for an appropriate task; capabilities not supplied.` })),
                         { value: 'keep_current', description: 'Preserve the existing selection; no confident supported choice.' },

package/dist/src/setup.d.ts

@@ -12,6 +12,7 @@ export interface SetupClientResult {
     status: 'configured' | 'unchanged' | 'removed' | 'skipped' | 'error';
     codes: string[];
     requires_hook_review?: boolean;
+    recovery?: string[];
 }
 export interface SetupResult {
     status: 'complete' | 'partial' | 'skipped';
@@ -24,4 +25,12 @@ 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;
+};
+/** Preserved standard registrations require a separate explicit opt-in; ownership stays unchanged. */
+export declare function migrateLauncher(options: SetupOptions, dryRun?: boolean, includeExisting?: boolean): SetupResult;
 export {};

package/dist/src/setup.js

@@ -188,7 +188,7 @@ function editEnvironment(current, edit, client) {
         updates.APTLY_SECRET_BACKEND = 'os';
         updates.APTLY_SECRET_CLIENT = client;
     }
-    else {
+    else if (!('migrate' in edit)) {
         validateEnvironmentValue(edit.key, edit.value);
         updates[edit.key] = edit.value;
     }
@@ -234,6 +234,34 @@ function updateTomlEnv(text, updates) {
         fail('unsupported_toml_layout');
     return text;
 }
+/** Replace only unambiguous single-line launcher assignments in an existing table. */
+function updateTomlLauncher(text, entry) {
+    const original = toml(text), expected = structuredClone(original);
+    expected.mcp_servers.aptly.command = entry.command;
+    expected.mcp_servers.aptly.args = entry.args;
+    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?.aptly_probe === true;
+    }
+    catch {
+        return false;
+    } });
+    if (!header)
+        fail('unsupported_toml_layout');
+    const start = header.index + header[0].length, end = headers.find(h => h.index > header.index)?.index ?? text.length;
+    let body = text.slice(start, end);
+    for (const key of ['command', 'args']) {
+        const assignment = new RegExp('^[ \\t]*' + key + '[ \\t]*=[^\\n]*(?:\\n|$)', 'gm');
+        const matches = [...body.matchAll(assignment)];
+        if (matches.length !== 1 || !isDeepStrictEqual(toml(matches[0][0])[key], original.mcp_servers.aptly[key]))
+            fail('unsupported_toml_layout');
+        body = body.replace(assignment, () => key + ' = ' + JSON.stringify(entry[key]) + (matches[0][0].endsWith('\r\n') ? '\r\n' : matches[0][0].endsWith('\n') ? '\n' : ''));
+    }
+    const rendered = text.slice(0, start) + body + text.slice(end);
+    if (!isDeepStrictEqual(toml(rendered), expected))
+        fail('unsupported_toml_layout');
+    return rendered;
+}
 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;
@@ -251,8 +279,11 @@ function ownership(value, client) {
 /** 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')];
-    if (entry.command !== process.execPath || !Array.isArray(entry.args) || entry.args.length !== 1 || !allowed.includes(entry.args[0]))
-        fail('credential_launcher_unverified');
+    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;
@@ -261,12 +292,12 @@ function requireCredentialRuntime(entry, root) {
             fail('credential_launcher_unverified');
     }
     catch {
-        fail('credential_launcher_unverified');
+        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')]) {
@@ -290,16 +321,17 @@ function prepare(options, client, removing, edit) {
     } })();
     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)
             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) {
@@ -354,6 +386,18 @@ function prepare(options, client, removing, edit) {
         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 || !object(servers.aptly) || (oldOwner.mcp_created ? !isDeepStrictEqual(servers.aptly, oldOwner.mcp) : !edit.includeExisting))
+                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');
+            for (const [key, value] of Object.entries(oldOwner.env_added))
+                if (entry.env?.[key] !== value)
+                    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: edit && 'defaults' in edit ? 'decisions' : env.ROUTER_PROVIDER === 'fixture' ? 'fixture' : 'decisions', ...additions } };
@@ -370,7 +414,11 @@ function prepare(options, client, removing, edit) {
             Object.assign(currentEnv, missing);
             mcp.after = client === 'codex' ? addTomlEnv(mcp.before ?? '', missing) : stringify(config);
         }
-        if (edit && 'credential' in edit)
+        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) : {};
@@ -383,14 +431,17 @@ function prepare(options, client, removing, edit) {
             else
                 mcp.after = stringify(config);
         }
-        else if (edit)
+        else if (edit) {
             mcp.after = client === 'codex' ? updateTomlEnv(mcp.after, updates) : stringify(config);
+            if (client === 'codex' && 'migrate' in edit && !oldOwner?.mcp_created)
+                mcp.after = updateTomlLauncher(mcp.after, servers.aptly);
+        }
         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);
+        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) {
@@ -451,7 +502,7 @@ function prepare(options, client, removing, edit) {
             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) {
@@ -496,19 +547,19 @@ function replace(snapshot, forward) {
         }
     }
 }
-function execute(options, removing, edit) {
+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, 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);
@@ -520,6 +571,7 @@ function execute(options, removing, edit) {
             continue;
         const written = [], madeDirs = [];
         try {
+            validateObservations(plan);
             for (const path of plan.dirs) {
                 noSymlinks(path);
                 try {
@@ -543,9 +595,11 @@ function execute(options, removing, edit) {
                     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;
@@ -569,7 +623,7 @@ function execute(options, removing, edit) {
     }
     return { status: results.some(result => result.status === 'error') ? 'partial' : results.every(result => result.status === 'skipped') ? 'skipped' : 'complete', clients: results };
 }
-const codes = new Set(['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']);
+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); }
@@ -585,3 +639,73 @@ export function setEnvironment(key, value, options = {}) {
 }
 /** 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];
+        } };
+}
+/** Preserved standard registrations require a separate explicit opt-in; ownership stays unchanged. */
+export function migrateLauncher(options, dryRun = false, includeExisting = 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 edit = { migrate: true, includeExisting };
+        const plan = prepare(options, client, false, edit);
+        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, edit, [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/update-notifier.d.ts

@@ -0,0 +1,14 @@
+export interface UpdateNotificationOptions {
+    command: string;
+    args: readonly string[];
+    env: NodeJS.ProcessEnv;
+    stderrIsTTY: boolean;
+    stdoutIsTTY?: boolean;
+    stdinIsTTY: boolean;
+    currentVersion: string;
+    cachePath?: string;
+    fetch?: typeof globalThis.fetch;
+    now?: number;
+}
+/** Returns one stderr hint; never prints, reads credentials, or changes installed code. */
+export declare function updateNotification(options: UpdateNotificationOptions): Promise<string | null>;

package/dist/src/update-notifier.js

@@ -0,0 +1,179 @@
+// Optional interactive CLI hint only. Never used by MCP, routing, or provider code.
+import { mkdirSync, lstatSync, openSync, closeSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { dirname, join, isAbsolute, parse } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { assertNoRedirectedAncestors, assertPrivateStatePath, readRegularFile } from './files.js';
+import { protectNewWindowsPrivateDirectory } from './windows-private.js';
+const registry = 'https://registry.npmjs.org/aptly/latest';
+const ttl = 24 * 60 * 60 * 1000, cooldown = 60 * 60 * 1000, maximumBody = 16 * 1024, timeout = 800;
+function version(value) {
+    if (typeof value !== 'string' || value.length > 64 || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value))
+        return null;
+    const parts = value.split('.').map(Number);
+    return parts.every(Number.isSafeInteger) ? parts : null;
+}
+function newer(candidate, current) {
+    const a = version(candidate), b = version(current);
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+function eligible(o) {
+    return o.stdinIsTTY && o.stderrIsTTY && o.stdoutIsTTY !== false && !o.env.CI && o.env.APTLY_NO_UPDATE_NOTIFIER !== '1' && !!version(o.currentVersion) &&
+        ['help', '--help', '-h', '--version', 'config', 'setup', 'remove', 'set', 'report'].includes(o.command) && !o.args.includes('--automatic');
+}
+function directory(path) {
+    if (!isAbsolute(path))
+        throw Error('cache_path');
+    const parent = dirname(path);
+    if (parent !== path) {
+        try {
+            assertNoRedirectedAncestors(parent);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            directory(parent);
+        }
+    }
+    let created = false;
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        created = true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    assertNoRedirectedAncestors(path);
+    if (!lstatSync(path).isDirectory())
+        throw Error('cache_path');
+    if (created && process.platform === 'win32')
+        protectNewWindowsPrivateDirectory(path);
+}
+function readCache(path, now) {
+    assertPrivateStatePath(path);
+    try {
+        const c = JSON.parse(readRegularFile(path, { privateFile: true, maxBytes: 1024 }).toString('utf8'));
+        if (!c || Array.isArray(c) || Object.keys(c).sort().join(',') !== 'checked_at,failed,latest,schema_version' || c.schema_version !== 1 ||
+            !Number.isSafeInteger(c.checked_at) || c.checked_at < 0 || c.checked_at > now || typeof c.failed !== 'boolean' ||
+            (c.latest !== null && !version(c.latest)) || (!c.failed && c.latest === null))
+            return null;
+        return c;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+function writeCache(path, c) {
+    let stage;
+    try {
+        assertPrivateStatePath(path);
+        stage = join(dirname(path), '.aptly-update-' + randomUUID());
+        const fd = openSync(stage, 'wx', 0o600);
+        try {
+            writeFileSync(fd, JSON.stringify(c) + '\n');
+        }
+        finally {
+            closeSync(fd);
+        }
+        assertPrivateStatePath(stage);
+        assertPrivateStatePath(path);
+        renameSync(stage, path);
+        stage = undefined;
+    }
+    finally {
+        if (stage)
+            try {
+                unlinkSync(stage);
+            }
+            catch { /* Best-effort cleanup of our stage only. */ }
+    }
+}
+async function latestStable(fetcher) {
+    const controller = new AbortController();
+    let timer;
+    let reader;
+    const work = async () => {
+        const response = await fetcher(registry, { signal: controller.signal, redirect: 'error', credentials: 'omit', headers: { accept: 'application/json' } });
+        if (!response.ok || !response.body)
+            throw Error('registry_response');
+        const size = response.headers.get('content-length');
+        if (size !== null && (!/^\d+$/.test(size) || Number(size) > maximumBody))
+            throw Error('registry_size');
+        reader = response.body.getReader();
+        let total = 0;
+        const chunks = [];
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            total += chunk.value.byteLength;
+            if (total > maximumBody)
+                throw Error('registry_size');
+            chunks.push(chunk.value);
+        }
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        const metadata = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (!metadata || metadata.name !== 'aptly' || !version(metadata.version))
+            throw Error('registry_metadata');
+        return metadata.version;
+    };
+    try {
+        return await Promise.race([work(), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(Error('registry_timeout')); }, timeout); })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        controller.abort();
+        if (reader)
+            void reader.cancel().catch(() => { });
+    }
+}
+/** Returns one stderr hint; never prints, reads credentials, or changes installed code. */
+export async function updateNotification(options) {
+    if (!eligible(options))
+        return null;
+    const now = options.now ?? Date.now();
+    if (!Number.isSafeInteger(now) || now < 0)
+        return null;
+    const path = options.cachePath ?? join(homedir(), '.cache', 'aptly', 'update-check.json');
+    let cached;
+    try {
+        if (!isAbsolute(path) || parse(path).root === path)
+            return null;
+        directory(dirname(path));
+        cached = readCache(path, now);
+    }
+    catch {
+        return null;
+    }
+    if (cached && now - cached.checked_at < (cached.failed ? cooldown : ttl))
+        return !cached.failed && cached.latest && newer(cached.latest, options.currentVersion) ? hint(cached.latest, options.currentVersion) : null;
+    try {
+        const latest = await latestStable(options.fetch ?? globalThis.fetch);
+        try {
+            writeCache(path, { schema_version: 1, checked_at: now, latest, failed: false });
+        }
+        catch { /* Notification must not make CLI commands fail. */ }
+        return newer(latest, options.currentVersion) ? hint(latest, options.currentVersion) : null;
+    }
+    catch {
+        try {
+            writeCache(path, { schema_version: 1, checked_at: now, latest: null, failed: true });
+        }
+        catch { /* Silent best effort; no provider/ledger fallback. */ }
+        return null;
+    }
+}
+function hint(latest, current) { return `Aptly ${latest} is available (installed: ${current}). Run aptly update to update this global installation; use the installation guide for local installs.`; }