@danmoisan/drm-copilot-mcp 1.1.16 → 1.1.18

package/resources/claude-customizations/.claude/hooks/enforce-python-batch-budget.ps1

@@ -1,17 +1,35 @@
 <#
 .SYNOPSIS
-    Pre-tool-use hook that enforces the Python per-batch change budget.
+    Pre-tool-use hook that routes Python changes of more than three production files to the orchestrated large path.
 
 .DESCRIPTION
     This script is invoked by the Claude Code PreToolUse hook before any Write or Edit
-    operation. When the target file is a Python file, it classifies the file as either
-    production or test and checks the running count against the per-batch cap:
-      - 3 production .py files per batch
-      - 3 test .py files per batch
+    operation. When the target file is a Python file (.py), it decides whether the
+    change may proceed in direct mode.
+
+    Direct mode counts distinct production Python paths per Claude Code session. The
+    running set is persisted under .claude/state/python-batch-budget.<session_id>.json,
+    and repeated edits to the same file are counted once. The 4th distinct production
+    path is denied with a PYTHON_LARGE_PATH_REQUIRED reason that instructs the caller
+    to route the change through /orchestrate.
+
+    The orchestrated large path is detected from
+    <root>/artifacts/orchestration/orchestrator-state.json. The selected route is the
+    route_id value when that key is present, otherwise the path_selected value, and it
+    is usable only as a non-blank string. When the selected route is large,
+    remediation, or preparation and the checkpoint is not terminal (next_step is not
+    complete and completed_steps does not contain S12_complete), no path is denied for
+    count and no state is read or written. Every other checkpoint outcome, including
+    an absent, unreadable, or malformed checkpoint, enforces direct mode.
+
+    Test files are never counted. They are those matching:
+      - tests/**/*.py
+      - test_*.py
 
-    A "batch" is scoped to the current Claude Code session. The running count is
-    persisted under .claude/state/python-batch-budget.<session_id>.json. Only distinct
-    file paths are counted; repeated edits to the same file consume one slot.
+    All other .py files are production files. Non-Python paths pass through. The
+    threshold of three production files is a routing constant and is not configurable
+    at runtime. Legacy prodCap, testCap, and testFiles keys in a persisted state file
+    are ignored when the state is loaded.
 
     The session id is resolved from the first non-empty of: the CLAUDE_SESSION_ID
     environment variable; the contents of <root>/.claude/state/current-session-id;
@@ -26,20 +44,13 @@
     dropped when state is rehydrated, so a state file carried between worktrees
     cannot spend this worktree's budget.
 
-    Test files are those matching:
-      - tests/**/*.py
-      - test_*.py
-
-    All other .py files are treated as production files. Non-Python paths pass through.
-
-    The cap may be overridden per session by setting the environment variable
-    CLAUDE_PYTHON_BUDGET_PROD or CLAUDE_PYTHON_BUDGET_TEST to a positive integer before
-    the session starts, or by writing {"prodCap": N, "testCap": M} into the state file.
+    When a production path is denied, the script emits a PreToolUse JSON response with
+    hookSpecificOutput.permissionDecision = 'deny' and exits 0. Files already counted
+    are always allowed through.
 
