@caupulican/pi-adaptative 0.85.0 → 0.85.3

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [0.85.3] - 2026-08-03
+
+### Fixed
+
+- Fixed the bundled Windows incident collector on PowerShell 5.1 hosts where the module-provided `Get-FileHash` command is unavailable.
+- Fixed native Windows path canonicalization so 8.3 short paths and their long-path spellings resolve to one resource identity.
+- Fixed cooperative worker cleanup under Windows file-lock contention so terminal state is durably persisted, including cleanup requested during the adoption grace window.
+- Fixed system Python detection incorrectly accepting the Windows Store execution alias or another non-Python executable as an installed interpreter.
+
+## [0.85.2] - 2026-08-03
+
+### Fixed
+
+- Fixed fresh Windows search-tool provisioning by pinning checksum-verified `fd` release assets instead of relying on GitHub's rate-limited latest-release API, and hardened Windows release-gate portability without enabling unsupported native tmux.
+
+## [0.85.1] - 2026-08-03
+
+### Fixed
+
+- Prevented concurrent and ineffective repeated auto-compaction runs in image-heavy sessions and contexts with protected recent messages.
+- Fixed Windows runtime probes and case-insensitive context-file identity, plus Bash-like path parsing, portable `printf`, word-list and arithmetic `for` loops, and nested `break`/`continue` in the managed shell.
+- Preserved managed-tool provisioning causes and bounded execution-failure guidance in recovery logs, failure corpora, and `/toolhealth`.
+- Kept proven native tool-call models off the phone/text protocol and routed phone validation, repair teaching, and failure guidance through the shared tool pipeline.
+- Required the exact release ref to pass Linux and Windows CI before publishing binaries.
+
 ## [0.85.0] - 2026-08-02
 
 ### Breaking Changes

package/dist/bundled-resources/runtimes/pi-shell-engine/arithmetic.py

