fix: address review findings from PR #1719

- Remove issue number refs (#1717, #1651) from comments per CLAUDE.md
- Trim multi-line JSDoc on extractNodeOutputEnvVars to 2-line comment
- Remove regex comment that explained WHAT not WHY
- Trim escapedForBash trailing comment
- Add collision guard warn log when two node IDs map to the same env var
- Spread config.envVars into until_bash subprocess for parity with executeBashNode
- Update variables.md: replace stale "auto shell-quoted" description with env-var mechanism
- Update script-nodes.md: fix stale contrast with bash node auto-quoting
- Add CHANGELOG entry for #1717 fix
- Add integration tests: executeBashNode and until_bash env var wiring via spy
- Add empty-string output unit test for extractNodeOutputEnvVars

Author: Wirasm

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - MCP server support for Codex workflow nodes via the shared `loadMcpConfig` module — pass `mcp: <path>` on a Codex node and the config is translated to Codex's `mcp_servers` overrides at runtime. MCP client errors are surfaced to the workflow author as `system` chunks when MCP is explicitly configured for the node (#1459).
 
+### Fixed
+
+- **Bash node large-output corruption**: whole-output `$nodeId.output` refs in `bash:` and `until_bash` loop conditions now travel via environment variables instead of inline shell-quoting. Inputs of any size (including 40 KB+ LLM outputs) are handled correctly. Field-access refs (`$nodeId.output.field`) are unaffected. Closes #1717.
+
 ## [0.3.12] - 2026-05-14
 
 Orchestrator prompt-cache fix, SDK termination edge cases, marketplace expansion, and broad workflow fixes.

packages/docs-web/src/content/docs/guides/script-nodes.md

@@ -199,9 +199,10 @@ for field access in `when:` conditions and prompt substitution.
 ### Variable Substitution in Scripts
 
 Variables are substituted into the `script` text **as raw strings, without
-shell quoting** — unlike `bash:` nodes, where `$nodeId.output` values are
-auto-quoted. Treat substituted values as untrusted input and parse them with
-language features, not by interpolating into shell syntax.
+shell quoting** — unlike `bash:` nodes, where `$nodeId.output` whole-output
+values are passed safely via environment variables. Treat substituted values
+as untrusted input and parse them with language features, not by interpolating
+into shell syntax.
 
 :::caution[Avoid String.raw with `$nodeId.output`]
 The pattern `` String.raw`$nodeId.output` `` looks safe but fails silently when

packages/docs-web/src/content/docs/reference/variables.md

@@ -67,7 +67,7 @@ In DAG workflows, nodes can reference the output of any completed upstream node.
 
 ### Shell Quoting in `bash:` vs `script:`
 
-`$nodeId.output` values are **auto shell-quoted** (single-quoted, with embedded `'` escaped) when substituted into `bash:` scripts, so the value is always safe to embed in a shell command. They are **not** shell-quoted when substituted into `script:` bodies — the raw value is embedded as-is. For script nodes, treat substituted values as untrusted input and parse them with language features (e.g. `JSON.parse`), not by interpolating into shell syntax.
+In `bash:` nodes, `$nodeId.output` (whole-output) is passed into the script via a dedicated environment variable (`_ARCHON_NODE_<ID>_OUTPUT`) and referenced as `"${_ARCHON_NODE_<ID>_OUTPUT}"`. This avoids size limits that inline argument quoting imposes on large LLM outputs. Field-access refs (`$nodeId.output.field`) are still substituted inline as shell-quoted strings. Values are **not** shell-quoted when substituted into `script:` bodies — the raw value is embedded as-is. For script nodes, treat substituted values as untrusted input and parse them with language features (e.g. `JSON.parse`), not by interpolating into shell syntax.
 
 ### Example
 

packages/workflows/src/dag-executor.test.ts

@@ -891,6 +891,13 @@ describe('extractNodeOutputEnvVars', () => {
     expect(script).toBe('echo $a.output.field_name');
     expect(envVars).toEqual({});
   });
+
+  it('handles empty string node output', () => {
+    const outputs = new Map([['a', makeOutput('completed', '')]]);
+    const { script, envVars } = extractNodeOutputEnvVars('echo $a.output', outputs);
+    expect(script).toBe('echo "${_ARCHON_NODE_A_OUTPUT}"');
+    expect(envVars).toEqual({ _ARCHON_NODE_A_OUTPUT: '' });
+  });
 });
 
 describe('substituteNodeOutputRefs -- structuredOutput preference', () => {
@@ -1612,6 +1619,110 @@ describe('executeDagWorkflow -- bash nodes', () => {
       execSpy.mockRestore();
     }
   });
+
+  it('passes $nodeId.output value via _ARCHON_NODE_* env var in executeBashNode', async () => {
+    const execSpy = spyOn(git, 'execFileAsync').mockResolvedValue({ stdout: 'ok\n', stderr: '' });
+    try {
+      const mockDeps = createMockDeps();
+      const platform = createMockPlatform();
+      const workflowRun = makeWorkflowRun('bash-env-var-run-id');
+      const upstreamOutput = 'upstream value with $special "chars"';
+
+      const nodes: DagNode[] = [
+        { id: 'upstream', bash: 'echo upstream' },
+        { id: 'consumer', bash: 'echo $upstream.output', depends_on: ['upstream'] },
+      ];
+
+      await executeDagWorkflow(
+        mockDeps,
+        platform,
+        'conv-env-var',
+        testDir,
+        { name: 'env-var-test', nodes },
+        workflowRun,
+        'claude',
+        undefined,
+        join(testDir, 'artifacts'),
+        join(testDir, 'logs'),
+        'main',
+        'docs/',
+        minimalConfig,
+        undefined,
+        undefined,
+        new Map([['upstream', upstreamOutput]])
+      );
+
+      const consumerCall = execSpy.mock.calls.find(call => {
+        const script = (call[1] as string[])[1] ?? '';
+        return script.includes('_ARCHON_NODE_UPSTREAM_OUTPUT');
+      });
+      expect(consumerCall).toBeDefined();
+      const envArg = (consumerCall![2] as { env: NodeJS.ProcessEnv }).env;
+      expect(envArg?._ARCHON_NODE_UPSTREAM_OUTPUT).toBe(upstreamOutput);
+    } finally {
+      execSpy.mockRestore();
+    }
+  });
+
+  it('passes $nodeId.output via _ARCHON_NODE_* env var in until_bash', async () => {
+    // until_bash returning exit 0 signals loop completion; mock it to exit 0
+    const execSpy = spyOn(git, 'execFileAsync').mockResolvedValue({ stdout: '', stderr: '' });
+    try {
+      mockSendQueryDag.mockImplementation(function* () {
+        yield { type: 'assistant', content: 'Done. <promise>COMPLETE</promise>' };
+        yield { type: 'result', sessionId: 'loop-until-bash-session' };
+      });
+
+      const mockDeps = createMockDeps();
+      const platform = createMockPlatform();
+      const workflowRun = makeWorkflowRun('until-bash-env-run-id');
+      const upstreamOutput = 'done';
+
+      // upstream is a bash node whose output is pre-seeded via priorCompletedNodes
+      const nodes: DagNode[] = [
+        { id: 'upstream', bash: 'echo upstream' },
+        {
+          id: 'check',
+          loop: {
+            prompt: 'Do work.',
+            until_bash: 'test $upstream.output = "done"',
+            until: 'COMPLETE',
+            max_iterations: 1,
+          },
+          depends_on: ['upstream'],
+        },
+      ];
+
+      await executeDagWorkflow(
+        mockDeps,
+        platform,
+        'conv-until-bash-env',
+        testDir,
+        { name: 'until-bash-env-test', nodes },
+        workflowRun,
+        'claude',
+        undefined,
+        join(testDir, 'artifacts'),
+        join(testDir, 'logs'),
+        'main',
+        'docs/',
+        minimalConfig,
+        undefined,
+        undefined,
+        new Map([['upstream', upstreamOutput]])
+      );
+
+      const bashCall = execSpy.mock.calls.find(call => {
+        const script = (call[1] as string[])[1] ?? '';
+        return script.includes('_ARCHON_NODE_UPSTREAM_OUTPUT');
+      });
+      expect(bashCall).toBeDefined();
+      const envArg = (bashCall![2] as { env: NodeJS.ProcessEnv }).env;
+      expect(envArg?._ARCHON_NODE_UPSTREAM_OUTPUT).toBe(upstreamOutput);
+    } finally {
+      execSpy.mockRestore();
+    }
+  });
 });
 
 describe('executeDagWorkflow -- output_format structured output', () => {

packages/workflows/src/dag-executor.ts

@@ -233,22 +233,14 @@ function shellQuote(value: string): string {
   return `'${value.replaceAll("'", "'\\''")}'`;
 }
 
-/**
- * For bash node scripts: replaces $nodeId.output references (whole-output, no .field)
- * with env-var expansions ("${_ARCHON_NODE_<ID>_OUTPUT}") and returns the env vars
- * to inject into the subprocess environment.
- *
- * This avoids inline shell-quoting of arbitrarily large LLM outputs — the same
- * pattern used for $USER_MESSAGE / $ARGUMENTS / $LOOP_* since #1651.
- * Field-access refs ($nodeId.output.field) are left for substituteNodeOutputRefs.
- */
+// Replaces whole-output $nodeId.output refs with env-var expansions to avoid
+// inline shell-quoting of large LLM outputs. Field refs left for substituteNodeOutputRefs.
 export function extractNodeOutputEnvVars(
   script: string,
   nodeOutputs: Map<string, NodeOutput>
 ): { script: string; envVars: Record<string, string> } {
   const envVars: Record<string, string> = {};
   const modifiedScript = script.replace(
-    // Match $nodeId.output NOT followed by .fieldname (negative lookahead)
     /\$([a-zA-Z_][a-zA-Z0-9_-]*)\.output(?!\.[a-zA-Z_])/g,
     (match, nodeId: string) => {
       const nodeOutput = nodeOutputs.get(nodeId);
@@ -257,6 +249,9 @@ export function extractNodeOutputEnvVars(
         return match;
       }
       const envVarName = `_ARCHON_NODE_${nodeId.replace(/-/g, '_').toUpperCase()}_OUTPUT`;
+      if (envVarName in envVars) {
+        getLog().warn({ nodeId, envVarName }, 'dag.node_output_env_var_collision');
+      }
       envVars[envVarName] = nodeOutput.output;
       // Double-quoted expansion: prevents word-splitting without inline quoting
       return `"\${${envVarName}}"`;
@@ -1335,7 +1330,7 @@ async function executeBashNode(
     { shellSafe: true }
   );
   // Pass $nodeId.output (whole output) via env vars to avoid inline shell-quoting of
-  // large values — see #1717. Field-access refs ($nodeId.output.field) remain inline.
+  // large values. Field-access refs ($nodeId.output.field) remain inline.
   const { script: scriptWithEnvVarRefs, envVars: nodeOutputEnvVars } = extractNodeOutputEnvVars(
     substitutedScript,
     nodeOutputs
@@ -2178,13 +2173,13 @@ async function executeLoopNode(
           undefined,
           { shellSafe: true }
         );
-        // Pass $nodeId.output via env vars to avoid inline shell-quoting of large values — see #1717.
+        // Pass $nodeId.output via env vars to avoid inline shell-quoting of large values.
         const { script: bashWithEnvVarRefs, envVars: untilBashNodeEnvVars } =
           extractNodeOutputEnvVars(bashPrompt, nodeOutputs);
         const substitutedBash = substituteNodeOutputRefs(
           bashWithEnvVarRefs,
           nodeOutputs,
-          true // escapedForBash — field refs only remain
+          true // escapedForBash
         );
         await execFileAsync('bash', ['-c', substitutedBash], {
           cwd,
@@ -2200,6 +2195,7 @@ async function executeLoopNode(
             EXTERNAL_CONTEXT: issueContext ?? '',
             ISSUE_CONTEXT: issueContext ?? '',
             ...untilBashNodeEnvVars,
+            ...(config.envVars ?? {}),
           },
         });
         bashComplete = true; // exit 0 = complete