-    When the cap would be exceeded by a new file, the script emits a PreToolUse JSON
-    response with hookSpecificOutput.permissionDecision = 'deny' and exits 0. The session
-    must explicitly reset the counter by deleting the state file before starting a new
-    batch. Files already counted are always allowed through.
+    Known limitation: a stale non-terminal large-path checkpoint left at the root
+    exempts a later direct-mode session at that root. Orchestrator checkpoint hygiene
+    (issue #673) moves foreign checkpoints aside before a new run.
 
 .NOTES
     Compatible with PowerShell 7+.
@@ -49,6 +60,7 @@ param()
 
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+. (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1')
 
 function Test-PythonBatchBudgetPathInRoot {
     <#
@@ -171,25 +183,24 @@ function Get-PythonBatchBudgetSessionId {
 }
 
 function Get-PythonBatchBudgetState {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', 'TestCap', Justification = 'Accepted and ignored for callers written against the removed test-file cap.')]
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
         [Parameter(Mandatory)]
         [int] $ProdCap,
 
-        [Parameter(Mandatory)]
-        [int] $TestCap
+        [int] $TestCap = 0
     )
 
     [ordered]@{
         prodCap   = $ProdCap
-        testCap   = $TestCap
         prodFiles = @()
-        testFiles = @()
     }
 }
 
 function ConvertTo-PythonBatchBudgetState {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', 'TestCap', Justification = 'Accepted and ignored for callers written against the removed test-file cap.')]
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
@@ -199,17 +210,16 @@ function ConvertTo-PythonBatchBudgetState {
         [Parameter(Mandatory)]
         [int] $ProdCap,
 
-        [Parameter(Mandatory)]
-        [int] $TestCap,
+        [int] $TestCap = 0,
 
         [AllowNull()]
         [AllowEmptyString()]
         [string] $Root = (Split-Path (Split-Path $PSScriptRoot -Parent) -Parent)
     )
 
-    $state = Get-PythonBatchBudgetState -ProdCap $ProdCap -TestCap $TestCap
-    if ($null -ne $InputObject.prodCap) { $state.prodCap = [int]$InputObject.prodCap }
-    if ($null -ne $InputObject.testCap) { $state.testCap = [int]$InputObject.testCap }
+    # Only prodFiles is carried over. Persisted prodCap, testCap, and testFiles keys
+    # come from the removed test-file cap and runtime overrides and are ignored.
+    $state = Get-PythonBatchBudgetState -ProdCap $ProdCap
 
     # Persisted entries that resolve outside this root belong to another worktree
     # and are dropped, so a state file carried across worktrees cannot spend this
@@ -217,9 +227,6 @@ function ConvertTo-PythonBatchBudgetState {
     if ($null -ne $InputObject.prodFiles) {
         $state.prodFiles = @(@($InputObject.prodFiles) | Where-Object { Test-PythonBatchBudgetPathInRoot -Path $_ -Root $Root })
     }
-    if ($null -ne $InputObject.testFiles) {
-        $state.testFiles = @(@($InputObject.testFiles) | Where-Object { Test-PythonBatchBudgetPathInRoot -Path $_ -Root $Root })
-    }
 
     return $state
 }
@@ -249,6 +256,7 @@ function Get-PythonBatchBudgetBlockDecision {
 }
 
 function Invoke-PythonBatchBudgetDecision {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', 'TestCap', Justification = 'Accepted and ignored for callers written against the removed test-file cap.')]
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
@@ -258,12 +266,19 @@ function Invoke-PythonBatchBudgetDecision {
         [Parameter(Mandatory)]
         [System.Collections.IDictionary] $State,
 
-        [Parameter(Mandatory)]
-        [string] $StateFile,
+        [AllowEmptyString()]
+        [string] $StateFile = '',
+
+        [int] $TestCap = 0,
 
         [AllowNull()]
         [AllowEmptyString()]
-        [string] $Root = (Split-Path (Split-Path $PSScriptRoot -Parent) -Parent)
+        [string] $Root = (Split-Path (Split-Path $PSScriptRoot -Parent) -Parent),
+
+        [switch] $LargePathRoute,
+
+        [AllowEmptyString()]
+        [string] $ObservedRoute = ''
     )
 
     $normalized = $FilePath -replace '\\', '/'
@@ -278,27 +293,32 @@ function Invoke-PythonBatchBudgetDecision {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' }; state = $State; shouldWriteState = $false }
     }
 
+    # The orchestrated large path has no production-file cap, so nothing is counted.
+    if ($LargePathRoute) {
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' }; state = $State; shouldWriteState = $false }
+    }
+
+    # Test files never count toward the routing threshold.
     $isTestFile = ($normalized -match '(^|/)tests/.*\.py$') -or ($normalized -match '(^|/)test_[^/]+\.py$')
-    $targetList = if ($isTestFile) { @($State.testFiles) } else { @($State.prodFiles) }
-    $cap = if ($isTestFile) { [int]$State.testCap } else { [int]$State.prodCap }
-    $kind = if ($isTestFile) { 'test' } else { 'production' }
+    if ($isTestFile) {
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' }; state = $State; shouldWriteState = $false }
+    }
 
-    if ($targetList -contains $normalized) {
+    $countedFiles = @($State.prodFiles)
+    if ($countedFiles -contains $normalized) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' }; state = $State; shouldWriteState = $false }
     }
 
-    if ($targetList.Count -ge $cap) {
-        $currentFiles = ($targetList -join ', ')
-        $kindUpper = $kind.ToUpperInvariant()
-        $reason = "Python per-batch budget exceeded: $kind file cap is $cap and is already full ($currentFiles). Requested new file: $normalized. Split the work into a new batch, raise the cap via CLAUDE_PYTHON_BUDGET_$kindUpper environment variable with approved scope, or reset the batch by deleting $StateFile."
+    $cap = [int]$State.prodCap
+    if ($countedFiles.Count -ge $cap) {
+        Write-Verbose "Denying production Python path '$normalized' in direct mode; counted paths are recorded in '$StateFile'."
+        $counted = $countedFiles -join ', '
+        $route = if ([string]::IsNullOrWhiteSpace($ObservedRoute)) { 'none' } else { $ObservedRoute }
+        $reason = "PYTHON_LARGE_PATH_REQUIRED: this change touches more than $cap production Python files (already counted: $counted; requested: $normalized). A change of this size belongs on the orchestrated large path, which has no production-file cap. Route the change through /orchestrate. Checkpoint route observed: $route."
         return Get-PythonBatchBudgetBlockDecision -Reason $reason -State $State
     }
 
-    if ($isTestFile) {
-        $State.testFiles = @($State.testFiles) + @($normalized)
-    } else {
-        $State.prodFiles = @($State.prodFiles) + @($normalized)
-    }
+    $State.prodFiles = $countedFiles + @($normalized)
 
     return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' }; state = $State; shouldWriteState = $true }
 }
@@ -311,7 +331,6 @@ function Invoke-PythonBatchBudgetHook {
         [string] $SessionId = '',
         [string] $Root = (Split-Path (Split-Path $PSScriptRoot -Parent) -Parent),
         [int] $ProdCap = 3,
-        [int] $TestCap = 3,
         [scriptblock] $ReadSessionIdFile = {
             param([string] $Path)
             if (Test-Path -LiteralPath $Path -PathType Leaf) {
@@ -319,6 +338,13 @@ function Invoke-PythonBatchBudgetHook {
             }
             return ''
         },
+        [scriptblock] $ReadCheckpoint = {
+            param([string] $Path)
+            if (Test-Path -LiteralPath $Path -PathType Leaf) {
+                return (Get-Content -LiteralPath $Path -Raw)
+            }
+            return ''
+        },
         [scriptblock] $TestPathExists = { param([string] $Path) Test-Path -Path $Path },
         [scriptblock] $EnsureDirectory = { param([string] $Path) New-Item -ItemType Directory -Path $Path -Force | Out-Null },
         [scriptblock] $ReadState = { param([string] $Path) Get-Content -Path $Path -Raw },
@@ -356,23 +382,41 @@ function Invoke-PythonBatchBudgetHook {
         -SessionIdFilePath (Join-Path -Path $stateDir -ChildPath 'current-session-id') `
         -ReadSessionIdFile $ReadSessionIdFile
 
+    $stateFile = Join-Path -Path $stateDir -ChildPath ("python-batch-budget.$resolvedSessionId.json")
+
+    # The checkpoint is read before any state operation, so the large path neither
+    # creates the state directory nor reads or writes the state file.
+    $checkpointPath = Join-Path -Path $Root -ChildPath 'artifacts/orchestration/orchestrator-state.json'
+    $checkpointText = ''
+    try {
+        $checkpointText = [string](& $ReadCheckpoint $checkpointPath)
+    } catch {
+        Write-Verbose "Treating unreadable orchestrator checkpoint '$checkpointPath' as direct mode: $($_.Exception.Message)"
+        $checkpointText = ''
+    }
+
+    $isLargePath = Test-BatchBudgetLargePathRoute -CheckpointText $checkpointText
+    $observedRoute = Get-BatchBudgetSelectedRoute -CheckpointText $checkpointText
+    if ($isLargePath) {
+        return Invoke-PythonBatchBudgetDecision -FilePath $filePath -State (Get-PythonBatchBudgetState -ProdCap $ProdCap) -StateFile $stateFile -Root $Root -LargePathRoute
+    }
+
     if (-not (& $TestPathExists $stateDir)) {
         & $EnsureDirectory $stateDir
     }
 
-    $stateFile = Join-Path -Path $stateDir -ChildPath ("python-batch-budget.$resolvedSessionId.json")
-    $state = Get-PythonBatchBudgetState -ProdCap $ProdCap -TestCap $TestCap
+    $state = Get-PythonBatchBudgetState -ProdCap $ProdCap
 
     if (& $TestPathExists $stateFile) {
         try {
             $loaded = & $ReadState $stateFile | ConvertFrom-Json -ErrorAction Stop
-            $state = ConvertTo-PythonBatchBudgetState -InputObject $loaded -ProdCap $ProdCap -TestCap $TestCap -Root $Root
+            $state = ConvertTo-PythonBatchBudgetState -InputObject $loaded -ProdCap $ProdCap -Root $Root
         } catch {
             Write-Verbose "Ignoring unreadable Python batch-budget state file '$stateFile': $($_.Exception.Message)"
         }
     }
 
-    $decision = Invoke-PythonBatchBudgetDecision -FilePath $filePath -State $state -StateFile $stateFile -Root $Root
+    $decision = Invoke-PythonBatchBudgetDecision -FilePath $filePath -State $state -StateFile $stateFile -Root $Root -ObservedRoute $observedRoute
     if ($decision.shouldWriteState) {
         try {
             & $WriteState $stateFile $decision.state
@@ -420,16 +464,7 @@ function Invoke-PythonBatchBudgetEntryPoint {
     # worktree-derived identifier.
     $sessionId = [string]$env:CLAUDE_SESSION_ID
 
-    $prodCap = 3
-    $testCap = 3
-    if ($env:CLAUDE_PYTHON_BUDGET_PROD -match '^\d+$') {
-        $prodCap = [int]$env:CLAUDE_PYTHON_BUDGET_PROD
-    }
-    if ($env:CLAUDE_PYTHON_BUDGET_TEST -match '^\d+$') {
-        $testCap = [int]$env:CLAUDE_PYTHON_BUDGET_TEST
-    }
-
-    $decision = Invoke-PythonBatchBudgetHook -ToolInputRaw $ToolInputRaw -SessionId $sessionId -ProdCap $prodCap -TestCap $testCap
+    $decision = Invoke-PythonBatchBudgetHook -ToolInputRaw $ToolInputRaw -SessionId $sessionId
     if ($decision.hookSpecificOutput.permissionDecision -eq 'deny') {
         $decision.Remove('state')
         $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output

package/resources/claude-customizations/.claude/lib/bash/abandon-parallel-item.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# abandon-parallel-item.sh: bundled destination-runtime port of
+# scripts/dev_tools/parallel_mutation_abandon_cli.py (issue #763). It executes the
+# abandon disposition of /parallel-remove -- close the item's pull request, then
+# remove its worktree -- with nothing but bash, gh, and git on PATH: no Python, no
+# Poetry, no repository checkout.
+#
+# Usage:
+#   bash .claude/lib/bash/abandon-parallel-item.sh --item <key> --disposition abandon --confirm-abandon --pr <pr-number> --worktree <worktree-path>
+#
+# The PreToolUse hook .claude/hooks/enforce-parallel-abandon-gate.ps1 matches the
+# command text of that invocation: a command carrying the disposition token
+# without the confirmation marker is denied before it runs. The option tokens are
+# declared once each below, and tests/scripts/dev_tools/test_parallel_abandon_token_seam.py
+# binds them to the Python reference and to the hook.
+#
+# Exit codes:
+#   0  success; both side effects ran and nothing was written to stdout
+#   1  a side effect failed; the first failure is reported and nothing after it runs
+#   2  refusal (a disposition other than abandon, or no confirmation marker) or a
+#      usage error; both are reported before any side effect
+#
+# Declared divergences from the Python reference, all within "usage errors exit 2":
+#   - argparse usage text is not reproduced; only exit code 2 is matched, with one
+#     stderr line prefixed "PARALLEL_ABANDON_ERROR: usage error:".
+#   - option abbreviations are rejected (argparse accepts a unique prefix).
+#   - --item and --pr accept only canonical decimal integers (0 or [1-9][0-9]*).
+#   - -h and --help are unknown options.
+#   - an option value beginning with -- is treated as a missing value.
+# Repeated options keep the last value and the joined --name=value form is
+# accepted, as argparse does.
+set -euo pipefail
+
+# The option tokens and messages the abandon surface is built from. The first
+# three lines are read by the seam test and by tests/shell/parallel_abandon.bats.
+readonly ABANDON_DISPOSITION_OPTION='--disposition'
+readonly ABANDON_DISPOSITION_VALUE='abandon'
+readonly ABANDON_CONFIRM_OPTION='--confirm-abandon'
+readonly ABANDON_ITEM_OPTION='--item'
+readonly ABANDON_PR_OPTION='--pr'
+readonly ABANDON_WORKTREE_OPTION='--worktree'
+readonly ABANDON_VALID_DISPOSITIONS='detach abandon'
+readonly ABANDON_ERROR_PREFIX='PARALLEL_ABANDON_ERROR:'
+
+abandon_usage_error() {
+	# Report a usage error on stderr and exit 2 before any side effect.
+	#
+	# Args: $1 = the detail naming the offending argument.
+	printf '%s usage error: %s\n' "$ABANDON_ERROR_PREFIX" "$1" >&2
+	exit 2
+}
+
+abandon_require_integer() {
+	# Require a canonical decimal integer, as the reference's type=int requires
+	# an integer; leading zeros, signs, and blanks are usage errors here.
+	#
+	# Args: $1 = the value, $2 = the option it was given for.
+	if [[ ! $1 =~ ^(0|[1-9][0-9]*)$ ]]; then
+		abandon_usage_error "$2 requires a canonical decimal integer; got '$1'"
+	fi
+}
+
+abandon_require_disposition() {
+	# Require a member of the disposition vocabulary, as the reference's
+	# argparse choices do. Membership is not the abandon refusal: a valid
+	# disposition other than abandon is refused later with its own message.
+	#
+	# Args: $1 = the disposition value.
+	local candidate
+	# Scan the space-separated vocabulary for an exact match.
+	for candidate in $ABANDON_VALID_DISPOSITIONS; do
+		if [ "$candidate" = "$1" ]; then
+			return 0
+		fi
+	done
+	abandon_usage_error "$ABANDON_DISPOSITION_OPTION must be one of: $ABANDON_VALID_DISPOSITIONS; got '$1'"
+}
+
+abandon_side_effect_failed() {
+	# Report a failed side effect and exit 1, so nothing after it runs.
+	#
+	# Args: $1 = the exit code (-1 when the executable is not on PATH), then the
+	# command vector, which is rendered joined by single spaces.
+	local code="$1"
+	shift
+	printf '%s abandon side effect failed with exit code %s: %s\n' "$ABANDON_ERROR_PREFIX" "$code" "$*" >&2
+	exit 1
+}
+
+abandon_run_side_effect() {
+	# Run one side-effect command resolved through PATH. A non-zero exit is
+	# captured rather than aborting under set -e, so it can be reported.
+	#
+	# Args: the command vector, executable name first.
+	local executable status=0
+	if ! executable="$(command -v -- "$1")"; then
+		abandon_side_effect_failed -1 "$@"
+	fi
+	"$executable" "${@:2}" || status=$?
+	if [ "$status" -ne 0 ]; then
+		abandon_side_effect_failed "$status" "$@"
+	fi
+}
+
+item=''
+disposition=''
+pr=''
+worktree=''
+confirmed=0
+have_item=0
+have_disposition=0
+have_pr=0
+have_worktree=0
+
+# Parse the argument vector. The bare confirmation flag sets the marker; each of
+# the four valued options takes its value joined (--name=value) or as the next
+# argument; anything else -- an unknown option, an abbreviation, a value on the
+# confirmation flag, or a positional argument -- is a usage error.
+while [ "$#" -gt 0 ]; do
+	argument="$1"
+	shift
+	if [ "$argument" = "$ABANDON_CONFIRM_OPTION" ]; then
+		confirmed=1
+		continue
+	fi
+	name="${argument%%=*}"
+	case "$name" in
+	"$ABANDON_ITEM_OPTION" | "$ABANDON_DISPOSITION_OPTION" | "$ABANDON_PR_OPTION" | "$ABANDON_WORKTREE_OPTION") ;;
+	*) abandon_usage_error "unrecognized argument: $argument" ;;
+	esac
+	# Take the joined value when present, otherwise the next argument; an absent
+	# value is represented by the option prefix so one check rejects both forms.
+	if [ "$name" != "$argument" ]; then
+		value="${argument#*=}"
+	elif [ "$#" -gt 0 ]; then
+		value="$1"
+		shift
+	else
+		value='--'
+	fi
+	if [[ $value == --* ]]; then
+		abandon_usage_error "$name requires a value"
+	fi
+	# Store the value on its option; a repeated option keeps the last value.
+	case "$name" in
+	"$ABANDON_ITEM_OPTION") item="$value" have_item=1 ;;
+	"$ABANDON_DISPOSITION_OPTION") disposition="$value" have_disposition=1 ;;
+	"$ABANDON_PR_OPTION") pr="$value" have_pr=1 ;;
+	*) worktree="$value" have_worktree=1 ;;
+	esac
+done
+
+# Every valued option is required, as in the reference parser.
+if [ "$have_item" -eq 0 ] || [ "$have_disposition" -eq 0 ] || [ "$have_pr" -eq 0 ] || [ "$have_worktree" -eq 0 ]; then
+	abandon_usage_error "the options $ABANDON_ITEM_OPTION, $ABANDON_DISPOSITION_OPTION, $ABANDON_PR_OPTION, and $ABANDON_WORKTREE_OPTION are required"
+fi
+abandon_require_integer "$item" "$ABANDON_ITEM_OPTION"
+abandon_require_integer "$pr" "$ABANDON_PR_OPTION"
+abandon_require_disposition "$disposition"
+
+# The two refusals come before any side effect: this entry point exists only to
+# execute the confirmed abandon path, so any other request does nothing.
+if [ "$disposition" != "$ABANDON_DISPOSITION_VALUE" ]; then
+	printf "%s this CLI executes the '%s' disposition only; got '%s'.\n" "$ABANDON_ERROR_PREFIX" "$ABANDON_DISPOSITION_VALUE" "$disposition" >&2
+	exit 2
+fi
+if [ "$confirmed" -ne 1 ]; then
+	printf '%s refusing to abandon item %s without the explicit %s confirmation marker; no side effect was performed.\n' "$ABANDON_ERROR_PREFIX" "$item" "$ABANDON_CONFIRM_OPTION" >&2
+	exit 2
+fi
+
+# Close the pull request before removing the worktree: removing the worktree
+# first would leave an open pull request whose checkout is gone.
+abandon_run_side_effect gh pr close "$pr"
+abandon_run_side_effect git worktree remove "$worktree"
+exit 0

package/resources/claude-customizations/.claude/lib/bash/parallel-lane-assertion.sh

@@ -82,8 +82,10 @@ pla_parse_edges() {
 	PLA_EDGES=()
 	local -a tokens=()
 	# read -ra rather than an unquoted expansion, so a token carrying a glob
-	# character is never subjected to pathname expansion.
-	read -ra tokens <<<"$text"
+	# character is never subjected to pathname expansion. Newline, CR, VT, and FF
+	# become spaces first: read consumes one newline-terminated record and splits
+	# it on IFS only, so the Python str.split() whitespace set would otherwise differ.
+	read -ra tokens <<<"${text//[$'\n\r\v\f']/ }"
 	for token in "${tokens[@]}"; do
 		# Partition on the FIRST colon, matching str.partition: a token with two
 		# colons yields a second endpoint that still carries one, which the lexis