@@ -0,0 +1,364 @@
+"""Safe integer-expression parser/evaluator for arithmetic ``for ((...))`` loops.
+
+The evaluator deliberately does not call Python ``eval``. It accepts the integer,
+variable, update, assignment, comparison, logical, bitwise, and conditional operators
+used by Bash loop headers, then applies signed 64-bit wrapping after arithmetic writes.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from state import ShellState
+
+_MASK = (1 << 64) - 1
+_SIGN_BIT = 1 << 63
+_ASSIGNMENT_OPERATORS = frozenset(
+    {"=", "+=", "-=", "*=", "/=", "%=", "<<=", ">>=", "&=", "^=", "|="}
+)
+_TOKEN_RE = re.compile(
+    r"\s*(?:"
+    r"(?P<number>0[xX][0-9A-Fa-f]+|0[bB][01]+|0[0-7]+|[0-9]+)"
+    r"|(?P<variable>\$?[A-Za-z_][A-Za-z0-9_]*)"
+    r"|(?P<operator>\*\*|\+\+|--|<<=|>>=|\+=|-=|\*=|/=|%=|&=|\^=|\|="
+    r"|\|\||&&|==|!=|<=|>=|<<|>>|[=+\-*/%<>()!~&^|?:,])"
+    r")"
+)
+
+
+class ArithmeticError(ValueError):
+    """A bounded syntax or runtime failure in a loop arithmetic expression."""
+
+
+@dataclass(frozen=True)
+class _Token:
+    kind: str
+    text: str
+
+
+@dataclass(frozen=True)
+class _Number:
+    value: int
+
+
+@dataclass(frozen=True)
+class _Variable:
+    name: str
+
+
+@dataclass(frozen=True)
+class _Unary:
+    operator: str
+    operand: "_Expression"
+
+
+@dataclass(frozen=True)
+class _Binary:
+    operator: str
+    left: "_Expression"
+    right: "_Expression"
+
+
+@dataclass(frozen=True)
+class _Conditional:
+    condition: "_Expression"
+    when_true: "_Expression"
+    when_false: "_Expression"
+
+
+@dataclass(frozen=True)
+class _Assignment:
+    operator: str
+    target: _Variable
+    value: "_Expression"
+
+
+@dataclass(frozen=True)
+class _Update:
+    operator: str
+    target: _Variable
+    prefix: bool
+
+
+@dataclass(frozen=True)
+class _Sequence:
+    expressions: tuple["_Expression", ...]
+
+
+_Expression = _Number | _Variable | _Unary | _Binary | _Conditional | _Assignment | _Update | _Sequence
+
+
+def _wrap(value: int) -> int:
+    unsigned = value & _MASK
+    return unsigned - (1 << 64) if unsigned & _SIGN_BIT else unsigned
+
+
+def _parse_integer(text: str) -> int:
+    if text.lower().startswith(("0x", "0b")):
+        return _wrap(int(text, 0))
+    if len(text) > 1 and text.startswith("0"):
+        return _wrap(int(text, 8))
+    return _wrap(int(text, 10))
+
+
+def _tokenize(source: str) -> list[_Token]:
+    tokens: list[_Token] = []
+    position = 0
+    while position < len(source):
+        match = _TOKEN_RE.match(source, position)
+        if match is None:
+            excerpt = source[position : position + 16]
+            raise ArithmeticError(f"unexpected arithmetic token near {excerpt!r}")
+        kind = match.lastgroup
+        assert kind is not None
+        text = match.group(kind)
+        if kind == "variable" and text.startswith("$"):
+            text = text[1:]
+        tokens.append(_Token(kind, text))
+        position = match.end()
+    tokens.append(_Token("end", ""))
+    return tokens
+
+
+class _Parser:
+    def __init__(self, source: str) -> None:
+        self.tokens = _tokenize(source)
+        self.index = 0
+
+    def current(self) -> _Token:
+        return self.tokens[self.index]
+
+    def accept(self, operator: str) -> bool:
+        if self.current().kind == "operator" and self.current().text == operator:
+            self.index += 1
+            return True
+        return False
+
+    def require(self, operator: str) -> None:
+        if not self.accept(operator):
+            raise ArithmeticError(f"expected {operator!r} in arithmetic expression")
+
+    def parse(self) -> _Expression:
+        expression = self.parse_sequence()
+        if self.current().kind != "end":
+            raise ArithmeticError(f"unexpected arithmetic token {self.current().text!r}")
+        return expression
+
+    def parse_sequence(self) -> _Expression:
+        expressions = [self.parse_assignment()]
+        while self.accept(","):
+            expressions.append(self.parse_assignment())
+        return expressions[0] if len(expressions) == 1 else _Sequence(tuple(expressions))
+
+    def parse_assignment(self) -> _Expression:
+        target = self.parse_conditional()
+        token = self.current()
+        if token.kind != "operator" or token.text not in _ASSIGNMENT_OPERATORS:
+            return target
+        self.index += 1
+        if not isinstance(target, _Variable):
+            raise ArithmeticError("the left side of an arithmetic assignment must be a variable")
+        return _Assignment(token.text, target, self.parse_assignment())
+
+    def parse_conditional(self) -> _Expression:
+        condition = self.parse_logical_or()
+        if not self.accept("?"):
+            return condition
+        when_true = self.parse_sequence()
+        self.require(":")
+        return _Conditional(condition, when_true, self.parse_assignment())
+
+    def parse_logical_or(self) -> _Expression:
+        return self._parse_left_associative(self.parse_logical_and, frozenset({"||"}))
+
+    def parse_logical_and(self) -> _Expression:
+        return self._parse_left_associative(self.parse_bitwise_or, frozenset({"&&"}))
+
+    def parse_bitwise_or(self) -> _Expression:
+        return self._parse_left_associative(self.parse_bitwise_xor, frozenset({"|"}))
+
+    def parse_bitwise_xor(self) -> _Expression:
+        return self._parse_left_associative(self.parse_bitwise_and, frozenset({"^"}))
+
+    def parse_bitwise_and(self) -> _Expression:
+        return self._parse_left_associative(self.parse_equality, frozenset({"&"}))
+
+    def parse_equality(self) -> _Expression:
+        return self._parse_left_associative(self.parse_relational, frozenset({"==", "!="}))
+
+    def parse_relational(self) -> _Expression:
+        return self._parse_left_associative(self.parse_shift, frozenset({"<", "<=", ">", ">="}))
+
+    def parse_shift(self) -> _Expression:
+        return self._parse_left_associative(self.parse_additive, frozenset({"<<", ">>"}))
+
+    def parse_additive(self) -> _Expression:
+        return self._parse_left_associative(self.parse_multiplicative, frozenset({"+", "-"}))
+
+    def parse_multiplicative(self) -> _Expression:
+        return self._parse_left_associative(self.parse_power, frozenset({"*", "/", "%"}))
+
+    def parse_power(self) -> _Expression:
+        left = self.parse_unary()
+        if self.accept("**"):
+            return _Binary("**", left, self.parse_power())
+        return left
+
+    def parse_unary(self) -> _Expression:
+        token = self.current()
+        if token.kind == "operator" and token.text in ("+", "-", "!", "~"):
+            self.index += 1
+            return _Unary(token.text, self.parse_unary())
+        if token.kind == "operator" and token.text in ("++", "--"):
+            self.index += 1
+            target = self.parse_unary()
+            if not isinstance(target, _Variable):
+                raise ArithmeticError(f"{token.text} requires a variable")
+            return _Update(token.text, target, True)
+        return self.parse_postfix()
+
+    def parse_postfix(self) -> _Expression:
+        expression = self.parse_primary()
+        token = self.current()
+        if token.kind == "operator" and token.text in ("++", "--"):
+            self.index += 1
+            if not isinstance(expression, _Variable):
+                raise ArithmeticError(f"{token.text} requires a variable")
+            return _Update(token.text, expression, False)
+        return expression
+
+    def parse_primary(self) -> _Expression:
+        token = self.current()
+        if token.kind == "number":
+            self.index += 1
+            return _Number(_parse_integer(token.text))
+        if token.kind == "variable":
+            self.index += 1
+            return _Variable(token.text)
+        if self.accept("("):
+            expression = self.parse_sequence()
+            self.require(")")
+            return expression
+        raise ArithmeticError(f"expected an integer, variable, or '('; found {token.text!r}")
+
+    def _parse_left_associative(self, operand_parser, operators: frozenset[str]) -> _Expression:
+        expression = operand_parser()
+        while self.current().kind == "operator" and self.current().text in operators:
+            operator = self.current().text
+            self.index += 1
+            expression = _Binary(operator, expression, operand_parser())
+        return expression
+
+
+def compile_arithmetic(source: str) -> _Expression | None:
+    stripped = source.strip()
+    return None if not stripped else _Parser(stripped).parse()
+
+
+def _variable_value(variable: _Variable, state: ShellState) -> int:
+    text = state.env.get(variable.name, "").strip()
+    if not text:
+        return 0
+    try:
+        return _parse_integer(text)
+    except ValueError:
+        return 0
+
+
+def _set_variable(variable: _Variable, value: int, state: ShellState) -> int:
+    wrapped = _wrap(value)
+    state.setenv(variable.name, str(wrapped))
+    return wrapped
+
+
+def _divide(left: int, right: int) -> int:
+    if right == 0:
+        raise ArithmeticError("division by zero")
+    quotient = abs(left) // abs(right)
+    return -quotient if (left < 0) != (right < 0) else quotient
+
+
+def _binary(operator: str, left: int, right: int) -> int:
+    if operator == "+":
+        return _wrap(left + right)
+    if operator == "-":
+        return _wrap(left - right)
+    if operator == "*":
+        return _wrap(left * right)
+    if operator == "/":
+        return _wrap(_divide(left, right))
+    if operator == "%":
+        return _wrap(left - _divide(left, right) * right)
+    if operator == "**":
+        if right < 0:
+            raise ArithmeticError("negative exponent")
+        return _wrap(pow(left & _MASK, right, 1 << 64))
+    if operator in ("<<", ">>"):
+        if right < 0 or right >= 64:
+            raise ArithmeticError("shift count must be between 0 and 63")
+        return _wrap(left << right) if operator == "<<" else _wrap(left >> right)
+    if operator == "&":
+        return _wrap(left & right)
+    if operator == "^":
+        return _wrap(left ^ right)
+    if operator == "|":
+        return _wrap(left | right)
+    if operator == "==":
+        return int(left == right)
+    if operator == "!=":
+        return int(left != right)
+    if operator == "<":
+        return int(left < right)
+    if operator == "<=":
+        return int(left <= right)
+    if operator == ">":
+        return int(left > right)
+    if operator == ">=":
+        return int(left >= right)
+    raise ArithmeticError(f"unsupported arithmetic operator {operator!r}")
+
+
+def evaluate_arithmetic(expression: _Expression | None, state: ShellState) -> int:
+    if expression is None:
+        return 0
+    if isinstance(expression, _Number):
+        return expression.value
+    if isinstance(expression, _Variable):
+        return _variable_value(expression, state)
+    if isinstance(expression, _Sequence):
+        result = 0
+        for item in expression.expressions:
+            result = evaluate_arithmetic(item, state)
+        return result
+    if isinstance(expression, _Conditional):
+        branch = expression.when_true if evaluate_arithmetic(expression.condition, state) != 0 else expression.when_false
+        return evaluate_arithmetic(branch, state)
+    if isinstance(expression, _Unary):
+        value = evaluate_arithmetic(expression.operand, state)
+        if expression.operator == "+":
+            return value
+        if expression.operator == "-":
+            return _wrap(-value)
+        if expression.operator == "!":
+            return int(value == 0)
+        if expression.operator == "~":
+            return _wrap(~value)
+    if isinstance(expression, _Binary):
+        left = evaluate_arithmetic(expression.left, state)
+        if expression.operator == "&&":
+            return int(left != 0 and evaluate_arithmetic(expression.right, state) != 0)
+        if expression.operator == "||":
+            return int(left != 0 or evaluate_arithmetic(expression.right, state) != 0)
+        return _binary(expression.operator, left, evaluate_arithmetic(expression.right, state))
+    if isinstance(expression, _Assignment):
+        right = evaluate_arithmetic(expression.value, state)
+        if expression.operator == "=":
+            return _set_variable(expression.target, right, state)
+        left = _variable_value(expression.target, state)
+        return _set_variable(expression.target, _binary(expression.operator[:-1], left, right), state)
+    if isinstance(expression, _Update):
+        old = _variable_value(expression.target, state)
+        new = _set_variable(expression.target, old + (1 if expression.operator == "++" else -1), state)
+        return new if expression.prefix else old
+    raise ArithmeticError("unrecognized arithmetic expression")

package/dist/bundled-resources/runtimes/pi-shell-engine/context.py

@@ -44,9 +44,10 @@ class ExecContext:
     builtins: Mapping[str, BuiltinFn]
     deadline: float | None
     stderr: BinaryIO | int | None = None
+    loop_depth: int = 0
 
 
 # Executor-owned builtins are NOT in commands/REGISTRY: state mutators and `exit`
 # need ShellState/control-flow access, while the runner needs the executor.
-STATE_BUILTINS = {"cd", "export", "unset", "exit"}
+STATE_BUILTINS = {"cd", "export", "unset", "exit", "break", "continue"}
 RUNNER_BUILTINS = {"xargs"}

package/dist/bundled-resources/runtimes/pi-shell-engine/errors.py

@@ -55,3 +55,19 @@ class ShellExit(Exception):
     def __init__(self, exit_code: int) -> None:
         super().__init__(exit_code)
         self.exit_code = exit_code
+
+
+class LoopControl(Exception):
+    """Internal non-local control transfer consumed by enclosing loop nodes."""
+
+    def __init__(self, levels: int) -> None:
+        super().__init__(levels)
+        self.levels = levels
+
+
+class LoopBreak(LoopControl):
+    """Leave one or more enclosing loops."""
+
+
+class LoopContinue(LoopControl):
+    """Continue one or more enclosing loops."""

package/dist/bundled-resources/runtimes/pi-shell-engine/exec.py

@@ -10,17 +10,20 @@ import io
 import os
 import subprocess
 import threading
+import time
 from typing import BinaryIO
 
+from arithmetic import ArithmeticError, compile_arithmetic, evaluate_arithmetic
 import nodes
 import parser as parser_module
 import proc
 import tokens as tokens_module
 from context import RUNNER_BUILTINS, STATE_BUILTINS, BuiltinContext, ExecContext
-from errors import ShellExit, UnsupportedConstruct
+from errors import LoopBreak, LoopContinue, LoopControl, ShellExit, UnsupportedConstruct
 from state import ShellState
 
 DEVNULL = os.devnull
+MAX_LOOP_ITERATIONS = 1_000_000
 
 
 class _Redirected:
@@ -344,7 +347,7 @@ def _run_pipeline_elements(elements: list, ctx: ExecContext) -> int:
                 try:
                     # Pipeline stages are subshell-like: state mutations belong to the stage,
                     # never to the parent command context or a sibling stage.
-                    stage_ctx = _sub_ctx(ctx, ctx.state.copy(), sin, sout, stderr_base)
+                    stage_ctx = _sub_ctx(ctx, ctx.state.copy(), sin, sout, stderr_base, loop_depth=0)
                     results[idx] = _dispatch_element(elements[idx], stage_ctx, sin, sout, stderr_base, is_pipeline=True)
                 except UnsupportedConstruct as exc:
                     # A structured refusal from an inline stage means the WHOLE command
@@ -356,6 +359,10 @@ def _run_pipeline_elements(elements: list, ctx: ExecContext) -> int:
                     results[idx] = 1
                 except ShellExit as exc:
                     results[idx] = exc.exit_code
+                except LoopControl:
+                    # A pipeline stage is a subshell boundary. Loop control in that
+                    # stage cannot alter an enclosing loop in the parent context.
+                    results[idx] = 0
                 except BaseException as exc:  # noqa: BLE001 - any other stage failure must not crash the engine
                     # Any OTHER exception is a real per-stage failure, not a refusal: it
                     # gets a named, actionable one-line message on the merged sink (never
@@ -487,6 +494,8 @@ def _dispatch_element(
         return _execute_subshell(element, ctx, stdin_stream, stdout_stream, stderr_stream)
     if isinstance(element, nodes.BraceGroup):
         return _execute_brace_group(element, ctx, stdin_stream, stdout_stream, stderr_stream)
+    if isinstance(element, (nodes.ForCommand, nodes.ArithmeticForCommand)):
+        return _execute_for_command(element, ctx, stdin_stream, stdout_stream, stderr_stream)
     if isinstance(element, nodes.SimpleCommand):
         return _dispatch_simple_command(element, ctx, stdin_stream, stdout_stream, stderr_stream)
     raise UnsupportedConstruct("malformed-syntax", f"unrecognized pipeline element {type(element)!r}")
@@ -498,6 +507,8 @@ def _sub_ctx(
     stdin_stream: BinaryIO | int,
     stdout_stream: BinaryIO | int,
     stderr_stream: BinaryIO | int,
+    *,
+    loop_depth: int | None = None,
 ) -> ExecContext:
     return ExecContext(
         state=state,
@@ -508,11 +519,12 @@ def _sub_ctx(
         builtins=ctx.builtins,
         deadline=ctx.deadline,
         stderr=stderr_stream,
+        loop_depth=ctx.loop_depth if loop_depth is None else loop_depth,
     )
 
 
-def _execute_redirected_group(
-    node: nodes.Subshell | nodes.BraceGroup,
+def _execute_redirected_compound(
+    node: nodes.Subshell | nodes.BraceGroup | nodes.ForCommand | nodes.ArithmeticForCommand,
     ctx: ExecContext,
     stdin_stream,
     stdout_stream,
@@ -526,8 +538,18 @@ def _execute_redirected_group(
             node.redirects, ctx, stdin_stream, stdout_stream, stderr_stream, tracker
         )
         state = ctx.state.copy() if isolated else ctx.state
-        inner_ctx = _sub_ctx(ctx, state, r_in, r_out, r_err)
+        inner_ctx = _sub_ctx(
+            ctx,
+            state,
+            r_in,
+            r_out,
+            r_err,
+            loop_depth=0 if isolated else ctx.loop_depth,
+        )
         try:
+            if isinstance(node, (nodes.ForCommand, nodes.ArithmeticForCommand)):
+                inner_ctx.loop_depth += 1
+                return _execute_loop(node, inner_ctx)
             return execute(node.body, inner_ctx)
         except ShellExit as exc:
             if isolated:
@@ -538,17 +560,89 @@ def _execute_redirected_group(
 
 
 def _execute_subshell(node: nodes.Subshell, ctx: ExecContext, stdin_stream, stdout_stream, stderr_stream) -> int:
-    return _execute_redirected_group(
+    return _execute_redirected_compound(
         node, ctx, stdin_stream, stdout_stream, stderr_stream, isolated=True
     )
 
 
 def _execute_brace_group(node: nodes.BraceGroup, ctx: ExecContext, stdin_stream, stdout_stream, stderr_stream) -> int:
-    return _execute_redirected_group(
+    return _execute_redirected_compound(
+        node, ctx, stdin_stream, stdout_stream, stderr_stream, isolated=False
+    )
+
+
+def _execute_for_command(
+    node: nodes.ForCommand | nodes.ArithmeticForCommand,
+    ctx: ExecContext,
+    stdin_stream,
+    stdout_stream,
+    stderr_stream,
+) -> int:
+    return _execute_redirected_compound(
         node, ctx, stdin_stream, stdout_stream, stderr_stream, isolated=False
     )
 
 
+def _check_loop_budget(ctx: ExecContext, iteration: int) -> None:
+    if ctx.deadline is not None and time.monotonic() >= ctx.deadline:
+        raise ShellExit(124)
+    if iteration >= MAX_LOOP_ITERATIONS:
+        _write_merged(
+            _merged_sink(ctx),
+            f"for: iteration limit ({MAX_LOOP_ITERATIONS}) exceeded\n".encode("utf-8"),
+            ctx,
+        )
+        raise ShellExit(124)
+
+
+def _execute_loop_body(body: nodes.CommandList, ctx: ExecContext) -> tuple[int, str | None]:
+    try:
+        return execute(body, ctx), None
+    except LoopBreak as exc:
+        if exc.levels > 1:
+            raise LoopBreak(exc.levels - 1) from None
+        return 0, "break"
+    except LoopContinue as exc:
+        if exc.levels > 1:
+            raise LoopContinue(exc.levels - 1) from None
+        return 0, "continue"
+
+
+def _execute_loop(node: nodes.ForCommand | nodes.ArithmeticForCommand, ctx: ExecContext) -> int:
+    if isinstance(node, nodes.ForCommand):
+        values: list[str] = []
+        for item in node.items:
+            values.extend(ctx.expand_word(item, ctx))
+
+        exit_code = 0
+        for iteration, value in enumerate(values):
+            _check_loop_budget(ctx, iteration)
+            ctx.state.setenv(node.name, value)
+            exit_code, action = _execute_loop_body(node.body, ctx)
+            if action == "break":
+                return exit_code
+        return exit_code
+
+    try:
+        initializer = compile_arithmetic(node.initializer)
+        condition = compile_arithmetic(node.condition)
+        update = compile_arithmetic(node.update)
+        evaluate_arithmetic(initializer, ctx.state)
+        exit_code = 0
+        iteration = 0
+        while condition is None or evaluate_arithmetic(condition, ctx.state) != 0:
+            _check_loop_budget(ctx, iteration)
+            iteration += 1
+            exit_code, action = _execute_loop_body(node.body, ctx)
+            if action == "break":
+                return exit_code
+            evaluate_arithmetic(update, ctx.state)
+        return exit_code
+    except ArithmeticError as exc:
+        _write_merged(_merged_sink(ctx), f"bash: arithmetic: {exc}\n".encode("utf-8"), ctx)
+        return 1
+
+
 def _dispatch_simple_command(
     command: nodes.SimpleCommand,
     ctx: ExecContext,
@@ -577,7 +671,7 @@ def _dispatch_simple_command(
         name = argv[0]
 
         if name in STATE_BUILTINS:
-            return _run_state_builtin(name, argv, ctx, r_out)
+            return _run_state_builtin(name, argv, ctx, r_out, r_err)
 
         if name in RUNNER_BUILTINS:
             return _run_xargs(argv, ctx, r_in, r_out)
@@ -621,17 +715,46 @@ def _as_stream(fd_or_stream: BinaryIO | int, mode: str) -> BinaryIO:
     return fd_or_stream
 
 
-def _run_state_builtin(name: str, argv: list[str], ctx: ExecContext, out_stream: BinaryIO | int) -> int:
+def _run_state_builtin(
+    name: str,
+    argv: list[str],
+    ctx: ExecContext,
+    out_stream: BinaryIO | int,
+    error_stream: BinaryIO | int | None = None,
+) -> int:
+    diagnostic_stream = error_stream if error_stream is not None else out_stream
+    if name in ("break", "continue"):
+        if len(argv) > 2:
+            _write_merged(diagnostic_stream, f"{name}: too many arguments\n".encode("utf-8"), ctx)
+            return 1
+        try:
+            levels = int(argv[1], 10) if len(argv) == 2 else 1
+        except ValueError:
+            _write_merged(diagnostic_stream, f"{name}: {argv[1]}: numeric argument required\n".encode("utf-8"), ctx)
+            return 1
+        if levels <= 0:
+            _write_merged(diagnostic_stream, f"{name}: loop count must be positive\n".encode("utf-8"), ctx)
+            return 1
+        if ctx.loop_depth == 0:
+            _write_merged(
+                diagnostic_stream,
+                f"bash: {name}: only meaningful in a 'for', 'while', or 'until' loop\n".encode("utf-8"),
+                ctx,
+            )
+            return 0
+        control = LoopBreak if name == "break" else LoopContinue
+        raise control(min(levels, ctx.loop_depth))
+
     if name == "exit":
         if len(argv) > 2:
-            _write_merged(out_stream, b"exit: too many arguments\n", ctx)
+            _write_merged(diagnostic_stream, b"exit: too many arguments\n", ctx)
             raise ShellExit(1)
         if len(argv) == 1:
             raise ShellExit(ctx.state.last_exit_code)
         try:
             exit_code = int(argv[1], 10)
         except ValueError:
-            _write_merged(out_stream, f"exit: {argv[1]}: numeric argument required\n".encode("utf-8"), ctx)
+            _write_merged(diagnostic_stream, f"exit: {argv[1]}: numeric argument required\n".encode("utf-8"), ctx)
             raise ShellExit(2)
         raise ShellExit(exit_code & 0xFF)
 
@@ -641,16 +764,16 @@ def _run_state_builtin(name: str, argv: list[str], ctx: ExecContext, out_stream:
         if print_new_cwd:
             oldpwd = ctx.state.env.get("OLDPWD")
             if not oldpwd:
-                _write_merged(out_stream, b"cd: OLDPWD not set\n", ctx)
+                _write_merged(diagnostic_stream, b"cd: OLDPWD not set\n", ctx)
                 return 1
             target = oldpwd
         if target is None:
-            _write_merged(out_stream, b"cd: HOME not set\n", ctx)
+            _write_merged(diagnostic_stream, b"cd: HOME not set\n", ctx)
             return 1
         try:
             ctx.state.chdir(target)
         except FileNotFoundError:
-            _write_merged(out_stream, f"cd: {target}: No such file or directory\n".encode("utf-8"), ctx)
+            _write_merged(diagnostic_stream, f"cd: {target}: No such file or directory\n".encode("utf-8"), ctx)
             return 1
         if print_new_cwd:
             _write_merged(out_stream, f"{ctx.state.cwd}\n".encode("utf-8"), ctx)