@intentius/chant 0.46.0 → 0.49.0

package/src/secret-provenance.ts

@@ -0,0 +1,475 @@
+/**
+ * Secret provenance vocabulary (chant #1828, epic #1365).
+ *
+ * A secret's PROVENANCE is where its value comes from — never what the value
+ * is. chant's constitutional line on secrets: no code path may hold, log,
+ * hash, or compare a secret value. This module makes that structural: the
+ * declaration types have no field that could carry material, the factory
+ * rejects material-shaped fields at both the type level (`never` fields) and
+ * at runtime (own-property check, naming only the offending KEY), and
+ * "mismatch" anywhere downstream means presence, declared key-set, and
+ * metadata — never a value or a value-derived hash (#1365 decision 6).
+ *
+ * The closed kind set:
+ *
+ * - `referenced` — the value exists out of band (a human or an external
+ *   process put it where consumers read it). chant records only that the
+ *   estate depends on it, which is what lets the consumed-but-unproduced
+ *   check (#1382) ship as an error instead of a guess.
+ * - `from-provider` — a declared provider binding materializes it (the
+ *   operator/CRD seam; `K8s::Infisical::InfisicalSecret` from #1321 is the
+ *   exemplar). The declaration POINTS at that binding, it does not re-model
+ *   it.
+ * - `generated-once` — minted on first materialization, then never
+ *   regenerated (present means done). The declaration carries contract flags
+ *   only — e.g. the declared key-set — never mint parameters holding
+ *   material. `generated-once` secrets never enter the prunable set (#1365
+ *   decision 5).
+ * - `committed-encrypted` — sops-style ciphertext committed in the repo,
+ *   decrypted by the delivery system (Flux) straight into the target. The
+ *   declaration records a repo-relative PATH to the ciphertext, never the
+ *   bytes: the factory is pure and touches no filesystem, so it still folds
+ *   under `--sandbox`. The bytes are read at `buildRoots()` — the one
+ *   sanctioned impure seam — and emitted as a sidecar file, never as a
+ *   document in the primary output. See
+ *   `docs/design/committed-encrypted-sops-provenance.md`.
+ *
+ * Declarations are serializer-neutral: discovery collects them like any
+ * entity (they are Declarables), but `partitionByLexicon` (../build.ts)
+ * excludes them from every serializer partition, so no lexicon ever emits
+ * them. They are data that lint rules and lexicons READ (via
+ * {@link collectSecretDeclarations}), not output.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+
+/** The closed union of secret origins. */
+export type SecretProvenance =
+  | "referenced"
+  | "from-provider"
+  | "generated-once"
+  | "committed-encrypted";
+
+/** Every provenance kind, for exhaustiveness checks. */
+export const SECRET_PROVENANCE_KINDS: readonly SecretProvenance[] = [
+  "referenced",
+  "from-provider",
+  "generated-once",
+  "committed-encrypted",
+];
+
+/**
+ * Encryption tools a {@link CommittedEncryptedSecretDeclaration} understands.
+ * A closed union with one member, not a free string: a second tool later is a
+ * deliberate widening with a detection rule attached, not an unvalidated
+ * string that silently means nothing.
+ */
+export type SecretEncryption = "sops";
+
+/** Every encryption tool, for exhaustiveness checks. */
+export const SECRET_ENCRYPTION_TOOLS: readonly SecretEncryption[] = ["sops"];
+
+/**
+ * File extensions a committed ciphertext path may carry (v1).
+ *
+ * The CLI writer round-trips every additional file through `JSON.parse` and
+ * re-emits it key-sorted when the parse succeeds
+ * (`./cli/commands/build.ts`), which would silently rewrite a `.sops.json`
+ * file and break the byte-for-byte guarantee. v1 refuses anything but YAML;
+ * the writer additionally skips the round trip for these files, so byte
+ * identity is structural rather than a happy accident of JSON.parse failing.
+ */
+const CIPHERTEXT_FILE_EXTENSIONS = [".yaml", ".yml"] as const;
+
+/**
+ * Patterns that mean a PRIVATE key was pasted where a public recipient
+ * belongs. Matched against `recipients` entries; the thrown message names the
+ * field and the index, never the value.
+ */
+const PRIVATE_KEY_MARKERS = [/AGE-SECRET-KEY-/i, /-----BEGIN [A-Z ]*PRIVATE KEY-----/];
+
+/** Marker symbol identifying a secret provenance declaration. `Symbol.for` so
+ * it survives the entity-wire codec (../discovery/entity-wire-codec.ts). */
+export const SECRET_DECLARATION_MARKER = Symbol.for("chant.secret-declaration");
+
+/** The `entityType` every secret declaration carries. */
+export const SECRET_DECLARATION_ENTITY_TYPE = "Chant::SecretProvenance";
+
+/**
+ * Points a `from-provider` declaration at the provider binding that
+ * materializes the secret — the CRD seam, not a re-model of it. The binding
+ * itself is an ordinary declarable in its own lexicon (e.g. an
+ * `InfisicalSecret` instance, #1321); this ref names it so lint can resolve
+ * the pair without core depending on any lexicon.
+ */
+export interface SecretProviderRef {
+  /** Entity name (export name) of the provider binding declarable in this project. */
+  readonly binding: string;
+  /**
+   * Expected `entityType` of the binding (e.g.
+   * `"K8s::Infisical::InfisicalSecret"`). Optional; when present, lint can
+   * verify the named binding is actually the kind of seam the declaration
+   * claims.
+   */
+  readonly entityType?: string;
+}
+
+/**
+ * Fields that would carry secret material, forbidden by construction. Typed
+ * as `never` on every factory input so they fail to compile even when the
+ * input object was widened or spread (plain excess-property checks only catch
+ * object literals). The runtime check in {@link declareSecret} is the same
+ * list, for untyped callers.
+ */
+interface NoSecretMaterial {
+  readonly value?: never;
+  readonly data?: never;
+  readonly stringData?: never;
+  readonly material?: never;
+  readonly plaintext?: never;
+  readonly ciphertext?: never;
+}
+
+const FORBIDDEN_MATERIAL_FIELDS = [
+  "value",
+  "data",
+  "stringData",
+  "material",
+  "plaintext",
+  "ciphertext",
+] as const;
+
+/** Fields shared by every secret declaration. */
+interface SecretDeclarationBase extends Declarable {
+  readonly [SECRET_DECLARATION_MARKER]: true;
+  readonly lexicon: "chant";
+  readonly entityType: typeof SECRET_DECLARATION_ENTITY_TYPE;
+  /** The secret's name as consumers know it (e.g. the k8s Secret name). */
+  readonly name: string;
+  /** Which of the closed kind set this declaration is. */
+  readonly provenance: SecretProvenance;
+}
+
+/** A secret whose value exists out of band. */
+export interface ReferencedSecretDeclaration extends SecretDeclarationBase {
+  readonly provenance: "referenced";
+  /** Where consumers find it — free-form (a namespace, a vault path, a doc link). */
+  readonly scope?: string;
+}
+
+/** A secret a declared provider binding materializes. */
+export interface FromProviderSecretDeclaration extends SecretDeclarationBase {
+  readonly provenance: "from-provider";
+  readonly provider: SecretProviderRef;
+}
+
+/** A secret minted on first materialization and never regenerated. */
+export interface GeneratedOnceSecretDeclaration extends SecretDeclarationBase {
+  readonly provenance: "generated-once";
+  /**
+   * The declared key-set of the materialized secret. This is the contract a
+   * materializer (#1830) checks for mismatch — presence and keys, never
+   * values.
+   */
+  readonly keys?: readonly string[];
+}
+
+/**
+ * A secret whose ciphertext is committed to the repo and decrypted by the
+ * delivery system on the way into the target.
+ *
+ * The declaration is a POINTER: `file` is a repo-relative path, and nothing
+ * here carries bytes. That is what keeps the factory pure — the ciphertext is
+ * read at `buildRoots()` and emitted as a sidecar, never inlined into the
+ * primary output an applier reads.
+ */
+export interface CommittedEncryptedSecretDeclaration extends SecretDeclarationBase {
+  readonly provenance: "committed-encrypted";
+  /** Repo-relative path to the committed ciphertext file. */
+  readonly file: string;
+  /** Encryption tool. Defaults to `"sops"` when omitted. */
+  readonly encryption: SecretEncryption;
+  /**
+   * Public recipient identifiers — age recipients or PGP fingerprints. Public
+   * by definition, which is the opposite of material; a private key here is
+   * refused by the factory.
+   */
+  readonly recipients?: readonly string[];
+  /**
+   * The declared key-set of the decrypted Secret — the same contract meaning
+   * as {@link GeneratedOnceSecretDeclaration.keys}: presence and key names,
+   * never values. SOPS leaves key NAMES cleartext, so this is checkable
+   * against the file itself.
+   */
+  readonly keys?: readonly string[];
+}
+
+/** A secret provenance declaration — the discriminant is `provenance`. */
+export type SecretDeclaration =
+  | ReferencedSecretDeclaration
+  | FromProviderSecretDeclaration
+  | GeneratedOnceSecretDeclaration
+  | CommittedEncryptedSecretDeclaration;
+
+/** Narrow a declaration to the committed-encrypted kind. */
+export function isCommittedEncryptedSecret(
+  decl: SecretDeclaration,
+): decl is CommittedEncryptedSecretDeclaration {
+  return decl.provenance === "committed-encrypted";
+}
+
+/** Factory input for a `referenced` secret. */
+export interface ReferencedSecretInput extends NoSecretMaterial {
+  readonly name: string;
+  readonly provenance: "referenced";
+  readonly scope?: string;
+}
+
+/** Factory input for a `from-provider` secret. */
+export interface FromProviderSecretInput extends NoSecretMaterial {
+  readonly name: string;
+  readonly provenance: "from-provider";
+  readonly provider: SecretProviderRef;
+}
+
+/** Factory input for a `generated-once` secret. */
+export interface GeneratedOnceSecretInput extends NoSecretMaterial {
+  readonly name: string;
+  readonly provenance: "generated-once";
+  readonly keys?: readonly string[];
+}
+
+/** Factory input for a `committed-encrypted` secret. */
+export interface CommittedEncryptedSecretInput extends NoSecretMaterial {
+  readonly name: string;
+  readonly provenance: "committed-encrypted";
+  /**
+   * Repo-relative path to the committed ciphertext file — `file`, never
+   * `ciphertext`: the declaration points at bytes, it does not carry them,
+   * and `ciphertext` is a forbidden material field.
+   */
+  readonly file: string;
+  /** Encryption tool. Closed union; `"sops"` is its only member today. */
+  readonly encryption?: SecretEncryption;
+  /** Public recipient identifiers — age recipients or PGP fingerprints. */
+  readonly recipients?: readonly string[];
+  /** The declared key-set of the decrypted Secret. Names only, never values. */
+  readonly keys?: readonly string[];
+}
+
+export type SecretDeclarationInput =
+  | ReferencedSecretInput
+  | FromProviderSecretInput
+  | GeneratedOnceSecretInput
+  | CommittedEncryptedSecretInput;
+
+/**
+ * Declare a secret's provenance. The returned object is a locked Declarable:
+ * discovery collects it like any entity, `chant list` shows it, lint and
+ * lexicons read it — and no serializer ever emits it.
+ *
+ * Only the fields the kind defines are copied onto the declaration; anything
+ * else on the input — in particular anything that could carry material — is
+ * either a compile error ({@link NoSecretMaterial}) or a thrown error here.
+ * The thrown message names the offending KEY only, never its value.
+ */
+export function declareSecret(input: ReferencedSecretInput): ReferencedSecretDeclaration;
+export function declareSecret(input: FromProviderSecretInput): FromProviderSecretDeclaration;
+export function declareSecret(input: GeneratedOnceSecretInput): GeneratedOnceSecretDeclaration;
+export function declareSecret(
+  input: CommittedEncryptedSecretInput,
+): CommittedEncryptedSecretDeclaration;
+export function declareSecret(input: SecretDeclarationInput): SecretDeclaration {
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error("declareSecret: `name` must be a non-empty string");
+  }
+  if (!SECRET_PROVENANCE_KINDS.includes(input.provenance)) {
+    throw new Error(
+      `declareSecret("${input.name}"): unknown provenance "${String(input.provenance)}" — ` +
+        `expected one of ${SECRET_PROVENANCE_KINDS.join(", ")}`,
+    );
+  }
+  for (const field of FORBIDDEN_MATERIAL_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(input, field)) {
+      // Name the key only. Never read, log, or echo the value.
+      throw new Error(
+        `declareSecret("${input.name}"): field "${field}" is not allowed — ` +
+          `a secret declaration records provenance, never material`,
+      );
+    }
+  }
+
+  const base = {
+    [DECLARABLE_MARKER]: true,
+    [SECRET_DECLARATION_MARKER]: true,
+    lexicon: "chant",
+    entityType: SECRET_DECLARATION_ENTITY_TYPE,
+    name: input.name,
+  } as const;
+
+  // Copy known fields per kind explicitly — never spread `input`, so a field
+  // that slipped past the type system still cannot land on the declaration.
+  // The top-level object stays extensible (discovery stamps logical-name and
+  // provenance symbols onto entities); the declared fields themselves are
+  // defined non-writable below, and nested structures are frozen.
+  switch (input.provenance) {
+    case "referenced": {
+      const decl: ReferencedSecretDeclaration = {
+        ...base,
+        provenance: "referenced",
+        ...(input.scope !== undefined ? { scope: input.scope } : {}),
+      };
+      return lockDeclaredFields(decl);
+    }
+    case "from-provider": {
+      if (typeof input.provider?.binding !== "string" || input.provider.binding.length === 0) {
+        throw new Error(
+          `declareSecret("${input.name}"): from-provider requires \`provider.binding\` ` +
+            `naming the provider binding entity`,
+        );
+      }
+      const decl: FromProviderSecretDeclaration = {
+        ...base,
+        provenance: "from-provider",
+        provider: Object.freeze({
+          binding: input.provider.binding,
+          ...(input.provider.entityType !== undefined ? { entityType: input.provider.entityType } : {}),
+        }),
+      };
+      return lockDeclaredFields(decl);
+    }
+    case "generated-once": {
+      const decl: GeneratedOnceSecretDeclaration = {
+        ...base,
+        provenance: "generated-once",
+        ...(input.keys !== undefined ? { keys: Object.freeze([...input.keys]) } : {}),
+      };
+      return lockDeclaredFields(decl);
+    }
+    case "committed-encrypted": {
+      const decl: CommittedEncryptedSecretDeclaration = {
+        ...base,
+        provenance: "committed-encrypted",
+        file: validateCiphertextPath(input.name, input.file),
+        encryption: validateEncryption(input.name, input.encryption),
+        ...(input.recipients !== undefined
+          ? { recipients: Object.freeze(validateRecipients(input.name, input.recipients)) }
+          : {}),
+        ...(input.keys !== undefined ? { keys: Object.freeze([...input.keys]) } : {}),
+      };
+      return lockDeclaredFields(decl);
+    }
+  }
+}
+
+/**
+ * Validate the repo-relative ciphertext path. Pure and offline — the factory
+ * never stats the file, because discovery folds project source statically
+ * under `--sandbox` and a factory that touched the filesystem would either
+ * break folding or reintroduce the trust boundary that suite defends. The
+ * file's existence and shape are checked at `buildRoots()` instead.
+ */
+function validateCiphertextPath(name: string, file: unknown): string {
+  if (typeof file !== "string" || file.length === 0) {
+    throw new Error(
+      `declareSecret("${name}"): committed-encrypted requires \`file\`, a non-empty ` +
+        `repo-relative path to the committed ciphertext`,
+    );
+  }
+  if (file.startsWith("/") || /^[A-Za-z]:[\\/]/.test(file)) {
+    throw new Error(
+      `declareSecret("${name}"): \`file\` must be repo-relative, not absolute — got "${file}"`,
+    );
+  }
+  const segments = file.split(/[\\/]/);
+  if (segments.includes("..")) {
+    throw new Error(
+      `declareSecret("${name}"): \`file\` must not escape the project with a ".." segment — ` +
+        `got "${file}"`,
+    );
+  }
+  const dot = file.lastIndexOf(".");
+  const extension = dot === -1 ? "" : file.slice(dot).toLowerCase();
+  if (!(CIPHERTEXT_FILE_EXTENSIONS as readonly string[]).includes(extension)) {
+    throw new Error(
+      `declareSecret("${name}"): \`file\` must be a YAML file ` +
+        `(${CIPHERTEXT_FILE_EXTENSIONS.join(", ")}) — got "${extension || "no extension"}". ` +
+        `Other formats are not emitted byte-for-byte yet.`,
+    );
+  }
+  return file;
+}
+
+/** Validate the encryption tool, defaulting to `"sops"`. */
+function validateEncryption(name: string, encryption: unknown): SecretEncryption {
+  if (encryption === undefined) return "sops";
+  if (!(SECRET_ENCRYPTION_TOOLS as readonly unknown[]).includes(encryption)) {
+    throw new Error(
+      `declareSecret("${name}"): unknown encryption "${String(encryption)}" — ` +
+        `expected one of ${SECRET_ENCRYPTION_TOOLS.join(", ")}`,
+    );
+  }
+  return encryption as SecretEncryption;
+}
+
+/**
+ * Copy `recipients`, refusing a private key pasted where a public recipient
+ * belongs. The message names the field and the index — never the value, the
+ * same discipline the forbidden-material check above uses.
+ */
+function validateRecipients(name: string, recipients: readonly string[]): string[] {
+  const copied = [...recipients];
+  copied.forEach((recipient, index) => {
+    if (typeof recipient !== "string" || recipient.length === 0) {
+      throw new Error(
+        `declareSecret("${name}"): \`recipients[${index}]\` must be a non-empty string`,
+      );
+    }
+    if (PRIVATE_KEY_MARKERS.some((pattern) => pattern.test(recipient))) {
+      throw new Error(
+        `declareSecret("${name}"): \`recipients[${index}]\` looks like a PRIVATE key — ` +
+          `recipients are public identifiers (age recipients, PGP fingerprints). ` +
+          `Rotate it: it has been in a source file.`,
+      );
+    }
+  });
+  return copied;
+}
+
+/**
+ * Make every declared (string-keyed) field non-writable and non-configurable
+ * without sealing the object — discovery still stamps its own symbol-keyed
+ * metadata (logical name, build provenance) onto entities, which a frozen
+ * object would reject.
+ */
+function lockDeclaredFields<T extends object>(decl: T): T {
+  for (const key of Object.keys(decl)) {
+    Object.defineProperty(decl, key, { writable: false, configurable: false });
+  }
+  return decl;
+}
+
+/** Type guard for a secret provenance declaration. */
+export function isSecretDeclaration(value: unknown): value is SecretDeclaration {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    SECRET_DECLARATION_MARKER in value &&
+    (value as Record<symbol, unknown>)[SECRET_DECLARATION_MARKER] === true
+  );
+}
+
+/**
+ * Extract the secret declarations from a discovered entity map — the read
+ * surface for lint rules (#1382) and lexicon materializers (#1830). Keyed by
+ * entity name (export name), the same key `DiscoveryResult.entities` uses.
+ */
+export function collectSecretDeclarations(
+  entities: ReadonlyMap<string, Declarable>,
+): Map<string, SecretDeclaration> {
+  const out = new Map<string, SecretDeclaration>();
+  for (const [name, entity] of entities) {
+    if (isSecretDeclaration(entity)) out.set(name, entity);
+  }
+  return out;
+}

