@controllerai/cli 0.2.9 → 0.2.10

package/dist/commands/node.js

@@ -1,14 +1,18 @@
 import { readFileSync } from 'node:fs';
 import { requireContext } from '../context.js';
-import { validationFailed, validationMessage } from './expr.js';
+import { prepareWritableProp, requireReadbackProp, validationFailed, validationMessage, } from './expr.js';
 import { CaiError, userError } from '../errors.js';
 import { resolveJsSource } from '../jsSource.js';
-import { buildNodeReadiness, expressionReadbackChannel, nodePropsFromPayload, normalizeNodePropWrites, } from '../nodeProps.js';
+import { arrayExpressionReplacementWarning, assertArrayExpressionWriteSupported, buildNodeReadiness, expressionPersistenceMismatchMessage, nodePropsFromPayload, normalizeNodePropWrites, remoteOptionsCompiledLiteralNote, subflowTargetFromPayload, verifyExpressionPersistence, } from '../nodeProps.js';
 import { emit, printKeyValues, printTable, truncate, warn } from '../output.js';
 const readUtf8 = (source, encoding) => readFileSync(source, encoding);
 const loadProps = async (api, workflowId, nodeId) => {
-    const props = await api.tool(workflowId, 'get_node_props', { nodeId });
-    return nodePropsFromPayload(props);
+    const payload = await api.tool(workflowId, 'get_node_props', { nodeId });
+    const subflowTarget = subflowTargetFromPayload(payload);
+    return {
+        props: nodePropsFromPayload(payload),
+        ...(subflowTarget ? { subflowTarget } : {}),
+    };
 };
 /**
  * get_node exposes processOutput after a successful typed run or documented
@@ -35,19 +39,16 @@ const addResolvedOutputType = async (api, workflowId, record) => {
         return record;
     }
 };
-/** Fail closed: a write without current prop metadata is unsafe. */
-const findProp = async (api, workflowId, nodeId, propName) => {
-    const rows = await loadProps(api, workflowId, nodeId);
-    const prop = rows.find(p => p.name === propName);
-    if (!prop) {
-        throw userError(`Node ${nodeId} has no prop "${propName}". Re-read \`cai node props ${nodeId}\`; ` +
-            'a selector, connection, or reload may need to be configured first.', 'UNKNOWN_PROP');
-    }
-    if (prop.enabled === false || prop.source === 'propsCatalog') {
-        throw userError(`Prop "${propName}" is optional but not materialized. Run ` +
-            `\`cai node enable-prop ${nodeId} --prop ${propName}\`, then re-read props.`, 'PROP_NOT_ENABLED');
-    }
-    return prop;
+const loadNodeReadiness = async (api, workflowId, nodeId) => {
+    const [record, loadedProps] = await Promise.all([
+        api.tool(workflowId, 'get_node', { nodeId }),
+        loadProps(api, workflowId, nodeId),
+    ]);
+    const resolvedRecord = await addResolvedOutputType(api, workflowId, record);
+    return {
+        record: resolvedRecord,
+        readiness: buildNodeReadiness(nodeId, resolvedRecord, loadedProps.props, loadedProps.subflowTarget),
+    };
 };
 /**
  * Prop types whose stored shape pairs a value with the human label the UI displayed.
@@ -63,6 +64,9 @@ const isOptionBackedProp = (prop) => ['DROPDOWN', 'MULTI_SELECT', 'MULTI_SELECT_
  * Getting this wrong saves cleanly and shows blank chips in the UI (found by CFG-012).
  */
 const isMultiSelectProp = (prop) => ['MULTI_SELECT', 'MULTI_SELECT_DROPDOWN'].includes(String(prop.inputType ?? ''));
+const optionValueLabel = (prop, options) => isMultiSelectProp(prop)
+    ? options.map(option => ({ value: option.value, label: option.label }))
+    : options[0]?.label;
 /**
  * Remote option providers commonly search human labels rather than opaque ids.
  * A supplied --label is therefore the lookup query, never an unverified value
@@ -93,12 +97,69 @@ const isTextExpressionBackedProp = (prop) => ['JSON', 'LONG_TEXT', 'SHORT_TEXT',
 const fetchPropOptions = async (api, workflowId, nodeId, propName, query) => {
     const data = await api.tool(workflowId, 'get_prop_options', { nodeId, propName, ...(query ? { query } : {}) });
     const rows = Array.isArray(data) ? data : (data?.options ?? []);
-    return rows
-        .map(o => ({
-        value: String(o.value ?? o.id ?? ''),
-        label: String(o.label ?? o.name ?? o.value ?? o.id ?? ''),
-    }))
-        .filter(o => o.value !== '');
+    const error = !Array.isArray(data) && typeof data?.error === 'string' ? data.error : undefined;
+    return {
+        options: rows
+            .map(o => ({
+            value: String(o.value ?? o.id ?? ''),
+            label: String(o.label ?? o.name ?? o.value ?? o.id ?? ''),
+        }))
+            .filter(o => o.value !== ''),
+        ...(error ? { error } : {}),
+    };
+};
+export const parseNodeOptionsPrevContext = (raw) => {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        throw userError(`--prev-context must be a JSON object: ${error instanceof Error ? error.message : error}`, 'BAD_OPTION_CONTEXT');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw userError('--prev-context must be a JSON object.', 'BAD_OPTION_CONTEXT');
+    }
+    return value;
+};
+export const parseNodeOptionOverrides = (entries) => {
+    const overrides = new Map();
+    for (const entry of entries) {
+        const separator = entry.indexOf('=');
+        const name = separator >= 0 ? entry.slice(0, separator).trim() : '';
+        if (separator < 0 || !name) {
+            throw userError(`--for must use <prop>=<value>; received ${JSON.stringify(entry)}.`, 'BAD_OPTION_OVERRIDE');
+        }
+        const rawValue = entry.slice(separator + 1);
+        let value;
+        try {
+            value = JSON.parse(rawValue);
+        }
+        catch {
+            value = rawValue;
+        }
+        overrides.set(name, value);
+    }
+    return Object.fromEntries(overrides);
+};
+const collectNodeOptionOverride = (value, previous = []) => [
+    ...previous,
+    value,
+];
+const dynamicUpstreamOptionError = (value) => typeof value === 'string' &&
+    /^Upstream prop "[^"]+" holds a dynamic value, so no option list exists\./i.test(value.trim());
+const DYNAMIC_UPSTREAM_RAW_VALUE_NOTE = 'Value stored WITHOUT validation against provider options because an upstream prop holds a dynamic value.';
+const dynamicUpstreamOptionNext = (nodeId, propName) => `cai node set ${nodeId} --prop ${propName} --value <exact-id>; ` +
+    'options cannot be listed while an upstream prop is dynamic (or use --js for an expression)';
+const blockedUpstreamOptionMessage = (value) => {
+    if (!(value instanceof CaiError))
+        return undefined;
+    const match = /Cannot load options for "([^"]+)": earlier prop "([^"]+)" is unset\b/i.exec(value.message);
+    return match ? { propName: match[1], blockedBy: match[2] } : undefined;
+};
+const throwBlockedUpstreamOption = (nodeId, propName, blockedBy) => {
+    const next = `cai node set ${nodeId} --prop ${blockedBy} --value <value>`;
+    throw userError(`Cannot load options for "${propName}": earlier prop "${blockedBy}" is unset. ` +
+        `Set it first with \`${next}\`; nothing was written.`, 'OPTIONS_UNAVAILABLE');
 };
 const readObjectOption = (source, flag) => {
     const raw = source.trimStart().startsWith('{') ? source : readFileSync(source, 'utf8');
@@ -131,8 +192,10 @@ export const readNodeOutputSample = (source, reader = readUtf8) => {
     catch (error) {
         throw userError(`--sample-file must contain valid JSON: ${error instanceof Error ? error.message : error}`, 'BAD_SAMPLE');
     }
-    if (!sample || typeof sample !== 'object' || Array.isArray(sample)) {
-        throw userError('--sample-file must contain a JSON object.', 'BAD_SAMPLE');
+    if (sample === null ||
+        typeof sample !== 'object' ||
+        (Array.isArray(sample) && sample.length === 0)) {
+        throw userError('--sample-file must contain documented provider response data: a JSON object or a non-empty JSON array of items.', 'BAD_SAMPLE');
     }
     return sample;
 };
@@ -140,14 +203,14 @@ const nodeProcessOutput = (record) => record.processOutput ?? record.data?.proce
 const renderNodeOutputType = (dataType, declared) => declared && typeof dataType === 'string'
     ? `${dataType} (declared — unverified)`
     : dataType;
-const shellQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
-const requireCompletedPropReload = (result, nodeId, propName, retryCommand) => {
+const requireCompletedPropReload = (result, nodeId, propName) => {
     const reload = result;
     if (reload?.propsReloaded !== false)
         return;
     const reloadError = typeof reload.reloadError === 'string' && reload.reloadError.trim()
         ? reload.reloadError.trim()
         : 'The backend did not provide a reload error.';
+    const retryCommand = `cai node reload ${nodeId}`;
     const inspectCommand = `cai node props ${nodeId} --json`;
     throw new CaiError(`Prop "${propName}" was updated, but its dependent props were not reloaded: ` +
         `${reloadError}\nThe node may still contain stale dependent values. Retry the reload with ` +
@@ -162,6 +225,36 @@ const requireCompletedPropReload = (result, nodeId, propName, retryCommand) => {
         },
     });
 };
+const requireCompletedExplicitPropReload = (result, nodeId) => {
+    const reload = result;
+    if (reload?.reconcileSkipped === 'unset_selector')
+        return;
+    if (reload?.propsReloaded !== false)
+        return;
+    const reloadError = typeof reload.reloadError === 'string' && reload.reloadError.trim()
+        ? reload.reloadError.trim()
+        : 'The backend did not provide a reload error.';
+    const retryCommand = `cai node reload ${nodeId}`;
+    const inspectCommand = `cai node props ${nodeId} --json`;
+    throw new CaiError(`Node "${nodeId}" dependent props were not reloaded: ${reloadError}\n` +
+        `The node may still contain stale dependent values. Retry with \`${retryCommand}\`, then ` +
+        `inspect \`${inspectCommand}\` before configuring or running it.`, {
+        code: 'PROPS_RELOAD_FAILED',
+        detail: {
+            nodeId,
+            propsReloaded: false,
+            reloadError,
+            recoveryCommands: [retryCommand, inspectCommand],
+        },
+    });
+};
+const nodeReadinessDelta = (before, after) => ({
+    before: before.readinessState,
+    after: after.readinessState,
+    blockersResolved: before.blockedBy.filter(blocker => !after.blockedBy.includes(blocker)),
+    blockersAdded: after.blockedBy.filter(blocker => !before.blockedBy.includes(blocker)),
+    nextChanged: before.next === after.next ? null : { before: before.next, after: after.next },
+});
 const searchScore = (intent, component) => {
     const normalize = (value) => value
         .toLowerCase()
@@ -169,14 +262,22 @@ const searchScore = (intent, component) => {
         .trim();
     const query = normalize(intent);
     const terms = query.split(/\s+/).filter(Boolean);
+    if (terms.length === 0)
+        return 0;
     const name = normalize(component.name ?? '');
+    const nodeName = normalize(component.nodeName ?? '');
     const description = normalize(component.description ?? '');
     const props = normalize((component.propNames ?? []).join(' '));
-    let score = name === query ? 100 : name.includes(query) ? 50 : 0;
+    const searchableText = [name, nodeName, description];
+    let score = searchableText.some(value => value === query)
+        ? 100
+        : searchableText.some(value => value.includes(query))
+            ? 50
+            : 0;
     for (const term of terms) {
-        if (name.split(' ').includes(term))
+        if ([name, nodeName].some(value => value.split(' ').includes(term)))
             score += 12;
-        else if (name.includes(term))
+        else if ([name, nodeName].some(value => value.includes(term)))
             score += 7;
         if (description.includes(term))
             score += 3;
@@ -185,6 +286,79 @@ const searchScore = (intent, component) => {
     }
     return score;
 };
+const conceptHintDefinitions = [
+    {
+        concept: 'approval',
+        skill: 'controllerai-agents',
+        phrases: [
+            'approval',
+            'approvals',
+            'confirmation',
+            'confirmations',
+            'hitl',
+            'human in the loop',
+        ],
+        message: 'Configure confirmation on agent tools, then approve or deny pending requests in the conversation.',
+        commands: [
+            'cai agent tools <agentId>',
+            'cai agent add-action <agentId> --integration <slug> --action <key> --connection <id> --require-confirmation',
+            'cai agent add-workflow <agentId> --workflow-id <workflowId> --flow <flowId> --require-confirmation',
+            'cai agent update-tool <agentId> --tool <toolId> --require-confirmation',
+            'cai agent conversation approve <conversationId> --request <requestId>',
+            'cai agent conversation deny <conversationId> --request <requestId>',
+        ],
+    },
+    {
+        concept: 'memory',
+        skill: 'controllerai-data',
+        phrases: ['memory', 'memories'],
+        message: 'Use workflow data for durable structured state; the CLI has no separate agent-memory command.',
+        commands: [
+            'cai schema list',
+            'cai data collections',
+            'cai data query --type <dataType>',
+        ],
+    },
+    {
+        concept: 'knowledge',
+        skill: 'controllerai-agents',
+        phrases: ['knowledge'],
+        message: 'List or add files in an agent knowledge space.',
+        commands: [
+            'cai agent files <agentId> --space knowledge',
+            'cai agent add-file <agentId> --file <path> --space knowledge',
+        ],
+    },
+    {
+        concept: 'trigger',
+        skill: 'controllerai-triggers',
+        phrases: ['trigger', 'triggers', 'webhook', 'webhooks', 'schedule', 'schedules'],
+        message: 'If you are looking for trigger nodes rather than actions, use `cai trigger search`.',
+        commands: ['cai trigger search <query>'],
+    },
+];
+const conceptHintsFor = (query) => {
+    const normalized = query
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+    if (!normalized)
+        return [];
+    const padded = ` ${normalized} `;
+    return conceptHintDefinitions
+        .filter(definition => definition.phrases.some(phrase => padded.includes(` ${phrase} `)))
+        .map(({ phrases: _phrases, ...hint }) => hint);
+};
+const printConceptHints = (hints) => {
+    if (hints.length === 0)
+        return;
+    process.stdout.write('\nConcept hints:\n');
+    for (const hint of hints) {
+        process.stdout.write(`${hint.concept} (${hint.skill}): ${hint.message}\n`);
+        for (const command of hint.commands)
+            process.stdout.write(`  ${command}\n`);
+    }
+};
 /**
  * `add_node` needs BOTH nodeSlug and nodeKey, but component keys returned by
  * search are already `<nodeSlug>-<component>` — so the slug is recoverable.
@@ -212,6 +386,95 @@ const resolveSlug = async (api, workflowId, componentKey, explicit) => {
     throw userError(`Cannot infer the node slug from component key "${componentKey}". Pass --node <slug> ` +
         '(the `nodeSlug` column from `cai node components`).', 'UNRESOLVED_SLUG');
 };
+const rethrowNodeAddOptionalPropError = (error) => {
+    if (error instanceof CaiError) {
+        const match = /^Optional prop "([^"]+)" not found on this component — available optional props:\s*(.*)$/s.exec(error.message);
+        if (match) {
+            const propName = match[1];
+            const available = match[2].trim() || '(empty)';
+            throw new CaiError(`Optional prop "${propName}" is not in this component's STATIC catalog; ` +
+                `available optional props: ${available}. Dynamically-generated props only materialize ` +
+                'after creation. Create the node without that --enable-prop, then run ' +
+                `\`cai node set <newNodeId> --prop ${propName} --value <value>\` (which auto-enables ` +
+                `it) or \`cai node enable-prop <newNodeId> --prop ${propName}\`.`, {
+                exitCode: error.exitCode,
+                code: 'OPTIONAL_PROP_NOT_STATIC',
+                detail: error.detail,
+                scrubbed: error.scrubbed,
+            });
+        }
+    }
+    throw error;
+};
+const textExpressionsIn = (value) => {
+    if (Array.isArray(value))
+        return value.flatMap(textExpressionsIn);
+    if (!value || typeof value !== 'object')
+        return [];
+    const record = value;
+    if (record.type === 'TextExpression')
+        return [record];
+    return Object.values(record).flatMap(textExpressionsIn);
+};
+const textExpressionTerminalType = (expression) => {
+    const chips = (Array.isArray(expression.entries) ? expression.entries : [])
+        .flatMap(row => (Array.isArray(row) ? row : []))
+        .filter((entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry));
+    let terminal = chips.at(-1);
+    let inferredType;
+    while (terminal) {
+        if (typeof terminal.returnDataType === 'string')
+            inferredType = terminal.returnDataType;
+        terminal =
+            terminal.next && typeof terminal.next === 'object' && !Array.isArray(terminal.next)
+                ? terminal.next
+                : undefined;
+    }
+    return inferredType;
+};
+/**
+ * Protect older backends from advanced add_node expression writes when the
+ * component's static catalog is available. Dynamic props and catalog lookup
+ * failures deliberately fall through to the backend's authoritative guard.
+ */
+const guardInitialArrayExpressionWrites = async (api, workflowId, nodeSlug, nodeKey, writes) => {
+    const expressionWrites = Object.entries(writes ?? {}).filter(([, write]) => {
+        const valueExpressions = textExpressionsIn(write.value);
+        return (typeof write.valueJs === 'string' ||
+            typeof write.expressionValueJs === 'string' ||
+            write.expressionValue !== undefined ||
+            valueExpressions.length > 0 ||
+            write.useExpression === true);
+    });
+    if (expressionWrites.length === 0)
+        return;
+    let component;
+    try {
+        component = await api.tool(workflowId, 'get_node_component', { nodeSlug, nodeKey });
+    }
+    catch {
+        return;
+    }
+    const catalogProps = nodePropsFromPayload(component?.props ?? component?.component?.props ?? []);
+    for (const [propName, write] of expressionWrites) {
+        const prop = catalogProps.find(row => (row.name ?? row.key) === propName);
+        if (!prop || !String(prop.inputType ?? '').endsWith('_ARRAY'))
+            continue;
+        if (typeof write.valueJs === 'string') {
+            assertArrayExpressionWriteSupported('<newNodeId>', propName, prop, undefined);
+        }
+        if (typeof write.expressionValueJs === 'string' ||
+            write.expressionValue !== undefined ||
+            write.useExpression === true) {
+            assertArrayExpressionWriteSupported('<newNodeId>', propName, prop, undefined, 'expressionValue');
+        }
+        const valueExpressions = textExpressionsIn(write.value);
+        for (const expression of valueExpressions) {
+            assertArrayExpressionWriteSupported('<newNodeId>', propName, prop, textExpressionTerminalType(expression), 'value');
+        }
+    }
+};
+const isUnknownToolError = (error) => error instanceof CaiError && /unknown tool|method not found/i.test(error.message);
 export const registerNode = (program) => {
     const node = program.command('node').description('Nodes — search, add, configure, wire');
     node
@@ -223,6 +486,7 @@ export const registerNode = (program) => {
         .description('Search registry + catalog nodes (ranked by featuredWeight, not relevance)')
         .action(async (query, opts, command) => {
         const { api, workflowId } = requireContext(command);
+        const conceptHints = conceptHintsFor(query);
         const result = await api.tool(workflowId, 'search_nodes', {
             query,
             limit: Number(opts.limit),
@@ -230,15 +494,18 @@ export const registerNode = (program) => {
             ...(opts.events ? { hasEvents: true } : {}),
         });
         const rows = result?.data ?? [];
-        emit({ items: rows, pagination: result?.pagination ?? null }, () => printTable(['slug', 'name', 'source', 'actions', 'events', 'auth', 'weight'], rows.map((n) => [
-            n.slug,
-            n.name,
-            n.source,
-            n.actionsCount,
-            n.eventsCount,
-            n.authRequired ? 'yes' : 'no',
-            n.featuredWeight,
-        ])));
+        emit({ items: rows, pagination: result?.pagination ?? null, conceptHints }, () => {
+            printTable(['slug', 'name', 'source', 'actions', 'events', 'auth', 'weight'], rows.map((n) => [
+                n.slug,
+                n.name,
+                n.source,
+                n.actionsCount,
+                n.eventsCount,
+                n.authRequired ? 'yes' : 'no',
+                n.featuredWeight,
+            ]));
+            printConceptHints(conceptHints);
+        });
     });
     node
         .command('find')
@@ -248,6 +515,7 @@ export const registerNode = (program) => {
         .description('Find ranked action components and return exact nodeSlug/nodeKey pairs')
         .action(async (intent, opts, command) => {
         const { api, workflowId } = requireContext(command);
+        const conceptHints = conceptHintsFor(intent);
         let slugs;
         if (opts.node) {
             slugs = [opts.node];
@@ -266,23 +534,56 @@ export const registerNode = (program) => {
                 query: intent,
                 limit: 20,
             });
-            return (result?.data ?? []).map((component) => ({
-                ...component,
-                nodeSlug: component.nodeSlug ?? nodeSlug,
-            }));
+            return {
+                rows: (result?.data ?? []).map((component) => ({
+                    ...component,
+                    nodeSlug: component.nodeSlug ?? nodeSlug,
+                })),
+                hasMore: result?.pagination?.hasMore === true,
+            };
         }));
-        const rows = batches
-            .flat()
-            .map(component => ({ ...component, score: searchScore(intent, component) }))
-            .sort((left, right) => right.score - left.score || left.key.localeCompare(right.key))
-            .slice(0, Math.max(1, Number(opts.limit) || 8));
-        emit({ intent, items: rows }, () => printTable(['nodeSlug', 'nodeKey', 'action', 'auth', 'score'], rows.map(row => [
-            row.nodeSlug,
-            row.key,
-            row.name,
-            row.nodeAuthRequired ? 'yes' : 'no',
-            row.score,
-        ])));
+        const hasMore = batches.some(batch => batch.hasMore);
+        const scoredRows = batches
+            .flatMap(batch => batch.rows)
+            .filter(component => component.type === undefined ||
+            component.type === null ||
+            String(component.type).toLowerCase() === 'action')
+            .map(component => ({ ...component, score: searchScore(intent, component) }));
+        const hasPositiveScore = scoredRows.some(component => component.score > 0);
+        const rankedRows = hasPositiveScore
+            ? scoredRows
+                .filter(component => component.score > 0)
+                .sort((left, right) => right.score - left.score || left.key.localeCompare(right.key))
+            : scoredRows;
+        const rows = rankedRows.slice(0, Math.max(1, Number(opts.limit) || 8));
+        const rankingSource = scoredRows.length === 0 ? 'none' : hasPositiveScore ? 'local-literal' : 'server';
+        emit({
+            intent,
+            items: rows,
+            rankingSource,
+            pagination: { hasMore },
+            conceptHints,
+        }, () => {
+            if (rows.length === 0) {
+                process.stdout.write('No relevant components matched this intent.\n');
+            }
+            else {
+                printTable(['nodeSlug', 'nodeKey', 'action', 'auth', 'score'], rows.map(row => [
+                    row.nodeSlug,
+                    row.key,
+                    row.name,
+                    row.nodeAuthRequired ? 'yes' : 'no',
+                    row.score,
+                ]));
+            }
+            if (rankingSource === 'server') {
+                process.stdout.write('Note: no local literal match; results remain in the server-ranked order.\n');
+            }
+            if (hasMore) {
+                process.stdout.write('Note: the server has more component results beyond this page; narrow the intent or use --node.\n');
+            }
+            printConceptHints(conceptHints);
+        });
     });
     node
         .command('components')
@@ -319,24 +620,32 @@ export const registerNode = (program) => {
         const props = opts.props
             ? normalizeNodePropWrites(readObjectOption(opts.props, '--props'))
             : undefined;
-        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'add_node', {
-            flowId: opts.flow,
-            nodeSlug,
-            nodeKey: opts.key,
-            connectionId: opts.connection ? Number(opts.connection) : null,
-            ...(opts.name ? { displayName: opts.name } : {}),
-            ...(props ? { props } : {}),
-            ...(opts.enableProp?.length ? { enableOptionalProps: opts.enableProp } : {}),
-            ...(opts.after
-                ? { connectFrom: { sourceNodeId: opts.after, sourceOutput: opts.output } }
-                : {}),
-        }));
-        const [rawRecord, currentProps] = await Promise.all([
+        await guardInitialArrayExpressionWrites(api, workflowId, nodeSlug, opts.key, props);
+        let result;
+        try {
+            result = await api.mutate(workflowId, () => api.tool(workflowId, 'add_node', {
+                flowId: opts.flow,
+                nodeSlug,
+                nodeKey: opts.key,
+                connectionId: opts.connection ? Number(opts.connection) : null,
+                ...(opts.name ? { displayName: opts.name } : {}),
+                ...(props ? { props } : {}),
+                ...(opts.enableProp?.length ? { enableOptionalProps: opts.enableProp } : {}),
+                ...(opts.after
+                    ? { connectFrom: { sourceNodeId: opts.after, sourceOutput: opts.output } }
+                    : {}),
+            }));
+        }
+        catch (error) {
+            rethrowNodeAddOptionalPropError(error);
+        }
+        const [rawRecord, loadedProps] = await Promise.all([
             api.tool(workflowId, 'get_node', { nodeId: result.nodeId }),
             loadProps(api, workflowId, result.nodeId),
         ]);
+        const currentProps = loadedProps.props;
         const record = await addResolvedOutputType(api, workflowId, rawRecord);
-        const readiness = buildNodeReadiness(result.nodeId, record, currentProps);
+        const readiness = buildNodeReadiness(result.nodeId, record, currentProps, loadedProps.subflowTarget);
         const requestedPropNames = Object.keys(props ?? {});
         const propsReadback = currentProps.filter(prop => requestedPropNames.includes(prop.name ?? prop.key ?? ''));
         emit({ ...result, normalizedProps: props ?? {}, propsReadback, readiness }, () => printKeyValues([
@@ -457,15 +766,29 @@ export const registerNode = (program) => {
     node
         .command('declare-output')
         .argument('<nodeId>')
-        .requiredOption('--sample-file <file|->', 'documented response data JSON object; `-` reads stdin')
+        .requiredOption('--sample-file <file|->', 'documented provider response data: a JSON object or a non-empty JSON array of items; `-` reads stdin')
         .description('Declare an unverified dynamic output contract from documented response data')
         .action(async (nodeId, opts, command) => {
         const sample = readNodeOutputSample(opts.sampleFile);
         const { api, workflowId } = requireContext(command);
-        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'declare_node_output_type', {
-            nodeId,
-            sample,
-        }));
+        let result;
+        try {
+            result = await api.mutate(workflowId, () => api.tool(workflowId, 'declare_node_output_type', {
+                nodeId,
+                sample,
+            }));
+        }
+        catch (error) {
+            if (Array.isArray(sample) && error instanceof CaiError) {
+                throw new CaiError(`${error.message}\nArray samples require a newer backend with list-root output declaration support.`, {
+                    exitCode: error.exitCode,
+                    code: error.code,
+                    detail: error.detail,
+                    scrubbed: error.scrubbed,
+                });
+            }
+            throw error;
+        }
         emit(result, () => {
             printKeyValues([
                 ['dataTypeName', result.dataTypeName],
@@ -484,7 +807,17 @@ export const registerNode = (program) => {
         const { api, workflowId } = requireContext(command);
         const data = await api.tool(workflowId, 'get_node_props', { nodeId });
         const props = nodePropsFromPayload(data);
-        emit(data, () => printTable(['name', 'inputType', 'required', 'enabled', 'value', 'valueJs', 'expressionValueJs'], props.map(p => [
+        const hasAvailabilityMetadata = props.some(prop => Object.hasOwn(prop, 'optionsAvailability'));
+        emit(data, () => printTable([
+            'name',
+            'inputType',
+            'required',
+            'enabled',
+            'value',
+            'valueJs',
+            'expressionValueJs',
+            ...(hasAvailabilityMetadata ? ['optionsAvailability', 'blockedBy'] : []),
+        ], props.map(p => [
             p.name ?? p.key,
             p.inputType,
             p.required ? 'yes' : '',
@@ -492,49 +825,99 @@ export const registerNode = (program) => {
             truncate(p.value, 40),
             truncate(p.valueJs, 40),
             truncate(p.expressionValueJs, 40),
+            ...(hasAvailabilityMetadata ? [p.optionsAvailability ?? '', p.blockedBy ?? ''] : []),
         ])));
     });
+    node
+        .command('reload')
+        .argument('<nodeId>')
+        .description('Reload and reconcile dependent props, then report the readiness change')
+        .action(async (nodeId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const before = await loadNodeReadiness(api, workflowId, nodeId);
+        let result;
+        try {
+            result = await api.mutate(workflowId, () => api.tool(workflowId, 'reload_node_props', { nodeId }));
+        }
+        catch (error) {
+            if (isUnknownToolError(error)) {
+                const recoveryCommand = `cai node set ${nodeId} --prop <selector> --value <value>`;
+                throw userError('`cai node reload` is not supported by this backend. Re-set a selector value with ' +
+                    `\`${recoveryCommand}\` to trigger the implicit reload.`, 'NODE_RELOAD_UNSUPPORTED');
+            }
+            throw error;
+        }
+        requireCompletedExplicitPropReload(result, nodeId);
+        const after = await loadNodeReadiness(api, workflowId, nodeId);
+        const readinessDelta = nodeReadinessDelta(before.readiness, after.readiness);
+        const resultFields = result && typeof result === 'object' && !Array.isArray(result)
+            ? result
+            : { result };
+        emit({ ...resultFields, readiness: after.readiness, readinessDelta }, () => printKeyValues([
+            ['propsReloaded', resultFields.propsReloaded ?? 'not reported'],
+            ['propsReconciled', resultFields.propsReconciled ?? 'not reported'],
+            ...(resultFields.reconcileSkipped !== undefined
+                ? [['reconcileSkipped', resultFields.reconcileSkipped]]
+                : []),
+            ...(resultFields.note !== undefined
+                ? [['note', resultFields.note]]
+                : []),
+            ['readiness', `${readinessDelta.before} -> ${readinessDelta.after}`],
+            ['blockers resolved', readinessDelta.blockersResolved.join(', ') || 'none'],
+            ['blockers added', readinessDelta.blockersAdded.join(', ') || 'none'],
+            ['next', after.readiness.next],
+        ]));
+    });
     node
         .command('status')
         .argument('<nodeId>')
         .description('Return deterministic configuration readiness and exact blockers')
         .action(async (nodeId, _opts, command) => {
         const { api, workflowId } = requireContext(command);
-        const [record, props] = await Promise.all([
-            api.tool(workflowId, 'get_node', { nodeId }),
-            loadProps(api, workflowId, nodeId),
-        ]);
-        const resolvedRecord = await addResolvedOutputType(api, workflowId, record);
-        const readiness = buildNodeReadiness(nodeId, resolvedRecord, props);
-        const outputTypeDeclared = nodeProcessOutput(resolvedRecord)?.declared === true;
+        const { record, readiness } = await loadNodeReadiness(api, workflowId, nodeId);
+        const outputTypeDeclared = nodeProcessOutput(record)?.declared === true;
         const payload = {
             ...readiness,
             ...(outputTypeDeclared ? { outputTypeDeclared: true } : {}),
         };
-        emit(payload, () => printKeyValues([
-            ['nodeId', nodeId],
-            [
-                'connection',
-                payload.missingConnection ? 'missing' : (payload.connectionId ?? 'not required'),
-            ],
-            ['required props', payload.missingRequiredProps.join(', ') || 'complete'],
-            ['reload selectors', payload.pendingReloadProps.join(', ') || 'complete'],
-            [
-                'output type',
-                `${payload.outputTypeStatus}${payload.outputTypes.length
-                    ? ` (${payload.outputTypes
-                        .map(type => renderNodeOutputType(type, outputTypeDeclared && payload.outputTypeSource === 'processOutput'))
-                        .join(', ')})`
-                    : ''} via ${payload.outputTypeSource}`,
-            ],
-            ['ready for expressions', payload.readyForExpressions ? 'yes' : 'no'],
-            ['ready to run', payload.readyForRun ? 'yes' : 'no'],
-            [
-                'ready for downstream expressions',
-                payload.readyForDownstreamExpressions ? 'yes' : 'no',
-            ],
-            ['next', payload.next],
-        ]));
+        emit(payload, () => {
+            printKeyValues([
+                ['nodeId', nodeId],
+                [
+                    'connection',
+                    payload.missingConnection ? 'missing' : (payload.connectionId ?? 'not required'),
+                ],
+                ['required props', payload.missingRequiredProps.join(', ') || 'complete'],
+                [
+                    'required disabled props',
+                    payload.disabledRequiredProps.join(', ') || 'none',
+                ],
+                ['reload selectors', payload.pendingReloadProps.join(', ') || 'complete'],
+                [
+                    'output type',
+                    `${payload.outputTypeStatus}${payload.outputTypes.length
+                        ? ` (${payload.outputTypes
+                            .map(type => renderNodeOutputType(type, outputTypeDeclared && payload.outputTypeSource === 'processOutput'))
+                            .join(', ')})`
+                        : ''} via ${payload.outputTypeSource}`,
+                ],
+                ['readiness state', payload.readinessState],
+                ['blockers', payload.blockedBy.join(', ') || 'none'],
+                ['ready for expressions', payload.readyForExpressions ? 'yes' : 'no'],
+                ['ready to run', payload.readyForRun ? 'yes' : 'no'],
+                [
+                    'ready for downstream expressions',
+                    payload.readyForDownstreamExpressions ? 'yes' : 'no',
+                ],
+                ['next', payload.next],
+            ]);
+            if (payload.dynamicSelectorNotes.length) {
+                process.stdout.write('\ndynamic selector notes\n');
+                for (const note of payload.dynamicSelectorNotes) {
+                    process.stdout.write(`  ${note}\n`);
+                }
+            }
+        });
     });
     node
         .command('set')
@@ -555,32 +938,52 @@ export const registerNode = (program) => {
         if (js !== undefined && opts.value !== undefined) {
             throw userError('--value is mutually exclusive with --js and --js-file.', 'CONFLICTING_VALUE');
         }
-        const prop = await findProp(api, workflowId, nodeId, opts.prop);
-        const persistedExpressionChannel = expressionReadbackChannel(prop);
+        let compiledJs = js;
+        const prop = (await prepareWritableProp(api, workflowId, nodeId, opts.prop, candidate => {
+            if (compiledJs === undefined && String(candidate.inputType ?? '') === 'CUSTOM_DATA') {
+                const literal = parseLiteral(opts.value);
+                const supported = typeof literal === 'string' ||
+                    typeof literal === 'boolean' ||
+                    (typeof literal === 'number' && Number.isFinite(literal));
+                if (!supported) {
+                    throw userError(`--value for CUSTOM_DATA only supports string, finite number, or boolean literals. ` +
+                        'Use a typed --js expression for null, arrays, or objects; nothing was written.', 'CUSTOM_DATA_LITERAL_UNSUPPORTED');
+                }
+                compiledJs = JSON.stringify(literal);
+            }
+            if (compiledJs !== undefined) {
+                assertArrayExpressionWriteSupported(nodeId, opts.prop, candidate, undefined);
+            }
+        }));
         if (opts.expression) {
             warn('`--expression` is no longer needed; the CLI selects the correct storage channel.');
         }
-        if (js !== undefined) {
+        let validation;
+        if (compiledJs !== undefined) {
             // Compile FIRST. update_node_prop would also compile, but validating as
             // a separate read-only call guarantees a failed expression writes
             // nothing and lets us print the compiler error verbatim.
-            const validation = await api.tool(workflowId, 'validate_expression', {
-                js,
+            validation = await api.tool(workflowId, 'validate_expression', {
+                js: compiledJs,
                 nodeId,
                 propName: opts.prop,
             });
             if (validationFailed(validation)) {
                 throw userError(`Expression did not compile — nothing was written.\n\n${validationMessage(validation)}`, 'EXPRESSION_COMPILE_ERROR');
             }
+            assertArrayExpressionWriteSupported(nodeId, opts.prop, prop, validation?.inferredType);
+            const replacementWarning = arrayExpressionReplacementWarning(opts.prop, prop);
+            if (replacementWarning)
+                warn(replacementWarning);
             for (const w of validation?.warnings ?? [])
                 warn(String(w));
         }
         const payload = { nodeId, key: opts.prop };
-        if (js !== undefined) {
+        if (compiledJs !== undefined) {
             // valueJs is intentionally the one public write channel. The backend
             // resolves the prop's real compile target and routes the compiled value
             // into value or expressionValue as appropriate.
-            payload.valueJs = js;
+            payload.valueJs = compiledJs;
         }
         else if (isTextExpressionBackedProp(prop)) {
             // These props persist as a TextExpression wrapping the raw TEXT. The backend does
@@ -606,73 +1009,146 @@ export const registerNode = (program) => {
         // half-configured prop (CFG-004, CFG-012). When a provider does not index opaque ids,
         // caller-supplied --label is used only as the search query; the returned value must still
         // match before anything is persisted.
-        if (js === undefined) {
+        let skippedDynamicOptionValidation = false;
+        if (compiledJs === undefined) {
             const selected = Array.isArray(payload.value) ? payload.value : [payload.value];
-            const queries = optionLookupQueries(selected, suppliedLabels);
-            const optionBatches = prop.remoteOptions
-                ? await Promise.all(queries.map(query => fetchPropOptions(api, workflowId, nodeId, opts.prop, query)))
-                : [
-                    (prop.options ?? []).map(option => ({
-                        value: String(option.value ?? option.id ?? ''),
-                        label: String(option.label ?? option.name ?? option.value ?? option.id ?? ''),
-                    })),
-                ];
-            const options = [
-                ...new Map(optionBatches.flat().map(option => [option.value, option])).values(),
-            ];
-            if (prop.remoteOptions && options.length === 0) {
-                throw userError(`No live options were returned for ${opts.prop}. Check the connection and earlier ` +
-                    'selector props. If you copied an opaque value from `cai node options`, also pass ' +
-                    'its displayed label with `--label`; nothing was written.', 'OPTIONS_UNAVAILABLE');
+            const metadataBlockedBy = typeof prop.blockedBy === 'string' && prop.blockedBy.trim()
+                ? prop.blockedBy.trim()
+                : undefined;
+            if (prop.optionsAvailability === 'blocked_upstream' && metadataBlockedBy) {
+                throwBlockedUpstreamOption(nodeId, opts.prop, metadataBlockedBy);
             }
-            if (options.length) {
-                const labelFor = (value) => options.find(option => option.value === String(value));
-                const unknown = selected.filter(value => !labelFor(value)).map(value => String(value));
-                if (unknown.length) {
-                    throw userError(`${unknown.map(value => `"${value}"`).join(', ')} is not a valid option for ` +
-                        `${opts.prop}. Run \`cai node options ${nodeId} --prop ${opts.prop} --query ` +
-                        `"<display label>"\`, then retry with the exact returned --value and --label. ` +
-                        'Nothing was written.', 'UNKNOWN_OPTION');
+            skippedDynamicOptionValidation = prop.optionsAvailability === 'dynamic_upstream';
+            if (!skippedDynamicOptionValidation) {
+                const queries = optionLookupQueries(selected, suppliedLabels);
+                let fetched = [];
+                if (prop.remoteOptions) {
+                    try {
+                        fetched = await Promise.all(queries.map(query => fetchPropOptions(api, workflowId, nodeId, opts.prop, query)));
+                    }
+                    catch (error) {
+                        const blocked = blockedUpstreamOptionMessage(error);
+                        if (blocked) {
+                            throwBlockedUpstreamOption(nodeId, blocked.propName, blocked.blockedBy);
+                        }
+                        throw error;
+                    }
+                }
+                skippedDynamicOptionValidation = fetched.some(batch => dynamicUpstreamOptionError(batch.error));
+                const optionBatches = prop.remoteOptions
+                    ? fetched.map(batch => batch.options)
+                    : [
+                        (prop.options ?? []).map(option => ({
+                            value: String(option.value ?? option.id ?? ''),
+                            label: String(option.label ?? option.name ?? option.value ?? option.id ?? ''),
+                        })),
+                    ];
+                const options = [
+                    ...new Map(optionBatches.flat().map(option => [option.value, option])).values(),
+                ];
+                if (!skippedDynamicOptionValidation && prop.remoteOptions && options.length === 0) {
+                    throw userError(`No live options were returned for ${opts.prop}. Check the connection and earlier ` +
+                        'selector props. If you copied an opaque value from `cai node options`, also pass ' +
+                        'its displayed label with `--label`; nothing was written.', 'OPTIONS_UNAVAILABLE');
                 }
-                if (isOptionBackedProp(prop)) {
-                    const resolved = selected.map(value => labelFor(value));
-                    payload.valueLabel = isMultiSelectProp(prop)
-                        ? resolved.map(option => ({ value: option.value, label: option.label }))
-                        : resolved[0].label;
+                if (!skippedDynamicOptionValidation && options.length) {
+                    const labelFor = (value) => options.find(option => option.value === String(value));
+                    const unknown = selected.filter(value => !labelFor(value)).map(value => String(value));
+                    if (unknown.length) {
+                        throw userError(`${unknown.map(value => `"${value}"`).join(', ')} is not a valid option for ` +
+                            `${opts.prop}. Run \`cai node options ${nodeId} --prop ${opts.prop} --query ` +
+                            `"<display label>"\`, then retry with the exact returned --value and --label. ` +
+                            'Nothing was written.', 'UNKNOWN_OPTION');
+                    }
+                    if (isOptionBackedProp(prop)) {
+                        const resolved = selected.map(value => labelFor(value));
+                        payload.valueLabel = optionValueLabel(prop, resolved);
+                    }
+                }
+            }
+            if (skippedDynamicOptionValidation && prop.withLabel === true) {
+                const canBuildValueLabel = !isMultiSelectProp(prop) ||
+                    (Array.isArray(payload.value) &&
+                        payload.value.every(value => typeof value === 'string' ||
+                            (typeof value === 'number' && Number.isFinite(value))));
+                if (canBuildValueLabel) {
+                    const labels = optionLookupQueries(selected, suppliedLabels);
+                    payload.valueLabel = optionValueLabel(prop, selected.map((value, index) => ({
+                        value,
+                        label: labels[index],
+                    })));
                 }
             }
         }
         const result = await api.mutate(workflowId, () => api.tool(workflowId, 'update_node_prop', payload));
-        const retryCommand = `cai node set ${nodeId} --prop ${opts.prop}` +
-            (opts.value !== undefined
-                ? ` --value ${shellQuote(String(opts.value))}` +
-                    (suppliedLabels.length
-                        ? ` --label ${suppliedLabels.map(label => shellQuote(label)).join(' ')}`
-                        : '')
-                : ' --value <same-value>');
-        requireCompletedPropReload(result, nodeId, opts.prop, retryCommand);
-        const readback = await findProp(api, workflowId, nodeId, opts.prop);
-        const persistedChannel = js !== undefined ? persistedExpressionChannel : 'value';
-        if (js !== undefined && !readback[persistedChannel]) {
-            throw userError(`The write returned successfully but ${opts.prop}.${persistedChannel} did not read back.`, 'READBACK_MISMATCH');
-        }
-        if (js === undefined && readback.value === undefined) {
+        if (skippedDynamicOptionValidation)
+            warn(DYNAMIC_UPSTREAM_RAW_VALUE_NOTE);
+        requireCompletedPropReload(result, nodeId, opts.prop);
+        const readback = (await requireReadbackProp(api, workflowId, nodeId, opts.prop));
+        let persistedChannel = 'value';
+        let persistenceKind;
+        let persistedValue;
+        let note;
+        if (compiledJs !== undefined) {
+            const verification = verifyExpressionPersistence(prop, readback, validation?.expression);
+            if (!verification.verified) {
+                throw new CaiError(expressionPersistenceMismatchMessage(opts.prop, verification), {
+                    code: 'READBACK_MISMATCH',
+                    detail: {
+                        nodeId,
+                        prop: opts.prop,
+                        expected: verification.expected,
+                        observed: verification.observed,
+                    },
+                });
+            }
+            persistedChannel = verification.channel;
+            persistenceKind = verification.kind;
+            persistedValue = verification.persistedValue;
+            note = remoteOptionsCompiledLiteralNote(prop, verification);
+        }
+        if (compiledJs === undefined && readback?.value === undefined) {
             throw userError(`The write returned successfully but ${opts.prop}.value did not read back.`, 'READBACK_MISMATCH');
         }
+        const mode = js !== undefined ? 'js' : compiledJs !== undefined ? 'literal (compiled)' : 'static';
+        const humanMode = js !== undefined ? 'expression (compiled)' : mode;
+        const source = js !== undefined
+            ? 'explicit --js'
+            : compiledJs !== undefined
+                ? 'synthesized from --value'
+                : 'explicit --value';
+        const rawDynamicSelectorNote = result && typeof result === 'object' && !Array.isArray(result)
+            ? result.dynamicSelectorNote
+            : undefined;
+        const dynamicSelectorNote = typeof rawDynamicSelectorNote === 'string' && rawDynamicSelectorNote.trim()
+            ? rawDynamicSelectorNote
+            : undefined;
         emit({
             nodeId,
             prop: opts.prop,
-            mode: js !== undefined ? 'js' : 'static',
+            mode,
+            source,
             persistedChannel,
+            ...(persistenceKind ? { kind: persistenceKind, persistedValue } : {}),
+            ...(note ? { note } : {}),
+            ...(dynamicSelectorNote ? { dynamicSelectorNote } : {}),
             readback,
             result,
-        }, () => printKeyValues([
-            ['nodeId', nodeId],
-            ['prop', opts.prop],
-            ['mode', js !== undefined ? 'expression (compiled)' : 'static'],
-            ['persisted channel', persistedChannel],
-            ['verified', 'yes'],
-        ]));
+        }, () => {
+            printKeyValues([
+                ['nodeId', nodeId],
+                ['prop', opts.prop],
+                ['mode', humanMode],
+                ['source', source],
+                ['persisted channel', persistedChannel],
+                ...(persistenceKind ? [['kind', persistenceKind]] : []),
+                ['verified', 'yes'],
+            ]);
+            if (note)
+                process.stdout.write(`\n${note}\n`);
+            if (dynamicSelectorNote)
+                process.stdout.write(`\n${dynamicSelectorNote}\n`);
+        });
     });
     node
         .command('set-connection')
@@ -785,6 +1261,59 @@ export const registerNode = (program) => {
         const result = await api.mutate(workflowId, () => api.tool(workflowId, 'enable_optional_prop', { nodeId, propName: opts.prop }));
         emit(result, () => printKeyValues([['enabled', `${nodeId}.${opts.prop}`]]));
     });
+    node
+        .command('disable-prop')
+        .argument('<nodeId>')
+        .requiredOption('--prop <name>', 'enabled optional prop key from `cai node props`')
+        .description('Disable an optional prop. Its stored value is removed when present; a reload prop may prune dependent props')
+        .action(async (nodeId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        let result;
+        try {
+            result = await api.mutate(workflowId, () => api.tool(workflowId, 'disable_optional_prop', { nodeId, propName: opts.prop }));
+        }
+        catch (error) {
+            if (isUnknownToolError(error)) {
+                throw new CaiError(`${error.message}\nThis backend predates disable_optional_prop. Disable ` +
+                    `"${opts.prop}" on ${nodeId} in the builder instead.`, {
+                    exitCode: error.exitCode,
+                    code: error.code,
+                    detail: error.detail,
+                    scrubbed: error.scrubbed,
+                });
+            }
+            throw error;
+        }
+        const { props } = await loadProps(api, workflowId, nodeId);
+        const readback = props.find(row => (row.name ?? row.key) === opts.prop);
+        const disabled = readback === undefined || readback.source === 'propsCatalog' || readback.enabled === false;
+        if (!disabled) {
+            throw new CaiError(`Prop "${opts.prop}" did not read back as disabled after the backend accepted the ` +
+                'request; its stored value may still be present. ' +
+                `Inspect \`cai node props ${nodeId} --json\` before continuing.`, {
+                code: 'READBACK_MISMATCH',
+                detail: { nodeId, prop: opts.prop, readback },
+            });
+        }
+        const resultFields = result && typeof result === 'object' && !Array.isArray(result)
+            ? result
+            : { result };
+        emit({
+            ...resultFields,
+            nodeId,
+            prop: opts.prop,
+            enabled: false,
+            verified: true,
+            readback: readback ?? null,
+        }, () => printKeyValues([
+            ['disabled', `${nodeId}.${opts.prop}`],
+            [
+                'stored value',
+                resultFields.storedValueRemoved === true ? 'removed' : 'no stored value existed',
+            ],
+            ['verified', 'yes'],
+        ]));
+    });
     node
         .command('options')
         .argument('<nodeId>')
@@ -792,18 +1321,62 @@ export const registerNode = (program) => {
         // keep in sync with fetchPropOptions() below, which reuses this tool
         .option('--query <q>', 'search term — strongly preferred over paging')
         .option('--page <n>', '0-based page when not searching')
+        .option('--prev-context <json>', 'pagination context returned by a previous options response')
+        .option('--for <prop>=<value>', 'override an earlier prop value for option resolution; JSON literals are accepted, bare text is passed as a string; repeatable', collectNodeOptionOverride)
         .description('Resolved remote dropdown options for a prop')
         .action(async (nodeId, opts, command) => {
-        const { api, workflowId } = requireContext(command);
         const page = parseNodeOptionPage(opts.page);
-        const data = await api.tool(workflowId, 'get_prop_options', {
-            nodeId,
-            propName: opts.prop,
-            ...(opts.query ? { query: opts.query } : {}),
-            ...(page !== undefined ? { page } : {}),
-        });
+        const prevContext = opts.prevContext !== undefined
+            ? parseNodeOptionsPrevContext(opts.prevContext)
+            : undefined;
+        const formValueOverrides = parseNodeOptionOverrides(opts.for ?? []);
+        const { api, workflowId } = requireContext(command);
+        let data;
+        try {
+            data = await api.tool(workflowId, 'get_prop_options', {
+                nodeId,
+                propName: opts.prop,
+                ...(opts.query ? { query: opts.query } : {}),
+                ...(page !== undefined ? { page } : {}),
+                ...(prevContext ? { prevContext } : {}),
+                ...(Object.keys(formValueOverrides).length ? { formValueOverrides } : {}),
+            });
+        }
+        catch (error) {
+            const blocked = blockedUpstreamOptionMessage(error);
+            if (blocked) {
+                throwBlockedUpstreamOption(nodeId, blocked.propName, blocked.blockedBy);
+            }
+            throw error;
+        }
+        const dynamicUpstreamNext = dynamicUpstreamOptionError(data?.error)
+            ? dynamicUpstreamOptionNext(nodeId, opts.prop)
+            : undefined;
+        const outputData = dynamicUpstreamNext && data && typeof data === 'object' && !Array.isArray(data)
+            ? { ...data, next: dynamicUpstreamNext }
+            : data;
         const rows = data?.options ?? (Array.isArray(data) ? data : []);
-        emit(data, () => printTable(['value', 'label'], rows.map(o => [o.value ?? o.id, o.label ?? o.name])));
+        emit(outputData, () => {
+            if (!Array.isArray(data) && typeof data?.error === 'string' && data.error.trim()) {
+                printKeyValues([
+                    ['error', data.error],
+                    ...(dynamicUpstreamNext
+                        ? [['next', dynamicUpstreamNext]]
+                        : []),
+                ]);
+                process.stdout.write('\n');
+            }
+            printTable(['value', 'label'], rows.map(o => [o.value ?? o.id, o.label ?? o.name]));
+            if (!Array.isArray(data) &&
+                data &&
+                typeof data === 'object' &&
+                Object.hasOwn(data, 'context') &&
+                data.context !== undefined &&
+                data.context !== null) {
+                process.stdout.write(`\ncontext  ${JSON.stringify(data.context)}\n`);
+                process.stdout.write('Pass this context back with --prev-context to continue.\n');
+            }
+        });
     });
     node
         .command('continue-on-error')