fraim-hub 2.0.351 → 2.0.352

package/dist/src/ai-hub/configured-agent-child.js

@@ -0,0 +1,172 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const node_string_decoder_1 = require("node:string_decoder");
+function report(stage, value = '') {
+    const control = process.env.FRAIM_CONFIGURED_CONTROL;
+    if (control)
+        node_fs_1.default.writeFileSync(node_path_1.default.join(control, stage), value, { mode: 0o600 });
+}
+/** Quote a native argument, then protect both cmd parsing passes of a %* forwarding wrapper. */
+function forwardingCmdArgument(value) {
+    let quoted = '"';
+    let slashes = 0;
+    for (const character of value) {
+        if (character === '\\') {
+            slashes++;
+            continue;
+        }
+        quoted += '\\'.repeat(character === '"' ? slashes * 2 + 1 : slashes) + character;
+        slashes = 0;
+    }
+    quoted += '\\'.repeat(slashes * 2) + '"';
+    return escapeCmd(escapeCmd(quoted));
+}
+function escapeCmd(value) { return value.replace(/([()\][%!^"`<>&|;, *?])/g, '^$1'); }
+function cleanEnvironment() {
+    const env = { ...process.env };
+    const electronMode = env.FRAIM_CONFIGURED_ELECTRON_MODE;
+    for (const key of Object.keys(env))
+        if (key.startsWith('FRAIM_CONFIGURED_'))
+            delete env[key];
+    if (electronMode)
+        env.ELECTRON_RUN_AS_NODE = electronMode;
+    else
+        delete env.ELECTRON_RUN_AS_NODE;
+    return env;
+}
+async function main() {
+    const mode = process.argv[2];
+    if (mode === '--fail') {
+        report('failure', ['preparation', 'resolution', 'invocation', 'migration'].includes(process.argv[3]) ? process.argv[3] : 'invocation');
+        return;
+    }
+    const spec = JSON.parse(process.env.FRAIM_CONFIGURED_SPEC || '{}');
+    if (mode === '--shell-data') {
+        const shellPath = (value) => process.platform === 'win32' ? value.replace(/\\/g, '/') : value;
+        const fields = [shellPath(spec.target), spec.envPrefixText, shellPath(spec.setupScript?.command || ''), ...(spec.setupScript?.args || [])];
+        process.stdout.write(fields.join('\0') + '\0');
+        return;
+    }
+    const env = cleanEnvironment();
+    let browser = { args: [] };
+    if (spec.browser && env.FRAIM_BROWSER_CDP_ENDPOINT) {
+        // Loaded only in the prepared child: CODEX_HOME and auth now belong to the selected account.
+        const { sharedBrowserHostConfig } = await Promise.resolve().then(() => __importStar(require('./hosts')));
+        browser = sharedBrowserHostConfig(spec.hostId, env);
+        if (spec.hostId === 'codex' && !browser.env?.CODEX_HOME)
+            throw new Error('Browser home preparation failed');
+    }
+    const args = spec.hostId === 'codex'
+        ? [...spec.args, ...spec.extraArgs, ...browser.args]
+        : [...spec.args, ...browser.args, ...spec.extraArgs];
+    Object.assign(env, browser.env);
+    if (mode === '--prepare-shell') {
+        report('ready');
+        const updates = { ...browser.env, ELECTRON_RUN_AS_NODE: env.ELECTRON_RUN_AS_NODE || '' };
+        process.stdout.write(JSON.stringify({ args, env: updates }));
+        return;
+    }
+    let target = process.env.FRAIM_CONFIGURED_TARGET;
+    if (target && process.platform === 'win32' && spec.runner === 'bash' && !node_fs_1.default.existsSync(target) && node_fs_1.default.existsSync(`${target}.exe`))
+        target += '.exe';
+    if (!target || !node_fs_1.default.existsSync(target)) {
+        report('failure', 'resolution');
+        process.exitCode = 71;
+        return;
+    }
+    let command = target;
+    let commandArgs = args;
+    let windowsVerbatimArguments = false;
+    let shellTransport = false;
+    if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(target)) {
+        command = env.ComSpec || env.COMSPEC || 'cmd.exe';
+        commandArgs = ['/d', '/v:off', '/s', '/c', `"${[escapeCmd(target), ...args.map(forwardingCmdArgument)].join(' ')}"`];
+        windowsVerbatimArguments = true;
+        shellTransport = true;
+    }
+    else if (process.platform === 'win32' && spec.runner === 'bash' && !/\.(exe|com)$/i.test(target)) {
+        command = 'bash';
+        // MSYS parses apostrophes in separately supplied Windows argv. Transport one
+        // POSIX command string whose every data token is single-quoted for Bash.
+        const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+        commandArgs = ['--noprofile', '--norc', '-c', `exec ${[target.replace(/\\/g, '/'), ...args].map(quote).join(' ')}`];
+        shellTransport = true;
+    }
+    const child = (0, node_child_process_1.spawn)(command, commandArgs, { env, cwd: process.cwd(), stdio: ['inherit', 'inherit', shellTransport ? 'pipe' : 'inherit'], windowsHide: true, windowsVerbatimArguments });
+    if (child.stderr) {
+        // A selected script can disappear between resolution and the shell opening it.
+        // Preserve diagnostics while withholding the selected account's local path.
+        const names = [...new Set([target, target.replace(/\\/g, '/'), target.replace(/\//g, '\\')])];
+        const pattern = new RegExp(names.map(name => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'gi');
+        const decoder = new node_string_decoder_1.StringDecoder('utf8');
+        let pending = '';
+        const publish = (text) => process.stderr.write(text.replace(pattern, '[configured target]'));
+        child.stderr.on('data', chunk => {
+            pending += decoder.write(chunk);
+            let boundary;
+            while ((boundary = pending.indexOf('\n')) >= 0) {
+                publish(pending.slice(0, boundary + 1));
+                pending = pending.slice(boundary + 1);
+            }
+            if (pending.length > 65536 + target.length) {
+                let boundary = 65536;
+                pattern.lastIndex = 0;
+                let match;
+                while ((match = pattern.exec(pending)) && match.index < boundary) {
+                    if (match.index + match[0].length > boundary) {
+                        boundary = match.index;
+                        break;
+                    }
+                }
+                publish(pending.slice(0, boundary));
+                pending = pending.slice(boundary);
+            }
+        });
+        child.stderr.once('end', () => publish(pending + decoder.end()));
+    }
+    child.once('spawn', () => report('ready'));
+    child.once('error', () => { report('failure', 'invocation'); process.exitCode = 72; });
+    child.once('close', (code, signal) => { process.exitCode = signal ? 73 : code ?? 72; });
+}
+if (require.main === module) {
+    main().catch(() => { report('failure', 'preparation'); process.exitCode = 70; });
+}

package/dist/src/ai-hub/configured-agent-command.js

@@ -1,116 +1,196 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIGURED_MIGRATION = exports.CONFIGURED_TROUBLESHOOTING = void 0;
 exports.parseConfiguredCommand = parseConfiguredCommand;
 exports.describeConfiguredCommandInvocationProblem = describeConfiguredCommandInvocationProblem;
-exports.__setCommandResolutionProbeForTests = __setCommandResolutionProbeForTests;
-exports.probeCommandResolvesNonInteractively = probeCommandResolvesNonInteractively;
 exports.commandContainsLiteralSecret = commandContainsLiteralSecret;
 exports.decorateHostPlanWithConfiguredAgent = decorateHostPlanWithConfiguredAgent;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const child_process_1 = require("child_process");
-const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
-const BASH_ENV_PREFIX = /^([A-Za-z_][A-Za-z0-9_]*)=(?:\$\([^)]*\)|"[^"]*"|'[^']*'|\S*)\s+/;
-// The value may be a parenthesized PowerShell expression followed by a
-// property-access chain (e.g. `(Get-Content ... | ConvertFrom-Json).api_key`),
-// a quoted string, or a bare token — always terminated by the statement `;`.
-const POWERSHELL_ENV_PREFIX = /^\$env:[A-Za-z_][A-Za-z0-9_]*\s*=\s*(?:\([^)]*\)(?:\.[A-Za-z_][A-Za-z0-9_]*)*|"[^"]*"|'[^']*'|\S+?)\s*;\s*/;
-function parseConfiguredCommand(runner, commandText) {
-    let rest = String(commandText || '').trim();
-    const prefixPattern = runner === 'powershell' ? POWERSHELL_ENV_PREFIX : BASH_ENV_PREFIX;
-    let prefixEnd = 0;
-    while (true) {
-        const match = rest.slice(prefixEnd).match(prefixPattern);
-        if (!match)
-            break;
-        prefixEnd += match[0].length;
-    }
-    const envPrefixText = rest.slice(0, prefixEnd).trim();
-    const invocation = rest.slice(prefixEnd).trim();
-    const tokens = tokenizeShellLike(invocation);
-    return { envPrefixText, extraArgs: tokens.slice(1), invocationHead: tokens[0] || '' };
-}
-// Reviewer finding (PR #1209, Round 3): parseConfiguredCommand's leniency is
-// intentional for *parsing* (it never throws), but that leniency means a
-// structurally wrong command — most dangerously a shell built-in like `.`
-// (source) or `source` at the head, meant to load a setup script into the
-// current shell — parses "successfully" into a garbage invocationHead that
-// decorateHostPlanWithConfiguredAgent then silently discards, appending only
-// the path/args that followed it as bogus positional arguments to the real
-// agent binary instead of ever sourcing the script. Since the invocation
-// head is always discarded and replaced with Hub's own known base binary,
-// the only way to catch this class of error is to check, at readiness time,
-// that what the user typed there actually was that same base binary — not
-// to attempt to execute or otherwise interpret it.
-function describeConfiguredCommandInvocationProblem(parsed, baseHostId, agentLabel = 'Configured agent') {
-    if (!parsed.invocationHead) {
-        return `${agentLabel} command has no invocation after the environment prefix. Run the create-hub-configured-agent job to repair this profile with an environment prefix followed by "${baseHostId}".`;
-    }
-    if (parsed.invocationHead !== baseHostId) {
-        return `Configured agent "${agentLabel}" invokes "${parsed.invocationHead}", but Hub launches the "${baseHostId}" base CLI and cannot apply that wrapper's environment. Run the create-hub-configured-agent job to repair this profile with an environment prefix followed by "${baseHostId}".`;
+exports.CONFIGURED_TROUBLESHOOTING = 'Run troubleshoot-fraim with another working agent or in your IDE if this agent cannot start. Share only the profile ID, base agent and error category; do not share commands, environment values or credentials.';
+exports.CONFIGURED_MIGRATION = 'This profile needs migration: Hub launches the base CLI after setup-only preparation. Use troubleshoot-fraim, then create-hub-configured-agent to extract and preserve the wrapper or profile function\'s account/environment setup. Do not replace its name and lose account selection. ' + exports.CONFIGURED_TROUBLESHOOTING;
+const unsupportedSyntax = () => new Error('Configured command uses unsupported shell syntax. Use environment assignments followed by the base CLI and supported settings. ' + exports.CONFIGURED_MIGRATION);
+// Explicit settings prevent alternate CLI spellings (attached short options,
+// clusters, positionals and subcommands) from taking over Hub's session/protocol.
+// Values are consumed with their option, never scanned as independent flags.
+const SETTINGS = {
+    claude: ['--model', '-m', '--effort', '--permission-mode', '--allowedTools', '--disallowedTools', '--tools', '--add-dir', '--betas', '--settings', '--setting-sources', '--fallback-model', '--max-budget-usd'],
+    codex: ['--model', '-m', '--profile', '-p', '--config', '-c', '--sandbox'],
+    gemini: ['--model', '-m', '--approval-mode', '--allowed-tools', '--extensions', '--include-directories'],
+    copilot: ['--model', '--reasoning-effort', '--allow-tool', '--deny-tool', '--add-dir'],
+};
+// Prefixes are trusted user preparation, but only assignments belong here. Scan
+// balanced quotes/subexpressions so a semicolon inside a secret-file expression
+// cannot become an invocation boundary, and never evaluate an entire command.
+function prefixValueEnd(text, start, runner) {
+    let quote = '';
+    let depth = 0;
+    let i = start;
+    for (; i < text.length; i++) {
+        const char = text[i];
+        if (quote) {
+            if (char === quote) {
+                if (runner === 'powershell' && quote === "'" && text[i + 1] === "'") {
+                    i++;
+                    continue;
+                }
+                quote = '';
+            }
+            else if ((runner === 'powershell' && char === '`' && quote === '"') || (runner === 'bash' && char === '\\' && quote === '"')) {
+                if (++i >= text.length)
+                    throw unsupportedSyntax();
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        if ((runner === 'powershell' && char === '`') || (runner === 'bash' && char === '\\')) {
+            if (++i >= text.length)
+                throw unsupportedSyntax();
+            continue;
+        }
+        if (char === '(') {
+            if (runner === 'bash' && depth === 0 && text[i - 1] !== '$')
+                throw unsupportedSyntax();
+            depth++;
+        }
+        else if (char === ')') {
+            if (depth === 0)
+                throw unsupportedSyntax();
+            depth--;
+        }
+        else if (depth === 0) {
+            if (runner === 'powershell' && char === ';')
+                break;
+            if (/\s/.test(char)) {
+                if (runner === 'powershell') {
+                    const afterPlus = text[i - 1] === '+';
+                    while (/\s/.test(text[i] || '') && i < text.length)
+                        i++;
+                    if (text[i] === '+')
+                        continue;
+                    if (afterPlus && text[i] && text[i] !== ';') {
+                        i--;
+                        continue;
+                    }
+                    if (text[i] !== ';')
+                        throw unsupportedSyntax();
+                }
+                break;
+            }
+            if (/[;&|<>`{}]/.test(char))
+                throw unsupportedSyntax();
+        }
     }
-    return null;
-}
-let commandResolutionProbeOverride = null;
-function __setCommandResolutionProbeForTests(stub) {
-    commandResolutionProbeOverride = stub;
+    if (quote || depth !== 0 || (i === start && runner === 'powershell'))
+        throw unsupportedSyntax();
+    if (runner === 'powershell' && text[i] !== ';')
+        throw unsupportedSyntax();
+    return i;
 }
-const PROBE_CACHE_TTL_MS = 60_000;
-const NON_INTERACTIVE_PROBE_TIMEOUT_MS = 3_000;
-const probeCache = new Map();
-// Probes whether commandName is resolvable in the non-interactive shell context
-// that Hub actually uses to launch configured agents (bash --noprofile --norc,
-// or powershell -NoProfile). Commands defined only as profile functions or
-// aliases are unavailable in that context and would cause silent launch failure.
-// Results are cached for PROBE_CACHE_TTL_MS to avoid repeated spawnSync calls
-// on frequent availability checks.
-function probeCommandResolvesNonInteractively(runner, commandName) {
-    if (commandResolutionProbeOverride !== null)
-        return commandResolutionProbeOverride(runner, commandName);
-    const key = `${runner}\x00${commandName}`;
-    const cached = probeCache.get(key);
-    if (cached && Date.now() - cached.at < PROBE_CACHE_TTL_MS)
-        return cached.result;
-    let result;
-    if (runner === 'powershell') {
-        if (process.platform !== 'win32') {
-            result = null;
+function tokenizeInvocation(text, runner) {
+    const tokens = [];
+    let value = '';
+    let quote = '';
+    let started = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (!quote && /\s/.test(char)) {
+            if (started)
+                tokens.push(value);
+            value = '';
+            started = false;
+            continue;
         }
-        else {
-            const r = (0, child_process_1.spawnSync)('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `Get-Command -Name ${JSON.stringify(commandName)} -ErrorAction Stop`], { encoding: 'utf8', timeout: NON_INTERACTIVE_PROBE_TIMEOUT_MS, windowsHide: true });
-            result = r.error || r.status !== 0
-                ? `Command '${commandName}' not found in non-interactive PowerShell (powershell -NoProfile). ` +
-                    `This command may be a PowerShell profile function or alias that is unavailable without a profile. ` +
-                    `Create a .cmd wrapper on PATH that calls the real executable directly.`
-                : null;
+        started = true;
+        if (quote === "'") {
+            if (char === "'") {
+                if (runner === 'powershell' && text[i + 1] === "'") {
+                    value += "'";
+                    i++;
+                }
+                else
+                    quote = '';
+            }
+            else
+                value += char;
+            continue;
+        }
+        if (char === '"') {
+            quote = quote ? '' : '"';
+            continue;
         }
+        if (!quote && char === "'") {
+            quote = "'";
+            continue;
+        }
+        if ((runner === 'powershell' && char === '`') || (runner === 'bash' && char === '\\')) {
+            const next = text[++i];
+            if (next === undefined)
+                throw unsupportedSyntax();
+            if (runner === 'bash' && quote && !/["$`\\]/.test(next))
+                value += '\\';
+            if (runner === 'powershell' && /[0abefnrtuv]/i.test(next))
+                throw unsupportedSyntax();
+            value += next;
+            continue;
+        }
+        // Expanding variables, globbing, expressions and shell operators in the
+        // target/arguments would require evaluating a second command language.
+        // Reject those shapes rather than silently changing their meaning.
+        if (char === '$' || char === '`' || (!quote && /[;&|<>(){}*?\[\]#@~]/.test(char)))
+            throw unsupportedSyntax();
+        value += char;
     }
-    else {
-        const r = (0, child_process_1.spawnSync)('bash', ['--noprofile', '--norc', '-c', `command -v ${commandName}`], {
-            encoding: 'utf8',
-            timeout: NON_INTERACTIVE_PROBE_TIMEOUT_MS,
-            windowsHide: true,
-        });
-        result = r.error || r.status !== 0
-            ? `Command '${commandName}' not found in non-interactive bash (bash --noprofile --norc). ` +
-                `This command may be defined only in a shell profile. ` +
-                `Add the command to a PATH location accessible without sourcing any profile.`
-            : null;
+    if (quote)
+        throw unsupportedSyntax();
+    if (started)
+        tokens.push(value);
+    return tokens;
+}
+function parseConfiguredCommand(runner, commandText) {
+    const text = String(commandText || '').trim();
+    if (/[\r\n\0]/.test(text))
+        throw unsupportedSyntax();
+    let prefixEnd = 0;
+    while (prefixEnd < text.length) {
+        const assignment = text.slice(prefixEnd).match(runner === 'powershell'
+            ? /^\$env:[A-Za-z_][A-Za-z0-9_]*\s*=\s*/i
+            : /^[A-Za-z_][A-Za-z0-9_]*=/);
+        if (!assignment)
+            break;
+        const valueEnd = prefixValueEnd(text, prefixEnd + assignment[0].length, runner);
+        prefixEnd = valueEnd + (runner === 'powershell' ? 1 : 0);
+        while (/\s/.test(text[prefixEnd] || '') && prefixEnd < text.length)
+            prefixEnd++;
     }
-    probeCache.set(key, { result, at: Date.now() });
-    return result;
+    let invocation = text.slice(prefixEnd).trim();
+    if (runner === 'powershell' && invocation.startsWith('&'))
+        invocation = invocation.slice(1).trimStart();
+    const tokens = tokenizeInvocation(invocation, runner);
+    return { envPrefixText: text.slice(0, prefixEnd).trim(), invocationHead: tokens[0] || '', extraArgs: tokens.slice(1) };
 }
-function tokenizeShellLike(text) {
-    const tokens = [];
-    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
-    let match;
-    while ((match = re.exec(text)) !== null) {
-        tokens.push(match[1] ?? match[2] ?? match[3]);
+function describeConfiguredCommandInvocationProblem(parsed, baseHostId) {
+    if (!parsed.invocationHead)
+        return 'Configured command has no invocation after its environment prefix.';
+    if (parsed.invocationHead !== baseHostId)
+        return exports.CONFIGURED_MIGRATION;
+    const settings = SETTINGS[baseHostId] || [];
+    for (let i = 0; i < parsed.extraArgs.length; i++) {
+        const argument = parsed.extraArgs[i];
+        const option = argument.split('=')[0];
+        if (!settings.includes(option)) {
+            return 'Configured command contains an unsupported setting or conflicts with Hub protocol or session arguments. Hub supplies prompt, output and resume options, including short and attached forms. ' + exports.CONFIGURED_TROUBLESHOOTING;
+        }
+        if (argument.includes('=')) {
+            if (!argument.slice(argument.indexOf('=') + 1))
+                return 'Configured setting requires a value. ' + exports.CONFIGURED_TROUBLESHOOTING;
+        }
+        else if (!parsed.extraArgs[++i] || parsed.extraArgs[i].startsWith('-')) {
+            return 'Configured setting requires a value. ' + exports.CONFIGURED_TROUBLESHOOTING;
+        }
     }
-    return tokens;
+    return null;
 }
 // Issue #1201 (R2.3): UX safety net only — flags what pattern-matches as a
 // literal high-entropy secret pasted into the command field. Not a substitute
@@ -129,76 +209,38 @@ function commandContainsLiteralSecret(commandText) {
     }
     return false;
 }
-// The env-prefix assignment is evaluated as a bash "temporary environment"
-// directly attached to the `exec` command on the same line (`VAR=$(...) exec
-// "$@"`), not as a separate statement before it. A bare `VAR=value` on its
-// own line only sets a local shell variable — it is NOT exported, so it
-// would silently vanish from the real binary's environment once `exec`
-// replaces this process image. Attaching it to the same command line is
-// exactly what a terminal user's `VAR=$(...) codex ...` already does.
-const BASH_LAUNCH_WRAPPER = [
-    '#!/usr/bin/env bash',
-    'set -e',
-    'if [ -n "$FRAIM_CONFIGURED_AGENT_ENV_PREFIX" ]; then',
-    '  eval "$FRAIM_CONFIGURED_AGENT_ENV_PREFIX exec \\"\\$@\\""',
-    'else',
-    '  exec "$@"',
-    'fi',
-    '',
-].join('\n');
-const POWERSHELL_LAUNCH_WRAPPER = [
-    '$ErrorActionPreference = "Stop"',
-    'if ($env:FRAIM_CONFIGURED_AGENT_ENV_PREFIX) {',
-    '  Invoke-Expression $env:FRAIM_CONFIGURED_AGENT_ENV_PREFIX',
-    '}',
-    '$exe = $args[0]',
-    'if ($args.Length -gt 1) { $rest = $args[1..($args.Length - 1)] } else { $rest = @() }',
-    '& $exe @rest',
-    'exit $LASTEXITCODE',
-    '',
-].join('\r\n');
-// Writes the small, fixed wrapper script that lets a configured-agent's
-// env-prefix (which may contain `$(...)`/`(...)` substitutions) resolve in a
-// real shell at spawn time, then `exec`s Hub's own required invocation with
-// the parsed extra CLI args appended. Content-checked so it self-heals like
-// any other FRAIM-generated artifact (issue #1206 precedent) rather than
-// silently going stale if regenerated with different logic.
-//
-// Security review (issue #1201): written under the per-user FRAIM home
-// (`getUserFraimDirPath()`), NOT `os.tmpdir()`. A predictable filename in a
-// shared, world-writable OS temp directory is a symlink-race target on
-// multi-user machines — another local user could pre-place a symlink at the
-// predictable path, and `fs.writeFileSync` would follow it and overwrite an
-// arbitrary file the *victim* user can write to. The per-user FRAIM home is
-// not shared across OS accounts, closing that class of attack.
-function ensureConfiguredAgentLaunchWrapper(runner) {
-    const content = runner === 'bash' ? BASH_LAUNCH_WRAPPER : POWERSHELL_LAUNCH_WRAPPER;
-    const filePath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), runner === 'bash' ? 'hub-configured-agent-launch.sh' : 'hub-configured-agent-launch.ps1');
-    const existing = fs_1.default.existsSync(filePath) ? fs_1.default.readFileSync(filePath, 'utf8') : null;
-    if (existing !== content) {
-        fs_1.default.writeFileSync(filePath, content, { encoding: 'utf8', mode: 0o755 });
-    }
-    return filePath;
-}
 function decorateHostPlanWithConfiguredAgent(plan, agent, agentEnv = {}) {
     if (!agent)
         return plan;
+    if (!agent.enabled)
+        throw new Error('Configured agent is disabled. Enable this profile before starting it.');
     const withEnv = { ...plan, env: { ...(plan.env || {}), ...agentEnv } };
-    if (!agent.command)
-        return withEnv;
-    const parsed = parseConfiguredCommand(agent.command.runner, agent.command.command);
-    if (!parsed.envPrefixText && parsed.extraArgs.length === 0)
+    if (!agent.command && !agent.setupScript)
         return withEnv;
-    const wrapperPath = ensureConfiguredAgentLaunchWrapper(agent.command.runner);
-    const realInvocation = [plan.command, ...plan.args, ...parsed.extraArgs];
-    const decoratedEnv = { ...withEnv.env, FRAIM_CONFIGURED_AGENT_ENV_PREFIX: parsed.envPrefixText };
-    if (agent.command.runner === 'bash') {
-        return { ...withEnv, command: 'bash', args: [wrapperPath, ...realInvocation], env: decoratedEnv };
+    if (agent.command && agent.setupScript && agent.command.runner !== agent.setupScript.runner) {
+        throw new Error('Configured command and setup script use different runners. Use the same runner for both preparation and launch.');
     }
+    const runner = agent.command?.runner || agent.setupScript.runner;
+    const parsed = agent.command
+        ? parseConfiguredCommand(runner, agent.command.command)
+        : { invocationHead: agent.baseHostId, envPrefixText: '', extraArgs: [] };
+    const problem = describeConfiguredCommandInvocationProblem(parsed, agent.baseHostId);
+    if (problem)
+        throw new Error(problem);
+    if (agent.setupScript && !agent.setupScript.command.trim())
+        throw new Error('Configured setup script is empty.');
     return {
         ...withEnv,
-        command: 'powershell.exe',
-        args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', wrapperPath, ...realInvocation],
-        env: decoratedEnv,
+        configuredInvocation: {
+            configuredAgentId: agent.id,
+            runner,
+            // The adapter owns the executable; settings never select a launch wrapper.
+            // Resolve it only after preparation, against that session's PATH.
+            target: plan.command,
+            envPrefixText: parsed.envPrefixText,
+            extraArgs: parsed.extraArgs,
+            ...(agent.setupScript ? { setupScript: { ...agent.setupScript, args: [...(agent.setupScript.args || [])] } } : {}),
+            timeoutMs: agent.setupScript?.timeoutMs || agent.command?.timeoutMs || 30_000,
+        },
     };
 }