package/src/serializer.ts

@@ -20,6 +20,18 @@ export interface SerializeContext {
    * ad-hoc builds (e.g. context tools) that pass no config.
    */
   config?: Record<string, unknown>;
+
+  /**
+   * Effect receipts (#1832, epic #1703) declared in this lexicon's partition.
+   * Withheld from the `entities` map by the build: receipts are observe-only
+   * to the generic apply path, and the serialized output is what feeds
+   * appliers, so a receipt must never enter the apply-bound document. A
+   * serializer that wants to render receipts for visibility (#1835) reads
+   * them here and puts them anywhere BUT the section an applier writes from;
+   * a serializer that ignores this field emits nothing for them, which is the
+   * safe default.
+   */
+  receipts?: ReadonlyMap<string, Declarable>;
 }
 
 /**

package/src/yaml.test.ts

@@ -226,6 +226,94 @@ describe("parseScalar", () => {
     expect(parseScalar("hello")).toBe("hello");
   });
 });
+// Quoted scalars (#1860) — stripping the delimiters is only half the job; the
+// escapes inside them have to be decoded too. A double-quoted `\n` that stayed
+// two literal characters is what sent a seven-line setup script to a shell as
+// one line.
+describe("parseScalar quoted scalars (#1860)", () => {
+  test("double-quoted escapes decode", () => {
+    expect(parseScalar(String.raw`"a\nb"`)).toBe("a\nb");
+    expect(parseScalar(String.raw`"a\tb"`)).toBe("a\tb");
+    expect(parseScalar(String.raw`"say \"hi\""`)).toBe('say "hi"');
+    expect(parseScalar(String.raw`"back\\slash"`)).toBe("back\\slash");
+    expect(parseScalar(String.raw`"a\/b"`)).toBe("a/b");
+  });
+
+  test("hex, unicode and 32-bit escapes", () => {
+    expect(parseScalar(String.raw`"\x41"`)).toBe("A");
+    expect(parseScalar(String.raw`"A"`)).toBe("A");
+    expect(parseScalar(String.raw`"\U0001F600"`)).toBe("\u{1F600}");
+  });
+
+  test("an escaped line break folds away with its indentation", () => {
+    expect(parseScalar('"a\\\n   b"')).toBe("ab");
+  });
+
+  test("single-quoted '' is one quote", () => {
+    expect(parseScalar("'it''s'")).toBe("it's");
+    expect(parseScalar("'''quoted'''")).toBe("'quoted'");
+  });
+
+  test("a lone quote character is not a quoted scalar", () => {
+    expect(parseScalar('"')).toBe('"');
+    expect(parseScalar("'")).toBe("'");
+  });
+
+  test("a body with a bare quote keeps the old strip-only behaviour", () => {
+    expect(parseScalar('"a" + "b"')).toBe('a" + "b');
+  });
+
+  test("an unknown or truncated escape keeps the old strip-only behaviour", () => {
+    expect(parseScalar(String.raw`"a\qb"`)).toBe(String.raw`a\qb`);
+    expect(parseScalar(String.raw`"\x4"`)).toBe(String.raw`\x4`);
+  });
+});
+
+// Round-trip parity for the scalars `emitYAML` quotes: what it writes,
+// `parseYAML` must read back unchanged. The single-quote half of #1860 was
+// invisible until this existed. Multiline strings are excluded on purpose —
+// the emitter sends those through a block scalar, which #910 already covers
+// and which does not preserve trailing newlines.
+describe("emitYAML/parseYAML round trip (#1860)", () => {
+  const values = [
+    "'quoted'",
+    "#hash's",
+    "it's a test",
+    "plain",
+    "yes",
+    "a: b",
+    "$VAR",
+    "",
+  ];
+
+  for (const v of values) {
+    test(`round-trips ${JSON.stringify(v)}`, () => {
+      expect(parseYAML(`k: ${emitYAML(v, 0)}\n`).k).toBe(v);
+    });
+  }
+});
+
+// The fountain lexicon emits multiline strings as `JSON.stringify(s)` — a
+// double-quoted scalar, not a block scalar — so this is the shape that
+// actually reached the applier (#1860).
+describe("double-quoted multiline manifest values (#1860)", () => {
+  test("a joined shell script keeps its newlines", () => {
+    const script = [
+      "set -e",
+      "sudo service postgresql start || true",
+      `sudo -u postgres psql -tc "ALTER USER postgres PASSWORD 'postgres'" || true`,
+      "cd /workspace/fountain",
+    ].join("\n");
+
+    const yaml = `spec:\n  setup_script: ${JSON.stringify(script)}\n`;
+    const parsed = parseYAML(yaml) as { spec: { setup_script: string } };
+
+    expect(parsed.spec.setup_script).toBe(script);
+    expect(parsed.spec.setup_script.split("\n")).toHaveLength(4);
+    expect(parsed.spec.setup_script).not.toContain(String.raw`\n`);
+  });
+});
+
 
 // Block scalars (#910) — round-trip parity with js-yaml for literal/folded/chomping,
 // including block scalars nested inside array items (the case that mis-parsed).

package/src/yaml.ts

@@ -559,15 +559,85 @@ export function parseScalar(value: string): unknown {
   if (value === "" || value === "~" || value === "null") return null;
   if (value === "true" || value === "yes") return true;
   if (value === "false" || value === "no") return false;
-  // Strip quotes
-  if (
-    (value.startsWith("'") && value.endsWith("'")) ||
-    (value.startsWith('"') && value.endsWith('"'))
-  ) {
-    return value.slice(1, -1);
+  // Quoted scalars carry escapes, and stripping the quotes is only half the
+  // job: a double-quoted `\n` is a newline, a single-quoted `''` is one
+  // quote. Dropping that step leaves the escape sequence in the value as
+  // literal characters, which is how a multiline `setup_script` reached a
+  // shell as one line of `set -e\nsudo ...` (#1860).
+  if (value.length >= 2) {
+    if (value.startsWith('"') && value.endsWith('"')) {
+      const unescaped = unescapeDoubleQuoted(value.slice(1, -1));
+      // `null` means the body held a bare `"`, so this was never a single
+      // well-formed scalar (`"a" + "b"`). Keep the old behaviour there.
+      return unescaped ?? value.slice(1, -1);
+    }
+    if (value.startsWith("'") && value.endsWith("'")) {
+      return value.slice(1, -1).replace(/''/g, "'");
+    }
   }
   // Number
   const num = Number(value);
   if (!isNaN(num) && value !== "") return num;
   return value;
 }
+
+/** YAML double-quoted escapes, per the spec's escape table. */
+const DQ_ESCAPES: Record<string, string> = {
+  "0": "\0",
+  a: "\x07",
+  b: "\b",
+  t: "\t",
+  "\t": "\t",
+  n: "\n",
+  v: "\v",
+  f: "\f",
+  r: "\r",
+  e: "\x1b",
+  " ": " ",
+  '"': '"',
+  "/": "/",
+  "\\": "\\",
+  N: "\x85",
+  _: "\xa0",
+  L: "\u2028",
+  P: "\u2029",
+};
+
+/**
+ * Decode the body of a double-quoted YAML scalar.
+ *
+ * Returns `null` when the body holds an unescaped `"`, which means the caller
+ * was not looking at one quoted scalar after all.
+ */
+function unescapeDoubleQuoted(body: string): string | null {
+  let out = "";
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch === '"') return null;
+    if (ch !== "\\") {
+      out += ch;
+      continue;
+    }
+    const esc = body[++i];
+    if (esc === undefined) return null;
+    // \xXX, \uXXXX, \UXXXXXXXX
+    const width = esc === "x" ? 2 : esc === "u" ? 4 : esc === "U" ? 8 : 0;
+    if (width > 0) {
+      const hex = body.slice(i + 1, i + 1 + width);
+      if (hex.length < width || !/^[0-9a-fA-F]+$/.test(hex)) return null;
+      out += String.fromCodePoint(parseInt(hex, 16));
+      i += width;
+      continue;
+    }
+    // An escaped line break is a line continuation: it and the following
+    // indentation fold away to nothing.
+    if (esc === "\n") {
+      while (body[i + 1] === " " || body[i + 1] === "\t") i++;
+      continue;
+    }
+    const mapped = DQ_ESCAPES[esc];
+    if (mapped === undefined) return null;
+    out += mapped;
+  }
+  return out;
+}