codex - 💡(How to fix) Fix Shell snapshot validation fails on env vars containing single-quoted empty strings (`''`) — broken escape sequence

Summary

Codex CLI's shell_snapshot validation fails with syntax error: unterminated quoted string when an exported environment variable contains a JSON payload with embedded single-quoted empty strings (e.g., SQL '' literals in code blocks).

The escape logic produces a malformed sequence:

'"''"'    ← generated (broken — unbalanced quotes)
'"'"'     ← correct shell-escape of a single quote within single-quoted strings

Environment

• codex-cli version: 0.130.0
• Adapter: codex_local (Paperclip)
• Triggering env var in our case: PAPERCLIP_WAKE_PAYLOAD_JSON — a JSON-encoded payload Paperclip passes containing the issue description verbatim

Repro

1. Have an agent in Paperclip with the codex_local adapter

2. Create or update an issue whose description contains SQL or other code with '' (empty single-quoted string) — common patterns:

   COALESCE(field, '')          -- SQL fallback
   v_last_name := '';           -- assignment

3. Wake the agent on that issue (e.g., add a comment to trigger wake)

4. Codex CLI invokes its shell-snapshot phase, attempting to export PAPERCLIP_WAKE_PAYLOAD_JSON with the JSON containing the description verbatim

5. The escape pass mangles the '' sequence

6. The resulting snapshot file contains a line like:

   export PAPERCLIP_WAKE_PAYLOAD_JSON='{...COALESCE(NEW.email, '"''"')...}'

   The '"''"' sub-sequence parses as: close-quote → open-double-quote-with-' → close-double-quote → open-double-quote → ... → unterminated string

7. Snapshot validation fails:

   ERROR codex_core::shell_snapshot: Snapshot command exited with status exit status: 2:
   /bin/sh: .../shell_snapshots/<id>.tmp-...: line 52: syntax error: unterminated quoted string

Impact

• Non-fatal for the run itself (Codex continues without the snapshot)
• Loss of shell context for the session (aliases, function defs not restored)
• Log noise at every wake involving an affected issue
• Confusing for ops — looks scary in stderr, hard to diagnose without reading the actual snapshot file

Workaround

Edit the offending issue description to remove or escape the '' pattern. Replace with:

• EMPTY_STRING placeholder text
• ' ' (with a separator)
• Escape with backslashes or use code-fence prose instead of SQL inline

This works but is fragile — every new issue or comment with the pattern triggers the bug again.

Suggested fix

In Codex CLI's shell snapshot generation logic, the routine that escapes single quotes inside a single-quoted string should produce the canonical '"'"' sequence, regardless of adjacent characters. The current implementation appears to special-case adjacent single quotes incorrectly.

Test cases to add:

• Empty string literal: ''
• Single quote followed by another quote: '''
• JSON with embedded SQL: {"sql": "COALESCE(x, '')"}

Real-world occurrence

Encountered on Paperclip 2026-05-18 with agent Senior Release Manager IMPULSION. The issue description (markdown) for IMP-2217 contained:

v_full_name := COALESCE(NEW.raw_user_meta_data->>'full_name', split_part(COALESCE(NEW.email, ''), '@', 1));

Every wake of an agent picking up this issue or commenting on it caused the shell_snapshot validation to fail at line 52. Fix applied by editing the description to remove the empty-string SQL literal.