@sjawhar/pi-legion-envoy 5.16.9 → 5.17.0

package/dist/legion.js

@@ -33473,7 +33473,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.16.9",
+  version: "5.17.0",
   type: "module",
   omp: {
     extensions: [
@@ -40317,6 +40317,148 @@ class Parser {
   }
 }
 
+// src/legion/pane-guard-bash.ts
+function isAscii(text) {
+  for (let i = 0;i < text.length; i += 1)
+    if (text.charCodeAt(i) > 127)
+      return false;
+  return true;
+}
+var ANY_RUN = -1;
+var ANY_ONE = -2;
+function globWork(glob, n, operator) {
+  const characters = operator === "/" || operator === "//" ? n * (n + 3) / 2 + 1 : n + 1;
+  return characters * (glob.length + 8);
+}
+function prefixMatches(glob, value, from) {
+  const m = glob.length;
+  const matches = new Uint8Array(value.length - from + 1);
+  let reached = new Uint8Array(m + 1);
+  let next = new Uint8Array(m + 1);
+  reached[0] = 1;
+  closeRuns(glob, reached);
+  for (let k = 0;; k += 1) {
+    matches[k] = reached[m];
+    if (from + k === value.length)
+      break;
+    const c = value.charCodeAt(from + k);
+    next.fill(0);
+    let any2 = false;
+    for (let i = 0;i < m; i += 1) {
+      if (reached[i] !== 1)
+        continue;
+      const element = glob[i];
+      if (element === ANY_RUN)
+        next[i] = 1;
+      else if (element === ANY_ONE || element === c)
+        next[i + 1] = 1;
+      else
+        continue;
+      any2 = true;
+    }
+    if (!any2)
+      break;
+    closeRuns(glob, next);
+    [reached, next] = [next, reached];
+  }
+  return matches;
+}
+function closeRuns(glob, reached) {
+  for (let i = 0;i < glob.length; i += 1) {
+    if (reached[i] === 1 && glob[i] === ANY_RUN)
+      reached[i + 1] = 1;
+  }
+}
+function globMatches(glob, value) {
+  return prefixMatches(glob, value, 0)[value.length] === 1;
+}
+function matchEdge(value, glob, from, longest) {
+  const matches = from === "start" ? prefixMatches(glob, value, 0) : prefixMatches([...glob].reverse(), [...value].reverse().join(""), 0);
+  const length = longest ? matches.lastIndexOf(1) : matches.indexOf(1);
+  return length === -1 ? undefined : length;
+}
+function removePattern(value, operator, glob) {
+  const from = operator.startsWith("#") ? "start" : "end";
+  const length = matchEdge(value, glob, from, operator.length === 2);
+  if (length === undefined)
+    return value;
+  return from === "start" ? value.slice(length) : value.slice(0, value.length - length);
+}
+function replacePattern(value, operator, glob, replacement) {
+  const n = value.length;
+  if (operator === "/#" || operator === "/%") {
+    const from = operator === "/#" ? "start" : "end";
+    const length = matchEdge(value, glob, from, true);
+    if (length === undefined)
+      return value;
+    return from === "start" ? replacement + value.slice(length) : value.slice(0, n - length) + replacement;
+  }
+  if (n === 0)
+    return globMatches(glob, "") ? replacement : value;
+  let out = "";
+  let at = 0;
+  while (at < n) {
+    const length = prefixMatches(glob, value, at).lastIndexOf(1);
+    if (length <= 0) {
+      out += value[at];
+      at += 1;
+      continue;
+    }
+    out += replacement;
+    at += length;
+    if (operator === "/")
+      return out + value.slice(at);
+  }
+  return out;
+}
+function evaluateTest(operands) {
+  const [left = "", operator = "", right = ""] = operands;
+  if (operands.length === 1)
+    return left !== "";
+  if (operands.length === 2) {
+    if (left === "!")
+      return operator === "";
+    if (left === "-n")
+      return operator !== "";
+    if (left === "-z")
+      return operator === "";
+    return;
+  }
+  if (operands.length !== 3)
+    return;
+  if (operator === "=" || operator === "==")
+    return left === right;
+  if (operator === "!=")
+    return left !== right;
+  if (!/^-?[0-9]+$/.test(left) || !/^-?[0-9]+$/.test(right))
+    return;
+  const a = Number(left);
+  const b = Number(right);
+  switch (operator) {
+    case "-eq":
+      return a === b;
+    case "-ne":
+      return a !== b;
+    case "-gt":
+      return a > b;
+    case "-ge":
+      return a >= b;
+    case "-lt":
+      return a < b;
+    case "-le":
+      return a <= b;
+    default:
+      return;
+  }
+}
+function shellQuoted(text) {
+  if (text === "")
+    return "''";
+  if (/^[A-Za-z0-9_/.:@%+=,-]+$/.test(text))
+    return text;
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
 // src/legion/pane-guard-code.ts
 var UNKNOWN_MARKER = "__LEGION_GUARD_UNKNOWN__";
 var PY_STRING_PREFIX = new Set(["r", "u", "b", "f", "br", "rb", "fr", "rf"]);
@@ -41287,6 +41429,19 @@ function scanIpythonShell(source, sinks) {
 }
 
 // src/legion/pane-guard.ts
+var UNSET = [{ kind: "literal", text: "", unset: true }];
+function isUnset(value) {
+  return value?.length === 1 && value[0]?.unset === true;
+}
+var NO_ELEMENTS = { kind: "literal", text: "", noElements: true };
+function stored(value) {
+  if (!value.some((piece) => piece.noElements === true))
+    return value;
+  return value.map((piece) => piece.noElements === true ? literal2("") : piece);
+}
+var ANY_NAME = "\x00";
+var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var ARRAY_ELEMENT = /^([A-Za-z_][A-Za-z0-9_]*)\[.*\]$/s;
 var definitions = new WeakMap;
 function trapSignal(operand) {
   const name = operand.toUpperCase();
@@ -41322,7 +41477,10 @@ function wrapRefusal(error48, site, label) {
 }
 var MAX_DEPTH = 8;
 var MAX_WALK_STEPS = 1e5;
+var WALK_LIMIT = `the guard reached its walk limit of ${MAX_WALK_STEPS} nodes; run a smaller script`;
 var MAX_ALTERNATIVES = 64;
+var MAX_PATTERN_VALUE = 512;
+var PATTERN_WORK_PER_STEP = 1024;
 var MAX_SCRIPT_BYTES = 1024 * 1024;
 var FRESH_TEMP_NAME = "tmp.XXXXXXXXXX";
 var PROTECTED_SCRATCH = [
@@ -41410,7 +41568,7 @@ function realish(abs, followFinal) {
   return path4.join(realExisting(path4.dirname(resolved)), path4.basename(resolved));
 }
 function isProtectedScratchComponent(component, roots, partial2 = false) {
-  return roots.protectedScratch.some((name) => component.startsWith(name) || partial2 && name.startsWith(component));
+  return roots.protectedScratch.some((name) => component.startsWith(name) || partial2 && name.startsWith(component)) || roots.protectedDirectories.some((name) => component === name || partial2 && name.startsWith(component));
 }
 function inWorkspace(real, roots) {
   const workspace = roots.workspace;
@@ -41516,12 +41674,81 @@ function unquotedLiteral(source, tildeAt, st, ctx) {
 function lookup(name, st, ctx) {
   const own = st.vars.get(name);
   if (own !== undefined)
-    return own;
+    return isUnset(own) ? undefined : own;
+  const any2 = st.vars.get(ANY_NAME)?.[0];
+  if (any2 !== undefined)
+    return [{ ...any2, why: `\`$${name}\`, which ${any2.why}` }];
   if (name === "PWD" && st.cwd !== undefined)
     return [literal2(st.cwd)];
   const value = ctx.env[name];
   return value === undefined ? undefined : [literal2(value)];
 }
+function assignScalar(st, name, value) {
+  if (attributed(st, name)) {
+    keepAttributed(st, name);
+    return;
+  }
+  const kept = stored(value);
+  st.vars.set(name, kept);
+  const elements = st.arrays.get(name);
+  if (elements !== undefined)
+    st.arrays.set(name, new Map(elements).set("0", kept));
+}
+function attributed(st, name) {
+  return st.vars.get(name)?.some((piece) => piece.rewrites === true) === true;
+}
+function keepAttributed(st, name, unsets = false) {
+  const before = st.vars.get(name);
+  const maybeUnset = unsets || before === undefined || isUnset(before) || before.some((piece) => piece.maybeUnset === true);
+  const kept = [
+    {
+      ...unknown2(`\`$${name}\`, whose \`readonly\`, \`-i\`, \`-l\` or \`-u\` refuses or rewrites a write`),
+      rewrites: true,
+      ...maybeUnset ? { maybeUnset: true } : {}
+    }
+  ];
+  st.vars.set(name, kept);
+  if (st.arrays.has(name))
+    st.arrays.set(name, new Map([[UNKNOWN_ARRAY_INDEX, kept]]));
+}
+function assignByName(st, name, value, writer) {
+  if (name === undefined) {
+    forgetVariables(st, `${writer} under a name the guard cannot read may have changed`);
+    return;
+  }
+  if (IDENTIFIER.test(name)) {
+    assignScalar(st, name, value);
+    return;
+  }
+  const base = ARRAY_ELEMENT.exec(name)?.[1];
+  if (base === undefined)
+    return;
+  if (attributed(st, base)) {
+    keepAttributed(st, base, true);
+    return;
+  }
+  const element = [
+    { ...unknown2(`\`$${base}\`, whose element ${writer} assigns`), maybeUnset: true }
+  ];
+  st.vars.set(base, element);
+  st.arrays.set(base, new Map([[UNKNOWN_ARRAY_INDEX, element]]));
+}
+function forgetVariables(st, why) {
+  const forgotten = (name) => [
+    {
+      ...unknown2(`\`$${name}\`, which ${why}`),
+      maybeUnset: true,
+      ...attributed(st, name) ? { rewrites: true } : {}
+    }
+  ];
+  for (const name of st.vars.keys())
+    if (name !== ANY_NAME)
+      st.vars.set(name, forgotten(name));
+  st.vars.set(ANY_NAME, [{ ...unknown2(why), maybeUnset: true }]);
+  for (const name of st.arrays.keys()) {
+    st.arrays.set(name, new Map([[UNKNOWN_ARRAY_INDEX, forgotten(name)]]));
+  }
+}
 function resolveArrayIndex(index, st, ctx) {
   if (index === undefined)
     return;
@@ -41534,7 +41761,7 @@ function parameter(name, quoted, st, ctx) {
   if (name === "@" || name === "*") {
     if (st.positional === undefined)
       return [[unknown2(`\`$${name}\` (the positional parameters)`)]];
-    return st.positional.length === 0 ? [[literal2("")]] : st.positional.map((p) => [...p]);
+    return elements(st.positional, name === "*" && quoted);
   }
   if (/^[0-9]+$/.test(name)) {
     if (name === "0")
@@ -41542,6 +41769,8 @@ function parameter(name, quoted, st, ctx) {
     const value2 = st.positional?.[Number(name) - 1];
     if (value2 !== undefined)
       return [[...value2]];
+    if (st.positional !== undefined)
+      return [[literal2("")]];
     return [[unknown2(`\`$${name}\` (a positional parameter)`)]];
   }
   if (name === "$") {
@@ -41550,8 +41779,12 @@ function parameter(name, quoted, st, ctx) {
   if (name === "!") {
     return [[unknown2("`$!` (the last background job)", st.backgroundStarted ? true : undefined)]];
   }
+  if (name === "#" && st.positional !== undefined)
+    return [[literal2(String(st.positional.length))]];
   if (["?", "#", "-"].includes(name))
     return [[unknown2(`\`$${name}\``)]];
+  if (isUnset(st.vars.get(name)))
+    return [[literal2("")]];
   const value = lookup(name, st, ctx);
   if (value === undefined) {
     return [[unknown2(`\`$${name}\`, which is not set in this command or the pane's environment`)]];
@@ -41569,6 +41802,30 @@ function parameter(name, quoted, st, ctx) {
   }
   return [pieces];
 }
+function elements(values, joined) {
+  if (joined)
+    return [values.flatMap((value, index) => index === 0 ? value : [literal2(" "), ...value])];
+  return values.length === 0 ? [[NO_ELEMENTS]] : values.map((value) => [...value]);
+}
+function operatorValue(name, st, ctx) {
+  const unknownValue = [unknown2(`\`$${name}\``)];
+  if (!/^([0-9]+|[@*#?$!-])$/.test(name)) {
+    const value = lookup(name, st, ctx);
+    if (value === undefined)
+      return { set: false, value: [] };
+    return { set: value.some((piece) => piece.maybeUnset === true) ? undefined : true, value };
+  }
+  if (/^[1-9][0-9]*$/.test(name) || name === "@" || name === "*") {
+    if (st.positional === undefined)
+      return { set: undefined, value: unknownValue };
+    const value = name === "@" || name === "*" ? st.positional.length === 0 ? undefined : elements(st.positional, true)[0] : st.positional[Number(name) - 1];
+    return value === undefined ? { set: false, value: [] } : { set: true, value };
+  }
+  if (name === "!" && !st.backgroundStarted)
+    return { set: undefined, value: unknownValue };
+  const alternatives = parameter(name, true, st, ctx);
+  return { set: true, value: alternatives.length === 1 ? alternatives[0] ?? [] : unknownValue };
+}
 function parameterExpansion(part, quoted, st, ctx) {
   const name = part.parameter;
   if (name === "BASH_SOURCE" && part.index === "0" && st.script !== undefined) {
@@ -41580,8 +41837,7 @@ function parameterExpansion(part, quoted, st, ctx) {
       const unknownElement = array2.get(UNKNOWN_ARRAY_INDEX);
       if (unknownElement !== undefined)
         return [[...unknownElement]];
-      const values = [...array2.values()];
-      return values.length === 0 ? [[literal2("")]] : values.map((value2) => [...value2]);
+      return elements([...array2.values()], part.index === "*" && quoted);
     }
     return parameter(name, quoted, st, ctx);
   }
@@ -41592,33 +41848,50 @@ function parameterExpansion(part, quoted, st, ctx) {
     }
     return [[unknown2(`\`${part.text}\``)]];
   }
-  if (part.length || part.indirect || part.slice || part.replace) {
+  if (part.length || part.indirect || part.slice) {
     return [[unknown2(`\`${part.text}\``)]];
   }
+  if (part.replace !== undefined || ["#", "##", "%", "%%"].includes(part.operator ?? "")) {
+    return patternExpansion(part, quoted, st, ctx);
+  }
   const operator = part.operator;
   if (operator === undefined)
     return parameter(name, quoted, st, ctx);
-  const value = lookup(name, st, ctx);
-  const set2 = value !== undefined;
-  const nonEmpty2 = set2 && value.map((p) => p.text).join("") !== "";
-  const known = !set2 || value.every((p) => p.kind === "literal");
+  const { set: set2, value } = operatorValue(name, st, ctx);
+  const nonEmpty2 = set2 === true && value.map((p) => p.text).join("") !== "";
+  const known = set2 === false || set2 === true && value.every((p) => p.kind === "literal");
+  const surelyNonEmpty = set2 === true && value.some((p) => p.descendantPid === true || p.kind === "literal" && p.text !== "");
+  const undecided = [[unknown2(`\`${part.text}\``)]];
   const operand = () => part.operand === undefined ? [[literal2("")]] : expandWord(part.operand, st, ctx);
+  const assigning = (result, maybe) => {
+    if ((operator === ":=" || operator === "=") && IDENTIFIER.test(name)) {
+      const only = result.length === 1 && !maybe ? result[0] : undefined;
+      assignScalar(st, name, only ?? [unknown2(`\`$${name}\`, which \`${part.text}\` may assign`)]);
+    }
+    return result;
+  };
   switch (operator) {
     case ":-":
     case ":=":
+      if (surelyNonEmpty)
+        return parameter(name, quoted, st, ctx);
       if (!known)
-        return [[unknown2(`\`${part.text}\``)]];
-      return nonEmpty2 ? parameter(name, quoted, st, ctx) : operand();
+        return assigning(undecided, true);
+      return nonEmpty2 ? parameter(name, quoted, st, ctx) : assigning(operand(), false);
     case "-":
     case "=":
-      if (!known)
-        return [[unknown2(`\`${part.text}\``)]];
-      return set2 ? parameter(name, quoted, st, ctx) : operand();
+      if (set2 === undefined)
+        return assigning(undecided, true);
+      return set2 ? parameter(name, quoted, st, ctx) : assigning(operand(), false);
     case ":+":
+      if (surelyNonEmpty)
+        return operand();
       if (!known)
-        return [[unknown2(`\`${part.text}\``)]];
+        return undecided;
       return nonEmpty2 ? operand() : [[literal2("")]];
     case "+":
+      if (set2 === undefined)
+        return undecided;
       return set2 ? operand() : [[literal2("")]];
     case ":?":
     case "?":
@@ -41627,6 +41900,57 @@ function parameterExpansion(part, quoted, st, ctx) {
       return [[unknown2(`\`${part.text}\``)]];
   }
 }
+function patternExpansion(part, quoted, st, ctx) {
+  const unknownResult = [[unknown2(`\`${part.text}\``)]];
+  const because = (pieces) => {
+    const cause = pieces.find((piece) => piece.kind === "unknown")?.why;
+    return cause === undefined ? unknownResult : [[unknown2(`\`${part.text}\` (${cause})`)]];
+  };
+  const operator = part.operator ?? "";
+  const head = `\${${part.parameter}${operator}`;
+  const accounted = part.replace === undefined ? part.text === `${head}${part.operand?.text ?? ""}}` : part.text === `${head}${part.replace.pattern.text}/${part.replace.replacement.text}}` || part.replace.replacement.text === "" && part.text === `${head}${part.replace.pattern.text}}`;
+  const slashPattern = operator === "/" || operator === "//";
+  if (!accounted || slashPattern && part.replace?.pattern.text === "")
+    return unknownResult;
+  const { set: set2, value: held } = operatorValue(part.parameter, st, ctx);
+  const knownUnset = set2 === false && (/^([1-9][0-9]*|[@*])$/.test(part.parameter) || isUnset(st.vars.get(part.parameter)));
+  const value = set2 === true ? literalText(held) : knownUnset ? "" : undefined;
+  if (value === undefined)
+    return because(held);
+  if (value.length > MAX_PATTERN_VALUE || !isAscii(value))
+    return unknownResult;
+  const patternWord = part.replace?.pattern ?? part.operand;
+  const patterns = patternWord === undefined ? [[literal2("")]] : expandWord(patternWord, st, ctx);
+  const glob = patterns.length === 1 ? patternGlob(patterns[0]) : undefined;
+  if (glob === undefined || slashPattern && glob.length === 0)
+    return unknownResult;
+  if (!spendPatternWork(globWork(glob, value.length, operator), ctx))
+    return unknownResult;
+  let result;
+  if (part.replace === undefined) {
+    result = removePattern(value, operator, glob);
+  } else {
+    const replacements = expandWord(part.replace.replacement, st, ctx);
+    const pieces = replacements.length === 1 ? replacements[0] : undefined;
+    if (pieces === undefined)
+      return unknownResult;
+    if (pieces.some((piece) => piece.kind === "unknown"))
+      return because(pieces);
+    const replacement = pieces.map((piece) => piece.text).join("");
+    if (/[&\\]/.test(replacement))
+      return unknownResult;
+    const most = value.length + (operator === "//" ? Math.max(value.length, 1) : 1) * replacement.length;
+    if (most > MAX_VALUE_LENGTH)
+      return [[overLong(`\`${part.text}\``)]];
+    result = replacePattern(value, operator, glob, replacement);
+  }
+  if (quoted)
+    return [[literal2(result)]];
+  if (/\s/.test(result)) {
+    return [[unknown2(`unquoted \`${part.text}\`, which splits into several words`)]];
+  }
+  return [unquotedLiteral(result.replaceAll("\\", "\\\\"), undefined, st, ctx)];
+}
 function substitution(script, text, st, ctx) {
   const pidRead = /^\$\(<(.+)\)$/.exec(text);
   const variableRead = /^\$\(<"?\$([A-Za-z_][A-Za-z0-9_]*)"?\)$/.exec(text);
@@ -41693,6 +42017,8 @@ function substitutionPath(base, list, st) {
   const target = literalText(operands(list, "").operands.at(-1)?.exp);
   if (target === undefined || st.cwd === undefined)
     return;
+  if (target === "")
+    return base === "dirname" ? "." : "";
   const abs = path4.resolve(st.cwd, target);
   if (base === "dirname")
     return path4.dirname(abs);
@@ -41771,11 +42097,23 @@ function product(left, right) {
       if (out.length >= MAX_ALTERNATIVES) {
         return [[unknown2(`a brace expansion with more than ${MAX_ALTERNATIVES} alternatives`)]];
       }
-      out.push([...a, ...b]);
+      const long = a.length + b.length > MAX_VALUE_PIECES || textLength(a) + textLength(b) > MAX_VALUE_LENGTH;
+      out.push(long ? [overLong("a word")] : [...a, ...b]);
     }
   }
   return out;
 }
+var MAX_VALUE_LENGTH = 65536;
+var MAX_VALUE_PIECES = 4096;
+function overLong(what) {
+  return unknown2(`${what}, longer than the guard builds (${MAX_VALUE_LENGTH} characters or ${MAX_VALUE_PIECES} pieces)`);
+}
+function textLength(pieces) {
+  let length = 0;
+  for (const piece of pieces)
+    length += piece.text.length;
+  return length;
+}
 function expandWord(word, st, ctx) {
   let alternatives = [[]];
   if (word.parts === undefined)
@@ -41790,8 +42128,38 @@ function expandWord(word, st, ctx) {
 function runtimeText(exp) {
   return exp.map((piece) => piece.kind === "unknown" ? UNKNOWN_MARKER : piece.text).join("");
 }
+var SPLIT_PARTS = new Set([
+  "SimpleExpansion",
+  "ParameterExpansion",
+  "CommandExpansion",
+  "ArithmeticExpansion"
+]);
 function args(words, st, ctx) {
-  return words.flatMap((word) => expandWord(word, st, ctx).map((exp) => ({ text: word.text, exp })));
+  return words.flatMap((word) => {
+    const parts = word.parts ?? [];
+    const unquoted = parts.some((part) => SPLIT_PARTS.has(part.type));
+    const onlyExpansions = parts.length > 0 && parts.every((part) => SPLIT_PARTS.has(part.type));
+    return expandWord(word, st, ctx).map((exp) => {
+      if (exp.some((piece) => piece.kind === "glob")) {
+        return { text: word.text, exp, fields: "unknown" };
+      }
+      if (unquoted && exp.some((piece) => piece.kind === "unknown" || /[ \t\n]/.test(piece.text))) {
+        return { text: word.text, exp, fields: "unknown" };
+      }
+      if (onlyExpansions && exp.every((piece) => piece.text === "")) {
+        return { text: word.text, exp, fields: "none" };
+      }
+      if (exp.length > 0 && exp.every((piece) => piece.noElements === true)) {
+        return { text: word.text, exp, fields: "none" };
+      }
+      return { text: word.text, exp };
+    });
+  });
+}
+function positionalOf(list) {
+  if (list.some((arg) => arg.fields === "unknown"))
+    return;
+  return list.filter((arg) => arg.fields !== "none").map((arg) => arg.exp);
 }
 function literalText(exp) {
   if (exp === undefined || exp.some((piece) => piece.kind !== "literal"))
@@ -41838,6 +42206,19 @@ function visitWord(word, st, ctx) {
   if (word !== undefined)
     visitParts(word.parts, st, ctx);
 }
+var ARITHMETIC_ASSIGNMENTS = new Set([
+  "=",
+  "+=",
+  "-=",
+  "*=",
+  "/=",
+  "%=",
+  "<<=",
+  ">>=",
+  "&=",
+  "^=",
+  "|="
+]);
 function visitArithmetic(expression, st, ctx) {
   if (expression === undefined)
     return;
@@ -41845,9 +42226,14 @@ function visitArithmetic(expression, st, ctx) {
     case "ArithmeticBinary":
       visitArithmetic(expression.left, st, ctx);
       visitArithmetic(expression.right, st, ctx);
+      if (ARITHMETIC_ASSIGNMENTS.has(expression.operator))
+        assignArithmetic(expression.left, st);
       break;
     case "ArithmeticUnary":
       visitArithmetic(expression.operand, st, ctx);
+      if (expression.operator === "++" || expression.operator === "--") {
+        assignArithmetic(expression.operand, st);
+      }
       break;
     case "ArithmeticTernary":
       visitArithmetic(expression.test, st, ctx);
@@ -41865,6 +42251,13 @@ function visitArithmetic(expression, st, ctx) {
       break;
   }
 }
+function assignArithmetic(target, st) {
+  if (target.type !== "ArithmeticWord")
+    return;
+  const name = /[$`]/.test(target.value) ? undefined : target.value;
+  const number4 = [unknown2(`\`$${target.value}\`, an arithmetic result`)];
+  assignByName(st, name, number4, "an arithmetic expression");
+}
 function visitTest(expression, st, ctx) {
   switch (expression.type) {
     case "TestUnary":
@@ -41899,11 +42292,12 @@ function clone2(st) {
     ...st,
     vars: new Map(st.vars),
     exported: new Set(st.exported),
-    arrays: new Map([...st.arrays].map(([name, elements]) => [name, new Map(elements)])),
+    arrays: new Map([...st.arrays].map(([name, elements2]) => [name, new Map(elements2)])),
     functions: new Map(st.functions),
     traps: [...st.traps],
     runningFunctions: new Set(st.runningFunctions),
-    pidFiles: st.pidFiles
+    pidFiles: st.pidFiles,
+    locals: st.locals === undefined ? undefined : new Map(st.locals)
   };
 }
 function merge2(target, branches) {
@@ -41917,9 +42311,35 @@ function merge2(target, branches) {
     if (first !== undefined && values.every((value) => value === values[0])) {
       target.vars.set(name, first);
     } else {
-      target.vars.set(name, [unknown2(`\`$${name}\`, which a branch sets differently`)]);
+      const signalSafe = branches.every((branch) => {
+        const value = branch.vars.get(name);
+        return value !== undefined && (literalText(value) === "" || value.length > 0 && value.every((piece) => piece.descendantPid === true));
+      });
+      const maybeUnset = branches.some((branch) => {
+        const value = branch.vars.get(name);
+        return value === undefined || isUnset(value) || value.some((piece) => piece.maybeUnset);
+      });
+      const rewrites = branches.some((branch) => attributed(branch, name));
+      const cause = branches.flatMap((branch) => branch.vars.get(name) ?? []).find((piece) => piece.kind === "unknown")?.why;
+      const merged2 = unknown2(name === ANY_NAME ? `${cause ?? "a write the guard cannot read may have changed"}, in a branch or loop body` : `\`$${name}\`, which a branch sets differently${cause === undefined ? "" : ` (${cause})`}`, signalSafe ? true : undefined);
+      target.vars.set(name, [
+        {
+          ...merged2,
+          ...maybeUnset ? { maybeUnset: true } : {},
+          ...rewrites ? { rewrites: true } : {}
+        }
+      ]);
     }
   }
+  if (target.locals !== undefined) {
+    const locals = new Map;
+    for (const branch of branches) {
+      for (const name of branch.locals?.keys() ?? []) {
+        locals.set(name, branches.every((other) => other.locals?.get(name) === true));
+      }
+    }
+    target.locals = locals;
+  }
   const arrayNames = new Set;
   for (const branch of branches)
     for (const name of branch.arrays.keys())
@@ -42035,13 +42455,108 @@ function walkList(statements, st, ctx) {
   for (const statement of statements)
     walkNode(statement, st, ctx, false);
 }
+var MAX_DECIDED_PASSES = 64;
+function walkLoopAnyPasses(node, st, ctx) {
+  const before = st.output;
+  const body = clone2(st);
+  walkList(node.clause.commands, body, ctx);
+  walkList(node.body.commands, body, ctx);
+  merge2(st, [clone2(st), body]);
+  if (outputChanged(before, body.output))
+    st.output = undefined;
+}
+function walkLoop(node, st, ctx) {
+  if (!/\b(break|continue)\b/.test(st.source.slice(node.body.pos, node.body.end))) {
+    for (let pass = 0;pass < MAX_DECIDED_PASSES; pass += 1) {
+      const holds = decideCondition(node.clause, st, ctx);
+      if (holds === undefined)
+        break;
+      walkList(node.clause.commands, st, ctx);
+      if (holds === (node.kind === "until"))
+        return;
+      walkList(node.body.commands, st, ctx);
+    }
+  }
+  walkLoopAnyPasses(node, st, ctx);
+}
+function decideCondition(clause, st, ctx) {
+  const [statement, ...others] = clause.commands;
+  if (statement === undefined || others.length > 0 || statement.background)
+    return;
+  const command = statement.command;
+  if (statement.redirects.length > 0 || command.type !== "Command" || command.name === undefined || command.prefix.length > 0 || command.redirects.length > 0) {
+    return;
+  }
+  const name = command.name.text;
+  if (name !== "[" && name !== "test")
+    return;
+  const argv = args(command.suffix, st, ctx);
+  if (argv.length !== command.suffix.length)
+    return;
+  const words = argv.map((arg) => literalText(arg.exp));
+  if (words.some((word) => word === undefined || word === ""))
+    return;
+  const operands = words;
+  if (name === "[")
+    return operands.at(-1) === "]" ? evaluateTest(operands.slice(0, -1)) : undefined;
+  return evaluateTest(operands);
+}
+function decideCase(node, st, ctx) {
+  const words = expandWord(node.word, st, ctx);
+  const value = words.length === 1 ? literalText(words[0]) : undefined;
+  if (value === undefined)
+    return;
+  for (const item of node.items) {
+    for (const word of item.pattern) {
+      const patterns = expandWord(word, st, ctx);
+      const matched = patterns.length === 1 ? matchesPattern(patterns[0], value, ctx) : undefined;
+      if (matched === undefined)
+        return;
+      if (matched)
+        return item.terminator === undefined || item.terminator === ";;" ? item : undefined;
+    }
+  }
+  return;
+}
+function matchesPattern(pattern, value, ctx) {
+  const glob = patternGlob(pattern);
+  if (glob === undefined || !isAscii(value))
+    return;
+  if (!spendPatternWork(globWork(glob, value.length, ""), ctx))
+    return;
+  return globMatches(glob, value);
+}
+function patternGlob(pattern) {
+  const glob = [];
+  for (const piece of pattern) {
+    if (piece.kind === "unknown" || !isAscii(piece.text))
+      return;
+    if (piece.kind === "glob") {
+      if (piece.text === "*")
+        glob.push(ANY_RUN);
+      else if (piece.text === "?")
+        glob.push(ANY_ONE);
+      else
+        return;
+    } else if (/[()|]/.test(piece.text))
+      return;
+    else
+      for (let i = 0;i < piece.text.length; i += 1)
+        glob.push(piece.text.charCodeAt(i));
+  }
+  return glob;
+}
+function spendPatternWork(work, ctx) {
+  ctx.steps.count += Math.ceil(work / PATTERN_WORK_PER_STEP);
+  return ctx.steps.count <= MAX_WALK_STEPS;
+}
 function outputChanged(before, after) {
   return before !== undefined && (after === undefined || JSON.stringify(before) !== JSON.stringify(after));
 }
 function walkNode(node, st, ctx, pipeIn) {
   if (++ctx.steps.count > MAX_WALK_STEPS) {
     const site = siteOf(node, st);
-    throw new Refusal(site.snippet, site.line, `the guard reached its walk limit of ${MAX_WALK_STEPS} nodes; run a smaller script`);
+    throw new Refusal(site.snippet, site.line, WALK_LIMIT);
   }
   switch (node.type) {
     case "Statement": {
@@ -42056,6 +42571,13 @@ function walkNode(node, st, ctx, pipeIn) {
         st.backgroundStarted = true;
         return;
       }
+      if (node.command.type === "BraceGroup") {
+        const written = groupOutputFile(node, st, ctx);
+        if (written !== undefined) {
+          st.files.set(written, walkRenderingGroup(node.command, st, ctx));
+          return;
+        }
+      }
       walkNode(node.command, st, ctx, pipeIn);
       return;
     }
@@ -42126,7 +42648,7 @@ function walkNode(node, st, ctx, pipeIn) {
       if (node.type === "For" && known.every((w) => w !== undefined) && known.length <= 16) {
         for (const value of known) {
           const body = clone2(st);
-          body.vars.set(name, [literal2(value)]);
+          assignScalar(body, name, [literal2(value)]);
           walkList(node.body.commands, body, ctx);
           branches.push(body);
         }
@@ -42136,7 +42658,9 @@ function walkNode(node, st, ctx, pipeIn) {
           const text = literalText(word.exp);
           return text === "" || word.exp.length > 0 && word.exp.every((piece) => piece.descendantPid);
         });
-        body.vars.set(name, signalSafe ? [unknown2(`\`$${name}\`, a loop variable`, true)] : [unknown2(`\`$${name}\`, a loop variable`)]);
+        assignScalar(body, name, signalSafe ? [unknown2(`\`$${name}\`, a loop variable`, true)] : [unknown2(`\`$${name}\`, a loop variable`)]);
+        if (node.type === "Select")
+          assignScalar(body, "REPLY", [unknown2("`$REPLY`, read from input")]);
         walkList(node.body.commands, body, ctx);
         branches.push(body);
       }
@@ -42158,16 +42682,19 @@ function walkNode(node, st, ctx, pipeIn) {
       return;
     }
     case "While": {
-      const before = st.output;
-      const body = clone2(st);
-      walkList(node.clause.commands, body, ctx);
-      walkList(node.body.commands, body, ctx);
-      merge2(st, [clone2(st), body]);
-      if (outputChanged(before, body.output))
-        st.output = undefined;
+      walkLoop(node, st, ctx);
       return;
     }
     case "Case": {
+      const chosen = decideCase(node, st, ctx);
+      if (chosen !== undefined) {
+        visitWord(node.word, st, ctx);
+        for (const item of node.items)
+          for (const word of item.pattern)
+            visitWord(word, st, ctx);
+        walkList(chosen.body.commands, st, ctx);
+        return;
+      }
       const before = st.output;
       visitWord(node.word, st, ctx);
       const branches = [clone2(st)];
@@ -42237,15 +42764,18 @@ function checkRedirects(redirects, command, site, st, ctx) {
       const file2 = path4.resolve(st.cwd ?? "/", target);
       let content = null;
       if (command?.name === "cat" && command.args.length === 0) {
-        content = heredoc?.content ?? (herestring ? herestringText(herestring, st, ctx) : null);
-      } else if (command?.name === "echo" || command?.name === "printf") {
-        const words = command.args.map((arg) => literalText(arg.exp));
-        content = words.every((word) => word !== undefined) ? `${words.join(" ")}
-` : null;
+        if (heredoc !== undefined)
+          content = heredocText(heredoc);
+        else if (herestring !== undefined)
+          content = herestringText(herestring, st, ctx);
+      } else if (command?.name === "echo") {
+        content = echoText(command.args);
+      } else if (command?.name === "printf") {
+        content = printfText(command.args, MAX_SCRIPT_BYTES, true) ?? null;
       }
       st.pidFiles.delete(file2);
       const before = appends ? st.files.get(file2) : "";
-      st.files.set(file2, content === null || before === null ? null : `${before ?? ""}${content}`);
+      st.files.set(file2, content === null || before === null ? null : readable(`${before ?? ""}${content}`));
       if (writes && !appends && command?.name === "echo" && command.args.length === 1 && command.args[0]?.exp.length > 0 && command.args[0]?.exp.every((piece) => piece.descendantPid)) {
         st.pidFiles.set(file2, command.args[0].exp);
       }
@@ -42257,6 +42787,137 @@ function herestringText(redirect, st, ctx) {
     return null;
   return literalText(expandWord(redirect.target, st, ctx)[0]) ?? null;
 }
+function groupOutputFile(statement, st, ctx) {
+  const [redirect, ...others] = statement.redirects;
+  if (redirect === undefined || others.length > 0 || redirect.fileDescriptor !== undefined) {
+    return;
+  }
+  if (redirect.operator !== ">" && redirect.operator !== ">|" || redirect.target === undefined) {
+    return;
+  }
+  const targets = expandWord(redirect.target, st, ctx);
+  const target = targets.length === 1 ? literalText(targets[0]) : undefined;
+  if (target === undefined || st.cwd === undefined && !target.startsWith("/"))
+    return;
+  return path4.resolve(st.cwd ?? "/", target);
+}
+function walkRenderingGroup(group, st, ctx) {
+  let content = "";
+  for (const statement of group.body.commands) {
+    if (content !== null) {
+      const text = statementOutput(statement, st, ctx);
+      content = text === undefined ? null : readable(content + text);
+    }
+    walkNode(statement, st, ctx, false);
+  }
+  return content;
+}
+function echoText(list) {
+  if (literalText(list[0]?.exp)?.startsWith("-"))
+    return null;
+  const words = [];
+  let length = 0;
+  for (const arg of list) {
+    const word = literalText(arg.exp);
+    if (word === undefined)
+      return null;
+    words.push(word);
+    length += word.length + 1;
+  }
+  return length > MAX_SCRIPT_BYTES ? null : `${words.join(" ")}
+`;
+}
+function readable(content) {
+  return content.length > MAX_SCRIPT_BYTES ? null : content;
+}
+function heredocText(heredoc) {
+  const text = heredoc.content;
+  if (text === undefined)
+    return null;
+  return !heredoc.heredocQuoted && /[$`]|\\[$`\\\n]/.test(text) ? null : text;
+}
+function statementOutput(statement, st, ctx) {
+  const command = statement.command;
+  if (statement.background || statement.redirects.length > 0 || command.type !== "Command") {
+    return;
+  }
+  if (command.name === undefined)
+    return command.redirects.length === 0 ? "" : undefined;
+  const name = literalText(expandWord(command.name, st, ctx)[0]);
+  const rest = args(command.suffix, st, ctx);
+  if (name === "cat" && rest.length === 0) {
+    const [heredoc, ...others] = command.redirects;
+    if (heredoc === undefined || others.length > 0)
+      return;
+    if (heredoc.operator !== "<<" && heredoc.operator !== "<<-")
+      return;
+    return heredocText(heredoc) ?? undefined;
+  }
+  if (command.redirects.length > 0)
+    return;
+  if (name === "printf")
+    return printfText(rest, MAX_SCRIPT_BYTES, true);
+  if (name === "echo")
+    return echoText(rest) ?? undefined;
+  return;
+}
+function printfText(list, limit, script = false) {
+  const [formatArg, ...values] = list;
+  const format = literalText(formatArg?.exp);
+  if (format === undefined || format.startsWith("-"))
+    return;
+  if (script && values.some((value) => value.fields === "unknown"))
+    return;
+  const parts = [];
+  for (let i = 0;i < format.length; i += 1) {
+    const char = format.charAt(i);
+    const next = format.charAt(i + 1);
+    if (char === "%") {
+      if (next === "%")
+        parts.push({ text: "%" });
+      else if (next === "s" || next === "q" || next === "d")
+        parts.push({ conversion: next });
+      else
+        return;
+      i += 1;
+    } else if (char === "\\") {
+      const text = next === "n" ? `
+` : next === "t" ? "\t" : next === "\\" ? "\\" : undefined;
+      if (text === undefined)
+        return;
+      parts.push({ text });
+      i += 1;
+    } else
+      parts.push({ text: char });
+  }
+  const conversions = parts.filter((part) => ("conversion" in part)).length;
+  let out = "";
+  let index = 0;
+  do {
+    for (const part of parts) {
+      if ("text" in part) {
+        out += part.text;
+        continue;
+      }
+      const value = values[index];
+      index += 1;
+      if (script && part.conversion !== "d" && value !== undefined) {
+        if (literalText(value.exp) === undefined)
+          return;
+      }
+      const text = value === undefined ? "" : runtimeText(value.exp);
+      if (part.conversion === "s")
+        out += text;
+      else if (part.conversion === "d")
+        out += /^-?[0-9]+$/.test(text) ? text : value === undefined ? "0" : UNKNOWN_MARKER;
+      else
+        out += shellQuoted(text);
+      if (out.length > limit)
+        return out;
+    }
+  } while (conversions > 0 && index < values.length);
+  return out;
+}
 function refusal(site, detail, ctx) {
   return new Refusal(site.snippet, site.line, `${detail}, outside ${describeRoots(ctx.roots)}. ${HINT}`);
 }
@@ -42270,39 +42931,51 @@ function handleCommand(command, st, ctx, pipeIn) {
       visitWord(word, st, ctx);
     if (assignment.name === undefined)
       continue;
-    const expanded = assignment.value === undefined ? [literal2("")] : expandWord(assignment.value, st, ctx)[0] ?? [];
+    const expanded = stored(assignment.value === undefined ? [literal2("")] : expandWord(assignment.value, st, ctx)[0] ?? []);
     const arrayAssignment = assignment.array !== undefined || assignment.append || assignment.index !== undefined;
     const descendantPid = expanded.length > 0 && expanded.every((piece) => piece.descendantPid);
     const value = arrayAssignment ? [unknown2(`\`$${assignment.name}\`, an array or appended value`, descendantPid || undefined)] : expanded;
-    overlay.set(assignment.name, value);
+    overlay.set(assignment.name, attributed(st, assignment.name) ? [{ ...unknown2(`\`$${assignment.name}\`, an attributed variable`), rewrites: true }] : value);
     if (command.name === undefined) {
-      if (arrayAssignment) {
-        const elements = assignment.array !== undefined && !assignment.append ? new Map : new Map(st.arrays.get(assignment.name) ?? []);
+      if (!arrayAssignment) {
+        assignScalar(st, assignment.name, value);
+      } else if (attributed(st, assignment.name)) {
+        keepAttributed(st, assignment.name);
+      } else {
+        const elements2 = assignment.array !== undefined && !assignment.append ? new Map : new Map(st.arrays.get(assignment.name) ?? []);
         if (assignment.array !== undefined) {
-          let index = assignment.append ? Math.max(0, ...[...elements.keys()].filter((key) => /^[0-9]+$/.test(key)).map((key) => Number(key) + 1)) : 0;
-          for (const word of assignment.array) {
-            elements.set(String(index), expandWord(word, st, ctx)[0] ?? []);
-            index += 1;
+          let index = assignment.append ? Math.max(0, ...[...elements2.keys()].filter((key) => /^[0-9]+$/.test(key)).map((key) => Number(key) + 1)) : 0;
+          const words2 = args(assignment.array, st, ctx);
+          if (words2.some((word) => word.fields === "unknown")) {
+            elements2.clear();
+            elements2.set(UNKNOWN_ARRAY_INDEX, [
+              unknown2(`\`$${assignment.name}\`, an array a word of which may be several elements`)
+            ]);
+          } else {
+            for (const word of words2) {
+              if (word.fields === "none")
+                continue;
+              elements2.set(String(index), stored(word.exp));
+              index += 1;
+            }
           }
         } else if (assignment.append) {
-          const index = Math.max(0, ...[...elements.keys()].filter((key) => /^[0-9]+$/.test(key)).map((key) => Number(key) + 1));
-          elements.set(String(index), expanded);
+          const index = Math.max(0, ...[...elements2.keys()].filter((key) => /^[0-9]+$/.test(key)).map((key) => Number(key) + 1));
+          elements2.set(String(index), expanded);
         } else {
           const index = resolveArrayIndex(assignment.index, st, ctx);
           if (index === undefined) {
-            elements.clear();
-            elements.set(UNKNOWN_ARRAY_INDEX, [
+            elements2.clear();
+            elements2.set(UNKNOWN_ARRAY_INDEX, [
               unknown2(`\`$${assignment.name}\`, an array element with an unresolved index`)
             ]);
           } else {
-            elements.set(index, expanded);
+            elements2.set(index, expanded);
           }
         }
-        st.arrays.set(assignment.name, elements);
-      } else {
-        st.arrays.delete(assignment.name);
+        st.arrays.set(assignment.name, elements2);
+        st.vars.set(assignment.name, value);
       }
-      st.vars.set(assignment.name, value);
     }
   }
   const words = command.name === undefined ? command.suffix : [command.name, ...command.suffix];
@@ -42441,7 +43114,7 @@ function unwrap2(argv, st, ctx, site) {
         list = rest.slice(i);
       state = { ...clone2(state), cwd, cwdWhy: "`env -C`" };
       for (const name2 of unset) {
-        state.vars.set(name2, [literal2("")]);
+        state.vars.set(name2, UNSET);
         state.exported.delete(name2);
       }
       for (const [name2, value] of overlay) {
@@ -42458,9 +43131,10 @@ function runFunction(name, definition, args2, outer, ctx) {
     return;
   const child = {
     ...clone2(outer),
-    positional: args2.map((arg) => arg.exp),
+    positional: positionalOf(args2),
     source: definition.source,
-    script: definition.file ?? outer.script
+    script: definition.file ?? outer.script,
+    locals: new Map
   };
   child.runningFunctions.add(name);
   try {
@@ -42468,11 +43142,12 @@ function runFunction(name, definition, args2, outer, ctx) {
   } catch (error48) {
     locateRefusal(error48, definition.file);
   }
+  returnLocals(name, child, outer);
   outer.vars = child.vars;
   outer.exported = child.exported;
   outer.arrays.clear();
-  for (const [name2, elements] of child.arrays)
-    outer.arrays.set(name2, new Map(elements));
+  for (const [name2, elements2] of child.arrays)
+    outer.arrays.set(name2, new Map(elements2));
   outer.cwd = child.cwd;
   outer.cwdWhy = child.cwdWhy;
   outer.functions = child.functions;
@@ -42480,15 +43155,47 @@ function runFunction(name, definition, args2, outer, ctx) {
   outer.output = child.output;
   outer.backgroundStarted ||= child.backgroundStarted;
 }
+function returnLocals(name, child, caller) {
+  for (const [local, everyPath] of child.locals ?? []) {
+    const value = caller.vars.get(local);
+    const elements2 = caller.arrays.get(local);
+    if (everyPath) {
+      if (value === undefined)
+        child.vars.delete(local);
+      else
+        child.vars.set(local, value);
+      if (elements2 === undefined)
+        child.arrays.delete(local);
+      else
+        child.arrays.set(local, new Map(elements2));
+      if (caller.exported.has(local))
+        child.exported.add(local);
+      else
+        child.exported.delete(local);
+      continue;
+    }
+    const same = JSON.stringify(child.vars.get(local) ?? null) === JSON.stringify(value ?? null) && JSON.stringify([...child.arrays.get(local) ?? []]) === JSON.stringify([...elements2 ?? []]);
+    if (same)
+      continue;
+    const either = [
+      { ...unknown2(`\`$${local}\`, local to \`${name}\` on some paths`), maybeUnset: true }
+    ];
+    child.vars.set(local, either);
+    if (elements2 !== undefined || child.arrays.has(local)) {
+      child.arrays.set(local, new Map([[UNKNOWN_ARRAY_INDEX, either]]));
+    }
+  }
+}
 function functionOutput(name, definition, args2, outer, ctx) {
   if (outer.runningFunctions.has(name))
     return;
   const child = {
     ...clone2(outer),
-    positional: args2.map((arg) => arg.exp),
+    positional: positionalOf(args2),
     source: definition.source,
     script: definition.file ?? outer.script,
-    output: []
+    output: [],
+    locals: new Map
   };
   child.runningFunctions.add(name);
   try {
@@ -42529,7 +43236,9 @@ function dispatch(invocation, outer, ctx) {
     return;
   }
   const stdoutRedirected = invocation.redirects.some((redirect) => (redirect.fileDescriptor === undefined || redirect.fileDescriptor === 1) && [">", ">>", ">|", "&>", "&>>", ">&"].includes(redirect.operator));
-  if (outer.output !== undefined && !stdoutRedirected && base !== "echo" && base !== "printf" && FUNCTION_OUTPUT_SILENT[base] !== true) {
+  const umaskWords = base === "umask" ? rest.map((arg) => literalText(arg.exp)) : [];
+  const silentUmask = umaskWords.every((word) => word !== undefined) && umaskWords.some((word) => !word?.startsWith("-"));
+  if (outer.output !== undefined && !stdoutRedirected && base !== "echo" && base !== "printf" && !silentUmask && FUNCTION_OUTPUT_SILENT[base] !== true) {
     outer.output = undefined;
   }
   switch (base) {
@@ -42553,35 +43262,68 @@ function dispatch(invocation, outer, ctx) {
     case "typeset":
     case "local":
     case "readonly":
-      declaration(base, rest, outer, ctx);
+      declaration(base, rest, outer, ctx, site);
       return;
-    case "unset":
-      for (const arg of operands(rest, "").operands) {
-        const variable = literalText(arg.exp);
-        if (variable !== undefined) {
-          outer.vars.set(variable, [literal2("")]);
-          outer.arrays.delete(variable);
+    case "unset": {
+      const found = operands(rest, "");
+      const functionsOnly = found.options.some((option) => /^-[a-zA-Z]*f/.test(option));
+      const variablesOnly = found.options.some((option) => /^-[a-zA-Z]*v/.test(option));
+      for (const arg of found.operands) {
+        const name2 = literalText(arg.exp);
+        if (!variablesOnly) {
+          if (name2 === undefined) {
+            for (const [fn, callee2] of outer.functions)
+              outer.functions.set(fn, orCommand(callee2));
+          } else {
+            const callee2 = outer.functions.get(name2);
+            const held = functionsOnly ? undefined : lookup(name2, outer, ctx);
+            if (callee2 !== undefined && held === undefined)
+              outer.functions.delete(name2);
+            else if (callee2 !== undefined && held?.some((piece) => piece.maybeUnset)) {
+              outer.functions.set(name2, orCommand(callee2));
+            }
+          }
         }
+        if (functionsOnly)
+          continue;
+        if (name2 === undefined || !IDENTIFIER.test(name2)) {
+          assignByName(outer, name2, [], "`unset`");
+          continue;
+        }
+        if (attributed(outer, name2)) {
+          keepAttributed(outer, name2, true);
+          continue;
+        }
+        outer.vars.set(name2, UNSET);
+        outer.exported.delete(name2);
+        outer.arrays.delete(name2);
       }
       return;
+    }
     case "read":
     case "mapfile":
     case "readarray":
     case "getopts": {
-      const found = operands(rest, base === "read" || base === "getopts" ? "adnNptui" : "");
-      const names = base === "getopts" ? found.operands.slice(1, 2) : found.operands;
-      const arrayAt = base === "read" ? rest.findIndex((arg) => literalText(arg.exp) === "-a") : -1;
-      const readsArray = base === "mapfile" || base === "readarray" || arrayAt !== -1;
-      const destinations = arrayAt === -1 || rest[arrayAt + 1] === undefined ? names : [rest[arrayAt + 1]];
-      for (const arg of destinations) {
-        const variable = literalText(arg.exp);
-        if (variable !== undefined) {
-          outer.vars.set(variable, [unknown2(`\`$${variable}\`, read from input`)]);
-          if (readsArray) {
-            const unknownArray = [unknown2(`\`$${variable}\`, read from input`)];
-            outer.arrays.set(variable, new Map([[UNKNOWN_ARRAY_INDEX, unknownArray]]));
-          }
-        }
+      readInput(base, rest, outer);
+      return;
+    }
+    case "wait": {
+      for (const [index, arg] of rest.entries()) {
+        if (!/^-[a-zA-Z]*p$/.test(literalText(arg.exp) ?? ""))
+          continue;
+        const pid = [{ ...unknown2("the pid `wait -p` assigns", true), maybeUnset: true }];
+        assignByName(outer, literalText(rest[index + 1]?.exp), pid, "`wait -p`");
+      }
+      return;
+    }
+    case "let": {
+      for (const arg of rest) {
+        const text = literalText(arg.exp);
+        const command = text === undefined ? undefined : parse5(`(( ${text} ))`).commands[0]?.command;
+        if (command?.type === "ArithmeticCommand")
+          visitArithmetic(command.expression, outer, ctx);
+        else
+          forgetVariables(outer, "`let` in text the guard cannot read may have changed");
       }
       return;
     }
@@ -42589,22 +43331,46 @@ function dispatch(invocation, outer, ctx) {
       const list = rest.map((arg) => literalText(arg.exp));
       const dashDash = list.indexOf("--");
       if (dashDash !== -1)
-        outer.positional = rest.slice(dashDash + 1).map((arg) => arg.exp);
+        outer.positional = positionalOf(rest.slice(dashDash + 1));
       else if (list.length > 0 && !list[0]?.startsWith("-") && !list[0]?.startsWith("+")) {
-        outer.positional = rest.map((arg) => arg.exp);
+        outer.positional = positionalOf(rest);
       }
       return;
     }
     case "shift": {
-      const count = Number(literalText(rest[0]?.exp) ?? "1");
-      outer.positional = Number.isInteger(count) ? outer.positional?.slice(count) : undefined;
+      const text = rest.length === 0 ? "1" : literalText(rest[0]?.exp);
+      if (text === undefined)
+        outer.positional = undefined;
+      else if (/^[0-9]+$/.test(text) && outer.positional !== undefined) {
+        const count = Number(text);
+        if (count <= outer.positional.length)
+          outer.positional = outer.positional.slice(count);
+      }
       return;
     }
     case "printf": {
-      const at = rest.findIndex((arg) => literalText(arg.exp) === "-v");
-      const variable = at === -1 ? undefined : literalText(rest[at + 1]?.exp);
-      if (variable !== undefined) {
-        outer.vars.set(variable, [unknown2(`\`$${variable}\` (printf -v)`)]);
+      const head = rest[0]?.exp ?? [];
+      const leading = head[0];
+      const spaced = literalText(head) === "-v";
+      const joined = !spaced && leading?.kind === "literal" && leading.text.startsWith("-v") && (leading.text.length > 2 || head.length > 1);
+      if (spaced || joined) {
+        const variable = spaced ? literalText(rest[1]?.exp) : literalText([
+          { ...leading, text: leading?.text.slice(2) ?? "" },
+          ...head.slice(1)
+        ]);
+        const printed = rest.slice(spaced ? 2 : 1);
+        const [format, value, ...others] = printed;
+        let assigned;
+        if (literalText(format?.exp) === "%s" && value !== undefined && others.length === 0) {
+          assigned = value.exp;
+        } else {
+          const text = printfText(printed, MAX_VALUE_LENGTH);
+          const cause = printed.flatMap((arg) => arg.exp).find((p) => p.kind === "unknown")?.why;
+          assigned = text === undefined || text.includes(UNKNOWN_MARKER) ? [
+            unknown2(`\`$${variable ?? "?"}\` (printf -v${cause === undefined ? "" : `: ${cause}`})`)
+          ] : text.length > MAX_VALUE_LENGTH ? [overLong(`\`$${variable ?? "?"}\` (printf -v)`)] : [literal2(text)];
+        }
+        assignByName(outer, variable, assigned, "`printf -v`");
         return;
       }
       if (outer.output !== undefined && !stdoutRedirected) {
@@ -42613,7 +43379,11 @@ function dispatch(invocation, outer, ctx) {
       return;
     }
     case "eval": {
-      runText(rest.map((arg) => runtimeText(arg.exp)).join(" "), "the `eval` text", outer, ctx, site);
+      const text = rest.map((arg) => runtimeText(arg.exp)).join(" ");
+      runText(text, "the `eval` text", outer, ctx, site);
+      if (text.includes(UNKNOWN_MARKER)) {
+        forgetVariables(outer, "`eval` of text the guard cannot read may have changed");
+      }
       return;
     }
     case "trap": {
@@ -42621,12 +43391,12 @@ function dispatch(invocation, outer, ctx) {
       if (handler === undefined)
         return;
       const text = literalText(handler.exp);
-      const readable = conditions.map((arg) => literalText(arg.exp));
-      const signals = readable.map((condition) => condition === undefined ? UNREADABLE_CONDITION : trapSignal(condition));
+      const readable2 = conditions.map((arg) => literalText(arg.exp));
+      const signals = readable2.map((condition) => condition === undefined ? UNREADABLE_CONDITION : trapSignal(condition));
       const handled = signals.length === 0 ? ["EXIT"] : signals;
       const file2 = outer.script ?? outer.source;
       if (text === "-") {
-        const named = readable.flatMap((condition) => condition === undefined ? [] : [trapSignal(condition)]);
+        const named = readable2.flatMap((condition) => condition === undefined ? [] : [trapSignal(condition)]);
         outer.traps = outer.traps.flatMap((trap) => {
           const signals2 = trap.signals.filter((signal) => !named.includes(signal));
           return signals2.length === 0 ? [] : [{ ...trap, signals: signals2 }];
@@ -42759,7 +43529,8 @@ function dispatch(invocation, outer, ctx) {
         if (target !== undefined && st.cwd !== undefined) {
           const file2 = path4.resolve(st.cwd, target);
           st.pidFiles.delete(file2);
-          st.files.set(file2, append ? null : heredoc?.content ?? null);
+          const text = heredoc === undefined ? null : heredocText(heredoc);
+          st.files.set(file2, append || text === null ? null : readable(text));
         }
       }
       return;
@@ -42862,37 +43633,156 @@ function changeDirectory(target, st, ctx) {
   }
   st.cwd = path4.resolve(st.cwd, text);
 }
-function declaration(builtin, list, st, ctx) {
-  const array2 = list.some((arg) => /^-[a-zA-Z]*[aA]/.test(literalText(arg.exp) ?? ""));
+function declaration(builtin, list, st, ctx, site) {
+  const options = list.map((arg) => literalText(arg.exp) ?? "").filter((text) => /^[-+][a-zA-Z]+$/.test(text));
+  const option = (letter) => options.some((text) => text.startsWith("-") && text.includes(letter));
+  if (builtin !== "export" && option("n")) {
+    throw new Refusal(site.snippet, site.line, "the guard does not follow a nameref (`declare -n`), whose writes land in the variable it names");
+  }
+  if (option("f") || option("F"))
+    return;
+  if (builtin === "local" && st.locals === undefined)
+    return;
+  const array2 = option("a") || option("A");
+  const exports = builtin === "export" || option("x");
+  const keeps = builtin === "readonly" || option("r");
+  const rewrites = option("i") || option("l") || option("u");
+  const locals = builtin === "local" || (builtin === "declare" || builtin === "typeset") && !option("g") ? st.locals : undefined;
+  const writer = `\`${builtin}\``;
   for (const arg of list) {
-    const first = arg.exp[0];
-    const equals = arg.text.indexOf("=");
-    const variable = equals === -1 ? literalText(arg.exp) : arg.text.slice(0, equals);
-    if (variable === undefined || variable.startsWith("-"))
+    const text = literalText(arg.exp);
+    if (text !== undefined && /^[-+][a-zA-Z]+$/.test(text))
+      continue;
+    const { name, value: assigned } = nameAndValue(arg);
+    if (name === undefined) {
+      forgetVariables(st, `${writer} under a name the guard cannot read may have changed`);
+      continue;
+    }
+    const base = ARRAY_ELEMENT.exec(name)?.[1] ?? name;
+    if (!IDENTIFIER.test(base))
+      continue;
+    if (exports)
+      st.exported.add(base);
+    if (rewrites || attributed(st, base) && (assigned !== undefined || locals !== undefined)) {
+      keepAttributed(st, base);
       continue;
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(variable))
+    }
+    if (attributed(st, base))
       continue;
-    if (builtin === "export")
-      st.exported.add(variable);
-    if (equals === -1)
+    if (locals !== undefined) {
+      locals.set(base, true);
+      if (assigned === undefined) {
+        st.vars.set(base, UNSET);
+        st.arrays.delete(base);
+      }
+    }
+    if (assigned === undefined) {
+      if (keeps)
+        markKept(st, base, ctx);
       continue;
-    let value = first?.kind === "literal" && first.text.startsWith(`${variable}=`) ? [
-      ...first.text.length === equals + 1 ? [] : [literal2(first.text.slice(equals + 1))],
-      ...arg.exp.slice(1)
-    ] : [...arg.exp];
-    if (arg.text.charAt(equals + 1) === "~" && arg.text.startsWith(`${variable}=~`)) {
-      value = [...unquotedLiteral(arg.text.slice(equals + 1), 0, st, ctx), ...arg.exp.slice(1)];
-    }
-    st.vars.set(variable, array2 ? [unknown2(`\`$${variable}\`, an array`)] : value);
-    if (array2) {
-      if (arg.text.slice(equals + 1) === "()") {
-        st.arrays.set(variable, new Map);
+    }
+    const value = arg.text.startsWith(`${name}=~`) ? [...unquotedLiteral(arg.text.slice(name.length + 1), 0, st, ctx), ...arg.exp.slice(1)] : assigned;
+    if (!array2 || name !== base) {
+      assignByName(st, name, value, writer);
+    } else {
+      st.vars.set(name, [unknown2(`\`$${name}\`, an array`)]);
+      if (arg.text === `${name}=()`) {
+        st.arrays.set(name, new Map);
       } else {
-        const unknownArray = [unknown2(`\`$${variable}\`, an array assignment`)];
-        st.arrays.set(variable, new Map([[UNKNOWN_ARRAY_INDEX, unknownArray]]));
+        const unknownArray = [unknown2(`\`$${name}\`, an array assignment`)];
+        st.arrays.set(name, new Map([[UNKNOWN_ARRAY_INDEX, unknownArray]]));
       }
     }
+    if (keeps)
+      markKept(st, base, ctx);
+  }
+}
+function markKept(st, name, ctx) {
+  const held = st.vars.get(name) ?? lookup(name, st, ctx) ?? UNSET;
+  const value = held.length === 0 ? [literal2("")] : held;
+  st.vars.set(name, value.map((piece) => ({ ...piece, rewrites: true })));
+}
+function readInput(builtin, rest, st) {
+  const valued = builtin === "read" ? "adinNptu" : builtin === "getopts" ? "" : "dnOsuCc";
+  const writer = `\`${builtin}\``;
+  const input = (name) => [
+    unknown2(`\`$${name ?? "?"}\`, read from input`)
+  ];
+  let array2;
+  let arrayOption = false;
+  const names = [];
+  let options = builtin !== "getopts";
+  for (let i = 0;i < rest.length; i += 1) {
+    const arg = rest[i];
+    const text = literalText(arg.exp);
+    if (options && text === "--") {
+      options = false;
+      continue;
+    }
+    if (options && text !== undefined && /^-./.test(text)) {
+      for (let j = 1;j < text.length; j += 1) {
+        const flag = text.charAt(j);
+        if (!valued.includes(flag))
+          continue;
+        const attached = text.slice(j + 1);
+        i += attached === "" ? 1 : 0;
+        const value = attached === "" ? rest[i] : { text: attached, exp: [literal2(attached)] };
+        if (flag === "a" && builtin === "read") {
+          arrayOption = true;
+          array2 = value;
+        }
+        break;
+      }
+      continue;
+    }
+    options = false;
+    names.push(arg);
+  }
+  const fill = (arg, fallback) => {
+    const name = arg === undefined ? fallback : literalText(arg.exp);
+    if (name === undefined || !IDENTIFIER.test(name) || attributed(st, name)) {
+      assignByName(st, name, input(name), writer);
+      return;
+    }
+    st.vars.set(name, input(name));
+    st.arrays.set(name, new Map([[UNKNOWN_ARRAY_INDEX, input(name)]]));
+  };
+  if (builtin === "getopts") {
+    const name = names[1];
+    if (name !== undefined)
+      assignByName(st, literalText(name.exp), input(name.text), writer);
+    for (const variable of ["OPTARG", "OPTIND"])
+      assignScalar(st, variable, input(variable));
+  } else if (builtin !== "read") {
+    fill(names[0], "MAPFILE");
+  } else if (arrayOption) {
+    if (array2 !== undefined)
+      fill(array2, "");
+  } else if (names.length === 0) {
+    assignScalar(st, "REPLY", input("REPLY"));
+  } else {
+    for (const name of names)
+      assignByName(st, literalText(name.exp), input(name.text), writer);
+  }
+}
+function orCommand(callee) {
+  return callee.includes(undefined) ? callee : [...callee, undefined];
+}
+function nameAndValue(arg) {
+  let name = "";
+  for (const [index, piece] of arg.exp.entries()) {
+    if (piece.kind !== "literal")
+      return { name: undefined, value: undefined };
+    const equals = piece.text.indexOf("=");
+    if (equals === -1) {
+      name += piece.text;
+      continue;
+    }
+    const rest = piece.text.slice(equals + 1);
+    const value = [...rest === "" ? [] : [{ ...piece, text: rest }], ...arg.exp.slice(index + 1)];
+    return { name: name + piece.text.slice(0, equals), value };
   }
+  return { name, value: undefined };
 }
 function checkTargets(program, verb, targets, follow, st, ctx, site) {
   for (const target of targets) {
@@ -43118,11 +44008,18 @@ function childState(st, overlay) {
     if (value !== undefined)
       vars.set(name, value);
   }
+  for (const [name, value] of st.vars)
+    if (isUnset(value))
+      vars.set(name, value);
   for (const [name, value] of overlay)
     vars.set(name, value);
+  const exported = new Set(vars.keys());
+  const any2 = st.vars.get(ANY_NAME);
+  if (any2 !== undefined)
+    vars.set(ANY_NAME, any2);
   return {
     vars,
-    exported: new Set(vars.keys()),
+    exported,
     cwd: st.cwd,
     cwdWhy: st.cwdWhy,
     positional: [],
@@ -43138,7 +44035,8 @@ function childState(st, overlay) {
     arrays: new Map,
     functions: new Map,
     traps: [],
-    runningFunctions: new Set
+    runningFunctions: new Set,
+    locals: undefined
   };
 }
 function runText(text, label, st, ctx, site) {
@@ -43185,19 +44083,23 @@ function runShell(list, invocation, st, ctx) {
   child.argv0 = operand[1]?.exp;
   if (command) {
     const text = operand[0] === undefined ? "" : runtimeText(operand[0].exp);
-    child.positional = operand.slice(2).map((arg) => arg.exp);
+    child.positional = positionalOf(operand.slice(2));
     runText(text, "its `-c` text", child, ctx, site);
     return;
   }
   const file2 = operand[0];
   if (file2 !== undefined) {
-    child.positional = operand.slice(1).map((arg) => arg.exp);
+    child.positional = positionalOf(operand.slice(1));
     runFile(file2, operand.slice(1), child, ctx, site, "shell");
     return;
   }
   const heredoc = invocation.redirects.find((r) => r.operator === "<<" || r.operator === "<<-");
-  if (heredoc?.content !== undefined) {
-    runText(heredoc.content, "the script it reads from the heredoc", child, ctx, site);
+  if (heredoc !== undefined) {
+    const text = heredocText(heredoc);
+    if (text === null) {
+      throw new Refusal(site.snippet, site.line, "the guard cannot read the script this shell reads from its here-document, which bash expands first; quote its delimiter (`<<'EOF'`) or write the script with the write tool");
+    }
+    runText(text, "the script it reads from the heredoc", child, ctx, site);
     return;
   }
   const herestring = invocation.redirects.find((r) => r.operator === "<<<");
@@ -43253,8 +44155,12 @@ function runInterpreter(base, language, list, invocation, st, ctx) {
       return;
     if (word === "-") {
       const heredoc = invocation.redirects.find((r) => r.operator === "<<" || r.operator === "<<-");
-      if (heredoc?.content !== undefined) {
-        runCode(language, { text: "<heredoc>", exp: [literal2(heredoc.content)] }, invocation, st, ctx, site);
+      if (heredoc !== undefined) {
+        const text = heredocText(heredoc);
+        if (text === null) {
+          throw new Refusal(site.snippet, site.line, "the guard cannot read the program this interpreter reads from its here-document, which bash expands first; quote its delimiter (`<<'PY'`) or write the program with the write tool");
+        }
+        runCode(language, { text: "<heredoc>", exp: [literal2(text)] }, invocation, st, ctx, site);
       }
       return;
     }
@@ -43290,7 +44196,7 @@ function runFile(file2, positional, st, ctx, site, kind, source = false) {
   if (st.files.has(abs)) {
     const written = st.files.get(abs);
     if (written === null || written === undefined) {
-      throw new Refusal(site.snippet, site.line, `this command writes ${abs} in a way the guard cannot read before running it; write the script with the write tool first`);
+      throw new Refusal(site.snippet, site.line, `this command writes ${abs} in a way the guard cannot read before running it (output it cannot render, or more than the ${MAX_SCRIPT_BYTES} bytes it reads of a script); write the script with the write tool first`);
     }
     content = written;
   } else {
@@ -43326,22 +44232,24 @@ function runFile(file2, positional, st, ctx, site, kind, source = false) {
         throw new Refusal(site.snippet, site.line, "the guard stops following scripts this deep; run the inner script directly");
       }
       const child = { ...clone2(st), source: content, script: abs, depth: st.depth + 1 };
-      const operands2 = positional.map((arg) => arg.exp);
-      child.positional = source && operands2.length === 0 ? st.positional : operands2;
+      const operands2 = positionalOf(positional);
+      const noOperands = operands2 !== undefined && operands2.length === 0;
+      child.positional = source && noOperands ? st.positional : operands2;
       walkScript(parse5(content), child, ctx, !source);
       if (source) {
-        st.positional = operands2.length === 0 ? child.positional : child.positional === operands2 ? st.positional : undefined;
+        st.positional = noOperands ? child.positional : child.positional === operands2 ? st.positional : undefined;
         st.vars = child.vars;
         st.exported = child.exported;
         st.arrays.clear();
-        for (const [name, elements] of child.arrays)
-          st.arrays.set(name, new Map(elements));
+        for (const [name, elements2] of child.arrays)
+          st.arrays.set(name, new Map(elements2));
         st.cwd = child.cwd;
         st.cwdWhy = child.cwdWhy;
         st.functions = child.functions;
         st.traps = child.traps;
         st.output = child.output;
         st.backgroundStarted ||= child.backgroundStarted;
+        st.locals = child.locals;
       }
     } else
       checkCode(language, content, st, ctx);
@@ -43383,7 +44291,9 @@ function checkCode(language, code, st, ctx, ipython = false) {
   const env = { ...ctx.env };
   for (const [name, value] of st.vars) {
     const text = literalText(value);
-    if (text !== undefined)
+    if (isUnset(value))
+      delete env[name];
+    else if (text !== undefined)
       env[name] = text;
   }
   scanCode(language, code, { env, cwd: cwd ?? "/", tmpdir: env.TMPDIR ?? "/tmp", ipython }, {
@@ -43465,12 +44375,14 @@ function createPaneGuard(options) {
     if (workspace === "/" || home !== undefined && (home === workspace || home.startsWith(`${workspace}/`))) {
       workspace = undefined;
     }
-    const protectedScratch = [...PROTECTED_SCRATCH];
     const tmuxDir = env.TMUX_TMPDIR === undefined ? undefined : realish(env.TMUX_TMPDIR, true);
-    if (tmuxDir?.startsWith(`${scratch}/`)) {
-      protectedScratch.push(tmuxDir.slice(scratch.length + 1).split("/")[0] ?? "");
+    const protectedDirectories = [];
+    for (const owned of [tmuxDir, home]) {
+      const component = owned?.startsWith(`${scratch}/`) ? owned.slice(scratch.length + 1).split("/")[0] : undefined;
+      if (component !== undefined && component !== "")
+        protectedDirectories.push(component);
     }
-    return { workspace, scratch, protectedScratch };
+    return { workspace, scratch, protectedScratch: PROTECTED_SCRATCH, protectedDirectories };
   };
   const context = (env) => ({
     roots: roots(env),
@@ -43497,12 +44409,13 @@ function createPaneGuard(options) {
     pidFiles: new Map,
     arrays: new Map,
     functions: new Map,
-    traps: []
+    traps: [],
+    locals: undefined
   });
-  const run = (attempt, fallback) => {
+  const run = (ctx, attempt, fallback) => {
     try {
       attempt();
-      return;
+      return ctx.steps.count > MAX_WALK_STEPS ? `refused \`${fallback}\`: ${WALK_LIMIT}` : undefined;
     } catch (error48) {
       if (!(error48 instanceof Refusal))
         throw error48;
@@ -43512,13 +44425,13 @@ function createPaneGuard(options) {
   return {
     bash: (command, cwd, env) => {
       const ctx = context(env);
-      return run(() => walkScript(parse5(command), initial(cwd, command), ctx), command.trim());
+      return run(ctx, () => walkScript(parse5(command), initial(cwd, command), ctx), command.trim());
     },
     argv: (argv, cwd, env) => {
       const ctx = context(env);
       const list = argv.map((item) => ({ text: item, exp: [literal2(item)] }));
       const snippet = argv.join(" ");
-      return run(() => dispatch({
+      return run(ctx, () => dispatch({
         args: list,
         site: { snippet, line: 1 },
         overlay: new Map,
@@ -43528,7 +44441,7 @@ function createPaneGuard(options) {
     },
     code: (language, code, cwd, env) => {
       const ctx = context(env);
-      return run(() => checkCode(language, code, initial(cwd, code), ctx, true), `${language} code`);
+      return run(ctx, () => checkCode(language, code, initial(cwd, code), ctx, true), `${language} code`);
     }
   };
 }